From 23ae521832e716255d887869713153831eb9d543 Mon Sep 17 00:00:00 2001
From: CloakHQ <cloakhq@pm.me>
Date: Mon, 23 Feb 2026 18:11:28 +0100
Subject: [PATCH] docs: add headed mode guide, JS roadmap, bump to 0.1.5

- Add Headed Mode section for DataDome/Cloudflare Turnstile sites
- Add Xvfb setup instructions + residential proxy tip
- Add JavaScript/Puppeteer support to roadmap
---
 README.md                | 28 ++++++++++++++++++++++++++++
 cloakbrowser/_version.py |  2 +-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d97001d..6d3bb86 100644
--- a/README.md
+++ b/README.md
@@ -244,6 +244,7 @@ See the [`examples/`](examples/) directory:
 | Linux x64 binary | ✅ Released |
 | macOS arm64 (Apple Silicon) | 🔜 In progress |
 | Chromium 145 build | 🔜 In progress |
+| JavaScript/Puppeteer support (`cloakbrowser-js`) | 📋 Planned |
 | Fingerprint rotation per session | 📋 Planned |
 | Built-in proxy rotation | 📋 Planned |
 | Windows support | 📋 Planned |
@@ -274,6 +275,33 @@ CMD ["python", "your_script.py"]
 
 **Note:** If you run CloakBrowser inside a web server with uvloop (e.g., `uvicorn[standard]`), use `--loop asyncio` to avoid subprocess pipe hangs.
 
+## Headed Mode (for aggressive bot detection)
+
+Some sites using advanced bot detection (e.g., DataDome, Cloudflare Turnstile) can detect headless mode even with our C++ patches. For these sites, run in **headed mode** with a virtual display:
+
+```bash
+# Install Xvfb (virtual framebuffer)
+sudo apt install xvfb
+
+# Start virtual display
+Xvfb :99 -screen 0 1920x1080x24 &
+export DISPLAY=:99
+```
+
+```python
+from cloakbrowser import launch
+
+# Headed mode + residential proxy for maximum stealth
+browser = launch(headless=False, proxy="http://your-residential-proxy:port")
+page = browser.new_page()
+page.goto("https://heavily-protected-site.com")  # passes DataDome, etc.
+browser.close()
+```
+
+This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combined with a residential proxy, this passes even the most aggressive detection services.
+
+> **Tip:** Datacenter IPs are often flagged by IP reputation databases regardless of browser fingerprint. For sites with strict bot detection, a residential proxy makes the difference.
+
 ## Troubleshooting
 
 **Binary download fails / timeout**
diff --git a/cloakbrowser/_version.py b/cloakbrowser/_version.py
index bbab024..1276d02 100644
--- a/cloakbrowser/_version.py
+++ b/cloakbrowser/_version.py
@@ -1 +1 @@
-__version__ = "0.1.4"
+__version__ = "0.1.5"