grewbrowser 0.1.0__tar.gz

grewbrowser-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+examples/profiles/
+profiles/
+.grewbrowser/
+.DS_Store
+Thumbs.db
+*.log
+
+examples/deof/
+examples/extensions/

grewbrowser-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-11-14
+
+First release. 🎉
+
+### Added
+
+- **Own managed browser** — `grewbrowser install` fetches a full Chromium from
+  Google's Chrome for Testing host into `~/.grewbrowser`. No
+  `playwright install` required, and a fresh machine downloads it automatically
+  on the first launch (`GREWBROWSER_AUTO_DOWNLOAD=0` turns that off).
+- **Four launchers** — `launch`, `launch_async`,
+  `launch_persistent_context`, `launch_persistent_context_async`, each
+  returning a session that owns its driver, browser, context, relay and
+  profile directory.
+- **One seed, one identity** — `BrowserProfile` derives the user agent, client
+  hints, platform, screen, viewport, GPU strings, core count and memory from a
+  single seed; a persistent profile pins that seed in
+  `<user_data_dir>/.grewbrowser-seed`.
+- **Stealth flags** — automation flags suppressed, hardware ANGLE backend per
+  platform (D3D11 / Metal / GL), GPU blocklist bypassed, WebRTC restricted to
+  the proxy, renderer backgrounding and timer throttling disabled.
+- **Fingerprint injection** — prototype-level patches with native-looking
+  `toString`, seed-deterministic canvas and audio noise, a `chrome` object that
+  matches a real Chrome (including the absence of `chrome.runtime`), and
+  patched iframe realms.
+- **Human input layer** — `human_click`, `human_type`, `human_fill`,
+  `human_scroll`, `human_move`, `human_idle`: Bézier pointer paths with
+  Fitts'-law timing and corrective sub-strokes, keystroke intervals that depend
+  on the key pair with corrected typos, and wheel scrolling in real platform
+  notches. Actionability probes run in a CDP isolated world.
+- **Network identity** — proxy exit-IP lookup that sets timezone, locale and
+  coordinates to match; a loopback relay that holds proxy credentials so the
+  browser never sees a 407.
+- **Session management** — `BrowserPool` and `SyncBrowserPool` with a
+  concurrency semaphore and a launch-rate token bucket; a teardown guard with
+  `atexit` and signal hooks that kills the whole browser process tree.
+- **Self-check** — `grewbrowser check` runs 110 probes per mode and prints
+  headless against headful side by side.
+- **One driver per thread** — several synchronous sessions can be open at once
+  in the same thread; they share a reference-counted Playwright driver that
+  stops when the last session closes.
+- **Platforms** — Windows, Linux and macOS, with CI running the full suite on
+  all three.

grewbrowser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 X2Super
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grewbrowser-0.1.0/PKG-INFO

@@ -0,0 +1,531 @@
+Metadata-Version: 2.5
+Name: grewbrowser
+Version: 0.1.0
+Summary: Stealth Chromium for Playwright: coherent fingerprints, geo-matched identities, human-paced input, and its own managed browser.
+Project-URL: Homepage, https://github.com/x2super/grewbrowser
+Project-URL: Documentation, https://github.com/x2super/grewbrowser#readme
+Project-URL: Source, https://github.com/x2super/grewbrowser
+Project-URL: Issues, https://github.com/x2super/grewbrowser/issues
+Project-URL: Changelog, https://github.com/x2super/grewbrowser/blob/main/CHANGELOG.md
+Author-email: x2super <august260853@gmail.com>
+Maintainer-email: x2super <august260853@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 X2Super
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: automation,browser,chromium,fingerprint,playwright,scraping,stealth,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: playwright>=1.45
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: psutil>=5.9; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: process
+Requires-Dist: psutil>=5.9; extra == 'process'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/images/banner.svg" alt="grewbrowser" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/x2super/grewbrowser/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/x2super/grewbrowser/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/grewbrowser/"><img alt="PyPI" src="https://img.shields.io/pypi/v/grewbrowser.svg?color=1f6feb"></a>
+  <a href="https://pypi.org/project/grewbrowser/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/grewbrowser.svg"></a>
+  <img alt="Platforms" src="https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macos-8957e5">
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-3fb950"></a>
+</p>
+
+<p align="center">
+  <b>Stealth Chromium for Playwright.</b><br>
+  One call gives you a browser whose flags, fingerprint, timezone, locale and input behaviour<br>
+  all describe the same machine in the same place — instead of a default automation profile with patches bolted on.
+</p>
+
+---
+
+## ⚡ Sixty seconds
+
+```bash
+pip install grewbrowser
+grewbrowser install
+```
+
+```python
+from grewbrowser import launch
+
+with launch() as session:
+    page = session.new_page()
+    page.goto("https://example.com")
+
+    page.human_click("#login")
+    page.human_type("#email", "someone@example.com")
+    page.human_scroll(600)
+```
+
+That is the whole setup. No `playwright install`, no flag lists, no fingerprint JSON to maintain.
+
+> 💡 **Fresh machine?** You do not even need `grewbrowser install` — the first
+> `launch()` fetches the browser automatically. Set `GREWBROWSER_AUTO_DOWNLOAD=0`
+> if you would rather it never touched the network.
+
+---
+
+## ✨ What actually changes
+
+| | Plain Playwright | grewbrowser |
+|---|---|---|
+| 🤖 **Automation flags** | `--enable-automation`, `navigator.webdriver` set | suppressed, no infobar, no `webdriver` |
+| 🎮 **GPU** | SwiftShader — a renderer string no real user has | hardware ANGLE: D3D11 / Metal / GL, blocklist bypassed |
+| 📡 **WebRTC** | UDP candidates escape the proxy | `disable_non_proxied_udp` + permission check |
+| 🔑 **Proxy auth** | a `407` round trip on every tunnel | credentials held by a loopback relay, zero challenges |
+| 🌍 **Timezone & locale** | your machine's | resolved from the proxy's **exit** address |
+| 🖱️ **`click()`** | teleports to the exact centre, presses instantly | Bézier path, ~60 Hz events, overshoot + correction, aim pause |
+| ⌨️ **`fill()`** | sets `value`, zero key events | per-key intervals that depend on the key pair, typos that get fixed |
+| 🖲️ **`wheel(0, 2000)`** | one impossible 2000px event | real platform notches with ramp-up and ramp-down |
+| 🔍 **Actionability checks** | run in the page's own world | run in a CDP **isolated world** the page cannot see |
+| 💥 **Crash** | leaked browser + profile directory | `atexit` + signal hooks kill the whole process tree |
+| 🧪 **Proof** | — | `grewbrowser check`: 110 probes, headless vs headful |
+
+---
+
+## 📦 Install
+
+```bash
+pip install grewbrowser
+pip install "grewbrowser[process]"
+```
+
+`[process]` adds `psutil`, which lets the teardown guard kill a browser process
+tree even if the driver dies first. Recommended for anything long-running.
+
+### Getting a browser 🌐
+
+grewbrowser manages its own Chromium, so a fresh machine needs nothing else:
+
+```bash
+grewbrowser install
+grewbrowser install --version 157.0.8103.78
+grewbrowser install --source chromium-snapshots
+grewbrowser list
+grewbrowser info
+grewbrowser clean
+```
+
+Builds land in `~/.grewbrowser` (override with `GREWBROWSER_CACHE_DIR`) and come
+from Google's official Chrome for Testing host.
+
+### Picking a browser 🎛️
+
+| `channel=` | What it uses | Downloads? |
+|---|---|---|
+| `"auto"` *(default)* | cached own build → Playwright Chromium → system Chrome → Edge | only if nothing at all is found |
+| `"own"` | grewbrowser's own Chromium | yes, on demand |
+| `"chromium"` | Playwright's Chromium **only** | no — fails with a hint |
+| `"chrome"` / `"chrome-beta"` | that system install only | no |
+| `"chromium-system"` | `/usr/bin/chromium` and friends | no |
+| `"msedge"` | system Edge | no |
+| `executable_path=...` | your own binary | no |
+
+Named channels are strict on purpose: asking for Chromium and silently getting
+Chrome would mean a different build, version and GPU strings than you asked for.
+
+---
+
+## 🚀 Usage
+
+<details open>
+<summary><b>Sync</b></summary>
+
+```python
+from grewbrowser import launch
+
+with launch(headless=True, proxy="http://user:pass@gateway:8080") as session:
+    print(session.profile.timezone_id, session.profile.locale)
+    page = session.new_page()
+    page.goto("https://example.com")
+    page.human_click("button[type=submit]")
+```
+</details>
+
+<details>
+<summary><b>Async</b></summary>
+
+```python
+import asyncio
+from grewbrowser import launch_async
+
+async def main():
+    session = await launch_async(headless=True)
+    try:
+        page = await session.new_page()
+        await page.goto("https://example.com")
+        await page.human_type("#q", "hello")
+        await page.human_scroll(500)
+    finally:
+        await session.close()
+
+asyncio.run(main())
+```
+</details>
+
+<details>
+<summary><b>Persistent identity</b></summary>
+
+```python
+from grewbrowser import launch_persistent_context
+
+session = launch_persistent_context("./profiles/alice", headless=False)
+```
+
+Cookies **and** fingerprint live together: the seed is pinned in
+`<user_data_dir>/.grewbrowser-seed` on the first run and read back afterwards.
+Delete that one file to re-roll the identity while keeping the cookies.
+</details>
+
+<details>
+<summary><b>Many at once</b></summary>
+
+```python
+from grewbrowser import BrowserPool
+
+async def scrape(session, url):
+    page = await session.new_page()
+    await page.goto(url)
+    return await page.title()
+
+async with BrowserPool(max_concurrent=4, launches_per_minute=30, proxy=PROXY) as pool:
+    titles = await pool.map(urls, scrape)
+```
+
+`max_concurrent` bounds live browsers; `launches_per_minute` bounds cold starts
+— a separate problem, because a hundred simultaneous starts thrash the disk even
+when a hundred live browsers would fit in memory. `SyncBrowserPool` does the
+same across a thread pool.
+</details>
+
+---
+
+## 🧬 How one launch works
+
+<p align="center"><img src="docs/images/flow.svg" alt="launch pipeline" width="100%"></p>
+
+The order is the point. Each step feeds the next, so nothing has to be patched
+after the fact:
+
+1. 🔌 **Proxy** — parsed once into a form that can produce a *credential-free* URL.
+2. 🌍 **GeoIP** — the exit address is resolved **before** the identity is built, so
+   timezone and locale are part of it rather than bolted on after the first page
+   already loaded. `geoip="strict"` raises instead of warning.
+3. 🎲 **Seed** — one number. A persistent directory pins it; an explicit `seed=`
+   reproduces a run exactly.
+4. 🧍 **Profile** — user agent, client hints, platform, screen, viewport, GPU
+   strings, cores and memory, all derived from that seed **and from the real
+   binary's version**, so a 157 build never claims to be 139.
+5. 🚩 **Flags** — built by one merge function that de-duplicates by flag key, so a
+   flag can never be present on one launch path and missing on another.
+6. 🛰️ **Relay** — a loopback HTTP relay holds the proxy credentials and attaches
+   `Proxy-Authorization` upstream, so Chromium never sees a `407`.
+7. 🖥️ **Launch** — `--headless=new`, the real browser without a window, never the
+   stripped headless shell.
+8. 🧪 **Inject** — the fingerprint layer, applied to every realm.
+9. 🖱️ **Humanize** — Playwright's input primitives are replaced.
+
+---
+
+## 🕵️ The fingerprint layer
+
+Each rule closes a specific, cheap detection:
+
+- 🧬 **Prototype, never instance** — every patch is a getter on
+  `Navigator.prototype`, so `Object.getOwnPropertyNames(navigator)` stays empty.
+  An own property on the instance is visible in one line of JavaScript.
+- 🎭 **Native source** — a single patched `Function.prototype.toString` reports
+  `[native code]` for every replacement, and it **delegates to the parent realm**,
+  which closes the classic escape of borrowing a fresh iframe's `toString` and
+  calling it on a patched getter.
+- 🖼️ **Every realm** — dynamic `about:blank` iframes, `srcdoc`, nested frames and
+  `window.frames["name"]`, each verified separately.
+- 🎨 **Deterministic noise** — canvas and audio noise derives from the session
+  seed, so reading the same canvas twice returns the same bytes, exactly as a
+  real GPU does. Random-per-call noise is itself a signal.
+- 🧩 **Fill gaps, do not invent** — on a real Chrome the `chrome` object is left
+  alone, `chrome.runtime` **included**: it genuinely does not exist on a normal
+  page, and a stub that adds it stands out more than no stub at all.
+- 📋 **Headers agree with JavaScript** — client hints are set through CDP and that
+  session is kept alive for the page's lifetime, because detaching reverts the
+  override and leaves `Sec-CH-UA` disagreeing with `navigator.userAgentData`. The
+  brand list is copied from a real Chrome on the wire, GREASE entry and order
+  included.
+
+---
+
+## 🖱️ The human layer
+
+<p align="center"><img src="docs/images/pointer-path.svg" alt="a real human_click path" width="100%"></p>
+
+Timings are not invented. Inter-key intervals and hold times follow the
+distributions reported for 136M keystrokes (Dhakal et al., CHI 2018); pointing
+movements follow Fitts' law with the fast-stroke-plus-correction structure from
+the sub-movement literature — which is why a long move sometimes misses and
+lands with a short second stroke.
+
+<p align="center"><img src="docs/images/wheel.svg" alt="wheel notches" width="100%"></p>
+
+```python
+page.human_click("#go")
+page.human_type("#email", "a@b.com")
+page.human_fill("#email", "a@b.com")
+page.human_scroll(600)
+page.human_move(400, 300)
+page.human_idle(1.5)
+page.human
+```
+
+Tuning:
+
+```python
+launch(humanize="careful")
+launch(humanize="brisk")
+launch(humanize={"typing_delay": 90})
+launch(humanize=HumanConfig(mistype_chance=0.0))
+launch(humanize=False)
+```
+
+Failures are specific — `ElementNotVisibleError`, `ElementNotStableError`,
+`ElementNotEditableError`, `ElementNotReceivingEventsError` — so a failing
+selector tells you *why*, not just that it timed out.
+
+---
+
+## 🌍 Proxy, geo and the relay
+
+```python
+launch(proxy="http://user:pass@gateway:8080")
+launch(proxy={"server": "http://gw:8080", "username": "u", "password": "p"})
+launch(proxy=PROXY, geoip="strict")
+launch(proxy=PROXY, geoip=False, timezone_id="Asia/Bangkok", locale="th-TH")
+```
+
+- 🛰️ The relay listens on `127.0.0.1` with **no** authentication of its own and
+  attaches `Proxy-Authorization` upstream. Chromium gets a plain
+  `--proxy-server=http://127.0.0.1:<port>`, so no password reaches a child
+  process and no tunnel starts with a `407`.
+- 🌐 The geo lookup runs **through the proxy**, because the gateway and the exit
+  are frequently different hosts in different countries. It sends no identifiers
+  and can be turned off entirely.
+- 🧦 SOCKS proxies skip both — Chromium cannot authenticate SOCKS on the command
+  line either, and `urllib` cannot route the lookup. Pass `timezone_id` and
+  `locale` yourself there.
+
+---
+
+## ✅ Proving it
+
+<p align="center"><img src="docs/images/selfcheck.svg" alt="grewbrowser check output" width="100%"></p>
+
+```bash
+grewbrowser check
+grewbrowser check --mode headless
+grewbrowser check --url https://your-own-site.example
+```
+
+Probes are split into two tiers, which matters the moment you run this on a
+server:
+
+- **coherence** — everything grewbrowser controls and must always get right.
+  A failure here is a defect, and it is what the exit code reflects.
+- **this machine** — properties of the host that no patching can create: a
+  hardware GPU, installed fonts, speech-synthesis voices. A GPU-less CI box
+  legitimately fails these, and that is reported, not treated as a bug.
+
+Each tier is printed with a `<- differs` marker on any check where headless and
+headful disagree. Everything runs against a page served from loopback, so there
+is no network call and no third-party scoring service — loopback is also a
+*secure context*, which `about:blank` is not, and without it `mediaDevices` and
+WebGPU would look missing when they are merely unavailable on an insecure origin.
+
+It covers the identity, window geometry, the GPU, canvas and audio noise,
+permissions, media devices, WebRTC candidate types, all four iframe realm types
+plus the cross-realm `toString` escape, the known headless tells (fonts,
+speech-synthesis voices, `navigator.connection`, battery API, hover and pointer
+media queries, screen orientation, shader precision), the agreement between what
+the browser **sent** and what JavaScript **says**, and the input layer.
+
+`run_checks()` is importable if you would rather assert on it in your own tests.
+
+> ⚠️ This measures **self-consistency**, not a bot-detection score. It is not a
+> CAPTCHA bypass and makes no claim about any anti-bot vendor.
+
+---
+
+## 🧩 Extensions
+
+```python
+launch_persistent_context("./profiles/x", extension_paths=["./my_extension"])
+```
+
+Extensions need a **persistent context**, not a headful one. `--headless=new`
+loads them fine, but `launch()` builds a non-persistent context, which Chromium
+treats as incognito and does not run content scripts in — while the service
+worker still starts, so it *looks* loaded when it is not. grewbrowser warns if
+you use the wrong one.
+
+`examples/demo_extension/` is a two-line extension that marks each page, so you
+can prove loading works before trusting it with a real one.
+
+---
+
+## 🖥️ Platforms
+
+| | Windows | Linux | macOS |
+|---|:---:|:---:|:---:|
+| Own Chromium download | ✅ | ✅ | ✅ |
+| ANGLE backend | D3D11 | GL | Metal |
+| Wheel notch | 100px | 120px | 40px |
+| Process-tree teardown | `taskkill /T` | `killpg` | `killpg` |
+| CI, offline + live | ✅ | ✅ *(Xvfb)* | ✅ |
+
+Linux arm64 has no published Chrome for Testing build — use `executable_path=`
+with your own. Headful on Linux needs `DISPLAY` or `WAYLAND_DISPLAY`;
+grewbrowser warns when neither is set.
+
+---
+
+## ⚙️ Reference
+
+### Launch arguments
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `headless` | `True` | `--headless=new`, the real browser without a window |
+| `proxy` | `None` | URL string or Playwright mapping |
+| `geoip` | `True` | `True` warns on failure, `"strict"` raises, `False` skips |
+| `humanize` | `True` | preset name, `HumanConfig`, mapping of overrides, or `False` |
+| `seed` | random | same seed, same identity |
+| `os_family` | host's | `"windows"` / `"darwin"` / `"linux"` |
+| `locale`, `timezone_id` | from geo | override the lookup |
+| `viewport`, `screen` | derived | layout viewport and screen resolution |
+| `channel` | `"auto"` | see the channel table |
+| `executable_path` | `None` | your own binary |
+| `args` | `None` | extra flags; these **win** over the stealth defaults |
+| `stealth_args` | `True` | include the stealth flag list at all |
+| `inject_fingerprint` | auto | off automatically for a patched Chromium |
+| `relay` | `True` | move proxy credentials to the loopback relay |
+| `native_viewport` | `True` | viewport follows the real window instead of being emulated |
+| `extension_paths` | `None` | unpacked extensions (persistent contexts) |
+| `permissions` | `None` | granted up front |
+| `**context_kwargs` | — | passed straight to `new_context` |
+
+### Environment
+
+| Variable | Effect |
+|---|---|
+| `GREWBROWSER_BINARY_PATH` | use this executable, above everything else |
+| `GREWBROWSER_AUTO_DOWNLOAD` | `0` stops `channel="auto"` from ever downloading |
+| `GREWBROWSER_CACHE_DIR` | where managed builds live (default `~/.grewbrowser`) |
+| `GREWBROWSER_PATCHED_BINARY` | `1` marks the binary as a fingerprint-patched build |
+| `GREWBROWSER_GEOIP_TIMEOUT` | seconds per geo provider (default 8) |
+
+### Modules
+
+| Module | Responsibility |
+|---|---|
+| `core.profile` | one seed in, one coherent identity out |
+| `core.flags` | `build_stealth_args`, the flag merge, seed pinning |
+| `core.binary_manager` | discovery: explicit path → env → own build → Playwright → system |
+| `core.download` | fetching and caching grewbrowser's own Chromium |
+| `fingerprint.scripts` | the injected payload |
+| `fingerprint.applier` | context options and the CDP client-hint override |
+| `behavior.curves` / `.keyboard` | pure motion and keystroke planning |
+| `behavior.world` | CDP isolated worlds for actionability probes |
+| `behavior.human` | the engines and the `human_*` page methods |
+| `network.proxy` / `.geoip` / `.relay` | proxy parsing, exit lookup, credential relay |
+| `session.pool` / `.teardown` | concurrency limits and guaranteed cleanup |
+| `diagnostics` | the self-check probes |
+
+Every module stands alone: `build_stealth_args` without launching, `resolve_geo`
+without a browser, `humanize_page(page)` on a page you opened yourself.
+
+---
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/x2super/grewbrowser
+cd grewbrowser
+pip install -e ".[dev]"
+
+pytest tests/test_offline.py -q     # no browser needed
+grewbrowser install
+pytest tests/test_live.py -q        # launches a real browser
+grewbrowser check
+```
+
+CI runs the offline suite on Windows, Linux and macOS across Python 3.10 and
+3.13, and the live suite plus the self-check on all three — Linux under Xvfb.
+
+---
+
+## 🚧 Honest limits
+
+- 🧪 **The fingerprint layer is JavaScript.** Careful JavaScript, but a Chromium
+  patched in C++ is strictly stronger. Point `executable_path` at one and
+  grewbrowser detects it (or set `GREWBROWSER_PATCHED_BINARY=1`) and skips
+  injection rather than overwriting correct native values.
+- 🎭 **Spoofing a foreign OS is supported but not advised.** Fonts and the real
+  GPU come from the host and will contradict the claim.
+- 🌐 **The geo lookup is a third-party request.** It carries no identifiers, and
+  `geoip=False` turns it off.
+- 🧦 **SOCKS** skips the relay and the geo lookup.
+- 🔒 **Chrome for Testing archives carry no publisher signature.** TLS to Google's
+  host is the trust anchor for the download — the same anchor `playwright
+  install` relies on. The archive's SHA-256 is recorded locally so you can see
+  what you got.
+- 🚫 **No CAPTCHA solving and no authentication bypass.** Not included, not
+  planned.
+
+Built for testing your own services, scraping with permission, and research into
+browser fingerprinting.
+
+---
+
+<p align="center">
+  <sub>MIT © <a href="https://github.com/x2super">x2super</a> · <a href="CHANGELOG.md">changelog</a></sub>
+</p>