feat(cloakserve): add connection tracking, configurable data dir, better status endpoint

- Move `import websockets` to top-level (guaranteed by [serve] extra) - Add --data-dir flag with smart default (Docker → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve) - Store launch params (tz/locale/proxy) on ChromeProcess for conflict logging - Enhance GET / to return per-process detail (pid, port, seed, connections, config) - Add connection refcounting in WS handlers for status visibility - Add first-launch-wins note to README - Add tests for data-dir, Docker detection, and connection tracking
feat: rewrite cloakserve as CDP multiplexer with per-connection fingerprint seeds
2026-06-23 11:41:46 +02:00 · 2026-04-05 22:41:33 +02:00 · 2026-04-05 22:30:18 +02:00 · 2026-04-05 22:26:14 +02:00 · 2026-04-02 01:32:08 +02:00 · 2026-03-30 20:46:16 +02:00
57 changed files with 2578 additions and 402 deletions
@@ -0,0 +1 @@
+ko_fi: cloakhq
@@ -0,0 +1,29 @@
+---
+name: Bug Report
+about: Report a bug or detection issue
+labels: bug
+---
+
+Description: <!-- What happened? What did you expect? -->
+
+CloakBrowser version: <!-- pip show cloakbrowser / npm list cloakbrowser -->
+
+Wrapper: <!-- Python or JavaScript -->
+
+Environment: <!-- OS, Docker y/n, base image, architecture -->
+
+Launch options:
+
+
+Tested with a different IP or proxy? <!-- Yes (same result) / Yes (works with different IP) / No -->
+
+Works outside Docker / on host machine? <!-- Yes / No / Not using Docker -->
+
+Steps to reproduce:
+
+
+Error output / screenshots:
+
+Dockerfile (if applicable):
+
+Additional notes:
@@ -0,0 +1 @@
+blank_issues_enabled: true
@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
@@ -21,7 +21,7 @@ jobs:
          GH_TOKEN: ${{ github.token }}

      - name: Attest build provenance
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32  # v4.1.0
        with:
          subject-path: |
            cloakbrowser-*.tar.gz
@@ -10,8 +10,8 @@ jobs:
  python:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
      - name: Install dependencies
@@ -22,8 +22,8 @@ jobs:
  javascript:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
        with:
          node-version: 20
      - name: Install and build
@@ -24,15 +24,15 @@ jobs:
  test:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
      - name: Python tests
        run: |
          pip install -e ".[dev]" pytest pytest-asyncio
          pytest tests/ -v -m "not slow"
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
        with:
          node-version: 22
      - name: JavaScript tests
@@ -42,8 +42,8 @@ jobs:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
      - name: Check tag matches package versions
@@ -62,8 +62,8 @@ jobs:
    permissions:
      id-token: write  # OIDC trusted publishing — no PYPI_TOKEN needed
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
      - name: Build
@@ -71,7 +71,7 @@ jobs:
          pip install build
          python -m build
      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1

  publish-npm:
    needs: [test, validate-version]
@@ -80,11 +80,13 @@ jobs:
    permissions:
      id-token: write  # OIDC trusted publishing + provenance — no NPM_TOKEN needed
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
        with:
          node-version: 22
          registry-url: 'https://registry.npmjs.org'
+      - name: Upgrade npm
+        run: npm install -g npm@latest
      - name: Build
        run: cd js && npm ci && npm run build
      - name: Publish to npm
@@ -100,32 +102,34 @@ jobs:
      attestations: write
      packages: write
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      - 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-buildx-action@v3
-      - uses: docker/login-action@v3
+      - 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
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}
      - name: Build and push
        id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
        with:
          context: .
+          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            cloakhq/cloakbrowser:${{ env.VERSION }}
            cloakhq/cloakbrowser:latest
          provenance: true
          sbom: true
-      - uses: sigstore/cosign-installer@v3
+      - uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003  # v4.1.1
      - name: Sign image
        run: cosign sign --yes cloakhq/cloakbrowser@${{ steps.build.outputs.digest }}
      - name: Attest build provenance
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32  # v4.1.0
        with:
          subject-name: index.docker.io/cloakhq/cloakbrowser
          subject-digest: ${{ steps.build.outputs.digest }}
@@ -56,9 +56,14 @@ test-infra/
 # Website (deployed separately)
 site/

+# Browser profile manager (deployed separately)
+manager/
+
 # Release scripts
 publish.sh
 deploy.sh
 .env
 debug
 publish-docker.sh
+captures
+20[0-9][0-9]-[0-9][0-9]-[0-9][0-9]-*.txt
@@ -6,6 +6,66 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi

 ---

+## [0.3.19] — 2026-03-30
+
+- **[binary]** Upgrade Linux x64 build to 145.0.7632.159.8 — 42 source-level C++ patches (up from 33)
+- **[binary]** 9 new fingerprint patches covering additional browser APIs and cross-platform consistency
+- **[binary]** New `--fingerprint-noise` flag — disable noise injection while keeping deterministic fingerprint seed active
+- **[binary]** Improved fingerprint noise reliability and determinism across all patched APIs
+- **[binary]** Expanded platform-aware fingerprint spoofing for more realistic cross-platform profiles
+- **[binary]** Font rendering and detection accuracy improvements for Windows profiles
+- **[binary]** Removed experimental patches that caused compatibility issues with certain anti-bot systems
+- **[binary]** Docker/VNC environment compatibility improvements
+- **[wrapper]** Fix Playwright cleanup — `pw.stop()` now runs even if `browser.close()` raises or is cancelled (fixes #60, thanks [@dgtlmoon](https://github.com/dgtlmoon))
+- **[meta]** Pin GitHub Actions to commit SHAs, add Dependabot for automated dependency updates
+
+## [0.3.18] — 2026-03-15
+
+- **[wrapper]** Fix welcome banner printing to stdout — now writes to stderr so it won't corrupt JSON output in programmatic usage (fixes #59)
+- **[wrapper]** Fix `cloakserve` Docker WebGL by adding `--ignore-gpu-blocklist` flag
+- **[docs]** Add Crawlee integration example
+- **[meta]** Add GitHub issue template for bug reports
+
+## [0.3.17] — 2026-03-15
+
+- **[binary]** Windows x64 build upgraded to 145.0.7632.159.7 — 33 source-level C++ patches, matching Linux
+- **[wrapper]** Auto-inject GPU blocklist bypass for headed mode and Windows — fixes WebGL/WebGPU on software GPUs in Docker/VNC (fixes #56)
+- **[wrapper]** Add 8 framework integration examples (Scrapy, Crawlee, BrowserBase, etc.) and README integrations section
+
+## [0.3.16] — 2026-03-14
+
+- **[binary]** Linux arm64 build available — Raspberry Pi, AWS Graviton, Oracle Ampere now supported
+- **[wrapper]** Add donate link to first-launch welcome banner
+
+## [0.3.15] — 2026-03-13
+
+- **[binary]** Upgrade Linux build to 145.0.7632.159.7 — 33 source-level C++ patches
+- **[binary]** StorageBuckets API quota normalization — closes the last storage-based incognito detection vector
+- **[wrapper]** Fix non-ASCII character support in humanized typing — Cyrillic, CJK, and emoji now type correctly (thanks [@evelaa123](https://github.com/evelaa123))
+
+## [0.3.14] — 2026-03-12
+
+- **[binary]** Upgrade Linux build to 145.0.7632.159.6 — fix persistent context detection by FingerprintJS
+- **[binary]** Storage quota normalization for persistent context profiles
+- **[binary]** Fix outerHeight calculation for non-incognito contexts
+- **[wrapper]** Add CLI for binary management — `python -m cloakbrowser install` / `npx cloakbrowser install` with visible download progress (closes #43)
+
+## [0.3.13] — 2026-03-10
+
+- **[wrapper]** Suppress Playwright's `--enable-unsafe-swiftshader` default arg — eliminates SwiftShader software renderer detection signal, letting the binary's GPU spoofing work cleanly
+- **[binary]** Upgrade Linux build to 145.0.7632.159.5 — fix WebGPU adapter limits and features for NVIDIA profiles
+
+## [0.3.12] — 2026-03-10
+
+- **[binary]** Upgrade Linux build to 145.0.7632.159.4
+- **[binary]** Native locale spoofing — new C++ patch replaces detectable CDP-level locale emulation
+- **[binary]** WebGPU fingerprint hardening — spoof adapter features, limits, device ID, and subgroup sizes for cross-API consistency
+- **[binary]** Restore WebGPU blocklist bypass auto-injection (safe now with full adapter spoofing)
+- **[binary]** Fix WebGL renderer suffix — remove driver version string flagged by BrowserLeaks
+- **[wrapper]** Use binary flags for timezone/locale instead of CDP emulation — eliminates a detection vector
+- **[wrapper]** Support bare proxy format (`user:pass@host:port`) without scheme prefix
+- **[wrapper]** Use ANGLE-wrapped GPU strings in default stealth args for realistic WebGL fingerprint
+
 ## [0.3.11] — 2026-03-08

 - **[wrapper]** `humanize=True` — human-like mouse (Bézier curves, overshoot), keyboard (per-character timing, thinking pauses), scroll (accelerate/cruise/decelerate), and click behavior. Two presets: `default` and `careful`. Works in Python and JS. (thanks [@evelaa123](https://github.com/evelaa123))
@@ -20,7 +20,7 @@ WORKDIR /app
 # Python wrapper
 COPY pyproject.toml README.md LICENSE BINARY-LICENSE.md CHANGELOG.md ./
 COPY cloakbrowser/ cloakbrowser/
-RUN pip install --no-cache-dir .
+RUN pip install --no-cache-dir ".[serve]"

 # JS wrapper
 COPY js/ js/
@@ -11,6 +11,11 @@
 <a href="https://github.com/CloakHQ/CloakBrowser"><img src="https://img.shields.io/github/stars/cloakhq/cloakbrowser" alt="Stars"></a>
 <a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pepy/dt/cloakbrowser?label=pypi&logo=pypi&logoColor=white" alt="PyPI Downloads"></a>
 <a href="https://www.npmjs.com/package/cloakbrowser"><img src="https://img.shields.io/npm/dt/cloakbrowser?label=npm&logo=npm&logoColor=white" alt="npm Downloads"></a>
+<a href="https://hub.docker.com/r/cloakhq/cloakbrowser"><img src="https://img.shields.io/docker/pulls/cloakhq/cloakbrowser?label=docker&logo=docker&logoColor=white" alt="Docker Pulls"></a>
+</p>
+
+<p align="center">
+<a href="https://ko-fi.com/cloakhq"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support on Ko-fi"></a>
 </p>

 <br>
@@ -35,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>

- **31 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, automation signals, CDP input behavior
+- **42 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, 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
@@ -109,16 +114,29 @@ page.goto("https://example.com")

 > ⭐ **Star** to show support — **[Watch releases](https://github.com/CloakHQ/CloakBrowser/subscription)** to get notified when new builds drop.

-## Latest: v0.3.11 (Chromium 145.0.7632.159.2)
+## Browser Profile Manager
+
+Self-hosted alternative to Multilogin, GoLogin, and AdsPower. Create browser profiles with unique fingerprints, proxies, and persistent sessions. Launch and interact with them in your browser via noVNC.
+
+```bash
+docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager
+```
+
+Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **Launch**. Done.
+
+→ **[CloakBrowser Manager](https://github.com/CloakHQ/CloakBrowser-Manager)** — free, open source (MIT)
+
+---
+
+## Latest: v0.3.19 (Chromium 145.0.7632.159.8)

 - **`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. Two presets: `default` and `careful`
- **CDP input behavior mimicking** — input events sent via CDP now produce the same signals as real user interactions. 5 new source-level patches covering pointer, keyboard, and mouse behavior
- **`cloakserve` CDP server** — no longer requires socat. Chrome binds directly to `0.0.0.0:9222` via native flag support
- **31 fingerprint patches** (Linux x64) — 5 new patches since v0.3.10, plus GPU fingerprint accuracy fixes for NVIDIA and Apple Silicon profiles
- **All 4 platforms** — Linux x64, macOS arm64, macOS x64, and Windows x64 all on Chromium 145
+- **CDP input behavior mimicking** — input events sent via CDP now produce the same signals as real user interactions. 4 source-level patches covering pointer, keyboard, and mouse behavior
+- **Native locale spoofing** — new C++ patch replaces detectable CDP-level locale emulation
+- **WebGPU fingerprint hardening** — adapter features, limits, and device ID spoofed for cross-API consistency
+- **42 fingerprint patches** (Linux x64) — all 4 platforms on Chromium 145
 - **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
- **Playwright + Puppeteer from one package** — `import from 'cloakbrowser'` or `import from 'cloakbrowser/puppeteer'`. Same binary, your choice of API
 - **Persistent profiles** — `launch_persistent_context()` keeps cookies and localStorage across sessions, bypasses incognito detection

 See the full [CHANGELOG.md](CHANGELOG.md) for details.
@@ -129,7 +147,7 @@ See the full [CHANGELOG.md](CHANGELOG.md) for details.
 - **CloakBrowser patches Chromium source code** — fingerprints are modified at the C++ level, compiled into the binary. Detection sites see a real browser because it *is* a real browser.
 - **Source-level stealth** — C++ patches handle fingerprints (GPU, screen, UA, hardware reporting) at the binary level. No JavaScript injection, no config-level hacks. Most stealth tools only patch at the surface.
 - **Same behavior everywhere** — works identically local, in Docker, and on VPS. No environment-specific patches or config needed.
- **Works with any browser automation framework** — tested and passing stealth checks with Playwright, Puppeteer, Selenium, undetected-chromedriver, browser-use, Crawl4AI, and agent-browser. Just point any Chromium-based framework at the binary path.
+- **Works with AI agents and automation frameworks** — drop-in stealth for browser-use, Crawl4AI, Scrapling, Stagehand, LangChain, Selenium, and more. See [integrations](#framework-integrations).

 CloakBrowser doesn't solve CAPTCHAs — it prevents them from appearing. No CAPTCHA-solving services, no proxy rotation built in — bring your own proxies, use the Playwright API you already know.

@@ -203,7 +221,7 @@ 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 31 source-level patches covering canvas, WebGL, audio, fonts, GPU, screen properties, hardware reporting, automation signal removal, and CDP input behavior mimicking.
+The binary includes 42 source-level patches covering canvas, WebGL, audio, fonts, GPU, screen properties, 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.

@@ -231,7 +249,7 @@ browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com",
 # With extra Chrome args
 browser = launch(args=["--disable-gpu"])

-# With timezone and locale (sets both binary flags and Playwright context)
+# With timezone and locale (sets binary flags — no detectable CDP emulation)
 browser = launch(timezone="America/New_York", locale="en-US")

 # Auto-detect timezone/locale from proxy IP (requires: pip install cloakbrowser[geoip])
@@ -288,7 +306,7 @@ context.close()

 ### `launch_persistent_context()`

-Same as `launch_context()`, but with a persistent user profile. Cookies, localStorage, and cache persist across sessions. Also avoids incognito detection by services like BrowserScan.
+Same as `launch_context()`, but with a persistent user profile. Cookies, localStorage, and cache persist across sessions.

 Use this when you need to:
 - **Stay logged in** across runs (cookies/sessions survive restarts)
@@ -313,6 +331,28 @@ Supports all the same options as `launch_context()`: `proxy`, `user_agent`, `vie

 Async version: `launch_persistent_context_async()`.

+**Storage quota and detection tradeoff:** By default, the binary normalizes storage quota to pass FingerprintJS, which blocks persistent contexts that report non-incognito quota values. This means detection services that penalize incognito mode (like BrowserScan's `notPrivate` check, -10 points) will still flag it. If your target site penalizes incognito but doesn't use FingerprintJS, set a higher quota to appear as a regular profile:
+
+```python
+ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quota=5000"])
+```
+
+| Quota setting | FingerprintJS | BrowserScan `notPrivate` |
+|---|---|---|
+| Default (auto, ~500MB) | PASS | -10 (flagged as incognito) |
+| `--fingerprint-storage-quota=5000` | May trigger detection | PASS (appears non-incognito) |
+
+### CLI
+
+Pre-download the binary or check installation status from the command line:
+
+```bash
+python -m cloakbrowser install      # Download binary with progress output
+python -m cloakbrowser info         # Show version, path, platform
+python -m cloakbrowser update       # Check for and download newer binary
+python -m cloakbrowser clear-cache  # Remove cached binaries
+```
+
 ### Utility Functions

 ```python
@@ -461,6 +501,8 @@ const browser = await launch({

 Access the original un-patched Playwright page at `page._original` if you need raw speed for a specific call.

+> **Note:** Always use `page.click(selector)`, `page.type(selector, text)`, `page.hover(selector)`, or `page.locator(selector).*` — these go through the full humanize pipeline. Avoid `page.query_selector()` — `ElementHandle` objects bypass all patches, so mouse movement teleports, keyboard events fire without timing, and scroll has no human curve.
+
 > Contributed by [@evelaa123](https://github.com/evelaa123) — full Playwright API coverage.

 ## Configuration
@@ -527,8 +569,11 @@ Supported by the binary but **not set by default** — pass via `args` to custom
 | `--fingerprint-platform-version` | Client Hints platform version |
 | `--fingerprint-location` | Geolocation coordinates |
 | `--fingerprint-timezone` | Timezone (e.g. `America/New_York`) |
+| `--fingerprint-locale` | Locale (e.g. `en-US`) |
+| `--fingerprint-storage-quota` | Override storage quota in MB — affects `storage.estimate()`, `storageBuckets`, and legacy webkit APIs. Auto-normalized when `--fingerprint` is set |
 | `--fingerprint-taskbar-height` | Override taskbar height (binary defaults: Win=48, Mac=95, Linux=0) |
 | `--fingerprint-fonts-dir` | Path to cross-platform font directory |
+| `--fingerprint-noise=false` | Disable noise injection (canvas, WebGL, audio, client rects) while keeping the deterministic fingerprint seed active |
 | `--enable-blink-features=FakeShadowRoot` | Access closed shadow DOM elements |

 > **Note:** All stealth tests were verified with the default fingerprint config above. Changing these flags may affect detection results — test your configuration before using in production.
@@ -568,14 +613,44 @@ browser = launch(args=[
 - [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer launch and load
 - [`stealth-test.ts`](js/examples/stealth-test.ts) — Run against 6 detection sites

+### Framework Integrations
+
+CloakBrowser works with any framework that uses Playwright or Chromium:
+
+```python
+# Option 1: Framework launches our binary directly (Selenium, Stagehand, UC)
+from cloakbrowser.download import ensure_binary
+from cloakbrowser.config import get_default_stealth_args
+binary_path = ensure_binary()          # auto-downloads if needed
+stealth_args = get_default_stealth_args()  # all fingerprint flags
+
+# Option 2: CloakBrowser launches first, framework connects via CDP (browser-use, Crawl4AI, Scrapling)
+from cloakbrowser import launch_async
+browser = await launch_async(args=["--remote-debugging-port=9242"])
+# Connect your framework to http://127.0.0.1:9242 — all stealth flags are set
+```
+
+| Framework | Stars | Language | Example |
+|-----------|-------|----------|---------|
+| [browser-use](https://github.com/browser-use/browser-use) | 70K | Python | [`browser_use_example.py`](examples/integrations/browser_use_example.py) |
+| [Crawl4AI](https://github.com/unclecode/crawl4ai) | 58K | Python | [`crawl4ai_example.py`](examples/integrations/crawl4ai_example.py) |
+| [Crawlee](https://github.com/apify/crawlee-python) | 8.6K | Python | [`crawlee_example.py`](examples/integrations/crawlee_example.py) |
+| [Scrapling](https://github.com/D4Vinci/Scrapling) | 21K | Python | [`scrapling_example.py`](examples/integrations/scrapling_example.py) |
+| [Stagehand](https://github.com/browserbase/stagehand) | 21K | TypeScript | [`stagehand.ts`](js/examples/stagehand.ts) |
+| [LangChain](https://github.com/langchain-ai/langchain) | 100K+ | Python | [`langchain_loader.py`](examples/integrations/langchain_loader.py) |
+| [Selenium](https://github.com/SeleniumHQ/selenium) | — | Python | [`selenium_example.py`](examples/integrations/selenium_example.py) |
+| [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) | 12K | Python | [`undetected_chromedriver.py`](examples/integrations/undetected_chromedriver.py) |
+| [agent-browser](https://github.com/nichochar/agent-browser) | — | Shell | [`agent_browser.sh`](examples/integrations/agent_browser.sh) |
+
 ## Platforms

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

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

@@ -679,7 +754,28 @@ services:
      start_period: 10s
 ```

-Run multiple instances with different fingerprint seeds on different ports — each gets unique canvas noise, client rects, and other browser signals. Pass `--fingerprint=<seed>` in the command (e.g., `cloakserve --fingerprint=12345`).
+**Per-connection fingerprint seeds** — run multiple browser identities from a single container. Each unique seed spawns a separate Chrome process with its own fingerprint:
+
+```python
+# Each seed gets unique canvas noise, client rects, and other browser signals
+b1 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=11111")
+b2 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=22222")
+
+# Full identity control via query params
+b3 = pw.chromium.connect_over_cdp(
+    "http://localhost:9222?fingerprint=33333"
+    "&timezone=Asia/Tokyo&locale=ja-JP&platform=macos"
+    "&hardware-concurrency=4&device-memory=8"
+)
+
+# Auto-detect timezone/locale from proxy exit IP
+b4 = pw.chromium.connect_over_cdp(
+    "http://localhost:9222?fingerprint=44444"
+    "&proxy=http://proxy:8080&geoip=true"
+)
+```
+
+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).

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

@@ -705,6 +801,15 @@ COPY your_script.py /app/
 CMD ["python", "your_script.py"]
 ```

+**Building your own image from pip** — use `python -m cloakbrowser install` to download the binary during build with visible progress:
+
+```dockerfile
+FROM python:3.12-slim
+RUN pip install cloakbrowser && python -m cloakbrowser install
+COPY your_script.py /app/
+CMD ["python", "/app/your_script.py"]
+```
+
 **Building from source** — a [`Dockerfile`](Dockerfile) is also included if you prefer to build your own image:

 ```bash
@@ -717,7 +822,9 @@ CloakBrowser works identically local, in Docker, and on VPS. No environment-spec

 ## Troubleshooting

-**Still getting blocked on aggressive sites (DataDome, Turnstile)?**
+---
+
+### Still getting blocked on aggressive sites (DataDome, Turnstile)?

 Some sites detect headless mode even with our C++ patches. Run in **headed mode** with a virtual display:

@@ -742,7 +849,9 @@ browser.close()

 This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combined with a residential proxy, this passes even the most aggressive detection services. Datacenter IPs are often flagged by IP reputation regardless of browser fingerprint — a residential proxy makes the difference.

-**Sites challenge fresh sessions but work after first visit**
+---
+
+### Sites challenge fresh sessions but work after first visit

 Some sites challenge first-time visitors with no cookies over HTTP/2. This affects all Chromium browsers, not just CloakBrowser. Use a persistent profile to warm up cookies once, then reuse across sessions:

@@ -776,7 +885,10 @@ ctx = await launchPersistentContext({ userDataDir: './profile' });

 For stateless/ephemeral use cases, `launch(args=["--disable-http2"])` forces HTTP/1.1 which bypasses the check. Only use this flag for sites that require it — most work fine with HTTP/2.

-**Something not working? Make sure you're on the latest version**
+---
+
+### Something not working? Make sure you're on the latest version
+
 Older versions may use outdated stealth args or download an older binary:
 ```bash
 pip install -U cloakbrowser    # Python
@@ -784,64 +896,68 @@ npm install cloakbrowser@latest # JavaScript
 docker pull cloakhq/cloakbrowser:latest  # Docker
 ```

-**Binary download fails / timeout**
+---
+
+### Binary download fails / timeout
+
 Set a custom download URL or use a local binary:
 ```bash
 export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
 ```

-**New update broke something? Roll back to the previous version**
-When auto-update downloads a newer binary, the previous version stays in `~/.cloakbrowser/`. Point `CLOAKBROWSER_BINARY_PATH` to the older cached binary:
+---
+
+### New update broke something? Roll back to the previous version
+
+Install a specific wrapper version to downgrade both the wrapper and the binary it downloads:
 ```bash
-# Linux
-export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.159.2/chrome
-
-# macOS
-export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109.2/Chromium.app/Contents/MacOS/Chromium
-
-# Windows
-set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.109.2\chrome.exe
+pip install cloakbrowser==0.3.11              # Python
+npm install cloakbrowser@0.3.11               # JavaScript
+docker pull cloakhq/cloakbrowser:0.3.11       # Docker
 ```
+Each wrapper version pins its own binary version, so downgrading the wrapper automatically gets you the matching binary on next launch.
+
+---
+
+### macOS: "App is damaged" or Gatekeeper blocks launch

-**macOS: "App is damaged" or Gatekeeper blocks launch**
 The binary is ad-hoc signed. macOS quarantines downloaded files. Run once to clear it:
 ```bash
 xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app
 ```

-**"playwright install" vs CloakBrowser binary**
+---
+
+### "playwright install" vs CloakBrowser binary
+
 You do NOT need `playwright install chromium`. CloakBrowser downloads its own binary. You only need Playwright's system deps:
 ```bash
 playwright install-deps chromium
 ```

-**macOS: Blocked on some sites that pass on Linux**
+---
+
+### macOS: Blocked on some sites that pass on Linux

 The macOS fingerprint profile has known inconsistencies that aggressive bot detection catches. If a site blocks you on macOS but works on Linux, switch to a Windows fingerprint profile by passing `stealth_args=False` and manually setting `--fingerprint-platform=windows` with matching GPU flags (see [Fingerprint Management](#fingerprint-management) for the full flag list).

-**Site detects incognito / private browsing mode**
+---

-By default, `launch()` opens an incognito context. Some sites (like BrowserScan) detect this. Use `launch_persistent_context()` instead — it runs with a real user profile, so incognito detection passes:
+### Site detects incognito / private browsing mode
+
+By default, `launch()` opens an incognito context. Some sites penalize this. Use `launch_persistent_context()` to get a real profile with cookie persistence:

 ```python
 from cloakbrowser import launch_persistent_context

 ctx = launch_persistent_context("./my-profile", headless=False)
-page = ctx.new_page()
 ```

-```javascript
-import { launchPersistentContext } from 'cloakbrowser';
+If the site still flags incognito, raise the storage quota to appear as a regular browsing session. See the [storage quota tradeoff](#launch_persistent_context) for details on how this affects different detection services.

-const ctx = await launchPersistentContext({
-  userDataDir: './my-profile',
-  headless: false,
-});
-```
+---

-This also gives you cookie and localStorage persistence across sessions.
-
-**reCAPTCHA v3 scores are low (0.1–0.3)**
+### reCAPTCHA v3 scores are low (0.1–0.3)

 Avoid `page.wait_for_timeout()` — it sends CDP protocol commands that reCAPTCHA detects. Use native sleep instead:

@@ -893,9 +1009,9 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` to `launch()`.

 | Feature | Status |
 |---------|--------|
-| Linux x64 — Chromium 145 (26 patches) | ✅ Released |
+| Linux x64 — Chromium 145 (42 patches) | ✅ Released |
 | macOS arm64/x64 — Chromium 145 (26 patches) | ✅ Released |
-| Windows x64 — Chromium 145 (26 patches) | ✅ Released |
+| Windows x64 — Chromium 145 (33 patches) | ✅ Released |
 | JavaScript/Puppeteer + Playwright support | ✅ Released |
 | Fingerprint rotation per session | ✅ Released |
 | Built-in proxy rotation | 📋 Planned |
@@ -907,19 +1023,26 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` to `launch()`.
 - 🐛 **Bug reports & feature requests** — [GitHub Issues](https://github.com/CloakHQ/CloakBrowser/issues)
 - 📦 **PyPI** — [pypi.org/project/cloakbrowser](https://pypi.org/project/cloakbrowser/)
 - 📦 **npm** — [npmjs.com/package/cloakbrowser](https://www.npmjs.com/package/cloakbrowser)
+- ☕ **Support** — [ko-fi.com/cloakhq](https://ko-fi.com/cloakhq)
 - 📧 **Contact** — cloakhq@pm.me

 ## Security

-All binary releases are GPG-signed and include GitHub artifact attestations for supply chain verification.
+All releases are signed for supply chain verification.

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

-# Verify binary attestation
+# Verify GitHub binary attestation (Sigstore)
 gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser
+
+# Verify Docker image signature (Cosign/Sigstore)
+cosign verify \
+  --certificate-identity-regexp "https://github.com/CloakHQ/CloakBrowser/" \
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+  cloakhq/cloakbrowser:latest
 ```

 ## License
@@ -1,31 +1,54 @@
 #!/usr/bin/env python3
-"""Launch stealth Chromium as a CDP server for remote connections.
+"""CDP multiplexer — per-connection fingerprint seeds for stealth Chromium.
+
+Spawns a separate Chrome process per unique fingerprint seed, routing CDP
+connections through a single port. Each seed gets its own browser identity.

 Usage:
-    cloakserve                          # headless on port 9222
-    cloakserve --headless=false         # headed (uses Xvfb in Docker)
-    cloakserve --proxy-server=host:port # with proxy
+    cloakserve                                      # default, backward compat
+    cloakserve --port=9222                           # custom port

-Connect from host:
-    playwright.chromium.connect_over_cdp("http://localhost:9222")
+Client:
+    browser = pw.chromium.connect_over_cdp("http://host:9222?fingerprint=12345")
+    browser = pw.chromium.connect_over_cdp(
+        "http://host:9222?fingerprint=12345&timezone=America/New_York&locale=en-US"
+    )
 """
-import signal
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import random
+import shutil
+import socket
 import subprocess
 import sys
 import time
+from dataclasses import dataclass
+from urllib.parse import parse_qs

-from cloakbrowser.config import get_default_stealth_args
+from pathlib import Path
+
+import aiohttp
+import websockets
+from aiohttp import web
+
+from cloakbrowser.browser import build_args, maybe_resolve_geoip
 from cloakbrowser.download import ensure_binary

-PORT = 9222
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger("cloakserve")

-binary = ensure_binary()
-
-chrome_args = [
-    binary,
-    f"--remote-debugging-port={PORT}",
-    "--remote-debugging-address=0.0.0.0",
-    # Sane defaults for running Chrome directly (outside Playwright)
+# Args for running Chrome directly (outside Playwright).
+# Playwright normally adds its own version of these.
+BASE_CHROME_ARGS = [
    "--no-first-run",
    "--no-default-browser-check",
    "--disable-dev-shm-usage",
@@ -33,21 +56,574 @@ chrome_args = [
    "--disable-popup-blocking",
    "--disable-background-networking",
    "--metrics-recording-only",
-] + get_default_stealth_args() + sys.argv[1:]
+    "--ignore-gpu-blocklist",
+]

-chrome = subprocess.Popen(chrome_args)
-
-time.sleep(2)
-
-print(f"CloakBrowser CDP server ready on port {PORT}", flush=True)
+BASE_CDP_PORT = 5100


-def cleanup(sig, frame):
-    chrome.terminate()
-    sys.exit(0)
+# ---------------------------------------------------------------------------
+# ChromeProcess — one running Chrome instance
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ChromeProcess:
+    seed: str
+    process: subprocess.Popen
+    cdp_port: int
+    user_data_dir: str
+    timezone: str | None = None
+    locale: str | None = None
+    proxy: str | None = None


-signal.signal(signal.SIGTERM, cleanup)
-signal.signal(signal.SIGINT, cleanup)
+# ---------------------------------------------------------------------------
+# ChromePool — manages multiple Chrome processes keyed by seed
+# ---------------------------------------------------------------------------

-chrome.wait()
+class ChromePool:
+    def __init__(
+        self,
+        binary: str,
+        global_args: list[str],
+        headless: bool,
+        data_dir: str = "/tmp/cloakserve",
+    ):
+        self._binary = binary
+        self._global_args = global_args
+        self._headless = headless
+        self._data_dir = data_dir
+        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] = {}
+
+    def _get_lock(self, seed: str) -> asyncio.Lock:
+        if seed not in self._locks:
+            self._locks[seed] = asyncio.Lock()
+        return self._locks[seed]
+
+    def _allocate_port(self) -> int:
+        """Find a free port starting from _next_port."""
+        for _ in range(100):
+            port = self._next_port
+            self._next_port += 1
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                    s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+        raise RuntimeError("No free ports available for Chrome CDP")
+
+    def connect(self, seed_key: str) -> None:
+        """Increment connection refcount for a seed."""
+        self._connections[seed_key] = self._connections.get(seed_key, 0) + 1
+
+    def disconnect(self, seed_key: str) -> None:
+        """Decrement connection refcount for a seed."""
+        count = self._connections.get(seed_key, 0) - 1
+        if count <= 0:
+            self._connections.pop(seed_key, None)
+        else:
+            self._connections[seed_key] = count
+
+    async def get_or_launch(
+        self,
+        seed: str | None,
+        extra_args: list[str] | None = None,
+        timezone: str | None = None,
+        locale: str | None = None,
+        proxy: str | None = None,
+        geoip: bool = False,
+    ) -> ChromeProcess:
+        """Get existing or launch new Chrome process for a seed."""
+        # No seed = default shared process
+        if seed is None:
+            seed_key = "__default__"
+            actual_seed = str(random.randint(10000, 99999))
+        else:
+            seed_key = seed
+            actual_seed = seed
+
+        lock = self._get_lock(seed_key)
+        async with lock:
+            # Check if already running (including default fast-path)
+            if seed_key in self._processes:
+                proc = self._processes[seed_key]
+                if proc.process.poll() is None:
+                    if any([extra_args, timezone, locale, proxy, geoip]):
+                        logger.warning(
+                            "Seed %s already running (port %d, tz=%s, locale=%s, proxy=%s) — "
+                            "ignoring new params (first-launch wins)",
+                            seed_key, proc.cdp_port,
+                            proc.timezone, proc.locale, proc.proxy,
+                        )
+                    return proc
+                # Dead — clean up
+                await self._cleanup_process(seed_key)
+
+            # Resolve geoip if requested
+            if geoip and proxy:
+                timezone, locale = maybe_resolve_geoip(True, proxy, timezone, locale)
+
+            # Build Chrome args via shared logic
+            fp_extra = [f"--fingerprint={actual_seed}"]
+            if extra_args:
+                fp_extra.extend(extra_args)
+            if proxy:
+                fp_extra.append(f"--proxy-server={proxy}")
+
+            chrome_args = build_args(
+                stealth_args=True,
+                extra_args=fp_extra,
+                timezone=timezone,
+                locale=locale,
+                headless=self._headless,
+            )
+
+            # Allocate port and user data dir
+            port = self._allocate_port()
+            user_data_dir = os.path.join(self._data_dir, seed_key)
+            os.makedirs(user_data_dir, exist_ok=True)
+
+            full_args = (
+                [self._binary]
+                + BASE_CHROME_ARGS
+                + chrome_args
+                + self._global_args
+                + [
+                    f"--remote-debugging-port={port}",
+                    "--remote-debugging-address=127.0.0.1",
+                    f"--user-data-dir={user_data_dir}",
+                ]
+            )
+
+            logger.info("Launching Chrome (seed=%s, port=%d)", actual_seed, port)
+            process = subprocess.Popen(
+                full_args,
+                stdout=subprocess.DEVNULL,
+            )
+
+            # Wait for CDP to be ready
+            if not await self._wait_for_cdp(port):
+                process.kill()
+                await asyncio.to_thread(process.wait, timeout=5)
+                await asyncio.to_thread(shutil.rmtree, user_data_dir, True)
+                raise web.HTTPBadGateway(
+                    text=json.dumps({"error": "Chrome failed to start"}),
+                    content_type="application/json",
+                )
+
+            cp = ChromeProcess(
+                seed=actual_seed,
+                process=process,
+                cdp_port=port,
+                user_data_dir=user_data_dir,
+                timezone=timezone,
+                locale=locale,
+                proxy=proxy,
+            )
+            self._processes[seed_key] = cp
+
+            if seed is None:
+                self._default = cp
+
+            logger.info("Chrome ready (seed=%s, port=%d, pid=%d)", actual_seed, port, process.pid)
+            return cp
+
+    async def _cleanup_process(self, key: str) -> None:
+        """Terminate a Chrome process and clean up."""
+        proc = self._processes.pop(key, None)
+        if not proc:
+            return
+        if proc.process.poll() is None:
+            proc.process.terminate()
+            try:
+                await asyncio.to_thread(proc.process.wait, timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.process.kill()
+        # Clean up user data dir (can be slow for large profiles)
+        await asyncio.to_thread(shutil.rmtree, proc.user_data_dir, True)
+        if self._default is proc:
+            self._default = None
+        self._locks.pop(key, None)
+        self._connections.pop(key, None)
+
+    async def shutdown(self) -> None:
+        """Terminate all Chrome processes."""
+        for key in list(self._processes.keys()):
+            await self._cleanup_process(key)
+        logger.info("All Chrome processes terminated")
+
+    @staticmethod
+    async def _wait_for_cdp(port: int, timeout: float = 10.0) -> bool:
+        """Poll Chrome's /json/version until ready."""
+        deadline = time.monotonic() + timeout
+        delay = 0.1
+        session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=1)
+        )
+        try:
+            while time.monotonic() < deadline:
+                try:
+                    async with session.get(
+                        f"http://127.0.0.1:{port}/json/version"
+                    ) as resp:
+                        if resp.status == 200:
+                            return True
+                except Exception:
+                    pass
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, 1.0)
+            return False
+        finally:
+            await session.close()
+
+
+# ---------------------------------------------------------------------------
+# Query param parsing
+# ---------------------------------------------------------------------------
+
+# Params that need special handling (not simple --fingerprint-{name}= mapping)
+SPECIAL_PARAMS = {"fingerprint", "proxy", "geoip", "locale", "timezone"}
+
+
+def parse_connection_params(query_string: str) -> dict:
+    """Parse query params into connection config."""
+    qs = parse_qs(query_string, keep_blank_values=False)
+
+    result: dict = {
+        "seed": None,
+        "timezone": None,
+        "locale": None,
+        "proxy": None,
+        "geoip": False,
+        "extra_args": [],
+    }
+
+    for key, values in qs.items():
+        val = values[0]
+        if key == "fingerprint":
+            result["seed"] = val
+        elif key == "timezone":
+            result["timezone"] = val
+        elif key == "locale":
+            result["locale"] = val
+        elif key == "proxy":
+            result["proxy"] = val
+        elif key == "geoip":
+            result["geoip"] = val.lower() in ("true", "1", "yes")
+        elif key not in SPECIAL_PARAMS:
+            # Generic fingerprint param: map to --fingerprint-{key}={val}
+            result["extra_args"].append(f"--fingerprint-{key}={val}")
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# HTTP handlers
+# ---------------------------------------------------------------------------
+
+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)
+    return "wss" if proto == "https" else "ws"
+
+
+async def handle_root(request: web.Request) -> web.Response:
+    """Health check / process status."""
+    pool: ChromePool = request.app["pool"]
+    processes = {}
+    for key, proc in pool._processes.items():
+        if proc.process.poll() is None:
+            processes[key] = {
+                "pid": proc.process.pid,
+                "port": proc.cdp_port,
+                "seed": proc.seed,
+                "connections": pool._connections.get(key, 0),
+                "timezone": proc.timezone,
+                "locale": proc.locale,
+                "proxy": proc.proxy,
+            }
+    return web.json_response({
+        "status": "ok",
+        "active": len(processes),
+        "processes": processes,
+    })
+
+
+async def handle_json_version(request: web.Request) -> web.Response:
+    """Proxy /json/version with optional per-seed routing."""
+    pool: ChromePool = request.app["pool"]
+    params = parse_connection_params(request.query_string)
+
+    cp = await pool.get_or_launch(
+        seed=params["seed"],
+        extra_args=params["extra_args"] or None,
+        timezone=params["timezone"],
+        locale=params["locale"],
+        proxy=params["proxy"],
+        geoip=params["geoip"],
+    )
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                f"http://127.0.0.1:{cp.cdp_port}/json/version",
+                timeout=aiohttp.ClientTimeout(total=5),
+            ) as resp:
+                data = await resp.json()
+    except Exception as exc:
+        logger.error("Failed to reach Chrome CDP (port %d): %s", cp.cdp_port, exc)
+        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']}")
+    seed_key = params["seed"]
+    if seed_key:
+        ws_path = f"fingerprint/{seed_key}/devtools/browser"
+    else:
+        ws_path = "devtools/browser"
+
+    # Extract the browser GUID from Chrome's original URL
+    orig_ws = data.get("webSocketDebuggerUrl", "")
+    guid = orig_ws.rsplit("/", 1)[-1] if "/devtools/" in orig_ws else ""
+
+    scheme = _ws_scheme(request)
+    data["webSocketDebuggerUrl"] = f"{scheme}://{host}/{ws_path}/{guid}"
+    return web.json_response(data)
+
+
+async def handle_json_list(request: web.Request) -> web.Response:
+    """Proxy /json/list with per-seed routing. Rewrites all entries."""
+    pool: ChromePool = request.app["pool"]
+    params = parse_connection_params(request.query_string)
+
+    cp = await pool.get_or_launch(
+        seed=params["seed"],
+        extra_args=params["extra_args"] or None,
+        timezone=params["timezone"],
+        locale=params["locale"],
+        proxy=params["proxy"],
+        geoip=params["geoip"],
+    )
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                f"http://127.0.0.1:{cp.cdp_port}/json/list",
+                timeout=aiohttp.ClientTimeout(total=5),
+            ) as resp:
+                data = await resp.json()
+    except Exception as exc:
+        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']}")
+    scheme = _ws_scheme(request)
+    seed_key = params["seed"]
+
+    for entry in data:
+        if "webSocketDebuggerUrl" in entry:
+            ws_tail = entry["webSocketDebuggerUrl"].split("/devtools/")[-1]
+            if seed_key:
+                entry["webSocketDebuggerUrl"] = (
+                    f"{scheme}://{host}/fingerprint/{seed_key}/devtools/{ws_tail}"
+                )
+            else:
+                entry["webSocketDebuggerUrl"] = f"{scheme}://{host}/devtools/{ws_tail}"
+
+    return web.json_response(data)
+
+
+# ---------------------------------------------------------------------------
+# WebSocket proxy
+# ---------------------------------------------------------------------------
+
+async def proxy_cdp_websocket(
+    client_ws: web.WebSocketResponse,
+    target_url: str,
+    label: str,
+) -> None:
+    """Bidirectional WebSocket proxy between client and Chrome CDP."""
+    try:
+        async with websockets.connect(
+            target_url, max_size=None, ping_interval=None, ping_timeout=None,
+        ) as cdp_ws:
+            logger.info("%s: connected to %s", label, target_url)
+
+            async def client_to_cdp():
+                try:
+                    async for msg in client_ws:
+                        if msg.type == aiohttp.WSMsgType.TEXT:
+                            await cdp_ws.send(msg.data)
+                        elif msg.type == aiohttp.WSMsgType.BINARY:
+                            await cdp_ws.send(msg.data)
+                        elif msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSING, aiohttp.WSMsgType.CLOSED):
+                            break
+                except Exception as exc:
+                    logger.debug("%s [c->cdp]: %s", label, exc)
+
+            async def cdp_to_client():
+                try:
+                    async for msg in cdp_ws:
+                        if isinstance(msg, str):
+                            await client_ws.send_str(msg)
+                        else:
+                            await client_ws.send_bytes(msg)
+                except Exception as exc:
+                    logger.debug("%s [cdp->c]: %s", label, exc)
+
+            c2d = asyncio.create_task(client_to_cdp(), name="c2d")
+            d2c = asyncio.create_task(cdp_to_client(), name="d2c")
+            done, pending = await asyncio.wait(
+                [c2d, d2c], return_when=asyncio.FIRST_COMPLETED,
+            )
+            for task in pending:
+                task.cancel()
+            logger.info("%s: disconnected", label)
+
+    except Exception as exc:
+        logger.error("%s error: %s", label, exc)
+
+
+async def handle_ws_default(request: web.Request) -> web.WebSocketResponse:
+    """WebSocket proxy for default (no-seed) Chrome: /devtools/{type}/{guid}"""
+    pool: ChromePool = request.app["pool"]
+    path = request.match_info.get("path", "")
+
+    cp = await pool.get_or_launch(seed=None)
+
+    ws = web.WebSocketResponse()
+    await ws.prepare(request)
+
+    pool.connect("__default__")
+    try:
+        target_url = f"ws://127.0.0.1:{cp.cdp_port}/devtools/{path}"
+        await proxy_cdp_websocket(ws, target_url, f"CDP default [{path}]")
+    finally:
+        pool.disconnect("__default__")
+    return ws
+
+
+async def handle_ws_seed(request: web.Request) -> web.WebSocketResponse:
+    """WebSocket proxy for seed-specific Chrome: /fingerprint/{seed}/devtools/{type}/{guid}"""
+    pool: ChromePool = request.app["pool"]
+    seed = request.match_info["seed"]
+    path = request.match_info.get("path", "")
+
+    cp = await pool.get_or_launch(seed=seed)
+
+    ws = web.WebSocketResponse()
+    await ws.prepare(request)
+
+    pool.connect(seed)
+    try:
+        target_url = f"ws://127.0.0.1:{cp.cdp_port}/devtools/{path}"
+        await proxy_cdp_websocket(ws, target_url, f"CDP seed={seed} [{path}]")
+    finally:
+        pool.disconnect(seed)
+    return ws
+
+
+async def on_shutdown(app: web.Application) -> None:
+    await app["pool"].shutdown()
+
+
+# ---------------------------------------------------------------------------
+# CLI arg parsing
+# ---------------------------------------------------------------------------
+
+def _default_data_dir() -> str:
+    """Smart default: Docker → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve."""
+    if os.path.exists("/.dockerenv"):
+        return "/tmp/cloakserve"
+    return str(Path.home() / ".cloakbrowser" / "cloakserve")
+
+
+def parse_cli_args(argv: list[str]) -> tuple[dict, list[str]]:
+    """Parse cloakserve-specific args, return (config, passthrough_args)."""
+    config: dict = {
+        "port": 9222,
+        "headless": True,
+        "data_dir": None,
+    }
+    passthrough = []
+    # Flags consumed by cloakserve (not passed to Chrome)
+    consumed_prefixes = (
+        "--port=",
+        "--data-dir=",
+        "--remote-debugging-port=",
+        "--remote-debugging-address=",
+    )
+
+    for arg in argv:
+        if arg.startswith("--port="):
+            config["port"] = int(arg.split("=", 1)[1])
+        elif arg.startswith("--data-dir="):
+            config["data_dir"] = arg.split("=", 1)[1]
+        elif arg == "--headless=false" or arg == "--headless=False":
+            config["headless"] = False
+            passthrough.append(arg)
+        elif arg.startswith(consumed_prefixes):
+            pass  # Strip these silently
+        else:
+            passthrough.append(arg)
+
+    if config["data_dir"] is None:
+        config["data_dir"] = _default_data_dir()
+
+    return config, passthrough
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    binary = ensure_binary()
+    config, global_args = parse_cli_args(sys.argv[1:])
+
+    pool = ChromePool(
+        binary=binary,
+        global_args=global_args,
+        headless=config["headless"],
+        data_dir=config["data_dir"],
+    )
+
+    app = web.Application()
+    app["pool"] = pool
+    app["port"] = config["port"]
+
+    # Routes
+    app.router.add_get("/", handle_root)
+    app.router.add_get("/json/version", handle_json_version)
+    app.router.add_get("/json/version/", handle_json_version)
+    app.router.add_get("/json/list", handle_json_list)
+    app.router.add_get("/json/list/", handle_json_list)
+    app.router.add_get("/json", handle_json_list)
+    app.router.add_get("/json/", handle_json_list)
+
+    # WebSocket routes — seed-specific (must be before default to match first)
+    app.router.add_get("/fingerprint/{seed}/devtools/{path:.+}", handle_ws_seed)
+    # WebSocket routes — default (no seed)
+    app.router.add_get("/devtools/{path:.+}", handle_ws_default)
+
+    app.on_shutdown.append(on_shutdown)
+
+    port = config["port"]
+    logger.info("CloakBrowser CDP multiplexer starting on port %d", port)
+    logger.info(
+        "Connect: playwright.chromium.connect_over_cdp("
+        "\"http://localhost:%d?fingerprint=<seed>\")",
+        port,
+    )
+
+    web.run_app(app, host="0.0.0.0", port=port, print=None)
+
+
+if __name__ == "__main__":
+    main()
@@ -11,7 +11,7 @@ Usage:
    browser.close()
 """

-from .browser import launch, launch_async, launch_context, launch_persistent_context, launch_persistent_context_async, ProxySettings
+from .browser import launch, launch_async, launch_context, launch_persistent_context, launch_persistent_context_async, ProxySettings, build_args, maybe_resolve_geoip
 from .config import CHROMIUM_VERSION, get_default_stealth_args
 from .download import binary_info, check_for_update, clear_cache, ensure_binary
 from ._version import __version__
@@ -40,6 +40,8 @@ __all__ = [
    "check_for_update",
    "CHROMIUM_VERSION",
    "get_default_stealth_args",
+    "build_args",
+    "maybe_resolve_geoip",
    "ProxySettings",
    "HumanConfig",
    "resolve_human_config",
@@ -0,0 +1,111 @@
+"""CLI for cloakbrowser — download and manage the stealth Chromium binary.
+
+Usage:
+    python -m cloakbrowser install      # Download binary (with progress)
+    python -m cloakbrowser info         # Show binary version, path, platform
+    python -m cloakbrowser update       # Check for and download newer binary
+    python -m cloakbrowser clear-cache  # Remove cached binaries
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+
+def _setup_logging() -> None:
+    """Route cloakbrowser logger to stderr with clean output."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+        stream=sys.stderr,
+        force=True,
+    )
+    # Suppress noisy HTTP request logs from httpx
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+
+
+def cmd_install(args: argparse.Namespace) -> None:
+    from .download import ensure_binary
+
+    path = ensure_binary()
+    print(path)
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    from .config import get_local_binary_override
+    from .download import binary_info
+
+    info = binary_info()
+    override = get_local_binary_override()
+
+    print(f"Version:   {info['version']}")
+    print(f"Platform:  {info['platform']}")
+    print(f"Binary:    {info['binary_path']}")
+    print(f"Installed: {info['installed']}")
+    print(f"Cache:     {info['cache_dir']}")
+    if override:
+        print(f"Override:  {override} (CLOAKBROWSER_BINARY_PATH)")
+
+
+def cmd_update(args: argparse.Namespace) -> None:
+    from .download import check_for_update
+
+    logger = logging.getLogger("cloakbrowser")
+    logger.info("Checking for updates...")
+    new_version = check_for_update()
+    if new_version:
+        print(f"Updated to Chromium {new_version}")
+    else:
+        print("Already up to date.")
+
+
+def cmd_clear_cache(args: argparse.Namespace) -> None:
+    from .config import get_cache_dir
+    from .download import clear_cache
+
+    if not get_cache_dir().exists():
+        print("No cache to clear.")
+        return
+    clear_cache()
+    print("Cache cleared.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="cloakbrowser",
+        description="Manage the CloakBrowser stealth Chromium binary.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("install", help="Download the Chromium binary")
+    sub.add_parser("info", help="Show binary version, path, and platform")
+    sub.add_parser("update", help="Check for and download a newer binary")
+    sub.add_parser("clear-cache", help="Remove all cached binaries")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(2)
+
+    _setup_logging()
+
+    commands = {
+        "install": cmd_install,
+        "info": cmd_info,
+        "update": cmd_update,
+        "clear-cache": cmd_clear_cache,
+    }
+
+    try:
+        commands[args.command](args)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
@@ -1 +1 @@
-__version__ = "0.3.11"
+__version__ = "0.3.19"
@@ -16,20 +16,18 @@ from __future__ import annotations

 import logging
 import os
-import warnings
 from typing import Any, Literal, TypedDict
 from urllib.parse import unquote, urlparse, urlunparse

-from .config import DEFAULT_VIEWPORT, get_default_stealth_args
+from .config import DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS, get_default_stealth_args
 from .download import ensure_binary

 logger = logging.getLogger("cloakbrowser")


-def _migrate_timezone_id(timezone: str | None, kwargs: dict[str, Any]) -> str | None:
-    """Pop deprecated timezone_id from kwargs, warn, return resolved timezone."""
+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:
-        warnings.warn("timezone_id is deprecated, use timezone instead", FutureWarning, stacklevel=3)
        if timezone is None:
            timezone = kwargs.pop("timezone_id")
        else:
@@ -103,8 +101,8 @@ def launch(
    sync_playwright = _import_sync_playwright(_resolve_backend(backend))

    binary_path = ensure_binary()
-    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=locale)
+    timezone, locale = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    chrome_args = build_args(stealth_args, args, timezone=timezone, locale=locale, headless=headless)

    logger.debug("Launching stealth Chromium (headless=%s, args=%d)", headless, len(chrome_args))

@@ -113,7 +111,7 @@ def launch(
        executable_path=binary_path,
        headless=headless,
        args=chrome_args,
-        ignore_default_args=["--enable-automation"],
+        ignore_default_args=IGNORE_DEFAULT_ARGS,
        **_build_proxy_kwargs(proxy),
        **kwargs,
    )
@@ -122,8 +120,10 @@ def launch(
    _original_close = browser.close

    def _close_with_cleanup() -> None:
-        _original_close()
-        pw.stop()
+        try:
+            _original_close()
+        finally:
+            pw.stop()

    browser.close = _close_with_cleanup

@@ -186,8 +186,8 @@ async def launch_async(  # noqa: C901
    async_playwright = _import_async_playwright(_resolve_backend(backend))

    binary_path = ensure_binary()
-    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=locale)
+    timezone, locale = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    chrome_args = build_args(stealth_args, args, timezone=timezone, locale=locale, headless=headless)

    logger.debug("Launching stealth Chromium async (headless=%s, args=%d)", headless, len(chrome_args))

@@ -196,7 +196,7 @@ async def launch_async(  # noqa: C901
        executable_path=binary_path,
        headless=headless,
        args=chrome_args,
-        ignore_default_args=["--enable-automation"],
+        ignore_default_args=IGNORE_DEFAULT_ARGS,
        **_build_proxy_kwargs(proxy),
        **kwargs,
    )
@@ -205,8 +205,10 @@ async def launch_async(  # noqa: C901
    _original_close = browser.close

    async def _close_with_cleanup() -> None:
-        await _original_close()
-        await pw.stop()
+        try:
+            await _original_close()
+        finally:
+            await pw.stop()

    browser.close = _close_with_cleanup

@@ -279,11 +281,11 @@ def launch_persistent_context(
    """
    sync_playwright = _import_sync_playwright(_resolve_backend(backend))

-    timezone = _migrate_timezone_id(timezone, kwargs)
+    timezone = _resolve_timezone(timezone, kwargs)

    binary_path = ensure_binary()
-    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=locale)
+    timezone, locale = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    chrome_args = build_args(stealth_args, args, timezone=timezone, locale=locale, headless=headless)

    logger.debug(
        "Launching persistent stealth Chromium (headless=%s, user_data_dir=%s)",
@@ -291,14 +293,12 @@ def launch_persistent_context(
        user_data_dir,
    )

+    # locale and timezone are set via binary flags (--lang, --fingerprint-timezone)
+    # — NOT via Playwright context kwargs which use detectable CDP emulation.
    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
    context_kwargs["viewport"] = viewport or DEFAULT_VIEWPORT
-    if locale:
-        context_kwargs["locale"] = locale
-    if timezone:
-        context_kwargs["timezone_id"] = timezone
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
@@ -309,7 +309,7 @@ def launch_persistent_context(
        executable_path=binary_path,
        headless=headless,
        args=chrome_args,
-        ignore_default_args=["--enable-automation"],
+        ignore_default_args=IGNORE_DEFAULT_ARGS,
        **_build_proxy_kwargs(proxy),
        **context_kwargs,
    )
@@ -318,8 +318,10 @@ def launch_persistent_context(
    _original_close = context.close

    def _close_with_cleanup() -> None:
-        _original_close()
-        pw.stop()
+        try:
+            _original_close()
+        finally:
+            pw.stop()

    context.close = _close_with_cleanup

@@ -394,11 +396,11 @@ async def launch_persistent_context_async(
    """
    async_playwright = _import_async_playwright(_resolve_backend(backend))

-    timezone = _migrate_timezone_id(timezone, kwargs)
+    timezone = _resolve_timezone(timezone, kwargs)

    binary_path = ensure_binary()
-    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=locale)
+    timezone, locale = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    chrome_args = build_args(stealth_args, args, timezone=timezone, locale=locale, headless=headless)

    logger.debug(
        "Launching persistent stealth Chromium async (headless=%s, user_data_dir=%s)",
@@ -406,14 +408,12 @@ async def launch_persistent_context_async(
        user_data_dir,
    )

+    # locale and timezone are set via binary flags (--lang, --fingerprint-timezone)
+    # — NOT via Playwright context kwargs which use detectable CDP emulation.
    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
    context_kwargs["viewport"] = viewport or DEFAULT_VIEWPORT
-    if locale:
-        context_kwargs["locale"] = locale
-    if timezone:
-        context_kwargs["timezone_id"] = timezone
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
@@ -424,7 +424,7 @@ async def launch_persistent_context_async(
        executable_path=binary_path,
        headless=headless,
        args=chrome_args,
-        ignore_default_args=["--enable-automation"],
+        ignore_default_args=IGNORE_DEFAULT_ARGS,
        **_build_proxy_kwargs(proxy),
        **context_kwargs,
    )
@@ -433,8 +433,10 @@ async def launch_persistent_context_async(
    _original_close = context.close

    async def _close_with_cleanup() -> None:
-        await _original_close()
-        await pw.stop()
+        try:
+            await _original_close()
+        finally:
+            await pw.stop()

    context.close = _close_with_cleanup

@@ -491,25 +493,21 @@ def launch_context(
    Returns:
        Playwright BrowserContext object.
    """
-    timezone = _migrate_timezone_id(timezone, kwargs)
+    timezone = _resolve_timezone(timezone, kwargs)

    # Resolve geoip BEFORE launch() to avoid double-resolution and ensure
-    # resolved values flow to both binary flags AND context params
-    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    # Skip --fingerprint-timezone binary flag: it only applies to the default
-    # context and interferes with Playwright's timezone_id on new contexts.
-    # Timezone is set via browser.new_context(timezone_id=...) below instead.
+    # resolved values flow to binary flags
+    timezone, locale = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    # --fingerprint-timezone is process-wide (reads CommandLine in renderer),
+    # so it applies to ALL contexts, not just the default one.
+    # locale and timezone are set via binary flags only — no CDP emulation.
    browser = launch(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                     timezone=None, locale=locale, backend=backend)
+                     timezone=timezone, locale=locale, backend=backend)

    context_kwargs: dict[str, Any] = {}
    if user_agent:
        context_kwargs["user_agent"] = user_agent
    context_kwargs["viewport"] = viewport or DEFAULT_VIEWPORT
-    if locale:
-        context_kwargs["locale"] = locale
-    if timezone:
-        context_kwargs["timezone_id"] = timezone
    if color_scheme:
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)
@@ -524,8 +522,10 @@ def launch_context(
    _original_ctx_close = context.close

    def _close_context_with_cleanup() -> None:
-        _original_ctx_close()
-        browser.close()
+        try:
+            _original_ctx_close()
+        finally:
+            browser.close()

    context.close = _close_context_with_cleanup

@@ -585,7 +585,12 @@ def _import_async_playwright(backend: str):
 # ---------------------------------------------------------------------------


-def _maybe_resolve_geoip(
+def _ensure_proxy_scheme(proxy_url: str) -> str:
+    """Prepend http:// to schemeless proxy URLs so parsers can extract hostname."""
+    return proxy_url if "://" in proxy_url else f"http://{proxy_url}"
+
+
+def maybe_resolve_geoip(
    geoip: bool,
    proxy: str | ProxySettings | None,
    timezone: str | None,
@@ -600,6 +605,7 @@ def _maybe_resolve_geoip(
    proxy_url = proxy.get("server") if isinstance(proxy, dict) else proxy
    if not proxy_url:
        return timezone, locale
+    proxy_url = _ensure_proxy_scheme(proxy_url)
    geo_tz, geo_locale = resolve_proxy_geo(proxy_url)
    if timezone is None:
        timezone = geo_tz
@@ -608,11 +614,12 @@ def _maybe_resolve_geoip(
    return timezone, locale


-def _build_args(
+def build_args(
    stealth_args: bool,
    extra_args: list[str] | None,
    timezone: str | None = None,
    locale: str | None = None,
+    headless: bool = True,
 ) -> list[str]:
    """Combine stealth args with user-provided args and locale flags.

@@ -625,6 +632,16 @@ def _build_args(
        for arg in get_default_stealth_args():
            seen[arg.split("=", 1)[0]] = arg

+    # GPU blocklist bypass:
+    # - Headed mode (all platforms): Chromium blocks WebGL on software GPUs
+    #   in Docker/Xvfb. Flag lets SwiftShader serve WebGL. See issue #56.
+    # - Windows (all modes): Chromium's GPU blocklist blocks WebGPU for the
+    #   Microsoft Basic Render Driver. Dawn's adapter_blocklist bypass alone
+    #   isn't enough — need this flag too. Linux doesn't need it.
+    import platform as _platform
+    if not headless or _platform.system() == "Windows":
+        seen["--ignore-gpu-blocklist"] = "--ignore-gpu-blocklist"
+
    if extra_args:
        for arg in extra_args:
            key = arg.split("=", 1)[0]
@@ -640,11 +657,11 @@ def _build_args(
            logger.debug("Arg override: %s -> %s", seen[key], flag)
        seen[key] = flag
    if locale:
-        key = "--lang"
-        flag = f"{key}={locale}"
-        if key in seen:
-            logger.debug("Arg override: %s -> %s", seen[key], flag)
-        seen[key] = flag
+        for key in ("--lang", "--fingerprint-locale"):
+            flag = f"{key}={locale}"
+            if key in seen:
+                logger.debug("Arg override: %s -> %s", seen[key], flag)
+            seen[key] = flag

    return list(seen.values())

@@ -653,12 +670,18 @@ def _parse_proxy_url(proxy: str) -> dict[str, Any]:
    """Parse proxy URL, extracting credentials into separate Playwright fields.

    Handles: http://user:pass@host:port -> {server: "http://host:port", username: "user", password: "pass"}
-    Also handles: no credentials, URL-encoded special chars, socks5://, missing port.
+    Also handles: no credentials, URL-encoded special chars, socks5://, missing port,
+    and bare proxy strings without a scheme (e.g. 'user:pass@host:port' -> treated as http).
    """
-    parsed = urlparse(proxy)
+    # Bare format: "user:pass@host:port" — urlparse needs a scheme to extract credentials.
+    normalized = proxy
+    if "@" in proxy and "://" not in proxy:
+        normalized = f"http://{proxy}"
+
+    parsed = urlparse(normalized)

    if not parsed.username:
-        return {"server": proxy}
+        return {"server": proxy}  # no creds — return original unchanged

    # Rebuild server URL without credentials
    netloc = parsed.hostname or ""
@@ -15,15 +15,24 @@ 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 = "145.0.7632.159.3"
+CHROMIUM_VERSION = "145.0.7632.159.8"

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

+# ---------------------------------------------------------------------------
+# Playwright default args to suppress — these leak automation signals.
+# --enable-automation: exposes navigator.webdriver = true
+# --enable-unsafe-swiftshader: forces software WebGL rendering via SwiftShader,
+#   producing a distinctive renderer string that no real user browser has
+# ---------------------------------------------------------------------------
+IGNORE_DEFAULT_ARGS = ["--enable-automation", "--enable-unsafe-swiftshader"]
+
 # ---------------------------------------------------------------------------
 # Default stealth arguments passed to the patched Chromium binary.
 # These activate source-level fingerprint patches compiled into the binary.
@@ -56,8 +65,8 @@ def get_default_stealth_args() -> list[str]:
    # auto-generated by the binary from the seed (v14+).
    return base + [
        "--fingerprint-platform=windows",
-        "--fingerprint-gpu-vendor=NVIDIA Corporation",
-        "--fingerprint-gpu-renderer=NVIDIA GeForce RTX 3070",
+        "--fingerprint-gpu-vendor=Google Inc. (NVIDIA)",
+        "--fingerprint-gpu-renderer=ANGLE (NVIDIA, NVIDIA GeForce RTX 3070 (0x00002484) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    ]


@@ -12,6 +12,7 @@ import os
 import platform
 import stat
 import subprocess
+import sys
 import tarfile
 import tempfile
 import threading
@@ -55,13 +56,14 @@ def _show_welcome() -> None:
    marker = get_cache_dir() / ".welcome_shown"
    if marker.exists():
        return
-    print()
-    print("  CloakBrowser — stealth Chromium for automation")
-    print("  https://github.com/CloakHQ/CloakBrowser")
-    print()
-    print("  Issues?  https://github.com/CloakHQ/CloakBrowser/issues")
-    print("  Star us if CloakBrowser helps your project!")
-    print()
+    sys.stderr.write("\n")
+    sys.stderr.write("  CloakBrowser — stealth Chromium for automation\n")
+    sys.stderr.write("  https://github.com/CloakHQ/CloakBrowser\n")
+    sys.stderr.write("\n")
+    sys.stderr.write("  Issues?  https://github.com/CloakHQ/CloakBrowser/issues\n")
+    sys.stderr.write("  Donate?  https://ko-fi.com/cloakhq\n")
+    sys.stderr.write("  Star us if CloakBrowser helps your project!\n")
+    sys.stderr.write("\n")
    try:
        marker.parent.mkdir(parents=True, exist_ok=True)
        marker.write_text("")
@@ -41,7 +41,15 @@ def _get_nearby_key(ch: str) -> str:

 def human_type(page: Any, raw: RawKeyboard, text: str, cfg: HumanConfig) -> None:
    for i, ch in enumerate(text):
-        # Mistype chance — press wrong key, notice, backspace, then correct
+        # Non-ASCII characters (Cyrillic, CJK, emoji) — use insertText
+        if not ch.isascii():
+            sleep_ms(rand_range(cfg.key_hold))
+            raw.insert_text(ch)
+            if i < len(text) - 1:
+                _inter_char_delay(cfg)
+            continue
+
+        # Mistype chance — only for ASCII alphanumeric
        if random.random() < cfg.mistype_chance and ch.isalnum():
            wrong = _get_nearby_key(ch)
            _type_normal_char(raw, wrong, cfg)
@@ -22,7 +22,15 @@ class AsyncRawKeyboard(Protocol):

 async def async_human_type(page: Any, raw: AsyncRawKeyboard, text: str, cfg: HumanConfig) -> None:
    for i, ch in enumerate(text):
-        # Mistype chance — press wrong key, notice, backspace, then correct
+        # Non-ASCII characters (Cyrillic, CJK, emoji) — use insertText
+        if not ch.isascii():
+            await async_sleep_ms(rand_range(cfg.key_hold))
+            await raw.insert_text(ch)
+            if i < len(text) - 1:
+                await _inter_char_delay(cfg)
+            continue
+
+        # Mistype chance — only for ASCII alphanumeric
        if random.random() < cfg.mistype_chance and ch.isalnum():
            wrong = _get_nearby_key(ch)
            await _type_normal_char(raw, wrong, cfg)
@@ -0,0 +1,30 @@
+#!/bin/bash
+# agent-browser + CloakBrowser: AI browser agent with stealth fingerprints.
+#
+# agent-browser is a Node.js CLI for browser automation with session management.
+# CloakBrowser provides the stealth Chromium binary.
+#
+# Requires: npm install -g agent-browser
+#           pip install cloakbrowser (to auto-download the binary)
+#
+# Note: agent-browser launches Chrome itself via env vars — it can't connect
+# to an existing browser via CDP. So we pass the binary path and stealth args directly.
+
+# Get CloakBrowser binary path (auto-downloads if needed)
+BINARY_PATH=$(python3 -c "from cloakbrowser.download import ensure_binary; print(ensure_binary())")
+
+# Get stealth args from our wrapper (comma-separated for agent-browser)
+STEALTH_ARGS=$(python3 -c "from cloakbrowser.config import get_default_stealth_args; print(','.join(get_default_stealth_args()))")
+
+# Point agent-browser at CloakBrowser
+export AGENT_BROWSER_EXECUTABLE_PATH="$BINARY_PATH"
+export AGENT_BROWSER_ARGS="$STEALTH_ARGS"
+
+# Open a page
+agent-browser --session stealth-test open "https://example.com"
+
+# Get page title
+agent-browser --session stealth-test eval "document.title"
+
+# Check stealth
+agent-browser --session stealth-test eval "JSON.stringify({webdriver: navigator.webdriver, plugins: navigator.plugins.length, platform: navigator.platform})"
@@ -0,0 +1,41 @@
+"""browser-use + CloakBrowser: AI agent with stealth fingerprints.
+
+browser-use handles AI agent logic, CloakBrowser handles bot detection.
+Your agent can now browse sites behind Cloudflare, reCAPTCHA, DataDome.
+
+Requires: pip install browser-use cloakbrowser
+Set OPENAI_API_KEY (or swap for another LLM provider).
+"""
+
+import asyncio
+
+from browser_use import Agent, BrowserSession, ChatOpenAI
+
+from cloakbrowser import launch_async
+
+
+async def main():
+    # Step 1: Launch CloakBrowser (handles binary, stealth args, fingerprints)
+    cb_browser = await launch_async(
+        headless=True,
+        args=["--remote-debugging-port=9242", "--remote-debugging-address=127.0.0.1"],
+    )
+
+    # Step 2: Connect browser-use to the stealth browser via CDP
+    session = BrowserSession(cdp_url="http://127.0.0.1:9242")
+
+    # Step 3: Run your AI agent — it browses through CloakBrowser
+    agent = Agent(
+        task="Go to https://www.google.com and search for 'browser automation'",
+        llm=ChatOpenAI(model="gpt-4o-mini"),
+        browser_session=session,
+    )
+
+    result = await agent.run()
+    print(result)
+
+    await cb_browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,39 @@
+"""Crawl4AI + CloakBrowser: LLM-ready web crawling with stealth fingerprints.
+
+Crawl4AI handles extraction and markdown conversion,
+CloakBrowser handles bot detection.
+
+Requires: pip install crawl4ai cloakbrowser
+"""
+
+import asyncio
+
+from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
+
+from cloakbrowser import launch_async
+
+
+async def main():
+    # Step 1: Launch CloakBrowser with remote debugging
+    cb_browser = await launch_async(
+        headless=True,
+        args=["--remote-debugging-port=9243", "--remote-debugging-address=127.0.0.1"],
+    )
+
+    # Step 2: Connect Crawl4AI to the stealth browser via CDP
+    browser_config = BrowserConfig(browser_mode="cdp", cdp_url="http://127.0.0.1:9243")
+    run_config = CrawlerRunConfig()
+
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        result = await crawler.arun(
+            "https://example.com",
+            config=run_config,
+        )
+        print(f"Extracted {len(result.markdown)} chars of markdown")
+        print(result.markdown[:500])
+
+    await cb_browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,72 @@
+"""Crawlee + CloakBrowser: stealth web crawling with PlaywrightCrawler.
+
+Uses a custom BrowserPlugin to swap Crawlee's default Chromium
+for CloakBrowser's patched binary with source-level fingerprint patches.
+
+Requires: pip install cloakbrowser "crawlee[playwright]"
+"""
+
+import asyncio
+
+from cloakbrowser.config import IGNORE_DEFAULT_ARGS, get_default_stealth_args
+from cloakbrowser.download import ensure_binary
+from typing_extensions import override
+
+from crawlee.browsers import (
+    BrowserPool,
+    PlaywrightBrowserController,
+    PlaywrightBrowserPlugin,
+)
+from crawlee.crawlers import PlaywrightCrawler, PlaywrightCrawlingContext
+
+
+class CloakBrowserPlugin(PlaywrightBrowserPlugin):
+    """Browser plugin that uses CloakBrowser's patched Chromium,
+    but otherwise keeps the functionality of PlaywrightBrowserPlugin.
+    """
+
+    @override
+    async def new_browser(self) -> PlaywrightBrowserController:
+        if not self._playwright:
+            raise RuntimeError('Playwright browser plugin is not initialized.')
+
+        binary_path = ensure_binary()
+        stealth_args = get_default_stealth_args()
+
+        # Merge CloakBrowser stealth args with any user-provided launch options.
+        launch_options = dict(self._browser_launch_options)
+        launch_options.pop('executable_path', None)
+        launch_options.pop('chromium_sandbox', None)
+        existing_args = list(launch_options.pop('args', []))
+        launch_options['args'] = [*existing_args, *stealth_args]
+
+        return PlaywrightBrowserController(
+            browser=await self._playwright.chromium.launch(
+                executable_path=binary_path,
+                ignore_default_args=IGNORE_DEFAULT_ARGS,
+                **launch_options,
+            ),
+            max_open_pages_per_browser=1,
+            # CloakBrowser handles fingerprints at the binary level.
+            header_generator=None,
+        )
+
+
+async def main() -> None:
+    crawler = PlaywrightCrawler(
+        max_requests_per_crawl=10,
+        browser_pool=BrowserPool(plugins=[CloakBrowserPlugin()]),
+    )
+
+    @crawler.router.default_handler
+    async def request_handler(context: PlaywrightCrawlingContext) -> None:
+        context.log.info(f'Processing {context.request.url} ...')
+        title = await context.page.title()
+        await context.push_data({'url': context.request.url, 'title': title})
+        await context.enqueue_links()
+
+    await crawler.run(['https://example.com'])
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
@@ -0,0 +1,51 @@
+"""LangChain + CloakBrowser: load web pages behind bot detection into LangChain Documents.
+
+LangChain's PlaywrightURLLoader hardcodes chromium.launch() with no way to pass
+a custom binary. This example uses CloakBrowser directly as a stealth document loader
+that produces LangChain Document objects.
+
+Requires: pip install langchain-core cloakbrowser
+"""
+
+import asyncio
+
+from langchain_core.documents import Document
+
+from cloakbrowser import launch_async
+
+
+async def load_urls_stealth(urls: list[str], **launch_kwargs) -> list[Document]:
+    """Load URLs using CloakBrowser stealth browser, return LangChain Documents."""
+    browser = await launch_async(headless=True, **launch_kwargs)
+    page = await browser.new_page()
+    docs = []
+
+    for url in urls:
+        await page.goto(url, wait_until="domcontentloaded")
+        text = await page.evaluate("document.body.innerText")
+        title = await page.title()
+        docs.append(Document(
+            page_content=text,
+            metadata={"source": url, "title": title},
+        ))
+
+    await browser.close()
+    return docs
+
+
+async def main():
+    urls = [
+        "https://example.com",
+        "https://httpbin.org/html",
+    ]
+
+    docs = await load_urls_stealth(urls)
+
+    for doc in docs:
+        print(f"--- {doc.metadata['title']} ({doc.metadata['source']}) ---")
+        print(doc.page_content[:300])
+        print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,42 @@
+"""Scrapling + CloakBrowser: adaptive web scraping with stealth fingerprints.
+
+Scrapling handles parsing and element tracking,
+CloakBrowser handles bot detection.
+
+Requires: pip install scrapling[all] cloakbrowser
+"""
+
+import asyncio
+import json
+from urllib.request import urlopen
+
+from scrapling.fetchers import StealthyFetcher
+
+from cloakbrowser import launch_async
+
+
+async def main():
+    # Launch CloakBrowser with remote debugging
+    cb_browser = await launch_async(
+        headless=True,
+        args=["--remote-debugging-port=9245", "--remote-debugging-address=127.0.0.1"],
+    )
+
+    # Get the WebSocket URL from Chrome (Scrapling requires ws:// scheme)
+    info = json.loads(urlopen("http://127.0.0.1:9245/json/version").read())
+    ws_url = info["webSocketDebuggerUrl"]
+
+    # Connect Scrapling to the stealth browser via CDP
+    page = await StealthyFetcher.async_fetch(
+        "https://example.com",
+        cdp_url=ws_url,
+    )
+
+    print(f"Title: {page.css('title::text').get()}")
+    print(f"Text: {page.css('p::text').getall()}")
+
+    await cb_browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,41 @@
+"""Selenium + CloakBrowser: use stealth Chromium with Selenium WebDriver.
+
+CloakBrowser provides the binary and stealth args.
+Selenium drives it via ChromeDriver.
+
+Requires: pip install selenium cloakbrowser
+Note: ChromeDriver version must match Chromium 145.
+      pip install chromedriver-autoinstaller or download manually.
+"""
+
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+
+from cloakbrowser.config import get_default_stealth_args
+from cloakbrowser.download import ensure_binary
+
+binary_path = ensure_binary()
+stealth_args = get_default_stealth_args()
+
+options = Options()
+options.binary_location = binary_path
+options.add_argument("--headless")
+for arg in stealth_args:
+    options.add_argument(arg)
+
+driver = webdriver.Chrome(options=options)
+
+driver.get("https://example.com")
+print(f"Selenium + CloakBrowser: {driver.title}")
+
+# Verify stealth
+result = driver.execute_script("""
+    return {
+        webdriver: navigator.webdriver,
+        plugins: navigator.plugins.length,
+        platform: navigator.platform,
+    }
+""")
+print(f"Stealth checks: {result}")
+
+driver.quit()
@@ -0,0 +1,40 @@
+"""undetected-chromedriver + CloakBrowser: double stealth layer.
+
+undetected-chromedriver patches ChromeDriver detection signals,
+CloakBrowser patches the browser fingerprints at the C++ level.
+
+Requires: pip install undetected-chromedriver cloakbrowser
+"""
+
+import undetected_chromedriver as uc
+
+from cloakbrowser.config import get_chromium_version, get_default_stealth_args
+from cloakbrowser.download import ensure_binary
+
+binary_path = ensure_binary()
+stealth_args = get_default_stealth_args()
+chromium_major = int(get_chromium_version().split(".")[0])
+
+options = uc.ChromeOptions()
+options.binary_location = binary_path
+options.add_argument("--headless")
+for arg in stealth_args:
+    options.add_argument(arg)
+
+driver = uc.Chrome(options=options, version_main=chromium_major)
+
+driver.get("https://example.com")
+print(f"undetected-chromedriver + CloakBrowser: {driver.title}")
+
+# Verify stealth
+result = driver.execute_script("""
+    return {
+        webdriver: navigator.webdriver,
+        plugins: navigator.plugins.length,
+        platform: navigator.platform,
+        hardwareConcurrency: navigator.hardwareConcurrency,
+    }
+""")
+print(f"Stealth checks: {result}")
+
+driver.quit()
@@ -11,12 +11,12 @@

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

- **26 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, automation signals
+- **42 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, 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
 - **Free and open source** — no subscriptions, no usage limits
- **Works with any framework** — also tested with Selenium, undetected-chromedriver, browser-use, Crawl4AI, and agent-browser
+- **Works with any framework** — tested with browser-use, Crawl4AI, Scrapling, Stagehand ([example](examples/stagehand.ts)), LangChain, Selenium, and more

 ## Install

@@ -81,7 +81,7 @@ const browser = await launch({
  args: ['--fingerprint=12345'],
 });

-// With timezone and locale (sets --fingerprint-timezone and --lang binary flags)
+// With timezone and locale
 const browser = await launch({
  timezone: 'America/New_York',
  locale: 'en-US',
@@ -93,7 +93,7 @@ const browser = await launch({
  geoip: true,
 });

-// Browser + context in one call (timezone/locale set both binary flags AND context)
+// Browser + context in one call (timezone/locale set via binary flags)
 const context = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
@@ -133,6 +133,17 @@ const browser = await launch({ proxy: 'http://proxy:8080', geoip: true, timezone

 > **Note:** For rotating residential proxies, the DNS-resolved IP may differ from the exit IP. Pass explicit `timezone`/`locale` in those cases.

+### CLI
+
+Pre-download the binary or check installation status from the command line:
+
+```bash
+npx cloakbrowser install      # Download binary with progress output
+npx cloakbrowser info         # Show version, path, platform
+npx cloakbrowser update       # Check for and download newer binary
+npx cloakbrowser clear-cache  # Remove cached binaries
+```
+
 ### Utilities

 ```javascript
@@ -192,10 +203,11 @@ const page = await browser.newPage();

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

 ## Requirements

@@ -253,7 +265,7 @@ export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.159.2/chrome
 export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109.2/Chromium.app/Contents/MacOS/Chromium

 # Windows
-set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.109.2\chrome.exe
+set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.159.7\chrome.exe
 ```

 ## Links
@@ -0,0 +1,36 @@
+/**
+ * Stagehand + CloakBrowser: AI browser automation with stealth fingerprints.
+ *
+ * Stagehand handles AI-powered navigation and actions,
+ * CloakBrowser handles bot detection.
+ *
+ * Requires: npm install @browserbasehq/stagehand cloakbrowser
+ * Set OPENAI_API_KEY for the AI model.
+ *
+ * Usage:
+ *   CLOAKBROWSER_BINARY_PATH=/path/to/chrome npx tsx examples/stagehand.ts
+ */
+
+import { Stagehand } from "@browserbasehq/stagehand";
+import { ensureBinary } from "../src/download.js";
+import { getDefaultStealthArgs } from "../src/config.js";
+
+const binaryPath = await ensureBinary();
+const stealthArgs = getDefaultStealthArgs();
+
+const stagehand = new Stagehand({
+  env: "LOCAL",
+  localBrowserLaunchOptions: {
+    executablePath: binaryPath,
+    args: stealthArgs,
+    headless: true,
+  },
+});
+
+await stagehand.init();
+
+const page = stagehand.context.pages()[0];
+await page.goto("https://example.com");
+console.log(`Stagehand + CloakBrowser: ${await page.title()}`);
+
+await stagehand.close();
@@ -1,6 +1,6 @@
 {
  "name": "cloakbrowser",
-  "version": "0.3.11",
+  "version": "0.3.19",
  "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",
@@ -15,6 +15,9 @@
      "import": "./dist/puppeteer.js"
    }
  },
+  "bin": {
+    "cloakbrowser": "./dist/cli.js"
+  },
  "files": [
    "dist"
  ],
@@ -20,6 +20,15 @@ export function buildArgs(options: LaunchOptions): string[] {
      seen.set(arg.split("=")[0], arg);
    }
  }
+  // GPU blocklist bypass:
+  // - Headed mode (all platforms): Chromium blocks WebGL on software GPUs
+  //   in Docker/Xvfb. Flag lets SwiftShader serve WebGL. See issue #56.
+  // - Windows (all modes): Chromium's GPU blocklist blocks WebGPU for the
+  //   Microsoft Basic Render Driver. Dawn's adapter_blocklist bypass alone
+  //   isn't enough. Linux doesn't need it.
+  if (options.headless === false || process.platform === "win32") {
+    seen.set("--ignore-gpu-blocklist", "--ignore-gpu-blocklist");
+  }
  if (options.args) {
    for (const arg of options.args) {
      const key = arg.split("=")[0];
@@ -38,12 +47,13 @@ export function buildArgs(options: LaunchOptions): string[] {
    seen.set(key, flag);
  }
  if (options.locale) {
-    const key = "--lang";
-    const flag = `${key}=${options.locale}`;
-    if (seen.has(key)) {
-      if (DEBUG) console.debug(`[cloakbrowser] Arg override: ${seen.get(key)} -> ${flag}`);
+    for (const k of ["--lang", "--fingerprint-locale"] as const) {
+      const flag = `${k}=${options.locale}`;
+      if (seen.has(k)) {
+        if (DEBUG) console.debug(`[cloakbrowser] Arg override: ${seen.get(k)} -> ${flag}`);
+      }
+      seen.set(k, flag);
    }
-    seen.set(key, flag);
  }
  return [...seen.values()];
 }
@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * CLI for cloakbrowser — download and manage the stealth Chromium binary.
+ *
+ * Usage:
+ *   npx cloakbrowser install      # Download binary (with progress)
+ *   npx cloakbrowser info         # Show binary version, path, platform
+ *   npx cloakbrowser update       # Check for and download newer binary
+ *   npx cloakbrowser clear-cache  # Remove cached binaries
+ */
+
+import { ensureBinary, binaryInfo, checkForUpdate, clearCache } from "./download.js";
+import { getLocalBinaryOverride, getCacheDir } from "./config.js";
+import fs from "node:fs";
+
+const USAGE = `Usage: cloakbrowser <command>
+
+Commands:
+  install      Download the Chromium binary
+  info         Show binary version, path, and platform
+  update       Check for and download a newer binary
+  clear-cache  Remove all cached binaries`;
+
+async function cmdInstall(): Promise<void> {
+  const binaryPath = await ensureBinary();
+  console.log(binaryPath);
+}
+
+function cmdInfo(): void {
+  const info = binaryInfo();
+  const override = getLocalBinaryOverride();
+
+  console.log(`Version:   ${info.version}`);
+  console.log(`Platform:  ${info.platform}`);
+  console.log(`Binary:    ${info.binaryPath}`);
+  console.log(`Installed: ${info.installed}`);
+  console.log(`Cache:     ${info.cacheDir}`);
+  if (override) {
+    console.log(`Override:  ${override} (CLOAKBROWSER_BINARY_PATH)`);
+  }
+}
+
+async function cmdUpdate(): Promise<void> {
+  console.error("Checking for updates...");
+  const newVersion = await checkForUpdate();
+  if (newVersion) {
+    console.log(`Updated to Chromium ${newVersion}`);
+  } else {
+    console.log("Already up to date.");
+  }
+}
+
+function cmdClearCache(): void {
+  const cacheDir = getCacheDir();
+  if (!fs.existsSync(cacheDir)) {
+    console.log("No cache to clear.");
+    return;
+  }
+  clearCache();
+  console.log("Cache cleared.");
+}
+
+async function main(): Promise<void> {
+  const command = process.argv[2];
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(USAGE);
+    process.exit(command ? 0 : 2);
+  }
+
+  try {
+    switch (command) {
+      case "install":
+        await cmdInstall();
+        break;
+      case "info":
+        cmdInfo();
+        break;
+      case "update":
+        await cmdUpdate();
+        break;
+      case "clear-cache":
+        cmdClearCache();
+        break;
+      default:
+        console.error(`Unknown command: ${command}\n`);
+        console.log(USAGE);
+        process.exit(2);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+main();
@@ -27,13 +27,14 @@ export { WRAPPER_VERSION };
 // CHROMIUM_VERSION is the latest across all platforms (for display/reference).
 // Use getChromiumVersion() for the current platform's actual version.
 // ---------------------------------------------------------------------------
-export const CHROMIUM_VERSION = "145.0.7632.159.3";
+export const CHROMIUM_VERSION = "145.0.7632.159.8";

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

 // ---------------------------------------------------------------------------
@@ -188,6 +189,14 @@ export function getLocalBinaryOverride(): string | undefined {
  return process.env.CLOAKBROWSER_BINARY_PATH || undefined;
 }

+// ---------------------------------------------------------------------------
+// Playwright default args to suppress — these leak automation signals.
+// --enable-automation: exposes navigator.webdriver = true
+// --enable-unsafe-swiftshader: forces software WebGL rendering via SwiftShader,
+//   producing a distinctive renderer string that no real user browser has
+// ---------------------------------------------------------------------------
+export const IGNORE_DEFAULT_ARGS = ["--enable-automation", "--enable-unsafe-swiftshader"];
+
 // ---------------------------------------------------------------------------
 // Default stealth arguments
 // ---------------------------------------------------------------------------
@@ -222,7 +231,7 @@ export function getDefaultStealthArgs(): string[] {
  return [
    ...base,
    "--fingerprint-platform=windows",
-    "--fingerprint-gpu-vendor=NVIDIA Corporation",
-    "--fingerprint-gpu-renderer=NVIDIA GeForce RTX 3070",
+    "--fingerprint-gpu-vendor=Google Inc. (NVIDIA)",
+    "--fingerprint-gpu-renderer=ANGLE (NVIDIA, NVIDIA GeForce RTX 3070 (0x00002484) Direct3D11 vs_5_0 ps_5_0, D3D11)",
  ];
 }
@@ -146,13 +146,14 @@ export async function checkForUpdate(): Promise<string | null> {
 function showWelcome(): void {
  const marker = path.join(getCacheDir(), ".welcome_shown");
  if (fs.existsSync(marker)) return;
-  console.log();
-  console.log("  CloakBrowser — stealth Chromium for automation");
-  console.log("  https://github.com/CloakHQ/CloakBrowser");
-  console.log();
-  console.log("  Issues?  https://github.com/CloakHQ/CloakBrowser/issues");
-  console.log("  Star us if CloakBrowser helps your project!");
-  console.log();
+  console.error();
+  console.error("  CloakBrowser — stealth Chromium for automation");
+  console.error("  https://github.com/CloakHQ/CloakBrowser");
+  console.error();
+  console.error("  Issues?  https://github.com/CloakHQ/CloakBrowser/issues");
+  console.error("  Donate?  https://ko-fi.com/cloakhq");
+  console.error("  Star us if CloakBrowser helps your project!");
+  console.error();
  try {
    fs.mkdirSync(getCacheDir(), { recursive: true });
    fs.writeFileSync(marker, "");
@@ -227,7 +228,8 @@ async function verifyDownloadChecksum(filePath: string, version?: string): Promi
  await verifyChecksum(filePath, expected);
 }

-async function fetchChecksums(version?: string): Promise<Map<string, string> | null> {
+/** @internal Exported for testing only. */
+export async function fetchChecksums(version?: string): Promise<Map<string, string> | null> {
  const v = version || getChromiumVersion();
  const hasCustomUrl = !!process.env.CLOAKBROWSER_DOWNLOAD_URL;

@@ -14,6 +14,8 @@ import { createWriteStream } from "node:fs";
 import dns from "node:dns/promises";
 import net from "node:net";
 import { getCacheDir } from "./config.js";
+import type { LaunchOptions } from "./types.js";
+import { ensureProxyScheme } from "./proxy.js";

 // P3TERX mirror of MaxMind GeoLite2-City — no license key needed
 const GEOIP_DB_URL =
@@ -260,3 +262,23 @@ function maybeTriggerUpdate(dbPath: string): void {
  // Fire-and-forget background update
  downloadGeoipDb(dbPath).catch(() => {});
 }
+
+/**
+ * Auto-fill timezone/locale from proxy IP when geoip is enabled.
+ * Shared by the Playwright and Puppeteer wrappers.
+ */
+export async function maybeResolveGeoip(
+  options: LaunchOptions
+): Promise<{ timezone?: string; locale?: string }> {
+  if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
+  if (options.timezone && options.locale) return { timezone: options.timezone, locale: options.locale };
+
+  let proxyUrl = typeof options.proxy === "string" ? options.proxy : options.proxy.server;
+  if (!proxyUrl) return { timezone: options.timezone, locale: options.locale };
+  proxyUrl = ensureProxyScheme(proxyUrl);
+  const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(proxyUrl);
+  return {
+    timezone: options.timezone ?? geoTz ?? undefined,
+    locale: options.locale ?? geoLocale ?? undefined,
+  };
+}
@@ -22,6 +22,11 @@ const NEARBY_KEYS: Record<string, string> = {
  '6': '57ty', '7': '68yu', '8': '79ui', '9': '80io', '0': '9p',
 };

+function isAscii(ch: string): boolean {
+  const code = ch.codePointAt(0);
+  return code !== undefined && code < 128;
+}
+
 function getNearbyKey(ch: string): string {
  const lower = ch.toLowerCase();
  if (lower in NEARBY_KEYS) {
@@ -38,11 +43,23 @@ export async function humanType(
  text: string,
  cfg: HumanConfig,
 ): Promise<void> {
-  for (let i = 0; i < text.length; i++) {
-    const ch = text[i];
+  const chars = [...text]; // Handle emoji surrogate pairs correctly

-    // Mistype chance — press wrong key, notice, backspace, then correct
-    if (Math.random() < cfg.mistype_chance && /[a-zA-Z0-9]/.test(ch)) {
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i];
+
+    // Non-ASCII characters (Cyrillic, CJK, emoji) — use insertText
+    if (!isAscii(ch)) {
+      await sleep(randRange(cfg.key_hold));
+      await raw.insertText(ch);
+      if (i < chars.length - 1) {
+        await interCharDelay(cfg);
+      }
+      continue;
+    }
+
+    // Mistype chance — only for ASCII alphanumeric
+    if (Math.random() < cfg.mistype_chance && /^[a-zA-Z0-9]$/.test(ch)) {
      const wrong = getNearbyKey(ch);
      await typeNormalChar(raw, wrong, cfg);
      await sleep(randRange(cfg.mistype_delay_notice));
@@ -60,7 +77,7 @@ export async function humanType(
      await typeNormalChar(raw, ch, cfg);
    }

-    if (i < text.length - 1) {
+    if (i < chars.length - 1) {
      await interCharDelay(cfg);
    }
  }
@@ -5,15 +5,15 @@

 import type { Browser, BrowserContext } from "playwright-core";
 import type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOptions } from "./types.js";
-import { DEFAULT_VIEWPORT } from "./config.js";
+import { DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { parseProxyUrl } from "./proxy.js";
+import { maybeResolveGeoip } from "./geoip.js";

-/** @internal Migrate deprecated timezoneId → timezone, warn once. Exported for testing. */
-export function migrateTimezoneId<T extends { timezone?: string; timezoneId?: string }>(options: T): T {
+/** @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 {
  if (options.timezoneId != null) {
-    console.warn("[cloakbrowser] timezoneId is deprecated, use timezone instead");
    const merged = { ...options, timezone: options.timezone ?? options.timezoneId };
    delete (merged as any).timezoneId;
    return merged;
@@ -45,7 +45,7 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    executablePath: binaryPath,
    headless: options.headless ?? true,
    args,
-    ignoreDefaultArgs: ["--enable-automation"],
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
    ...(options.proxy
      ? { proxy: typeof options.proxy === "string" ? parseProxyUrl(options.proxy) : options.proxy }
      : {}),
@@ -85,21 +85,19 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
 export async function launchContext(
  options: LaunchContextOptions = {}
 ): Promise<BrowserContext> {
-  options = migrateTimezoneId(options);
+  options = resolveTimezone(options);
  // Resolve geoip BEFORE launch() to avoid double-resolution
  const resolved = await maybeResolveGeoip(options);
-  // Skip --fingerprint-timezone binary flag: it only applies to the default
-  // context and interferes with Playwright's timezoneId on new contexts.
-  // Timezone is set via browser.newContext(timezoneId: ...) below instead.
-  const browser = await launch({ ...options, ...resolved, geoip: false, timezone: undefined });
+  // --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, geoip: false });

  let context: BrowserContext;
  try {
    context = await browser.newContext({
      ...(options.userAgent ? { userAgent: options.userAgent } : {}),
      viewport: options.viewport ?? DEFAULT_VIEWPORT,
-      ...(resolved.locale ? { locale: resolved.locale } : {}),
-      ...(resolved.timezone ? { timezoneId: resolved.timezone } : {}),
      ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
    });
  } catch (err) {
@@ -152,25 +150,25 @@ export async function launchContext(
 export async function launchPersistentContext(
  options: LaunchPersistentContextOptions
 ): Promise<BrowserContext> {
-  options = migrateTimezoneId(options);
+  options = resolveTimezone(options);
  const { chromium } = await import("playwright-core");

  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
  const resolved = await maybeResolveGeoip(options);
  const args = buildArgs({ ...options, ...resolved });

+  // 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, {
    executablePath: binaryPath,
    headless: options.headless ?? true,
    args,
-    ignoreDefaultArgs: ["--enable-automation"],
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
    ...(options.proxy
      ? { proxy: typeof options.proxy === "string" ? parseProxyUrl(options.proxy) : options.proxy }
      : {}),
    ...(options.userAgent ? { userAgent: options.userAgent } : {}),
    viewport: options.viewport ?? DEFAULT_VIEWPORT,
-    ...(resolved.locale ? { locale: resolved.locale } : {}),
-    ...(resolved.timezone ? { timezoneId: resolved.timezone } : {}),
    ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
    ...options.launchOptions,
  });
@@ -193,21 +191,5 @@ export async function launchPersistentContext(
 // Internal
 // ---------------------------------------------------------------------------

-async function maybeResolveGeoip(
-  options: LaunchOptions
-): Promise<{ timezone?: string; locale?: string }> {
-  if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
-  if (options.timezone && options.locale) return { timezone: options.timezone, locale: options.locale };
-
-  const { resolveProxyGeo } = await import("./geoip.js");
-  const proxyUrl = typeof options.proxy === "string" ? options.proxy : options.proxy.server;
-  if (!proxyUrl) return { timezone: options.timezone, locale: options.locale };
-  const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(proxyUrl);
-  return {
-    timezone: options.timezone ?? geoTz ?? undefined,
-    locale: options.locale ?? geoLocale ?? undefined,
-  };
-}
-
 /** @internal Exposed for unit tests only. */
 export { buildArgs as _buildArgsForTest } from "./args.js";
@@ -8,16 +8,28 @@ export interface ParsedProxy {
  password?: string;
 }

+/**
+ * Prepend http:// to schemeless proxy URLs so parsers can extract hostname.
+ * Used by geoip resolution which only needs a valid hostname, not auth fields.
+ */
+export function ensureProxyScheme(proxyUrl: string): string {
+  return proxyUrl.includes("://") ? proxyUrl : `http://${proxyUrl}`;
+}
+
 /**
 * Parse a proxy URL, extracting credentials into separate fields.
 *
 * Handles: "http://user:pass@host:port" -> { server: "http://host:port", username: "user", password: "pass" }
- * Also handles: no credentials, URL-encoded special chars, socks5://, missing port.
+ * Also handles: no credentials, URL-encoded special chars, socks5://, missing port,
+ * and bare proxy strings without a scheme (e.g. "user:pass@host:port" -> treated as http).
 */
 export function parseProxyUrl(proxy: string): ParsedProxy {
  let url: URL;
+  // Bare format: "user:pass@host:port" — new URL() throws without a scheme.
+  const normalized =
+    proxy.includes("@") && !proxy.includes("://") ? `http://${proxy}` : proxy;
  try {
-    url = new URL(proxy);
+    url = new URL(normalized);
  } catch {
    // Not a parseable URL (e.g. bare "host:port") — pass through as-is
    return { server: proxy };
@@ -5,9 +5,11 @@

 import type { Browser } from "puppeteer-core";
 import type { LaunchOptions } from "./types.js";
+import { IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { parseProxyUrl } from "./proxy.js";
+import { maybeResolveGeoip } from "./geoip.js";

 /**
 * Launch stealth Chromium browser via Puppeteer.
@@ -61,7 +63,7 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    executablePath: binaryPath,
    headless: options.headless ?? true,
    args,
-    ignoreDefaultArgs: ["--enable-automation"],
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
    ...options.launchOptions,
  });

@@ -83,19 +85,3 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
 // Internal
 // ---------------------------------------------------------------------------

-async function maybeResolveGeoip(
-  options: LaunchOptions
-): Promise<{ timezone?: string; locale?: string }> {
-  if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
-  if (options.timezone && options.locale) return { timezone: options.timezone, locale: options.locale };
-
-  const { resolveProxyGeo } = await import("./geoip.js");
-  const proxyUrl = typeof options.proxy === "string" ? options.proxy : options.proxy.server;
-  if (!proxyUrl) return { timezone: options.timezone, locale: options.locale };
-  const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(proxyUrl);
-  return {
-    timezone: options.timezone ?? geoTz ?? undefined,
-    locale: options.locale ?? geoLocale ?? undefined,
-  };
-}
-
@@ -39,7 +39,7 @@ export interface LaunchContextOptions extends LaunchOptions {
  viewport?: { width: number; height: number };
  /** Browser locale, e.g. "en-US". */
  locale?: string;
-  /** @deprecated Use `timezone` (inherited from LaunchOptions) instead. */
+  /** IANA timezone — alias for `timezone`. Either works. */
  timezoneId?: string;
  /** Color scheme preference — 'light', 'dark', or 'no-preference'. */
  colorScheme?: "light" | "dark" | "no-preference";
@@ -9,7 +9,7 @@ import {
  getDownloadUrl,
  getFallbackDownloadUrl,
 } from "../src/config.js";
-import { _buildArgsForTest, migrateTimezoneId } from "../src/playwright.js";
+import { _buildArgsForTest, resolveTimezone } from "../src/playwright.js";

 describe("config", () => {
  it("CHROMIUM_VERSION matches expected format", () => {
@@ -97,21 +97,24 @@ describe("buildArgs timezone/locale", () => {
    expect(args).toContain("--fingerprint-timezone=America/New_York");
  });

-  it("injects --lang when locale is set", () => {
+  it("injects --lang and --fingerprint-locale when locale is set", () => {
    const args = _buildArgsForTest({ locale: "en-US" });
    expect(args).toContain("--lang=en-US");
+    expect(args).toContain("--fingerprint-locale=en-US");
  });

  it("injects both when both are set", () => {
    const args = _buildArgsForTest({ timezone: "Europe/Berlin", locale: "de-DE" });
    expect(args).toContain("--fingerprint-timezone=Europe/Berlin");
    expect(args).toContain("--lang=de-DE");
+    expect(args).toContain("--fingerprint-locale=de-DE");
  });

  it("injects timezone/locale even when stealthArgs=false", () => {
    const args = _buildArgsForTest({ stealthArgs: false, timezone: "America/New_York", locale: "en-US" });
    expect(args).toContain("--fingerprint-timezone=America/New_York");
    expect(args).toContain("--lang=en-US");
+    expect(args).toContain("--fingerprint-locale=en-US");
    expect(args.some(a => a.startsWith("--fingerprint="))).toBe(false);
  });

@@ -119,6 +122,7 @@ describe("buildArgs timezone/locale", () => {
    const args = _buildArgsForTest({});
    expect(args.some(a => a.startsWith("--fingerprint-timezone="))).toBe(false);
    expect(args.some(a => a.startsWith("--lang="))).toBe(false);
+    expect(args.some(a => a.startsWith("--fingerprint-locale="))).toBe(false);
  });
 });

@@ -147,14 +151,17 @@ describe("buildArgs deduplication", () => {
    expect(tzArgs[0]).toBe("--fingerprint-timezone=America/New_York");
  });

-  it("locale param overrides user --lang arg", () => {
+  it("locale param overrides user --lang and --fingerprint-locale args", () => {
    const args = _buildArgsForTest({
-      args: ["--lang=de-DE"],
+      args: ["--lang=de-DE", "--fingerprint-locale=de-DE"],
      locale: "en-US",
    });
    const langArgs = args.filter(a => a.startsWith("--lang="));
    expect(langArgs).toHaveLength(1);
    expect(langArgs[0]).toBe("--lang=en-US");
+    const localeArgs = args.filter(a => a.startsWith("--fingerprint-locale="));
+    expect(localeArgs).toHaveLength(1);
+    expect(localeArgs[0]).toBe("--fingerprint-locale=en-US");
  });

  it("no duplicate flag keys in output", () => {
@@ -175,29 +182,29 @@ describe("buildArgs deduplication", () => {
  });
 });

-describe("migrateTimezoneId deprecation", () => {
-  it("migrates timezoneId to timezone", () => {
-    const result = migrateTimezoneId({ timezoneId: "Europe/Paris" });
+describe("resolveTimezone alias", () => {
+  it("resolves timezoneId to timezone", () => {
+    const result = resolveTimezone({ timezoneId: "Europe/Paris" });
    expect(result.timezone).toBe("Europe/Paris");
    expect(result).not.toHaveProperty("timezoneId");
  });

  it("preserves explicit timezone over timezoneId", () => {
-    const result = migrateTimezoneId({ timezone: "UTC", timezoneId: "Europe/Paris" });
+    const result = resolveTimezone({ timezone: "UTC", timezoneId: "Europe/Paris" });
    expect(result.timezone).toBe("UTC");
    expect(result).not.toHaveProperty("timezoneId");
  });

  it("returns options unchanged when no timezoneId", () => {
    const opts = { timezone: "UTC" };
-    const result = migrateTimezoneId(opts);
+    const result = resolveTimezone(opts);
    expect(result).toBe(opts); // same reference, no copy
    expect(result.timezone).toBe("UTC");
  });

  it("returns options unchanged when neither is set", () => {
    const opts = {};
-    const result = migrateTimezoneId(opts);
+    const result = resolveTimezone(opts);
    expect(result).toBe(opts);
  });
 });
@@ -25,6 +25,17 @@ describe("resolveProxyIp", () => {
  it("returns null for empty string", async () => {
    expect(await resolveProxyIp("")).toBeNull();
  });
+
+  it("returns null for schemeless proxy (shows why normalization is needed)", async () => {
+    // no scheme — new URL() gives empty hostname for both bare formats
+    expect(await resolveProxyIp("user:pass@10.50.96.5:8888")).toBeNull();
+    expect(await resolveProxyIp("10.50.96.5:8888")).toBeNull();
+  });
+
+  it("extracts IP after normalization (http:// prepended by maybeResolveGeoip)", async () => {
+    expect(await resolveProxyIp("http://user:pass@10.50.96.5:8888")).toBe("10.50.96.5");
+    expect(await resolveProxyIp("http://10.50.96.5:8888")).toBe("10.50.96.5");
+  });
 });

 describe("COUNTRY_LOCALE_MAP", () => {
@@ -530,6 +530,81 @@ function buildMockPage(overrides: Record<string, any> = {}): any {
  return page;
 }

+// =========================================================================
+// humanType non-ASCII
+// =========================================================================
+describe("humanType non-ASCII", () => {
+  function makeRawKeyboardMock() {
+    const downKeys: string[] = [];
+    const insertedChars: string[] = [];
+    const raw = {
+      down: vi.fn(async (k: string) => { downKeys.push(k); }),
+      up: vi.fn(async () => {}),
+      type: vi.fn(async () => {}),
+      insertText: vi.fn(async (t: string) => { insertedChars.push(t); }),
+    };
+    return { raw, downKeys, insertedChars };
+  }
+
+  it("types Cyrillic via insertText, not down", async () => {
+    const { humanType } = await import("../src/human/keyboard.js");
+    const cfg = resolveConfig("default", { mistype_chance: 0 });
+    const { raw, downKeys, insertedChars } = makeRawKeyboardMock();
+
+    await humanType({} as any, raw, "Привет", cfg);
+
+    expect(insertedChars.join("")).toBe("Привет");
+    for (const k of downKeys) {
+      expect(k.charCodeAt(0)).toBeLessThan(128);
+    }
+  });
+
+  it("types mixed ASCII + Cyrillic correctly", async () => {
+    const { humanType } = await import("../src/human/keyboard.js");
+    const cfg = resolveConfig("default", { mistype_chance: 0 });
+    const { raw, downKeys, insertedChars } = makeRawKeyboardMock();
+
+    await humanType({} as any, raw, "Hi Мир", cfg);
+
+    expect(downKeys).toContain("H");
+    expect(downKeys).toContain("i");
+    expect(insertedChars.join("")).toContain("М");
+    expect(insertedChars.join("")).toContain("и");
+    expect(insertedChars.join("")).toContain("р");
+  });
+
+  it("types CJK via insertText", async () => {
+    const { humanType } = await import("../src/human/keyboard.js");
+    const cfg = resolveConfig("default", { mistype_chance: 0 });
+    const { raw, insertedChars } = makeRawKeyboardMock();
+
+    await humanType({} as any, raw, "你好", cfg);
+
+    expect(insertedChars.join("")).toBe("你好");
+  });
+
+  it("types emoji via insertText", async () => {
+    const { humanType } = await import("../src/human/keyboard.js");
+    const cfg = resolveConfig("default", { mistype_chance: 0 });
+    const { raw, insertedChars } = makeRawKeyboardMock();
+
+    await humanType({} as any, raw, "Hi 👋", cfg);
+
+    expect(insertedChars.join("")).toContain("👋");
+  });
+
+  it("mistype only triggers for ASCII, not Cyrillic", async () => {
+    const { humanType } = await import("../src/human/keyboard.js");
+    const cfg = resolveConfig("default", { mistype_chance: 1.0 });
+    const { raw, downKeys } = makeRawKeyboardMock();
+
+    await humanType({} as any, raw, "AБ", cfg);
+
+    expect(downKeys).toContain("Backspace");
+  });
+});
+
+

 function buildMockFrame(): any {
  return {
@@ -96,20 +96,20 @@ describe("launchContext (unit)", () => {
    expect(ctxArgs.userAgent).toBe("Custom/1.0");
  });

-  it("passes timezone to context timezoneId, not to launch", async () => {
+  it("passes timezone via binary flag, not CDP context", async () => {
    const { launchContext } = await import("../src/playwright.js");
    await launchContext({ timezone: "America/New_York" });

-    // launch() called with timezone: undefined (skipped for binary flag)
+    // launch() called with --fingerprint-timezone binary flag
    const launchArgs = mockChromium.launch.mock.calls[0][0];
    const hasTimezoneFlag = launchArgs.args.some((a: string) =>
-      a.startsWith("--fingerprint-timezone=")
+      a.startsWith("--fingerprint-timezone=America/New_York")
    );
-    expect(hasTimezoneFlag).toBe(false);
+    expect(hasTimezoneFlag).toBe(true);

-    // newContext() gets timezoneId
+    // NOT in newContext() — no CDP emulation
    const ctxArgs = mockBrowser.newContext.mock.calls[0][0];
-    expect(ctxArgs.timezoneId).toBe("America/New_York");
+    expect(ctxArgs.timezoneId).toBeUndefined();
  });

  it("forwards colorScheme to newContext", async () => {
@@ -165,7 +165,7 @@ describe("launchPersistentContext (unit)", () => {
    expect(args.viewport).toEqual(DEFAULT_VIEWPORT);
  });

-  it("passes timezone and locale to context", async () => {
+  it("passes timezone and locale via binary args, not CDP context", async () => {
    const { launchPersistentContext } = await import("../src/playwright.js");
    await launchPersistentContext({
      userDataDir: "/tmp/profile",
@@ -174,11 +174,12 @@ describe("launchPersistentContext (unit)", () => {
    });

    const args = mockChromium.launchPersistentContext.mock.calls[0][1];
-    expect(args.timezoneId).toBe("Asia/Tokyo");
-    expect(args.locale).toBe("ja-JP");
-    // Also in binary args
+    // Binary args (native, undetectable)
    expect(args.args).toContain("--fingerprint-timezone=Asia/Tokyo");
    expect(args.args).toContain("--lang=ja-JP");
+    // NOT in context kwargs (would trigger detectable CDP emulation)
+    expect(args.timezoneId).toBeUndefined();
+    expect(args.locale).toBeUndefined();
  });

  it("forwards proxy string", async () => {
@@ -82,3 +82,36 @@ describe("proxy dict type", () => {
    }
  });
 });
+
+describe("bare proxy format (user:pass@host:port)", () => {
+  it("extracts credentials from bare format", () => {
+    expect(parseProxyUrl("user:pass@proxy:8080")).toEqual({
+      server: "http://proxy:8080",
+      username: "user",
+      password: "pass",
+    });
+  });
+
+  it("credentials not in server", () => {
+    const r = parseProxyUrl("user:pass@proxy1.example.com:5610");
+    expect(r.server).not.toContain("user");
+    expect(r.server).not.toContain("pass");
+  });
+
+  it("bare username only", () => {
+    const r = parseProxyUrl("user@proxy:8080");
+    expect(r.username).toBe("user");
+    expect(r.password).toBeUndefined();
+    expect(r.server).toBe("http://proxy:8080");
+  });
+
+  it("bare no port", () => {
+    const r = parseProxyUrl("user:pass@proxy.example.com");
+    expect(r.username).toBe("user");
+    expect(r.server).toBe("http://proxy.example.com");
+  });
+
+  it("bare no credentials passes through unchanged", () => {
+    expect(parseProxyUrl("proxy:8080")).toEqual({ server: "proxy:8080" });
+  });
+});
@@ -13,6 +13,7 @@ vi.mock("../src/download.js", () => ({

 vi.mock("../src/geoip.js", () => ({
  resolveProxyGeo: vi.fn().mockResolvedValue({ timezone: null, locale: null }),
+  maybeResolveGeoip: vi.fn().mockResolvedValue({}),
 }));

 describe("puppeteer launch", () => {
@@ -14,6 +14,7 @@ import {
  checkWrapperUpdate,
  clearCache,
  ensureBinary,
+  fetchChecksums,
  getLatestChromiumVersion,
  parseChecksums,
  resetWrapperUpdateChecked,
@@ -269,6 +270,54 @@ describe("parseChecksums", () => {
  });
 });

+describe("download fallback", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.CLOAKBROWSER_DOWNLOAD_URL;
+  });
+
+  it("checksum fetch falls back to GitHub on primary 429", async () => {
+    const HASH =
+      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    const checksumText = `${HASH}  cloakbrowser-${getPlatformTag()}.tar.gz`;
+
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url =
+        typeof input === "string"
+          ? input
+          : input instanceof URL
+            ? input.toString()
+            : (input as Request).url;
+      if (url.includes("cloakbrowser.dev")) {
+        return {
+          ok: false,
+          status: 429,
+          statusText: "Too Many Requests",
+        } as Response;
+      }
+      // GitHub fallback
+      return { ok: true, text: async () => checksumText } as Response;
+    });
+
+    const result = await fetchChecksums();
+    expect(result).not.toBeNull();
+    expect(
+      result!.has(`cloakbrowser-${getPlatformTag()}.tar.gz`)
+    ).toBe(true);
+  });
+
+  it("checksum fetch returns null when both sources fail", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: false,
+      status: 429,
+      statusText: "Too Many Requests",
+    } as Response);
+
+    const result = await fetchChecksums();
+    expect(result).toBeNull();
+  });
+});
+
 describe("effective version", () => {
  it("returns platform version when no marker exists", () => {
    // Default behavior — no marker file in test environment
@@ -56,8 +56,12 @@ dependencies = [
 [project.optional-dependencies]
 geoip = ["geoip2>=4.0"]
 patchright = ["patchright>=1.40"]
+serve = ["aiohttp>=3.9", "websockets>=12.0"]
 dev = ["pytest>=7.0", "pytest-asyncio>=0.23"]

+[project.scripts]
+cloakbrowser = "cloakbrowser.__main__:main"
+
 [project.urls]
 Homepage = "https://github.com/CloakHQ/CloakBrowser"
 Documentation = "https://github.com/CloakHQ/CloakBrowser#readme"
@@ -1,97 +1,88 @@
-"""Unit tests for _build_args timezone/locale injection and deprecation compat."""
+"""Unit tests for build_args timezone/locale injection and timezone alias."""

-import warnings
-
-from cloakbrowser.browser import _build_args, _migrate_timezone_id
+from cloakbrowser.browser import build_args, _resolve_timezone


 def test_timezone_injected():
    """--fingerprint-timezone flag should appear when timezone is set."""
-    args = _build_args(stealth_args=True, extra_args=None, timezone="America/New_York")
+    args = build_args(stealth_args=True, extra_args=None, timezone="America/New_York")
    assert "--fingerprint-timezone=America/New_York" in args


 def test_locale_injected():
-    """--lang flag should appear when locale is set."""
-    args = _build_args(stealth_args=True, extra_args=None, locale="en-US")
+    """--lang and --fingerprint-locale flags should appear when locale is set."""
+    args = build_args(stealth_args=True, extra_args=None, locale="en-US")
    assert "--lang=en-US" in args
+    assert "--fingerprint-locale=en-US" in args


 def test_both_injected():
    """Both flags should appear when both are set."""
-    args = _build_args(stealth_args=True, extra_args=None, timezone="Europe/Berlin", locale="de-DE")
+    args = build_args(stealth_args=True, extra_args=None, timezone="Europe/Berlin", locale="de-DE")
    assert "--fingerprint-timezone=Europe/Berlin" in args
    assert "--lang=de-DE" in args
+    assert "--fingerprint-locale=de-DE" in args


 def test_timezone_independent_of_stealth_args():
    """--fingerprint-timezone should be injected even when stealth_args=False."""
-    args = _build_args(stealth_args=False, extra_args=None, timezone="America/New_York", locale="en-US")
+    args = build_args(stealth_args=False, extra_args=None, timezone="America/New_York", locale="en-US")
    assert "--fingerprint-timezone=America/New_York" in args
    assert "--lang=en-US" in args
+    assert "--fingerprint-locale=en-US" in args
    # No stealth fingerprint args
    assert not any(a.startswith("--fingerprint=") for a in args)


 def test_no_flags_when_not_set():
-    """No timezone/lang flags when params are None."""
-    args = _build_args(stealth_args=True, extra_args=None)
+    """No timezone/lang/fingerprint-locale flags when params are None."""
+    args = build_args(stealth_args=True, extra_args=None)
    assert not any(a.startswith("--fingerprint-timezone=") for a in args)
    assert not any(a.startswith("--lang=") for a in args)
+    assert not any(a.startswith("--fingerprint-locale=") for a in args)


 def test_extra_args_preserved():
    """Extra args should still be included alongside timezone/locale."""
-    args = _build_args(stealth_args=True, extra_args=["--disable-gpu"], timezone="Asia/Tokyo", locale="ja-JP")
+    args = build_args(stealth_args=True, extra_args=["--disable-gpu"], timezone="Asia/Tokyo", locale="ja-JP")
    assert "--disable-gpu" in args
    assert "--fingerprint-timezone=Asia/Tokyo" in args
    assert "--lang=ja-JP" in args
+    assert "--fingerprint-locale=ja-JP" in args


-# --- _migrate_timezone_id deprecation compat ---
+# --- _resolve_timezone alias ---


-def test_migrate_old_param_only():
+def test_resolve_timezone_id_alias():
    """timezone_id in kwargs should be promoted to timezone."""
    kwargs = {"timezone_id": "Europe/Paris"}
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        result = _migrate_timezone_id(None, kwargs)
+    result = _resolve_timezone(None, kwargs)
    assert result == "Europe/Paris"
    assert "timezone_id" not in kwargs
-    assert len(w) == 1 and issubclass(w[0].category, FutureWarning)


-def test_migrate_new_param_wins():
+def test_resolve_timezone_wins_over_alias():
    """Explicit timezone takes precedence; timezone_id is still popped."""
    kwargs = {"timezone_id": "Europe/Paris"}
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        result = _migrate_timezone_id("UTC", kwargs)
+    result = _resolve_timezone("UTC", kwargs)
    assert result == "UTC"
    assert "timezone_id" not in kwargs
-    assert len(w) == 1


-def test_migrate_no_old_param():
-    """No warning when timezone_id is absent."""
+def test_resolve_no_alias():
+    """No-op when timezone_id is absent."""
    kwargs = {"other": "value"}
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        result = _migrate_timezone_id("UTC", kwargs)
+    result = _resolve_timezone("UTC", kwargs)
    assert result == "UTC"
    assert "other" in kwargs
-    assert len(w) == 0


-def test_migrate_both_none():
-    """Neither param set — returns None, no warning."""
+def test_resolve_both_none():
+    """Neither param set — returns None."""
    kwargs = {}
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        result = _migrate_timezone_id(None, kwargs)
+    result = _resolve_timezone(None, kwargs)
    assert result is None
-    assert len(w) == 0


 # --- Deduplication tests ---
@@ -99,7 +90,7 @@ def test_migrate_both_none():

 def test_user_fingerprint_overrides_default():
    """User --fingerprint should override the random default seed."""
-    args = _build_args(stealth_args=True, extra_args=["--fingerprint=99887"])
+    args = build_args(stealth_args=True, extra_args=["--fingerprint=99887"])
    fingerprint_args = [a for a in args if a.startswith("--fingerprint=")]
    assert len(fingerprint_args) == 1
    assert fingerprint_args[0] == "--fingerprint=99887"
@@ -107,7 +98,7 @@ def test_user_fingerprint_overrides_default():

 def test_user_platform_overrides_default():
    """User --fingerprint-platform should override the default."""
-    args = _build_args(stealth_args=True, extra_args=["--fingerprint-platform=linux"])
+    args = build_args(stealth_args=True, extra_args=["--fingerprint-platform=linux"])
    platform_args = [a for a in args if a.startswith("--fingerprint-platform=")]
    assert len(platform_args) == 1
    assert platform_args[0] == "--fingerprint-platform=linux"
@@ -115,7 +106,7 @@ def test_user_platform_overrides_default():

 def test_timezone_param_overrides_user_arg():
    """Dedicated timezone param should override user arg."""
-    args = _build_args(
+    args = build_args(
        stealth_args=True,
        extra_args=["--fingerprint-timezone=Europe/London"],
        timezone="America/New_York",
@@ -126,20 +117,23 @@ def test_timezone_param_overrides_user_arg():


 def test_locale_param_overrides_user_arg():
-    """Dedicated locale param should override user --lang arg."""
-    args = _build_args(
+    """Dedicated locale param should override user --lang and --fingerprint-locale args."""
+    args = build_args(
        stealth_args=True,
-        extra_args=["--lang=de-DE"],
+        extra_args=["--lang=de-DE", "--fingerprint-locale=de-DE"],
        locale="en-US",
    )
    lang_args = [a for a in args if a.startswith("--lang=")]
    assert len(lang_args) == 1
    assert lang_args[0] == "--lang=en-US"
+    locale_args = [a for a in args if a.startswith("--fingerprint-locale=")]
+    assert len(locale_args) == 1
+    assert locale_args[0] == "--fingerprint-locale=en-US"


 def test_no_duplicate_flags():
    """No flag key should appear more than once in the output."""
-    args = _build_args(
+    args = build_args(
        stealth_args=True,
        extra_args=["--fingerprint=99887", "--fingerprint-timezone=UTC", "--lang=fr-FR"],
        timezone="Europe/Berlin",
@@ -151,7 +145,7 @@ def test_no_duplicate_flags():

 def test_non_value_flags_preserved():
    """Flags without = should be preserved without dedup issues."""
-    args = _build_args(stealth_args=True, extra_args=["--disable-gpu", "--no-zygote"])
+    args = build_args(stealth_args=True, extra_args=["--disable-gpu", "--no-zygote"])
    assert "--disable-gpu" in args
    assert "--no-zygote" in args
    assert "--no-sandbox" in args
@@ -162,5 +156,5 @@ def test_override_logs_debug(caplog):
    import logging

    with caplog.at_level(logging.DEBUG, logger="cloakbrowser"):
-        _build_args(stealth_args=True, extra_args=["--fingerprint=99887"])
+        build_args(stealth_args=True, extra_args=["--fingerprint=99887"])
    assert any("--fingerprint=" in r.message and "99887" in r.message for r in caplog.records)
@@ -0,0 +1,244 @@
+"""Unit tests for cloakserve — parse_connection_params, parse_cli_args, URL rewriting, connection tracking."""
+
+import importlib.machinery
+import importlib.util
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+aiohttp = pytest.importorskip("aiohttp", reason="cloakserve requires aiohttp (install with .[serve])")
+
+# Load cloakserve as a module from bin/ (no .py extension).
+_bin_path = str(Path(__file__).resolve().parents[1] / "bin" / "cloakserve")
+_loader = importlib.machinery.SourceFileLoader("cloakserve", _bin_path)
+_spec = importlib.util.spec_from_file_location("cloakserve", _bin_path, loader=_loader)
+_mod = importlib.util.module_from_spec(_spec)
+sys.modules["cloakserve"] = _mod
+_loader.exec_module(_mod)
+
+parse_connection_params = _mod.parse_connection_params
+parse_cli_args = _mod.parse_cli_args
+ChromePool = _mod.ChromePool
+_default_data_dir = _mod._default_data_dir
+
+
+# ---------------------------------------------------------------------------
+# parse_connection_params
+# ---------------------------------------------------------------------------
+
+
+class TestParseConnectionParams:
+    def test_empty_query(self):
+        result = parse_connection_params("")
+        assert result["seed"] is None
+        assert result["extra_args"] == []
+
+    def test_fingerprint_seed(self):
+        result = parse_connection_params("fingerprint=12345")
+        assert result["seed"] == "12345"
+
+    def test_timezone_and_locale(self):
+        result = parse_connection_params("fingerprint=1&timezone=Asia/Tokyo&locale=ja-JP")
+        assert result["timezone"] == "Asia/Tokyo"
+        assert result["locale"] == "ja-JP"
+
+    def test_proxy(self):
+        result = parse_connection_params("proxy=http://proxy:8080")
+        assert result["proxy"] == "http://proxy:8080"
+
+    def test_geoip_true_variants(self):
+        for val in ("true", "1", "yes", "True", "YES"):
+            result = parse_connection_params(f"geoip={val}")
+            assert result["geoip"] is True, f"geoip={val} should be True"
+
+    def test_geoip_false(self):
+        for val in ("false", "0", "no", "anything"):
+            result = parse_connection_params(f"geoip={val}")
+            assert result["geoip"] is False, f"geoip={val} should be False"
+
+    def test_generic_fingerprint_params(self):
+        qs = "fingerprint=1&platform=windows&hardware-concurrency=8&gpu-vendor=NVIDIA"
+        result = parse_connection_params(qs)
+        assert "--fingerprint-platform=windows" in result["extra_args"]
+        assert "--fingerprint-hardware-concurrency=8" in result["extra_args"]
+        assert "--fingerprint-gpu-vendor=NVIDIA" in result["extra_args"]
+
+    def test_special_params_not_in_extra_args(self):
+        qs = "fingerprint=1&timezone=UTC&locale=en-US&proxy=http://x:1&geoip=true"
+        result = parse_connection_params(qs)
+        assert result["extra_args"] == []
+
+    def test_multiple_values_takes_first(self):
+        result = parse_connection_params("fingerprint=111&fingerprint=222")
+        assert result["seed"] == "111"
+
+
+# ---------------------------------------------------------------------------
+# parse_cli_args
+# ---------------------------------------------------------------------------
+
+
+class TestParseCliArgs:
+    def test_defaults(self):
+        config, passthrough = parse_cli_args([])
+        assert config["port"] == 9222
+        assert config["headless"] is True
+        assert config["data_dir"] is not None
+        assert passthrough == []
+
+    def test_custom_port(self):
+        config, _ = parse_cli_args(["--port=8080"])
+        assert config["port"] == 8080
+
+    def test_headless_false(self):
+        config, passthrough = parse_cli_args(["--headless=false"])
+        assert config["headless"] is False
+        # headless flag still passed through to Chrome
+        assert "--headless=false" in passthrough
+
+    def test_strips_remote_debugging_flags(self):
+        args = ["--remote-debugging-port=9999", "--remote-debugging-address=0.0.0.0", "--no-sandbox"]
+        config, passthrough = parse_cli_args(args)
+        assert passthrough == ["--no-sandbox"]
+
+    def test_passthrough_args(self):
+        args = ["--no-sandbox", "--disable-gpu", "--fingerprint=999"]
+        _, passthrough = parse_cli_args(args)
+        assert passthrough == args
+
+    def test_port_not_in_passthrough(self):
+        _, passthrough = parse_cli_args(["--port=9222", "--no-sandbox"])
+        assert "--port=9222" not in passthrough
+        assert "--no-sandbox" in passthrough
+
+    def test_custom_data_dir(self):
+        config, passthrough = parse_cli_args(["--data-dir=/custom/path", "--no-sandbox"])
+        assert config["data_dir"] == "/custom/path"
+        assert "--data-dir=/custom/path" not in passthrough
+
+    def test_data_dir_not_in_passthrough(self):
+        _, passthrough = parse_cli_args(["--data-dir=/tmp/test"])
+        assert not any(a.startswith("--data-dir=") for a in passthrough)
+
+    @patch("os.path.exists", return_value=True)
+    def test_default_data_dir_docker(self, _mock):
+        assert _default_data_dir() == "/tmp/cloakserve"
+
+    @patch("os.path.exists", return_value=False)
+    def test_default_data_dir_bare_metal(self, _mock):
+        result = _default_data_dir()
+        assert result.endswith(".cloakbrowser/cloakserve")
+
+
+# ---------------------------------------------------------------------------
+# URL rewriting logic (pure string manipulation, extracted from handlers)
+# ---------------------------------------------------------------------------
+
+
+class TestURLRewriting:
+    """Test the URL rewriting logic used by /json/version and /json/list."""
+
+    def _rewrite_version(self, orig_ws: str, host: str, seed: str | None, scheme: str = "ws") -> str:
+        """Replicate the URL rewrite logic from handle_json_version."""
+        if seed:
+            ws_path = f"fingerprint/{seed}/devtools/browser"
+        else:
+            ws_path = "devtools/browser"
+        guid = orig_ws.rsplit("/", 1)[-1] if "/devtools/" in orig_ws else ""
+        return f"{scheme}://{host}/{ws_path}/{guid}"
+
+    def _rewrite_list_entry(self, orig_ws: str, host: str, seed: str | None, scheme: str = "ws") -> str:
+        """Replicate the URL rewrite logic from handle_json_list."""
+        ws_tail = orig_ws.split("/devtools/")[-1]
+        if seed:
+            return f"{scheme}://{host}/fingerprint/{seed}/devtools/{ws_tail}"
+        else:
+            return f"{scheme}://{host}/devtools/{ws_tail}"
+
+    def test_version_rewrite_with_seed(self):
+        orig = "ws://127.0.0.1:5100/devtools/browser/abc-123"
+        result = self._rewrite_version(orig, "container:9222", "12345")
+        assert result == "ws://container:9222/fingerprint/12345/devtools/browser/abc-123"
+
+    def test_version_rewrite_no_seed(self):
+        orig = "ws://127.0.0.1:5100/devtools/browser/abc-123"
+        result = self._rewrite_version(orig, "container:9222", None)
+        assert result == "ws://container:9222/devtools/browser/abc-123"
+
+    def test_list_rewrite_page_with_seed(self):
+        orig = "ws://127.0.0.1:5100/devtools/page/DEF-456"
+        result = self._rewrite_list_entry(orig, "host:9222", "99")
+        assert result == "ws://host:9222/fingerprint/99/devtools/page/DEF-456"
+
+    def test_list_rewrite_page_no_seed(self):
+        orig = "ws://127.0.0.1:5100/devtools/page/DEF-456"
+        result = self._rewrite_list_entry(orig, "host:9222", None)
+        assert result == "ws://host:9222/devtools/page/DEF-456"
+
+    def test_list_rewrite_browser(self):
+        orig = "ws://127.0.0.1:5100/devtools/browser/XYZ"
+        result = self._rewrite_list_entry(orig, "host:9222", "seed1")
+        assert result == "ws://host:9222/fingerprint/seed1/devtools/browser/XYZ"
+
+    def test_wss_scheme_version(self):
+        orig = "ws://127.0.0.1:5100/devtools/browser/abc-123"
+        result = self._rewrite_version(orig, "host:443", "seed1", scheme="wss")
+        assert result == "wss://host:443/fingerprint/seed1/devtools/browser/abc-123"
+
+    def test_wss_scheme_list(self):
+        orig = "ws://127.0.0.1:5100/devtools/page/DEF-456"
+        result = self._rewrite_list_entry(orig, "host:443", "seed1", scheme="wss")
+        assert result == "wss://host:443/fingerprint/seed1/devtools/page/DEF-456"
+
+
+# ---------------------------------------------------------------------------
+# Connection refcounting
+# ---------------------------------------------------------------------------
+
+
+class TestConnectionTracking:
+    """Test ChromePool.connect() / disconnect() without real Chrome."""
+
+    def _make_pool(self):
+        return ChromePool(
+            binary="/fake/chrome",
+            global_args=[],
+            headless=True,
+            data_dir="/tmp/test-cloakserve",
+        )
+
+    def test_connect_increments(self):
+        pool = self._make_pool()
+        pool.connect("seed1")
+        assert pool._connections["seed1"] == 1
+        pool.connect("seed1")
+        assert pool._connections["seed1"] == 2
+
+    def test_disconnect_decrements(self):
+        pool = self._make_pool()
+        pool.connect("seed1")
+        pool.connect("seed1")
+        pool.disconnect("seed1")
+        assert pool._connections["seed1"] == 1
+
+    def test_disconnect_to_zero_removes_key(self):
+        pool = self._make_pool()
+        pool.connect("seed1")
+        pool.disconnect("seed1")
+        assert "seed1" not in pool._connections
+
+    def test_disconnect_below_zero_safe(self):
+        pool = self._make_pool()
+        pool.disconnect("nonexistent")
+        assert "nonexistent" not in pool._connections
+
+    def test_multiple_seeds_independent(self):
+        pool = self._make_pool()
+        pool.connect("a")
+        pool.connect("b")
+        pool.connect("a")
+        pool.disconnect("a")
+        assert pool._connections["a"] == 1
+        assert pool._connections["b"] == 1
@@ -4,7 +4,7 @@ from unittest.mock import patch

 import pytest

-from cloakbrowser.browser import _maybe_resolve_geoip
+from cloakbrowser.browser import maybe_resolve_geoip
 from cloakbrowser.geoip import (
    COUNTRY_LOCALE_MAP,
    _is_private_ip,
@@ -92,25 +92,25 @@ def test_resolve_geo_returns_none_when_db_missing():


 # ---------------------------------------------------------------------------
-# _maybe_resolve_geoip (browser.py helper)
+# maybe_resolve_geoip (browser.py helper)
 # ---------------------------------------------------------------------------


 def test_maybe_resolve_skips_when_geoip_false():
-    tz, loc = _maybe_resolve_geoip(False, "http://proxy:8080", None, None)
+    tz, loc = maybe_resolve_geoip(False, "http://proxy:8080", None, None)
    assert tz is None
    assert loc is None


 def test_maybe_resolve_skips_when_no_proxy():
-    tz, loc = _maybe_resolve_geoip(True, None, None, None)
+    tz, loc = maybe_resolve_geoip(True, None, None, None)
    assert tz is None
    assert loc is None


 def test_maybe_resolve_skips_when_both_explicit():
    """Explicit values should not trigger geoip resolution."""
-    tz, loc = _maybe_resolve_geoip(True, "http://proxy:8080", "Europe/Berlin", "de-DE")
+    tz, loc = maybe_resolve_geoip(True, "http://proxy:8080", "Europe/Berlin", "de-DE")
    assert tz == "Europe/Berlin"
    assert loc == "de-DE"

@@ -118,7 +118,7 @@ def test_maybe_resolve_skips_when_both_explicit():
 def test_maybe_resolve_fills_missing_timezone():
    """When only locale is explicit, geoip should fill timezone."""
    with patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("America/New_York", "en-US")):
-        tz, loc = _maybe_resolve_geoip(True, "http://proxy:8080", None, "fr-FR")
+        tz, loc = maybe_resolve_geoip(True, "http://proxy:8080", None, "fr-FR")
        assert tz == "America/New_York"
        assert loc == "fr-FR"  # Explicit wins

@@ -126,7 +126,7 @@ def test_maybe_resolve_fills_missing_timezone():
 def test_maybe_resolve_fills_missing_locale():
    """When only timezone is explicit, geoip should fill locale."""
    with patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("America/New_York", "en-US")):
-        tz, loc = _maybe_resolve_geoip(True, "http://proxy:8080", "Asia/Tokyo", None)
+        tz, loc = maybe_resolve_geoip(True, "http://proxy:8080", "Asia/Tokyo", None)
        assert tz == "Asia/Tokyo"  # Explicit wins
        assert loc == "en-US"

@@ -134,7 +134,7 @@ def test_maybe_resolve_fills_missing_locale():
 def test_maybe_resolve_fills_both():
    """When neither is set, geoip should fill both."""
    with patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("Europe/Berlin", "de-DE")):
-        tz, loc = _maybe_resolve_geoip(True, "http://proxy:8080", None, None)
+        tz, loc = maybe_resolve_geoip(True, "http://proxy:8080", None, None)
        assert tz == "Europe/Berlin"
        assert loc == "de-DE"

@@ -406,6 +406,127 @@ class TestSelectAllPlatform:
            assert _SELECT_ALL == "Control+a"


+# =========================================================================
+# 11. Non-ASCII keyboard input
+# =========================================================================
+
+class TestNonAsciiKeyboard:
+    def test_cyrillic_uses_insert_text(self):
+        from cloakbrowser.human.keyboard import human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {"mistype_chance": 0})
+        page = MagicMock()
+        raw = MagicMock()
+
+        down_keys = []
+        inserted = []
+        raw.down = MagicMock(side_effect=lambda k: down_keys.append(k))
+        raw.up = MagicMock()
+        raw.insert_text = MagicMock(side_effect=lambda t: inserted.append(t))
+
+        human_type(page, raw, "Привет", cfg)
+
+        assert "".join(inserted) == "Привет"
+        for k in down_keys:
+            assert ord(k[0]) < 128 or k in ("Shift", "Backspace")
+
+    def test_mixed_ascii_cyrillic(self):
+        from cloakbrowser.human.keyboard import human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {"mistype_chance": 0})
+        page = MagicMock()
+        raw = MagicMock()
+
+        down_keys = []
+        inserted = []
+        raw.down = MagicMock(side_effect=lambda k: down_keys.append(k))
+        raw.up = MagicMock()
+        raw.insert_text = MagicMock(side_effect=lambda t: inserted.append(t))
+
+        human_type(page, raw, "Hi Мир", cfg)
+
+        assert "H" in down_keys
+        assert "i" in down_keys
+        assert "М" in "".join(inserted)
+
+    def test_cjk_uses_insert_text(self):
+        from cloakbrowser.human.keyboard import human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {"mistype_chance": 0})
+        page = MagicMock()
+        raw = MagicMock()
+
+        inserted = []
+        raw.down = MagicMock()
+        raw.up = MagicMock()
+        raw.insert_text = MagicMock(side_effect=lambda t: inserted.append(t))
+
+        human_type(page, raw, "你好", cfg)
+
+        assert "".join(inserted) == "你好"
+
+    def test_mistype_only_ascii(self):
+        from cloakbrowser.human.keyboard import human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {"mistype_chance": 1.0})
+        page = MagicMock()
+        raw = MagicMock()
+
+        down_keys = []
+        raw.down = MagicMock(side_effect=lambda k: down_keys.append(k))
+        raw.up = MagicMock()
+        raw.insert_text = MagicMock()
+
+        human_type(page, raw, "AБ", cfg)
+
+        assert "Backspace" in down_keys
+
+    def test_no_error_on_cyrillic(self):
+        from cloakbrowser.human.keyboard import human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {"mistype_chance": 0})
+        page = MagicMock()
+        raw = MagicMock()
+        raw.down = MagicMock()
+        raw.up = MagicMock()
+        raw.insert_text = MagicMock()
+
+        # Should not raise
+        human_type(page, raw, "Тест кириллицы", cfg)
+
+
+class TestNonAsciiKeyboardAsync:
+    @pytest.mark.asyncio
+    async def test_async_cyrillic_uses_insert_text(self):
+        from cloakbrowser.human.keyboard_async import async_human_type
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, AsyncMock
+
+        cfg = resolve_config("default", {"mistype_chance": 0})
+        page = MagicMock()
+        raw = MagicMock()
+
+        inserted = []
+        raw.down = AsyncMock()
+        raw.up = AsyncMock()
+        raw.insert_text = AsyncMock(side_effect=lambda t: inserted.append(t))
+
+        await async_human_type(page, raw, "Привет", cfg)
+
+        assert "".join(inserted) == "Привет"
+
+
+
 # =========================================================================
 # SLOW TESTS — require browser (skipped in CI unless pytest -m slow)
 # =========================================================================
@@ -1,6 +1,5 @@
 """Unit tests for launch_context() — context kwargs, viewport defaults, close cleanup."""

-import warnings
 from unittest.mock import MagicMock, call, patch

 import pytest
@@ -66,7 +65,7 @@ def test_user_agent(mock_launch, _mock_bin):
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.launch")
 def test_locale_forwarded(mock_launch, _mock_bin):
-    """locale flows to both launch() binary args AND new_context()."""
+    """locale flows to launch() for --lang binary flag, NOT to new_context() CDP."""
    browser, context = _make_mock_browser()
    mock_launch.return_value = browser

@@ -75,18 +74,18 @@ def test_locale_forwarded(mock_launch, _mock_bin):

    # Locale in launch() call (for --lang binary flag)
    assert mock_launch.call_args[1]["locale"] == "de-DE"
-    # Locale in new_context() call
+    # NOT in new_context() — would trigger detectable CDP emulation
    ctx_kwargs = browser.new_context.call_args
-    assert ctx_kwargs[1]["locale"] == "de-DE"
+    assert "locale" not in ctx_kwargs[1]


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.launch")
-def test_timezone_via_context_not_binary(mock_launch, _mock_bin):
-    """timezone passed to new_context(timezone_id=...) but NOT to launch(timezone=...).
+def test_timezone_via_binary_not_cdp(mock_launch, _mock_bin):
+    """timezone passed to launch() for binary flag, NOT to new_context() CDP.

-    This is intentional: the --fingerprint-timezone binary flag only applies to the
-    default context and would conflict with Playwright's timezone_id on new contexts.
+    --fingerprint-timezone is process-wide (reads CommandLine in renderer),
+    so it applies to ALL contexts, not just the default one.
    """
    browser, context = _make_mock_browser()
    mock_launch.return_value = browser
@@ -94,11 +93,11 @@ def test_timezone_via_context_not_binary(mock_launch, _mock_bin):
    from cloakbrowser.browser import launch_context
    launch_context(timezone="America/New_York")

-    # timezone=None in launch() — binary flag skipped
-    assert mock_launch.call_args[1]["timezone"] is None
-    # timezone_id in new_context()
+    # timezone in launch() — binary flag set
+    assert mock_launch.call_args[1]["timezone"] == "America/New_York"
+    # NOT in new_context() — no CDP emulation
    ctx_kwargs = browser.new_context.call_args
-    assert ctx_kwargs[1]["timezone_id"] == "America/New_York"
+    assert "timezone_id" not in ctx_kwargs[1]


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@@ -115,44 +114,41 @@ def test_color_scheme(mock_launch, _mock_bin):
    assert ctx_kwargs[1]["color_scheme"] == "dark"


-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=("Europe/Berlin", "de-DE"))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=("Europe/Berlin", "de-DE"))
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.launch")
 def test_geoip_resolution(mock_launch, _mock_bin, _mock_geoip):
-    """geoip fills timezone+locale, both flow to correct places."""
+    """geoip fills timezone+locale, both flow to binary args only."""
    browser, context = _make_mock_browser()
    mock_launch.return_value = browser

    from cloakbrowser.browser import launch_context
    launch_context(proxy="http://proxy:8080", geoip=True)

-    # Locale goes to launch() for binary flag
+    # Both go to launch() for binary flags
    assert mock_launch.call_args[1]["locale"] == "de-DE"
-    # Timezone goes to context, not binary
-    assert mock_launch.call_args[1]["timezone"] is None
+    assert mock_launch.call_args[1]["timezone"] == "Europe/Berlin"
+    # Neither in context — no CDP emulation
    ctx_kwargs = browser.new_context.call_args
-    assert ctx_kwargs[1]["timezone_id"] == "Europe/Berlin"
-    assert ctx_kwargs[1]["locale"] == "de-DE"
+    assert "timezone_id" not in ctx_kwargs[1]
+    assert "locale" not in ctx_kwargs[1]


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.launch")
-def test_timezone_id_deprecation(mock_launch, _mock_bin):
-    """timezone_id kwarg triggers FutureWarning, value migrated to timezone."""
+def test_timezone_id_alias(mock_launch, _mock_bin):
+    """timezone_id kwarg accepted as alias for timezone."""
    browser, context = _make_mock_browser()
    mock_launch.return_value = browser

    from cloakbrowser.browser import launch_context
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        launch_context(timezone_id="Europe/Paris")
+    launch_context(timezone_id="Europe/Paris")

-    assert len(w) == 1
-    assert issubclass(w[0].category, FutureWarning)
-    assert "timezone_id" in str(w[0].message)
-    # Migrated value flows to context
+    # Resolved value flows to launch() for binary flag
+    assert mock_launch.call_args[1]["timezone"] == "Europe/Paris"
+    # NOT in context — no CDP emulation
    ctx_kwargs = browser.new_context.call_args
-    assert ctx_kwargs[1]["timezone_id"] == "Europe/Paris"
+    assert "timezone_id" not in ctx_kwargs[1]


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@@ -3,7 +3,6 @@
 All tests mock playwright to avoid needing a binary.
 """

-import warnings
 from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
@@ -27,7 +26,7 @@ def _make_mock_pw_and_context():


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_args_built(_mock_geoip, _mock_bin):
    """Stealth args + extra args combined correctly."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -43,7 +42,7 @@ def test_persistent_context_args_built(_mock_geoip, _mock_bin):


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_default_viewport(_mock_geoip, _mock_bin):
    """DEFAULT_VIEWPORT applied when no viewport given."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -57,7 +56,7 @@ def test_persistent_context_default_viewport(_mock_geoip, _mock_bin):


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_custom_viewport(_mock_geoip, _mock_bin):
    """Custom viewport overrides DEFAULT_VIEWPORT."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -72,7 +71,7 @@ def test_persistent_context_custom_viewport(_mock_geoip, _mock_bin):


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_user_agent(_mock_geoip, _mock_bin):
    """user_agent forwarded to launch_persistent_context()."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -87,7 +86,7 @@ def test_persistent_context_user_agent(_mock_geoip, _mock_bin):

@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
 def test_persistent_context_locale_and_timezone(_mock_bin):
-    """Both timezone and locale flow to context kwargs and binary args."""
+    """Timezone and locale flow to binary args only, NOT to CDP context kwargs."""
    pw_cm, pw, context = _make_mock_pw_and_context()

    with patch("playwright.sync_api.sync_playwright", return_value=pw_cm):
@@ -95,16 +94,16 @@ def test_persistent_context_locale_and_timezone(_mock_bin):
        launch_persistent_context("/tmp/profile", timezone="Asia/Tokyo", locale="ja-JP")

    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
-    # Context kwargs
-    assert call_kwargs["timezone_id"] == "Asia/Tokyo"
-    assert call_kwargs["locale"] == "ja-JP"
-    # Binary args
+    # Binary args (native, undetectable)
    assert "--fingerprint-timezone=Asia/Tokyo" in call_kwargs["args"]
    assert "--lang=ja-JP" in call_kwargs["args"]
+    # NOT in context kwargs (would trigger detectable CDP emulation)
+    assert "timezone_id" not in call_kwargs
+    assert "locale" not in call_kwargs


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_color_scheme(_mock_geoip, _mock_bin):
    """color_scheme forwarded correctly."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -117,10 +116,10 @@ def test_persistent_context_color_scheme(_mock_geoip, _mock_bin):
    assert call_kwargs["color_scheme"] == "dark"


-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=("Europe/Berlin", "de-DE"))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=("Europe/Berlin", "de-DE"))
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
 def test_persistent_context_geoip(_mock_bin, _mock_geoip):
-    """geoip fills missing tz/locale."""
+    """geoip fills missing tz/locale — flows to binary args, not CDP context."""
    pw_cm, pw, context = _make_mock_pw_and_context()

    with patch("playwright.sync_api.sync_playwright", return_value=pw_cm):
@@ -128,29 +127,30 @@ def test_persistent_context_geoip(_mock_bin, _mock_geoip):
        launch_persistent_context("/tmp/profile", proxy="http://proxy:8080", geoip=True)

    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
-    assert call_kwargs["timezone_id"] == "Europe/Berlin"
-    assert call_kwargs["locale"] == "de-DE"
+    # Binary args
+    assert "--fingerprint-timezone=Europe/Berlin" in call_kwargs["args"]
+    assert "--lang=de-DE" in call_kwargs["args"]
+    # NOT in context kwargs
+    assert "timezone_id" not in call_kwargs
+    assert "locale" not in call_kwargs


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-def test_persistent_context_timezone_id_deprecation(_mock_bin):
-    """Old timezone_id kwarg migrated with warning."""
+def test_persistent_context_timezone_id_alias(_mock_bin):
+    """timezone_id kwarg accepted as alias for timezone."""
    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
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            launch_persistent_context("/tmp/profile", timezone_id="Europe/Paris")
+        launch_persistent_context("/tmp/profile", timezone_id="Europe/Paris")

-    assert len(w) == 1
-    assert issubclass(w[0].category, FutureWarning)
    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
-    assert call_kwargs["timezone_id"] == "Europe/Paris"
+    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))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_close_stops_pw(_mock_geoip, _mock_bin):
    """context.close() also calls pw.stop()."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -166,7 +166,7 @@ def test_persistent_context_close_stops_pw(_mock_geoip, _mock_bin):


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_proxy_string(_mock_geoip, _mock_bin):
    """Proxy string parsed and passed."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -182,7 +182,7 @@ def test_persistent_context_proxy_string(_mock_geoip, _mock_bin):


@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 def test_persistent_context_proxy_dict(_mock_geoip, _mock_bin):
    """Proxy dict passed through."""
    pw_cm, pw, context = _make_mock_pw_and_context()
@@ -213,7 +213,7 @@ def _make_mock_async_pw_and_context():

@pytest.mark.asyncio
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 async def test_persistent_context_async_args_built(_mock_geoip, _mock_bin):
    """Async launch builds args correctly."""
    pw_cm, pw, context = _make_mock_async_pw_and_context()
@@ -229,7 +229,7 @@ async def test_persistent_context_async_args_built(_mock_geoip, _mock_bin):

@pytest.mark.asyncio
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-@patch("cloakbrowser.browser._maybe_resolve_geoip", return_value=(None, None))
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None))
 async def test_persistent_context_async_close_stops_pw(_mock_geoip, _mock_bin):
    """await context.close() calls await pw.stop()."""
    pw_cm, pw, context = _make_mock_async_pw_and_context()
@@ -246,17 +246,14 @@ async def test_persistent_context_async_close_stops_pw(_mock_geoip, _mock_bin):

@pytest.mark.asyncio
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
-async def test_persistent_context_async_timezone_id_deprecation(_mock_bin):
-    """Deprecated timezone_id kwarg migrated with warning in async path."""
+async def test_persistent_context_async_timezone_id_alias(_mock_bin):
+    """timezone_id kwarg accepted as alias in async 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
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            await launch_persistent_context_async("/tmp/profile", timezone_id="Europe/Paris")
+        await launch_persistent_context_async("/tmp/profile", timezone_id="Europe/Paris")

-    assert len(w) == 1
-    assert issubclass(w[0].category, FutureWarning)
    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
-    assert call_kwargs["timezone_id"] == "Europe/Paris"
+    assert "--fingerprint-timezone=Europe/Paris" in call_kwargs["args"]
+    assert "timezone_id" not in call_kwargs
@@ -2,7 +2,7 @@

 from unittest.mock import patch

-from cloakbrowser.browser import _build_proxy_kwargs, _maybe_resolve_geoip, _parse_proxy_url
+from cloakbrowser.browser import _build_proxy_kwargs, maybe_resolve_geoip, _parse_proxy_url


 class TestParseProxyUrl:
@@ -70,7 +70,7 @@ class TestBuildProxyKwargs:
 class TestMaybeResolveGeoip:
    @patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("America/New_York", "en-US"))
    def test_geoip_with_string_proxy(self, mock_geo):
-        tz, locale = _maybe_resolve_geoip(True, "http://proxy:8080", None, None)
+        tz, locale = maybe_resolve_geoip(True, "http://proxy:8080", None, None)
        mock_geo.assert_called_once_with("http://proxy:8080")
        assert tz == "America/New_York"
        assert locale == "en-US"
@@ -78,23 +78,76 @@ class TestMaybeResolveGeoip:
    @patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("Europe/London", "en-GB"))
    def test_geoip_with_dict_proxy_extracts_server(self, mock_geo):
        proxy_dict = {"server": "http://proxy:8080", "bypass": ".google.com"}
-        tz, locale = _maybe_resolve_geoip(True, proxy_dict, None, None)
+        tz, locale = maybe_resolve_geoip(True, proxy_dict, None, None)
        mock_geo.assert_called_once_with("http://proxy:8080")
        assert tz == "Europe/London"
        assert locale == "en-GB"

    def test_geoip_disabled_skips_resolution(self):
-        tz, locale = _maybe_resolve_geoip(False, "http://proxy:8080", None, None)
+        tz, locale = maybe_resolve_geoip(False, "http://proxy:8080", None, None)
        assert tz is None
        assert locale is None

    def test_geoip_no_proxy_skips_resolution(self):
-        tz, locale = _maybe_resolve_geoip(True, None, None, None)
+        tz, locale = maybe_resolve_geoip(True, None, None, None)
        assert tz is None
        assert locale is None

    @patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("Asia/Tokyo", "ja-JP"))
    def test_geoip_preserves_explicit_timezone(self, mock_geo):
-        tz, locale = _maybe_resolve_geoip(True, "http://proxy:8080", "Europe/Berlin", None)
+        tz, locale = maybe_resolve_geoip(True, "http://proxy:8080", "Europe/Berlin", None)
        assert tz == "Europe/Berlin"
        assert locale == "ja-JP"
+
+    @patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("America/New_York", "en-US"))
+    def test_geoip_normalizes_bare_proxy_with_creds(self, mock_geo):
+        # "user:pass@host:port" must be normalized to http:// before geoip lookup.
+        tz, locale = maybe_resolve_geoip(True, "user:pass@proxy:8080", None, None)
+        mock_geo.assert_called_once_with("http://user:pass@proxy:8080")
+        assert tz == "America/New_York"
+        assert locale == "en-US"
+
+    @patch("cloakbrowser.geoip.resolve_proxy_geo", return_value=("America/New_York", "en-US"))
+    def test_geoip_normalizes_schemeless_proxy_no_creds(self, mock_geo):
+        # "host:port" (no @ and no scheme) must also be normalized.
+        tz, locale = maybe_resolve_geoip(True, "proxy:8080", None, None)
+        mock_geo.assert_called_once_with("http://proxy:8080")
+        assert tz == "America/New_York"
+
+
+class TestBareProxyFormat:
+    """_parse_proxy_url must handle bare 'user:pass@host:port' strings (no scheme)."""
+
+    def test_bare_with_credentials(self):
+        r = _parse_proxy_url("user:pass@proxy:8080")
+        assert r["username"] == "user"
+        assert r["password"] == "pass"
+        assert r["server"] == "http://proxy:8080"
+
+    def test_bare_credentials_not_in_server(self):
+        r = _parse_proxy_url("user:pass@proxy1.example.com:5610")
+        assert "user" not in r["server"]
+        assert "pass" not in r["server"]
+
+    def test_bare_username_only(self):
+        r = _parse_proxy_url("user@proxy:8080")
+        assert r["username"] == "user"
+        assert "password" not in r
+        assert r["server"] == "http://proxy:8080"
+
+    def test_bare_no_port(self):
+        r = _parse_proxy_url("user:pass@proxy.example.com")
+        assert r["username"] == "user"
+        assert r["password"] == "pass"
+        assert r["server"] == "http://proxy.example.com"
+
+    def test_bare_no_credentials_passthrough(self):
+        # "host:port" without @ — no scheme, no creds — pass through unchanged
+        r = _parse_proxy_url("proxy:8080")
+        assert r == {"server": "proxy:8080"}
+
+    def test_build_proxy_kwargs_bare(self):
+        r = _build_proxy_kwargs("user:pass@proxy:8080")
+        assert r["proxy"]["username"] == "user"
+        assert r["proxy"]["password"] == "pass"
+        assert "user" not in r["proxy"]["server"]
@@ -20,6 +20,8 @@ from cloakbrowser.config import (
 )
 from cloakbrowser.download import (
    _check_wrapper_update,
+    _download_and_extract,
+    _fetch_checksums,
    _get_latest_chromium_version,
    _parse_checksums,
    _should_check_for_update,
@@ -474,3 +476,75 @@ class TestWriteVersionMarker:
            marker = tmp_path / f"latest_version_{get_platform_tag()}"
            assert marker.exists()
            assert marker.read_text() == "999.0.0.0"
+
+
+class TestDownloadFallback:
+    """Verify primary server (cloakbrowser.dev) → GitHub Releases fallback on HTTP errors."""
+
+    def test_binary_download_falls_back_on_http_error(self, tmp_path):
+        """HTTP error from primary triggers GitHub Releases fallback for binary download."""
+        with patch.dict(os.environ, {
+            "CLOAKBROWSER_CACHE_DIR": str(tmp_path),
+            "CLOAKBROWSER_DOWNLOAD_URL": "",
+            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
+        }):
+            urls_called = []
+
+            def mock_download_file(url, dest):
+                urls_called.append(url)
+                if "cloakbrowser.dev" in url:
+                    raise Exception("HTTP 429 Too Many Requests")
+                # GitHub fallback succeeds
+                dest.write_bytes(b"fake")
+
+            with patch("cloakbrowser.download._download_file", side_effect=mock_download_file), \
+                 patch("cloakbrowser.download._extract_archive"), \
+                 patch("cloakbrowser.download._show_welcome"):
+                _download_and_extract()
+
+            assert len(urls_called) == 2
+            assert "cloakbrowser.dev" in urls_called[0]
+            assert "github.com" in urls_called[1]
+
+    def test_binary_download_no_fallback_with_custom_url(self, tmp_path):
+        """Custom CLOAKBROWSER_DOWNLOAD_URL disables GitHub fallback — error propagates."""
+        with patch.dict(os.environ, {
+            "CLOAKBROWSER_CACHE_DIR": str(tmp_path),
+            "CLOAKBROWSER_DOWNLOAD_URL": "https://my-mirror.com/releases",
+            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
+        }):
+            with patch("cloakbrowser.download._download_file", side_effect=Exception("503")):
+                with pytest.raises(Exception, match="503"):
+                    _download_and_extract()
+
+    def test_checksum_fetch_falls_back_on_http_error(self):
+        """HTTP error from primary checksum URL triggers GitHub fallback."""
+        valid_checksums = (
+            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+            "  cloakbrowser-linux-x64.tar.gz\n"
+        )
+
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            if "cloakbrowser.dev" in url:
+                resp.raise_for_status.side_effect = Exception("HTTP 429")
+                return resp
+            # GitHub URL succeeds
+            resp.text = valid_checksums
+            resp.raise_for_status = MagicMock()
+            return resp
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}):
+            with patch("cloakbrowser.download.httpx.get", side_effect=mock_get):
+                result = _fetch_checksums()
+
+        assert result is not None
+        assert "cloakbrowser-linux-x64.tar.gz" in result
+
+    def test_checksum_fetch_returns_none_when_both_fail(self):
+        """Both primary and GitHub checksum URLs fail → returns None (skip verification)."""
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}):
+            with patch("cloakbrowser.download.httpx.get", side_effect=Exception("network error")):
+                result = _fetch_checksums()
+
+        assert result is None
Author	SHA1	Message	Date
CloakHQ	d63ddd4d43	feat(cloakserve): add connection tracking, configurable data dir, better status endpoint - Move `import websockets` to top-level (guaranteed by [serve] extra) - Add --data-dir flag with smart default (Docker → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve) - Store launch params (tz/locale/proxy) on ChromeProcess for conflict logging - Enhance GET / to return per-process detail (pid, port, seed, connections, config) - Add connection refcounting in WS handlers for status visibility - Add first-launch-wins note to README - Add tests for data-dir, Docker detection, and connection tracking	2026-04-05 22:41:33 +02:00
CloakHQandDurafen	03a0ad732f	feat: rewrite cloakserve as CDP multiplexer with per-connection fingerprint seeds Spawns a separate Chrome process per unique fingerprint seed, all behind a single port (9222). Clients specify seeds and fingerprint params via query string on the CDP URL: connect_over_cdp("http://host:9222?fingerprint=12345&timezone=Asia/Tokyo") Supports all --fingerprint-* flags as query params, geoip=true for auto timezone/locale from proxy IP, and proxy= for per-process proxies. - Rewrite bin/cloakserve from 57-line wrapper to aiohttp CDP multiplexer - Add ChromePool with per-seed process management and port allocation - Bidirectional WebSocket proxy for CDP traffic - URL rewriting for /json/version, /json/list, and WS paths - Rename _build_args -> build_args, _maybe_resolve_geoip -> maybe_resolve_geoip - Add aiohttp + websockets to serve optional deps - Dockerfile installs .[serve] extras - Add 20 unit tests for cloakserve (param parsing, CLI args, URL rewriting)	2026-04-05 22:30:18 +02:00
CloakHQ	c58b691f1c	chore(deps): bump actions/checkout, docker/setup-qemu, docker/setup-buildx, docker/login-action; group Dependabot PRs	2026-04-05 22:26:14 +02:00
CloakHQ	1b91a33e51	chore: update integration examples and gitignore - browser_use: migrate to BrowserSession + bundled ChatOpenAI API - crawl4ai: add browser_mode="cdp" param - gitignore: add captures/	2026-04-02 01:32:08 +02:00
CloakHQ	1bfd5ca036	docs: update patch count to 42, add --fingerprint-noise flag, bump version refs	2026-03-30 20:46:16 +02:00
CloakHQ	f46f8e9364	release: v0.3.19 — upgrade Linux x64 binary to 145.0.7632.159.8 (42 patches)	2026-03-30 19:17:41 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	592b3d5661	chore(deps): bump docker/build-push-action from 6.19.2 to 7.0.0 (#90 ) Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 6.19.2 to 7.0.0. - [Release notes](https://github.com/docker/build-push-action/releases) - [Commits](https://github.com/docker/build-push-action/compare/10e90e3645eae34f1e60eeb005ba3a3d33f178e8...d08e5c354a6adb9ed34480a06d141179aa583294) --- updated-dependencies: - dependency-name: docker/build-push-action dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-29 22:54:19 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	a0a8210e35	chore(deps): bump actions/setup-python from 5.6.0 to 6.2.0 (#89 ) Bumps [actions/setup-python](https://github.com/actions/setup-python) from 5.6.0 to 6.2.0. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/a26af69be951a213d495a4c3e4e4022e16d87065...a309ff8b426b58ec0e2a45f0f869d46889d02405) --- updated-dependencies: - dependency-name: actions/setup-python dependency-version: 6.2.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-29 22:54:17 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	468964ff30	chore(deps): bump actions/setup-node from 4.4.0 to 6.3.0 (#88 ) Bumps [actions/setup-node](https://github.com/actions/setup-node) from 4.4.0 to 6.3.0. - [Release notes](https://github.com/actions/setup-node/releases) - [Commits](https://github.com/actions/setup-node/compare/49933ea5288caeca8642d1e84afbd3f7d6820020...53b83947a5a98c8d113130e565377fae1a50d02f) --- updated-dependencies: - dependency-name: actions/setup-node dependency-version: 6.3.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-29 22:54:15 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	c1b93e634b	chore(deps): bump sigstore/cosign-installer from 3.9.1 to 4.1.1 (#87 ) Bumps [sigstore/cosign-installer](https://github.com/sigstore/cosign-installer) from 3.9.1 to 4.1.1. - [Release notes](https://github.com/sigstore/cosign-installer/releases) - [Commits](https://github.com/sigstore/cosign-installer/compare/398d4b0eeef1380460a10c8013a76f728fb906ac...cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003) --- updated-dependencies: - dependency-name: sigstore/cosign-installer dependency-version: 4.1.1 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-29 22:54:12 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	5ccb4a32a5	chore(deps): bump actions/attest-build-provenance from 2.4.0 to 4.1.0 (#86 ) Bumps [actions/attest-build-provenance](https://github.com/actions/attest-build-provenance) from 2.4.0 to 4.1.0. - [Release notes](https://github.com/actions/attest-build-provenance/releases) - [Changelog](https://github.com/actions/attest-build-provenance/blob/main/RELEASE.md) - [Commits](https://github.com/actions/attest-build-provenance/compare/e8998f949152b193b063cb0ec769d69d929409be...a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32) --- updated-dependencies: - dependency-name: actions/attest-build-provenance dependency-version: 4.1.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-29 22:54:10 +02:00
CloakHQ	49d80d3b57	security: pin GitHub Actions to commit SHAs, add Dependabot Pin all 22 action references across ci.yml, publish.yml, and attest-release.yml to immutable commit SHAs. Mutable tags can be force-pushed by attackers (cf. TeamPCP supply chain campaign). Add Dependabot for github-actions to get weekly PRs when pinned actions have new versions.	2026-03-27 21:20:08 +01:00
CloakHQ	2813b3dc4c	docs: warn that ElementHandle bypasses humanize patches	2026-03-18 07:51:07 +01:00
dgtlmoonandGitHub	6550f3ad6c	fix: ensure pw.stop() runs even if browser.close() raises or is cancelled (#60 )	2026-03-15 17:51:03 +01:00
CloakHQ	132cafe13c	release: v0.3.18 — fix welcome banner polluting stdout (fixes #59 )	2026-03-15 17:19:44 +01:00
CloakHQ	6c94b9e985	feat: add GitHub issue template for bug reports	2026-03-15 07:11:33 +01:00
CloakHQ	fdc1ae0484	fix: add --ignore-gpu-blocklist to cloakserve for Docker WebGL support cloakserve bypasses the wrapper and launches Chrome directly, missing the GPU blocklist fix from `1380c86`. Fixes #58.	2026-03-15 06:02:47 +01:00
CloakHQ	2ded0c1866	docs: add Crawlee integration example	2026-03-15 05:42:23 +01:00
CloakHQ	f91700c4a4	release: v0.3.17 — Windows x64 binary upgrade to 145.0.7632.159.7 - Bump wrapper version to 0.3.17 (Python + JS) - Update PLATFORM_CHROMIUM_VERSIONS: windows-x64 109.2 → 159.7 - Update patch counts in platform tables (Linux 33, Windows 33) - Add Linux arm64 to JS README platform table - Update CHANGELOG with all changes since v0.3.16	2026-03-15 02:42:13 +01:00
CloakHQ	1380c86847	fix: auto-inject --ignore-gpu-blocklist for headed mode and Windows Headed mode (all platforms): Chromium's GPU blocklist disables WebGL on software GPUs in Docker/VNC/Xvfb. Flag lets SwiftShader serve WebGL. Harmless on real GPUs. Headless unaffected. Ref #56. Windows (all modes): GPU blocklist also blocks WebGPU for the Microsoft Basic Render Driver. Dawn's adapter_blocklist bypass alone isn't enough.	2026-03-15 02:23:48 +01:00
CloakHQ	83e3b30117	feat: add 8 framework integration examples + README integrations section Add examples/integrations/ with tested examples for browser-use, Crawl4AI, Scrapling, LangChain, Selenium, undetected-chromedriver, and agent-browser. Add js/examples/stagehand.ts for Stagehand (TypeScript). README: new "Framework Integrations" subsection with two integration patterns (direct binary launch vs CDP connect) and table linking all 8 examples.	2026-03-14 20:56:25 +01:00
CloakHQ	5649620545	release: v0.3.16 — Linux ARM64 binary, multi-arch Docker, donate link - Add linux-arm64 to PLATFORM_CHROMIUM_VERSIONS (Python + JS) - Multi-arch Docker build (linux/amd64 + linux/arm64) via QEMU in CI - Add ko-fi donate link to welcome banner (Python + JS) - Version bump to 0.3.16	2026-03-14 00:42:06 +01:00
CloakHQ	d2a42fc86b	release: v0.3.15 — upgrade Linux binary to .159.7, StorageBuckets normalization Binary: - Upgrade Linux x64 build to Chromium 145.0.7632.159.7 (33 C++ patches) - StorageBuckets API quota normalization — closes last storage-based incognito detection vector Wrapper: - Fix non-ASCII character support in humanized typing (Cyrillic, CJK, emoji) - Document storage quota tradeoff for persistent contexts - Add Ko-fi funding link	2026-03-13 18:59:18 +01:00
lilos	1af25d67bc	fix: support non-ASCII characters (Cyrillic, CJK, emoji) in humanized typing	2026-03-13 00:34:01 +01:00
CloakHQ	1bef989404	test: add download fallback tests for primary → GitHub failover Verify that HTTP errors (429, 503, etc.) from cloakbrowser.dev correctly trigger GitHub Releases fallback for both binary and checksum downloads. Also test that custom CLOAKBROWSER_DOWNLOAD_URL disables fallback, and both-sources-fail returns gracefully.	2026-03-12 19:47:49 +01:00
CloakHQ	0aa4ea56bd	docs: add Browser Profile Manager section to README	2026-03-12 01:58:26 +01:00
CloakHQ	c0ba21faa1	release: v0.3.14 — upgrade Linux binary to .159.6, add binary management CLI Binary: - Upgrade Linux build to 145.0.7632.159.6 (32 patches) - Fix persistent context fingerprint consistency - Storage quota normalization for persistent context profiles - Fix window dimension calculation for non-incognito contexts Wrapper: - Add CLI for binary management with visible download progress (closes #43) - Python: python -m cloakbrowser install\|info\|update\|clear-cache - JavaScript: npx cloakbrowser install\|info\|update\|clear-cache	2026-03-11 23:44:41 +01:00
CloakHQ	b501d8f158	chore: gitignore browser profile manager directory	2026-03-11 18:13:19 +01:00
CloakHQ	6007a6e511	feat: add CLI for binary management (Python + JavaScript) Adds install, info, update, and clear-cache subcommands with visible download progress. Python: `python -m cloakbrowser install`. JavaScript: `npx cloakbrowser install`. Useful for Dockerfiles where silent first-use downloads are hard to debug. Closes #43.	2026-03-11 04:33:37 +01:00
CloakHQ	96c55352e0	ci: remove deployment environments from publish workflow to hide actor identity	2026-03-11 00:22:57 +01:00
CloakHQ	5d35fb9e4c	release: v0.3.13 — suppress SwiftShader default arg, upgrade Linux binary to .159.5	2026-03-10 23:11:12 +01:00
CloakHQ	c966e046e7	docs: add Docker signature verification, deployment environments, improve troubleshooting - Add cosign verify command to README Security section for Docker image verification - Add GitHub deployment environments (pypi, npm, docker) to publish workflow for sidebar status tracking - Simplify downgrade instructions: version-pinned pip/npm/docker instead of manual binary paths - Improve troubleshooting section with headings and dividers for readability - Update Latest section to v0.3.12 with new binary features	2026-03-10 07:27:18 +01:00
CloakHQ	767eb16a82	release: v0.3.12 — locale spoofing patch, WebGPU hardening, binary flags for tz/locale Binary: 145.0.7632.159.4 (linux), 32 patches. Wrapper: bare proxy format, ANGLE GPU strings, README updates.	2026-03-10 06:27:16 +01:00
CloakHQ	04255cf412	fix: use binary flags for timezone/locale instead of detectable CDP emulation - Remove locale and timezone_id from Playwright context kwargs (CDP) - Pass timezone via --fingerprint-timezone binary flag (process-wide) - Pass locale via --lang + --fingerprint-locale binary flags - Accept both timezone and timezone_id param names silently (no deprecation) - Update all wrapper tests to verify binary args, not CDP context params	2026-03-10 03:56:57 +01:00
CloakHQ	1fb554e061	fix: support bare proxy format (user:pass@host:port) without scheme Normalize bare proxy strings by prepending http:// before parsing when @ is present but :// is absent. Tests added for Python and JS.	2026-03-09 19:35:07 +01:00
CloakHQ	748013bf83	fix: use ANGLE-wrapped GPU strings for realistic WebGL fingerprint Bare vendor/renderer strings are detectable — real Chrome reports ANGLE-wrapped values through WebGL's getParameter API.	2026-03-09 02:25:33 +01:00
CloakHQ	eeea366047	ci: upgrade npm for OIDC trusted publishing (requires npm >= 11.5.1)	2026-03-08 23:54:18 +01:00