barebrowse 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.7
+
+Snapshot URL prefix format changed from `# <url>` to `url: <url>`.
+
+- Fix: MCP clients (Claude Code) stripped `#`-prefixed lines as comments, making the URL invisible to agents
+- Snapshot first line is now `url: <current-page-url>` (was `# <current-page-url>`)
+- Stats line no longer prefixed with `#`
+
+## 0.4.6
+
+- README wording fix
+
 ## 0.4.5
 
 - README: "What this is" rewritten — concise, no implementation details exposed

package/README.md

@@ -105,27 +105,7 @@ For code examples, API reference, and wiring instructions, see **[barebrowse.con
 
 ## What it handles automatically
 
-This is the obstacle course your agent doesn't have to think about:
-
-| 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, camera, mic) | Launch flags + CDP Browser.setPermission auto-deny | Both |
-| **Media autoplay blocked** | Autoplay policy flag on launch | Both |
-| **Login walls** | Cookie extraction from all browsers (Firefox + Chromium merged), injected via CDP | Both |
-| **Pre-filled form inputs** | Select-all + delete before typing | Both |
-| **Off-screen elements** | Scrolled into view before every click | Both |
-| **Form submission** | Enter key triggers onsubmit | Both |
-| **Tab between fields** | Tab key moves focus correctly | Both |
-| **SPA navigation** (YouTube, GitHub) | SPA-aware wait: frameNavigated + loadEventFired | Both |
-| **Bot detection** (Google, Reddit) | Stealth patches (headless) + automatic headed fallback with real cookies | Hybrid |
-| **navigator.webdriver leak** | Patched before page scripts run: webdriver, plugins, languages, chrome object | Headless |
-| **JS dialogs** (alert/confirm/prompt) | Auto-dismiss via CDP, logged for inspection | Both |
-| **Profile locking** | Unique temp dir per headless instance | Headless |
-| **ARIA noise** | 9-step pruning pipeline (ported from mcprune): wrapper collapse, noise removal, landmark promotion | Both |
+Cookie consent walls (29 languages), login walls (cookie extraction from your browsers), bot detection (stealth patches + automatic headed fallback), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.
 
 ## What the agent sees
 
@@ -202,6 +182,28 @@ URL -> find/launch browser (chromium.js)
 - Any Chromium-based browser installed (Chrome, Chromium, Brave, Edge, Vivaldi)
 - Linux tested (Fedora/KDE). macOS/Windows cookie paths exist but untested.
 
+## The bare ecosystem
+
+Three vanilla JS modules. Zero dependencies. Same API patterns.
+
+| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) |
+|---|---|---|---|
+| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents an Android device |
+| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out |
+| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, UIAutomator2 |
+| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP |
+| **Solo or together** | Orchestrates both as tools | Works standalone | Works standalone |
+
+**What you can build:**
+
+- **Headless automation** — scrape sites, fill forms, extract data, monitor pages on a schedule
+- **QA & testing** — automated test suites for web and Android apps without heavyweight frameworks
+- **Personal AI assistants** — chatbots that browse the web or control your phone on your behalf
+- **Remote device control** — manage Android devices over WiFi, including on-device via Termux
+- **Agentic workflows** — multi-step tasks where an AI plans, browses, and acts across web and mobile
+
+**Why this exists:** Most automation stacks ship 200MB of opinions before you write a line of code. These don't. Install, import, go.
+
 ## License
 
 MIT

package/baremobile.md

@@ -0,0 +1,105 @@
+# 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/01-product/prd.md

@@ -131,6 +131,30 @@ After connection, every CDP command is the same. Three modes = ~20 extra lines i
 
 **What stays in mcprune:** The Playwright MCP proxy architecture. mcprune can continue to exist as a Playwright-based MCP server for users who want that path. But for barebrowse consumers, pruning is built in.
 
+### Obstacle Course — What barebrowse handles automatically
+
+The agent doesn't have to think about any of this:
+
+| 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, camera, mic) | Launch flags + CDP Browser.setPermission auto-deny | Both |
+| **Media autoplay blocked** | Autoplay policy flag on launch | Both |
+| **Login walls** | Cookie extraction from all browsers (Firefox + Chromium merged), injected via CDP | Both |
+| **Pre-filled form inputs** | Select-all + delete before typing | Both |
+| **Off-screen elements** | Scrolled into view before every click | Both |
+| **Form submission** | Enter key triggers onsubmit | Both |
+| **Tab between fields** | Tab key moves focus correctly | Both |
+| **SPA navigation** (YouTube, GitHub) | SPA-aware wait: frameNavigated + loadEventFired | Both |
+| **Bot detection** (Google, Reddit) | Stealth patches (headless) + automatic headed fallback with real cookies | Hybrid |
+| **navigator.webdriver leak** | Patched before page scripts run: webdriver, plugins, languages, chrome object | Headless |
+| **JS dialogs** (alert/confirm/prompt) | Auto-dismiss via CDP, logged for inspection | Both |
+| **Profile locking** | Unique temp dir per headless instance | Headless |
+| **ARIA noise** | 9-step pruning pipeline (ported from mcprune): wrapper collapse, noise removal, landmark promotion | Both |
+
 ---
 
 ## API Design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -223,10 +223,10 @@ export async function connect(opts = {}) {
       const raw = formatTree(result.tree);
       const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
       const pageUrl = entries[currentIndex]?.url || '';
-      if (pruneOpts === false) return `# ${pageUrl}\n` + raw;
+      if (pruneOpts === false) return `url: ${pageUrl}\n` + raw;
       const pruned = pruneTree(result.tree, { mode: pruneOpts?.mode || 'act' });
       const out = formatTree(pruned);
-      const stats = `# ${pageUrl}\n# ${raw.length.toLocaleString()} chars → ${out.length.toLocaleString()} chars (${Math.round((1 - out.length / raw.length) * 100)}% pruned)`;
+      const stats = `url: ${pageUrl}\n${raw.length.toLocaleString()} chars → ${out.length.toLocaleString()} chars (${Math.round((1 - out.length / raw.length) * 100)}% pruned)`;
       return stats + '\n' + out;
     },