New commands:
- goto <url> --tab: navigate existing tab via Page.navigate (keeps SPA context)
- cookies --tab [--filter]: view page cookies via Network.getCookies
- source grep <pattern> --tab: search loaded JS sources for API endpoints
Improvements:
- trace events --exclude-static: filter out .js/.css/.png/.woff and _next/static
- network requests --exclude-static: same filtering for network command
- trace --exclude-static filters both requests AND their matching responses
- trace body returns requestBody alongside responseBody for POST requests
- open command output shows short tab ID prominently
* feat(trace): unified timeline of actions + network for site adapter creation
Replaces the empty trace skeleton with a working recording system that
captures command actions, human browser interactions, network requests,
and responses in a single timeline with causal inference (triggerSeq).
Key changes:
- protocol.ts: TraceEntry union type (TraceAction/Request/Response/Navigation)
- tab-state.ts: TraceSession on TabStateManager, recordAction() with detail
- command-dispatch.ts: trace start/stop/status/events/body handlers
- cdp-connection.ts: network/navigation events pushed to trace timeline,
human action capture via Runtime.addBinding + injected JS listeners,
new tabs auto-join trace session via Target.targetCreated openerId
- commands.ts: trace accepts 5 subcommands with filtering params
- cli trace.ts: formatted timeline output, --type/--filter/--since/--limit
Verified: actions (command + human), network requests with triggerSeq,
trace events query with filters, trace body fetch, backward compat with
existing network/console/errors commands.
* fix(cdp): preserve tab state across same-tab navigation
During cross-origin navigation, Chrome detaches the old CDP session and
attaches a new one for the same target. The old code called
tabManager.removeTab() in Target.detachedFromTarget, destroying the tab's
event buffers (network requests, console, errors, trace data).
Fix:
- Target.detachedFromTarget: only clean session maps, do NOT remove tab
state. Tab removal is now exclusively handled by Target.targetDestroyed.
- Target.attachedToTarget: re-enable CDP domains (Network, Page, Runtime,
DOM, Accessibility) on the new session when the tab already exists.
Also re-inject human capture script for traced tabs.
This fixes a long-standing bug where network requests after page navigation
were silently dropped from both the network buffer and the trace timeline.
* docs(cli): update help text and hints for trace commands
- Help text: list all 5 trace subcommands with descriptions
- Options section: add --since/--type/--filter/--limit/--request-id
- Error message already updated in previous commit
Enhance the eval command to support:
- --domain: auto-route to a tab matching the domain (find existing or create new)
- --args: pass a JSON object to the script as function arguments
When domain is set and no --tab is provided, eval will:
1. Search existing tabs for a hostname match (exact or subdomain)
2. If no match, create a new tab at https://<domain> and wait for load
3. Execute the script in that tab's context
When args is set, the script is wrapped in an IIFE:
(async function(){return (<script>)(<argsJSON>);})()
This enables Bun Clips to use browser.eval for site-specific data
extraction — replacing site adapters with standard Clips that invoke
browser capabilities via the Hub.
Example:
bb-browser eval 'async function(args) { ... }' --domain x.com --args '{"query":"AI"}'
TURN secret no longer shipped in npm package. Daemon fetches
temporary credentials from Hub /turn/credentials endpoint.
Falls back to TURN_URL/TURN_SECRET env vars for standalone mode.
Default to Pinix public coturn on pinix-cn (81.70.98.26:3478).
Users no longer need to set TURN_URL/TURN_SECRET — WebRTC stream
works out of the box even behind NAT. Env vars still override.
- hub-bridge.ts: ensureStreamerBinary() checks local install, PATH,
then auto-downloads platform-specific binary from COS
- Dockerfile: single-stage build, downloads pre-built bb-viewer and
Chrome from COS instead of compiling Go in multi-stage
Pre-built binaries uploaded to COS:
releases/bb-viewer/latest/bb-viewer-darwin-arm64
releases/bb-viewer/latest/bb-viewer-linux-amd64
releases/chrome/chrome-linux64.zip
Headless mode lacks full GUI APIs on Linux and gets flagged by anti-bot
systems. On macOS, Chrome renders off-screen without a visible window
when there is no focused user session, so headed mode works everywhere.
Remove CHROME_HEADED env toggle — headed is now the only mode.
Linux --headless=new lacks full GUI APIs (WebGL, plugins, screen info)
that anti-bot systems like Google's use to detect automation. macOS
headless works because Chrome still links the full Cocoa/CoreGraphics
stack even in headless mode.
Changes:
- Dockerfile: add Xvfb, entrypoint starts virtual framebuffer before
daemon; pre-install Chrome for Testing in image; use China mirrors
for apt/Go/npm to speed up builds
- chrome.ts: CHROME_HEADED=1 env skips --headless=new and --disable-gpu
flags, letting Chrome render on the Xvfb display
Video stream still uses CDP screencast → bb-viewer → WebRTC.
Stealth injection (Emulation overrides, addScriptToEvaluateOnNewDocument)
is itself detectable by Google and other anti-bot systems. CDP alone
without stealth works fine for Google login.
- Disable stealth for all Chrome types (full Chrome doesn't need it,
headless-shell is inherently detectable regardless)
- Update Dockerfile: static-linked bb-viewer, no .so dependencies
- Clean up Dockerfile for full Chrome for Testing
Stealth injections (Emulation.setUserAgentOverride, setDeviceMetricsOverride,
Page.addScriptToEvaluateOnNewDocument) are themselves detectable by Google's
anti-bot systems. CDP alone is NOT detected — the stealth overrides were
causing the detection.
Now only inject stealth when running headless-shell (product starts with
'HeadlessChrome'). Full Chrome (headed or --headless=new) works fine
with just CDP, no stealth needed.
Three headless fingerprints that Google detects:
1. screen.width/height was 800x600 (headless default) — now overridden
to 1920x1080 via Emulation.setDeviceMetricsOverride
2. navigator.webdriver was undefined (stealth bug) — normal Chrome
returns false, not undefined
3. navigator.plugins.length was 3 — normal Chrome has 5 PDF-related
plugins
Browser.getVersion is a browser-level CDP command, not a session-level
one. Using sessionCommand returned null/error, causing fallback to
hardcoded 149.0.7827.22 — creating a version mismatch with the real
Chrome (148.0.7778.179) that Google detects as bot fingerprint.
Switch to browserCommand which correctly returns the real product
version string.
- Add Dockerfile for containerized deployment
- chrome.ts: prefer system Chrome, auto-download Chrome for Testing
(full browser, not headless-shell) when no system Chrome found
- hub-bridge: handle bb-viewer spawn ENOENT gracefully instead of
crashing the entire daemon process
headless-shell is an stripped-down Chrome that lacks many browser APIs
(Bluetooth, USB, SharedWorker, etc.), making it easily detectable by
anti-bot systems. Switch to using full Chrome:
1. System Chrome: prefer already-installed Google Chrome/Chromium/Edge
2. Chrome for Testing: auto-download full browser if no system Chrome
3. headless-shell: removed as a fallback (no longer needed)
Also fix UA override to dynamically detect the real Chrome version from
Browser.getVersion, so User-Agent, Sec-Ch-Ua, and Sec-Ch-Ua-Full-Version
are always consistent — no more version mismatch fingerprint.
Sec-Ch-Ua-Full-Version was leaking the real Chrome version (149) while
User-Agent and Sec-Ch-Ua claimed 148 — this version mismatch is a
strong anti-bot signal. Align all version strings to match the actual
headless-shell binary version.
Also fix Accept-Language format.
Previously stealth (UA override, navigator.webdriver, canvas/WebGL/audio
fingerprint noise, chrome.runtime shim, etc.) was only injected by
bb-viewer's inputConn. The daemon's controlConn — used by site adapters,
CLI commands, and agent operations — had no stealth protection, exposing
HeadlessChrome UA and automation markers to anti-bot systems.
Now injects Emulation.setUserAgentOverride + Page.addScriptToEvaluateOnNewDocument
in attachAndEnable(), so every tab gets stealth from the moment it's
attached, regardless of whether a stream is active.
stream.close was timing out (15s) when no streamer process existed,
because it unconditionally sent an HTTP request to the streamer port.
Now returns {ok: true} immediately if streamer is not running.
- Remove pointer-events:none from dimmed tab/url bar so tabs remain
clickable even when not connected to a stream.
- Update activeTabId and re-render immediately on click for responsive
UI, then async invoke stream.switch only if connected.
- Skip stream.switch call when disconnected to avoid errors.
Daemon now automatically downloads and launches Chrome headless-shell
when started. No need to install Chrome separately.
- Downloads from Pinix COS (unified source for all platforms)
- Supports mac-arm64, mac-x64, linux64, linux-arm64
- Stores at ~/.bb-browser/browser/chrome-headless-shell-<platform>/
- Manages Chrome lifecycle: start on daemon start, kill on shutdown
- --no-chrome flag to skip (use external Chrome)
- Tested on macOS ARM64, Docker linux/amd64, Docker linux/arm64
Site adapters like twitter/search.js reference shared functions defined
in _helper.js (e.g. findTransactionIdGenerator). The runtime was not
loading this helper file, causing ReferenceError at runtime.
Now checks for _helper.js in the same directory as the adapter and
prepends it into the evaluation scope.
* feat(view): heartbeat ping + idle timeout + visibility-based disconnect
- Send OpPing (0x08) heartbeat every 5s (active) / 10s (idle)
- Visibility change: hidden starts 30s idle countdown, visible cancels
- cleanup(reason): distinct overlay messages for user/idle/network disconnect
- Start heartbeat on DataChannel open, stop on cleanup
* fix(view): use polling instead of setTimeout for idle timeout in hidden tabs
Browsers throttle setTimeout in hidden tabs to >=1 minute (Chrome).
The 30s idle timeout was never firing because the timer was delayed.
Fix: record hiddenSince timestamp on visibilitychange, check elapsed
time on each heartbeat interval tick instead of relying on setTimeout.
* fix(view): fire-and-forget stream.close to prevent disconnect from hanging
disconnect() was awaiting invoke('stream.close') which could hang if
the server is slow or the connection is degraded. This blocked cleanup()
from running, so the UI stayed in 'connected' state and heartbeat
continued indefinitely.
Fix: fire stream.close without awaiting, then immediately cleanup.
Streamer returns {result: {...}} but hub-bridge was passing the
entire envelope to Hub invoke. Frontend received
{result: {offer_sdp: ...}} instead of {offer_sdp: ...}, causing
offer_sdp to be undefined and video blackscreen.
Unwrap resp.result for stream.start/answer/close/switch.
Single source of truth for all command metadata:
- ParamDef with type, required, position, description
- CommandDef with method, group, description, requiresTab, params
- commandToJsonSchema() for Hub registration
- getCommand() / getCommandsByGroup() helpers
Hub registration now uses COMMANDS directly instead of
hardcoded arrays. Removed zod dependency from shared package.
CLI and daemon dispatch unchanged — they can consume COMMANDS
in a future refactor.
Daemon --hub mode replaces the standalone provider. All Hub
connection, clip registration, and invoke handling is now in
packages/daemon/src/hub-bridge.ts.
Also remove provider entry from tsup release build.
- New: packages/daemon/src/site-adapter.ts — site adapter scanning,
@meta parsing, domain-based tab matching, and JS evaluation via CDP
- Daemon: add site_run, site_list, site_info, site_search actions
- CLI: site commands now send HTTP to daemon instead of executing locally
- Provider: executeSiteCommand uses daemon site_run instead of shelling
out to CLI subprocess (removes execFile dependency)
- Protocol: add siteName, siteArgs, query fields to Request type
Site adapter execution is now a single path: CLI/Provider → daemon
→ CDP evaluate. No more three-layer process nesting.
Fix left-click being sent as middle-click: mapButton was converting
Web API button 0 (left) to 1, but bb-viewer uses 0-indexed buttons
(0=left, 1=middle, 2=right). Middle-click on links opens new tabs
in Chrome, which was the root cause of the 'links open in new tab'
bug.
Also remove unused URL bar composition tracking variables and
debug-only url_keydown logging.
Three fixes for modifier keys getting stuck:
- URL input capture-phase keyup no longer stops propagation for
modifier keys (Shift/Ctrl/Alt/Meta), allowing them to reach the
document-level onKeyUp handler
- Clicking the video overlay sends keyUp for all modifiers to clear
any stuck state from URL bar interactions
- Window focus event resets all modifiers to handle Cmd+Tab scenarios
Also add version indicator (v9) for debugging cache issues.
Route tab_list, tab_switch, tab_new, tab_close, navigate, back,
forward, reload through bb-viewer API instead of daemon. This ensures
tab operations and video stream operate on the same Chrome instance
and CDP session.
Also fix URL bar: skip polling overwrite when input is focused,
and simplify Enter key handling to avoid IME false suppression.
When CDP_PORT is set, forward it as --cdp-port to the daemon process
so both daemon (tab operations) and bb-viewer (screencast) connect
to the same Chrome instance. Without this, daemon defaults to 19825
(GUI Chrome) while bb-viewer uses the CDP_PORT value, causing tab
list and video stream to reference different Chrome instances.
yan5xu