eyebrowse 0.1.0__tar.gz

eyebrowse-0.1.0/.env.example

@@ -0,0 +1,26 @@
+# ──────────────────────────────────────────────────────────────────────────
+# EyeBrowse secrets & config.  Copy to `.env` (which is gitignored) and fill in.
+# Loaded by pydantic-settings. Vars without the EYEBROWSE_ prefix (the captcha
+# keys) are read by name to match each provider's conventional env var.
+# ──────────────────────────────────────────────────────────────────────────
+
+# ── Proxy (residential / ISP recommended; datacenter IPs trigger trust penalties) ──
+EYEBROWSE_PROXY_SERVER=
+EYEBROWSE_PROXY_USERNAME=
+EYEBROWSE_PROXY_PASSWORD=
+
+# ── Captcha solver API keys (API-mode only; no browser extension) ──
+# Fill in the provider(s) you actually use.
+CAPSOLVER_API_KEY=
+TWOCAPTCHA_API_KEY=
+CAPMONSTER_API_KEY=
+NEXTCAPTCHA_API_KEY=
+# Default provider when browser_solve_captcha is called without one:
+#   capsolver | twocaptcha | capmonster | nextcaptcha
+EYEBROWSE_CAPTCHA_PROVIDER=capsolver
+
+# ── Stealth defaults (engine already defaults these; uncomment to override) ──
+# EYEBROWSE_HEADLESS=false
+# EYEBROWSE_HUMANIZE=true
+# EYEBROWSE_GEOIP=true
+# EYEBROWSE_BLOCK_WEBRTC=true

eyebrowse-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings. Text files are stored LF in the repo; checked out
+# per-platform. Windows shell scripts MUST be CRLF on checkout — Windows
+# PowerShell 5.1 fails to parse here-strings (and other constructs) when a
+# .ps1 has LF-only endings.
+* text=auto
+
+*.ps1 text eol=crlf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Keep shell scripts LF so they run on Linux/macOS.
+*.sh text eol=lf

eyebrowse-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# ── Python ──
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# ── Virtualenv / uv ──
+.venv/
+venv/
+
+# ── Secrets / env (keep the example) ──
+.env
+*.env
+!.env.example
+# Never commit private keys / certs
+*.pem
+*.key
+*.pfx
+*.p12
+
+# ── Reference clones (read-only, NOT vendored) ──
+reference/
+
+# ── Runtime data: browser profiles, HAR captures, recordings, traces, extraction ──
+# (Generated artifacts default to data/. Curated demo media for the README lives in
+#  docs/ and is intentionally NOT ignored.)
+profiles/
+user_data/
+data/
+*.har
+
+# ── Caches ──
+.cache/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+
+# ── OS / editor ──
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

eyebrowse-0.1.0/CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md — EyeBrowse build notes
+
+Guidance for working in this repo. EyeBrowse is **Phase 1: a stealthy, LLM-drivable
+browser-control engine** (Camoufox) consumed two ways from one codebase: as a Python
+library (`from eyebrowse import EyeBrowse`) and over MCP (FastMCP, stdio). The engine
+holds no workflow logic — consumers decide *what* to do; it provides *what's possible*.
+
+## Layout
+
+```
+eyebrowse/
+  api.py            EyeBrowse façade — the single public entry point
+  config.py         pydantic-settings (proxy, captcha keys, stealth defaults)
+  snapshot.py       aria_snapshot(mode="ai") + aria-ref= locator resolution
+  proxy.py          ProxyConfig + ProxyProvider (pluggable rotation)
+  identity.py       Identity + random_identity() (fingerprint + profile)
+  extract.py        Crawl4AI raw: feed → markdown (no LLM; lazy, optional `extract` extra)
+  engine/
+    camoufox_engine.py  launch primitive (sequential-launch semaphore, HAR rule)
+    session.py          Session (verbs) + SessionRegistry (current-session)
+  captcha/          base (Anti-Captcha-style polling) + 4 providers + inject.py
+  mcp/
+    server.py       FastMCP entrypoint (lifespan holds one EyeBrowse), main()
+    state.py        process-wide engine handle
+    tools/          16 tool-group modules (1:1 over the façade) = 69 tools
+examples/direct_usage.py   library usage proof (no MCP)
+docs/TOOLS.md              full per-tool reference (generated from the live server)
+```
+
+## Run
+
+```bash
+uv sync                          # core engine
+uv sync --extra extract          # + Crawl4AI (heavier; only needed for extract())
+uv run python -m camoufox fetch  # pinned Firefox binary + GeoIP db
+uv run python examples/direct_usage.py        # verify the library path
+uv run eyebrowse-mcp                           # run the MCP server (stdio)
+claude mcp add eyebrowse uv run eyebrowse-mcp  # register with Claude Code
+```
+
+## Pinned versions (lockstep matters)
+
+* `camoufox==0.4.11` → Firefox **v135.0.1-beta.24** (safely below the v146 Brotli bug
+  that renders an empty DOM on `content-encoding: br`). Re-run `python -m camoufox fetch`
+  after any camoufox bump.
+* `playwright==1.60.0` (pulled by camoufox), `mcp==1.27.2`. Python 3.12 (pinned `<3.13`).
+
+## Verified API facts (current installs — supersede the original research report)
+
+* **Snapshot/refs:** `page.accessibility` and `Page._snapshot_for_ai` are **gone** in
+  Playwright 1.60. Use **`await page.aria_snapshot(mode="ai")`** → YAML ARIA tree with
+  `[ref=eN]` handles, and resolve with **`page.locator("aria-ref=eN")`**. This is the
+  whole LLM-drivable interaction model (see `snapshot.py`). No DOM injection needed.
+* **Screenshot:** return Playwright's raw PNG bytes via `Image(data=bytes, format="png")`
+  — never `PIL.tobytes()` (raw pixels → corrupt image).
+* **Camoufox:** `AsyncCamoufox(**launch_options)` accepts pass-through kwargs
+  (`headless`, `humanize`, `geoip`, `block_webrtc`, `proxy`, `os`, `screen`,
+  `persistent_context`, `user_data_dir`, `disable_coop`). Yields a **Browser** when
+  ephemeral, a **BrowserContext** when `persistent_context=True`.
+
+## Key constraints (encoded in code — don't "simplify" away)
+
+* **Sequential context creation.** Parallel `new_context()` deadlocks Camoufox's Juggler
+  pipe → launch is serialized behind a semaphore in `CamoufoxEngine` (interactions after
+  are parallel-safe).
+* **HAR ⇒ ephemeral.** `launch_persistent_context` strips `record_har_*`. HAR is only set
+  on `browser.new_context(record_har_*)`, and Playwright only flushes it on context close,
+  so `export_har()` **closes the session**. HAR + a logged-in profile ⇒ upstream mitmproxy.
+* **Captcha = API-mode only.** No browser extension (Chromium-oriented, unstable in
+  Firefox, raises bot-score). Solvers fetch a token over HTTP; `captcha/inject.py` writes
+  it into the response field and overrides `turnstile/grecaptcha.getResponse`.
+* **Stealth defaults:** `geoip=True`, `humanize=True`, `block_webrtc=True`. For identity
+  rotation, rotate IP + geo (geoip) + fingerprint (fresh profile) together.
+* **Windows:** runs headful/headless natively (no Xvfb). The `1x1x24` Xvfb patch is a
+  Linux/Docker concern, deferred.
+
+## MCP tool surface — 78 tools (grouped in `mcp/tools/`)
+
+- **sessions**: `browser_new_session` / `browser_close_session` / `browser_list_sessions`
+- **navigate**: `browser_navigate` / `browser_navigate_back` / `browser_navigate_forward` / `browser_reload` / `browser_tabs` / `browser_switch_to_popup`
+- **observe**: `browser_snapshot` / `browser_snapshot_frame` / `browser_screenshot` / `browser_resize` / `browser_console_messages` / `browser_wait_for_download`
+- **interact**: `browser_click` / `browser_type` / `browser_keyboard_type` / `browser_fill_form` / `browser_hover` / `browser_select_option` / `browser_press_key` / `browser_drag` / `browser_file_upload` / `browser_handle_dialog` / `browser_wait_for` / `browser_evaluate` / `browser_scroll` / `browser_scroll_to_bottom`
+- **mouse (coordinate)**: `browser_mouse_move` / `browser_mouse_click` / `browser_mouse_down` / `browser_mouse_up` / `browser_mouse_wheel` / `browser_mouse_drag`
+- **network**: `browser_network_requests` / `browser_network_request` / `browser_ws_messages`
+- **netcontrol**: `browser_block_urls` / `browser_unblock_urls` / `browser_set_offline` / `browser_mock_url`
+- **cookies**: `browser_cookie_list` / `browser_cookie_get` / `browser_cookie_set` / `browser_cookie_delete` / `browser_cookie_clear`
+- **localStorage**: `browser_localstorage_list` / `_get` / `_set` / `_remove` / `_clear`
+- **sessionStorage**: `browser_sessionstorage_list` / `_get` / `_set` / `_remove` / `_clear`
+- **state**: `browser_storage_state` / `browser_har_export`
+- **identity / proxy**: `browser_new_identity` / `browser_set_proxy`
+- **verify**: `browser_verify_element_visible` / `browser_verify_element_hidden` / `browser_verify_text_visible` / `browser_verify_value`
+- **devtools**: `browser_highlight` / `browser_clear_highlights` / `browser_generate_locator` / `browser_start_tracing` / `browser_stop_tracing` / `browser_start_recording` / `browser_stop_recording` (→ animated GIF)
+- **emulate**: `browser_set_geolocation` / `browser_set_extra_headers` / `browser_grant_permissions`
+- **captcha**: `browser_solve_captcha` / `browser_totp_generate` · **extract**: `browser_extract`
+
+## Camoufox behavior notes (verified — affect implementation choices)
+
+* **`page.evaluate` runs in an ISOLATED world.** It can read/write the DOM, but cannot see
+  `window.*` globals set by the page's own scripts (`window.__appState` → returns null).
+  Use DOM, network inspection, or HAR to read app state — not page-global JS vars.
+* **Cross-origin iframes:** `aria_snapshot(mode="ai")` assigns frame-prefixed refs like
+  `f1e36`. **`fN` is `"f"+frame.seq`** (a creation-order counter), **NOT** an index into
+  `page.frames` (which is DFS order) — they diverge on dynamic/nested pages, so never do
+  `page.frames[N]`. `ref_locator` hands the whole ref to Playwright's `aria-ref=` engine,
+  which jumps to the frame by seq via `_jumpToAriaRefFrameIfNeeded`
+  (`frameManager.frames().find(f => f.seq === N)`). For a real `Frame` (evaluate /
+  snapshot_frame) we resolve an element via aria-ref then read `owner_frame()` /
+  `content_frame()` — see `snapshot.py:frame_for_ref`. `browser_evaluate(frame_ref=...)`
+  runs JS **inside** the frame, so it works on CROSS-ORIGIN frames (the frame's own
+  context is reachable; only top-frame `contentDocument` access is blocked). If the page
+  snapshot collapses a frame to empty (usually a load-timing issue), `wait_for(network_idle)`
+  then re-snapshot, or use `browser_snapshot_frame('f1')`. Nested frames (`f1f2eM`) are
+  NOT supported — Playwright's own ref regex is single-level `^f\d+e\d+$`.
+* **Shadow DOM:** `aria_snapshot` traverses open shadow roots automatically via the
+  accessibility tree. Shadow-hosted elements get plain `eN` refs; `aria-ref=eN` resolves
+  through shadow boundaries natively — no extra handling needed.
+* **Rich text editors (TipTap, Quill, ProseMirror):** `fill()` is a no-op on
+  `contenteditable` divs. Pattern: `browser_mouse_click(x, y)` to focus the editor →
+  `browser_keyboard_type(text)` to insert. `browser_type` with a ref also works if the
+  snapshot returns a meaningful ref for the editor element.
+* **History navigation (reload / back / forward) isn't reported to Playwright** by Firefox's
+  Juggler, so `Session` drives them via `goto` + an internal navigate() URL history (see
+  `session.py`). Caveat: back/forward only traverse navigate()-driven history, not
+  click-driven navigations.
+* **Coordinate mouse works** (`page.mouse.*` dispatches real events); element/ref clicks also
+  work. Both are supported.
+* **Viewport** defaults to maximize-to-the-randomized-spoofed-screen (large screenshots, full
+  per-session fingerprint entropy, `inner <= screen`). Pin a fixed size via
+  `EYEBROWSE_VIEWPORT_WIDTH/HEIGHT` only if you need predictable dimensions.
+* **HAR export closes the session** (Playwright flushes the buffer on context close only).
+  Non-destructive checkpoint pattern: `browser_storage_state` → `browser_har_export` →
+  `browser_new_session(storage_state=...)`.
+* **Not available on Firefox/Camoufox** (Chromium-only / non-functional): `page.pdf()`,
+  media emulation (`prefers-color-scheme` via `setEmulatedMedia`), and **native video**
+  (`record_video_dir` yields a `page.video` path but Camoufox never writes the file) —
+  intentionally omitted rather than shipped broken. For demos/README, use
+  `browser_start_recording`/`browser_stop_recording` instead: it captures viewport frames and
+  encodes them with **ffmpeg** into a smooth real-time **MP4/WebM/GIF** (format from the path
+  extension; `also_gif=True` emits a sibling GIF). ffmpeg resolves from the bundled
+  `imageio-ffmpeg` (preferred — modern, has `palettegen`/`libx264`) or a system ffmpeg on PATH;
+  falls back to a Pillow GIF only if neither is present. See `examples/record_demo.py`.
+  Caveat: real capture rate is capped by `page.screenshot()` speed (~10-20 fps); the output is
+  encoded at the requested fps (default 30) in real time. A true-fps OS-capture mode (ffmpeg
+  `gdigrab`, headful) is a possible future addition.
+
+## Secrets
+
+`.env` (gitignored; see `.env.example`). Proxy + stealth settings use the `EYEBROWSE_`
+prefix; captcha keys use provider-conventional names (`CAPSOLVER_API_KEY`, …). Never
+hardcode. Extraction is markdown-only and uses **no LLM** — so no LLM provider keys are
+ever read (the consuming agent does any structuring).
+
+## Conventions
+
+Library-first: add capability to the façade/engine, then expose it as a thin MCP tool
+(no logic in the tool). Keep `Session` the home of per-session verbs. Async throughout.

eyebrowse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EyeBrowse contributors
+
+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.

eyebrowse-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: eyebrowse
+Version: 0.1.0
+Summary: EyeBrowse — a stealthy, LLM-drivable browser-control engine (Camoufox), consumed as a library and over MCP.
+Project-URL: Homepage, https://github.com/Evil-Bane/eyebrowse
+Project-URL: Repository, https://github.com/Evil-Bane/eyebrowse
+Project-URL: Issues, https://github.com/Evil-Bane/eyebrowse/issues
+Author-email: Evil-Bane <72240505+Evil-Bane@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,anti-detection,browser-automation,camoufox,firefox,llm,mcp,model-context-protocol,playwright,stealth,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: <3.13,>=3.12
+Requires-Dist: camoufox[geoip]==0.4.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: playwright<2,>=1.40
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyotp>=2.9
+Provides-Extra: extract
+Requires-Dist: crawl4ai>=0.4.0; extra == 'extract'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🦊 EyeBrowse
+
+### A stealthy, LLM-drivable browser engine — one codebase, two faces.
+
+A **Python library** *and* an **MCP server** for driving a real, hard-to-detect browser
+— Camoufox, a Firefox fork with C++-level fingerprint spoofing — so legitimate automation
+isn't false-flagged or IP-banned by Cloudflare, DataDome, Akamai, or PerimeterX.
+
+[![PyPI](https://img.shields.io/pypi/v/eyebrowse?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/eyebrowse/)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](LICENSE)
+[![MCP tools](https://img.shields.io/badge/MCP-78_tools-7c3aed.svg)](docs/TOOLS.md)
+[![Engine: Camoufox](https://img.shields.io/badge/engine-Camoufox%20(Firefox)-FF6611.svg)](https://github.com/daijro/camoufox)
+
+![EyeBrowse driving a real browser](https://raw.githubusercontent.com/Evil-Bane/eyebrowse/master/docs/demo.gif)
+
+<sub>▶ Higher-quality MP4: <a href="https://github.com/Evil-Bane/eyebrowse/blob/master/docs/demo.mp4">docs/demo.mp4</a> — real EyeBrowse captures, composed into an ad by <code>examples/make_demo.py</code></sub>
+
+</div>
+
+---
+
+## Why EyeBrowse?
+
+- 🥷 **Stealth by default** — engine-level fingerprint spoofing (`geoip` + `humanize` + `block_webrtc` on out of the box); `navigator.webdriver` masked; viewport auto-sized to the spoofed screen. No `puppeteer-extra` band-aids — the anti-detection is *in the browser*.
+- 🤖 **Built for LLMs** — pages are read as an **ARIA tree with `[ref=…]` handles**; the model acts by ref (`click`/`type`/`hover`), not by brittle CSS or raw pixels. Cross-origin iframes, shadow DOM, popups — handled.
+- 🧰 **Library *and* MCP from one codebase** — a clean Python API (`EyeBrowse` + `Session`), mirrored 1:1 by a thin **MCP server** (**78 `browser_*` tools**) for Claude Code and any MCP client.
+- 🪟 **Never boxed in** — the curated high-level API doesn't hide Playwright: reach `session.page` / `.context` / `.browser` for anything it doesn't wrap.
+- 🔋 **Batteries included** — multi-session, proxy + identity rotation, API-mode captcha solvers, full HAR capture, screen recording (MP4/GIF), and clean-markdown extraction.
+
+> **Scope.** This repo is **Phase 1: the browser engine.** It holds **no workflow logic** —
+> consumers decide *what* to do; the engine provides *what's possible*. (A Phase-2 agent is a
+> separate effort.)
+
+## Contents
+
+[Quickstart](#quickstart) · [Install](#install) · [Features](#features) · [Library](#use-as-a-library) · [MCP](#use-over-mcp) · [Proxy & identity](#proxy--identity-optional) · [Extraction](#extraction) · [Recording](#recording) · [How it works](#how-it-works) · [Caveats](#camoufox-caveats) · [Tools](docs/TOOLS.md) · [License](#license)
+
+## Quickstart
+
+```bash
+pip install eyebrowse
+python -m camoufox fetch          # one-time: download the stealth Firefox + GeoIP db
+```
+
+```python
+import asyncio
+from eyebrowse import EyeBrowse
+
+async def main():
+    eb = EyeBrowse()                          # stealth defaults: geoip · humanize · block_webrtc
+    async with eb.session() as s:
+        await s.navigate("https://example.com")
+        print(await s.snapshot())             # ARIA tree with [ref=...] handles
+        await s.click("e6")                   # act on a ref from the snapshot
+    await eb.aclose()
+
+asyncio.run(main())
+```
+
+…or wire it into **Claude Code** (or any MCP client) — see [Use over MCP](#use-over-mcp).
+
+## Install
+
+**From PyPI**
+
+```bash
+pip install eyebrowse                 # or: uv pip install eyebrowse
+python -m camoufox fetch             # one-time browser fetch (like Playwright's `playwright install`)
+pip install "eyebrowse[extract]"     # optional: + Crawl4AI markdown extraction (heavier)
+```
+
+**From source (development)**
+
+```bash
+git clone https://github.com/Evil-Bane/eyebrowse && cd eyebrowse
+uv sync                              # core engine  (add --extra extract for Crawl4AI)
+uv run python -m camoufox fetch
+cp .env.example .env                 # only if you use a proxy / captcha keys
+```
+
+Python 3.12 (pinned `<3.13`). Pinned engine: `camoufox==0.4.11` (Firefox v135), `playwright 1.60`, `mcp 1.27`.
+
+## Features
+
+| | |
+|---|---|
+| 🥷 **Stealth** | Camoufox engine-level fingerprint spoofing; `geoip` + `humanize` + `block_webrtc` by default; `webdriver` masked; viewport matched to the spoofed screen. |
+| 🤖 **LLM interaction** | `aria_snapshot(mode="ai")` → ARIA tree + `[ref]` handles; click / type / hover / select / drag / file-upload / dialogs / keyboard; coordinate mouse too. |
+| 🪟 **Frames & DOM** | cross-origin iframe routing by ref, shadow-DOM piercing, popup/new-tab switching, `evaluate` inside any frame. |
+| 🗂 **Multi-session** | independent stealth sessions, each with its own context / identity / proxy. |
+| 🌐 **Network** | inspect requests/responses (incl. XHR/fetch bodies & WebSocket frames), block URLs, mock responses, go offline, full **HAR** export. |
+| 💾 **State** | cookies, localStorage & sessionStorage (CRUD), `storage_state` save/reload. |
+| 🪪 **Identity rotation** | fresh fingerprint (OS/screen) + isolated profile + paired proxy; pluggable residential `ProxyProvider`. |
+| 🧩 **Captcha** | pluggable **API-mode** solvers (CapSolver / 2Captcha / CapMonster / NextCaptcha) + TOTP — no browser extension. |
+| 📄 **Extraction** | Crawl4AI `raw:` feed → clean, token-efficient **markdown** (no LLM, no API keys). |
+| 🎥 **Capture** | screenshots, Playwright tracing, and **screen recording → MP4 / WebM / GIF** (ffmpeg). |
+| ✅ **Verify & debug** | assertions, element highlighting, locator generation, geolocation/header emulation. |
+
+Full per-tool reference: **[docs/TOOLS.md](docs/TOOLS.md)** (78 tools across 17 groups).
+
+## Use as a library
+
+```python
+import asyncio
+from eyebrowse import EyeBrowse
+
+async def main():
+    eb = EyeBrowse()                           # stealth defaults
+    try:
+        async with eb.session() as s:          # a stealth session (auto-closed)
+            await s.navigate("https://example.com")
+            print(await s.snapshot())          # ARIA tree with [ref=...] handles
+            await s.click("e6")                # act on a ref
+            await s.type("e8", "hello", submit=True)
+            png = await s.screenshot(full_page=True)
+            title = await s.page.title()        # full Playwright power when you need it
+    finally:
+        await eb.aclose()
+
+asyncio.run(main())
+```
+
+Run the included proof: `uv run python examples/direct_usage.py`.
+
+## Use over MCP
+
+EyeBrowse ships an MCP server (`eyebrowse-mcp`, FastMCP over stdio). Add it to any MCP client.
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add eyebrowse -- eyebrowse-mcp
+```
+
+**Any MCP client (JSON config):**
+
+```json
+{
+  "mcpServers": {
+    "eyebrowse": {
+      "command": "eyebrowse-mcp"
+    }
+  }
+}
+```
+
+Then drive the loop: `browser_navigate(url)` → read the snapshot → act by ref
+(`browser_click` / `browser_type` / …). A default session is auto-created, so most tools just
+work. Full list: **[docs/TOOLS.md](docs/TOOLS.md)**.
+
+## Proxy & identity (optional)
+
+Runs **proxyless by default** (`geoip` still aligns locale/timezone to your real IP). Add a proxy
+only when you want one:
+
+```python
+await eb.new_session(proxy="http://user:pass@residential.example:8080")
+await eb.rotate_identity(proxy="socks5://host:1080")   # fresh fingerprint + paired IP
+await eb.new_session(no_proxy=True)                     # force proxyless
+```
+
+Set a default once via `EYEBROWSE_PROXY_*` in `.env`, `eb.set_static_proxy(...)`, or a custom
+`ProxyProvider` for rotation. Over MCP: `browser_new_session(proxy_url=…)` /
+`browser_new_identity(proxy_url=…)` / `browser_set_proxy(…)`.
+
+## Extraction
+
+`eb.extract()` (or `browser_extract`) hands the rendered HTML to Crawl4AI's `raw:` feed and
+returns clean, pruned **markdown** — **no LLM is called and no LLM keys are ever read**; the
+consuming agent does any structuring.
+
+```python
+md  = await eb.extract()                            # markdown string
+res = await eb.extract(output_path="data/page.md")  # → {"path": ..., "chars": ...}
+```
+
+## Recording
+
+Camoufox can't write native browser video, so EyeBrowse rolls its own recorder: it captures
+viewport frames and encodes them with **ffmpeg** into a smooth, real-time **MP4/WebM** (and a
+palette-optimized **GIF** that autoplays inline on GitHub). ffmpeg ships bundled
+(`imageio-ffmpeg`), so it works out of the box.
+
+```python
+await s.start_recording(fps=30)
+# ... drive the browser ...
+await s.stop_recording("demo.mp4", extra_paths=["demo.gif"])
+```
+
+The demo at the top was produced this way — see **`examples/make_demo.py`**.
+
+## How it works
+
+```
+CONSUMERS                         ENGINE (library: eyebrowse/)
+ Claude Code  ──MCP──▶  mcp/  ──▶  EyeBrowse façade (public API)
+ your code   ─ import ──────────▶   ├─ Camoufox engine (stealth context, HAR)
+ any MCP client                     ├─ proxy / identity rotation (pluggable)
+                                    ├─ captcha solvers (pluggable, API-mode)
+                                    └─ Crawl4AI (raw: feed) → clean markdown
+```
+
+The façade (`EyeBrowse` + `Session`) is the product; the MCP adapter is a thin 1:1 wrapper over
+it. The high-level API is curated and LLM-friendly — *not* a reimplementation of all of Playwright
+— and the raw `page` / `context` / `browser` objects are always one attribute away.
+
+## Camoufox caveats
+
+These shape the API — worth knowing:
+
+- **`evaluate` runs in an isolated world** — it sees the DOM but **not** page-script `window.*`
+  globals. Read app state via DOM / network / HAR.
+- **reload / back / forward** aren't reported by Firefox's Juggler, so they're driven via `goto` +
+  an internal navigate() history (they traverse navigate()-driven history, not click-driven).
+- **Not available on Firefox/Camoufox** (intentionally omitted, not broken): `page.pdf()`, media
+  emulation, and native Playwright video — use the **ffmpeg recorder** instead.
+
+## Project layout
+
+```
+eyebrowse/
+  api.py            EyeBrowse façade — the single public entry point
+  config.py         settings / secrets (pydantic-settings)
+  snapshot.py       aria_snapshot(mode="ai") + aria-ref= resolution
+  proxy.py          ProxyConfig + pluggable ProxyProvider
+  identity.py       Identity + random_identity()
+  extract.py        Crawl4AI raw: feed → markdown (lazy, optional dep)
+  engine/           camoufox_engine.py (launch) + session.py (verbs + registry)
+  captcha/          solver ABC + 4 providers + DOM detect/inject
+  mcp/              FastMCP server + state + tools/ (17 groups, 78 tools)
+examples/direct_usage.py   library proof (no MCP)
+examples/make_demo.py      the screen-recording demo above
+docs/TOOLS.md              full tool reference
+```
+
+Build notes, version-pin rationale, and verified Camoufox behavior live in **[CLAUDE.md](CLAUDE.md)**.
+
+## Roadmap
+
+- ✅ **Phase 1 — the engine** (this repo): stealth Camoufox engine, 78-tool MCP surface, library API.
+- 🔭 **Phase 2 — the agent**: an LLM agent + durable orchestrator that drives this engine to run web tasks at scale (separate project).
+
+## Authorized use
+
+EyeBrowse is for **personal automation** and **authorized security research / bug-bounty** work.
+Use it only against properties you own or are explicitly permitted to test.
+
+## License
+
+[MIT](LICENSE) © Evil-Bane