v0.7.2

Overview

Patch release fixing a critical bug in the wrapper script and updating dependencies.

🎯 Highlights

• Fixed symlink installation: The documented installation method via symlink now works correctly
• Updated development dependencies and Chrome DevTools Protocol definitions

🔧 Changes

Fixed

• Wrapper symlink resolution - Fix infinite recursion when bdg-wrapper invoked via symlink (#152)
  • Resolves symlinks before determining script directory
  • Enables documented installation method: ln -s /path/to/bdg-wrapper ~/.local/bin/bdg
  • Handles relative and absolute symlink targets
  • Supports symlink chains across directories
  • Thank you @sfc-gh-mochen for this contribution!

Changed

• Updated development dependencies to latest versions
  • @typescript-eslint/eslint-plugin: 8.48.1 → 8.49.0
  • @typescript-eslint/parser: 8.48.1 → 8.49.0
  • @eslint/js: 9.39.1 → 9.39.2
  • eslint: 9.39.1 → 9.39.2
  • knip: 5.72.0 → 5.73.4
  • @types/node: 24.10.1 → 25.0.2
  • devtools-protocol: 0.0.1551306 → 0.0.1558402

Installation

npm install -g browser-debugger-cli@alpha

Full Changelog: v0.7.1...v0.7.2

v0.7.1

🎉 Community Release

This release is entirely powered by community contributions! A huge thank you to our amazing contributors who made this possible.

🙏 Contributors

• @felores - DOM scroll command for agent-friendly navigation (#135)
• @3dyuval - Custom Chrome flags support (#143)
• @sfc-gh-mochen - Agent experience improvements and Claude Code integration (#144)

Your contributions make bdg better for everyone. Thank you!

✨ Highlights

DOM Scroll Command

Navigate pages like a pro with the new scroll command:

bdg dom scroll "footer"        # Scroll to element
bdg dom scroll --down 500      # Scroll by pixels
bdg dom scroll --bottom        # Jump to bottom

Custom Chrome Flags

Fine-tune Chrome behavior for your use case:

bdg <url> --chrome-flags="--proxy-server=localhost:8080"
export BDG_CHROME_FLAGS="--user-agent=CustomBot/1.0"

Better Agent Experience

• Auto-detect headless mode based on display availability
• Helpful suggestions when using raw CDP commands
• Session isolation for multi-repo workflows
• Persistent sessions that survive HMR

📦 Installation

npm install -g browser-debugger-cli@alpha

🔗 Links

Full Changelog: v0.7.0...v0.7.1

v0.7.0

🎯 Form Discovery - Let AI Agents Fill Forms Effortlessly

This release introduces bdg dom form - a game-changer for AI agents interacting with web forms.

The Problem

AI agents struggle with forms: finding fields, understanding labels, knowing what's required, detecting validation errors. This leads to trial-and-error interactions and wasted tokens.

The Solution

One command gives agents everything they need:

bdg dom form

Form: "Login"
──────────────────────────────────────────────────────────────────────
   #  Type         Label                    Value                Status
──────────────────────────────────────────────────────────────────────
   0  text         Username or email        empty                invalid
   1  password     Password*                empty                invalid
──────────────────────────────────────────────────────────────────────
   2  button       Sign in                  (primary)            enabled

Summary: 0/2 fields filled | 2 required remaining | NOT ready

Remaining:
  bdg dom fill 0 "<value>"            # Username or email
  bdg dom fill 1 "<value>"            # Password

Agents get:

• Semantic labels (not cryptic id="field_3c3c")
• Current values and validation state
• Ready-to-use commands for each field
• Form type detection (Login, Registration, Search, Address, Contact, Payment)
• Multi-form page handling with relevance scoring

What's New

Added

• Form discovery command (bdg dom form) - Agent-friendly form inspection (#130)
• Shell quote damage detection (#127) - Better error recovery when shell mangles quotes

Installation

npm install -g [email protected]

Full Changelog: v0.6.11...v0.7.0

v0.6.11

Overview

Smart screenshot optimization for AI agents + agent-friendly API consistency improvements.

🎯 Highlights

• Screenshot auto-resize for Claude Vision - Inspired by community feedback that avoiding screenshots lets agents run 100+ tool calls without context exhaustion
• Agent-friendly consistency refactor - Stable JSON API contract with BdgResponse<T> type, typo detection, and cleaner error handling

📸 Screenshot Optimization

Screenshots now auto-resize to Claude Vision's optimal 1568px max edge (~1,600 tokens). Tall pages (>3:1 aspect ratio) fall back to viewport capture instead of producing unusable images.

Mode	Result
Default (auto)	Viewport at optimal size (~3k tokens)
--no-resize	Full resolution (for archiving)
--scroll <selector>	Scroll to element, capture viewport

Bug fixes: DPR race condition, clip coordinates, scroll restoration

🔧 Agent-Friendly Improvements

• BdgResponse<T> type with type guards for stable JSON API
• --help --json now includes all 17 exit codes
• Typo detection with Levenshtein distance for --preset/--type
• Validation errors return exit 81 (was showing stack traces)
• Suppressed log pollution in JSON output mode

Installation

npm install -g [email protected]

Full Changelog: v0.6.10...v0.6.11

v0.6.10

Overview

This release adds element-level screenshots, screenshot sequences, and automatic cache refresh for DOM commands. DOM commands now "just work" after page navigation.

🎯 Highlights

• Element screenshots - Capture specific elements with --selector or --index
• Screenshot sequences - Continuous capture with --follow mode
• Auto-refresh stale cache - DOM commands recover transparently after navigation
• WebSocket capture - Full WebSocket frames in HAR export

🔧 Changes

Added

• Element-level screenshots (bdg dom screenshot --selector)

  • --selector <css> for CSS selector-based element capture
  • --index <n> for cached element index from previous query
  • JSON output includes element bounds metadata

• Screenshot sequences (bdg dom screenshot --follow)

  • --follow enables capture to directory at intervals
  • --interval <ms> controls capture frequency (default: 1000ms)
  • --limit <n> stops after N frames

• Auto-refresh stale cache - DOM commands "just work" after navigation

  • Automatically re-runs original query when cache is stale
  • New exit code 87 (STALE_CACHE) for unrecoverable staleness

• DOM.documentUpdated tracking - Detect SPA re-renders

• WebSocket message capture in HAR export

Changed

• Enhanced screenshot output format with element metadata
• Centralized auto-refresh logic in DomElementResolver

Fixed

• Package-lock.json sync issue causing CI failures

Installation

npm install -g browser-debugger-cli@alpha

Examples

# Element screenshot
bdg dom screenshot hero.png --selector ".hero-banner"

# Screenshot sequence
bdg dom screenshot ./frames/ --follow --interval 500 --limit 10

# Auto-refresh in action
bdg dom query "button"
# Navigate to different page...
bdg dom click --index 0  # Works! Auto-refreshes cache

Full Changelog: v0.6.9...v0.6.10

v0.6.9

Overview

This release adds powerful DevTools-compatible network filtering, rich console object expansion, and multiple critical bug fixes discovered through comprehensive benchmark testing.

🎯 Highlights

• Network filter DSL - Chrome DevTools filter syntax with 10 filter types and 8 presets
• Console object expansion - Nested objects displayed like DevTools instead of [Object]
• Critical bug fixes - Console buffer size, memory profiling timeouts, network error details
• Form compatibility - React/Vue synthetic keyboard events for proper form validation

🔧 Changes

Added

• DevTools-compatible network filter DSL (bdg network list) with wildcards, negation, and presets (#91)
• Console object expansion with async CDP-based expansion for nested objects (#92)
• Console level filtering with --level option (error/warning/info/debug) (#105)
• Quiet mode (-q/--quiet) for minimal output, ideal for AI agents (#105)
• Benchmark v3.1 comparing bdg vs MCP (77/100 vs 60/100, +28% advantage)

Changed

• Refactored network commands into modular structure with centralized messages (#91)
• Enhanced console timestamps with millisecond precision (HH:MM:SS.mmm) (#105)
• Improved source location formatting for inline/eval code (#105)

Fixed

• Console buffer size: IPC layer now passes client's lastN parameter (#105)
• Memory profiling: IPC timeout increased from 10s to 30s to match CDP timeout (#105)
• Network error details: Capture errorText, canceled, blocked, blockedReason (#105)
• Commander.js: --json flag now properly propagates to subcommands (#88)
• React/Vue forms: Synthetic keyboard events for framework compatibility (#88)
• A11y routing: CSS selector detection for smart routing (#88)

Installation

npm install -g browser-debugger-cli@alpha

Full Changelog: v0.6.8...v0.6.9

v0.6.8

Smart Console Inspection

This release adds intelligent console message inspection with navigation awareness.

Highlights

• Default shows current page only - No more noise from previous navigations
• Error/warning prioritization - Problems shown first with deduplication
• Stack traces - Source locations for debugging (file:line:column)
• --history flag - See all messages across page loads when needed

Usage

# Smart summary (current page, deduplicated)
bdg console

# All messages from all page loads
bdg console --history

# Chronological list with navigation markers
bdg console --history --list

# Real-time streaming
bdg console --follow

# JSON output with summary stats
bdg console --json

Installation

npm install -g [email protected]

Full Changelog: v0.6.7...v0.6.8

v0.6.7

Overview

Bug fixes and code quality improvements focusing on help output, accessibility graceful degradation, and cache management.

🔧 Changes

Fixed

• Subcommand help output - --help --json now returns focused command info instead of full tool structure (#84)
• Graceful degradation for dom get - Handle accessibility API unavailability gracefully (#82)
• Stale query cache detection - Detect and clear stale query cache after page navigation (#74)

Changed

• Improved cache management - Better DOM element resolution and cache management architecture (#79)
• Consolidated cleanup logic - Improved type safety in cleanup state and type guards (#77)
• Removed unused exports - Clean up unused exports identified by knip (#80)
• Documentation updates - Slimmer README with Wiki links, updated CDP method count to 644

Installation

npm install -g [email protected]

Full Changelog: v0.6.6...v0.6.7

v0.6.6

Overview

Agent UX improvements with keyboard interactions, network stability waiting, and enhanced DOM command output.

Highlights

• New bdg dom pressKey command - Send keyboard events (Enter, Tab, Escape, arrows, modifiers)
• Network stability waiting - Click and fill now wait for AJAX to settle
• Improved element output - Better context in dom get and a11y describe

Changes

Added

• Keyboard interaction command (bdg dom pressKey) with modifier support
• Network stability waiting for click/fill commands (with --no-wait opt-out)
• Direct index support for dom click

Changed

• Improved dom get output with DOM context when a11y name missing
• Improved a11y describe output with tag, classes, text preview
• Smart routing for bdg dom a11y based on input type
• Better filter feedback when --type matches nothing

Fixed

• Reject invalid --last 0 value in peek command
• Extracted shared element resolution logic (~70 lines removed)

Installation

```bash
npm install -g browser-debugger-cli@alpha
```

Full Changelog: v0.6.5...v0.6.6

v0.6.5

Overview

This release dramatically improves agent discoverability with machine-readable help, intelligent pattern detection, and query caching for streamlined DOM workflows. Agents can now discover high-level commands efficiently and receive context-aware hints when using verbose CDP patterns.

🎯 Highlights

• Machine-readable help with task mappings and decision trees
• Pattern detection suggests high-level alternatives to verbose CDP
• Query cache enables fast index-based DOM element access
• Enhanced hints guide users toward efficient command patterns
• Resource type indicators in peek output for quick identification
• Security fix for string escaping vulnerability

🔧 Changes

Added

• Agent-friendly discovery system - Machine-readable help and intelligent pattern detection (#68, #69)
  • bdg --help --json - Machine-readable schema with task mappings, decision trees, and runtime state
  • Pattern detection for common CDP usage that suggests high-level alternatives
  • 15 task-to-command mappings with CDP fallback options
  • 5 intent-based decision trees (DOM, Network, Console, Monitoring, Session)
  • Dynamic runtime state showing command availability
  • Capabilities summary (53 CDP domains, 300+ methods)
• Query cache for index-based DOM access - Persistent cache enables fast element references (#68)
  • After bdg dom query <selector>, reference elements by index in subsequent commands
  • Direct index access for inspection: bdg dom get 0, bdg dom a11y describe 0
  • File-based cache in ~/.bdg/query-cache.json persists across CLI invocations
  • Automatically cleared when starting new queries or ending sessions
  • Two access patterns documented: direct index (inspection) vs --index flag (interaction)
• Enhanced command hints - Context-aware guidance for better command usage (#68)
  • Pattern-based hints suggest high-level commands when using verbose CDP
  • Runtime.evaluate triggers suggest bdg dom query for element inspection
  • Page.captureScreenshot triggers suggest bdg dom screenshot
  • Network.getCookies triggers suggest bdg network getCookies
  • CommandRunner integration for consistent hint display
• Resource type indicators in peek - Visual indicators for network resource types (#68)
  • Short codes in peek output: IMG (images), DOC (documents), XHR (AJAX), SCR (scripts)
  • Helps quickly identify resource types during live monitoring
  • Complements existing --type filtering for resource-based queries

Changed

• Improved error messages - Better guidance and actionable suggestions (#68)
  • Enhanced daemon-not-running errors with clear next steps
  • Session-not-found errors include start command examples
  • Invalid argument errors show expected formats
• Documentation updates - Comprehensive agent discoverability documentation (#68)
  • Added CLAUDE.md section on DOM interaction patterns
  • Created manual testing guide for agent discovery features
  • Reorganized agent discoverability docs to focus on unresolved items
  • Added PAIN_POINTS_RESOLVED.md tracking completed improvements

Fixed

• String escaping security issue - Properly escape backslashes in selector strings (#68)
  • Fixes CodeQL high-severity warning about incomplete string escaping
  • Backslashes now escaped before single quotes to prevent bypass
  • Resolves potential injection in DOM formatter hints

Performance

• Optimized HAR endpoint selection - Prefer current navigation's Document resource (#68)
  • Smarter default endpoint inference from network data
  • Improves accuracy of HAR export for SPAs

Installation

npm install -g browser-debugger-cli@alpha

Full Changelog: v0.6.4...v0.6.5