puppeteer-bidi 0.0.1.beta1

data/CLAUDE/core_layer_gotchas.md

@@ -0,0 +1,136 @@
+# Core Layer Gotchas
+
+## Overview
+
+This document covers non-obvious issues and pitfalls in the Core layer implementation.
+
+## BrowsingContext: disposed? vs closed? Conflict
+
+### The Problem
+
+`BrowsingContext` uses both `Disposable::DisposableMixin` and defines `alias disposed? closed?`:
+
+```ruby
+class BrowsingContext < EventEmitter
+  include Disposable::DisposableMixin
+
+  def closed?
+    !@reason.nil?
+  end
+
+  alias disposed? closed?
+end
+```
+
+This creates a conflict:
+- `DisposableMixin#dispose` checks `disposed?` before proceeding
+- `disposed?` is aliased to `closed?`
+- `closed?` returns `true` when `@reason` is set
+
+### The Bug
+
+Original `dispose_context` implementation:
+
+```ruby
+def dispose_context(reason)
+  @reason = reason  # Sets @reason, making closed? return true
+  dispose           # dispose checks disposed?/closed?, sees true, returns early!
+end
+```
+
+**Result**: `:closed` event was never emitted because `dispose` returned early.
+
+### The Fix
+
+Set `@reason` AFTER calling `dispose`:
+
+```ruby
+def dispose_context(reason)
+  # IMPORTANT: Call dispose BEFORE setting @reason
+  # Otherwise disposed?/closed? returns true and dispose returns early
+  dispose
+  @reason = reason
+end
+```
+
+### Additional Fix: Emit :closed Before @disposed = true
+
+`EventEmitter#emit` returns early if `@disposed` is true. But `DisposableMixin#dispose` sets `@disposed = true` before calling `perform_dispose`. This means any events emitted in `perform_dispose` would be ignored.
+
+Solution: Override `dispose` to emit `:closed` before calling `super`:
+
+```ruby
+def dispose
+  return if disposed?
+
+  @reason ||= 'Browsing context closed'
+  emit(:closed, { reason: @reason })  # Emit BEFORE @disposed = true
+
+  super  # This sets @disposed = true and calls perform_dispose
+end
+```
+
+## EventEmitter and DisposableMixin @disposed Interaction
+
+Both `EventEmitter` and `DisposableMixin` use `@disposed` instance variable:
+
+```ruby
+# EventEmitter
+def emit(event, data = nil)
+  return if @disposed  # Early return if disposed
+  # ...
+end
+
+def dispose
+  @disposed = true
+  @listeners.clear
+end
+
+# DisposableMixin
+def dispose
+  return if @disposed
+  @disposed = true
+  perform_dispose
+end
+```
+
+When a class includes both (like `BrowsingContext`), they share the same `@disposed` variable. This is usually fine, but be aware:
+
+1. **Order matters**: If you need to emit events during disposal, do it BEFORE setting `@disposed = true`
+2. **Check disposal state carefully**: Use `disposed?` method, not `@disposed` directly
+3. **Override dispose if needed**: To emit events or do cleanup that requires the emitter to still be active
+
+## Debugging Tips
+
+### Enable BiDi Debug Logging
+
+```bash
+DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/frame_spec.rb
+```
+
+### Track Disposal State
+
+Add temporary debug logs:
+
+```ruby
+def dispose
+  puts "[DEBUG] dispose called for #{@id}, disposed?=#{disposed?}"
+  # ...
+end
+```
+
+### Check Event Listener Registration
+
+Verify listeners are registered on the correct instance:
+
+```ruby
+browsing_context.once(:closed) do
+  puts "[DEBUG] :closed received for #{browsing_context.id}"
+end
+```
+
+## Related Files
+
+- `lib/puppeteer/bidi/core/browsing_context.rb` - BrowsingContext implementation
+- `lib/puppeteer/bidi/core/event_emitter.rb` - EventEmitter base class
+- `lib/puppeteer/bidi/core/disposable.rb` - DisposableMixin module

data/CLAUDE/error_handling.md

@@ -0,0 +1,232 @@
+# Error Handling and Custom Exceptions
+
+This document covers the custom exception hierarchy, implementation patterns, and benefits of type-safe error handling in puppeteer-bidi.
+
+### Philosophy
+
+Use custom exception classes instead of inline string raises for:
+- **Type safety**: Enable `rescue` by specific exception type
+- **DRY principle**: Centralize error messages
+- **Debugging**: Attach contextual data to exception objects
+- **Consistency**: Uniform error handling across codebase
+
+### Custom Exception Hierarchy
+
+```ruby
+StandardError
+└── Puppeteer::Bidi::Error
+    ├── JSHandleDisposedError
+    ├── PageClosedError
+    ├── FrameDetachedError
+    └── SelectorNotFoundError
+```
+
+All custom exceptions inherit from `Puppeteer::Bidi::Error` for consistent rescue patterns.
+
+### Exception Classes
+
+#### JSHandleDisposedError
+
+**When raised**: Attempting to use a disposed JSHandle or ElementHandle
+
+**Location**: `lib/puppeteer/bidi/errors.rb`
+
+```ruby
+class JSHandleDisposedError < Error
+  def initialize
+    super('JSHandle is disposed')
+  end
+end
+```
+
+**Usage**:
+```ruby
+# JSHandle and ElementHandle
+private
+
+def assert_not_disposed
+  raise JSHandleDisposedError if @disposed
+end
+```
+
+**Affected methods**:
+- `JSHandle#evaluate`, `#evaluate_handle`, `#get_property`, `#get_properties`, `#json_value`
+- `ElementHandle#query_selector`, `#query_selector_all`, `#eval_on_selector`, `#eval_on_selector_all`
+
+#### PageClosedError
+
+**When raised**: Attempting to use a closed Page
+
+**Location**: `lib/puppeteer/bidi/errors.rb`
+
+```ruby
+class PageClosedError < Error
+  def initialize
+    super('Page is closed')
+  end
+end
+```
+
+**Usage**:
+```ruby
+# Page
+private
+
+def assert_not_closed
+  raise PageClosedError if closed?
+end
+```
+
+**Affected methods**:
+- `Page#goto`, `#set_content`, `#screenshot`
+
+#### FrameDetachedError
+
+**When raised**: Attempting to use a detached Frame
+
+**Location**: `lib/puppeteer/bidi/errors.rb`
+
+```ruby
+class FrameDetachedError < Error
+  def initialize
+    super('Frame is detached')
+  end
+end
+```
+
+**Usage**:
+```ruby
+# Frame
+private
+
+def assert_not_detached
+  raise FrameDetachedError if @browsing_context.closed?
+end
+```
+
+**Affected methods**:
+- `Frame#evaluate`, `#evaluate_handle`, `#document`
+
+#### SelectorNotFoundError
+
+**When raised**: CSS selector doesn't match any elements in `eval_on_selector`
+
+**Location**: `lib/puppeteer/bidi/errors.rb`
+
+```ruby
+class SelectorNotFoundError < Error
+  attr_reader :selector
+
+  def initialize(selector)
+    @selector = selector
+    super("Error: failed to find element matching selector \"#{selector}\"")
+  end
+end
+```
+
+**Usage**:
+```ruby
+# ElementHandle#eval_on_selector
+element_handle = query_selector(selector)
+raise SelectorNotFoundError, selector unless element_handle
+```
+
+**Contextual data**: The `selector` value is accessible via the exception object for debugging.
+
+### Implementation Pattern
+
+#### 1. Define Custom Exception
+
+```ruby
+# lib/puppeteer/bidi/errors.rb
+class MyCustomError < Error
+  def initialize(context = nil)
+    @context = context
+    super("Error message with #{context}")
+  end
+end
+```
+
+#### 2. Add Private Assertion Method
+
+```ruby
+class MyClass
+  private
+
+  def assert_valid_state
+    raise MyCustomError, @context if invalid?
+  end
+end
+```
+
+#### 3. Replace Inline Raises
+
+```ruby
+# Before
+def my_method
+  raise 'Invalid state' if invalid?
+  # ...
+end
+
+# After
+def my_method
+  assert_valid_state
+  # ...
+end
+```
+
+### Benefits
+
+**Type-safe error handling**:
+```ruby
+begin
+  page.eval_on_selector('.missing', 'e => e.id')
+rescue SelectorNotFoundError => e
+  puts "Selector '#{e.selector}' not found"
+rescue JSHandleDisposedError
+  puts "Handle was disposed"
+end
+```
+
+**Consistent error messages**: Single source of truth for error text
+
+**Reduced duplication**: 16 inline raises eliminated across codebase
+
+**Better debugging**: Exception objects carry contextual information
+
+### Testing Custom Exceptions
+
+Tests use regex matching for backward compatibility:
+
+```ruby
+# Test remains compatible with custom exception
+expect {
+  page.eval_on_selector('non-existing', 'e => e.id')
+}.to raise_error(/failed to find element matching selector/)
+```
+
+This allows tests to pass with both string raises and custom exceptions.
+
+### Refactoring Statistics
+
+| Class | Inline Raises Replaced | Private Assert Method |
+|-------|------------------------|----------------------|
+| JSHandle | 5 | `assert_not_disposed` |
+| ElementHandle | 4 + 1 (selector) | (inherited) |
+| Page | 3 | `assert_not_closed` |
+| Frame | 3 | `assert_not_detached` |
+| **Total** | **16** | **3 methods** |
+
+### Future Considerations
+
+When adding new error conditions:
+
+1. **Create custom exception** in `lib/puppeteer/bidi/errors.rb`
+2. **Add to exception hierarchy** by inheriting from `Error`
+3. **Include contextual data** as `attr_reader` if needed
+4. **Create private assert method** in the relevant class
+5. **Replace inline raises** with assert method calls
+6. **Update tests** to use regex matching for flexibility
+
+This pattern ensures consistency and maintainability across the entire codebase.
+

data/CLAUDE/file_chooser.md

@@ -0,0 +1,95 @@
+# FileChooser Implementation
+
+## Overview
+
+FileChooser provides file upload functionality through the WebDriver BiDi `input.setFiles` command and `input.fileDialogOpened` event.
+
+## Firefox Nightly Requirement
+
+**Important**: The `input.fileDialogOpened` event is only supported in Firefox Nightly. Stable Firefox does not fire this event.
+
+```bash
+# Run tests with Firefox Nightly
+FIREFOX_PATH="/Applications/Firefox Nightly.app/Contents/MacOS/firefox" bundle exec rspec spec/integration/input_spec.rb
+```
+
+The browser launcher prioritizes Firefox Nightly in its search order.
+
+## API Design
+
+### Block-based Interface
+
+Ruby uses a block-based interface instead of JavaScript's Promise.all pattern:
+
+```ruby
+# Ruby (block-based)
+chooser = page.wait_for_file_chooser do
+  page.click('input[type=file]')
+end
+chooser.accept(['/path/to/file.txt'])
+
+# JavaScript equivalent
+const [chooser] = await Promise.all([
+  page.waitForFileChooser(),
+  page.click('input[type=file]'),
+]);
+await chooser.accept(['/path/to/file.txt']);
+```
+
+### Direct Upload
+
+```ruby
+input = page.query_selector('input[type=file]')
+input.upload_file('/path/to/file.txt')
+```
+
+## Implementation Flow
+
+```
+ElementHandle#upload_file(files)
+  └── Frame#set_files(element, files)
+        └── BrowsingContext#set_files(shared_reference, files)
+              └── BiDi command: input.setFiles
+```
+
+This follows Puppeteer's pattern where ElementHandle delegates to Frame, which then calls the BrowsingContext.
+
+## Firefox BiDi Limitations
+
+### 1. Detached Elements Not Supported
+
+Firefox does not fire `input.fileDialogOpened` for file inputs that are not attached to the DOM:
+
+```ruby
+# This will timeout - detached element
+page.wait_for_file_chooser do
+  page.evaluate(<<~JS)
+    () => {
+      const el = document.createElement('input');
+      el.type = 'file';
+      el.click();  // No event fired
+    }
+  JS
+end
+```
+
+### 2. Non-existent Files Rejected
+
+Firefox BiDi rejects files that don't exist with `NS_ERROR_FILE_NOT_FOUND`. Chrome allows setting non-existent files.
+
+### 3. Event Subscription
+
+The `input` module must be subscribed at session level. This is handled automatically in `Session#initialize_session`:
+
+```ruby
+subscribe_modules = %w[browsingContext network log script input]
+subscribe(subscribe_modules)
+```
+
+## Key Classes
+
+- `FileChooser` - Wraps the element with `accept()`, `cancel()`, `multiple?()` methods
+- `Page#wait_for_file_chooser` - Listens for `filedialogopened` event with timeout
+- `ElementHandle#upload_file` - Resolves paths and delegates to frame
+- `Frame#set_files` - Calls BrowsingContext with shared reference
+- `BrowsingContext#set_files` - Sends BiDi `input.setFiles` command