barebrowse 0.1.0 → 0.2.0

package/.claude/memory/AGENT_RULES.md

@@ -0,0 +1,251 @@
+# AI Agent Collaboration Guide
+
+## Table of Contents
+1. [Communication Protocol](#communication-protocol)
+2. [Development Standards](#development-standards)
+3. [Testing Standards](#testing-standards)
+4. [Environment](#environment)
+5. [Development Workflow](#development-workflow)
+6. [Twelve-Factor Reference](#twelve-factor-reference)
+7. [CLAUDE.md Stub](#claudemd-stub)
+8. [AI Agent Instructions](#ai-agent-instructions)
+
+---
+
+## Communication Protocol
+
+### Core Rules
+- **Clarity First**: Always ask clarifying questions when requirements are ambiguous
+- **Fact-Based**: Base all recommendations on verified, current information
+- **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
+- **Safety First**: Never modify critical systems without explicit understanding and approval
+
+### User Profile
+- **Technical Level**: Non-coder but technically savvy
+- **Learning Style**: Understands concepts, needs executable instructions
+- **Expects**: Step-by-step guidance with clear explanations
+- **Comfortable with**: Command-line operations and scripts
+
+### Required Safeguards
+- Always identify affected files before making changes
+- Never modify authentication systems without explicit permission
+- Never alter database schema without proper migration files
+- Explain what changes will be made and why
+
+---
+
+## Development Standards
+
+### Validate Before You Build
+
+- **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
+- **POC scope:** Cover the happy path and 2-3 common edge cases. If those work, the idea is sound
+- **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
+- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+
+### Dependency Hierarchy
+
+Always exhaust the simpler option before reaching for the next:
+
+1. **Vanilla language** — Write it yourself using only language primitives. If it's <50 lines and not security-critical, this is the answer
+2. **Standard library** — Use built-in modules (`os`, `json`, `pathlib`, `http`, `fs`, `crypto`). The stdlib is tested, maintained, and has zero supply chain risk
+3. **External library** — Only when both vanilla and stdlib are insufficient. Must pass the checklist below
+
+### External Dependency Checklist
+
+Before adding any external dependency, all of these must be true:
+- **Necessity:** Can't reasonably implement this with stdlib in <100 lines
+- **Maintained:** Active commits in the last 6 months, responsive maintainer
+- **Lightweight:** Few transitive dependencies (check the dep tree, not just the top-level)
+- **Established:** Widely used, not a single-maintainer hobby project for production-critical code
+- **Security-aware:** For security-critical domains (crypto, auth, sanitization, parsing untrusted input), a vetted library is *required* — never roll your own
+
+### Language Selection
+
+- **Use widely-adopted languages only** — Python, JavaScript/TypeScript, Go, Rust. No niche languages unless the domain demands it
+- **Pick the lightest language that fits the domain:** shell scripts for automation, Python for data/backend/CLI, TypeScript for web, Go for systems/infra, Rust for performance-critical
+- **Minimize the polyglot tax.** Every language in the stack adds CI config, tooling, and onboarding friction. Do not add a new language for one microservice — use what's already in the stack unless there's a compelling reason
+- **Vanilla over frameworks.** Express over NestJS, Flask over Django, unless the project genuinely needs the framework's structure. Structure can always be added later; removing a framework is painful
+
+### Build Rules
+
+- **Open-source only.** Always use open-source solutions. No vendor lock-in
+- **Lightweight over complex.** If two solutions solve the same problem, use the one with fewer moving parts, fewer dependencies, and less configuration
+- **Every line must have a purpose.** No speculative code, no "might need this later", no abstractions for one use case
+- **Simple > clever.** Readable code that a junior can follow beats elegant code that requires a PhD to debug
+- **Containerize only when necessary.** Start with a virtualenv or bare metal. Docker adds value for deployment parity and isolation — not for running a script
+
+### Red Flags — Stop and Flag These
+- Over-engineering simple problems
+- Adding external dependencies for trivial operations
+- Frameworks where a library or stdlib would suffice
+- Vendor-specific implementations when open alternatives exist
+- Skipping POC validation for unproven ideas
+
+---
+
+## Testing Standards
+
+### Rules
+
+**Test behavior, not implementation.** A test suite must give you confidence to refactor freely. If changing internal code (without changing behavior) breaks tests, those tests are liabilities, not assets.
+
+**Follow the Testing Trophy** (not the Testing Pyramid):
+- Few unit tests — only for pure logic, algorithms, and complex calculations
+- Many integration tests — the sweet spot; test real components working together
+- Some E2E tests — cover critical user journeys end-to-end
+- Static analysis — types and linters catch bugs cheaper than tests
+
+### When to Write Tests
+
+- **After the design stabilizes, not during exploration.** Do not TDD a prototype — you'll write 500 tests for code you delete tomorrow. First make it work (POC), then make it right (refactor + tests), then make it fast
+- **Write tests when the code has users.** If a function is called by other modules or exposed to users, it needs tests. Internal helpers that only serve one caller don't need their own test file
+- **Write tests for bugs.** Every bug fix must include a regression test that fails before the fix and passes after. This is the highest-value test you can write
+- **Write tests before refactoring.** Before changing working code, write characterization tests first to lock in current behavior, then refactor with confidence
+- **Do not write tests for glue code.** Code that just wires components together (calls A then B then C) is tested at the integration level, not unit level
+
+### TDD: When It Works and When It Doesn't
+
+- **TDD works for:** Pure functions, algorithms, parsers, validators, data transformations — anything with clear inputs and outputs
+- **TDD does not work for:** Exploring a design, building a POC, or unstable interfaces. Writing tests for unstable APIs creates churn and false confidence
+- **The rule:** You must understand what you're building before you TDD it. TDD is a design tool for known problems, not a discovery tool for unknown ones
+- **Red-green-refactor discipline:** If you do TDD, follow the cycle strictly. Write a failing test, write minimal code to pass, refactor. Do not write 20 tests then implement — that's front-loading waste
+
+### What Makes a Good Test
+
+- **Tests real behavior.** Call the public API, assert on observable output. Do not reach into internals
+- **Fails for the right reason.** A good test fails when the feature is broken, not when the implementation changes
+- **Reads like a spec.** Someone unfamiliar with the code must understand what the feature does by reading the test
+- **Self-contained.** Each test sets up its own state, runs, and cleans up. No ordering dependencies between tests
+- **Fast and deterministic.** Flaky tests erode trust. If a test depends on timing, network, or global state, fix that dependency
+
+### Anti-Patterns — Do Not Do These
+
+- **Mocking more than 60% of the test.** If most of the test is mock setup, you're testing mocks, not code. Use real implementations with `tmp_path`, `:memory:` SQLite, or test containers
+- **Smoke tests.** `assert result is not None` proves nothing. Assert on specific values, structure, or side effects
+- **Testing private methods.** If you need to test a private method, either it should be public or the public method's tests should cover it
+- **Mirroring implementation.** Tests that replicate the source code line-by-line break on every refactor and catch zero bugs
+- **Test-only production code.** Never add methods, flags, or branches to production code solely for testing. Use dependency injection instead
+
+### Test Organization
+
+- **Co-locate tests with packages:** `packages/<pkg>/tests/` not a root `tests/` directory. Each package owns its tests
+- **Separate by type:**
+  ```
+  packages/<pkg>/tests/
+    unit/           # Fast, isolated, mocked deps, <1s each
+    integration/    # Real DB, filesystem, multi-component, <10s each
+    e2e/            # Full workflows, subprocess calls, <60s each
+    conftest.py     # Shared fixtures for this package
+  ```
+- **One test file per module** (not per function). `test_auth.py` tests the auth module, not `test_login.py` + `test_logout.py` + `test_session.py`
+- **No duplicate test files.** Before creating a new test file, check if one already exists for that module
+
+### Markers and Signals
+
+| Marker | Purpose | CI Behavior |
+|--------|---------|-------------|
+| `@pytest.mark.slow` | Runtime > 5s | Run in full suite, skip in quick checks |
+| `@pytest.mark.ml` | Requires ML deps (torch, etc.) | Skip if deps not installed |
+| `@pytest.mark.real_api` | Calls external APIs | Skip in CI — run manually before release |
+
+**CI runs for fast signals:**
+- `pytest -m "not slow and not ml and not real_api"` — fast gate on every push (~30s)
+- `pytest` — full suite on PR merge or nightly
+- Package-level runs for targeted debugging: `pytest packages/core/tests/`
+
+### Coverage and Ratios
+
+- **Do not chase a coverage number.** 80% coverage with meaningless tests is worse than 40% with behavior-testing integration tests
+- **Cover the critical path first.** Data layer, auth, payment, core business logic — before helper utilities
+- **Coverage tells you what's NOT tested, not what IS tested.** High coverage with bad assertions is false confidence
+- **Delete tests that don't catch bugs.** If a test has never failed (or only fails on refactors), it's not providing value
+
+**Target ratio:** ~20% unit, ~60% integration, ~15% E2E, ~5% manual/exploratory
+
+### Test Tooling Standards
+
+- Use `tmp_path` for filesystem tests, `:memory:` or `tmp_path` SQLite for DB tests
+- Use dependency injection over `@patch` — it's more readable and survives refactors
+- Tests must be self-sufficient — no dependency on project directories, user config, or environment state
+- Use factories or builders for test data, not raw constructors with 15 arguments
+- Keep test fixtures close to where they're used. Shared fixtures in `conftest.py`, not a global test utilities package
+
+---
+
+## Environment
+
+- **OS**: Fedora Linux (use `dnf` for packages, `systemctl` for services)
+- **Testing**: pytest (Python), Jest/Vitest (JS/TS), Playwright (browser automation)
+
+---
+
+## Development Workflow
+
+### Environments
+- **Development**: Local machines
+- **Staging**: VPS with isolated database
+- **Production**: VPS with containerized setup
+
+### Deployment Strategy
+
+**Simple Projects:** `Local → GitHub → VPS (direct deployment)`
+
+**Complex Projects:** `Local → GitHub → GHCR → VPS (containerized)`
+
+---
+
+## Twelve-Factor Reference
+
+The [Twelve-Factor App](https://12factor.net) methodology for modern, scalable applications:
+
+| # | Factor | Rule |
+|---|--------|------|
+| 1 | Codebase | One repo per app, multiple deploys from same codebase |
+| 2 | Dependencies | Explicitly declare and isolate all dependencies |
+| 3 | Config | Store config in environment variables, never in code |
+| 4 | Backing Services | Treat databases, caches, queues as attached resources |
+| 5 | Build, Release, Run | Strict separation between build, release, and run stages |
+| 6 | Processes | Run as stateless processes, persist state externally |
+| 7 | Port Binding | Apps are self-contained, export services via port binding |
+| 8 | Concurrency | Scale out via the process model, not bigger instances |
+| 9 | Disposability | Fast startup, graceful shutdown, idempotent operations |
+| 10 | Dev/Prod Parity | Keep dev, staging, and production as similar as possible |
+| 11 | Logs | Treat logs as event streams to stdout |
+| 12 | Admin Processes | Run admin/maintenance tasks as one-off processes |
+
+---
+
+## CLAUDE.md Stub
+
+Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions.
+
+```markdown
+## 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. Express over NestJS, Flask over Django, unless the project genuinely needs the framework. 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.
+
+For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.
+```
+
+---
+
+## AI Agent Instructions
+
+When working with this user:
+1. **Always verify** you understand the requirements before proceeding
+2. **Provide step-by-step** instructions with clear explanations
+3. **Include ready-to-run** scripts and commands
+4. **Explain the "why"** behind technical recommendations
+5. **Flag potential issues** before they become problems
+6. **Suggest simpler alternatives** when appropriate
+7. **Never modify** authentication or database schema without explicit permission
+8. **Always identify** which files will be affected by changes

package/.claude/settings.local.json

@@ -0,0 +1,30 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wc:*)",
+      "Bash(flatpak list)",
+      "WebSearch",
+      "Bash(tail:*)",
+      "Bash(grep:*)",
+      "Bash(rpm -qa)",
+      "Bash(node:*)",
+      "Bash(cp:*)",
+      "Bash(ls:*)",
+      "Bash(head:*)",
+      "Bash(which kwalletcli:*)",
+      "Bash(kwallet-query:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(npm view:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(npm whoami:*)",
+      "Bash(npm pack:*)",
+      "Bash(npm publish:*)",
+      "Skill(git-commit)",
+      "Bash(python3:*)",
+      "Bash(printf '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}\\\\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}\\\\n' | timeout 5 node /home/hamr/PycharmProjects/barebrowse/mcp-server.js 2>/dev/null)",
+      "Bash(chmod +x:*)"
+    ]
+  }
+}

package/.claude/stash/barebrowse-research-2026-02-22.md

@@ -0,0 +1,49 @@
+# Stash: barebrowse Research & Repo Creation
+**Timestamp:** 2026-02-22
+**Session focus:** Research steipete repos, design shared browsing layer
+
+## Key Decisions
+
+1. **Researched steipete/sweetlink** — daemon + WebSocket + CDP architecture for driving real browser tabs. Not headless — opposite approach. Good ideas, overcomplicated for our needs.
+
+2. **Researched steipete/sweet-cookie** — TS library extracting cookies from real browser profiles (Chrome/FF/Safari). Direct fit for mcprune's Cloudflare/auth-wall problem.
+
+3. **Identified the parallel** — mcprune (headless DOM reading) and Multis (interactive browsing) share the same underlying need: get a browser context that loads any URL, authenticated as the user, without being blocked.
+
+4. **Designed `barebrowse`** — a unified browsing layer with 3 modes:
+   - `headless` — Playwright + cookie injection + stealth (mcprune)
+   - `headed` — CDP connect to running Chrome (Multis)
+   - `hybrid` — try headless, auto-fallback to headed
+
+5. **Key simplification over sweetlink** — skip daemon entirely, use CDP directly. Playwright wraps CDP already. No WebSocket bridge, no in-page runtime injection.
+
+6. **Named it `barebrowse`** — follows bare- ecosystem (bareagent, barebrowse, mcprune, multis)
+
+## Work Completed
+
+- Created repo: `~/PycharmProjects/barebrowse/` (git init, main branch)
+- Moved research doc: `mcprune/docs/peter-repos.md` → `barebrowse/docs/prd.md`
+- PRD includes: architecture diagrams, API sketches, 4-phase POC plan, repos to study, package structure
+
+## Repos to Borrow From
+
+| Repo | Take |
+|---|---|
+| steipete/sweet-cookie | Cookie extraction (TS) |
+| steipete/sweetlink | Selector discovery, click patterns, CDP dual-channel |
+| steipete/canvas | Stealth/anti-detection config |
+
+## Next Steps
+
+- [ ] Start barebrowse POC Phase 1 (headless + cookies)
+- [ ] Wire mcprune to use barebrowse instead of direct Playwright
+- [ ] Design Multis headed-mode integration
+
+## Bare Ecosystem Map
+
+```
+bareagent  → agent orchestration
+barebrowse → browser access layer (NEW)
+mcprune    → DOM snapshot pruning
+multis     → personal assistant
+```

package/.claude/stash/phase3-interactions-complete.md

@@ -0,0 +1,69 @@
+# Phase 3 Interactions — Complete
+
+**Date:** 2026-02-22
+**Session:** Real-world interaction testing + fixes
+
+## What Was Done
+
+### Fixes to `src/interact.js`
+1. **scrollIntoView before click** — `DOM.scrollIntoViewIfNeeded` in `getCenter()` before `DOM.getBoxModel`
+2. **`press(key)` function** — 14-key KEY_MAP (Enter, Tab, Escape, Backspace, Delete, arrows, Home/End, PageUp/Down, Space). Enter has `text: '\r'`, Tab has `text: '\t'` for proper form submission.
+3. **`type({ clear: true })`** — Ctrl+A select-all + Backspace before typing to replace pre-filled content
+4. **Key event text field** — Without `text: '\r'` on Enter keyDown, form `onsubmit` never fires
+
+### Additions to `src/index.js`
+- `page.press(key)` — wired to `cdpPress`
+- `page.waitForNavigation(timeout)` — `Page.loadEventFired` promise
+
+### Tests: 54/54 passing
+- `test/integration/interact.test.js` (15 tests, 8 suites):
+  - Round 1: data: URL fixture (7 tests — click, type, clear, offscreen scroll, Enter submit, unknown key error, link navigation)
+  - Round 2: Google Search (consent handling, type+Enter+nav — bot-blocked but flow works)
+  - Round 3: Wikipedia (article link click + navigation)
+  - Round 4: GitHub (SPA navigation with settle time)
+  - Round 5: DuckDuckGo (search + results — headless-friendly)
+  - Round 6: Hacker News (story link click + navigation)
+  - Round 7: Reddit/old.reddit.com (with fallback to www.reddit.com)
+  - Round 8: Firefox cookie injection (extractCookies → injectCookies → Network.getAllCookies verification)
+
+### `examples/headed-demo.js`
+10-step demo: Wikipedia → click link → DuckDuckGo → type query → Enter → results. Requires `chromium-browser --remote-debugging-port=9222`.
+
+### YouTube Demo (ad-hoc, in /tmp)
+Proved the full loop: Firefox cookies extracted → injected into headed Chromium → YouTube consent bypassed → searched "Family Portrait Pink" → clicked and played the video. User watched it happen live.
+
+## Key Findings
+
+### Real-world breakage patterns
+- **Cookie consent walls** block everything (Google, YouTube). Need locale-aware button matching or cookie injection to bypass.
+- **Bot detection** (Google, Reddit) blocks headless. Headed mode with real cookies is the fix.
+- **ARIA roles vary wildly** — DuckDuckGo search box is `LabelText` not `textbox`, Google's is `combobox` with `[expanded=false]` between role and ref.
+- **`Page.loadEventFired` doesn't fire** for data: URL → data: URL navigation or SPA transitions.
+- **`Page.frameNavigated` fires too early** — page DOM not ready yet, snapshots return empty.
+- **Example.com link text changed** from "More information..." to "Learn more" — real sites change.
+- **IANA page about example domains** contains "Example Domain" text — can't assert absence.
+- **Act mode prunes links** on simple pages like example.com — need browse mode to find clickable links.
+
+### Firefox → Chromium cookie flow (proven)
+```
+Firefox cookies.sqlite (plaintext) → extractCookies({ browser: 'firefox', domain })
+  → injectCookies(session, cookies) via Network.setCookie
+  → headless/headed Chromium uses user's sessions
+```
+Works for YouTube (8 cookies), Google (35 cookies), GitHub, etc.
+
+## Docs Updated
+- `docs/poc-plan.md` — Phase 3 DoD checkboxes checked, test section expanded
+- `docs/blueprint.md` — interactions section updated, "Real-world testing" marked DONE, wait strategies partially done
+- `docs/prd.md` — wait strategies and cookie auth decision updated
+
+## Commits
+1. `6017113` — feat(interact): add scrollIntoView, press(), clear, waitForNavigation
+2. `41bed12` — test: add real-site rounds + headed demo, update docs
+
+## What's Next (not started)
+- Phase 4: Hybrid mode (headless → headed fallback)
+- Stealth patches (`navigator.webdriver`, etc.)
+- More wait strategies (network idle, element presence)
+- Shopping/checkout flows, login forms, dropdowns
+- Screenshot capture for visual verification

package/.claude/stash/phase3-prep.md

@@ -0,0 +1,88 @@
+# Stash: barebrowse Phase 3 Prep
+**Timestamp:** 2026-02-22
+**Session focus:** Built Phase 1 + Phase 2 of barebrowse POC
+
+## What barebrowse Is
+Vanilla JS library — CDP-direct browsing for autonomous agents. URL in → pruned ARIA snapshot out. No Playwright, no bundled browser. Uses user's installed Chromium.
+
+## Completed Work
+
+### Phase 1 — CDP + ARIA Foundation (DONE)
+- `src/chromium.js` (142 lines) — Find/launch any Chromium browser, parse CDP WebSocket URL from stderr
+- `src/cdp.js` (148 lines) — Vanilla WebSocket CDP client with flattened session support (sessionId at top level)
+- `src/aria.js` (69 lines) — Format ARIA tree as YAML-like text, skip InlineTextBox/LineBreak noise
+- `src/index.js` (223 lines) — `browse(url)` and `connect(opts)` public API
+
+### Phase 2 — Auth + Prune (DONE)
+- `src/auth.js` (279 lines) — Cookie extraction from Chromium (AES-128-CBC + KWallet/GNOME keyring) and Firefox (plaintext). Injection via CDP `Network.setCookie`. Uses `node:sqlite` with `immutable=1` URI to read live DBs.
+- `src/prune.js` (472 lines) — Full port of mcprune's 9-step pruning pipeline adapted for CDP ARIA tree format. Two modes: `act` (actions only) and `browse` (keeps content).
+
+### Tests — 39/39 passing
+- `test/unit/prune.test.js` — 16 tests (pruning logic, pure function)
+- `test/unit/auth.test.js` — 7 tests (cookie extraction from Firefox)
+- `test/unit/cdp.test.js` — 5 tests (CDP client, browser launch, ARIA tree)
+- `test/integration/browse.test.js` — 11 tests (end-to-end pipeline)
+
+### Docs
+- `docs/prd.md` — Comprehensive PRD with all decisions and rationale
+- `docs/poc-plan.md` — 4-phase plan with DoD, test instructions, repo study reference
+- `CLAUDE.md` — Project dev rules stub
+
+## Key Architecture Decisions (settled)
+- CDP direct, not Playwright (no 200MB download)
+- ARIA tree, not DOM (semantic, token-efficient)
+- Pruning built-in from mcprune (not optional)
+- Three modes: headless/headed/hybrid (one flag, same CDP code)
+- Chromium-only (CDP constraint, Firefox later via BiDi)
+- Vanilla JS, ES modules, Node >= 22, zero required deps
+- sweet-cookie not on npm — wrote our own auth.js
+- Unique temp dirs per browser instance (`/tmp/barebrowse-{pid}-{timestamp}`)
+
+## Test Results
+- HN: 51,932 chars raw → 27,312 pruned (47% reduction on minimal site)
+- example.com: browse mode keeps paragraphs, act mode keeps only heading
+- Cookie extraction: 181 Firefox cookies across 54 domains
+- GitHub cookies found but `logged_in=no` (user not logged in via Firefox)
+
+## System Details
+- OS: Fedora Linux, KDE Plasma, Wayland
+- Node: 22.22.0 (built-in WebSocket, experimental node:sqlite)
+- Browser: Firefox default, Chromium installed via `sudo dnf install chromium`
+- Chromium binary: `/usr/bin/chromium-browser`
+- KWallet running with Chromium Safe Storage key available
+
+## What's Next — Phase 3 (Headed + Interaction)
+
+**Goal:** Connect to user's running browser, click/type on pages.
+
+**Files to create/update:**
+- Update `src/chromium.js` — `connect()` mode for running browser on debug port
+- `src/interact.js` — Click (`Input.dispatchMouseEvent`), type (`Input.dispatchKeyEvent`), scroll. Resolve ARIA nodeId to DOM coordinates.
+- Update `src/index.js` — Add click/type to connect() page handle
+
+**Key challenge:** Mapping ARIA nodeId to screen coordinates for click targeting. CDP `DOM.getBoxModel` + `Accessibility.getFullAXTree` node→backendDOMNodeId mapping needed.
+
+**Prerequisite:** User launches browser with `--remote-debugging-port=9222`
+
+## Phase 4 — Hybrid + bareagent Integration
+- `src/stealth.js` — Anti-detection patches via `Runtime.evaluate`
+- Hybrid mode: try headless, detect CF/403, fall back to headed
+- Wire as bareagent tool functions
+
+## Repos Studied
+- steipete/sweet-cookie — concept only (not on npm, wrote our own)
+- steipete/sweetlink — CDP-direct concept, skip daemon/WS bloat
+- steipete/canvas — stealth patterns noted for Phase 4
+- mcprune (own) — pruning logic fully ported
+
+## File Inventory
+```
+src/index.js      223 lines  — Public API
+src/chromium.js   142 lines  — Browser find/launch
+src/cdp.js        148 lines  — CDP WebSocket client
+src/aria.js        69 lines  — ARIA tree formatter
+src/auth.js       279 lines  — Cookie extraction + injection
+src/prune.js      472 lines  — ARIA tree pruning
+                 1333 total source
+                  576 total tests
+```

package/.mcp.json

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

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 0.2.0
+
+Agent integration release. MCP server, bareagent adapter, and interaction features that make barebrowse usable as a standalone tool or embedded browsing layer.
+
+### New: MCP server
+- Raw JSON-RPC 2.0 over stdio, zero SDK dependencies
+- 7 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`
+- Singleton session page, lazy-created on first session tool call
+- `npx barebrowse mcp` to start, `npx barebrowse install` to auto-configure
+
+### New: MCP auto-installer
+- `npx barebrowse install` detects Claude Desktop, Cursor, and Claude Code
+- Writes MCP config automatically -- no manual JSON editing
+- Reports status for each detected client
+
+### New: bareagent tool adapter
+- `import { createBrowseTools } from 'barebrowse/bareagent'`
+- Returns `{ tools, close }` with 9 bareagent-compatible tools
+- Action tools auto-return fresh snapshot after each action (300ms settle)
+- Tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot
+
+### New: stealth patches
+- `src/stealth.js` -- anti-detection for headless mode
+- Uses `Page.addScriptToEvaluateOnNewDocument` (runs before page scripts)
+- Patches: `navigator.webdriver`, `navigator.plugins`, `navigator.languages`, `window.chrome`, `Permissions.prototype.query`
+- Auto-applied in headless mode
+
+### New: interactions
+- `page.hover(ref)` -- mouse move to element center, triggers hover styles/tooltips
+- `page.select(ref, value)` -- native `<select>` (set value + change event) or custom dropdown (click + find option)
+- `page.screenshot(opts)` -- `Page.captureScreenshot`, returns base64 (png/jpeg/webp)
+
+### New: wait strategies
+- `page.waitForNetworkIdle(opts)` -- resolve when no pending requests for N ms (default 500)
+- `page.waitForNavigation()` now SPA-aware -- falls back gracefully when no `loadEventFired` fires
+
+### New: hybrid mode
+- `mode: 'hybrid'` in `browse()` -- tries headless, detects challenge pages (Cloudflare, etc.), falls back to headed
+- Challenge detection via ARIA tree heuristic ("Just a moment", "Checking your browser", etc.)
+
+### New: CLI
+- `npx barebrowse mcp` -- start MCP server
+- `npx barebrowse install` -- auto-configure MCP clients
+- `npx barebrowse browse <url>` -- one-shot browse, print snapshot to stdout
+
+### New: documentation
+- `README.md` -- complete guide: idea, token savings, modes, library vs MCP, bareagent wiring
+- `barebrowse.context.md` -- LLM-consumable integration guide for AI assistants
+- `docs/testing.md` -- test pyramid, all 54 tests documented, CI guidance
+- `docs/blueprint.md` -- updated with full 10-step pipeline, module table, integration sections
+
+### Changed
+- `package.json` -- subpath exports (`./bareagent`), `bin` entry, keywords
+- `src/index.js` -- stealth auto-applied in headless via `createPage()`, `type()` param renamed to avoid shadowing
+- `src/interact.js` -- `getCenter()` reused by new `hover()` function
+
+### Tests
+- 54 tests passing (was 47 in 0.1.0)
+- All existing tests unchanged and passing
+
+---
+
+## 0.1.0
+
+Initial release. CDP-direct browsing with ARIA snapshots.
+
+### Core
+- `browse(url, opts)` -- one-shot: URL in, pruned ARIA snapshot out
+- `connect(opts)` -- session: navigate, interact, observe across pages
+- Three modes: headless (default), headed (connect to running browser)
+- Zero required dependencies, vanilla JS, ES modules, Node >= 22
+
+### Modules
+- `src/cdp.js` -- WebSocket CDP client with flattened session support
+- `src/chromium.js` -- find/launch any installed Chromium browser
+- `src/aria.js` -- format ARIA tree as YAML-like text
+- `src/auth.js` -- cookie extraction from Firefox (SQLite) and Chromium (AES + keyring)
+- `src/prune.js` -- 9-step ARIA pruning pipeline (47-95% token reduction)
+- `src/interact.js` -- click, type (with clear), press (14 special keys), scroll
+- `src/consent.js` -- auto-dismiss cookie consent dialogs (7 languages, 16+ sites tested)
+
+### Features
+- Cookie injection from Firefox/Chromium into headless CDP sessions
+- Permission suppression (notifications, geolocation, camera, mic) via launch flags + CDP
+- Cookie consent auto-dismiss across EN, NL, DE, FR, ES, IT, PT
+- `waitForNavigation()` for post-click page loads
+- Unique temp dirs per headless instance to avoid profile locking
+
+### Tests
+- 47 tests across 5 files (unit: prune, auth, cdp; integration: browse, interact)
+- Real-site testing: Google, Wikipedia, GitHub, DuckDuckGo, YouTube, HN, Reddit

package/CLAUDE.md

@@ -0,0 +1,22 @@
+## 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
+
+- **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)
+- **Key files:** `src/index.js` (API), `src/cdp.js` (CDP client), `src/chromium.js` (browser launch), `src/aria.js` (ARIA formatting)
+- **Docs:** `docs/prd.md` (decisions + rationale), `docs/poc-plan.md` (phases + DoD)
+
+For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.