barebrowse 0.4.8 → 0.5.2

package/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "barebrowse": {
-      "command": "npx",
-      "args": ["barebrowse", "mcp"]
-    }
-  }
-}

package/CLAUDE.md

@@ -1,24 +0,0 @@
-## Dev Rules
-
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC.
-
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
-
-**Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
-
-**Lightweight over complex.** Fewer moving parts, fewer deps, less config. Simple > clever. Readable > elegant.
-
-**Open-source only.** No vendor lock-in. Every line of code must have a purpose — no speculative code, no premature abstractions.
-
-## Project Specifics
-
-- **What:** Vanilla JS library — CDP-direct browsing for autonomous agents. URL in, pruned ARIA snapshot out.
-- **Language:** Vanilla JavaScript, ES modules, no build step
-- **Runtime:** Node.js >= 22 (built-in WebSocket, sqlite)
-- **Protocol:** CDP (Chrome DevTools Protocol) direct — no Playwright
-- **Browser:** Any installed Chromium-based browser (chromium, chrome, brave, edge)
-- **Modules:** 11 files in `src/`, ~2,400 lines, zero required deps
-- **Tests:** 54 passing — run with `node --test test/unit/*.test.js test/integration/*.test.js`
-- **Docs:** `docs/README.md` (navigation guide to all documentation)
-
-For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.

package/baremobile.md

@@ -1,105 +0,0 @@
-# baremobile — Research & Feasibility
-
-## Platform Feasibility
-
-| Platform | Accessibility Tree | Input Injection | Auth/Cookie Reuse | Practical? |
-|---|---|---|---|---|
-| **Android (non-root)** | uiautomator dump — good XML tree | ADB tap/swipe/input — solid | No. SharedPrefs locked, Keystore hardware-bound | Yes — tree + input work, auth is the gap |
-| **Android (rooted)** | Same | Same | Partial — SharedPrefs yes, Keystore still no | Yes — best mobile option |
-| **iOS (simulator)** | XCUITest — excellent tree | simctl + WDA | No. Absolute sandboxing | Dev/QA only |
-| **iOS (physical)** | Same, but needs Mac+Xcode+signing | Same | No | Impractical for end users |
-| **Windows** | UI Automation (UIA) — best desktop tree | SendInput — works well | App-specific, no universal trick | Yes — strongest desktop option |
-| **macOS** | AXUIElement — good tree | CGEvent APIs, cliclick | Keychain Access (gated by prompts) | Medium — permission hell |
-| **Linux (X11)** | AT-SPI2 — inconsistent coverage | xdotool — trivial | App-specific | Medium — tree quality varies |
-| **Linux (Wayland)** | AT-SPI2 — same | ydotool (needs root) | Same | Hard — input injection blocked by design |
-
-## Market Demand
-
-| Platform | Who Wants It | Use Cases | Demand Level |
-|---|---|---|---|
-| **Android** | Devs, QA teams, end users | Mobile-only apps, testing, data entry, social media automation | **High** — DroidRun got 900 signups in 72h, 2.1M EUR raised |
-| **iOS** | QA teams, enterprises | App testing, accessibility audits | **Medium** — gated access kills consumer use |
-| **Windows** | Enterprises | Legacy app automation (no API, GUI only) | **High** — Microsoft building UFO (8k stars) |
-| **macOS** | Developers, power users | App automation, workflows | **Low-Medium** — most Mac apps have APIs or CLI |
-| **Linux desktop** | Almost nobody | Niche automation | **Low** — devs use CLI, not GUI agents |
-
-## Existing Open-Source Competition
-
-| Project | Platform | Stars | Approach | Maturity |
-|---|---|---|---|---|
-| DroidRun | Android | 3.8k | A11y tree + ADB | Funded (2.1M EUR), active |
-| DroidClaw | Android | New | A11y tree + vision fallback | Weeks old |
-| agent-device (Callstack) | Android + iOS | Early | A11y tree, TypeScript | Active |
-| UFO (Microsoft) | Windows | 8k | UIA + vision | Mature |
-| Agent-S (Simular AI) | Cross-platform | 8.5k | Hybrid | Mature, 72% OSWorld |
-| Cua | macOS/Linux/Win | 11.8k | Sandbox VMs | YC-backed |
-
-## Auth Problem (Mobile vs Web)
-
-| | Web (barebrowse) | Android Native | iOS Native |
-|---|---|---|---|
-| Where tokens live | SQLite cookie DB, readable | SharedPrefs (locked) or Keystore (hardware) | Keychain (sandboxed) |
-| Can agent read them? | Yes — decrypt with OS keyring | No (non-root), Partial (root) | No |
-| Workaround | N/A — it works | Agent logs in via UI, or keeps app session alive | Same |
-| WebView content? | N/A | CDP attach possible (debug builds only) | No |
-
-## Strategic Comparison
-
-| Factor | Android | Windows | iOS | macOS | Linux Desktop |
-|---|---|---|---|---|---|
-| Tree quality | Good | Excellent | Excellent | Good | Inconsistent |
-| Input control | Easy (ADB) | Easy | Gated | Permission-heavy | X11 easy, Wayland hard |
-| Auth reuse | Bad | App-specific | Impossible | Gated | App-specific |
-| Real demand | **High** | **High** | Medium (QA only) | Low-Medium | Low |
-| Competition | Active but early | Microsoft owns it | Apple controls it | Niche | Nobody cares |
-| Fits barebrowse DNA? | **Yes** | Partial | No | No | No |
-
-## Android Technical Details
-
-### Accessibility Tree via ADB
-```bash
-adb shell uiautomator dump /dev/tty  # dump XML accessibility tree
-```
-Returns XML with: bounds, text, class, content-desc, resource-id, clickable, scrollable, focused, enabled, checked, selected. Structurally similar to ARIA — roles, names, states, coordinates.
-
-### Input via ADB
-```bash
-adb shell input tap 500 300           # tap at coordinates
-adb shell input text "hello"          # type text
-adb shell input keyevent 66           # Enter key (KEYCODE_ENTER)
-adb shell input swipe 300 500 300 100 # swipe gesture
-adb shell input keyevent 4            # Back button
-```
-
-### Key Limitations
-- **WebViews:** uiautomator tree is empty/shallow for WebView content. Flutter apps can crash uiautomator with StackOverflowError.
-- **Auth:** Cannot read app tokens on non-rooted devices. Agent must log in through UI or keep sessions alive.
-- **Latency:** uiautomator dump takes 1-3 seconds. Screenshot approach is faster per frame but less structured.
-
-### WebView Gap — Potential Differentiator
-Android WebViews expose a CDP debug port when the app is built with `WebView.setWebContentsDebuggingEnabled(true)`. If accessible, barebrowse's CDP + ARIA expertise can fill the gap that all other Android agent tools struggle with — structured content inside WebViews instead of falling back to screenshots.
-
-Discovery: `adb forward tcp:9222 localabstract:webview_devtools_remote_<pid>`
-
-## Windows Technical Details
-
-### UI Automation (UIA)
-Windows' accessibility API. Exposes a tree of AutomationElements with: ControlType, Name, AutomationId, BoundingRectangle, IsEnabled, patterns (Invoke, Value, Toggle, Selection, Scroll, etc.).
-
-Best desktop accessibility tree. Covers Win32, WPF, WinForms, UWP, and most Electron apps.
-
-### Input
-SendInput API for keyboard/mouse. Or higher-level: `pyautogui`, `robotjs`, `nut.js`.
-
-### Competition
-Microsoft's own UFO project (8k stars) dominates this space. They have first-party UIA access and deep investment. Competing here means competing with Microsoft on their own platform's APIs.
-
-## References
-- [DroidRun](https://github.com/droidrun/droidrun)
-- [DroidClaw](https://github.com/unitedbyai/droidclaw)
-- [agent-device](https://github.com/callstackincubator/agent-device)
-- [UFO (Microsoft)](https://github.com/microsoft/UFO)
-- [Agent-S](https://github.com/simular-ai/Agent-S)
-- [Cua](https://github.com/trycua/cua)
-- [Android uiautomator](https://developer.android.com/training/testing/other-components/ui-automator)
-- [Windows UI Automation](https://learn.microsoft.com/en-us/windows/win32/winauto/entry-uiauto-win32)

package/docs/00-context/assumptions.md

@@ -1,38 +0,0 @@
-# barebrowse -- Assumptions & Constraints
-
-## Hard constraints
-
-| Constraint | Detail |
-|-----------|--------|
-| **Chromium-only** | CDP protocol. Covers Chrome, Chromium, Edge, Brave, Vivaldi, Arc, Opera (~80% desktop share). Firefox later via WebDriver BiDi. |
-| **Node >= 22** | Built-in WebSocket (`globalThis.WebSocket`), built-in SQLite (`node:sqlite`). No polyfills. |
-| **Linux first** | Tested on Fedora/KDE/Wayland. macOS/Windows cookie extraction paths exist in auth.js but are untested. |
-| **Zero required deps** | Everything uses Node stdlib. Vanilla JS, ES modules, no build step. |
-| **Not a server** | Library that agents import. MCP wrapper included, HTTP wrapper is DIY. |
-
-## Assumptions
-
-- **User has Chromium installed.** At least one of: chromium-browser, google-chrome, brave-browser, microsoft-edge. `chromium.js` searches common paths.
-- **Cookie extraction needs unlocked profile.** Chromium cookies are AES-encrypted with a keyring key (KWallet on KDE, GNOME Keyring on GNOME). Firefox cookies are plaintext SQLite and always accessible.
-- **Headed mode requires manual browser launch.** User must start their browser with `--remote-debugging-port=9222`. barebrowse connects to it -- does not launch it.
-- **Hybrid fallback needs a running headed browser.** If headless is bot-blocked, hybrid kills headless and connects to headed on port 9222. That browser must already be running.
-- **Cookies expire.** Cookie injection works for existing sessions, not new logins. For sites requiring fresh auth, headed mode with user interaction is the fallback.
-- **One page per connect().** Each `connect()` call creates one page. For multiple tabs, call `connect()` multiple times.
-
-## Known limitations
-
-| Limitation | Impact | Workaround |
-|-----------|--------|------------|
-| No Firefox/WebKit support | ~20% of desktop users can't use native browser | Use Chromium as the automation target, Firefox as cookie source |
-| No file upload | Can't interact with file inputs | Not yet implemented (`Input.setFiles` via CDP) |
-| No drag and drop | Can't use drag-based UIs | Not yet implemented |
-| No cross-origin iframes | Content inside iframes invisible to ARIA tree | Frame tree traversal via CDP (medium effort) |
-| No CAPTCHAs | Cannot solve challenge pages | Headed mode lets user solve manually |
-| Canvas/WebGL opaque | No ARIA representation | Needs screenshot + vision model |
-| macOS/Windows untested | Cookie paths exist but may not work | Linux-only for now |
-
-## Risks
-
-- **CDP is not a stable API.** Chrome team can change it across versions. Mitigation: we use well-established domains (Accessibility, Input, Page, Network, DOM) that rarely break.
-- **Cookie consent patterns evolve.** New consent frameworks may not be detected by `consent.js`. Mitigation: best-effort, opt-out with `{ consent: false }`.
-- **Stealth patches are an arms race.** Bot detection evolves. Mitigation: headed mode with real browser profile is the ultimate fallback.

package/docs/00-context/system-state.md

@@ -1,402 +0,0 @@
-# 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 |
-| Wait for content | `page.waitFor({ text, selector })` | Poll for text or CSS selector to appear on page | Done |
-| Back / Forward | `page.goBack()` / `page.goForward()` | Browser history navigation via `Page.getNavigationHistory` | Done |
-| Drag | `page.drag(fromRef, toRef)` | Mouse down on source, move to target, release | Done |
-| Upload | `page.upload(ref, files)` | Set files on file input via `DOM.setFileInputFiles` | Done |
-| PDF | `page.pdf(opts)` | Export page as PDF via `Page.printToPDF` | Done |
-| Tabs | `page.tabs()` / `page.switchTab(index)` | List and switch between browser tabs | Done |
-| Dialog handling | Auto | JS alert/confirm/prompt auto-dismissed, logged to `page.dialogLog` | Done |
-| Save state | `page.saveState(filePath)` | Export cookies + localStorage to JSON for later `--storage-state` | 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** | ARIA tree scan, jsClick accept button. 29 languages | 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** | All-browser cookie merge (Firefox + Chromium), 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 |
-| **JS dialogs** (alert/confirm/prompt) | Auto-dismiss via `Page.handleJavaScriptDialog`, logged to `dialogLog` | Both |
-| **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 |
-|----------|--------------|------------|
-| 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: URL + pruning stats + 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
-
-Thirteen modules, 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` | ~280 | Auto-dismiss cookie consent dialogs, 29 languages |
-| `src/stealth.js` | 51 | Navigator patches for headless anti-detection |
-| `src/bareagent.js` | 161 | Tool adapter for bareagent Loop |
-| `src/daemon.js` | ~230 | Background HTTP server holding connect() session for CLI mode |
-| `src/session-client.js` | ~60 | HTTP client to daemon (sendCommand, readSession, isAlive) |
-| `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 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
-- 29 languages: EN, NL, DE, FR, ES, IT, PT, RU, UK, PL, CS, TR, RO, HU, EL, SV, DA, NO, FI, AR, FA, ZH, JA, KO, VI, TH, HI, ID/MS
-- 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
-Auto mode merges cookies from all detected browsers (Chromium + Firefox, last-write-wins by name+domain). No need to use Chromium as daily browser.
-- `browse()`: auto-injects merged cookies before navigation (opt-out with `{ cookies: false }`)
-- `connect()`: manual injection via `page.injectCookies(url, { browser: 'firefox' })`
-- MCP `goto`: auto-injects cookies before every navigation
-- 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 -- 64 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)
-- 10 integration tests (CLI session lifecycle: open/snapshot/goto/click/eval/console/network/close)
-- 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();
-```
-
-13 tools: browse, goto, snapshot, click, type, press, scroll, select, back, forward, drag, upload, 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"]
-    }
-  }
-}
-```
-
-12 tools: browse (one-shot), goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf.
-Action tools return `'ok'` -- agent calls `snapshot` explicitly (MCP tool calls are cheap to chain).
-`browse` and `snapshot` accept `maxChars` (default 30000) — large snapshots are saved to `.barebrowse/` and a file path is returned.
-Session runs in hybrid mode (headless + automatic headed fallback on bot detection). `goto` injects cookies from the user's browser before navigation.
-Session tools share a singleton page, lazy-created on first use.
-
-### CLI session -- for coding agents + human devs
-
-Shell commands that output to disk. Coding agents (Claude Code, Copilot, Cursor) read output files with their file tools -- no tokens wasted in tool responses.
-
-```bash
-barebrowse open https://example.com    # Start daemon + navigate
-barebrowse snapshot                    # → .barebrowse/page-*.yml
-barebrowse click 8                     # Click element
-barebrowse console-logs                # → .barebrowse/console-*.json
-barebrowse close                       # Kill daemon + browser
-```
-
-Architecture: `open` spawns a detached child process running an HTTP server on a random localhost port. Session state stored in `.barebrowse/session.json`. Subsequent commands POST to the daemon. `close` sends shutdown, daemon calls `page.close()` + `process.exit(0)`.
-
-Full commands: open, close, status, goto, back, forward, snapshot, screenshot, pdf, click, type, fill, press, scroll, hover, select, drag, upload, tabs, tab, eval, wait-idle, wait-for, console-logs, network-log, dialog-log, save-state.
-
-Self-sufficiency features (console/network capture, eval) let agents debug without guessing -- they see JS errors and failed requests directly.
-
-SKILL.md (`commands/barebrowse/SKILL.md`) teaches Claude Code the CLI commands. Install with `barebrowse install --skill`.
-
----
-
-## 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.** Tested on Linux only. Published to npm as `barebrowse`.
-
----
-
-## 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
-│   ├── daemon.js      # Background HTTP server for CLI session
-│   └── session-client.js  # HTTP client to daemon
-├── test/
-│   ├── unit/          # prune, auth, cdp tests
-│   └── integration/   # browse, interact, cli tests
-├── examples/
-│   ├── headed-demo.js # Interactive demo: Wikipedia → DuckDuckGo
-│   └── yt-demo.js     # YouTube demo: Firefox cookies → search → play video
-├── docs/
-│   ├── README.md             # Documentation navigation guide
-│   ├── 00-context/           # vision, assumptions, system-state (this file)
-│   ├── 01-product/           # prd.md
-│   ├── 03-logs/              # decisions, implementation, bugs, validation, insights
-│   ├── 04-process/           # dev-workflow, definition-of-done, testing (64 tests)
-│   └── archive/              # poc-plan.md
-├── mcp-server.js      # MCP server (JSON-RPC 2.0 over stdio)
-├── cli.js             # CLI entry: session commands, MCP, browse, install
-├── .mcp.json          # MCP server config for Claude Desktop / Cursor
-├── barebrowse.context.md  # LLM-consumable integration guide
-├── commands/
-│   ├── barebrowse.md         # CLI command reference (any agent)
-│   └── barebrowse/
-│       └── SKILL.md          # CLI command reference (Claude Code skill)
-├── package.json
-├── README.md
-└── CLAUDE.md
-```

package/docs/00-context/vision.md

@@ -1,52 +0,0 @@
-# barebrowse -- Vision
-
-## What it is
-
-A standalone vanilla JavaScript library that gives autonomous agents authenticated access to the web through the user's own Chromium browser. One package, one import, three modes.
-
-```js
-import { browse } from 'barebrowse';
-const snapshot = await browse('https://any-page.com');
-```
-
-barebrowse handles: finding the browser, connecting via CDP, injecting cookies, navigating, extracting the ARIA accessibility tree, and pruning it down to what an agent actually needs. The output is a clean, token-efficient snapshot of any web page -- authenticated as the real user.
-
-## What it is NOT
-
-- **Not a framework.** No plugin system, no config files, no lifecycle hooks.
-- **Not Playwright.** No bundled browser, no cross-engine abstraction, no 200MB download.
-- **Not an agent.** No LLM, no planning, no orchestration -- that's bareagent's job.
-- **Not a scraper.** It browses as the user, not as a bot harvesting data.
-
-## The core insight
-
-The user already has a browser. It's already logged in. It already passes Cloudflare. Instead of fighting the web with headless stealth tricks, **use what's already there**.
-
-CDP (Chrome DevTools Protocol) lets us connect to any Chromium-based browser -- the same one the user browses with daily. We get their cookies, their sessions, their anti-detection posture, for free.
-
-## The problem it solves
-
-Every AI agent that needs to read or interact with the web hits the same walls:
-
-1. **Cloudflare / bot detection** -- headless browsers get blocked
-2. **Authentication** -- sites require login, OAuth, session cookies
-3. **Token bloat** -- raw DOM is 100K+ tokens; agents need ~5K
-4. **Two consumers, same need** -- research agents (read pages) and personal assistants (click/type) both need an authenticated browser, but existing tools force you to choose one path
-
-## The bare- 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.
-
-## Success criteria
-
-1. `browse(url)` returns a pruned ARIA snapshot of any page, authenticated as the user
-2. Zero heavy dependencies -- no Playwright, no Puppeteer, no bundled browser
-3. Works with any installed Chromium-based browser
-4. Headless for research, headed for interaction, hybrid for autonomous agents
-5. Plugs into bareagent as plain tool functions
-6. An agent using barebrowse + bareagent can autonomously research the web and act on pages