🎯 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 browser-debugger-cli@0.7.0

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

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.

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 browser-debugger-cli@0.6.11

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

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

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

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 browser-debugger-cli@0.6.8

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

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 browser-debugger-cli@0.6.7

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

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

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

Overview

This release brings three major network analysis enhancements: HAR 1.2 export for external tools, HTTP header inspection for debugging, and resource type filtering for traffic analysis.

🎯 Highlights

• HAR Export - Export network data to industry-standard HAR 1.2 format
• Network Headers Command - Inspect HTTP request/response headers with rich formatting
• Resource Type Filtering - Filter network requests by type (Document, XHR, Script, etc.)

🔧 Changes

Added

• HAR Export (bdg network har) - Export network data as HAR 1.2 format (#65)

  • bdg network har [output-file] - Export to HAR format compatible with Chrome DevTools
  • Works with live sessions (queries daemon via IPC) or post-session (reads session.json)
  • Optional output filename defaults to timestamped file in ~/.bdg/
  • Automatic binary content detection and base64 encoding
  • Includes creator/browser metadata and Chrome version
  • Valid HAR 1.2 format that opens in Chrome DevTools and HAR Viewer
  • Real timing data: DNS resolution, TCP/SSL connection, send, wait (TTFB), and receive times
  • Accurate sizes: Wire-level body sizes (encodedDataLength), HTTP headers including request/status lines
  • Server metadata: IP address and connection ID for each request
  • Proper handling of missing timing fields (-1 for unknown per HAR spec)

• Network headers command (bdg network headers) - HTTP header inspection for debugging and analysis (#67)

  • bdg network headers - Display all request and response headers for all network requests
  • bdg network headers <id> - Show headers for a specific request by ID
  • bdg network headers --request - Show only request headers
  • bdg network headers --response - Show only response headers
  • Human-readable tabular format with proper key-value alignment
  • JSON output mode for programmatic processing
  • Works with both live sessions and post-session analysis

• Resource type filtering - Enhanced network telemetry with resource type metadata (#66)

  • All network requests now include resourceType field (Document, Stylesheet, Script, XHR, Fetch, Image, Font, etc.)
  • bdg peek --type <types> - Filter by resource type (e.g., --type Document,XHR)
  • Resource types displayed in peek command output alongside URLs
  • Better understanding of network traffic composition for debugging and optimization

Changed

• Documentation updates - Updated CLI reference and roadmap for HAR export feature
  • Removed completed Issue #62 from roadmap
  • Prioritized Issue #48 (form interaction enhancements)

Installation

npm install -g browser-debugger-cli@alpha

Full Changelog: v0.6.2...v0.6.4

Note: v0.6.3 was never released; all features consolidated into v0.6.4.

Overview

Patch release adding accessibility testing capabilities, enhanced daemon cleanup, and test infrastructure improvements.

🎯 Highlights

• Accessibility tree inspection - New bdg dom a11y commands for screen reader compatibility testing
• Aggressive daemon cleanup - Automatic cleanup of orphaned daemon processes
• Test infrastructure - Added c8 coverage tooling and comprehensive unit tests
• Documentation - Reorganized docs into roadmap, principles, and quality sections

🔧 Changes

Added

• Accessibility tree inspection (bdg dom a11y) - Comprehensive accessibility testing capabilities (#64)
  • bdg dom a11y tree - View full accessibility tree with role/name/description hierarchy
  • bdg dom a11y query <pattern> - Query nodes by role, name, or description (AND logic)
  • bdg dom a11y describe <selector> - Get accessibility info for specific element
  • Exposes Chrome's accessibility tree (what screen readers see)
  • Human-readable tree view with automatic ignored node filtering
  • JSON output for programmatic processing
  • Use cases: verify accessible names, validate ARIA landmarks, audit form labels, CI/CD accessibility testing
• Aggressive daemon cleanup - Enhanced cleanup of orphaned daemon processes (#46)
  • bdg cleanup --aggressive now finds and kills orphaned daemon processes
  • Cross-platform support (macOS, Linux, Windows)
  • Prevents resource leaks from test failures, timeouts, and crashes
  • Safe cleanup that preserves currently tracked daemon

Changed

• Test infrastructure consolidation (#63)
  • Added c8 coverage tooling with proper exclusions for test files
  • Added comprehensive unit tests for core utilities (errors, http, process)
  • Created reusable shell test helpers in tests/lib/
  • Hardened shell tests against timing issues with better retry logic
  • Improved smoke test reliability with better timeouts and daemon helpers
• Documentation reorganization (#63)
  • Consolidated scattered planning docs into docs/roadmap/
  • Moved agent principles to dedicated docs/principles/ directory
  • Created docs/quality/ section with test guides and shell test hardening docs
  • Added implementation status tracking in roadmap
  • Updated README with clear documentation navigation section
• Code quality improvements (#59)
  • Enhanced error handling and logging consistency
  • Improved module boundaries and separation of concerns
  • All 19 integration tests now pass (100% pass rate)

Fixed

• Test reliability (#59)
  • Fixed tail.test to match current JSON output format
  • Fixed url-handling.test to use --headless flag for IP address test

Dependencies

• Bump js-yaml from 4.1.0 to 4.1.1 (#45) - dev dependency security update

Installation

npm install -g browser-debugger-cli@alpha

Full Changelog: v0.6.1...v0.6.2