puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta2

data/CLAUDE/wrapped_element_click.md

@@ -1,247 +0,0 @@
-# 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

@@ -1,238 +0,0 @@
-# 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. **Update `API_COVERAGE.md`** - Mark implemented methods as ✅ and update coverage count
-6. 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 -- The name to set
-  # @rbs return: void
-  def initialize(name)
-    @name = name
-  end
-
-  # Query for an element matching the selector
-  # @rbs selector: String -- CSS selector to query
-  # @rbs return: ElementHandle? -- Matching element or nil
-  def query_selector(selector)
-    # ...
-  end
-end
-```
-
-**Conventions:**
-- Use `A?` for nullable types (not `A | nil`)
-- Use `A | B | nil` for union types with nil
-- **Always include descriptions** with `--` separator: `# @rbs name: String -- the name`
-- Public methods should have type annotations
-- **Do NOT use `@rbs!` blocks** - RubyMine IDE doesn't recognize them
-- **Use direct union types** instead of type aliases: `BrowserTarget | PageTarget | FrameTarget` not `target`
-- **Do NOT use `**options` in public APIs** - RubyMine shows as `untyped`. Use explicit keyword arguments:
-  - Optional params: `param: nil`
-  - Boolean params with default: `headless: true` or `enabled: false`
-  - Internal/Core layer methods may still use `**options` for flexibility
-
-**Generate RBS files:**
-```bash
-bundle exec rake rbs  # Generates sig/**/*.rbs
-```
-
-**Note:** `sig/` directory is gitignored. RBS files are generated automatically during `rake build`.
-
-### Type Checking with Steep
-
-Run type checking locally:
-```bash
-bundle exec rake rbs       # Generate RBS files first
-bundle exec steep check    # Run type checker
-```
-
-**Steepfile Configuration:**
-- Currently configured with lenient `:hint` level diagnostics for gradual typing
-- As type coverage improves, change to `:warning` or `:error` in `Steepfile`
-
-**Special RBS Files (manually maintained, NOT gitignored):**
-
-1. **`sig/_external.rbs`** - External dependency stubs
-   - Types for async gem (`Async`, `Kernel#Async`, `Kernel#Sync`, `Async::Task`, etc.)
-   - Standard library extensions (`Dir.mktmpdir`, `Time.parse`)
-   - Third-party types (`Singleton`, `Protocol::WebSocket`)
-
-2. **`sig/_supplementary.rbs`** - Types rbs-inline cannot generate
-   - `extend self` pattern: Add `extend ModuleName` declaration
-   - Singleton pattern: Add `extend Singleton::SingletonClassMethods`
-
-**Common Issues:**
-
-1. **Type alias must be lowercase**: In RBS, `type target = ...` not `type Target = ...`
-
-2. **`extend self` not recognized**: Add to `sig/_supplementary.rbs`:
-   ```rbs
-   module Foo
-     extend Foo  # Makes instance methods callable as singleton methods
-   end
-   ```
-
-3. **Singleton pattern**: Add to `sig/_supplementary.rbs`:
-   ```rbs
-   class Bar
-     extend Singleton::SingletonClassMethods
-   end
-   ```
-
-4. **Missing external types**: Add stubs to `sig/_external.rbs`
-
-### 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
-- **[ReactorRunner](CLAUDE/reactor_runner.md)** - Using browser outside Sync blocks (at_exit, etc.)
-- **[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)
-- **[ExposeFunction](CLAUDE/expose_function_implementation.md)** - `exposeFunction` and `evaluateOnNewDocument` using BiDi script.message
-- **[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