barebrowse 0.1.0 → 0.2.0

package/docs/blueprint.md

@@ -0,0 +1,361 @@
+# barebrowse -- Blueprint
+
+Vanilla JS library. CDP-direct. URL in, pruned ARIA snapshot out.
+No Playwright, no bundled browser, no build step.
+
+---
+
+## What It Does
+
+Gives autonomous agents authenticated access to the web through the user's own Chromium browser.
+
+```js
+import { browse, connect } from 'barebrowse';
+
+// One-shot: read a page
+const snapshot = await browse('https://any-page.com');
+
+// Session: navigate, interact, observe
+const page = await connect();
+await page.goto('https://any-page.com');
+console.log(await page.snapshot());
+await page.click('8');      // ref from snapshot
+await page.type('3', 'hello');
+await page.scroll(500);
+await page.close();
+```
+
+---
+
+## Capabilities
+
+Every action returns a **pruned ARIA snapshot** -- the agent's view of the page after each move. The snapshot is a YAML-like tree with `[ref=N]` markers on interactive elements. The agent reads the snapshot, picks a ref, acts, then reads the next snapshot. This is the observe-think-act loop.
+
+### Actions
+
+| Action | Method | What It Does | Status |
+|--------|--------|-------------|--------|
+| Navigate | `page.goto(url)` | Load a URL, wait for page load, dismiss consent | Done |
+| Snapshot | `page.snapshot()` | Pruned ARIA tree (47-95% token reduction) | Done |
+| Click | `page.click(ref)` | Scroll into view, mouse press+release at element center | Done |
+| Type | `page.type(ref, text)` | Focus element, insert text (fast batch mode) | Done |
+| Type (clear) | `page.type(ref, text, { clear: true })` | Select-all + delete, then type (replaces pre-filled content) | Done |
+| Type (key events) | `page.type(ref, text, { keyEvents: true })` | Char-by-char keyDown/keyUp (triggers JS handlers) | Done |
+| Press | `page.press(key)` | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home/End, PageUp/Down, Space | Done |
+| Scroll | `page.scroll(deltaY)` | Mouse wheel event (positive=down, negative=up) | Done |
+| Hover | `page.hover(ref)` | Move mouse to element center (triggers hover styles/tooltips) | Done |
+| Select | `page.select(ref, value)` | Set `<select>` value or click custom dropdown option | Done |
+| Screenshot | `page.screenshot(opts)` | `Page.captureScreenshot`, returns base64 string | Done |
+| Wait for nav | `page.waitForNavigation()` | Promise.race of loadEventFired + frameNavigated (SPA-aware) | Done |
+| Wait for idle | `page.waitForNetworkIdle(opts)` | Resolve when no pending requests for N ms (default 500) | Done |
+| Inject cookies | `page.injectCookies(url, opts)` | Extract cookies from Firefox/Chromium, inject via CDP | Done |
+| Raw CDP | `page.cdp.send(method, params)` | Escape hatch for any CDP command | Done |
+| Close | `page.close()` | Close page target, disconnect CDP, kill browser (if headless) | Done |
+
+### Obstacle course -- what barebrowse handles automatically
+
+| Obstacle | How It's Handled | Mode |
+|----------|-----------------|------|
+| **Cookie consent walls** (GDPR) | ARIA tree scan, jsClick accept button. 7 languages: EN, NL, DE, FR, ES, IT, PT | Both |
+| **Consent in dialog role** | Detect `dialog`/`alertdialog` with consent hints, click accept inside | Both |
+| **Consent outside dialog** (BBC SourcePoint) | Fallback global button scan when dialog has no accept button | Both |
+| **Consent behind iframe overlay** | JS `.click()` via `DOM.resolveNode` bypasses z-index/overlay issues | Both |
+| **Permission prompts** (location, notifications, camera, mic) | Launch flags + CDP `Browser.setPermission` auto-deny | Both |
+| **Media autoplay blocked** | `--autoplay-policy=no-user-gesture-required` | Both |
+| **Login walls** | Firefox cookie extraction, CDP injection (user's real sessions) | Both |
+| **Pre-filled form inputs** | `type({ clear: true })` selects all + deletes before typing | Both |
+| **Off-screen elements** | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| **Form submission** | `press('Enter')` with proper `text: '\r'` triggers onsubmit | Both |
+| **Tab between fields** | `press('Tab')` with `text: '\t'` moves focus | Both |
+| **SPA navigation** (YouTube, GitHub) | `waitForNavigation()` uses frameNavigated + loadEventFired race | Both |
+| **Bot detection** (Google, Reddit) | Stealth patches (headless) + headed mode with real cookies | Both |
+| **`navigator.webdriver`** | Stealth patches: webdriver, plugins, languages, chrome object | Headless |
+| **Profile locking** | Unique temp dir per headless instance (`/tmp/barebrowse-<pid>-<ts>`) | Headless |
+| **ARIA noise** | 9-step pruning: wrapper collapse, noise removal, landmark promotion | Both |
+
+### Not yet handled
+
+| Obstacle | What's Needed | Difficulty |
+|----------|--------------|------------|
+| File upload | `Input.setFiles` via CDP | Low |
+| Drag and drop | `Input.dispatchDragEvent` sequence | Medium |
+| Infinite scroll | Scroll + wait for new content strategy | Medium |
+| CAPTCHAs | Cannot solve -- headed mode lets user solve manually | N/A |
+| Cross-origin iframes | Frame tree traversal via CDP | Medium |
+| Canvas/WebGL | Opaque to ARIA -- needs screenshot + vision model | Hard |
+
+### Tested sites (16+ sites, 8 countries, all consent dismissed)
+
+| Site | Consent | Cookies | Interactions | Notes |
+|------|---------|---------|-------------|-------|
+| google.com | NL dialog dismissed | Firefox injection | Search (combobox + Enter) | Bot-blocks headless |
+| youtube.com | Bypassed via cookies | Firefox injection | Search + video playback | Full e2e demo, SPA nav |
+| bbc.com | SourcePoint dismissed | -- | -- | Button outside dialog |
+| wikipedia.org | -- | -- | Link click + navigation | Clean, no consent |
+| github.com | -- | -- | SPA navigation | Needs settle time |
+| duckduckgo.com | -- | -- | Search + results | Headless-friendly |
+| news.ycombinator.com | -- | -- | Story link click | Clean, simple DOM |
+| amazon.de | Banner dismissed | -- | -- | |
+| theguardian.com | CMP dismissed | -- | -- | |
+| spiegel.de | CMP dismissed | -- | -- | German |
+| lemonde.fr | CMP dismissed | -- | -- | French |
+| elpais.com | CMP dismissed | -- | -- | Spanish |
+| corriere.it | CMP dismissed | -- | -- | Italian |
+| nos.nl | CMP dismissed | -- | -- | Dutch |
+| bild.de | CMP dismissed | -- | -- | German |
+| nu.nl | CMP dismissed | -- | -- | Dutch |
+| booking.com | Banner dismissed | -- | -- | |
+| nytimes.com | -- | -- | -- | No consent wall |
+| stackoverflow.com | Footer link only | -- | -- | Not blocking |
+| cnn.com | -- | -- | -- | No consent wall |
+| reddit.com | -- | -- | Fallback to old.reddit | Bot-blocks headless |
+
+---
+
+## Architecture
+
+### Full pipeline: browse(url) or connect() -> goto(url)
+
+```
+1. LAUNCH            chromium.js finds installed browser
+                     Headless: spawn fresh Chromium with permission flags
+                     Headed: connect to running browser on CDP port
+                     Hybrid: try headless, detect challenge page, fallback to headed
+
+2. CDP CONNECTION    cdp.js opens WebSocket to browser
+                     Creates page target, attaches flattened session
+                     Enables Page, Network, DOM domains
+
+3. STEALTH           stealth.js (headless only)
+                     Page.addScriptToEvaluateOnNewDocument before any page scripts
+                     Patches: navigator.webdriver, plugins, languages, chrome object
+
+4. PERMISSIONS       Browser.setPermission denies all prompts
+                     geo, notifications, camera, mic, midi, sensors, idle
+
+5. AUTH              auth.js extracts cookies from user's browser
+                     Firefox: SQLite cookies.sqlite (plaintext)
+                     Chromium: SQLite Cookies + AES decrypt via keyring
+                     Injects via Network.setCookie before navigation
+
+6. NAVIGATE          Page.navigate(url), wait for Page.loadEventFired
+                     500ms settle for dynamic content
+
+7. CONSENT           consent.js scans ARIA tree post-load
+                     Finds dialog/alertdialog with consent hints
+                     Falls back to global button scan (BBC SourcePoint pattern)
+                     jsClick via DOM.resolveNode (bypasses iframe overlays)
+
+8. SNAPSHOT          Accessibility.getFullAXTree -> nested tree (aria.js)
+                     prune.js: 9-step pipeline (47-95% token reduction)
+                     Output: YAML-like text with [ref=N] markers
+
+9. INTERACT          interact.js dispatches real CDP Input events
+                     click: scrollIntoView -> getBoxModel -> mousePressed/Released
+                     type: DOM.focus -> insertText or keyDown/keyUp per char
+                     press: special keys (Enter, Tab, Escape, arrows, etc.)
+                     scroll: mouseWheel events
+                     hover: mouseMoved at element center
+                     select: set <select> value or click custom dropdown option
+
+10. OBSERVE AGAIN    Back to step 8. Refs are ephemeral -- fresh snapshot needed.
+```
+
+### Module table
+
+Eleven modules, 2,396 lines, zero required dependencies.
+
+| Module | Lines | Purpose |
+|---|---|---|
+| `src/index.js` | 434 | Public API: `browse()`, `connect()`, screenshot, network idle, hybrid |
+| `src/cdp.js` | 148 | WebSocket CDP client, flattened sessions |
+| `src/chromium.js` | 148 | Find/launch Chromium browsers, permission-suppressing flags |
+| `src/aria.js` | 69 | Format ARIA tree as YAML-like text |
+| `src/auth.js` | 279 | Cookie extraction (Chromium AES + keyring, Firefox), CDP injection |
+| `src/prune.js` | 472 | ARIA pruning pipeline (9-step, ported from mcprune) |
+| `src/interact.js` | 208 | Click, type, press, scroll, hover, select |
+| `src/consent.js` | 210 | Auto-dismiss cookie consent dialogs, 7 languages |
+| `src/stealth.js` | 51 | Navigator patches for headless anti-detection |
+| `src/bareagent.js` | 161 | Tool adapter for bareagent Loop |
+| `mcp-server.js` | 216 | MCP server (JSON-RPC 2.0 over stdio) |
+
+---
+
+## What's Built
+
+### Headless mode -- done
+Spawn a fresh Chromium, navigate, snapshot, close. Default mode.
+- Cookie extraction from user's Firefox or Chromium profile
+- Cookie injection via `Network.setCookie` before navigation
+- ARIA tree extraction via `Accessibility.getFullAXTree`
+- 9-step pruning: landmarks, noise removal, wrapper collapsing, context filtering
+- 47-95% token reduction depending on page complexity
+- Permission prompts auto-suppressed (notifications, geolocation, camera, mic)
+- Stealth patches: `navigator.webdriver`, plugins, languages, chrome object
+
+### Headed mode -- done
+Connect to an already-running browser on a CDP debug port.
+- Same ARIA + prune pipeline
+- Manual cookie injection via `page.injectCookies(url, { browser })` (e.g. inject Firefox cookies into headed Chromium)
+- Permission prompts suppressed via CDP `Browser.setPermission`
+- User must launch browser with `--remote-debugging-port=9222`
+
+### Hybrid mode -- done
+Try headless first. If bot-blocked (Cloudflare, etc.), fall back to headed automatically.
+- Detection: heuristic on ARIA tree for challenge phrases ("Just a moment", "Checking your browser")
+- Fallback: kill headless, connect to user's running browser on port 9222, re-navigate
+- One flag: `mode: 'hybrid'`
+
+### Interactions -- done, real-world tested
+On `connect()` sessions: `click(ref)`, `type(ref, text, opts)`, `press(key)`, `scroll(deltaY)`, `hover(ref)`, `select(ref, value)`, `screenshot()`, `waitForNavigation()`, `waitForNetworkIdle()`, `injectCookies(url, opts)`.
+- Refs come from ARIA snapshot (`[ref=N]` markers)
+- Click: `DOM.scrollIntoViewIfNeeded` -> `DOM.getBoxModel` -> center -> `Input.dispatchMouseEvent`
+- Type: `DOM.focus` + `Input.insertText` (fast) or `Input.dispatchKeyEvent` (triggers handlers)
+- Type with `{ clear: true }`: select-all (Ctrl+A) + delete before typing
+- Press: special keys (Enter, Tab, Escape, Backspace, arrows) with proper key/code/keyCode
+- Scroll: `Input.dispatchMouseEvent` mouseWheel
+- Hover: `DOM.scrollIntoViewIfNeeded` -> `Input.dispatchMouseEvent` mouseMoved
+- Select: native `<select>` (set value + change event) or custom dropdown (click + find option)
+- Screenshot: `Page.captureScreenshot` -> base64 string (png/jpeg/webp)
+- WaitForNavigation: `Promise.race` of `Page.loadEventFired` + `Page.frameNavigated` (SPA-aware)
+- WaitForNetworkIdle: track pending requests, resolve when 0 for N ms
+
+**Real-world tested against:** Google, Wikipedia, GitHub (SPA), Hacker News, DuckDuckGo, YouTube (search + video playback), example.com
+
+### Cookie consent auto-dismiss -- done
+Automatically detects and dismisses GDPR/cookie consent dialogs after page load.
+- Scans ARIA tree for `dialog`/`alertdialog` with consent-related content
+- Falls back to global button scan for sites that don't use dialog roles (e.g. BBC SourcePoint)
+- Uses JS `.click()` via `DOM.resolveNode` + `Runtime.callFunctionOn` to bypass iframe overlays
+- Multi-language: EN, NL, DE, FR, ES, IT, PT button text patterns
+- Opt-out via `{ consent: false }`
+- Works in both headless and headed modes
+
+**Tested against 16+ sites across 8 countries, 0 consent dialogs remaining.**
+
+### Permission suppression -- done
+Chrome permission prompts (location, notifications, camera, mic, etc.) are suppressed automatically.
+- Headless: launch flags (`--disable-notifications`, `--autoplay-policy=no-user-gesture-required`, `--use-fake-device-for-media-stream`, `--use-fake-ui-for-media-stream`, `--disable-features=MediaRouter`)
+- Both modes: CDP `Browser.setPermission` denies geolocation, notifications, midi, audioCapture, videoCapture, sensors, idleDetection, etc.
+- No user prompt ever appears -- agents browse without interruption
+
+### Cross-browser cookie injection -- done
+Firefox cookies (user's default browser) extracted from SQLite -> injected into headless or headed Chromium via CDP `Network.setCookie`. No need to use Chromium as daily browser.
+- `browse()`: auto-injects cookies before navigation (opt-out with `{ cookies: false }`)
+- `connect()`: manual injection via `page.injectCookies(url, { browser: 'firefox' })`
+- Proven: YouTube login session transferred from Firefox -> headed Chromium -> video playback
+
+### Stealth patches -- done
+Anti-detection for headless mode via `Page.addScriptToEvaluateOnNewDocument` (runs before page scripts).
+- `navigator.webdriver` -> undefined
+- `navigator.plugins` -> fake 3 plugins
+- `navigator.languages` -> `['en-US', 'en']`
+- `window.chrome` -> fake object
+- `Permissions.prototype.query` -> notifications return 'prompt'
+- Applied automatically in headless mode
+
+### Tests -- 47+ passing
+- 16 unit tests (pruning logic)
+- 7 unit tests (cookie extraction -- 2 skip when Chromium profile locked)
+- 5 unit tests (CDP client + browser launch)
+- 11 integration tests (end-to-end browse pipeline)
+- 15 integration tests (real-world interactions: data: URL fixture + live sites)
+
+---
+
+## Integrations
+
+### bareagent -- tool adapter
+
+`createBrowseTools(opts)` returns bareagent-compatible tools for the Loop:
+
+```js
+import { Loop } from 'bare-agent';
+import { Anthropic } from 'bare-agent/providers';
+import { createBrowseTools } from 'barebrowse/src/bareagent.js';
+
+const { tools, close } = createBrowseTools();
+const loop = new Loop({ provider: new Anthropic({ apiKey }) });
+const result = await loop.run(messages, tools);
+await close();
+```
+
+9 tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot.
+Action tools auto-return snapshot (300ms settle delay). The LLM always sees the result.
+
+### MCP server
+
+Raw JSON-RPC 2.0 over stdio. Zero SDK dependencies. `npm install barebrowse` then:
+
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+7 tools: browse (one-shot), goto, snapshot, click, type, press, scroll.
+Action tools return `'ok'` -- agent calls `snapshot` explicitly (MCP tool calls are cheap to chain).
+Session tools share a singleton page, lazy-created on first use.
+
+---
+
+## Ecosystem
+
+```
+bareagent  = the brain  (orchestration, LLM loop, memory, retries)
+barebrowse = the eyes + hands  (browse, read, interact with the web)
+```
+
+**barebrowse is a library.** bareagent imports it as a capability. barebrowse doesn't know about bareagent. bareagent doesn't know about CDP. Clean boundary. Each ships and tests independently.
+
+---
+
+## Constraints
+
+- **Chromium-only.** CDP protocol. Covers Chrome, Chromium, Edge, Brave, Vivaldi, Arc, Opera (~80% desktop share). Firefox later via WebDriver BiDi.
+- **Linux first.** Tested on Fedora/KDE. macOS/Windows cookie extraction paths exist in auth.js but untested.
+- **Node >= 22.** Built-in WebSocket, built-in SQLite.
+- **Not a server.** Library that agents import. Wrap as MCP (included) or HTTP if needed.
+- **Not cross-platform tested.** Local development only, not published to npm.
+
+---
+
+## File Map
+
+```
+barebrowse/
+├── src/
+│   ├── index.js       # Public API: browse(), connect(), screenshot, network idle, hybrid
+│   ├── cdp.js         # WebSocket CDP client
+│   ├── chromium.js    # Find/launch Chromium, permission flags
+│   ├── aria.js        # ARIA tree formatting
+│   ├── auth.js        # Cookie extraction + injection
+│   ├── prune.js       # ARIA pruning (9-step pipeline)
+│   ├── interact.js    # Click, type, press, scroll, hover, select
+│   ├── consent.js     # Auto-dismiss cookie consent dialogs
+│   ├── stealth.js     # Navigator patches for headless anti-detection
+│   └── bareagent.js   # Tool adapter for bareagent Loop
+├── test/
+│   ├── unit/          # prune, auth, cdp tests
+│   └── integration/   # browse + interact tests (real sites)
+├── examples/
+│   ├── headed-demo.js # Interactive demo: Wikipedia → DuckDuckGo
+│   └── yt-demo.js     # YouTube demo: Firefox cookies → search → play video
+├── docs/
+│   ├── prd.md         # Decisions + rationale (reference)
+│   ├── poc-plan.md    # Original POC phases + DoD
+│   ├── blueprint.md   # This file
+│   └── testing.md     # Test guide: pyramid, all 54 tests, CI strategy
+├── mcp-server.js      # MCP server (JSON-RPC 2.0 over stdio)
+├── cli.js             # CLI entry: `npx barebrowse mcp` or `npx barebrowse browse <url>`
+├── .mcp.json          # MCP server config for Claude Desktop / Cursor
+├── barebrowse.context.md  # LLM-consumable integration guide
+├── package.json
+├── README.md
+└── CLAUDE.md
+```

package/docs/poc-plan.md

@@ -0,0 +1,230 @@
+# barebrowse — POC Plan
+
+**Date:** 2026-02-22
+**Goal:** Prove that an autonomous agent can get an authenticated, pruned ARIA snapshot of any web page via CDP — no Playwright, no bundled browser.
+
+---
+
+## Repo Structure
+
+```
+barebrowse/
+├── src/
+│   ├── index.js          # Public API: browse(), connect()
+│   ├── chromium.js        # Find/launch/connect to Chromium browsers
+│   ├── cdp.js             # Vanilla WebSocket CDP client
+│   ├── aria.js            # Accessibility.getFullAXTree → structured tree
+│   ├── auth.js            # Cookie extraction + CDP Network.setCookie injection
+│   ├── prune.js           # ARIA tree pruning (ported from mcprune)
+│   ├── interact.js        # Click, type, scroll via CDP Input domain
+│   ├── consent.js         # Auto-dismiss cookie consent dialogs
+│   └── stealth.js         # Anti-detection patches via Runtime.evaluate (Phase 4)
+├── test/
+│   ├── integration/
+│   │   ├── browse.test.js     # End-to-end: URL → pruned snapshot
+│   │   ├── auth.test.js       # Cookie injection → authenticated page
+│   │   └── interact.test.js   # Click/type on a live page
+│   └── unit/
+│       ├── cdp.test.js        # CDP client message handling
+│       ├── aria.test.js       # ARIA tree formatting
+│       └── prune.test.js      # Pruning logic on sample trees
+├── docs/
+│   ├── prd.md             # Product requirements (comprehensive)
+│   └── poc-plan.md        # This file
+├── package.json
+└── CLAUDE.md
+```
+
+**No build step.** Vanilla JS, ES modules, runs directly with Node.js >= 22.
+
+---
+
+## Phases
+
+### Phase 1 — CDP + ARIA Foundation
+
+**Prove:** Get an ARIA tree from any page via CDP, no Playwright.
+
+**Files:**
+- `src/chromium.js` — Find installed Chromium browsers on the system (Chrome, Chromium, Brave, Edge). Launch headless with `--headless=new --remote-debugging-port=<port>`. Parse CDP WebSocket URL from stderr output.
+- `src/cdp.js` — Vanilla WebSocket client that speaks CDP. Send JSON commands, receive responses and events. Handle command IDs, promises, event subscriptions. ~100 lines.
+- `src/aria.js` — Call `Accessibility.getFullAXTree` via CDP. Transform the raw CDP response (flat array of AXNodes with parentId references) into a nested tree structure. Format as readable output.
+- `src/index.js` — Wire chromium → cdp → aria into `browse(url)` function. Minimal, just the pipeline.
+
+**Test:**
+```bash
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+```
+
+**DoD:**
+- [x] `chromium.js` finds and launches at least one Chromium browser on Fedora Linux
+- [x] `cdp.js` connects via WebSocket, sends commands, receives responses
+- [x] `aria.js` returns a structured ARIA tree for any public page
+- [x] `browse(url)` works end-to-end with zero external dependencies
+- [x] Headless Chrome process is cleaned up on close
+
+### Phase 2 — Auth + Prune
+
+**Prove:** Authenticated, pruned ARIA snapshot of a Cloudflare-protected page.
+
+**Files:**
+- `src/auth.js` — Extract cookies from user's browser profile (use sweet-cookie or implement minimal extraction from Chrome's Cookies SQLite DB + Linux keyring decryption via `secret-tool`). Inject via CDP `Network.setCookie` before navigation.
+- `src/prune.js` — Port mcprune's pruning logic as a pure function. Input: raw ARIA tree. Output: pruned ARIA tree. Role-based: keep landmarks + interactive elements, drop noise/structural wrappers.
+- Update `src/index.js` — Add cookie injection and pruning to the `browse()` pipeline.
+
+**Test:**
+```bash
+# Should return authenticated content, not a login wall or CF challenge
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://some-cf-protected-site.com'))"
+```
+
+**DoD:**
+- [x] `auth.js` extracts cookies from Firefox profile on Linux (also supports Chromium when installed)
+- [x] Cookies injected via CDP before navigation
+- [ ] CF-protected page returns real content, not challenge page (needs active session to test)
+- [x] `prune.js` reduces ARIA tree by 47%+ on HN (minimal site — heavier sites will see 70%+)
+- [x] Pruned output preserves all interactive elements and landmarks
+- [x] `browse(url)` returns pruned, authenticated snapshot by default
+
+### Phase 3 — Headed Mode + Interaction
+
+**Prove:** Connect to user's running browser and interact with a logged-in page.
+
+**Files:**
+- Update `src/chromium.js` — Add `connect()` mode: connect to an already-running browser's debug port instead of launching a new one. Detect running browsers with debug ports.
+- `src/interact.js` — Click (`Input.dispatchMouseEvent`), type (`Input.dispatchKeyEvent`), scroll. Resolve ARIA node IDs to DOM coordinates for click targets.
+- Update `src/index.js` — Add `connect()` export for long-lived sessions. Add `mode: 'headed'` option.
+
+**Prerequisite:** User must launch their browser with `--remote-debugging-port=9222` flag.
+
+**Test:**
+```bash
+# User has Chrome open with debug port, logged into GitHub
+node -e "
+  import { connect } from './src/index.js';
+  const page = await connect({ mode: 'headed' });
+  await page.goto('https://github.com/notifications');
+  console.log(await page.snapshot());
+"
+```
+
+**DoD:**
+- [x] `connect()` attaches to a running Chromium browser via CDP
+- [x] Same ARIA + prune pipeline works on headed browser
+- [x] `click()` and `type()` send real input events via CDP
+- [x] `press()` sends special keys (Enter, Tab, Escape, arrows) — triggers form submit
+- [x] `scrollIntoView` before click ensures off-screen elements are reachable
+- [x] `type({ clear: true })` replaces pre-filled input content
+- [x] `waitForNavigation()` waits for page load after link clicks
+- [x] Interactions tested against real sites: Wikipedia, GitHub, Google, Hacker News, DuckDuckGo, YouTube
+- [x] Browser stays open after barebrowse disconnects
+- [x] Cookie injection via `page.injectCookies()` for headed mode (Firefox → Chromium)
+- [x] Permission prompts suppressed via launch flags + CDP `Browser.setPermission`
+- [x] Cookie consent dialogs auto-dismissed across 16+ sites in 7 languages
+- [x] YouTube end-to-end: Firefox cookies → search → click → video playback in headed mode
+
+### Phase 4 — Hybrid + bareagent Integration
+
+**Prove:** Agent autonomously browses the web using barebrowse tools.
+
+**Files:**
+- Update `src/chromium.js` — Add `mode: 'hybrid'`. Try headless first. If navigation returns a CF challenge or 403, automatically retry in headed mode.
+- `src/stealth.js` — Basic anti-detection: patch `navigator.webdriver`, `navigator.plugins`, `window.chrome`. Applied via `Runtime.evaluate` on new page.
+- Update `src/index.js` — Final API surface: `browse()`, `connect()`.
+
+**Test:**
+```js
+import { Loop } from 'bare-agent';
+import { browse } from './src/index.js';
+
+const tools = [
+  { name: 'browse', execute: ({ url }) => browse(url) },
+];
+
+const loop = new Loop({ provider });
+await loop.run([
+  { role: 'user', content: 'Go to hacker news and tell me the top 3 stories' }
+], tools);
+```
+
+**DoD:**
+- [ ] Hybrid mode automatically falls back when headless is blocked
+- [ ] Stealth patches reduce headless detection on common sites
+- [ ] bareagent can use `browse()` as a tool in its think/act/observe loop
+- [ ] Agent successfully completes a multi-page research task autonomously
+
+---
+
+## Definition of Done — Full POC
+
+The POC is complete when ALL of these are true:
+
+1. **`browse(url)` works end-to-end** — URL in, pruned ARIA snapshot out, authenticated as the user
+2. **Zero heavy deps** — no Playwright, no Puppeteer. Only deps: `ws` (WebSocket client, if Node's built-in isn't sufficient) and optionally `sweet-cookie`
+3. **Three modes work** — headless (default), headed (connect to running browser), hybrid (auto-fallback)
+4. **Works on Fedora Linux** — finds Chrome/Chromium/Brave, launches headless, connects headed
+5. **Token-efficient output** — pruned ARIA tree is 70%+ smaller than raw tree
+6. **Clean process management** — headless browser spawned and killed cleanly, no orphan processes
+7. **Under 1,000 lines total** for core src/ (excluding tests)
+8. **Documented** — PRD captures all decisions, this file captures all phases
+
+## What the POC is NOT
+
+- Not production-ready. No error recovery, no retry logic, no edge case handling beyond happy path.
+- Not cross-platform tested. Linux first (Fedora). macOS/Windows later.
+- Not an MCP server. That's a future wrapper.
+- Not a published npm package. Local development only.
+
+---
+
+## Running Tests
+
+```bash
+# All tests (47+ tests)
+node --test test/unit/*.test.js test/integration/*.test.js
+
+# Unit tests only (fast, no network)
+node --test test/unit/prune.test.js    # 16 tests — pruning logic
+node --test test/unit/auth.test.js     # 7 tests — cookie extraction (2 fail when Chromium locked)
+node --test test/unit/cdp.test.js      # 5 tests — CDP client + browser launch
+
+# Integration tests (needs network + Chromium)
+node --test test/integration/browse.test.js    # 11 tests — end-to-end pipeline
+node --test test/integration/interact.test.js  # 15 tests — interactions on real sites
+
+# Quick smoke test
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+
+# Headed mode demos (requires: chromium-browser --remote-debugging-port=9222)
+node examples/headed-demo.js    # Wikipedia → DuckDuckGo search
+node examples/yt-demo.js        # YouTube: Firefox cookies → search → play video
+```
+
+---
+
+## Repos Studied — What We Borrowed vs Built
+
+| steipete repo | What we studied | What we used | Why not more |
+|---|---|---|---|
+| **sweet-cookie** | Cookie extraction (SQLite + keyring) | **Concept only** — wrote `auth.js` ourselves | Not on npm (different package). Our version is simpler, tailored, vanilla JS |
+| **sweetlink** | CDP dual-channel, selector discovery, daemon | **CDP-direct concept only** | Daemon + WebSocket bridge + in-page runtime = bloat. CDP direct is 100 lines vs ~2,000 |
+| **canvas** | Stealth/anti-detection patterns | **Noted for Phase 4** `stealth.js` | Not needed yet — headless + real cookies handles most cases |
+| **mcprune (own)** | ARIA pruning pipeline | **Full port** — `prune.js` (472 lines) | Proven code, adapted node format from Playwright YAML to CDP tree objects |
+
+### What to explore in later phases
+
+- **Selector discovery** (sweetlink) — crawl ARIA tree, score interactive elements, rank action targets. Phase 3/4.
+- **Stealth patches** (canvas) — `navigator.webdriver`, plugins, chrome object spoofing. Phase 4.
+- **In-page JS execution** (sweetlink) — `Runtime.evaluate` for complex interactions. Phase 3.
+- **Screenshot + visual grounding** — `Page.captureScreenshot` for multimodal agents. Post-POC.
+
+---
+
+## Dev Rules (from AGENT_RULES.md)
+
+- **Vanilla JS only.** No TypeScript, no build step, no transpilation.
+- **Dependency hierarchy:** vanilla → stdlib → external. Write it yourself if <50 lines.
+- **Simple > clever.** Readable code a junior can follow.
+- **POC first.** Validate logic before designing. Never ship the POC — rewrite it.
+- **Test behavior, not implementation.** Integration tests over unit tests.
+- **No speculative code.** Every line must have a purpose.