release: v0.3.19 — upgrade Linux x64 binary to 145.0.7632.159.8 (42 patches)

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-06-23 11:41:46 +02:00 · 2026-03-30 19:17:41 +02:00 · 2026-03-29 22:54:19 +02:00 · 2026-03-29 22:54:17 +02:00 · 2026-03-29 22:54:15 +02:00 · 2026-03-29 22:54:12 +02:00
53 changed files with 1650 additions and 320 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,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
@@ -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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - 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@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
      - 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@c7c53464625b32c7a7e944ae62b3e17d2b600130  # v3
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+      - uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
        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,6 +56,9 @@ test-infra/
 # Website (deployed separately)
 site/

+# Browser profile manager (deployed separately)
+manager/
+
 # Release scripts
 publish.sh
 deploy.sh
@@ -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))
@@ -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
+- **33 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.17 (Chromium 145.0.7632.159.7)

 - **`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
+- **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
+- **33 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 33 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,6 +569,8 @@ 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 |
 | `--enable-blink-features=FakeShadowRoot` | Access closed shadow DOM elements |
@@ -568,14 +612,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 |
+| 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 |

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

@@ -705,6 +779,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 +800,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 +827,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 +863,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 +874,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:

@@ -907,19 +1001,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.7

-# 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
@@ -33,6 +33,9 @@ chrome_args = [
    "--disable-popup-blocking",
    "--disable-background-networking",
    "--metrics-recording-only",
+    # GPU blocklist bypass: Chromium blocks WebGL on software GPUs in
+    # Docker/Xvfb. Without this, WebGL vendor/renderer spoofing fails. #58
+    "--ignore-gpu-blocklist",
 ] + get_default_stealth_args() + sys.argv[1:]

 chrome = subprocess.Popen(chrome_args)
@@ -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:
@@ -104,7 +102,7 @@ def launch(

    binary_path = ensure_binary()
    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=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

@@ -187,7 +187,7 @@ async def launch_async(  # noqa: C901

    binary_path = ensure_binary()
    timezone, locale = _maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    chrome_args = _build_args(stealth_args, args, timezone=timezone, locale=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)
+    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)
+    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
+    # resolved values flow to binary flags
    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.
+    # --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,6 +585,11 @@ def _import_async_playwright(backend: str):
 # ---------------------------------------------------------------------------


+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,
@@ -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
@@ -613,6 +619,7 @@ def _build_args(
    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,43 @@
+"""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 langchain-openai
+Set OPENAI_API_KEY (or swap for another LLM provider).
+"""
+
+import asyncio
+
+from browser_use import Agent, Browser, BrowserConfig
+from langchain_openai import 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
+    config = BrowserConfig(cdp_url="http://127.0.0.1:9242")
+    browser = Browser(config=config)
+
+    # 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=browser,
+    )
+
+    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(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
+- **33 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
@@ -58,6 +58,9 @@ geoip = ["geoip2>=4.0"]
 patchright = ["patchright>=1.40"]
 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,8 +1,6 @@
-"""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():
@@ -12,9 +10,10 @@ def test_timezone_injected():


 def test_locale_injected():
-    """--lang flag should appear when locale is set."""
+    """--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():
@@ -22,6 +21,7 @@ def test_both_injected():
    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():
@@ -29,15 +29,17 @@ def test_timezone_independent_of_stealth_args():
    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."""
+    """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():
@@ -46,52 +48,41 @@ def test_extra_args_preserved():
    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 ---
@@ -126,15 +117,18 @@ def test_timezone_param_overrides_user_arg():


 def test_locale_param_overrides_user_arg():
-    """Dedicated locale param should override user --lang arg."""
+    """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():
@@ -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")
@@ -119,40 +118,37 @@ def test_color_scheme(mock_launch, _mock_bin):
@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
@@ -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,12 +94,12 @@ 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")
@@ -120,7 +119,7 @@ def test_persistent_context_color_scheme(_mock_geoip, _mock_bin):
@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,25 +127,26 @@ 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")
@@ -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
@@ -98,3 +98,56 @@ class TestMaybeResolveGeoip:
        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	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