puppeteer-bidi 0.0.1.beta1

data/CLAUDE/two_layer_architecture.md

@@ -0,0 +1,180 @@
+# Two-Layer Async Architecture
+
+This codebase implements a two-layer architecture to separate async complexity from user-facing APIs.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Upper Layer (Puppeteer::Bidi)                          │
+│  - User-facing, synchronous API                         │
+│  - Calls .wait internally on Core layer methods         │
+│  - Examples: Page, Frame, JSHandle, ElementHandle       │
+├─────────────────────────────────────────────────────────┤
+│  Core Layer (Puppeteer::Bidi::Core)                     │
+│  - Returns Async::Task for all async operations         │
+│  - Uses async_send_command internally                   │
+│  - Examples: Session, BrowsingContext, Realm            │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Design Principles
+
+1. **Core Layer (Puppeteer::Bidi::Core)**:
+   - All methods that communicate with BiDi protocol return `Async::Task`
+   - Uses `session.async_send_command` (not `send_command`)
+   - Methods are explicitly async and composable
+   - Examples: `BrowsingContext#navigate`, `Realm#call_function`
+
+2. **Upper Layer (Puppeteer::Bidi)**:
+   - All methods call `.wait` on Core layer async operations
+   - Provides synchronous, blocking API for users
+   - Users never see `Async::Task` directly
+   - Examples: `Page#goto`, `Frame#evaluate`, `JSHandle#get_property`
+
+## Implementation Patterns
+
+### Core Layer Pattern
+
+```ruby
+# lib/puppeteer/bidi/core/browsing_context.rb
+def navigate(url, wait: nil)
+  Async do
+    raise BrowsingContextClosedError, @reason if closed?
+    params = { context: @id, url: url }
+    params[:wait] = wait if wait
+    result = session.async_send_command('browsingContext.navigate', params).wait
+    result
+  end
+end
+
+def perform_actions(actions)
+  raise BrowsingContextClosedError, @reason if closed?
+  session.async_send_command('input.performActions', {
+    context: @id,
+    actions: actions
+  })
+end
+```
+
+**Key points:**
+- Returns `Async::Task` (implicitly from `Async do` block or explicitly from `async_send_command`)
+- Users of Core layer must call `.wait` to get results
+
+### Upper Layer Pattern
+
+```ruby
+# lib/puppeteer/bidi/frame.rb
+def goto(url, wait_until: 'load', timeout: 30000)
+  response = wait_for_navigation(timeout: timeout, wait_until: wait_until) do
+    @browsing_context.navigate(url, wait: 'interactive').wait  # .wait call
+  end
+  HTTPResponse.new(url: @browsing_context.url, status: 200)
+end
+
+# lib/puppeteer/bidi/keyboard.rb
+def perform_actions(action_list)
+  @browsing_context.perform_actions([
+    {
+      type: 'key',
+      id: 'default keyboard',
+      actions: action_list
+    }
+  ]).wait  # .wait call
+end
+```
+
+**Key points:**
+- Always calls `.wait` on Core layer methods
+- Returns plain Ruby objects (String, Hash, etc.), not Async::Task
+- User-facing API is synchronous
+
+## Common Mistakes and How to Fix Them
+
+### Mistake 1: Forgetting .wait on Core Layer Methods
+
+```ruby
+# WRONG: Missing .wait
+def query_selector(selector)
+  result = @realm.call_function(...)
+  if result['type'] == 'exception'  # Error: undefined method '[]' for Async::Task
+    # ...
+  end
+end
+
+# CORRECT: Add .wait
+def query_selector(selector)
+  result = @realm.call_function(...).wait  # Add .wait here
+  if result['type'] == 'exception'
+    # ...
+  end
+end
+```
+
+### Mistake 2: Using send_command Instead of async_send_command in Core Layer
+
+```ruby
+# WRONG: Using send_command (doesn't exist)
+def perform_actions(actions)
+  session.send_command('input.performActions', {...})  # Error: undefined method
+end
+
+# CORRECT: Use async_send_command
+def perform_actions(actions)
+  session.async_send_command('input.performActions', {...})
+end
+```
+
+### Mistake 3: Not Calling .wait on All Core Methods
+
+```ruby
+# WRONG: Multiple Core calls, only one .wait
+def get_properties
+  result = @realm.call_function(...).wait  # OK
+  props_result = @realm.call_function(...)  # Missing .wait!
+  if props_result['type'] == 'exception'  # Error
+    # ...
+  end
+end
+
+# CORRECT: Add .wait to all Core calls
+def get_properties
+  result = @realm.call_function(...).wait
+  props_result = @realm.call_function(...).wait  # Add .wait
+  if props_result['type'] == 'exception'
+    # ...
+  end
+end
+```
+
+## Checklist for Adding New Methods
+
+When adding new methods to the Upper Layer:
+
+1. Identify all calls to Core layer methods
+2. Add `.wait` to each Core layer method call
+3. Verify the method returns plain Ruby objects, not Async::Task
+4. Test with integration specs
+
+When adding new methods to the Core Layer:
+
+1. Use `session.async_send_command` (not `send_command`)
+2. Wrap in `Async do ... end` if needed
+3. Return `Async::Task` (don't call .wait)
+4. Document that callers must call .wait
+
+## Files Modified for Async Architecture
+
+**Core Layer:**
+- `lib/puppeteer/bidi/core/session.rb` - Changed `send_command` → `async_send_command`
+- `lib/puppeteer/bidi/core/browsing_context.rb` - All methods use `async_send_command`
+- `lib/puppeteer/bidi/core/realm.rb` - Methods return `Async::Task`
+
+**Upper Layer:**
+- `lib/puppeteer/bidi/realm.rb` - Added `.wait` to `execute_with_core`, `call_function`
+- `lib/puppeteer/bidi/frame.rb` - Added `.wait` to `goto`
+- `lib/puppeteer/bidi/js_handle.rb` - Added `.wait` to `dispose`, `get_property`, `get_properties`, `as_element`
+- `lib/puppeteer/bidi/element_handle.rb` - Added `.wait` to `query_selector_all`, `eval_on_selector_all`
+- `lib/puppeteer/bidi/keyboard.rb` - Added `.wait` to `perform_actions`
+- `lib/puppeteer/bidi/mouse.rb` - Added `.wait` to `perform_actions`
+- `lib/puppeteer/bidi/page.rb` - Added `.wait` to `capture_screenshot`, `close`, `set_viewport`, `set_javascript_enabled`

data/CLAUDE/wrapped_element_click.md

@@ -0,0 +1,247 @@
+# Wrapped Element Click Implementation
+
+## Problem
+
+When clicking on wrapped or multi-line text elements, using `getBoundingClientRect()` returns a single large bounding box that may have empty space in the center, causing clicks to miss the actual element.
+
+## Example: Wrapped Link
+
+```html
+<div style="width: 10ch; word-wrap: break-word;">
+  <a href='#clicked'>123321</a>
+</div>
+```
+
+The link text wraps into two lines:
+```
+123
+321
+```
+
+### getBoundingClientRect() Problem
+
+Returns single large box:
+```ruby
+{x: 628.45, y: 62.47, width: 109.1, height: 49.73}
+```
+
+Click point (center): `(683, 87)` → **hits empty space between lines!**
+
+### getClientRects() Solution
+
+Returns multiple boxes for wrapped text:
+```ruby
+[
+  {x: 708.58, y: 62.47, width: 32.73, height: 22.67},  # "123"
+  {x: 628.45, y: 85.15, width: 32.73, height: 22.67}   # "321"
+]
+```
+
+Click point (first box center): `(725, 73)` → **hits actual text!**
+
+## Implementation
+
+### clickable_box Method
+
+```ruby
+def clickable_box
+  assert_not_disposed
+
+  # Get client rects - returns multiple boxes for wrapped elements
+  boxes = evaluate(<<~JS)
+    element => {
+      if (!(element instanceof Element)) {
+        return null;
+      }
+      return [...element.getClientRects()].map(rect => {
+        return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
+      });
+    }
+  JS
+
+  return nil unless boxes&.is_a?(Array) && !boxes.empty?
+
+  # Intersect boxes with frame boundaries
+  intersect_bounding_boxes_with_frame(boxes)
+
+  # Find first box with valid dimensions
+  box = boxes.find { |rect| rect['width'] >= 1 && rect['height'] >= 1 }
+  return nil unless box
+
+  {
+    x: box['x'],
+    y: box['y'],
+    width: box['width'],
+    height: box['height']
+  }
+end
+```
+
+### Viewport Clipping: intersectBoundingBoxesWithFrame
+
+Clips element boxes to visible viewport boundaries:
+
+```ruby
+def intersect_bounding_boxes_with_frame(boxes)
+  # Get document dimensions using element's evaluate
+  dimensions = evaluate(<<~JS)
+    element => {
+      return {
+        documentWidth: element.ownerDocument.documentElement.clientWidth,
+        documentHeight: element.ownerDocument.documentElement.clientHeight
+      };
+    }
+  JS
+
+  document_width = dimensions['documentWidth']
+  document_height = dimensions['documentHeight']
+
+  boxes.each do |box|
+    intersect_bounding_box(box, document_width, document_height)
+  end
+end
+
+def intersect_bounding_box(box, width, height)
+  # Clip width
+  box['width'] = [
+    box['x'] >= 0 ?
+      [width - box['x'], box['width']].min :
+      [width, box['width'] + box['x']].min,
+    0
+  ].max
+
+  # Clip height
+  box['height'] = [
+    box['y'] >= 0 ?
+      [height - box['y'], box['height']].min :
+      [height, box['height'] + box['y']].min,
+    0
+  ].max
+
+  # Ensure non-negative coordinates
+  box['x'] = [box['x'], 0].max
+  box['y'] = [box['y'], 0].max
+end
+```
+
+## Why This Matters
+
+### Use Cases for getClientRects()
+
+1. **Wrapped text**: Multi-line links, buttons with text wrapping
+2. **Inline elements**: `<span>` elements that span multiple lines
+3. **Complex layouts**: Elements with transforms, rotations
+
+### Algorithm Flow
+
+1. **Get all client rects** for element (array of boxes)
+2. **Clip to viewport** using intersectBoundingBox algorithm
+3. **Find first valid box** (width >= 1 && height >= 1)
+4. **Click center of that box**
+
+## Puppeteer Reference
+
+Based on [ElementHandle.ts#clickableBox](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts):
+
+```typescript
+async #clickableBox(): Promise<BoundingBox | null> {
+  const boxes = await this.evaluate(element => {
+    if (!(element instanceof Element)) {
+      return null;
+    }
+    return [...element.getClientRects()].map(rect => {
+      return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
+    });
+  });
+
+  if (!boxes?.length) {
+    return null;
+  }
+
+  await this.#intersectBoundingBoxesWithFrame(boxes);
+
+  // ... parent frame handling ...
+
+  const box = boxes.find(box => {
+    return box.width >= 1 && box.height >= 1;
+  });
+
+  return box || null;
+}
+```
+
+## Testing
+
+### Test Asset
+
+Official Puppeteer test asset: `spec/assets/wrappedlink.html`
+
+```html
+<div style="width: 10ch; word-wrap: break-word; transform: rotate(33deg);">
+  <a href='#clicked'>123321</a>
+</div>
+```
+
+**Critical**: Always use official test assets without modification!
+
+### Test Case
+
+```ruby
+it 'should click wrapped links' do
+  with_test_state do |page:, server:, **|
+    page.goto("#{server.prefix}/wrappedlink.html")
+    page.click('a')
+    result = page.evaluate('window.__clicked')
+    expect(result).to be true
+  end
+end
+```
+
+## Debugging Protocol Messages
+
+Compare BiDi protocol messages with Puppeteer to verify coordinates:
+
+```bash
+# Ruby implementation
+DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/click_spec.rb:138
+
+# Look for input.performActions with click coordinates
+# Verify they fall within actual element bounds
+```
+
+## Key Takeaways
+
+1. **getClientRects() > getBoundingClientRect()** for clickable elements
+2. **First valid box** is the click target (not center of bounding box)
+3. **Viewport clipping** ensures clicks stay within visible area
+4. **Test with official assets** - simplified versions hide edge cases
+5. **Follow Puppeteer exactly** - algorithm has been battle-tested
+
+## Performance
+
+- `getClientRects()` is fast (native browser API)
+- Intersection algorithm is O(n) where n = number of boxes (typically 1-3)
+- No additional round-trips to browser
+
+## Future: Parent Frame Support
+
+For iframe support, add coordinate transformation:
+
+```ruby
+# TODO: Handle parent frames
+frame = self.frame
+while (parent_frame = frame.parent_frame)
+  # Adjust coordinates for parent frame offset
+  # boxes.each { |box| box['x'] += offset_x; box['y'] += offset_y }
+end
+```
+
+## Files
+
+- `lib/puppeteer/bidi/element_handle.rb`: clickable_box, intersect methods
+- `spec/integration/click_spec.rb`: Test case for wrapped links
+- `spec/assets/wrappedlink.html`: Official test asset (never modify!)
+
+## Commit Reference
+
+See commit: "Implement clickable_box with getClientRects() and viewport clipping"

data/CLAUDE.md

@@ -0,0 +1,185 @@
+# Puppeteer-BiDi Development Guide
+
+## Project Overview
+
+Port the WebDriver BiDi protocol portions of Puppeteer to Ruby, providing a standards-based tool for Firefox automation.
+
+### Development Principles
+
+- **BiDi-only**: Do not port CDP protocol-related code
+- **Standards compliance**: Adhere to W3C WebDriver BiDi specification
+- **Firefox optimization**: Maximize BiDi protocol capabilities
+- **Ruby conventions**: Design Ruby-idiomatic interfaces
+
+## Quick Reference
+
+### Running Tests
+
+```bash
+# All integration tests (requires Firefox Nightly for full functionality)
+bundle exec rspec spec/integration/
+
+# Single test file
+bundle exec rspec spec/integration/click_spec.rb
+
+# Non-headless mode
+HEADLESS=false bundle exec rspec spec/integration/
+
+# Debug protocol messages
+DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/click_spec.rb
+
+# Use specific Firefox path (e.g., Nightly)
+FIREFOX_PATH="/Applications/Firefox Nightly.app/Contents/MacOS/firefox" bundle exec rspec
+```
+
+**Note**: Some features (e.g., FileChooser) require Firefox Nightly. The browser launcher prioritizes Nightly automatically.
+
+### Key Architecture
+
+```
+Upper Layer (Puppeteer::Bidi)     - User-facing synchronous API
+  └── Page, Frame, ElementHandle, JSHandle
+
+Core Layer (Puppeteer::Bidi::Core) - Async operations, returns Async::Task
+  └── Session, BrowsingContext, Realm
+```
+
+**Critical**: Upper layer methods must call `.wait` on all Core layer method calls. See [Two-Layer Architecture](CLAUDE/two_layer_architecture.md).
+
+### Async Programming
+
+This project uses **Async (Fiber-based)**, NOT concurrent-ruby (Thread-based).
+
+- No Mutex needed (cooperative multitasking)
+- Similar to JavaScript async/await
+- See [Async Programming Guide](CLAUDE/async_programming.md)
+
+## Development Workflow
+
+1. Study Puppeteer's TypeScript implementation first
+2. Understand BiDi protocol calls
+3. Implement with proper deserialization
+4. Port tests from Puppeteer
+5. See [Porting Puppeteer Guide](CLAUDE/porting_puppeteer.md)
+
+## Coding Conventions
+
+### Ruby
+
+- Use Ruby 3.0+ features
+- Follow RuboCop guidelines
+- Class names: `PascalCase`, Methods: `snake_case`, Constants: `SCREAMING_SNAKE_CASE`
+
+### Type Annotations (rbs-inline)
+
+Use [rbs-inline](https://github.com/soutaro/rbs-inline) for type annotations in Ruby source files.
+
+**Setup:**
+- Add `# rbs_inline: enabled` magic comment at the top of the file
+- Use Doc style syntax for type annotations
+
+**Example:**
+```ruby
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Example
+  attr_reader :name #: String
+
+  # @rbs name: String
+  # @rbs return: void
+  def initialize(name)
+    @name = name
+  end
+
+  # @rbs selector: String
+  # @rbs return: ElementHandle?
+  def query_selector(selector)
+    # ...
+  end
+end
+```
+
+**Conventions:**
+- Use `A?` for nullable types (not `A | nil`)
+- Use `A | B | nil` for union types with nil
+- Add space around `--` for inline comments: `# @rbs name: String -- the name`
+- Public methods should have type annotations
+
+**Generate RBS files:**
+```bash
+bundle exec rake rbs  # Generates sig/**/*.rbs
+```
+
+**Note:** `sig/` directory is gitignored. RBS files are generated automatically during `rake build`.
+
+### Testing
+
+- Use RSpec for unit and integration tests
+- Integration tests in `spec/integration/`
+- Use `with_test_state` helper for browser reuse
+
+### Test Assets
+
+**CRITICAL**: Always use Puppeteer's official test assets without modification.
+
+- Source: https://github.com/puppeteer/puppeteer/tree/main/test/assets
+- Never modify files in `spec/assets/`
+- Revert any experimental changes before PRs
+
+## Detailed Documentation
+
+See the [CLAUDE/](CLAUDE/) directory for detailed implementation guides:
+
+### Architecture & Patterns
+
+- **[Two-Layer Architecture](CLAUDE/two_layer_architecture.md)** - Core vs Upper layer, async patterns
+- **[Async Programming](CLAUDE/async_programming.md)** - Fiber-based concurrency with socketry/async
+- **[Porting Puppeteer](CLAUDE/porting_puppeteer.md)** - Best practices for implementing features
+- **[Core Layer Gotchas](CLAUDE/core_layer_gotchas.md)** - EventEmitter/Disposable pitfalls, @disposed conflicts
+
+### Implementation Details
+
+- **[QueryHandler](CLAUDE/query_handler.md)** - CSS, XPath, text selector handling
+- **[JavaScript Evaluation](CLAUDE/javascript_evaluation.md)** - `evaluate()` and `evaluate_handle()`
+- **[JSHandle and ElementHandle](CLAUDE/jshandle_implementation.md)** - Object handle management
+- **[Selector Evaluation](CLAUDE/selector_evaluation.md)** - `eval_on_selector` methods
+- **[Click Implementation](CLAUDE/click_implementation.md)** - Mouse input and clicking
+- **[Mouse Implementation](CLAUDE/mouse_implementation.md)** - wheel, reset, hover, BoundingBox/Point data classes
+- **[Wrapped Element Click](CLAUDE/wrapped_element_click.md)** - getClientRects() for multi-line elements
+- **[Navigation Waiting](CLAUDE/navigation_waiting.md)** - waitForNavigation patterns
+- **[Frame Architecture](CLAUDE/frame_architecture.md)** - Parent-based frame hierarchy
+- **[FileChooser](CLAUDE/file_chooser.md)** - File upload and dialog handling (requires Firefox Nightly)
+- **[Error Handling](CLAUDE/error_handling.md)** - Custom exception types
+
+### Testing
+
+- **[Testing Strategy](CLAUDE/testing_strategy.md)** - Test organization and optimization
+- **[RSpec pending vs skip](CLAUDE/rspec_pending_vs_skip.md)** - Documenting limitations
+- **[Test Server Routes](CLAUDE/test_server_routes.md)** - Dynamic route handling
+
+## Releasing
+
+To release a new version:
+
+1. Update the version number in `lib/puppeteer/bidi/version.rb`
+2. Commit the change and push to main
+3. Create and push a version tag:
+   ```bash
+   git tag 1.2.3
+   git push origin 1.2.3
+   ```
+
+GitHub Actions will automatically build and publish the gem to RubyGems. Supported tag formats:
+- `1.2.3` - stable release
+- `1.2.3.alpha1` - alpha release
+- `1.2.3.beta2` - beta release
+
+**Note:** `RUBYGEMS_API_KEY` must be configured in repository secrets.
+
+## References
+
+- [WebDriver BiDi Specification](https://w3c.github.io/webdriver-bidi/)
+- [Puppeteer Documentation](https://pptr.dev/)
+- [Puppeteer Source Code](https://github.com/puppeteer/puppeteer)
+- [puppeteer-ruby](https://github.com/YusukeIwaki/puppeteer-ruby) - CDP implementation reference

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 YusukeIwaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.