┌──────────┐   ┌────────────┐   ┌─────────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ CONNECT  │ → │   ORIENT   │ → │     SEE     │ → │   PLAN   │ → │   ACT    │ → │  VERIFY  │
 │ check_   │   │ navigate + │   │ screenshot  │   │ selector │   │ click /  │   │ re-read  │
 │ browser  │   │ wait idle  │   │ get_dom     │   │ or coords│   │ type     │   │ state    │
 └──────────┘   └────────────┘   └─────────────┘   └──────────┘   └──────────┘   └──────────┘
      │                                                    │
      ▼ not running                                        ▼ DOM miss
 ┌──────────────┐                              ┌──────────────────────────┐
 │ open_browser │                              │ validate_position(x, y)  │
 │ (real profile│                              │ → annotated O=(x,y) shot │
 │  + CDP flag) │                              │ → click_position(x, y)   │
 └──────────────┘                              └──────────────────────────┘

agent call → pre-click Gaussian delay (~80ms)
           → PhantomWright Actionability Engine (visible? enabled? stable? unobscured?)
           → CDP Input.dispatchMouseEvent (trusted gesture, NOT element.click())
           → post-click pause (~150ms)
           → result JSON (+ optional verification screenshot)

# 1. Clone
git clone https://github.com/YOUR_USER/probrowser.git
cd probrowser

# 2. Setup (venv + deps + verify)
./setup.sh
# ...or manually:
python -m venv .venv
.venv/bin/pip install -r requirements.txt

{
  "mcp": {
    "probrowser": {
      "type": "local",
      "command": ["/absolute/path/to/probrowser/.venv/bin/python", "-m", "src"],
      "enabled": true,
      "timeout": 120000
    }
  }
}

# Option A — start Opera yourself with CDP enabled:
opera --remote-debugging-port=9222

# Option B — let the agent do it (real profile, cookies intact):
browse_check_browser()          # → not connected?
browse_open_browser(browser="opera")

→ browse_check_browser()
← { connected: false }                      # nothing on :9222 yet

→ browse_open_browser(browser="opera")
← { launched: true, profile: "~/.config/opera", cdp_url: "...:9222" }

→ browse_navigate(url="https://youtube.com/...")
← { success: true, title: "..." }           # auto CAPTCHA scan ran here

→ browse_get_dom(search="One of These Nights")
← { count: 10, elements: [{type: "link", selector: "a[aria-label=...]"}] }

→ browse_click(selector="a[aria-label=...]")
← { success: true }

→ browse_eval(expression="() => {const v=document.querySelector('video'); return {paused: v.paused, time: v.currentTime}}")
← { paused: false, time: 3.1 }              # verified: audio is playing 🎵

PROBROWSER_CDP_URL=http://localhost:9222 .venv/bin/python -m src

┌──────────────────────────────────────────────────────────┐
│                AI Agent (Kilo / Claude Code)              │
│        plan → browse_* tool call → evaluate → repeat      │
└───────────────────────┬──────────────────────────────────┘
                        │ MCP Protocol (stdio, JSON-RPC)
                        ▼
┌──────────────────────────────────────────────────────────┐
│              ProBrowser MCP Server (Python)               │
│   tool registry (29) → action coordinator → humanize.py   │
│        (Gaussian delays · WPM typing · scroll easing)     │
│   analyzer/: dom_parser · hybrid_strategy · captcha       │
└───────────────────────┬──────────────────────────────────┘
                        │ CDP — Input.dispatch* events only
                        ▼
┌──────────────────────────────────────────────────────────┐
│         User's Real Browser (Opera/Chrome, port 9222)     │
│            sessions · cookies · logins preserved          │
└──────────────────────────────────────────────────────────┘

probrowser/
├── main entry
│   ├── src/__main__.py            # python -m src → stdio MCP loop
│   └── src/server.py              # registry (29 tools) + dispatch + timeouts + captcha hooks
├── core
│   ├── src/browser/connection.py  # connect_over_cdp, session persistence, page recovery
│   ├── src/browser/tab_manager.py # tab discovery / switching
│   ├── src/humanize.py            # Gaussian timing middleware
│   ├── src/errors.py              # classify_exception → structured error codes
│   ├── src/config.py              # env-driven configuration
│   └── src/logging.py             # per-action latency/success logging
├── tools (src/tools/, 29 modules)
│   ├── navigate · wait · list_tabs · switch_tab · open_tab · close_tab
│   ├── click · validate_position · click_position · type · hover · keyboard
│   ├── scroll · drag_drop
│   ├── get_dom · find · get_text · eval_js
│   ├── screenshot · screenshot_viewport · screenshot_save
│   ├── check_captcha · captcha_grid · solve_captcha
│   └── detect_browsers · check_browser · open_browser · help · list_tools
├── analyzer (src/analyzer/)
│   ├── dom_parser.py              # DOM → simplified JSON (interactive + visible only)
│   ├── hybrid_strategy.py         # DOM-first, vision fallback
│   └── captcha.py                 # CAPTCHA/ad-overlay detection
├── captcha (src/captcha/)
│   ├── grid.py                    # grid geometry + cropped screenshot extraction
│   └── solver.py                  # tile clicking + verify flow
├── docs/                          # 11 topics served via browse_help()
├── tests/                         # 87 unit tests + integration suite
├── AGENTS.md / CLAUDE.md          # operating guide injected into agents
└── dev-phase-mcp-server.md        # dev-phase principles

# Unit suite — fake pages, no browser required (87 tests)
.venv/bin/python -m pytest tests/ -q

# Integration suite — needs Opera running with CDP
.venv/bin/python -m pytest tests/test_integration.py -m integration

git clone https://github.com/YOUR_USER/probrowser.git && cd probrowser
./setup.sh                                   # venv + dependencies + verify
opera --remote-debugging-port=9222           # hoặc để agent tự mở