Changelog

v2.4.1 — iOS Element Path Resolution (2026-08-15)

A fix for native iOS automation, where interacting with elements deep in an app's hierarchy could fail with Element not found at path.

The iOS runner built its element tree from app.snapshot().dictionaryRepresentation, but resolved paths by walking children(matching: .any). Those two hierarchies are shaped differently, so a path read off the tree did not address the same node when replayed through the query API — deep paths drifted, and fill failed on them.

Paths now resolve against the snapshot hierarchy, then map back to a live XCUIElement by element type, identifier or label, and nearest frame centre. A matching child-walk fallback covers the case where snapshot() throws and tree building falls back to walkElement.

v2.4.0 — Camoufox Runtime, SEO/AEO/GEO Skills (2026-04-13)

A major release adding a full anti-detection browser runtime, a configuration system to control it, three SEO-focused read commands, and five end-to-end skills for search engine optimization, answer engine optimization, and generative engine optimization.

Camoufox — a new anti-detection browser runtime

Bypasses Cloudflare Turnstile, DataDome, PerimeterX, and fingerprint-based bot detection that standard Chromium can't get past. Unlike user-agent spoofing, Camoufox is a patched Firefox that spoofs navigator, canvas, WebGL, WebRTC, audio context, fonts, screen, and timezone at the C++ level — where detection scripts actually look.

npm install camoufox-js
browse --runtime camoufox goto https://protected-site.com

Verified working: navigator.platform returns Win32 on a macOS host when the profile sets os: "windows". The spoofing happens below the JavaScript surface, so detection scripts can't unmask it.

Full configuration system — 26 camoufox options

Every camoufox-js launch option is now configurable through browse.json or named profiles. No more hardcoded defaults — tune OS fingerprint, GeoIP, humanize delays, proxy, font list, screen size, WebRTC/WebGL blocking, Firefox prefs, addons, and more:

// browse.json
{
  "camoufox": {
    "geoip": true,
    "humanize": true,
    "os": ["windows", "macos", "linux"],
    "blockWebrtc": true,
    "proxy": { "server": "http://proxy:8080" }
  }
}

Named profiles — save per-scenario presets in .browse/camoufox-profiles/<name>.json and switch with one flag:

browse --camoufox-profile stealth-google goto https://google.com
browse --camoufox-profile fast-scrape goto https://ecom-site.com

browse profiles — lists all available camoufox profiles with their configured options. Profile names are sanitized against path traversal. Malformed JSON falls back gracefully; missing profiles throw with the list of available names.

Three new SEO commands (Content Extraction)

Built specifically for agents auditing websites — fast, structured, LLM-friendly output:

browse schema — extract JSON-LD, Microdata, and RDFa structured data. Returns parsed JSON. Covers Article, Product, Organization, FAQ, HowTo, and any schema.org type present.
browse meta — extract every meta tag that matters for SEO/AEO: title, description, canonical, Open Graph, Twitter Card, robots, viewport, plus full hreflang table (20+ locales on international sites).
browse headings — extract H1-H6 hierarchy with count summary ([h1:1 h2:7 h3:28]) and indented tree. Shows heading structure at a glance — critical for SEO and AEO readiness scoring.

All three are exposed via MCP, so Cursor/Claude Desktop/Windsurf can call them as browse_schema, browse_meta, browse_headings.

Five new skills for search optimization workflows

End-to-end workflows that use the new commands + existing browse capabilities (snapshot, detect, perf, perf-audit) to deliver complete audits:

/browse-seo — full SEO audit workflow: meta tags, headings, structured data, performance, links, mobile rendering, image alt audit, custom JS checks, final scored report with prioritized recommendations.
/browse-aeo — Answer Engine Optimization: page-audit mode (FAQ schema, answer readiness, authority signals) plus SERP-analysis mode (Google AI Overviews, Perplexity citations). Scores across 5 weighted dimensions.
/browse-geo — Generative Engine Optimization: multi-engine brand visibility monitoring across Google AI Overviews, Perplexity, and ChatGPT Search. Produces a cross-engine visibility matrix with citation positions, competing domains, and gap queries.
/browse-config — guided camoufox configuration generator. AskUserQuestion walks through presets (stealth, fast-scrape, google-safe, custom) and writes a valid browse.json or named profile. Shows the exact CLI command to use it.
/browse-stealth (v2 rewrite) — full rewrite against the new profile system. Covers Turnstile bypass, Google anti-bot evasion, authenticated sessions, and proxy rotation. Every step includes exact browse commands.

Runtime registry

Five browser engines now available via --runtime:

Runtime	Purpose
`playwright` (default)	Full compatibility, all features
`rebrowser`	Stealth patched Chromium
`camoufox` (new)	Anti-detection Firefox with C++ fingerprint spoofing
`lightpanda`	Lightweight Zig engine for static pages
`chrome`	System Chrome with real user profile

Under the hood

loadCamoufoxConfig() respects BROWSE_LOCAL_DIR, then project root .browse/, matching the rest of the system's path resolution
Config errors (missing profile, bad JSON) propagate immediately instead of silently falling back to defaults — no more silent wrong-config launches
listCamoufoxProfiles() extracted as a pure function for testability
19 new tests covering read commands, config mapping (with a key-list assertion pinning the 26-key contract), profile load/merge, malformed-JSON fallback, and the profiles command path
All five engines listed in --runtime help text and CLI error messages

v2.3.3 — Enable Command & Pre-built Binaries (2026-03-29)

browse enable android|ios|macos|all — one command to set up native drivers for any platform
Pre-built binaries (browse-ax, Android APKs, iOS runner) ship with npm install — no build step for most users
Fixed path resolution so native binaries work correctly when installed globally via npm

v2.3.0 — Simulator Lifecycle & Zero-Setup Native Automation (2026-03-29)

The headline feature: boot an Android emulator or iOS Simulator, launch any app, and interact with it — all from the CLI. On Android, everything installs automatically from a blank machine.

Simulator/Emulator management:

browse sim start --platform ios|android --app <id> [--visible] — boot, launch app, start automation driver
browse sim stop / browse sim status — clean lifecycle management
--visible opens the simulator/emulator window (default: headless background)
Switch apps on-the-fly: iOS reconfigures instantly, Android restarts the driver while keeping the emulator

Android zero-setup:

First sim start on a blank machine installs everything via Homebrew: adb, JDK 21, Android SDK, emulator, system image (API 35), and creates a default AVD
Driver APK builds automatically from source
No manual setup. No Android Studio required.

iOS improvements:

Runner no longer crashes when switching target apps (.activate() fix)
WebView scrolling works reliably (coordinate-based swipe instead of XCUITest swipeUp())
Swipe auto-targets the first scrollable element (webView, scrollView, table)

macOS improvements:

Click works on elements without AXPress (sidebar items, static text) via coordinate-based fallback
Modifier key combos: cmd+n, cmd+shift+s, ctrl+c
System Settings sidebar shows real labels ("Wi-Fi", "Bluetooth") instead of generic "text"

Android driver fixes:

Server socket works (added INTERNET permission to manifest)
WebView content visible in tree (reflection-based window roots + invisible-node workaround)
Scroll finds the right element (deepest scrollable, not toolbar)
Friendly messages when hitting scroll boundaries

Unified command surface:

All three platforms: snapshot, text, tap, fill, type, press, swipe, screenshot
Same @ref workflow everywhere

v2.2.1 — Unified Flows & Recording (2026-03-29)

Flows and chains route through the same execution pipeline with lifecycle hooks
Recording captures individual sub-steps, not wrapper commands
record export flow — new YAML export that round-trips with flow <file>
Flows work on all targets: browser, Android, iOS, macOS

v2.2.0 — Project-Local Extensibility (2026-03-29)

Custom audit rules — JSON rules in .browse/rules/ for perf-audit and a11y-audit thresholds
Custom detections — JSON signatures in .browse/detections/ for tech stack fingerprinting
Saved flows — flow save <name> / flow run <name> / flow list from .browse/flows/
All configurable via browse.json: rulePaths, detectionPaths, flowPaths, startupFlows

v2.1.0 — Workflow Commands & SDK (2026-03-29)

flow <file.yaml> — YAML automation scripts with steps, variables, and conditionals
retry — retry last failed command with exponential backoff
watch — watch DOM element for changes, trigger callback
SDK mode — createBrowser() returns direct Playwright access for embedding in Node.js apps

v2.0.0 — Native App Automation (2026-03-29)

Automate Android, iOS, and macOS apps through the same CLI:

Android — on-device instrumentation driver (Kotlin + NanoHTTPD), accessibility tree via UiAutomation, full HTTP protocol
iOS — Simulator bridge via XCUITest runner app, simctl lifecycle management
macOS — Swift bridge binary (browse-ax) using the Accessibility API
Unified CLI — --platform android|ios|macos --app <name> --device <serial>
Same @ref workflow across all platforms — snapshot -i assigns refs, tap @e1 clicks
Capability gating — browser-only commands blocked with clear errors on app targets
24 Android contract tests, doctor diagnostics for all platforms

v1.7.0 — Visual Analysis & Accessibility Audit (2026-03-29)

visual — inspect layout spacing, alignment, and overflow
a11y-audit — WCAG violation detection (missing labels, contrast, heading hierarchy)
layout — computed layout with contrast ratio for any element

v1.6.0 — Assertions & Performance Budgets (2026-03-28)

expect <expression> — assert on text, elements, attributes, counts, URL, title
perf-audit --budget <file> — pass/fail against performance budgets
wait --request <pattern> — wait for a specific network request
Playwright export format for recorded sessions

v1.5.2 — Network Body Capture & API Discovery (2026-03-28)

--network-bodies — capture request/response bodies (256KB limit per entry)
request <url-pattern> — inspect captured request/response for a URL
api — list discovered API endpoints from network traffic
Write commands now wait for network + DOM to settle before returning

v1.5.1 — Domain Architecture (2026-03-28)

Major structural refactor — 9 domain directories, AutomationTarget interface, unified execution pipeline. CLI help and MCP tools auto-generated from registry. 530 tests.

v1.5.0 — Snapshot Context (2026-03-28)

--context delta — ARIA diff with refs after write commands (+2 -1 =12)
--context full — complete snapshot with fresh refs after writes
Eliminates snapshot → action → snapshot round-trips

v1.4.5 — Action Context (2026-03-28)

--context — write commands append state delta (URL, title, dialog, tabs, errors)
Always-on in MCP mode — agents always see what changed
O(1) capture via running counters

v1.4.4 — Audit Persistence (2026-03-27)

perf-audit save [name] / perf-audit compare <baseline> — save and compare audits over time
Regression thresholds aligned with Web Vitals boundaries

v1.4.0 — Performance Audit System (2026-03-26)

perf-audit [url] — full performance audit: Core Web Vitals, LCP critical path, layout shift attribution, long task analysis, resource breakdown, image/font audit, DOM complexity, JS/CSS coverage. Platform-aware recommendations.
detect — 162 technology fingerprints: 108 frameworks (React, Vue, Next.js, Laravel, WordPress, Shopify...), 55 SaaS platforms, CDN/protocol/compression analysis, third-party inventory
coverage start/stop — JS/CSS code coverage via Playwright Coverage API
initscript set/clear/show — inject JS before every page load

v1.3.1 — Chrome Runtime & Replay Export (2026-03-23)

--chrome — launch system Chrome with real profile (cookies, extensions, sessions)
handoff defaults to Chrome for bot detection bypass
Replay export resolves @ref to real selectors (ARIA, CSS, XPath, text)

v1.2.0 — Cloud Providers (2026-03-22)

provider save/list/delete — encrypted API key vault (AES-256-GCM)
--provider browserless / --provider browserbase — cloud browser connections
API keys encrypted at rest — never visible to agents

v1.1.2 — MCP Server Mode (2026-03-22)

--mcp — run browse as a Model Context Protocol server over stdio
Works with Cursor, Windsurf, Cline, Claude Desktop
All browse commands exposed as MCP tools

v1.1.0 — React DevTools (2026-03-22)

11 subcommands for React app inspection:

tree — component hierarchy with Suspense status
props <sel> — inspect props, state, and hooks
suspense / errors — find pending boundaries and caught errors
profiler / hydration — render timing, Next.js hydration timing
renders / owners / context — re-renders, parent chain, context values

v1.0.5 — Handoff (Human Takeover) (2026-03-22)

handoff [reason] — swap to visible browser for user to solve CAPTCHA/MFA/OAuth
resume — swap back to headless, returns fresh snapshot
Auto-suggested after 3 consecutive failures

v1.0.0 — Node.js Port (2026-03-21)

Ported from Bun to Node.js — zero Bun dependency, runs on Node 18+. Fixed WebSocket upgrade bug that blocked all CDP features. Unblocked --connect, --cdp, --runtime lightpanda.

v0.10.0 — Feature Parity (2026-03-21)

12 new commands: rightclick, tap, swipe, mouse move/down/up/wheel, keyboard inserttext, scrollinto, set geo, set media, box, errors, doctor, upgrade. Extended wait with --text, --fn, --load, --state hidden. Cookie management: clear, set with options, export, import.

v0.9.0 — Auth Persistence (2026-03-20)

Named sessions auto-save/restore cookies + localStorage
cookie-import chrome — import cookies from Chrome, Arc, Brave, Edge on macOS
Encrypted state at rest (AES-256-GCM)
--state <path> flag for loading saved state

v0.8.0 — Command Recording (2026-03-19)

record start/stop/status — record browse commands as you go
Export as chain JSON (replay with browse chain) or Chrome DevTools Recorder format

v0.7.5 — Token Optimization (2026-03-18)

snapshot -i outputs terse flat list (2.4-2.8x fewer tokens than competitors)
-V viewport-only filter (~85% element reduction)
-f flag for full indented tree when needed

v0.3.0–v0.5.0 — Headed Mode, Video, Runtime Abstraction (2026-03-17)

--headed — visible browser for debugging
video start/stop — WebM video recording
clipboard read/write, inspect DevTools, screenshot --annotate
Browser runtime registry: --runtime rebrowser (stealth), --runtime lightpanda

v0.2.0 — Security & Interactions (2026-03-16)

Security: --allowed-domains, browse-policy.json, encrypted credential vault, --content-boundaries
Commands: dblclick, focus, check/uncheck, drag, frame, route block/fulfill, offline, har, state save/load, screenshot-diff, find locators
DX: --json output, browse.json config, AI-friendly error messages, per-session output folders

v0.1.0 — Foundation (2026-03-15)

Persistent headless Chromium daemon. snapshot with @ref system. Session multiplexing. Device emulation (100+ devices). ~100ms per command after first call.

On this page