barebrowse 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.4.4
+
+Snapshot URL prefix and MCP large-snapshot handling.
+
+### Snapshot URL (`src/index.js`)
+- First line of every snapshot is now `# <current-page-url>`
+- Works in both `browse()` (uses the url param) and `connect().snapshot()` (uses `Page.getNavigationHistory`)
+
+### MCP maxChars (`mcp-server.js`)
+- `browse` and `snapshot` tools accept `maxChars` param (default 30000)
+- If snapshot exceeds limit: saved to `.barebrowse/page-<timestamp>.yml`, returns file path message
+- If under limit: returned inline as before
+
+### Docs
+- barebrowse.context.md: snapshot format updated with URL line, maxChars documented
+- commands/barebrowse.md + SKILL.md: snapshot example updated
+- docs/00-context/system-state.md: pipeline step 8 updated, MCP maxChars noted
+
+## 0.4.3
+
+Cookie consent expanded to 29 languages.
+
+- Added: RU, UK, PL, CS, TR, RO, HU, EL, SV, DA, NO, FI, AR, FA, ZH, JA, KO, VI, TH, HI, ID/MS
+- Dialog hints for 11 more languages
+- `.npmignore`: added `.idea/` (leaked in 0.4.2 tarball)
+
 ## 0.4.2
 
 Authenticated browsing improvements. MCP sessions now auto-inject cookies and fall back to headed mode when bot-detected.

package/barebrowse.context.md

@@ -87,14 +87,13 @@ const snapshot = await browse('https://example.com', {
 
 ## Snapshot format
 
-The snapshot is a YAML-like ARIA tree. Each line is one node:
+The snapshot is a YAML-like ARIA tree. First line is the page URL, second is pruning stats, then the tree:
 
 ```
-- WebArea "Example Domain" [ref=1]
-  - heading "Example Domain" [level=1] [ref=3]
-  - paragraph [ref=5]
-    - StaticText "This domain is for use in illustrative examples." [ref=6]
-  - link "More information..." [ref=8]
+# https://example.com/
+# 379 chars → 45 chars (88% pruned)
+- heading "Example Domain" [level=1] [ref=3]
+- link "More information..." [ref=8]
 ```
 
 Key rules:
@@ -238,6 +237,8 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
 
 Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
 
+`browse` and `snapshot` accept a `maxChars` param (default 30000). If the snapshot exceeds the limit, it's saved to `.barebrowse/page-<timestamp>.yml` and a short message with the file path is returned instead.
+
 Session runs in hybrid mode (headless with automatic headed fallback on bot detection). `goto` injects cookies from the user's browser before navigation for authenticated access.
 
 Session tools share a singleton page, lazy-created on first use.

package/commands/barebrowse/SKILL.md

@@ -96,11 +96,9 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 The snapshot is a YAML-like ARIA tree. Each line is one node:
 
 ```
-- WebArea "Example Domain" [ref=1]
-  - heading "Example Domain" [level=1] [ref=3]
-  - paragraph [ref=5]
-    - StaticText "This domain is for use in illustrative examples." [ref=6]
-  - link "More information..." [ref=8]
+# https://example.com/
+# 379 chars → 45 chars (88% pruned)
+- heading "Example Domain" [level=1] [ref=3]
 ```
 
 - `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload

package/commands/barebrowse.md

@@ -95,11 +95,9 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 The snapshot is a YAML-like ARIA tree. Each line is one node:
 
 ```
-- WebArea "Example Domain" [ref=1]
-  - heading "Example Domain" [level=1] [ref=3]
-  - paragraph [ref=5]
-    - StaticText "This domain is for use in illustrative examples." [ref=6]
-  - link "More information..." [ref=8]
+# https://example.com/
+# 379 chars → 45 chars (88% pruned)
+- heading "Example Domain" [level=1] [ref=3]
 ```
 
 - `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload

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

@@ -155,7 +155,7 @@ Every action returns a **pruned ARIA snapshot** -- the agent's view of the page
 
 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
+                     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
@@ -311,6 +311,7 @@ Raw JSON-RPC 2.0 over stdio. Zero SDK dependencies. `npm install barebrowse` the
 
 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.
 

package/mcp-server.js

@@ -10,6 +10,19 @@
  */
 
 import { browse, connect } from './src/index.js';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_CHARS_DEFAULT = 30000;
+const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
+
+function saveSnapshot(text) {
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = join(OUTPUT_DIR, `page-${ts}.yml`);
+  writeFileSync(file, text);
+  return file;
+}
 
 let _page = null;
 
@@ -27,6 +40,7 @@ const TOOLS = [
       properties: {
         url: { type: 'string', description: 'URL to browse' },
         mode: { type: 'string', enum: ['headless', 'headed', 'hybrid'], description: 'Browser mode (default: headless)' },
+        maxChars: { type: 'number', description: 'Max chars to return inline. Larger snapshots are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
       },
       required: ['url'],
     },
@@ -45,7 +59,12 @@ const TOOLS = [
   {
     name: 'snapshot',
     description: 'Get the current ARIA snapshot of the session page. Returns a YAML-like tree with [ref=N] markers on interactive elements.',
-    inputSchema: { type: 'object', properties: {} },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        maxChars: { type: 'number', description: 'Max chars to return inline. Larger snapshots are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
+      },
+    },
   },
   {
     name: 'click',
@@ -141,9 +160,15 @@ const TOOLS = [
 
 async function handleToolCall(name, args) {
   switch (name) {
-    case 'browse':
-      return await browse(args.url, { mode: args.mode });
-
+    case 'browse': {
+      const text = await browse(args.url, { mode: args.mode });
+      const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
+      if (text.length > limit) {
+        const file = saveSnapshot(text);
+        return `Snapshot (${text.length} chars) saved to ${file}`;
+      }
+      return text;
+    }
     case 'goto': {
       const page = await getPage();
       try { await page.injectCookies(args.url); } catch {}
@@ -152,7 +177,13 @@ async function handleToolCall(name, args) {
     }
     case 'snapshot': {
       const page = await getPage();
-      return await page.snapshot();
+      const text = await page.snapshot();
+      const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
+      if (text.length > limit) {
+        const file = saveSnapshot(text);
+        return `Snapshot (${text.length} chars) saved to ${file}`;
+      }
+      return text;
     }
     case 'click': {
       const page = await getPage();
@@ -218,7 +249,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.4.2' },
+      serverInfo: { name: 'barebrowse', version: '0.4.4' },
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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

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