puppeteer-bidi 0.0.1.beta1

data/CLAUDE/keyboard_implementation.md

@@ -0,0 +1,250 @@
+# Keyboard Implementation
+
+This document describes the keyboard input implementation for WebDriver BiDi.
+
+## Overview
+
+The Keyboard class implements user keyboard input using the BiDi `input.performActions` protocol. It supports typing text, pressing individual keys, and handling modifier keys (Shift, Control, Alt, Meta).
+
+## Architecture
+
+### Class Structure
+
+```
+Keyboard
+├── @page (Page) - Reference to the page for focused_frame access
+├── @browsing_context (BrowsingContext) - Target context for input actions
+└── @pressed_keys (Set) - Track currently pressed keys for modifier state
+```
+
+### Key Components
+
+1. **Keyboard class** (`lib/puppeteer/bidi/keyboard.rb`)
+   - High-level keyboard input API
+   - Manages modifier key state
+   - Converts Ruby key names to BiDi format
+
+2. **Key mappings** (`lib/puppeteer/bidi/key_definitions.rb`)
+   - Maps key names to Unicode code points
+   - Handles special keys (Enter, Tab, Arrow keys, etc.)
+   - Platform-specific keys (CtrlOrMeta)
+
+## BiDi Protocol Usage
+
+### input.performActions Format
+
+```ruby
+session.send_command('input.performActions', {
+  context: browsing_context_id,
+  actions: [
+    {
+      type: 'key',
+      id: 'keyboard',
+      actions: [
+        { type: 'keyDown', value: 'a' },
+        { type: 'keyUp', value: 'a' }
+      ]
+    }
+  ]
+})
+```
+
+### Key Value Format
+
+BiDi accepts two formats for key values:
+
+1. **Single character**: `'a'`, `'1'`, `'!'`
+2. **Unicode escape**: `"\uE007"` for Enter, `"\uE008"` for Shift, etc.
+
+## Implementation Details
+
+### Modifier Keys
+
+**Special handling for CtrlOrMeta**:
+```ruby
+KEY_DEFINITIONS = {
+  'CtrlOrMeta' => {
+    key: RUBY_PLATFORM.include?('darwin') ? 'Meta' : 'Control',
+    code: RUBY_PLATFORM.include?('darwin') ? 'MetaLeft' : 'ControlLeft',
+    location: 1
+  }
+}
+```
+
+**Modifier state tracking**:
+```ruby
+def down(key)
+  definition = get_key_definition(key)
+  @pressed_keys.add(definition[:key])
+  # ... send keyDown action
+end
+
+def up(key)
+  definition = get_key_definition(key)
+  @pressed_keys.delete(definition[:key])
+  # ... send keyUp action
+end
+```
+
+### Type Method
+
+The `type` method splits text into individual characters and presses each one:
+
+```ruby
+def type(text, delay: 0)
+  text.each_char do |char|
+    # Handle special keys (e.g., "\n" → Enter)
+    if SPECIAL_CHAR_MAP[char]
+      press(SPECIAL_CHAR_MAP[char])
+    else
+      press(char)
+    end
+    sleep(delay / 1000.0) if delay > 0
+  end
+end
+```
+
+### Send Character Method
+
+The `send_character` method inserts text without triggering keydown/keyup events:
+
+```ruby
+def send_character(char)
+  raise ArgumentError, 'Cannot send more than 1 character.' if char.length > 1
+
+  # Get the focused frame (may be an iframe)
+  focused_frame = @page.focused_frame
+
+  # Execute insertText in the focused frame's realm
+  focused_frame.isolated_realm.call_function(
+    'function(char) { document.execCommand("insertText", false, char); }',
+    false,
+    arguments: [{ type: 'string', value: char }]
+  )
+end
+```
+
+## Focused Frame Detection
+
+For iframe keyboard input, we need to detect which frame currently has focus.
+
+### Implementation Pattern (from Puppeteer)
+
+```ruby
+# Page#focused_frame
+def focused_frame
+  handle = main_frame.evaluate_handle(<<~JS)
+    () => {
+      let win = window;
+      while (
+        win.document.activeElement instanceof win.HTMLIFrameElement ||
+        win.document.activeElement instanceof win.HTMLFrameElement
+      ) {
+        if (win.document.activeElement.contentWindow === null) {
+          break;
+        }
+        win = win.document.activeElement.contentWindow;
+      }
+      return win;
+    }
+  JS
+
+  # Get context ID from window object
+  remote_value = handle.remote_value
+  context_id = remote_value['value']['context']
+
+  # Find frame with matching context ID
+  frames.find { |f| f.browsing_context.id == context_id }
+end
+```
+
+### Why This Matters
+
+When typing in an iframe:
+1. The user focuses a textarea inside the iframe
+2. `document.activeElement` in main frame points to the iframe element
+3. We traverse `activeElement.contentWindow` to find the focused frame
+4. `send_character` executes `insertText` in the correct frame's realm
+
+## Firefox BiDi Behavior Differences
+
+### Modifier + Character Input Events
+
+**Puppeteer (Chrome CDP) behavior**:
+- Shift + '!' → triggers input event
+- Control + '!' → no input event
+- Alt + '!' → no input event
+
+**Firefox BiDi behavior**:
+- Shift + '!' → triggers input event ✅
+- Control + '!' → triggers input event ⚠️
+- Alt + '!' → triggers input event ⚠️
+
+**Test adaptation**:
+```ruby
+# Instead of strict equality:
+expect(result).to eq("Keydown: ! Digit1 [#{modifier_key}]")
+
+# Use include to handle extra input events:
+expect(result).to include("Keydown: ! Digit1 [#{modifier_key}]")
+```
+
+### Modifier State Persistence
+
+**Known limitation**: BiDi doesn't maintain modifier state across separate `performActions` calls.
+
+**Workaround**: Combine all actions into a single `performActions` call when modifier state needs to persist.
+
+## Testing
+
+### Test Structure
+
+```ruby
+with_test_state do |page:, server:, **|
+  page.goto("#{server.prefix}/input/keyboard.html")
+
+  # Type text
+  page.keyboard.type('Hello')
+
+  # Verify result
+  result = page.evaluate('() => globalThis.getResult()')
+  expect(result).to eq('Keydown: H KeyH []')
+end
+```
+
+### Test Assets
+
+**Important**: `spec/assets/input/textarea.html` must define:
+```html
+<script>
+  globalThis.result = '';
+  globalThis.textarea = document.querySelector('textarea');
+  textarea.addEventListener('input', () => result = textarea.value, false);
+</script>
+```
+
+These global variables are used by multiple tests to verify keyboard input behavior.
+
+## References
+
+- **Puppeteer keyboard implementation**:
+  - TypeScript: `packages/puppeteer-core/src/bidi/Input.ts`
+  - Tests: `test/src/keyboard.spec.ts`
+- **BiDi Specification**:
+  - [input.performActions](https://w3c.github.io/webdriver-bidi/#command-input-performActions)
+- **Key definitions**:
+  - [W3C WebDriver Key Codes](https://www.w3.org/TR/webdriver/#keyboard-actions)
+
+## Common Pitfalls
+
+1. **Forgetting to update test assets**: Tests fail with "result is not defined" or "textarea is undefined"
+   - Solution: Download official Puppeteer test assets
+
+2. **Modifier state not persisting**: Separate `performActions` calls don't maintain modifier state
+   - Solution: Combine actions in single call (current limitation)
+
+3. **iframe input goes to main frame**: Text appears in wrong frame
+   - Solution: Implement `focused_frame` detection
+
+4. **Platform-specific Meta key**: Meta key doesn't work on Linux/Windows
+   - Solution: Use CtrlOrMeta abstraction

data/CLAUDE/mouse_implementation.md

@@ -0,0 +1,140 @@
+# Mouse Implementation
+
+## Overview
+
+Mouse input is implemented using WebDriver BiDi's `input.performActions` command with different source types.
+
+## BiDi Input Sources
+
+Different input types use different source types:
+
+| Input Type | Source Type | Source ID |
+|------------|-------------|-----------|
+| Mouse pointer | `pointer` | `default mouse` |
+| Keyboard | `key` | `default keyboard` |
+| Mouse wheel | `wheel` | `__puppeteer_wheel` |
+
+## Mouse Methods
+
+### move(x, y, steps:)
+
+Moves mouse to coordinates with optional intermediate steps for smooth movement.
+
+```ruby
+mouse.move(100, 200)           # Instant move
+mouse.move(100, 200, steps: 5) # Smooth move with 5 intermediate points
+```
+
+Uses linear interpolation for intermediate positions.
+
+### click(x, y, button:, count:, delay:)
+
+Moves to coordinates and performs click(s).
+
+```ruby
+mouse.click(100, 200)                    # Single left click
+mouse.click(100, 200, button: 'right')   # Right click
+mouse.click(100, 200, button: 'middle')  # Middle click (aux click)
+mouse.click(100, 200, button: 'back')    # Back button
+mouse.click(100, 200, button: 'forward') # Forward button
+mouse.click(100, 200, count: 2)          # Double click
+mouse.click(100, 200, delay: 100)        # Click with 100ms delay between down/up
+```
+
+### wheel(delta_x:, delta_y:)
+
+Scrolls using mouse wheel at current mouse position.
+
+```ruby
+mouse.wheel(delta_y: -100)  # Scroll up
+mouse.wheel(delta_y: 100)   # Scroll down
+mouse.wheel(delta_x: 50)    # Scroll right
+```
+
+**Important**: Uses separate `wheel` source type (not `pointer`).
+
+### reset
+
+Resets mouse state to origin and releases all pressed buttons.
+
+```ruby
+mouse.reset
+```
+
+Uses `input.releaseActions` BiDi command.
+
+## Data Classes
+
+### ElementHandle::BoundingBox
+
+```ruby
+BoundingBox = Data.define(:x, :y, :width, :height)
+
+box = element.bounding_box
+box.x      # => 10.0
+box.width  # => 100.0
+```
+
+### ElementHandle::Point
+
+```ruby
+Point = Data.define(:x, :y)
+
+point = element.clickable_point
+point.x  # => 50.0
+point.y  # => 75.0
+```
+
+### ElementHandle::BoxModel
+
+CSS box model with content, padding, border, and margin quads. Each quad is an array of 4 Points (top-left, top-right, bottom-right, bottom-left).
+
+```ruby
+BoxModel = Data.define(:content, :padding, :border, :margin, :width, :height)
+
+box = element.box_model
+box.width           # => 200.0
+box.height          # => 100.0
+box.border[0]       # => Point(x: 10.0, y: 20.0) - top-left corner
+box.content[0].x    # => 21.0 (border.x + borderLeftWidth + paddingLeft)
+```
+
+**Note**: Frame offset handling is not yet implemented. For elements inside iframes, coordinates are relative to the iframe, not the main page.
+
+## ElementHandle#click
+
+ElementHandle has its own `click` method that:
+1. Scrolls element into view if needed
+2. Gets clickable point
+3. Uses `frame.page.mouse.click()` to perform the click
+
+```ruby
+element = page.query_selector('button')
+element.click                      # Single click
+element.click(count: 2)            # Double click
+element.click(button: 'right')     # Right click
+```
+
+Note: ElementHandle gets its frame via `@realm.environment`, so no frame parameter is needed.
+
+## Hover Implementation
+
+Hover is implemented at three levels following Puppeteer's pattern:
+
+1. **ElementHandle#hover** - Scrolls into view, gets clickable point, moves mouse
+2. **Frame#hover(selector)** - Queries element, calls element.hover
+3. **Page#hover(selector)** - Delegates to main_frame.hover
+
+## WebDriver BiDi Limitations
+
+### is_mobile not supported
+
+The `set_viewport` method does not support `is_mobile` parameter because WebDriver BiDi protocol doesn't support device emulation yet.
+
+- Tracking issue: https://github.com/w3c/webdriver-bidi/issues/772
+- Puppeteer also doesn't implement this for BiDi
+
+## References
+
+- [WebDriver BiDi Input Module](https://w3c.github.io/webdriver-bidi/#module-input)
+- [Puppeteer Input.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Input.ts)

data/CLAUDE/navigation_waiting.md

@@ -0,0 +1,234 @@
+# Navigation Waiting Pattern
+
+This document explains the implementation of `Page.waitForNavigation` and `Frame.waitForNavigation`.
+
+## Overview
+
+Navigation waiting is a critical feature for browser automation. It allows you to execute an action that triggers navigation and wait for it to complete before proceeding.
+
+## API Design
+
+### Block-Based API
+
+Following Ruby conventions, we provide a block-based API that hides Async complexity:
+
+```ruby
+# Wait for navigation triggered by block
+page.wait_for_navigation(timeout: 30000, wait_until: 'load') do
+  page.click('a')
+end
+
+# Without block - waits for any navigation
+page.wait_for_navigation(timeout: 30000)
+```
+
+**Parameters:**
+- `timeout` (milliseconds): Navigation timeout (default: 30000)
+- `wait_until`: When to consider navigation succeeded
+  - `'load'`: Wait for `load` event (default)
+  - `'domcontentloaded'`: Wait for `DOMContentLoaded` event
+
+**Returns:**
+- `HTTPResponse` object for full page navigation
+- `nil` for fragment navigation (#hash) or History API operations
+
+## Navigation Types
+
+WebDriver BiDi distinguishes three types of navigation:
+
+### 1. Full Page Navigation
+
+**Trigger**: `page.goto()`, clicking links, form submission
+
+**BiDi Events:**
+1. `browsingContext.navigationStarted` - Creates Navigation object
+2. `browsingContext.load` or `browsingContext.domContentLoaded`
+
+**Response**: Returns HTTPResponse object
+
+```ruby
+response = page.wait_for_navigation do
+  page.evaluate("url => { window.location.href = url }", "https://example.com")
+end
+# => HTTPResponse object
+```
+
+### 2. Fragment Navigation
+
+**Trigger**: Anchor link clicks (`<a href="#section">`), hash changes
+
+**BiDi Events:**
+- `browsingContext.fragmentNavigated` (no navigationStarted)
+
+**Response**: Returns `nil`
+
+```ruby
+response = page.wait_for_navigation do
+  page.click('a[href="#foobar"]')
+end
+# => nil
+expect(page.url).to end_with('#foobar')
+```
+
+### 3. History API Navigation
+
+**Trigger**: `history.pushState()`, `history.replaceState()`, `history.back()`, `history.forward()`
+
+**BiDi Events:**
+- `browsingContext.historyUpdated` (no navigationStarted)
+
+**Response**: Returns `nil`
+
+```ruby
+response = page.wait_for_navigation do
+  page.evaluate("() => { history.pushState({}, '', 'new.html') }")
+end
+# => nil
+expect(page.url).to end_with('new.html')
+```
+
+## Implementation Pattern
+
+### Event-Driven Waiting
+
+The implementation uses an **event-driven pattern** with `Async::Promise`:
+
+```ruby
+def wait_for_navigation(timeout: 30000, wait_until: 'load', &block)
+  # Single promise that all event listeners resolve
+  promise = Async::Promise.new
+
+  # Register listeners for all 3 navigation types
+  navigation_listener = proc { ... promise.resolve(...) }
+  history_listener = proc { ... promise.resolve(nil) }
+  fragment_listener = proc { ... promise.resolve(nil) }
+
+  @browsing_context.on(:navigation, &navigation_listener)
+  @browsing_context.on(:history_updated, &history_listener)
+  @browsing_context.on(:fragment_navigated, &fragment_listener)
+
+  begin
+    block.call if block  # Trigger navigation
+
+    Async do |task|
+      task.with_timeout(timeout / 1000.0) do
+        promise.wait  # Wait for any listener to resolve
+      end
+    end.wait
+  ensure
+    # Clean up ALL listeners
+    @browsing_context.off(:navigation, &navigation_listener)
+    @browsing_context.off(:history_updated, &history_listener)
+    @browsing_context.off(:fragment_navigated, &fragment_listener)
+  end
+end
+```
+
+### Why Not Use `AsyncUtils.promise_race`?
+
+**TL;DR**: Event-driven waiting is different from racing independent tasks.
+
+`AsyncUtils.promise_race` is designed for **parallel task execution**:
+```ruby
+# ✅ Good use case: Racing independent tasks
+result = AsyncUtils.promise_race(
+  -> { fetch_from_api_1 },
+  -> { fetch_from_api_2 },
+  -> { fetch_from_api_3 }
+)
+```
+
+Navigation waiting requires **event listener coordination**:
+- Need to register listeners *before* triggering navigation
+- Must clean up *all* listeners regardless of which fires
+- Share state between listeners (e.g., `navigation_received` flag)
+- Nested event handling (Navigation object events)
+
+The current pattern is **simpler and more appropriate** because:
+1. ✅ Single promise resolved by multiple listeners
+2. ✅ Clear cleanup path for all listeners in `ensure` block
+3. ✅ No nested reactor issues (promise_race uses `Sync do`)
+4. ✅ Handles complex nested events (Navigation object completion events)
+5. ✅ Easy to debug and reason about
+
+## Navigation Object Integration
+
+For full page navigation, BiDi creates a Navigation object that tracks completion:
+
+```ruby
+navigation_listener = proc do |data|
+  navigation = data[:navigation]
+  navigation_received = true
+
+  # Listen for Navigation completion events
+  navigation.once(:fragment) { promise.resolve(nil) }
+  navigation.once(:failed) { promise.resolve(nil) }
+  navigation.once(:aborted) { promise.resolve(nil) }
+
+  # Also wait for load event
+  @browsing_context.once(load_event) do
+    promise.resolve(response_holder[:value])
+  end
+end
+```
+
+This nested event handling is a key reason why `promise_race` doesn't simplify the implementation.
+
+## Race Condition Prevention
+
+The implementation prevents race conditions where multiple navigation types could fire:
+
+```ruby
+navigation_received = false
+
+navigation_listener = proc do |data|
+  navigation_received = true
+  # ... set up Navigation object listeners
+end
+
+history_listener = proc do
+  # Only resolve if we haven't received navigation event
+  promise.resolve(nil) unless navigation_received || promise.resolved?
+end
+
+fragment_listener = proc do
+  # Only resolve if we haven't received navigation event
+  promise.resolve(nil) unless navigation_received || promise.resolved?
+end
+```
+
+This ensures:
+- Full page navigation takes precedence over history/fragment events
+- No double-resolution of the promise
+- Correct return value (HTTPResponse vs nil)
+
+## Error Handling
+
+Navigation can fail or timeout:
+
+```ruby
+begin
+  # ... wait for navigation
+rescue Async::TimeoutError
+  raise Puppeteer::Bidi::TimeoutError,
+        "Navigation timeout of #{timeout}ms exceeded"
+end
+```
+
+## Testing
+
+See `spec/integration/navigation_spec.rb` for comprehensive tests covering:
+1. Full page navigation
+2. Fragment navigation (anchor links)
+3. History API - pushState
+4. History API - replaceState
+5. History API - back/forward
+
+All tests verify both the navigation completes and the URL updates correctly.
+
+## References
+
+- [Puppeteer Frame.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Frame.ts)
+- [Puppeteer BrowsingContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/BrowsingContext.ts)
+- [Puppeteer Navigation.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/Navigation.ts)
+- [WebDriver BiDi Specification](https://w3c.github.io/webdriver-bidi/#module-browsingContext)