Metadata-Version: 2.4
Name: x5browser
Version: 1.0.0
Summary: Browser library for AI agents: CDP tools (every action returns result + screenshot) plus a pure token-gated live view.
Author: x5browser
License: MIT
Keywords: browser,chrome,cdp,ai-agent,automation,live-view,vnc
Classifier: Development Status :: 3 - Alpha
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Requires-Dist: websockets>=15
Provides-Extra: annotate
Requires-Dist: Pillow>=10; extra == "annotate"
Dynamic: license-file

# x5browser — hidden Chrome + VNC live link + agent tools

```bash
pip install x5browser            # core only (CDP + live view)
pip install "x5browser[annotate]" # + Pillow for screenshot(annotate=true)
```

```python
from x5browser import LiveBrowser

live = LiveBrowser()          # hidden Chrome (WSL on Windows) + VNC link
await live.start()
print(live.live_url)          # minimal noVNC page, open / embed in <iframe>
await live.navigate("https://example.com")  # tools return result + screenshot
await live.take_control()     # user drives the same browser
await live.agent_control()    # agent resumes with fresh observe
await live.stop()
```

- **Live**: the remote Chrome in any browser tab or `<iframe>`
  (`x5-live.html` — no toolbar, no scrollbars, no fixed size: the screen fills
  its host, scales to it and re-scales when the host changes size, showing a
  spinner with the word "Loading" until the stream is drawn). Any VNC player
  can attach to the same machine at `vnc://<host>:5900`.
  Embed: `<iframe src="...live_url..."></iframe>`.
- **Tools**: an acting tool answers with its output plus **one image taken
  after the event** (`ActionResult(ok, message, screenshot)`); a read-only
  tool answers with data only (text/JSON, never an image). The page map is
  never attached: ask for it with `page_snapshot` / `find_elements`.
- **Profile**: created on first start, reused afterwards.
  `close_profile()` on `X5Browser` closes Chrome quietly, data is kept.

## Setup (once)

```bash
python scripts/setup_local.py
```

Starts Xvfb + headed Chrome + x11vnc + noVNC + CDP relay inside WSL
(Ubuntu) and publishes them on Windows localhost (6080/5900/9334).

## Demo page (optional)

`scripts/agent_popup_demo.html` is a tiny page with three real popups
(alert, prompt, in-page dialog) for trying the tools by hand.

## Tool console + live gate (one command)

```bash
python scripts/run_ui.py          # stack + UI on http://127.0.0.1:8790/
```

- `http://127.0.0.1:8790/` — the tool console: **one section per tool**, each
  with its own inputs, a **Test** button, the organized JSON log and the
  returned image. A Test runs the real library tool, never a copy of it.
- `http://127.0.0.1:8790/view?token=...` — the live link. **Every browser
  start mints a new token**; the old link answers **Not Connect**, and closing
  the browser revokes the link automatically.
- Tools: `open_browser` / `close_browser` (quiet, data kept) drive the browser,
  and any other tool opens it by itself when it is closed.
- `human_control` answers the control link (the user drives), `live_preview`
  answers a watch-only link.
