barebrowse 0.3.2 → 0.4.0

package/.claude/skills/barebrowse/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Bash(barebrowse:*)
 
 # barebrowse CLI — Browser Automation for Agents
 
-Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, and bot detection automatically.
+Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, JS dialogs, and bot detection automatically.
 
 ## Quick Start
 
@@ -36,15 +36,21 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 - `--browser=firefox|chromium` — Cookie source
 - `--prune-mode=act|read` — Default pruning mode
 - `--timeout=N` — Navigation timeout in ms
+- `--proxy=URL` — HTTP/SOCKS proxy server
+- `--viewport=WxH` — Viewport size (e.g. 1280x720)
+- `--storage-state=FILE` — Load cookies/localStorage from JSON file
 
 ### Navigation
 
 | Command | Output |
 |---------|--------|
 | `barebrowse goto <url>` | Navigates, waits for load, dismisses consent. Prints "ok". |
+| `barebrowse back` | Go back in browser history. |
+| `barebrowse forward` | Go forward in browser history. |
 | `barebrowse snapshot` | ARIA snapshot → `.barebrowse/page-<timestamp>.yml` |
 | `barebrowse snapshot --mode=read` | Read mode: keeps all text (for content extraction) |
 | `barebrowse screenshot` | Screenshot → `.barebrowse/screenshot-<timestamp>.png` |
+| `barebrowse pdf [--landscape]` | PDF export → `.barebrowse/page-<timestamp>.pdf` |
 
 ### Interaction
 
@@ -57,6 +63,15 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 | `barebrowse scroll <deltaY>` | Scroll page (positive=down, negative=up) |
 | `barebrowse hover <ref>` | Hover over element (triggers tooltips) |
 | `barebrowse select <ref> <value>` | Select dropdown option |
+| `barebrowse drag <fromRef> <toRef>` | Drag element to another element |
+| `barebrowse upload <ref> <files..>` | Upload file(s) to a file input element |
+
+### Tabs
+
+| Command | Description |
+|---------|-------------|
+| `barebrowse tabs` | List open tabs (index, url, title) |
+| `barebrowse tab <index>` | Switch to tab by index |
 
 ### Debugging
 
@@ -64,9 +79,17 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 |---------|--------|
 | `barebrowse eval <expression>` | Evaluate JS in page, print result |
 | `barebrowse wait-idle` | Wait for network idle (no requests for 500ms) |
+| `barebrowse wait-for [opts]` | Wait for content to appear on page |
 | `barebrowse console-logs` | Console logs → `.barebrowse/console-<timestamp>.json` |
 | `barebrowse network-log` | Network log → `.barebrowse/network-<timestamp>.json` |
 | `barebrowse network-log --failed` | Only failed/4xx/5xx requests |
+| `barebrowse dialog-log` | JS dialog log → `.barebrowse/dialogs-<timestamp>.json` |
+| `barebrowse save-state` | Cookies + localStorage → `.barebrowse/state-<timestamp>.json` |
+
+**wait-for flags:**
+- `--text=STRING` — Wait for text to appear in page body
+- `--selector=CSS` — Wait for CSS selector to match
+- `--timeout=N` — Max wait time in ms (default: 30000)
 
 ## Snapshot Format
 
@@ -80,7 +103,7 @@ The snapshot is a YAML-like ARIA tree. Each line is one node:
   - link "More information..." [ref=8]
 ```
 
-- `[ref=N]` — Use this number with click, type, fill, hover, select
+- `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload
 - Refs change on every snapshot — always take a fresh snapshot before interacting
 - **act mode** (default): interactive elements + labels — for clicking, typing, navigating
 - **read mode**: all text content — for reading articles, extracting data
@@ -90,7 +113,7 @@ The snapshot is a YAML-like ARIA tree. Each line is one node:
 1. `barebrowse open <url>` — start session
 2. `barebrowse snapshot` — observe page (read the .yml file)
 3. Decide action based on snapshot content
-4. `barebrowse click/type/fill/press/scroll <ref>` — act
+4. `barebrowse click/type/fill/press/scroll/drag/upload <ref>` — act
 5. `barebrowse snapshot` — observe result (refs are now different!)
 6. Repeat 3-5 until goal achieved
 7. `barebrowse close` — clean up
@@ -100,6 +123,11 @@ The snapshot is a YAML-like ARIA tree. Each line is one node:
 - **Always snapshot before interacting** — refs are ephemeral and change every time
 - **Use `fill` instead of `type`** when replacing existing text in input fields
 - **Use `--mode=read`** for snapshot when you need to extract article content or data
+- **Use `back`/`forward`** to navigate browser history instead of re-entering URLs
+- **Use `upload`** for file inputs — pass absolute paths to the files
+- **Use `wait-for`** when content loads asynchronously — more reliable than `wait-idle`
+- **Check `dialog-log`** if JS alerts/confirms were auto-dismissed during your session
+- **Use `save-state`** to persist cookies/localStorage for later sessions via `--storage-state`
 - **Check `console-logs`** when page behavior seems wrong — JS errors show up there
 - **Check `network-log --failed`** to debug missing content or broken API calls
 - **Use `eval`** as an escape hatch when ARIA tree doesn't show what you need

package/CHANGELOG.md

@@ -1,10 +1,53 @@
 # Changelog
 
+## 0.4.0
+
+10 new features inspired by Playwright MCP. All validated manually against live sites.
+
+### New commands
+- `back` / `forward` — Browser history navigation via `Page.getNavigationHistory`
+- `drag <fromRef> <toRef>` — Drag-and-drop between elements (Kanban boards, sliders)
+- `upload <ref> <files..>` — File upload via `DOM.setFileInputFiles`
+- `pdf [--landscape]` — PDF export via `Page.printToPDF`
+- `tabs` / `tab <index>` — List and switch between browser tabs
+- `wait-for --text=X --selector=Y` — Poll for content to appear on page
+- `save-state` — Export cookies + localStorage to JSON
+- `dialog-log` — View auto-dismissed JS dialog history
+
+### New open flags
+- `--proxy=URL` — HTTP/SOCKS proxy server (pass-through to Chromium launch args)
+- `--viewport=WxH` — Set viewport dimensions via `Emulation.setDeviceMetricsOverride`
+- `--storage-state=FILE` — Load cookies/localStorage from previously saved JSON
+
+### Built-in behavior
+- JS dialog auto-dismiss — alert/confirm/prompt handled via `Page.handleJavaScriptDialog`, logged to `dialogLog`
+
+### Library API additions (connect())
+- `goBack()`, `goForward()`, `drag(fromRef, toRef)`, `upload(ref, files)`
+- `pdf(opts)`, `tabs()`, `switchTab(index)`, `waitFor({ text, selector, timeout })`
+- `saveState(filePath)`, `dialogLog` array
+- New connect opts: `proxy`, `viewport`, `storageState`
+
+### MCP server
+- 5 new tools: `back`, `forward`, `drag`, `upload`, `pdf` (12 total, was 7)
+
+### bareagent adapter
+- 4 new tools: `back`, `forward`, `drag`, `upload` (13 total, was 9)
+
+### Docs
+- SKILL.md updated with all new commands and flags
+- README: new actions table, dialog handling in obstacle course
+- barebrowse.context.md: full connect() API table updated
+- docs/00-context/system-state.md: actions + obstacle tables updated
+
+## 0.3.3
+
+- Simplified skill install paths: Claude Code (`.claude/` project, `~/.claude/` global), other agents (`.barebrowse/commands/` project, `~/.config/barebrowse/commands/` global)
+
 ## 0.3.2
 
-- Skill install table in README: per-agent instructions for Claude Code, Cursor, Windsurf, Copilot (project + global scope)
-- Clarified that `npm install barebrowse` is still required — the skill file is documentation only
-- New: `docs/skill-template.md` — generic template for any CLI tool to create a skill file, with frontmatter reference, install locations, and skill-vs-MCP comparison
+- Skill install instructions in README, clarified `npm install` still required — skill is documentation only
+- New: `docs/skill-template.md` — generic template for any CLI tool to create a skill file
 
 ## 0.3.1
 

package/README.md

@@ -45,15 +45,11 @@ Outputs go to `.barebrowse/` as files -- agents read them with their file tools,
 
 **Teach your agent the commands** by installing the skill file (a markdown reference the agent reads as context). The CLI tool itself still needs `npm install barebrowse` -- the skill just teaches the agent how to use it.
 
-| Agent | Project scope | Global scope |
-|-------|---------------|--------------|
-| **Claude Code** | `.claude/skills/barebrowse/SKILL.md` (auto-detected) | `barebrowse install --skill` |
-| **Cursor** | `.cursor/rules/barebrowse.md` | `~/.cursor/rules/barebrowse.md` |
-| **Windsurf** | `.windsurf/rules/barebrowse.md` | `~/.windsurf/rules/barebrowse.md` |
-| **Copilot** | Append to `.github/copilot-instructions.md` | N/A |
-| **Any agent** | Copy `SKILL.md` to project root or context dir | Varies |
+**Claude Code:** `.claude/skills/barebrowse/` (project) or `~/.claude/skills/barebrowse/` (global, via `barebrowse install --skill`).
 
-Source file: [.claude/skills/barebrowse/SKILL.md](.claude/skills/barebrowse/SKILL.md). For writing your own skill files: [docs/skill-template.md](docs/skill-template.md).
+**Other agents:** `.barebrowse/commands/` (project) or `~/.config/barebrowse/commands/` (global). Copy [SKILL.md](.claude/skills/barebrowse/SKILL.md) there.
+
+For writing your own skill files for other CLI tools: [docs/skill-template.md](docs/skill-template.md).
 
 ### 2. MCP server -- for Claude Desktop, Cursor, and other MCP clients
 
@@ -127,6 +123,7 @@ This is the obstacle course your agent doesn't have to think about:
 | **SPA navigation** (YouTube, GitHub) | SPA-aware wait: frameNavigated + loadEventFired | Both |
 | **Bot detection** (Google, Reddit) | Stealth patches (headless) + headed fallback with real cookies | Both |
 | **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 |
 
@@ -150,6 +147,7 @@ Everything the agent can do through barebrowse:
 | Action | What it does |
 |--------|-------------|
 | **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
+| **Back / Forward** | Browser history navigation |
 | **Snapshot** | Pruned ARIA tree with `[ref=N]` markers (40-90% token reduction) |
 | **Click** | Scroll into view + mouse click at element center |
 | **Type** | Focus + insert text, with option to clear existing content first |
@@ -157,9 +155,16 @@ Everything the agent can do through barebrowse:
 | **Scroll** | Mouse wheel up or down |
 | **Hover** | Move mouse to element center (triggers tooltips, hover states) |
 | **Select** | Set dropdown value (native select or custom dropdown) |
+| **Drag** | Drag one element to another (Kanban boards, sliders) |
+| **Upload** | Set files on a file input element |
 | **Screenshot** | Page capture as base64 PNG/JPEG/WebP |
+| **PDF** | Export page as PDF |
+| **Tabs** | List open tabs, switch between them |
+| **Wait for content** | Poll for text or CSS selector to appear on page |
 | **Wait for navigation** | SPA-aware: works for full page loads and pushState |
 | **Wait for network idle** | Resolve when no pending requests for 500ms |
+| **Dialog handling** | Auto-dismiss JS alert/confirm/prompt dialogs |
+| **Save state** | Export cookies + localStorage to JSON |
 | **Inject cookies** | Extract from Firefox/Chromium and inject via CDP |
 | **Raw CDP** | Escape hatch for any Chrome DevTools Protocol command |
 

package/barebrowse.context.md

@@ -56,6 +56,8 @@ const snapshot = await browse('https://example.com', {
 | Method | Args | Returns | Notes |
 |---|---|---|---|
 | `goto(url, timeout?)` | url: string, timeout: number (default 30000) | void | Navigate + wait for load + dismiss consent |
+| `goBack()` | -- | void | Navigate back in browser history |
+| `goForward()` | -- | void | Navigate forward in browser history |
 | `snapshot(pruneOpts?)` | false or { mode: 'act'\|'read' } | string | ARIA tree with `[ref=N]` markers. Pass `false` for raw. |
 | `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
 | `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
@@ -63,13 +65,26 @@ const snapshot = await browse('https://example.com', {
 | `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. |
 | `hover(ref)` | ref: string | void | Move mouse to element center |
 | `select(ref, value)` | ref: string, value: string | void | Set `<select>` value or click custom dropdown option |
+| `drag(fromRef, toRef)` | fromRef: string, toRef: string | void | Drag from one element to another |
+| `upload(ref, files)` | ref: string, files: string[] | void | Set files on a file input (absolute paths) |
 | `screenshot(opts?)` | { format?: 'png'\|'jpeg'\|'webp', quality?: number } | string (base64) | Page screenshot |
+| `pdf(opts?)` | { landscape?: boolean } | string (base64) | Export page as PDF |
+| `tabs()` | -- | Array<{index, url, title, targetId}> | List open browser tabs |
+| `switchTab(index)` | index: number | void | Switch to tab by index |
+| `waitFor(opts)` | { text?: string, selector?: string, timeout?: number } | void | Poll for content to appear on page |
 | `waitForNavigation(timeout?)` | timeout: number (default 30000) | void | Wait for page load or frame navigation |
 | `waitForNetworkIdle(opts?)` | { timeout?: number, idle?: number } | void | Wait until no pending requests for `idle` ms (default 500) |
+| `saveState(filePath)` | filePath: string | void | Export cookies + localStorage to JSON file |
 | `injectCookies(url, opts?)` | url: string, { browser?: string } | void | Extract cookies from user's browser and inject via CDP |
+| `dialogLog` | -- | Array<{type, message, timestamp}> | Auto-dismissed JS dialog history |
 | `cdp` | -- | object | Raw CDP session for escape hatch: `page.cdp.send(method, params)` |
 | `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
 
+**connect() options** (in addition to mode/port/consent):
+- `proxy: 'http://...'` — HTTP/SOCKS proxy for browser
+- `viewport: '1280x720'` — Set viewport dimensions
+- `storageState: 'file.json'` — Load cookies/localStorage from saved state
+
 ## Snapshot format
 
 The snapshot is a YAML-like ARIA tree. Each line is one node:

package/cli.js

@@ -2,35 +2,7 @@
 /**
  * cli.js -- barebrowse CLI entry point.
  *
- * Session commands:
- *   barebrowse open [url] [flags]     Open browser session (daemon)
- *   barebrowse close                  Close session + kill daemon
- *   barebrowse status                 Check if session is running
- *
- * Navigation:
- *   barebrowse goto <url>             Navigate to URL
- *   barebrowse snapshot [--mode]      Get pruned ARIA snapshot → file
- *   barebrowse screenshot [--format]  Take screenshot → file
- *
- * Interaction:
- *   barebrowse click <ref>            Click element by ref
- *   barebrowse type <ref> <text>      Type text into element
- *   barebrowse fill <ref> <text>      Clear + type (replace content)
- *   barebrowse press <key>            Press special key
- *   barebrowse scroll <deltaY>        Scroll page
- *   barebrowse hover <ref>            Hover over element
- *   barebrowse select <ref> <value>   Select dropdown value
- *
- * Self-sufficiency:
- *   barebrowse eval <expression>      Evaluate JS in page
- *   barebrowse wait-idle [--timeout]  Wait for network idle
- *   barebrowse console-logs           Dump console logs → file
- *   barebrowse network-log            Dump network log → file
- *
- * Legacy / tools:
- *   barebrowse browse <url> [mode]    One-shot browse (stdout)
- *   barebrowse mcp                    Start MCP server (stdio)
- *   barebrowse install [--skill]      Auto-configure MCP or install skill
+ * See `barebrowse` (no args) for full command reference.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
@@ -84,6 +56,26 @@ if (args.includes('--daemon-internal')) {
   await cmdProxy('console-logs', { level: parseFlag('--level'), clear: hasFlag('--clear') });
 } else if (cmd === 'network-log') {
   await cmdProxy('network-log', { failed: hasFlag('--failed') });
+} else if (cmd === 'back') {
+  await cmdProxy('back');
+} else if (cmd === 'forward') {
+  await cmdProxy('forward');
+} else if (cmd === 'drag' && args[1] && args[2]) {
+  await cmdProxy('drag', { fromRef: args[1], toRef: args[2] });
+} else if (cmd === 'upload' && args[1] && args[2]) {
+  await cmdProxy('upload', { ref: args[1], files: args.slice(2).filter(a => !a.startsWith('--')).map(f => resolve(f)) });
+} else if (cmd === 'pdf') {
+  await cmdProxy('pdf', { landscape: hasFlag('--landscape') });
+} else if (cmd === 'tabs') {
+  await cmdProxy('tabs');
+} else if (cmd === 'tab' && args[1]) {
+  await cmdProxy('tab', { index: Number(args[1]) });
+} else if (cmd === 'wait-for') {
+  await cmdProxy('wait-for', { text: parseFlag('--text'), selector: parseFlag('--selector'), timeout: parseFlag('--timeout') });
+} else if (cmd === 'save-state') {
+  await cmdProxy('save-state');
+} else if (cmd === 'dialog-log') {
+  await cmdProxy('dialog-log');
 } else {
   printUsage();
 }
@@ -111,6 +103,9 @@ async function cmdOpen() {
     timeout: parseFlag('--timeout'),
     pruneMode: parseFlag('--prune-mode') || 'act',
     consent: !hasFlag('--no-consent'),
+    proxy: parseFlag('--proxy'),
+    viewport: parseFlag('--viewport'),
+    storageState: parseFlag('--storage-state'),
   };
 
   try {
@@ -208,6 +203,9 @@ async function runDaemonInternal() {
     timeout: parseFlag('--timeout'),
     pruneMode: parseFlag('--prune-mode') || 'act',
     consent: !hasFlag('--no-consent'),
+    proxy: parseFlag('--proxy'),
+    viewport: parseFlag('--viewport'),
+    storageState: parseFlag('--storage-state'),
   };
   const outputDir = parseFlag('--output-dir') || resolve('.barebrowse');
   const url = parseFlag('--url');
@@ -360,11 +358,17 @@ Session:
     --timeout=N                     Navigation timeout in ms
     --prune-mode=act|read           Default pruning mode
     --no-consent                    Skip consent dismissal
+    --proxy=URL                     HTTP/SOCKS proxy server
+    --viewport=WxH                  Viewport size (e.g. 1280x720)
+    --storage-state=FILE            Load cookies/localStorage from JSON file
 
 Navigation:
   barebrowse goto <url>             Navigate to URL
+  barebrowse back                   Go back in history
+  barebrowse forward                Go forward in history
   barebrowse snapshot [--mode=M]    ARIA snapshot -> .barebrowse/page-*.yml
   barebrowse screenshot [--format]  Screenshot -> .barebrowse/screenshot-*.png
+  barebrowse pdf [--landscape]      PDF export -> .barebrowse/page-*.pdf
 
 Interaction:
   barebrowse click <ref>            Click element
@@ -374,12 +378,24 @@ Interaction:
   barebrowse scroll <deltaY>        Scroll (positive=down)
   barebrowse hover <ref>            Hover element
   barebrowse select <ref> <value>   Select dropdown value
+  barebrowse drag <from> <to>       Drag element to another
+  barebrowse upload <ref> <files..> Upload files to file input
+
+Tabs:
+  barebrowse tabs                   List open tabs
+  barebrowse tab <index>            Switch to tab by index
 
 Debugging:
   barebrowse eval <expression>      Run JS in page context
   barebrowse wait-idle [--timeout]  Wait for network idle
+  barebrowse wait-for [opts]        Wait for text/selector to appear
+    --text=STRING                   Wait for text in page body
+    --selector=CSS                  Wait for CSS selector to match
+    --timeout=N                     Max wait time in ms (default: 30000)
   barebrowse console-logs           Console logs -> .barebrowse/console-*.json
   barebrowse network-log            Network log -> .barebrowse/network-*.json
+  barebrowse dialog-log             JS dialog log -> .barebrowse/dialogs-*.json
+  barebrowse save-state             Cookies + localStorage -> .barebrowse/state-*.json
 
 One-shot:
   barebrowse browse <url> [mode]    Browse + print snapshot to stdout

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

@@ -48,6 +48,14 @@ Every action returns a **pruned ARIA snapshot** -- the agent's view of the page
 | 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 |
@@ -70,6 +78,7 @@ Every action returns a **pruned ARIA snapshot** -- the agent's view of the page
 | **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 |
 

package/docs/skill-template.md

@@ -63,23 +63,11 @@ Show a real example so the agent knows what to expect.
 
 The skill file is just a `.md` file placed where the agent can find it:
 
-### Claude Code
+**Claude Code:** `.claude/skills/your-tool/` (project) or `~/.claude/skills/your-tool/` (global).
 
-| Scope | Location | How |
-|-------|----------|-----|
-| **This project only** | `.claude/skills/your-tool/SKILL.md` | Copy file into project |
-| **All projects (global)** | `~/.config/claude/skills/your-tool/SKILL.md` | Copy file to home config |
+**Other agents:** `.your-tool/commands/` (project) or `~/.config/your-tool/commands/` (global).
 
-### Other coding agents (Cursor, Windsurf, Copilot, etc.)
-
-| Agent | Project scope | Global scope |
-|-------|---------------|--------------|
-| **Cursor** | `.cursor/rules/your-tool.md` | `~/.cursor/rules/your-tool.md` |
-| **Windsurf** | `.windsurf/rules/your-tool.md` | `~/.windsurf/rules/your-tool.md` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` (append) | N/A |
-| **Generic** | Drop in project root as `your-tool.context.md` | Varies by agent |
-
-> **Note:** Non-Claude agents ignore the YAML frontmatter — they just read it as markdown context. The `allowed-tools` field is Claude Code specific.
+Non-Claude agents ignore the YAML frontmatter — they just read it as markdown context. The `allowed-tools` field is Claude Code specific.
 
 ## What the skill does NOT do
 
@@ -104,16 +92,15 @@ Both require the underlying tool to be installed. Choose based on your agent's c
 
 ## Example: barebrowse
 
-barebrowse ships its skill at `.claude/skills/barebrowse/SKILL.md`. Install options:
+barebrowse ships its skill at `.claude/skills/barebrowse/SKILL.md`:
 
 ```bash
-# Project-local (Claude Code picks it up automatically)
+# Claude Code — project
 cp node_modules/barebrowse/.claude/skills/barebrowse/SKILL.md .claude/skills/barebrowse/SKILL.md
 
-# Global (all projects)
+# Claude Code — global
 barebrowse install --skill
-# copies to ~/.config/claude/skills/barebrowse/SKILL.md
 
-# For Cursor
-cp node_modules/barebrowse/.claude/skills/barebrowse/SKILL.md .cursor/rules/barebrowse.md
+# Other agents — project or global
+cp node_modules/barebrowse/.claude/skills/barebrowse/SKILL.md .barebrowse/commands/SKILL.md
 ```

package/mcp-server.js

@@ -3,7 +3,7 @@
  * mcp-server.js — MCP server for barebrowse.
  *
  * Raw JSON-RPC 2.0 over stdio. No SDK dependency.
- * 7 tools: browse (one-shot), goto, snapshot, click, type, press, scroll.
+ * 12 tools: browse, goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf.
  *
  * Session tools share a singleton page, lazy-created on first use.
  * Action tools return 'ok' — agent calls snapshot explicitly to observe.
@@ -93,6 +93,50 @@ const TOOLS = [
       required: ['deltaY'],
     },
   },
+  {
+    name: 'back',
+    description: 'Go back in browser history. Returns ok.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'forward',
+    description: 'Go forward in browser history. Returns ok.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'drag',
+    description: 'Drag one element to another by refs from the snapshot. Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromRef: { type: 'string', description: 'Source element ref' },
+        toRef: { type: 'string', description: 'Target element ref' },
+      },
+      required: ['fromRef', 'toRef'],
+    },
+  },
+  {
+    name: 'upload',
+    description: 'Upload files to a file input element by ref. Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'File input element ref' },
+        files: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths' },
+      },
+      required: ['ref', 'files'],
+    },
+  },
+  {
+    name: 'pdf',
+    description: 'Export current page as PDF. Returns base64-encoded PDF data.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        landscape: { type: 'boolean', description: 'Landscape orientation (default: false)' },
+      },
+    },
+  },
 ];
 
 async function handleToolCall(name, args) {
@@ -129,6 +173,30 @@ async function handleToolCall(name, args) {
       await page.scroll(args.deltaY);
       return 'ok';
     }
+    case 'back': {
+      const page = await getPage();
+      await page.goBack();
+      return 'ok';
+    }
+    case 'forward': {
+      const page = await getPage();
+      await page.goForward();
+      return 'ok';
+    }
+    case 'drag': {
+      const page = await getPage();
+      await page.drag(args.fromRef, args.toRef);
+      return 'ok';
+    }
+    case 'upload': {
+      const page = await getPage();
+      await page.upload(args.ref, args.files);
+      return 'ok';
+    }
+    case 'pdf': {
+      const page = await getPage();
+      return await page.pdf({ landscape: args.landscape });
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }

package/package.json

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

package/src/bareagent.js

@@ -133,6 +133,44 @@ export function createBrowseTools(opts = {}) {
       },
       execute: async ({ ref, value }) => actionAndSnapshot((page) => page.select(ref, value)),
     },
+    {
+      name: 'back',
+      description: 'Go back in browser history. Returns the updated snapshot.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => actionAndSnapshot((page) => page.goBack()),
+    },
+    {
+      name: 'forward',
+      description: 'Go forward in browser history. Returns the updated snapshot.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => actionAndSnapshot((page) => page.goForward()),
+    },
+    {
+      name: 'drag',
+      description: 'Drag one element to another by their refs. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          fromRef: { type: 'string', description: 'Source element ref' },
+          toRef: { type: 'string', description: 'Target element ref' },
+        },
+        required: ['fromRef', 'toRef'],
+      },
+      execute: async ({ fromRef, toRef }) => actionAndSnapshot((page) => page.drag(fromRef, toRef)),
+    },
+    {
+      name: 'upload',
+      description: 'Upload files to a file input element. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string', description: 'File input element ref' },
+          files: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths' },
+        },
+        required: ['ref', 'files'],
+      },
+      execute: async ({ ref, files }) => actionAndSnapshot((page) => page.upload(ref, files)),
+    },
     {
       name: 'screenshot',
       description: 'Take a screenshot of the current page. Returns base64-encoded image.',

package/src/chromium.js

@@ -84,6 +84,10 @@ export async function launch(opts = {}) {
     '--disable-features=MediaRouter',
   ];
 
+  if (opts.proxy) {
+    args.push(`--proxy-server=${opts.proxy}`);
+  }
+
   if (opts.userDataDir) {
     args.push(`--user-data-dir=${opts.userDataDir}`);
   } else {

package/src/daemon.js

@@ -36,6 +36,9 @@ export async function startDaemon(opts, outputDir, initialUrl) {
   if (opts.timeout) args.push('--timeout', String(opts.timeout));
   if (opts.pruneMode) args.push('--prune-mode', opts.pruneMode);
   if (opts.consent === false) args.push('--no-consent');
+  if (opts.proxy) args.push('--proxy', opts.proxy);
+  if (opts.viewport) args.push('--viewport', opts.viewport);
+  if (opts.storageState) args.push('--storage-state', opts.storageState);
 
   const child = spawn(process.execPath, args, {
     detached: true,
@@ -71,6 +74,9 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     mode: opts.mode || 'headless',
     port: opts.port ? Number(opts.port) : undefined,
     consent: opts.consent,
+    proxy: opts.proxy,
+    viewport: opts.viewport,
+    storageState: opts.storageState,
   });
 
   // Console log capture
@@ -192,6 +198,63 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return { ok: true };
     },
 
+    async back() {
+      await page.goBack();
+      return { ok: true };
+    },
+
+    async forward() {
+      await page.goForward();
+      return { ok: true };
+    },
+
+    async drag({ fromRef, toRef }) {
+      await page.drag(String(fromRef), String(toRef));
+      return { ok: true };
+    },
+
+    async upload({ ref, files }) {
+      await page.upload(String(ref), files);
+      return { ok: true };
+    },
+
+    async pdf({ landscape }) {
+      const data = await page.pdf({ landscape });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `page-${ts}.pdf`);
+      writeFileSync(file, Buffer.from(data, 'base64'));
+      return { ok: true, file };
+    },
+
+    async tabs() {
+      const list = await page.tabs();
+      return { ok: true, value: list };
+    },
+
+    async tab({ index }) {
+      await page.switchTab(Number(index));
+      return { ok: true };
+    },
+
+    async 'wait-for'({ text, selector, timeout }) {
+      await page.waitFor({ text, selector, timeout });
+      return { ok: true };
+    },
+
+    async 'save-state'() {
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `state-${ts}.json`);
+      await page.saveState(file);
+      return { ok: true, file };
+    },
+
+    async 'dialog-log'() {
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `dialogs-${ts}.json`);
+      writeFileSync(file, JSON.stringify(page.dialogLog, null, 2));
+      return { ok: true, file, count: page.dialogLog.length };
+    },
+
     async eval({ expression }) {
       const result = await page.cdp.send('Runtime.evaluate', {
         expression,

package/src/index.js

@@ -13,7 +13,7 @@ import { createCDP } from './cdp.js';
 import { formatTree } from './aria.js';
 import { authenticate } from './auth.js';
 import { prune as pruneTree } from './prune.js';
-import { click as cdpClick, type as cdpType, scroll as cdpScroll, press as cdpPress, hover as cdpHover, select as cdpSelect } from './interact.js';
+import { click as cdpClick, type as cdpType, scroll as cdpScroll, press as cdpPress, hover as cdpHover, select as cdpSelect, drag as cdpDrag, upload as cdpUpload } from './interact.js';
 import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
 
@@ -45,12 +45,12 @@ export async function browse(url, opts = {}) {
       cdp = await createCDP(wsUrl);
     } else {
       // headless or hybrid (start headless)
-      browser = await launch();
+      browser = await launch({ proxy: opts.proxy });
       cdp = await createCDP(browser.wsUrl);
     }
 
     // Step 2: Create a new page target and attach
-    let page = await createPage(cdp, mode !== 'headed');
+    let page = await createPage(cdp, mode !== 'headed', { viewport: opts.viewport });
 
     // Step 2.5: Suppress permission prompts
     await suppressPermissions(cdp);
@@ -84,7 +84,7 @@ export async function browse(url, opts = {}) {
       const port = opts.port || 9222;
       const wsUrl = await getDebugUrl(port);
       cdp = await createCDP(wsUrl);
-      page = await createPage(cdp, false);
+      page = await createPage(cdp, false, { viewport: opts.viewport });
       await suppressPermissions(cdp);
       if (opts.cookies !== false) {
         try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
@@ -131,16 +131,41 @@ export async function connect(opts = {}) {
     const wsUrl = await getDebugUrl(port);
     cdp = await createCDP(wsUrl);
   } else {
-    browser = await launch();
+    browser = await launch({ proxy: opts.proxy });
     cdp = await createCDP(browser.wsUrl);
   }
 
-  const page = await createPage(cdp, mode !== 'headed');
+  const page = await createPage(cdp, mode !== 'headed', { viewport: opts.viewport });
   let refMap = new Map();
 
   // Suppress permission prompts for all modes
   await suppressPermissions(cdp);
 
+  // Load storage state (cookies + localStorage) from file
+  if (opts.storageState) {
+    try {
+      const { readFileSync } = await import('node:fs');
+      const state = JSON.parse(readFileSync(opts.storageState, 'utf8'));
+      if (state.cookies?.length) {
+        await page.session.send('Network.setCookies', { cookies: state.cookies });
+      }
+    } catch { /* file not found or invalid — continue without */ }
+  }
+
+  // Auto-dismiss JS dialogs (alert, confirm, prompt)
+  const dialogLog = [];
+  page.session.on('Page.javascriptDialogOpening', async (params) => {
+    dialogLog.push({
+      type: params.type,
+      message: params.message,
+      timestamp: new Date().toISOString(),
+    });
+    await page.session.send('Page.handleJavaScriptDialog', {
+      accept: params.type !== 'beforeunload',
+      promptText: params.defaultPrompt || '',
+    });
+  });
+
   return {
     async goto(url, timeout = 30000) {
       await navigate(page, url, timeout);
@@ -149,6 +174,20 @@ export async function connect(opts = {}) {
       }
     },
 
+    async goBack() {
+      const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
+      if (currentIndex <= 0) throw new Error('No previous page in history');
+      await page.session.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex - 1].id });
+      await new Promise((r) => setTimeout(r, 500));
+    },
+
+    async goForward() {
+      const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
+      if (currentIndex >= entries.length - 1) throw new Error('No next page in history');
+      await page.session.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex + 1].id });
+      await new Promise((r) => setTimeout(r, 500));
+    },
+
     async injectCookies(url, cookieOpts) {
       await authenticate(page.session, url, { browser: cookieOpts?.browser });
     },
@@ -193,6 +232,80 @@ export async function connect(opts = {}) {
       await cdpSelect(page.session, backendNodeId, value);
     },
 
+    async drag(fromRef, toRef) {
+      const fromId = refMap.get(fromRef);
+      const toId = refMap.get(toRef);
+      if (!fromId) throw new Error(`No element found for ref "${fromRef}"`);
+      if (!toId) throw new Error(`No element found for ref "${toRef}"`);
+      await cdpDrag(page.session, fromId, toId);
+    },
+
+    async upload(ref, files) {
+      const backendNodeId = refMap.get(ref);
+      if (!backendNodeId) throw new Error(`No element found for ref "${ref}"`);
+      await cdpUpload(page.session, backendNodeId, files);
+    },
+
+    async pdf(pdfOpts = {}) {
+      const { data } = await page.session.send('Page.printToPDF', {
+        landscape: pdfOpts.landscape || false,
+        printBackground: true,
+      });
+      return data; // base64
+    },
+
+    async tabs() {
+      const { targetInfos } = await cdp.send('Target.getTargets');
+      return targetInfos
+        .filter((t) => t.type === 'page')
+        .map((t, i) => ({ index: i, url: t.url, title: t.title, targetId: t.targetId }));
+    },
+
+    async switchTab(index) {
+      const { targetInfos } = await cdp.send('Target.getTargets');
+      const pages = targetInfos.filter((t) => t.type === 'page');
+      if (index < 0 || index >= pages.length) throw new Error(`Tab index ${index} out of range (0-${pages.length - 1})`);
+      await cdp.send('Target.activateTarget', { targetId: pages[index].targetId });
+    },
+
+    async waitFor(waitOpts = {}) {
+      const timeout = waitOpts.timeout || 30000;
+      const interval = 200;
+      const deadline = Date.now() + timeout;
+
+      while (Date.now() < deadline) {
+        if (waitOpts.text) {
+          const { result } = await page.session.send('Runtime.evaluate', {
+            expression: 'document.body?.innerText || ""',
+            returnByValue: true,
+          });
+          if (result.value && result.value.includes(waitOpts.text)) return;
+        }
+        if (waitOpts.selector) {
+          const { result } = await page.session.send('Runtime.evaluate', {
+            expression: `!!document.querySelector(${JSON.stringify(waitOpts.selector)})`,
+            returnByValue: true,
+          });
+          if (result.value) return;
+        }
+        await new Promise((r) => setTimeout(r, interval));
+      }
+      throw new Error(`waitFor timed out after ${timeout}ms`);
+    },
+
+    async saveState(filePath) {
+      const { cookies } = await page.session.send('Network.getAllCookies');
+      const { result } = await page.session.send('Runtime.evaluate', {
+        expression: 'JSON.stringify(Object.fromEntries(Object.entries(localStorage)))',
+        returnByValue: true,
+      });
+      const state = { cookies, localStorage: JSON.parse(result.value || '{}') };
+      const { writeFileSync } = await import('node:fs');
+      writeFileSync(filePath, JSON.stringify(state, null, 2));
+    },
+
+    dialogLog,
+
     async screenshot(screenshotOpts = {}) {
       const format = screenshotOpts.format || 'png';
       const params = { format };
@@ -260,7 +373,7 @@ async function suppressPermissions(cdp) {
  * @param {object} cdp - CDP client
  * @param {boolean} [stealth=false] - Apply stealth patches (headless only)
  */
-async function createPage(cdp, stealth = false) {
+async function createPage(cdp, stealth = false, pageOpts = {}) {
   const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
   const { sessionId } = await cdp.send('Target.attachToTarget', {
     targetId,
@@ -279,6 +392,16 @@ async function createPage(cdp, stealth = false) {
     await applyStealth(session);
   }
 
+  // Set viewport size if specified (e.g. "1280x720")
+  if (pageOpts.viewport) {
+    const [w, h] = pageOpts.viewport.split('x').map(Number);
+    if (w && h) {
+      await session.send('Emulation.setDeviceMetricsOverride', {
+        width: w, height: h, deviceScaleFactor: 1, mobile: false,
+      });
+    }
+  }
+
   return { session, targetId, sessionId };
 }
 

package/src/interact.js

@@ -206,3 +206,39 @@ export async function select(session, backendNodeId, value) {
     returnByValue: true,
   });
 }
+
+/**
+ * Drag one element to another.
+ * Scrolls source into view, mouse down, move to target center, mouse up.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} fromNodeId - Source element backendDOMNodeId
+ * @param {number} toNodeId - Target element backendDOMNodeId
+ */
+export async function drag(session, fromNodeId, toNodeId) {
+  const from = await getCenter(session, fromNodeId);
+  const to = await getCenter(session, toNodeId);
+
+  await session.send('Input.dispatchMouseEvent', {
+    type: 'mousePressed', x: from.x, y: from.y, button: 'left', clickCount: 1,
+  });
+  // Intermediate move for drag recognition
+  const midX = (from.x + to.x) / 2;
+  const midY = (from.y + to.y) / 2;
+  await session.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: midX, y: midY });
+  await session.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: to.x, y: to.y });
+  await session.send('Input.dispatchMouseEvent', {
+    type: 'mouseReleased', x: to.x, y: to.y, button: 'left', clickCount: 1,
+  });
+}
+
+/**
+ * Upload files to a file input element.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID of the file input
+ * @param {string[]} files - Absolute paths to files to upload
+ */
+export async function upload(session, backendNodeId, files) {
+  await session.send('DOM.setFileInputFiles', { files, backendNodeId });
+}