chore(deps): bump actions/checkout in the actions group

Bumps the actions group with 1 update: [actions/checkout](https://github.com/actions/checkout). Updates `actions/checkout` from 6.0.3 to 7.0.0 - [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/df4cb1c069e1874edd31b4311f1884172cec0e10...9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions ... Signed-off-by: dependabot[bot] <support@github.com>
feat(security): verify binaries with pinned Ed25519 signature on SHA256SUMS
2026-06-23 11:41:46 +02:00 · 2026-06-21 20:12:34 +00:00 · 2026-06-21 02:42:18 +02:00 · 2026-06-20 22:53:53 +02:00 · 2026-06-20 21:50:22 +02:00 · 2026-06-20 03:17:07 +02:00
53 changed files with 3767 additions and 1066 deletions
@@ -0,0 +1,5 @@
+# Never let signing material enter a Docker build context / image.
+# The test image (test-infra/Dockerfile.test) uses selective COPY today, but
+# this is defense-in-depth against a future `COPY . .`.
+test-infra/signing/
+*.pem
@@ -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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: 24  # npm 11.11.0 native — no upgrade needed (Node 22.22.2 has broken npm)
@@ -100,20 +100,20 @@ jobs:
      attestations: write
      packages: write
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      - 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
@@ -73,3 +73,4 @@ captures
 .dolt/
 *.db
 .beads-credential-key
+.antigravitycli
@@ -8,6 +8,37 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi

 ## [Unreleased]

+- **[wrapper]** **Security**: downloaded binaries are now verified against a pinned Ed25519 signature on the published `SHA256SUMS` (a detached `SHA256SUMS.sig`), so a compromised download mirror can no longer certify a tampered binary — the previous same-origin checksum proved integrity but not authenticity (#308). The signed manifest also binds the release version, rejecting a forced downgrade to an older signed build. Verification is mandatory on the official download path; silent auto-update is preserved for everyone because only a constant public key is pinned, not per-version hashes. Older installed wrappers are unaffected.
+- **[wrapper]** Headed launches no longer apply a fixed emulated viewport on top of the real browser window — the page now tracks the actual window so window-geometry stays self-consistent. Headless keeps a deterministic viewport (unchanged). Applies across `launch`, `launch_context`, `launch_persistent_context` (+ async) and the JS Playwright/Puppeteer wrappers. Passing an explicit `viewport=`/`no_viewport` (Python) or `viewport`/`defaultViewport` (JS) still works exactly as before.
+- **[wrapper]** **Breaking**: removed the optional `patchright` backend. The `backend` parameter and `CLOAKBROWSER_BACKEND` environment variable no longer exist, and the `cloakbrowser[patchright]` extra is gone. Stock Playwright is now the only backend. The stealth binary handles automation-signal suppression at the C++ level — patchright added no measurable benefit on top of it (identical reCAPTCHA v3 score to plain Playwright) while breaking proxy auth and `add_init_script` (#27). Callers passing `backend=...` will get a `TypeError`; remove the argument.
+
+## [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)
+- **[binary]** Rendering consistency improvements across Linux and Windows — corrected GPU, display, and graphics parameters to match stock Chrome 146 profiles
+- **[binary]** Windows: native GPU/rendering values now pass through directly instead of being spoofed, matching real hardware behavior
+- **[binary]** Storage normalization fix for Windows
+- **[binary]** HTTP proxy inline credential support at the network layer
+- **[wrapper]** Update `PLATFORM_CHROMIUM_VERSIONS` for linux-x64 and windows-x64 to 146.0.7680.177.5
+
 ## [0.3.29] — 2026-05-20

 - **[wrapper]** **Security**: `cloakserve` — guard WebSocket origins to prevent browser-origin CSRF via CDP proxy (thanks [@0xlally](https://github.com/0xlally) for the report, [@honor2030](https://github.com/honor2030) for the fix, #239, #240)
@@ -40,7 +40,7 @@ Drop-in Playwright/Puppeteer replacement for Python and JavaScript.<br>
 Same API, same code — just swap the import. <strong>3 lines of code, 30 seconds to unblock.</strong>
 </p>

- **49 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, WebRTC, network timing, automation signals, CDP input behavior
+- **58 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, WebRTC, network timing, automation signals, CDP input behavior
 - **`humanize=True`** — human-like mouse curves, keyboard timing, and scroll patterns. One flag, behavioral detection passes
 - **0.9 reCAPTCHA v3 score** — human-level, server-verified
 - **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — tested against 30+ detection sites
@@ -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,17 +150,19 @@ Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **L

 ---

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

- **`launch_context_async()`** — async counterpart to `launch_context()`. Forwards kwargs to `browser.new_context()` for `storage_state`, `permissions`, `extra_http_headers` without a persistent profile folder.
- **JS `contextOptions` escape hatch** — forward arbitrary options (including `storageState`) to Playwright's `newContext()` from `launchContext()` / `launchPersistentContext()`.
- **Native SOCKS5 proxy** — `proxy="socks5://user:pass@host:port"` works directly in all launch functions, Python + JS. QUIC/HTTP3 tunnels through SOCKS5 via UDP ASSOCIATE.
- **Chromium 146 upgrade** — rebased all patches from 145.0.7632.x to 146.0.7680.177
- **57 fingerprint patches** — additional detection-vector coverage (WebAuthn, AAC audio, window position) and WebGL/canvas consistency fixes
- **WebRTC IP spoofing** — `--fingerprint-webrtc-ip=auto` resolves your proxy's exit IP and spoofs WebRTC ICE candidates. Auto-injected when using `geoip=True` (no extra network call)
+- **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
+- **HTTP proxy inline credentials** — new network-layer support for proxies with inline authentication
+- **`extension_paths`** — load Chrome extensions in all launch functions
+- **Humanize actionability** — auto-wait for visible, enabled, stable elements before humanized actions
+- **Per-call `human_config`** — override humanize settings on individual method calls
+- **Composable JS helpers** — `buildLaunchOptions()` and `humanizeBrowser()` for custom Playwright integrations
+- **Native SOCKS5 proxy** — `proxy="socks5://user:pass@host:port"` works directly in all launch functions, Python + JS. QUIC/HTTP3 tunnels through SOCKS5 via UDP ASSOCIATE
 - **Proxy signal removal** — DNS/connect/SSL timing zeroed, proxy cache headers stripped, Proxy-Connection header leak removed
- **`cloakserve` CDP multiplexer** — rewritten as a multi-connection CDP proxy with per-connection fingerprint seeds
- **Humanize CDP isolation** — keyboard events now use isolated worlds and trusted dispatch for better behavioral stealth
+- **Chromium 146 upgrade** — rebased all patches from 145.0.7632.x to 146.0.7680.177
+- **WebRTC IP spoofing** — `--fingerprint-webrtc-ip=auto` resolves your proxy's exit IP and spoofs WebRTC ICE candidates. Auto-injected when using `geoip=True` (no extra network call)
 - **`humanize=True`** — one flag makes all mouse, keyboard, and scroll interactions behave like a real user. Bézier curves, per-character typing, realistic scroll patterns
 - **Stealthy with zero flags** — binary auto-generates a random fingerprint seed at startup. No configuration required
 - **Timezone & locale from proxy IP** — `launch(proxy="...", geoip=True)` auto-detects timezone and locale
@@ -226,11 +250,11 @@ CloakBrowser is a thin wrapper (Python + JavaScript) around a custom-built Chrom
 3. **Every launch** → Playwright or Puppeteer starts with our binary + stealth args
 4. **You write code** → standard Playwright/Puppeteer API, nothing new to learn

-The binary includes 49 source-level patches covering canvas, WebGL, audio, fonts, GPU, screen properties, WebRTC, network timing, hardware reporting, automation signal removal, and CDP input behavior mimicking.
+The binary includes 58 source-level patches covering canvas, WebGL, audio, fonts, GPU, screen properties, WebRTC, network timing, hardware reporting, automation signal removal, and CDP input behavior mimicking.

 These are compiled into the Chromium binary — not injected via JavaScript, not set via flags.

-Binary downloads are verified with SHA-256 checksums to ensure integrity.
+Binary downloads are verified against a pinned Ed25519 signature on the published checksums before extraction, so the download is confirmed authentic (genuinely ours) and not just intact. A compromised mirror cannot serve a tampered or downgraded binary.

 ## API

@@ -359,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
@@ -395,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:
@@ -413,7 +458,7 @@ from cloakbrowser import binary_info, clear_cache, ensure_binary

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

 # Force re-download
 clear_cache()
@@ -576,8 +621,10 @@ Access the original un-patched Playwright page at `page._original` if you need r
 | `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | Binary cache directory |
 | `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL for binary |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
-| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Set to `true` to skip SHA-256 verification after download |
+| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Only applies to a custom `CLOAKBROWSER_DOWNLOAD_URL`: set to `true` to skip its checksum check. Signature verification on the official download path is mandatory and cannot be skipped. |
 | `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

@@ -747,11 +794,11 @@ browser = await launch_async(args=["--remote-debugging-port=9242"])

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

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

@@ -815,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
@@ -825,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:
@@ -876,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:

@@ -984,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.
@@ -1120,7 +1240,6 @@ await new Promise(r => setTimeout(r, 3000));
 ```

 Other tips for maximizing reCAPTCHA scores:
- **Try the Patchright backend** — suppresses additional CDP automation signals at the Playwright protocol layer. Install with `pip install cloakbrowser[patchright]`, then use `launch(backend="patchright")` or set `CLOAKBROWSER_BACKEND=patchright` globally. Note: Patchright breaks proxy auth and `add_init_script` — only use it if you're still seeing low scores after trying the steps above
 - **Use Playwright, not Puppeteer** — Puppeteer sends more CDP protocol traffic that reCAPTCHA detects ([details](#puppeteer))
 - **Use residential proxies** — datacenter IPs are flagged by IP reputation, not browser fingerprint
 - **Spend 15+ seconds on the page** before triggering reCAPTCHA — short visits score lower
@@ -1150,9 +1269,9 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` or `proxy="socks5://user:pass@

 | Feature | Status |
 |---------|--------|
-| Linux x64 — Chromium 146 (57 patches) | ✅ Released |
+| Linux x64 — Chromium 146 (58 patches) | ✅ Released |
 | macOS arm64/x64 — Chromium 145 (26 patches) | ✅ Released |
-| Windows x64 — Chromium 146 (57 patches) | ✅ Released |
+| Windows x64 — Chromium 146 (58 patches) | ✅ Released |
 | JavaScript/Puppeteer + Playwright support | ✅ Released |
 | Fingerprint rotation per session | ✅ Released |
 | Built-in proxy rotation | 📋 Planned |
@@ -1169,12 +1288,12 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` or `proxy="socks5://user:pass@

 ## Security

-All releases are signed for supply chain verification.
+The wrapper automatically verifies every binary download against a pinned Ed25519 signature on the published checksums before extraction — a compromised mirror cannot serve a tampered or downgraded binary. Releases are additionally signed for manual supply chain verification:

 ```bash
 # Verify GPG signature (binary release tag)
 gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
-git verify-tag chromium-v146.0.7680.177.3
+git verify-tag chromium-v146.0.7680.177.5

 # Verify GitHub binary attestation (Sigstore)
 gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser
@@ -1200,7 +1319,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
@@ -1209,5 +1328,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.29"
+__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")

@@ -30,6 +31,79 @@ logger = logging.getLogger("cloakbrowser")
 _VIEWPORT_UNSET = object()


+def _default_no_viewport(browser: Any) -> None:
+    """Default ``new_page()``/``new_context()`` to ``no_viewport=True``.
+
+    ``launch()`` returns a raw Playwright ``Browser``; a bare ``browser.new_page()``
+    would otherwise inherit Playwright's emulated 1280x720 viewport, producing
+    ``outerWidth < innerWidth`` — a physically impossible window (bot tell). We wrap
+    the two factory methods so pages track the real OS window instead. ``setdefault``
+    only: an explicit ``viewport`` or ``no_viewport`` from the caller is never
+    overridden (Playwright rejects passing both). Applied for headed launches only.
+    Composes under humanize's ``patch_browser`` (apply this first).
+    """
+    orig_new_context = browser.new_context
+    orig_new_page = browser.new_page
+
+    def _patched_new_context(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return orig_new_context(**kwargs)
+
+    def _patched_new_page(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return orig_new_page(**kwargs)
+
+    browser.new_context = _patched_new_context
+    browser.new_page = _patched_new_page
+
+
+def _default_no_viewport_async(browser: Any) -> None:
+    """Async variant of :func:`_default_no_viewport`."""
+    orig_new_context = browser.new_context
+    orig_new_page = browser.new_page
+
+    async def _patched_new_context(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return await orig_new_context(**kwargs)
+
+    async def _patched_new_page(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return await orig_new_page(**kwargs)
+
+    browser.new_context = _patched_new_context
+    browser.new_page = _patched_new_page
+
+
+def _resolve_context_viewport(viewport: Any, headless: bool) -> dict[str, Any]:
+    """Return the viewport kwarg for a context.
+
+    Headed: no emulated viewport so the page tracks the real window (CDP viewport
+    emulation forces outerWidth < innerWidth = a physically impossible window =
+    bot tell). Headless: a fixed ``DEFAULT_VIEWPORT`` stays coherent (outer == inner)
+    and keeps dimensions deterministic. Explicit ``viewport`` / ``None`` honored.
+    """
+    if viewport is _VIEWPORT_UNSET:
+        return {"viewport": DEFAULT_VIEWPORT} if headless else {"no_viewport": True}
+    if viewport is None:
+        return {"no_viewport": True}
+    return {"viewport": viewport}
+
+
+def _drop_conflicting_viewport(context_kwargs: dict[str, Any], kwargs: dict[str, Any]) -> None:
+    """Playwright rejects passing both ``viewport`` and ``no_viewport``. ``viewport`` is a
+    named parameter (never in ``**kwargs``), so the only conflict is a caller passing
+    ``no_viewport`` via ``**kwargs`` alongside an explicit ``viewport`` — the explicit
+    ``no_viewport`` wins; drop the viewport so Playwright doesn't error.
+    """
+    if "no_viewport" in kwargs and "viewport" in context_kwargs:
+        logger.debug("Both viewport and no_viewport requested; no_viewport (kwargs) wins")
+        context_kwargs.pop("viewport", None)
+
+
 def _resolve_timezone(timezone: str | None, kwargs: dict[str, Any]) -> str | None:
    """Accept both timezone and timezone_id — either works, no warning."""
    if "timezone_id" in kwargs:
@@ -40,6 +114,15 @@ def _resolve_timezone(timezone: str | None, kwargs: dict[str, Any]) -> str | Non
    return timezone


+def _check_removed_kwargs(kwargs: dict[str, Any]) -> None:
+    """Raise a clear error for removed parameters that now fall into **kwargs."""
+    if "backend" in kwargs:
+        raise TypeError(
+            "The 'backend' parameter has been removed — patchright is no longer "
+            "supported and stock Playwright is the only backend. Remove the argument."
+        )
+
+
 class _ProxySettingsRequired(TypedDict):
    server: str

@@ -60,7 +143,6 @@ def launch(
    timezone: str | None = None,
    locale: str | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -85,10 +167,6 @@ def launch(
            Requires ``pip install cloakbrowser[geoip]``. Downloads ~70 MB
            GeoLite2-City database on first use.  Explicit timezone/locale
            always override geoip results.
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
-            Patchright suppresses CDP signals (helps reCAPTCHA v3 Enterprise)
-            but breaks proxy auth and add_init_script.
-            Override globally with CLOAKBROWSER_BACKEND env var.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -105,7 +183,9 @@ def launch(
        >>> print(page.title())
        >>> browser.close()
    """
-    sync_playwright = _import_sync_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.sync_api import sync_playwright

    binary_path = ensure_binary()
    timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
@@ -114,7 +194,7 @@ def launch(
    if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
        args = list(args or [])
        args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-        
+
    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)

    logger.debug("Launching stealth Chromium (headless=%s, args=%d)", headless, len(chrome_args))
@@ -140,6 +220,12 @@ def launch(

    browser.close = _close_with_cleanup

+    # Headed: default new_page()/new_context() to no_viewport so the page tracks the
+    # real window (avoids the impossible-window tell). Headless keeps Playwright's
+    # default viewport (coherent there). Apply before humanize so the wraps compose.
+    if not headless:
+        _default_no_viewport(browser)
+
    # Human-like behavioral patching
    if humanize:
        from .human import patch_browser
@@ -158,7 +244,6 @@ async def launch_async(  # noqa: C901
    timezone: str | None = None,
    locale: str | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -176,7 +261,6 @@ async def launch_async(  # noqa: C901
        timezone: IANA timezone (e.g. 'America/New_York'). Sets --fingerprint-timezone binary flag.
        locale: BCP 47 locale (e.g. 'en-US'). Sets --lang binary flag.
        geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -198,7 +282,9 @@ async def launch_async(  # noqa: C901
        >>>
        >>> asyncio.run(main())
    """
-    async_playwright = _import_async_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.async_api import async_playwright

    binary_path = ensure_binary()
    timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
@@ -232,6 +318,10 @@ async def launch_async(  # noqa: C901

    browser.close = _close_with_cleanup

+    # Headed: default new_page()/new_context() to no_viewport (see launch()).
+    if not headless:
+        _default_no_viewport_async(browser)
+
    # Human-like behavioral patching (async variant)
    if humanize:
        from .human import patch_browser_async
@@ -254,7 +344,6 @@ def launch_persistent_context(
    timezone: str | None = None,
    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -285,7 +374,6 @@ def launch_persistent_context(
            Default: None (uses Chromium default, which is 'light').
        geoip: Auto-detect timezone/locale from proxy IP (default False).
            Requires ``pip install cloakbrowser[geoip]``.
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -302,7 +390,9 @@ def launch_persistent_context(
        >>> page.goto("https://protected-site.com")
        >>> ctx.close()  # Profile is saved; re-use path next run to restore state.
    """
-    sync_playwright = _import_sync_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.sync_api import sync_playwright

    timezone = _resolve_timezone(timezone, kwargs)

@@ -326,15 +416,13 @@ def launch_persistent_context(
    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
+
+    seed_widevine_hint(user_data_dir, binary_path)

    pw = sync_playwright().start()
    context = pw.chromium.launch_persistent_context(
@@ -380,7 +468,6 @@ async def launch_persistent_context_async(
    timezone: str | None = None,
    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -408,7 +495,6 @@ async def launch_persistent_context_async(
        timezone: IANA timezone (e.g. 'America/New_York').
        color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
        geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -430,7 +516,9 @@ async def launch_persistent_context_async(
        >>>
        >>> asyncio.run(main())
    """
-    async_playwright = _import_async_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.async_api import async_playwright

    timezone = _resolve_timezone(timezone, kwargs)

@@ -454,15 +542,13 @@ async def launch_persistent_context_async(
    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
+
+    seed_widevine_hint(user_data_dir, binary_path)

    pw = await async_playwright().start()
    context = await pw.chromium.launch_persistent_context(
@@ -507,7 +593,6 @@ def launch_context(
    timezone: str | None = None,
    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -533,7 +618,6 @@ def launch_context(
        color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
            Default: None (uses Chromium default, which is 'light').
        geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -542,6 +626,8 @@ def launch_context(
    Returns:
        Playwright BrowserContext object.
    """
+    _check_removed_kwargs(kwargs)
+
    timezone = _resolve_timezone(timezone, kwargs)

    # Resolve geoip BEFORE launch() to avoid double-resolution and ensure
@@ -555,20 +641,16 @@ def launch_context(
    # so it applies to ALL contexts, not just the default one.
    # locale and timezone are set via binary flags only — no CDP emulation.
    browser = launch(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                     timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
+                     timezone=timezone, locale=locale, extension_paths=extension_paths)

    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)

    try:
        context = browser.new_context(**context_kwargs)
@@ -608,7 +690,6 @@ async def launch_context_async(
    timezone: str | None = None,
    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
    geoip: bool = False,
-    backend: str | None = None,
    humanize: bool = False,
    human_preset: HumanPreset = "default",
    human_config: HumanConfigOverrides | None = None,
@@ -635,7 +716,6 @@ async def launch_context_async(
        timezone: IANA timezone (e.g. 'America/New_York').
        color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
        geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
        human_config: Custom humanize config mapping to override preset values.
@@ -663,6 +743,8 @@ async def launch_context_async(
        >>>
        >>> asyncio.run(main())
    """
+    _check_removed_kwargs(kwargs)
+
    timezone = _resolve_timezone(timezone, kwargs)

    # Resolve geoip BEFORE launch_async() to avoid double-resolution and ensure
@@ -675,20 +757,16 @@ async def launch_context_async(
    # so it applies to ALL contexts, not just the default one.
    # locale and timezone are set via binary flags only — no CDP emulation.
    browser = await launch_async(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                                 timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
+                                 timezone=timezone, locale=locale, extension_paths=extension_paths)

    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)

    # Catch BaseException (not just Exception) so that asyncio.CancelledError
    # triggers browser cleanup — otherwise the underlying Chromium process
@@ -723,47 +801,6 @@ async def launch_context_async(
    return context


-# ---------------------------------------------------------------------------
-# Backend resolution
-# ---------------------------------------------------------------------------
-
-
-def _resolve_backend(backend: str | None) -> str:
-    """Resolve backend: param > env var > default ('playwright')."""
-    b = backend or os.environ.get("CLOAKBROWSER_BACKEND", "playwright")
-    if b not in ("playwright", "patchright"):
-        raise ValueError(f"Unknown backend '{b}'. Use 'playwright' or 'patchright'.")
-    return b
-
-
-def _import_sync_playwright(backend: str):
-    """Import sync_playwright from the resolved backend."""
-    if backend == "patchright":
-        try:
-            from patchright.sync_api import sync_playwright
-        except ModuleNotFoundError:
-            raise ModuleNotFoundError(
-                "patchright is not installed. Install it with: pip install cloakbrowser[patchright]"
-            ) from None
-        return sync_playwright
-    from playwright.sync_api import sync_playwright
-    return sync_playwright
-
-
-def _import_async_playwright(backend: str):
-    """Import async_playwright from the resolved backend."""
-    if backend == "patchright":
-        try:
-            from patchright.async_api import async_playwright
-        except ModuleNotFoundError:
-            raise ModuleNotFoundError(
-                "patchright is not installed. Install it with: pip install cloakbrowser[patchright]"
-            ) from None
-        return async_playwright
-    from playwright.async_api import async_playwright
-    return async_playwright
-
-
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------
@@ -774,7 +811,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 +822,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 +853,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 +893,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 +1098,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 +1186,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 +1209,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)}, []
@@ -15,16 +15,29 @@ from ._version import __version__
 # CHROMIUM_VERSION is the latest across all platforms (for display/reference).
 # Use get_chromium_version() for the current platform's actual version.
 # ---------------------------------------------------------------------------
-CHROMIUM_VERSION = "146.0.7680.177.3"
+CHROMIUM_VERSION = "146.0.7680.177.5"

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

+# ---------------------------------------------------------------------------
+# Ed25519 public keys for verifying downloaded binaries.
+#
+# Each release publishes SHA256SUMS and a detached signature SHA256SUMS.sig.
+# The wrapper verifies that signature against the keys below before trusting
+# any hash in the manifest, so the download origin alone cannot certify a
+# tampered binary. Values are base64 of the 32-byte raw public key. Multiple
+# entries are accepted to allow key rotation.
+# ---------------------------------------------------------------------------
+BINARY_SIGNING_PUBKEYS: list[str] = [
+    "MKFKwIhUcKWq5xTuNA0Ovg99njcDEcEJvmWYYhApvaU=",
+]
+
 # ---------------------------------------------------------------------------
 # Playwright default args to suppress — these leak automation signals.
 # --enable-automation: exposes navigator.webdriver = true
@@ -55,16 +68,19 @@ def get_default_stealth_args() -> list[str]:
        # Tell the fingerprint patches we're on macOS so GPU/UA match natively
        return base + ["--fingerprint-platform=macos"]

-    # Linux/Windows: Windows fingerprint profile
-    # Hardware concurrency, device memory, screen, window size, and GPU are
-    # auto-generated by the binary from the seed (v14+).
+    # Linux/Windows: Windows fingerprint profile.
+    # Screen and window size come from the real display, not this flag (verified:
+    # identical across seeds), so the wrapper must not emulate a viewport on top in
+    # headed mode — that would break outerWidth >= innerWidth coherence.
    return base + ["--fingerprint-platform=windows"]


 # ---------------------------------------------------------------------------
-# Default viewport — realistic maximized Chrome on 1080p Windows
-# screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
-# innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+# Default viewport — used for HEADLESS only (headed launches use no_viewport so
+# the page tracks the real window). Headless has no window chrome, so a fixed
+# viewport stays coherent (outer == inner) and gives deterministic dimensions.
+# Models a maximized Chrome on 1080p Windows: screen=1920x1080,
+# innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks).
 # ---------------------------------------------------------------------------
 DEFAULT_VIEWPORT = {"width": 1920, "height": 947}

@@ -23,6 +23,7 @@ import httpx

 from ._version import __version__ as _wrapper_version
 from .config import (
+    BINARY_SIGNING_PUBKEYS,
    CHROMIUM_VERSION,
    DOWNLOAD_BASE_URL,
    GITHUB_API_URL,
@@ -162,9 +163,11 @@ def _download_and_extract(version: str | None = None) -> None:
            )
            _download_file(fallback_url, tmp_path)

-        # Verify checksum before extraction
-        if os.environ.get("CLOAKBROWSER_SKIP_CHECKSUM", "").lower() != "true":
-            _verify_download_checksum(tmp_path, version)
+        # Verify the download before extraction. On the official path this is a
+        # mandatory, non-bypassable Ed25519 signature check (see
+        # _verify_download_checksum); the skip flag only applies to custom
+        # self-hosted CLOAKBROWSER_DOWNLOAD_URL setups.
+        _verify_download_checksum(tmp_path, version)

        _extract_archive(tmp_path, binary_dir, binary_path)
        _show_welcome()
@@ -174,22 +177,159 @@ def _download_and_extract(version: str | None = None) -> None:


 def _verify_download_checksum(file_path: Path, version: str | None = None) -> None:
-    """Fetch SHA256SUMS and verify the downloaded file. Warn if unavailable, fail on mismatch."""
-    checksums = _fetch_checksums(version)
+    """Verify the downloaded archive's integrity and authenticity.
+
+    Official path (cloakbrowser.dev / GitHub Releases): fetch SHA256SUMS plus
+    its detached Ed25519 signature SHA256SUMS.sig, verify the signature against
+    the pinned public keys FIRST, then verify the archive's SHA-256 against the
+    now-authenticated manifest. Mandatory and non-bypassable — a same-origin
+    manifest can no longer certify a tampered binary (#308).
+
+    Custom self-hosted path (CLOAKBROWSER_DOWNLOAD_URL set): the pinned keys do
+    not apply to a third-party server, so fall back to the plain same-origin
+    SHA256SUMS check, which CLOAKBROWSER_SKIP_CHECKSUM may bypass.
+    """
    tarball_name = get_archive_name()

-    if checksums is None:
-        logger.warning("SHA256SUMS not available for this release — skipping checksum verification")
+    if os.environ.get("CLOAKBROWSER_DOWNLOAD_URL"):
+        # Self-hosted mirror: signature scheme does not apply. Preserve the
+        # legacy same-origin checksum behavior, skippable as before.
+        if os.environ.get("CLOAKBROWSER_SKIP_CHECKSUM", "").lower() == "true":
+            logger.warning(
+                "CLOAKBROWSER_SKIP_CHECKSUM set — skipping verification for custom download URL"
+            )
+            return
+        checksums = _fetch_checksums(version)
+        if checksums is None:
+            logger.warning(
+                "SHA256SUMS not available from custom URL — skipping checksum verification"
+            )
+            return
+        expected = checksums.get(tarball_name)
+        if expected is None:
+            logger.warning(
+                "SHA256SUMS found but no entry for %s — skipping verification", tarball_name
+            )
+            return
+        _verify_checksum(file_path, expected)
        return

+    # Official path: signature is the trust root and is non-bypassable.
+    manifest = _fetch_signed_manifest(version)
+    if manifest is None:
+        raise RuntimeError(
+            "Could not fetch a signed SHA256SUMS (SHA256SUMS + SHA256SUMS.sig) "
+            "for this release — refusing to use an unverified binary. "
+            "Retry, or report at https://github.com/CloakHQ/cloakbrowser/issues"
+        )
+    manifest_bytes, sig_bytes = manifest
+    _verify_signature(manifest_bytes, sig_bytes)
+    manifest_text = manifest_bytes.decode("utf-8")
+
+    # Version binding: the signed manifest must declare the version we asked for.
+    # The signature proves "we made this manifest", not "this is the version you
+    # requested" — without this check a mirror could serve a genuinely-signed
+    # older release in place of the requested one (forced downgrade).
+    requested = version or get_chromium_version()
+    declared = _parse_manifest_version(manifest_text)
+    if declared != requested:
+        raise RuntimeError(
+            f"Version mismatch in signed SHA256SUMS: requested {requested}, "
+            f"manifest declares {declared or 'none'}. Refusing (possible downgrade)."
+        )
+
+    checksums = _parse_checksums(manifest_text)
    expected = checksums.get(tarball_name)
    if expected is None:
-        logger.warning("SHA256SUMS found but no entry for %s — skipping verification", tarball_name)
-        return
-
+        raise RuntimeError(
+            f"Signature-verified SHA256SUMS has no entry for {tarball_name} — "
+            f"cannot confirm binary integrity."
+        )
    _verify_checksum(file_path, expected)


+def _parse_manifest_version(text: str) -> str | None:
+    """Read the 'version=<v>' line from a signed manifest. None if absent.
+
+    The line has no internal whitespace so older wrappers' SHA256SUMS parsers
+    ignore it (they only accept '<hash>  <filename>' lines).
+    """
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("version="):
+            return line[len("version="):].strip()
+    return None
+
+
+def _fetch_signed_manifest(version: str | None = None) -> tuple[bytes, bytes] | None:
+    """Fetch (SHA256SUMS, SHA256SUMS.sig) raw bytes for a version, or None.
+
+    Both files are fetched from the SAME origin so the signature always matches
+    the exact manifest bytes it certifies. The primary origin is tried first,
+    then the GitHub Releases mirror. follow_redirects mirrors _fetch_checksums:
+    cloakbrowser.dev 301-redirects /chromium-v* to GitHub Releases.
+    """
+    v = version or get_chromium_version()
+    bases = [
+        f"{DOWNLOAD_BASE_URL}/chromium-v{v}",
+        f"{GITHUB_DOWNLOAD_BASE_URL}/chromium-v{v}",
+    ]
+    for base in bases:
+        try:
+            manifest_resp = httpx.get(
+                f"{base}/SHA256SUMS", follow_redirects=True, timeout=10.0
+            )
+            manifest_resp.raise_for_status()
+            sig_resp = httpx.get(
+                f"{base}/SHA256SUMS.sig", follow_redirects=True, timeout=10.0
+            )
+            sig_resp.raise_for_status()
+            return manifest_resp.content, sig_resp.content
+        except Exception:
+            continue
+    return None
+
+
+def _verify_signature(manifest_bytes: bytes, sig_b64: bytes) -> None:
+    """Verify a detached Ed25519 signature over the raw manifest bytes.
+
+    sig_b64 is the base64 of the 64-byte raw signature. Tries each pinned key
+    in BINARY_SIGNING_PUBKEYS; succeeds if any validates. Raises RuntimeError
+    if the signature is malformed or no pinned key validates it.
+    """
+    import base64
+
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    try:
+        signature = base64.b64decode(sig_b64.strip(), validate=True)
+    except Exception as exc:
+        raise RuntimeError(f"Malformed SHA256SUMS.sig (not valid base64): {exc}")
+
+    for pubkey_b64 in BINARY_SIGNING_PUBKEYS:
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(pubkey_b64))
+        except Exception:
+            # Skip an unparseable pinned key (e.g. the placeholder) rather than
+            # aborting — another pinned key may still validate.
+            continue
+        try:
+            pub.verify(signature, manifest_bytes)
+            logger.info("SHA256SUMS signature verified: Ed25519 OK")
+            return
+        except Exception:
+            # InvalidSignature, or a malformed/wrong-length signature that makes
+            # verify raise something else — either way this key didn't match,
+            # so try the next pinned key (and ultimately fail closed below).
+            continue
+
+    raise RuntimeError(
+        "SHA256SUMS signature verification failed — no pinned key validated the "
+        "manifest. The binary's authenticity could not be confirmed. "
+        "Report at https://github.com/CloakHQ/cloakbrowser/issues"
+    )
+
+
 def _fetch_checksums(version: str | None = None) -> dict[str, str] | None:
    """Fetch SHA256SUMS file for a version. Returns {filename: hash} or None."""
    v = version or get_chromium_version()
@@ -211,17 +351,22 @@ def _fetch_checksums(version: str | None = None) -> dict[str, str] | None:


 def _parse_checksums(text: str) -> dict[str, str]:
-    """Parse SHA256SUMS format: 'hash  filename' per line."""
+    """Parse SHA256SUMS format: '<64-hex sha256>  filename' per line.
+
+    Only lines whose first token is a 64-character hex digest are accepted
+    (matches the JS parser); blank lines, the version= line, and any other
+    junk are ignored.
+    """
    result = {}
    for line in text.strip().splitlines():
-        line = line.strip()
-        if not line:
+        parts = line.strip().split(None, 1)
+        if len(parts) != 2:
            continue
-        parts = line.split(None, 1)
-        if len(parts) == 2:
-            hash_val, filename = parts
-            filename = filename.lstrip("*")
-            result[filename] = hash_val.lower()
+        hash_val, filename = parts
+        hash_val = hash_val.lower()
+        if len(hash_val) != 64 or any(c not in "0123456789abcdef" for c in hash_val):
+            continue
+        result[filename.lstrip("*")] = hash_val
    return result


@@ -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
@@ -19,8 +19,8 @@
      packageInfo = {
        x86_64-linux = {
          platformTag = "linux-x64";
-          version = "146.0.7680.177.3";
-          hash = "sha256-WvAn+q+x/vmTPreEwJS3ZHBt4io3KizuhLwRf8SrU38=";
+          version = "146.0.7680.177.5";
+          hash = "sha256-ShK83pX6G7G+7ytBq15cJ8Nr544749DayMZNcFIWZw4=";
        };
        aarch64-linux = {
          platformTag = "linux-arm64";
@@ -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.29",
+  "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": {
@@ -27,16 +27,29 @@ export { WRAPPER_VERSION };
 // CHROMIUM_VERSION is the latest across all platforms (for display/reference).
 // Use getChromiumVersion() for the current platform's actual version.
 // ---------------------------------------------------------------------------
-export const CHROMIUM_VERSION = "146.0.7680.177.3";
+export const CHROMIUM_VERSION = "146.0.7680.177.5";

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

+// ---------------------------------------------------------------------------
+// Ed25519 public keys for verifying downloaded binaries.
+//
+// Each release publishes SHA256SUMS and a detached signature SHA256SUMS.sig.
+// The wrapper verifies that signature against the keys below before trusting
+// any hash in the manifest, so the download origin alone cannot certify a
+// tampered binary. Values are base64 of the 32-byte raw public key. Multiple
+// entries are accepted to allow key rotation. Keep in parity with config.py.
+// ---------------------------------------------------------------------------
+export const BINARY_SIGNING_PUBKEYS: string[] = [
+  "MKFKwIhUcKWq5xTuNA0Ovg99njcDEcEJvmWYYhApvaU=",
+];
+
 // ---------------------------------------------------------------------------
 // Platform detection
 // ---------------------------------------------------------------------------
@@ -200,9 +213,11 @@ export const IGNORE_DEFAULT_ARGS = ["--enable-automation", "--enable-unsafe-swif
 // ---------------------------------------------------------------------------
 // Default stealth arguments
 // ---------------------------------------------------------------------------
-// Default viewport — realistic maximized Chrome on 1080p Windows
-// screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
-// innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+// Default viewport — used for HEADLESS only (headed launches use no viewport so
+// the page tracks the real window). Headless has no window chrome, so a fixed
+// viewport stays coherent (outer == inner) and gives deterministic dimensions.
+// Models a maximized Chrome on 1080p Windows: screen=1920x1080,
+// innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks).
 export const DEFAULT_VIEWPORT = { width: 1920, height: 947 };

 export function getDefaultStealthArgs(): string[] {
@@ -219,8 +234,9 @@ export function getDefaultStealthArgs(): string[] {
    return [...base, "--fingerprint-platform=macos"];
  }

-  // Linux/Windows: spoof as Windows desktop
-  // Hardware concurrency, device memory, screen, window size, and GPU are
-  // auto-generated by the binary from the seed (v14+).
+  // Linux/Windows: spoof as Windows desktop.
+  // Screen and window size come from the real display, not this flag (verified:
+  // identical across seeds), so the wrapper must not emulate a viewport on top in
+  // headed mode — that would break outerWidth >= innerWidth coherence.
  return [...base, "--fingerprint-platform=windows"];
 }
@@ -5,7 +5,7 @@
 */

 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
@@ -14,6 +14,7 @@ import { extract as tarExtract } from "tar";

 import type { BinaryInfo } from "./types.js";
 import {
+  BINARY_SIGNING_PUBKEYS,
  DOWNLOAD_BASE_URL,
  GITHUB_API_URL,
  GITHUB_DOWNLOAD_BASE_URL,
@@ -195,10 +196,11 @@ async function downloadAndExtract(version?: string): Promise<void> {
      await downloadFile(fallbackUrl, tmpPath);
    }

-    // Verify checksum before extraction
-    if (process.env.CLOAKBROWSER_SKIP_CHECKSUM?.toLowerCase() !== "true") {
-      await verifyDownloadChecksum(tmpPath, version);
-    }
+    // Verify the download before extraction. On the official path this is a
+    // mandatory, non-bypassable Ed25519 signature check (see
+    // verifyDownloadChecksum); the skip flag only applies to custom
+    // self-hosted CLOAKBROWSER_DOWNLOAD_URL setups.
+    await verifyDownloadChecksum(tmpPath, version);

    await extractArchive(tmpPath, binaryDir, binaryPath);
    showWelcome();
@@ -210,22 +212,176 @@ async function downloadAndExtract(version?: string): Promise<void> {
  }
 }

-async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
-  const checksums = await fetchChecksums(version);
+/** @internal Exported for testing only. */
+export async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
  const tarballName = getArchiveName();

-  if (!checksums) {
-    console.warn("[cloakbrowser] SHA256SUMS not available for this release — skipping checksum verification");
+  if (process.env.CLOAKBROWSER_DOWNLOAD_URL) {
+    // Self-hosted mirror: the pinned signature keys do not apply to a
+    // third-party server. Preserve the legacy same-origin checksum behavior,
+    // skippable via CLOAKBROWSER_SKIP_CHECKSUM.
+    if (process.env.CLOAKBROWSER_SKIP_CHECKSUM?.toLowerCase() === "true") {
+      console.warn(
+        "[cloakbrowser] CLOAKBROWSER_SKIP_CHECKSUM set — skipping verification for custom download URL"
+      );
+      return;
+    }
+    const checksums = await fetchChecksums(version);
+    if (!checksums) {
+      console.warn(
+        "[cloakbrowser] SHA256SUMS not available from custom URL — skipping checksum verification"
+      );
+      return;
+    }
+    const expectedCustom = checksums.get(tarballName);
+    if (!expectedCustom) {
+      console.warn(
+        `[cloakbrowser] SHA256SUMS found but no entry for ${tarballName} — skipping verification`
+      );
+      return;
+    }
+    await verifyChecksum(filePath, expectedCustom);
    return;
  }

+  // Official path: signature is the trust root and is non-bypassable.
+  const manifest = await fetchSignedManifest(version);
+  if (!manifest) {
+    throw new Error(
+      "Could not fetch a signed SHA256SUMS (SHA256SUMS + SHA256SUMS.sig) for " +
+        "this release — refusing to use an unverified binary. " +
+        "Retry, or report at https://github.com/CloakHQ/cloakbrowser/issues"
+    );
+  }
+  const { manifestBytes, sigBytes } = manifest;
+  verifySignature(manifestBytes, sigBytes);
+  const manifestText = new TextDecoder().decode(manifestBytes);
+
+  // Version binding: the signed manifest must declare the version we asked for.
+  // The signature proves "we made this manifest", not "this is the version you
+  // requested" — without this check a mirror could serve a genuinely-signed
+  // older release in place of the requested one (forced downgrade).
+  const requested = version || getChromiumVersion();
+  const declared = parseManifestVersion(manifestText);
+  if (declared !== requested) {
+    throw new Error(
+      `Version mismatch in signed SHA256SUMS: requested ${requested}, ` +
+        `manifest declares ${declared ?? "none"}. Refusing (possible downgrade).`
+    );
+  }
+
+  const checksums = parseChecksums(manifestText);
  const expected = checksums.get(tarballName);
  if (!expected) {
-    console.warn(`[cloakbrowser] SHA256SUMS found but no entry for ${tarballName} — skipping verification`);
-    return;
+    throw new Error(
+      `Signature-verified SHA256SUMS has no entry for ${tarballName} — ` +
+        `cannot confirm binary integrity.`
+    );
+  }
+  await verifyChecksum(filePath, expected);
+}
+
+/**
+ * Read the 'version=<v>' line from a signed manifest. null if absent.
+ * The line has no internal whitespace so older wrappers' SHA256SUMS parsers
+ * ignore it (they only accept '<hash>  <filename>' lines).
+ * @internal Exported for testing only.
+ */
+export function parseManifestVersion(text: string): string | null {
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("version=")) {
+      return line.slice("version=".length).trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Fetch (SHA256SUMS, SHA256SUMS.sig) raw bytes for a version, or null.
+ * Both files come from the SAME origin so the signature always matches the
+ * exact manifest bytes it certifies. Primary origin first, then GitHub mirror.
+ * @internal Exported for testing only.
+ */
+export async function fetchSignedManifest(
+  version?: string
+): Promise<{ manifestBytes: Uint8Array; sigBytes: Uint8Array } | null> {
+  const v = version || getChromiumVersion();
+  const bases = [
+    `${DOWNLOAD_BASE_URL}/chromium-v${v}`,
+    `${GITHUB_DOWNLOAD_BASE_URL}/chromium-v${v}`,
+  ];
+  for (const base of bases) {
+    try {
+      const manifestResp = await fetch(`${base}/SHA256SUMS`, {
+        redirect: "follow",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!manifestResp.ok) continue;
+      const sigResp = await fetch(`${base}/SHA256SUMS.sig`, {
+        redirect: "follow",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!sigResp.ok) continue;
+      return {
+        manifestBytes: new Uint8Array(await manifestResp.arrayBuffer()),
+        sigBytes: new Uint8Array(await sigResp.arrayBuffer()),
+      };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Verify a detached Ed25519 signature over the raw manifest bytes.
+ * sigB64Bytes is the (base64-text) content of SHA256SUMS.sig. Tries each pinned
+ * key; succeeds if any validates. Throws if malformed or no key validates.
+ * @internal Exported for testing only.
+ */
+export function verifySignature(manifestBytes: Uint8Array, sigB64Bytes: Uint8Array): void {
+  // Node's Buffer.from(...,"base64") is lenient — it silently drops invalid
+  // characters instead of throwing. Validate by canonical round-trip so a
+  // malformed .sig is reported as such (parity with Python's
+  // base64.b64decode(validate=True)).
+  const sigText = new TextDecoder().decode(sigB64Bytes).trim();
+  const signature = Buffer.from(sigText, "base64");
+  if (signature.toString("base64") !== sigText) {
+    throw new Error("Malformed SHA256SUMS.sig (not valid base64)");
  }

-  await verifyChecksum(filePath, expected);
+  for (const pubkeyB64 of BINARY_SIGNING_PUBKEYS) {
+    let keyObject;
+    try {
+      // Build an Ed25519 public key from raw 32 bytes via JWK import.
+      const x = Buffer.from(pubkeyB64, "base64").toString("base64url");
+      keyObject = createPublicKey({
+        key: { kty: "OKP", crv: "Ed25519", x },
+        format: "jwk",
+      });
+    } catch {
+      // Skip an unparseable pinned key (e.g. the placeholder); another may validate.
+      continue;
+    }
+    try {
+      if (cryptoVerify(null, manifestBytes, keyObject, signature)) {
+        console.log("[cloakbrowser] SHA256SUMS signature verified: Ed25519 OK");
+        return;
+      }
+    } catch {
+      // A malformed/wrong-length signature can make verify throw rather than
+      // return false — treat it as a non-match and try the next pinned key
+      // (parity with Python's try/except around pub.verify), failing closed below.
+      continue;
+    }
+  }
+
+  throw new Error(
+    "SHA256SUMS signature verification failed — no pinned key validated the " +
+      "manifest. The binary's authenticity could not be confirmed. " +
+      "Report at https://github.com/CloakHQ/cloakbrowser/issues"
+  );
 }

 /** @internal Exported for testing only. */
@@ -425,11 +581,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,54 @@ 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()`.
+ */
+/**
+ * Effective headless mode for viewport decisions. buildLaunchOptions() spreads
+ * `...options.launchOptions` LAST, so a raw `launchOptions.headless` overrides the
+ * top-level field at the actual chromium.launch() call. Viewport logic must read
+ * the same effective value — otherwise a headed browser gets a fixed viewport
+ * (reintroducing the impossible-window tell). Playwright-specific (Puppeteer
+ * resolves headless the opposite way).
+ */
+function effectiveHeadless(options: LaunchOptions): boolean {
+  return (
+    (options.launchOptions as { headless?: boolean } | undefined)?.headless ??
+    options.headless ??
+    true
+  );
+}
+
+export function buildContextOptions(
+  options: LaunchContextOptions = {}
+): BrowserContextOptions {
+  // Headed: viewport=null (no emulation) so the page tracks the real window and
+  // outerWidth >= innerWidth stays coherent — CDP viewport emulation forces
+  // inner > outer = a physically impossible window = bot tell. Headless has no
+  // window chrome (outer == inner), so a fixed viewport stays coherent and keeps
+  // dimensions deterministic. Explicit viewport (incl. null) is always honored.
+  const headless = effectiveHeadless(options);
+  const viewport =
+    options.viewport !== undefined
+      ? options.viewport
+      : headless
+        ? DEFAULT_VIEWPORT
+        : null;
+  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.colorScheme ? { colorScheme: options.colorScheme } : {}),
+  } as BrowserContextOptions;
+}
+
 /**
 * Build Playwright launch options for CloakBrowser without starting Chromium.
 *
@@ -106,10 +155,33 @@ export async function humanizeBrowser(
 export async function launch(options: LaunchOptions = {}): Promise<Browser> {
  const { chromium } = await import("playwright-core");
  const browser = await chromium.launch(await buildLaunchOptions(options));
+  // Headed: a bare browser.newPage() would inherit Playwright's emulated 1280x720
+  // viewport -> outerWidth < innerWidth (impossible window = bot tell). Default
+  // newPage()/newContext() to viewport:null so the page tracks the real window.
+  // Headless keeps Playwright's default viewport (coherent there).
+  if (!effectiveHeadless(options)) {
+    applyDefaultNoViewport(browser);
+  }
  await humanizeBrowser(browser, options);
  return browser;
 }

+/**
+ * Wrap a Browser's newContext()/newPage() to default to viewport:null (no
+ * emulation) when the caller didn't specify a viewport. setdefault-style: an
+ * explicit viewport (including null) is always honored. Apply before humanize's
+ * patchBrowser so the wraps compose.
+ */
+function applyDefaultNoViewport(browser: Browser): void {
+  const origNewContext = browser.newContext.bind(browser);
+  (browser as any).newContext = (options?: Parameters<typeof origNewContext>[0]) =>
+    origNewContext(options?.viewport === undefined ? { ...options, viewport: null } : options);
+
+  const origNewPage = browser.newPage.bind(browser);
+  (browser as any).newPage = (options?: Parameters<typeof origNewPage>[0]) =>
+    origNewPage(options?.viewport === undefined ? { ...options, viewport: null } : options);
+}
+
 /**
 * Launch stealth browser and return a BrowserContext with common options pre-set.
 * Closing the context also closes the browser.
@@ -140,18 +212,13 @@ export async function launchContext(
  // --fingerprint-timezone is process-wide (reads CommandLine in renderer),
  // so it applies to ALL contexts, not just the default one.
  // locale and timezone are set via binary flags only — no CDP emulation.
-  const browser = await launch({ ...options, ...resolved, args: launchArgs, geoip: false });
+  // humanize:false on the inner launch — patchContext below applies humanize
+  // exactly once (else launch()'s humanizeBrowser would patch it a second time).
+  const browser = await launch({ ...options, ...resolved, args: launchArgs, geoip: false, humanize: false });

  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 +281,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 +291,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: [] };
  }
@@ -6,11 +6,30 @@

 import type { Browser } from "puppeteer-core";
 import type { LaunchOptions } from "./types.js";
-import { IGNORE_DEFAULT_ARGS } from "./config.js";
+import { DEFAULT_VIEWPORT, 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 Puppeteer's defaultViewport. Headed -> null (track the real window so
+ * outerWidth >= innerWidth stays coherent; Puppeteer otherwise forces an 800x600
+ * emulated viewport = a physically impossible window = bot tell). Headless has no
+ * window chrome (outer == inner), so a fixed viewport stays coherent and keeps
+ * dimensions deterministic. A user-supplied launchOptions.defaultViewport wins.
+ */
+function resolveDefaultViewport(options: LaunchOptions): { width: number; height: number } | null {
+  const launchOpts = (options.launchOptions ?? {}) as Record<string, unknown>;
+  // A user-supplied defaultViewport wins (incl. explicit null). undefined is NOT
+  // "supplied" — fall through to our default. Puppeteer sets `headless` AFTER the
+  // launchOptions spread, so the top-level field wins at launch — match it here.
+  if (launchOpts.defaultViewport !== undefined) {
+    return launchOpts.defaultViewport as { width: number; height: number } | null;
+  }
+  return (options.headless ?? true) ? DEFAULT_VIEWPORT : null;
+}

 /** Resolve binary path, geoip, webrtc, and build final Chrome args. */
 async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
@@ -26,9 +45,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 +58,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 +91,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,
@@ -107,6 +143,7 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    headless: options.headless ?? true,
    args,
    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+    defaultViewport: resolveDefaultViewport(options),
  });

  await applyPostLaunch(browser, options, proxyAuth);
@@ -138,6 +175,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,
@@ -145,6 +184,7 @@ export async function launchPersistentContext(
    args,
    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
    userDataDir: options.userDataDir,
+    defaultViewport: resolveDefaultViewport(options),
  });

  await applyPostLaunch(browser, options, proxyAuth);
@@ -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,102 @@ 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("buildContextOptions uses no viewport (null) when headed, so the page tracks the real window", async () => {
+    const { buildContextOptions } = await import("../src/index.js");
+
+    // Headed: no emulated viewport (CDP emulation would force outerWidth < innerWidth).
+    expect(buildContextOptions({ headless: false }).viewport).toBeNull();
+    // Headless keeps the deterministic default.
+    expect(buildContextOptions({ headless: true }).viewport).toEqual(DEFAULT_VIEWPORT);
+    // Explicit viewport always honored, even headed.
+    const custom = { width: 800, height: 600 };
+    expect(buildContextOptions({ headless: false, viewport: custom }).viewport).toEqual(custom);
+  });
+
+  it("buildContextOptions reads effective headless from launchOptions.headless", async () => {
+    const { buildContextOptions } = await import("../src/index.js");
+
+    // buildLaunchOptions spreads launchOptions LAST, so launchOptions.headless wins
+    // at the actual launch. Viewport must follow it — a raw headless:false (browser
+    // actually headed) must NOT get a fixed viewport (would reintroduce outer<inner).
+    expect(buildContextOptions({ launchOptions: { headless: false } }).viewport).toBeNull();
+    // And launchOptions.headless:true forces the deterministic viewport even if the
+    // top-level field said headed.
+    expect(
+      buildContextOptions({ headless: false, launchOptions: { headless: true } }).viewport,
+    ).toEqual(DEFAULT_VIEWPORT);
+  });
+
  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 +377,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();
+    }
+  });
 });
@@ -65,6 +65,53 @@ describe("puppeteer launch", () => {
    expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(false);
  });

+  it("headless (default) uses a fixed defaultViewport; headed uses null", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
+    const { launch } = await import("../src/puppeteer.js");
+
+    // Headless (default): deterministic viewport.
+    await launch();
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(DEFAULT_VIEWPORT);
+
+    // Headed: null so the page tracks the real window (else Puppeteer forces 800x600).
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launch({ headless: false });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+  });
+
+  it("honors an explicit launchOptions.defaultViewport (incl. null)", async () => {
+    const { launch } = await import("../src/puppeteer.js");
+
+    const custom = { width: 640, height: 480 };
+    await launch({ headless: true, launchOptions: { defaultViewport: custom } });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(custom);
+
+    // Explicit null honored even in headless (would otherwise default to DEFAULT_VIEWPORT).
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launch({ headless: true, launchOptions: { defaultViewport: null } });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+  });
+
+  it("Puppeteer headless precedence: top-level headless wins over launchOptions.headless", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
+    const { launch } = await import("../src/puppeteer.js");
+
+    // Puppeteer sets headless AFTER the launchOptions spread, so top-level wins at
+    // launch — the viewport decision must follow the same (top-level) value.
+    await launch({ headless: true, launchOptions: { headless: false } });
+    const opts = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(opts.headless).toBe(true);
+    expect(opts.defaultViewport).toEqual(DEFAULT_VIEWPORT);
+  });
+
  it("adds --proxy-server for string proxy", async () => {
    const { launch } = await import("../src/puppeteer.js");
    await launch({ proxy: "http://proxy:8080" });
@@ -84,16 +131,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 +259,40 @@ describe("puppeteer launchPersistentContext", () => {
    expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(true);
  });

-  it("handles proxy auth with persistent context", async () => {
+  it("headed persistent context uses null defaultViewport (tracks real window)", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
    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",
-    });
+    await launchPersistentContext({ userDataDir: "./my-profile", headless: false });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launchPersistentContext({ userDataDir: "./my-profile", headless: true });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(DEFAULT_VIEWPORT);
+  });
+
+  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",
+      });
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("keeps SOCKS5 credentials in --proxy-server URL", async () => {
@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { sign as cryptoSign, createPrivateKey, createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Generate a throwaway signing keypair BEFORE the config mock is hoisted, then
+// pin its public key so verifySignature accepts signatures we produce here.
+const h = vi.hoisted(() => {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const crypto = require("node:crypto");
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const otherPub = crypto.generateKeyPairSync("ed25519").publicKey;
+  const rawB64 = (pk: any) =>
+    Buffer.from(pk.export({ format: "jwk" }).x, "base64url").toString("base64");
+  return {
+    pinnedPubB64: rawB64(publicKey),
+    otherPubB64: rawB64(otherPub),
+    privPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+  };
+});
+
+vi.mock("../src/config.js", async (importActual) => {
+  const actual = await importActual<typeof import("../src/config.js")>();
+  return { ...actual, BINARY_SIGNING_PUBKEYS: [h.pinnedPubB64] };
+});
+
+import {
+  fetchSignedManifest,
+  parseChecksums,
+  parseManifestVersion,
+  verifyDownloadChecksum,
+  verifySignature,
+} from "../src/download.js";
+import { getArchiveName, getChromiumVersion } from "../src/config.js";
+
+/** Produce SHA256SUMS.sig content (base64 text bytes) for a manifest. */
+function sign(manifest: Uint8Array): Uint8Array {
+  const priv = createPrivateKey(h.privPem);
+  const sig = cryptoSign(null, manifest, priv); // raw 64-byte Ed25519 signature
+  return new TextEncoder().encode(sig.toString("base64"));
+}
+
+const enc = (s: string) => new TextEncoder().encode(s);
+
+describe("verifySignature", () => {
+  it("accepts a valid signature", () => {
+    const manifest = enc("abc  cloakbrowser-linux-x64.tar.gz\n");
+    expect(() => verifySignature(manifest, sign(manifest))).not.toThrow();
+  });
+
+  it("rejects a tampered manifest", () => {
+    const manifest = enc("abc  cloakbrowser-linux-x64.tar.gz\n");
+    const sig = sign(manifest);
+    const tampered = enc("xyz  cloakbrowser-linux-x64.tar.gz\n");
+    expect(() => verifySignature(tampered, sig)).toThrow(/signature verification failed/);
+  });
+
+  it("rejects malformed base64 in the .sig", () => {
+    expect(() => verifySignature(enc("data\n"), enc("!!!not base64!!!")))
+      .toThrow(/Malformed/);
+  });
+
+  it("rejects a signature from a non-pinned key", async () => {
+    // Re-mock config so ONLY the other key is pinned, then the signature
+    // (made with the real key) must fail.
+    vi.resetModules();
+    vi.doMock("../src/config.js", async (importActual) => {
+      const actual = await importActual<typeof import("../src/config.js")>();
+      return { ...actual, BINARY_SIGNING_PUBKEYS: [h.otherPubB64] };
+    });
+    const { verifySignature: vs } = await import("../src/download.js");
+    const manifest = enc("data\n");
+    expect(() => vs(manifest, sign(manifest))).toThrow(/signature verification failed/);
+    vi.doUnmock("../src/config.js");
+    vi.resetModules();
+  });
+
+  it("accepts a signature under the new key during rotation", async () => {
+    // Pin BOTH keys (old + new) and sign with the real (new) key — must pass.
+    vi.resetModules();
+    vi.doMock("../src/config.js", async (importActual) => {
+      const actual = await importActual<typeof import("../src/config.js")>();
+      return { ...actual, BINARY_SIGNING_PUBKEYS: [h.otherPubB64, h.pinnedPubB64] };
+    });
+    const { verifySignature: vs } = await import("../src/download.js");
+    const manifest = enc("rotated\n");
+    expect(() => vs(manifest, sign(manifest))).not.toThrow();
+    vi.doUnmock("../src/config.js");
+    vi.resetModules();
+  });
+});
+
+describe("verifyDownloadChecksum (official path, fail-closed)", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.CLOAKBROWSER_DOWNLOAD_URL;
+    delete process.env.CLOAKBROWSER_SKIP_CHECKSUM;
+  });
+
+  function tmpFile(bytes: Buffer): string {
+    const p = path.join(os.tmpdir(), `cloak-sig-${process.pid}-${bytes.length}-${bytes[0]}`);
+    fs.writeFileSync(p, bytes);
+    return p;
+  }
+
+  /** Mock fetch to serve a signed manifest for the official URLs. */
+  function mockManifest(manifestBytes: Uint8Array) {
+    const sig = sign(manifestBytes);
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = typeof input === "string" ? input : (input as URL).toString();
+      const body = url.endsWith(".sig") ? sig : manifestBytes;
+      return { ok: true, arrayBuffer: async () => body.buffer } as Response;
+    });
+  }
+
+  /** Manifest body with the bound version line prepended (defaults to current). */
+  const body = (lines: string, version = getChromiumVersion()) =>
+    enc(`version=${version}\n${lines}`);
+
+  it("passes when signature is valid and hash matches", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`));
+    await expect(verifyDownloadChecksum(file)).resolves.toBeUndefined();
+  });
+
+  it("fails when the binary is tampered (hash mismatch)", async () => {
+    const file = tmpFile(Buffer.from("a malicious binary"));
+    const goodHash = createHash("sha256").update(Buffer.from("the real binary")).digest("hex");
+    mockManifest(body(`${goodHash}  ${getArchiveName()}\n`));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Checksum verification failed/);
+  });
+
+  it("fails on a signed manifest for the wrong version (downgrade)", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    // Genuinely signed, but declares an old version we did not request.
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`, "1.0.0.0"));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Version mismatch/);
+  });
+
+  it("fails when the version line is missing (binding required)", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(enc(`${hash}  ${getArchiveName()}\n`)); // no version= line
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Version mismatch/);
+  });
+
+  it("fails closed when no signed manifest can be fetched", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({ ok: false, status: 404 } as Response);
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/signed SHA256SUMS/);
+  });
+
+  it("fails when the signed manifest has no entry for this platform", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    const someHash = "0".repeat(64);
+    mockManifest(body(`${someHash}  some-other-file.tar.gz\n`));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/no entry for/);
+  });
+
+  it("custom download URL keeps the legacy skippable path (no signature fetch)", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    process.env.CLOAKBROWSER_DOWNLOAD_URL = "https://my-mirror.test";
+    process.env.CLOAKBROWSER_SKIP_CHECKSUM = "true";
+    const spy = vi.spyOn(globalThis, "fetch");
+    await expect(verifyDownloadChecksum(file)).resolves.toBeUndefined();
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
+
+describe("version binding", () => {
+  it("reads the version= line", () => {
+    expect(
+      parseManifestVersion("version=146.0.7680.177.5\nabc  file.tar.gz\n")
+    ).toBe("146.0.7680.177.5");
+  });
+
+  it("returns null when absent", () => {
+    expect(parseManifestVersion("abc  file.tar.gz\n")).toBeNull();
+  });
+
+  it("old parseChecksums ignores the version line", () => {
+    const result = parseChecksums(
+      `version=146.0.7680.177.5\n${"a".repeat(64)}  cloakbrowser-linux-x64.tar.gz\n`
+    );
+    expect(result.size).toBe(1);
+    expect(result.has("cloakbrowser-linux-x64.tar.gz")).toBe(true);
+  });
+});
+
+describe("fetchSignedManifest", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const mockPair = (manifest: string, sig: string, failPrimarySig = false) =>
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = typeof input === "string" ? input : (input as URL).toString();
+      const isSig = url.endsWith(".sig");
+      if (url.includes("cloakbrowser.dev") && isSig && failPrimarySig) {
+        return { ok: false, status: 404 } as Response;
+      }
+      return {
+        ok: true,
+        arrayBuffer: async () =>
+          new TextEncoder().encode(isSig ? sig : manifest).buffer,
+      } as Response;
+    });
+
+  it("returns manifest + sig from the primary origin", async () => {
+    mockPair("MANIFEST", "U0lH");
+    const result = await fetchSignedManifest("1.2.3.4");
+    expect(new TextDecoder().decode(result!.manifestBytes)).toBe("MANIFEST");
+    expect(new TextDecoder().decode(result!.sigBytes)).toBe("U0lH");
+  });
+
+  it("falls back to GitHub when the primary .sig is missing", async () => {
+    const spy = mockPair("MANIFEST", "U0lH", true);
+    const result = await fetchSignedManifest("1.2.3.4");
+    expect(result).not.toBeNull();
+    // primary SHA256SUMS + primary .sig (404) + github SHA256SUMS + github .sig
+    expect(spy.mock.calls.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("returns null when everything fails", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("network"));
+    expect(await fetchSignedManifest("1.2.3.4")).toBeNull();
+  });
+});
@@ -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));
+  });
+});
@@ -51,11 +51,11 @@ classifiers = [
 dependencies = [
    "playwright>=1.40",
    "httpx>=0.24",
+    "cryptography>=41.0",  # verify Ed25519 signature on SHA256SUMS before trusting it
 ]

 [project.optional-dependencies]
 geoip = ["geoip2>=4.0", "socksio>=1.0"]  # socksio: SOCKS5 transport for httpx
-patchright = ["patchright>=1.40"]
 serve = ["aiohttp>=3.9", "websockets>=12.0"]
 dev = ["pytest>=7.0", "pytest-asyncio>=0.23"]

@@ -1,11 +0,0 @@
-"""Shared test fixtures."""
-
-import os
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def _clean_backend_env(monkeypatch):
-    """Ensure CLOAKBROWSER_BACKEND doesn't leak into tests from the host environment."""
-    monkeypatch.delenv("CLOAKBROWSER_BACKEND", raising=False)
@@ -1,45 +0,0 @@
-"""Unit tests for backend resolution (_resolve_backend)."""
-
-import os
-from unittest.mock import patch
-
-import pytest
-
-from cloakbrowser.browser import _resolve_backend
-
-
-def test_resolve_backend_default():
-    """No param, no env var → 'playwright'."""
-    with patch.dict(os.environ, {}, clear=True):
-        assert _resolve_backend(None) == "playwright"
-
-
-def test_resolve_backend_explicit_playwright():
-    assert _resolve_backend("playwright") == "playwright"
-
-
-def test_resolve_backend_explicit_patchright():
-    assert _resolve_backend("patchright") == "patchright"
-
-
-def test_resolve_backend_env_var():
-    """CLOAKBROWSER_BACKEND env var used when no param."""
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "patchright"}):
-        assert _resolve_backend(None) == "patchright"
-
-
-def test_resolve_backend_param_beats_env():
-    """Explicit param overrides env var."""
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "patchright"}):
-        assert _resolve_backend("playwright") == "playwright"
-
-
-def test_resolve_backend_invalid_raises():
-    with pytest.raises(ValueError, match="Unknown backend 'bogus'"):
-        _resolve_backend("bogus")
-
-
-def test_resolve_backend_invalid_env_raises():
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "bogus"}):
-        with pytest.raises(ValueError, match="Unknown backend 'bogus'"):
-            _resolve_backend(None)
@@ -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)
@@ -5,8 +5,8 @@ from cloakbrowser import launch


@patch("cloakbrowser.browser.ensure_binary")
-@patch("cloakbrowser.browser._import_sync_playwright")
-def test_extension_loading(mock_playwright_import, mock_ensure_binary):
+@patch("playwright.sync_api.sync_playwright")
+def test_extension_loading(mock_sync_playwright, mock_ensure_binary):
    mock_ensure_binary.return_value = "/fake/chrome"

    mock_browser = MagicMock()
@@ -14,10 +14,7 @@ def test_extension_loading(mock_playwright_import, mock_ensure_binary):
    mock_pw = MagicMock()
    mock_pw.chromium.launch.return_value = mock_browser

-    mock_pw_manager = MagicMock()
-    mock_pw_manager.return_value.start.return_value = mock_pw
-
-    mock_playwright_import.return_value = mock_pw_manager
+    mock_sync_playwright.return_value.start.return_value = mock_pw

    launch(extension_paths=["./ext"])

@@ -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)
 # =========================================================================
@@ -1,10 +1,33 @@
 """Basic launch tests for cloakbrowser."""

 import pytest
-from cloakbrowser import launch, launch_async, binary_info
+from cloakbrowser import (
+    launch,
+    launch_async,
+    launch_context,
+    launch_persistent_context,
+    binary_info,
+)
 from cloakbrowser.config import get_chromium_version


+@pytest.mark.parametrize("env", [None, "patchright"])
+def test_removed_backend_kwarg_raises(env, monkeypatch):
+    """The removed `backend` parameter raises a clear TypeError before any
+    launch side effects, regardless of the (also removed) CLOAKBROWSER_BACKEND
+    env var. Guards the patchright removal."""
+    if env is None:
+        monkeypatch.delenv("CLOAKBROWSER_BACKEND", raising=False)
+    else:
+        monkeypatch.setenv("CLOAKBROWSER_BACKEND", env)
+    with pytest.raises(TypeError, match="backend"):
+        launch(backend="patchright")
+    with pytest.raises(TypeError, match="backend"):
+        launch_context(backend="patchright")
+    with pytest.raises(TypeError, match="backend"):
+        launch_persistent_context("/tmp/cloakbrowser-test-profile", backend="patchright")
+
+
 def test_binary_info():
    """binary_info() returns expected structure."""
    info = binary_info()
@@ -33,6 +33,82 @@ def test_default_viewport(mock_launch, _mock_bin):
    assert ctx_kwargs[1]["viewport"] == DEFAULT_VIEWPORT


+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch")
+def test_headed_no_viewport(mock_launch, _mock_bin):
+    """Headed (headless=False): no emulated viewport — no_viewport=True so the page
+    tracks the real window (CDP viewport emulation would force outerWidth < innerWidth)."""
+    browser, context = _make_mock_browser()
+    mock_launch.return_value = browser
+
+    from cloakbrowser.browser import launch_context
+    launch_context(headless=False)
+
+    ctx_kwargs = browser.new_context.call_args[1]
+    assert ctx_kwargs.get("no_viewport") is True
+    assert "viewport" not in ctx_kwargs
+
+
+def test_default_no_viewport_helper():
+    """_default_no_viewport defaults new_page()/new_context() to no_viewport=True,
+    but never overrides an explicit viewport (Playwright rejects passing both)."""
+    from cloakbrowser.browser import _default_no_viewport
+
+    browser = MagicMock()
+    orig_new_page = browser.new_page
+    orig_new_context = browser.new_context
+    _default_no_viewport(browser)
+
+    browser.new_page()
+    orig_new_page.assert_called_once_with(no_viewport=True)
+    browser.new_context()
+    orig_new_context.assert_called_once_with(no_viewport=True)
+
+    # Explicit viewport respected — no_viewport NOT injected.
+    orig_new_page.reset_mock()
+    browser.new_page(viewport={"width": 800, "height": 600})
+    orig_new_page.assert_called_once_with(viewport={"width": 800, "height": 600})
+
+
+@pytest.mark.asyncio
+async def test_default_no_viewport_helper_async():
+    """_default_no_viewport_async mirrors the sync helper for async new_page/new_context."""
+    from cloakbrowser.browser import _default_no_viewport_async
+
+    browser = MagicMock()
+    browser.new_page = AsyncMock()
+    browser.new_context = AsyncMock()
+    orig_new_page = browser.new_page
+    orig_new_context = browser.new_context
+    _default_no_viewport_async(browser)
+
+    await browser.new_page()
+    orig_new_page.assert_awaited_once_with(no_viewport=True)
+    await browser.new_context()
+    orig_new_context.assert_awaited_once_with(no_viewport=True)
+
+    # Explicit viewport respected — no_viewport NOT injected.
+    orig_new_page.reset_mock()
+    await browser.new_page(viewport={"width": 800, "height": 600})
+    orig_new_page.assert_awaited_once_with(viewport={"width": 800, "height": 600})
+
+
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch")
+def test_conflicting_viewport_kwargs_deduped(mock_launch, _mock_bin):
+    """If a caller forces no_viewport via **kwargs alongside viewport=, only one
+    reaches Playwright (which rejects both). The explicit kwargs value wins."""
+    browser, context = _make_mock_browser()
+    mock_launch.return_value = browser
+
+    from cloakbrowser.browser import launch_context
+    launch_context(viewport={"width": 1280, "height": 800}, no_viewport=True)
+
+    ctx_kwargs = browser.new_context.call_args[1]
+    assert ctx_kwargs.get("no_viewport") is True
+    assert "viewport" not in ctx_kwargs
+
+
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.launch")
 def test_custom_viewport(mock_launch, _mock_bin):
@@ -55,6 +55,22 @@ def test_persistent_context_default_viewport(_mock_geoip, _mock_bin):
    assert call_kwargs["viewport"] == DEFAULT_VIEWPORT


+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
+def test_persistent_context_headed_no_viewport(_mock_geoip, _mock_bin):
+    """Headed (headless=False): no_viewport=True instead of DEFAULT_VIEWPORT so the
+    page tracks the real window (avoids the outerWidth < innerWidth tell)."""
+    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", headless=False)
+
+    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
+    assert call_kwargs.get("no_viewport") is True
+    assert "viewport" not in call_kwargs
+
+
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
 def test_persistent_context_custom_viewport(_mock_geoip, _mock_bin):
@@ -165,10 +181,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 +274,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 == []
@@ -259,9 +259,8 @@ class TestIssueRegressions:
    def test_add_init_script_with_proxy(self, browser):
        """Issue #27: add_init_script + proxy must not cause ERR_TUNNEL_CONNECTION_FAILED.

-        Patchright bug: add_init_script breaks proxy auth. This test guards
-        against regression if/when the upstream fix lands. Uses context-level
-        proxy to avoid launching a separate browser (event loop conflict).
+        Uses context-level proxy to avoid launching a separate browser
+        (event loop conflict).
        """
        proxy = os.environ.get("CLOAKBROWSER_TEST_PROXY")
        if not proxy:
@@ -276,11 +275,6 @@ class TestIssueRegressions:
            val = page.evaluate("window.__cloaktest")
            assert val == 99, f"init_script value wrong: {val}"
            assert "origin" in body, f"Page didn't load through proxy: {body[:100]}"
-        except Exception as e:
-            err = str(e)
-            if "ERR_TUNNEL_CONNECTION_FAILED" in err:
-                pytest.xfail("Known patchright bug: add_init_script + proxy auth (issue #27)")
-            raise
        finally:
            page.close()
            ctx.close()
@@ -2,12 +2,14 @@

 from __future__ import annotations

+import base64
 import hashlib
 import os
 from pathlib import Path
 from unittest.mock import MagicMock, patch

 import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

 from cloakbrowser.config import (
    CHROMIUM_VERSION,
@@ -22,10 +24,14 @@ from cloakbrowser.download import (
    _check_wrapper_update,
    _download_and_extract,
    _fetch_checksums,
+    _fetch_signed_manifest,
    _get_latest_chromium_version,
    _parse_checksums,
+    _parse_manifest_version,
    _should_check_for_update,
    _verify_checksum,
+    _verify_download_checksum,
+    _verify_signature,
    _write_version_marker,
    check_for_update,
    clear_cache,
@@ -486,7 +492,6 @@ class TestDownloadFallback:
        with patch.dict(os.environ, {
            "CLOAKBROWSER_CACHE_DIR": str(tmp_path),
            "CLOAKBROWSER_DOWNLOAD_URL": "",
-            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
        }):
            urls_called = []

@@ -497,7 +502,10 @@ class TestDownloadFallback:
                # GitHub fallback succeeds
                dest.write_bytes(b"fake")

+            # This test exercises URL fallback, not verification — stub the
+            # (now signature-based, non-bypassable) verify step.
            with patch("cloakbrowser.download._download_file", side_effect=mock_download_file), \
+                 patch("cloakbrowser.download._verify_download_checksum"), \
                 patch("cloakbrowser.download._extract_archive"), \
                 patch("cloakbrowser.download._show_welcome"):
                _download_and_extract()
@@ -548,3 +556,232 @@ class TestDownloadFallback:
                result = _fetch_checksums()

        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Signed-manifest verification (Ed25519). Trust root is the pinned public key,
+# not the same-origin SHA256SUMS — this is what closes M1 (#308).
+# ---------------------------------------------------------------------------
+def _make_key():
+    priv = Ed25519PrivateKey.generate()
+    from cryptography.hazmat.primitives import serialization
+
+    raw = priv.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return priv, base64.b64encode(raw).decode()
+
+
+def _sign(priv, manifest_bytes: bytes) -> bytes:
+    """Return SHA256SUMS.sig content (base64 of the raw signature), as served."""
+    return base64.b64encode(priv.sign(manifest_bytes))
+
+
+class TestSignatureVerification:
+    """_verify_signature: the cryptographic gate over the raw manifest bytes."""
+
+    def test_valid_signature_passes(self):
+        priv, pub_b64 = _make_key()
+        manifest = b"abc  cloakbrowser-linux-x64.tar.gz\n"
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            _verify_signature(manifest, sig)  # no raise
+
+    def test_tampered_manifest_fails(self):
+        priv, pub_b64 = _make_key()
+        manifest = b"abc  cloakbrowser-linux-x64.tar.gz\n"
+        sig = _sign(priv, manifest)
+        tampered = manifest.replace(b"abc", b"xyz")
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            with pytest.raises(RuntimeError, match="signature verification failed"):
+                _verify_signature(tampered, sig)
+
+    def test_wrong_key_fails(self):
+        priv, _ = _make_key()
+        _, other_pub = _make_key()
+        manifest = b"data\n"
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [other_pub]):
+            with pytest.raises(RuntimeError, match="signature verification failed"):
+                _verify_signature(manifest, sig)
+
+    def test_malformed_signature_fails(self):
+        _, pub_b64 = _make_key()
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            with pytest.raises(RuntimeError, match="Malformed"):
+                _verify_signature(b"data\n", b"!!!not base64!!!")
+
+    def test_placeholder_key_is_skipped_not_crashing(self):
+        """An unparseable pinned key (placeholder) must not abort — a real key still validates."""
+        priv, pub_b64 = _make_key()
+        manifest = b"data\n"
+        sig = _sign(priv, manifest)
+        with patch(
+            "cloakbrowser.download.BINARY_SIGNING_PUBKEYS",
+            ["REPLACE_WITH_REAL_ED25519_PUBLIC_KEY_BASE64", pub_b64],
+        ):
+            _verify_signature(manifest, sig)  # no raise
+
+    def test_key_rotation_second_key_accepts(self):
+        """A manifest signed with the new key validates while the old key stays pinned."""
+        old_priv, old_pub = _make_key()
+        new_priv, new_pub = _make_key()
+        manifest = b"rotated\n"
+        sig = _sign(new_priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [old_pub, new_pub]):
+            _verify_signature(manifest, sig)  # no raise
+
+
+class TestVerifyDownloadChecksumSigned:
+    """_verify_download_checksum on the official path: signature + version + hash, fail-closed."""
+
+    def _hash(self, data: bytes) -> str:
+        return hashlib.sha256(data).hexdigest()
+
+    def _manifest(self, body: str, version: str | None = None) -> bytes:
+        """Build a signed-manifest body with the bound version line prepended."""
+        v = version if version is not None else get_chromium_version()
+        return f"version={v}\n{body}".encode()
+
+    def test_valid_manifest_and_hash_passes(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = self._manifest(f"{self._hash(b'the real binary')}  {tarball}\n")
+        sig = _sign(priv, manifest)
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            _verify_download_checksum(archive)  # no raise
+
+    def test_tampered_binary_fails_hash(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"a malicious binary")  # different bytes
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = self._manifest(f"{self._hash(b'the real binary')}  {tarball}\n")
+        sig = _sign(priv, manifest)
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Checksum verification failed"):
+                _verify_download_checksum(archive)
+
+    def test_wrong_version_fails_downgrade(self, tmp_path):
+        """A genuinely-signed manifest for a DIFFERENT version is rejected (downgrade)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        # Manifest declares an old version, but we ask for get_chromium_version().
+        manifest = self._manifest(
+            f"{self._hash(b'the real binary')}  {tarball}\n", version="1.0.0.0"
+        )
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Version mismatch"):
+                _verify_download_checksum(archive)
+
+    def test_missing_version_line_fails(self, tmp_path):
+        """A signed manifest without a version line is rejected (binding required)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = f"{self._hash(b'the real binary')}  {tarball}\n".encode()  # no version=
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Version mismatch"):
+                _verify_download_checksum(archive)
+
+    def test_missing_signed_manifest_fails_closed(self, tmp_path):
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=None):
+            with pytest.raises(RuntimeError, match="signed SHA256SUMS"):
+                _verify_download_checksum(archive)
+
+    def test_manifest_without_entry_fails(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        manifest = self._manifest("deadbeef  some-other-file.tar.gz\n")  # no entry for our tarball
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="no entry for"):
+                _verify_download_checksum(archive)
+
+    def test_custom_url_uses_plain_checksum_and_skip(self, tmp_path):
+        """Self-hosted CLOAKBROWSER_DOWNLOAD_URL keeps the legacy skippable path."""
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        with patch.dict(os.environ, {
+            "CLOAKBROWSER_DOWNLOAD_URL": "https://my-mirror.test",
+            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
+        }):
+            # Signature path must NOT be consulted for a custom mirror.
+            with patch("cloakbrowser.download._fetch_signed_manifest") as mocked:
+                _verify_download_checksum(archive)  # skip honored, no raise
+            mocked.assert_not_called()
+
+
+class TestVersionBinding:
+    """The 'version=<v>' line: read by new wrappers, ignored by old parsers."""
+
+    def test_parse_manifest_version(self):
+        manifest = "version=146.0.7680.177.5\nabc  cloakbrowser-linux-x64.tar.gz\n"
+        assert _parse_manifest_version(manifest) == "146.0.7680.177.5"
+
+    def test_parse_manifest_version_absent(self):
+        assert _parse_manifest_version("abc  cloakbrowser-linux-x64.tar.gz\n") is None
+
+    def test_old_checksum_parser_ignores_version_line(self):
+        """Regression: the version line must not pollute the old hash map."""
+        h = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        manifest = f"version=146.0.7680.177.5\n{h}  cloakbrowser-linux-x64.tar.gz\n"
+        result = _parse_checksums(manifest)
+        assert result == {"cloakbrowser-linux-x64.tar.gz": h}
+
+
+class TestFetchSignedManifest:
+    """_fetch_signed_manifest pairs SHA256SUMS + .sig from the same origin."""
+
+    def test_fetches_both_from_primary(self):
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            resp.raise_for_status = MagicMock()
+            resp.content = b"SIG" if url.endswith(".sig") else b"MANIFEST"
+            return resp
+
+        with patch("cloakbrowser.download.httpx.get", side_effect=mock_get):
+            result = _fetch_signed_manifest("1.2.3.4")
+        assert result == (b"MANIFEST", b"SIG")
+
+    def test_falls_back_to_github_when_primary_missing_sig(self):
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            resp.content = b"SIG" if url.endswith(".sig") else b"MANIFEST"
+            if "cloakbrowser.dev" in url and url.endswith(".sig"):
+                resp.raise_for_status.side_effect = Exception("404")
+            else:
+                resp.raise_for_status = MagicMock()
+            return resp
+
+        with patch("cloakbrowser.download.httpx.get", side_effect=mock_get):
+            result = _fetch_signed_manifest("1.2.3.4")
+        assert result == (b"MANIFEST", b"SIG")
+
+    def test_returns_none_when_all_fail(self):
+        with patch("cloakbrowser.download.httpx.get", side_effect=Exception("network")):
+            assert _fetch_signed_manifest("1.2.3.4") is None
@@ -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
dependabot[bot]andGitHub	ab8f1108fa	chore(deps): bump actions/checkout in the actions group Bumps the actions group with 1 update: [actions/checkout](https://github.com/actions/checkout). Updates `actions/checkout` from 6.0.3 to 7.0.0 - [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/df4cb1c069e1874edd31b4311f1884172cec0e10...9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions ... Signed-off-by: dependabot[bot] <support@github.com>	2026-06-21 20:12:34 +00:00
CloakHQ	660b6bf58c	feat(security): verify binaries with pinned Ed25519 signature on SHA256SUMS Replace the same-origin checksum with a detached Ed25519 signature (SHA256SUMS.sig) verified against a pinned public key before extraction, closing #308: a compromised download mirror can no longer certify a tampered binary. The signed manifest also binds the release version, rejecting a forced downgrade to an older signed build. Verification is mandatory and non-bypassable on the official download path; custom CLOAKBROWSER_DOWNLOAD_URL mirrors keep the legacy skippable checksum. Silent auto-update is preserved for everyone because only a constant public key is pinned, not per-version hashes. Older installed wrappers are unaffected — the version= line is ignored by their checksum parser. Python uses cryptography; JS uses node:crypto. Adds tamper, downgrade, and fail-closed tests in both languages.	2026-06-21 02:42:18 +02:00
CloakHQ	50bf14b3f9	fix(wrapper): track real window geometry on headed launches Headed launches applied a fixed emulated viewport on top of the real browser window, yielding outerWidth < innerWidth (an impossible window). Default headed new_page()/new_context() to no_viewport so the page tracks the real window; headless keeps a deterministic viewport. Covers Python launch/launch_context/launch_persistent_context (+async) and the JS Playwright/Puppeteer wrappers. Explicit viewport still honored.	2026-06-20 22:53:53 +02:00
CloakHQ	d67c21abbe	refactor: remove optional patchright backend Patchright scored identically to plain Playwright on reCAPTCHA v3 (the binary handles stealth at C++ level) while breaking proxy auth and add_init_script (#27). Removed the backend param, CLOAKBROWSER_BACKEND env var, the patchright extra, and the two backend-specific tests. Stock Playwright is now the only backend.	2026-06-20 21:50:22 +02:00
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
CloakHQ	7e626ee7a1	release: v0.3.30 — binary 146.0.7680.177.5, rendering consistency fixes	2026-05-21 05:09:10 +02:00