puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta2

data/CLAUDE/expose_function_implementation.md

@@ -1,271 +0,0 @@
-# ExposeFunction and EvaluateOnNewDocument Implementation
-
-This document details the implementation of `Page.evaluateOnNewDocument` and `Page.exposeFunction`, which use BiDi preload scripts and `script.message` channel for communication.
-
-## Page.evaluateOnNewDocument
-
-Injects JavaScript to be evaluated before any page scripts run.
-
-### BiDi Implementation
-
-Uses `script.addPreloadScript` command:
-
-```ruby
-def evaluate_on_new_document(page_function, *args)
-  expression = build_evaluation_expression(page_function, *args)
-  script_id = @browsing_context.add_preload_script(expression).wait
-  NewDocumentScriptEvaluation.new(script_id)
-end
-```
-
-### Key Points
-
-1. **Preload Scripts Persist**: Scripts added via `addPreloadScript` run on every navigation
-2. **Argument Serialization**: Arguments are serialized into the script as JSON literals
-3. **Return Value**: Returns a `NewDocumentScriptEvaluation` with the script ID for later removal
-
-### Example
-
-```ruby
-# Inject code that runs before any page scripts
-script = page.evaluate_on_new_document("window.injected = 123")
-page.goto(server.empty_page)
-result = page.evaluate("window.injected")  # => 123
-
-# Remove when done
-page.remove_script_to_evaluate_on_new_document(script.identifier)
-```
-
-## Page.exposeFunction
-
-Exposes a Ruby callable as a JavaScript function on the page.
-
-### BiDi Implementation
-
-Uses `script.message` channel for bidirectional communication:
-
-```
-Page (JS)                    Ruby (ExposedFunction)
-    |                              |
-    |-- callback([resolve,reject,args]) -->|
-    |                              |
-    |<-- resolve(result) or reject(error) -|
-```
-
-### Key Components
-
-#### 1. Channel Argument Pattern
-
-BiDi uses a special `channel` argument type:
-
-```ruby
-def channel_argument
-  {
-    type: "channel",
-    value: {
-      channel: @channel,  # Unique channel ID
-      ownership: "root"   # Keep handles alive
-    }
-  }
-end
-```
-
-#### 2. Function Declaration
-
-The exposed function creates a Promise that waits for the Ruby callback:
-
-```javascript
-(callback) => {
-  Object.assign(globalThis, {
-    [name]: function (...args) {
-      return new Promise((resolve, reject) => {
-        callback([resolve, reject, args]);
-      });
-    },
-  });
-}
-```
-
-#### 3. Message Handling
-
-Ruby listens for `script.message` events and processes calls:
-
-```ruby
-def handle_message(params)
-  return unless params["channel"] == @channel
-
-  # Extract data handle with [resolve, reject, args]
-  data_handle = JSHandle.from(params["data"], realm.core_realm)
-
-  # Call Ruby function and send result back
-  result = @apply.call(*args)
-  send_result(data_handle, result)
-end
-```
-
-### Session Event Subscription
-
-**Important**: `script.message` must be subscribed in the session:
-
-```ruby
-# In Core::Session
-def subscribe_to_events
-  subscribe([
-    "browsingContext.load",
-    "browsingContext.domContentLoaded",
-    # ... other events
-    "script.message",  # Required for exposeFunction
-  ]).wait
-end
-```
-
-### Frame Handling
-
-ExposedFunction handles dynamic frames by:
-
-1. **Listening to frameattached**: Injects into new frames
-2. **Using preload scripts**: For top-level browsing contexts (not iframes)
-3. **Using callFunction**: For immediate injection into current context
-
-```ruby
-def inject_into_frame(frame)
-  # Add preload script for top-level contexts only
-  if frame.browsing_context.parent.nil?
-    script_id = frame.browsing_context.add_preload_script(
-      function_declaration,
-      arguments: [channel]
-    ).wait
-  end
-
-  # Always call function for immediate availability
-  realm.core_realm.call_function(
-    function_declaration,
-    false,
-    arguments: [channel]
-  ).wait
-end
-```
-
-### Error Handling
-
-#### Standard Errors
-
-Errors are serialized with name, message, and stack trace:
-
-```ruby
-def send_error(data_handle, error)
-  name = error.class.name
-  message = error.message
-  stack = error.backtrace&.join("\n")
-
-  data_handle.evaluate(<<~JS, name, message, stack)
-    ([, reject], name, message, stack) => {
-      const error = new Error(message);
-      error.name = name;
-      if (stack) { error.stack = stack; }
-      reject(error);
-    }
-  JS
-end
-```
-
-#### Non-Error Values (ThrownValue)
-
-Ruby doesn't support `throw "string"` syntax. Use `ThrownValue`:
-
-```ruby
-class ThrownValue < StandardError
-  attr_reader :value
-
-  def initialize(value)
-    @value = value
-    super("Thrown value")
-  end
-end
-
-# Usage
-page.expose_function("throwValue") do |value|
-  raise ExposedFunction::ThrownValue.new(value)
-end
-```
-
-### Cleanup
-
-Disposal removes the function from all frames and cleans up resources:
-
-```ruby
-def dispose
-  session.off("script.message", &@listener)
-  page.off(:frameattached, &@frame_listener)
-
-  # Remove from globalThis
-  remove_binding_from_frame(@frame)
-
-  # Remove preload scripts
-  @scripts.each do |frame, script_id|
-    frame.browsing_context.remove_preload_script(script_id).wait
-  end
-end
-```
-
-## Testing Considerations
-
-### CSP Headers
-
-Some tests require Content-Security-Policy headers. Use `TestServer#set_csp`:
-
-```ruby
-server.set_csp("/empty.html", "script-src 'self'")
-```
-
-### Test Asset
-
-`spec/assets/tamperable.html` captures `window.injected` before page scripts run:
-
-```html
-<script>
-  window.result = window.injected;
-</script>
-```
-
-## Common Pitfalls
-
-### 1. Missing script.message Subscription
-
-**Problem**: `exposeFunction` doesn't receive callbacks
-
-**Solution**: Ensure `script.message` is in session event subscriptions
-
-### 2. Ownership: "root" Required
-
-**Problem**: JSHandle becomes invalid before processing
-
-**Solution**: Use `ownership: "root"` in channel argument to keep handles alive
-
-### 3. Preload Scripts for Iframes
-
-**Problem**: `addPreloadScript` not supported for iframe contexts
-
-**Solution**: Only use preload scripts for top-level contexts; use `callFunction` for iframes
-
-### 4. TypeError on raise nil
-
-**Problem**: Ruby's `raise nil` throws `TypeError: exception class/object expected`
-
-**Solution**: Catch and convert to `send_thrown_value`:
-
-```ruby
-rescue TypeError => e
-  if e.message.include?("exception class/object expected")
-    send_thrown_value(data_handle, nil)
-  else
-    send_error(data_handle, e)
-  end
-end
-```
-
-## References
-
-- [WebDriver BiDi script.message](https://w3c.github.io/webdriver-bidi/#event-script-message)
-- [WebDriver BiDi addPreloadScript](https://w3c.github.io/webdriver-bidi/#command-script-addPreloadScript)
-- [Puppeteer ExposedFunction.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/ExposedFunction.ts)

data/CLAUDE/file_chooser.md

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

data/CLAUDE/frame_architecture.md

@@ -1,346 +0,0 @@
-# Frame Architecture Implementation
-
-## Overview
-
-This document details the Frame architecture implementation following Puppeteer's parent-based design pattern.
-
-## Architecture Change
-
-### Before (Incorrect)
-
-```ruby
-class Frame
-  def initialize(browsing_context, page = nil)
-    @browsing_context = browsing_context
-    @page = page
-  end
-end
-
-# Page creates frame
-Frame.new(@browsing_context, self)
-```
-
-**Problem**: Frame directly stores reference to Page, doesn't support nested frames (iframe).
-
-### After (Correct - Following Puppeteer)
-
-```ruby
-class Frame
-  def initialize(parent, browsing_context)
-    @parent = parent  # Page or Frame
-    @browsing_context = browsing_context
-  end
-
-  def page
-    @parent.is_a?(Page) ? @parent : @parent.page
-  end
-
-  def parent_frame
-    @parent.is_a?(Frame) ? @parent : nil
-  end
-end
-
-# Page creates frame
-Frame.new(self, @browsing_context)
-```
-
-**Benefits**:
-- Supports nested frames (iframe within iframe)
-- Matches Puppeteer's TypeScript implementation
-- Enables recursive page traversal
-- Simplifies parent_frame implementation
-
-## Reference Implementation
-
-Based on [Puppeteer's Frame.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Frame.ts):
-
-```typescript
-export class BidiFrame extends Frame {
-  #parent: BidiPage | BidiFrame;
-  #browsingContext: BrowsingContext;
-
-  constructor(
-    parent: BidiPage | BidiFrame,
-    browsingContext: BrowsingContext,
-  ) {
-    super();
-    this.#parent = parent;
-    this.#browsingContext = browsingContext;
-  }
-
-  override get page(): BidiPage {
-    let parent = this.#parent;
-    while (parent instanceof BidiFrame) {
-      parent = parent.#parent;
-    }
-    return parent;
-  }
-
-  override get parentFrame(): BidiFrame | null {
-    if (this.#parent instanceof BidiFrame) {
-      return this.#parent;
-    }
-    return null;
-  }
-}
-```
-
-## Implementation Details
-
-### Constructor Signature
-
-**Critical**: The first parameter is `parent` (Page or Frame), not `page`:
-
-```ruby
-def initialize(parent, browsing_context)
-  @parent = parent
-  @browsing_context = browsing_context
-end
-```
-
-### Page Traversal
-
-Recursive implementation using ternary operator:
-
-```ruby
-def page
-  @parent.is_a?(Page) ? @parent : @parent.page
-end
-```
-
-This is simpler than a while loop and matches Puppeteer's logic flow.
-
-### Parent Frame Access
-
-```ruby
-def parent_frame
-  @parent.is_a?(Frame) ? @parent : nil
-end
-```
-
-Returns:
-- `Frame` instance if this is a child frame
-- `nil` if this is a main frame (parent is Page)
-
-## Usage Examples
-
-### Main Frame
-
-```ruby
-page = browser.new_page
-main_frame = page.main_frame
-
-main_frame.page         # => page
-main_frame.parent_frame # => nil
-```
-
-### Nested Frames (Future)
-
-```ruby
-# When iframe support is added:
-iframe = main_frame.child_frames.first
-
-iframe.page         # => page (traverses up to Page)
-iframe.parent_frame # => main_frame
-```
-
-## Testing
-
-All 108 integration tests pass with this architecture:
-
-```bash
-bundle exec rspec spec/integration/
-# 108 examples, 0 failures, 4 pending
-```
-
-## Key Takeaways
-
-1. **Follow Puppeteer's constructor signature exactly** - `(parent, browsing_context)` not `(browsing_context, page)`
-2. **Use ternary operator for simplicity** - `@parent.is_a?(Page) ? @parent : @parent.page`
-3. **Enables future iframe support** - Architecture supports nested frame trees
-4. **Remove redundant attr_reader** - No need for `attr_reader :parent` when using private instance variable
-
-## Frame Events
-
-### Overview
-
-Frame lifecycle events are emitted on the Page object, following Puppeteer's pattern:
-
-- `:frameattached` - Fired when a new child frame is created
-- `:framedetached` - Fired when a frame's browsing context is closed
-- `:framenavigated` - Fired on DOMContentLoaded or fragment navigation
-
-### Event Emission Locations (Following Puppeteer Exactly)
-
-**Critical**: The location where each event is emitted matters for correct behavior.
-
-| Event | Location | Trigger |
-|-------|----------|---------|
-| `:frameattached` | `Frame#create_frame_target` | Child browsing context created |
-| `:framedetached` | `Frame#initialize_frame` | **Self's** browsing context closed |
-| `:framenavigated` | `Frame#initialize_frame` | DOMContentLoaded or fragment_navigated |
-
-### Puppeteer Reference Code
-
-From [Puppeteer's bidi/Frame.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Frame.ts):
-
-```typescript
-// In #initialize() - FrameDetached is emitted for THIS frame
-this.browsingContext.on('closed', () => {
-  this.page().trustedEmitter.emit(PageEvent.FrameDetached, this);
-});
-
-// In #createFrameTarget() - FrameAttached is emitted for child frame
-#createFrameTarget(browsingContext: BrowsingContext) {
-  const frame = BidiFrame.from(this, browsingContext);
-  this.#frames.set(browsingContext, frame);
-  this.page().trustedEmitter.emit(PageEvent.FrameAttached, frame);
-
-  // Note: FrameDetached is NOT emitted here
-  browsingContext.on('closed', () => {
-    this.#frames.delete(browsingContext);
-  });
-
-  return frame;
-}
-```
-
-### Ruby Implementation
-
-```ruby
-# Frame#initialize_frame
-def initialize_frame
-  # ... child frame setup ...
-
-  # FrameDetached: emit when THIS frame's context closes
-  @browsing_context.on(:closed) do
-    @frames.clear
-    page.emit(:framedetached, self)
-  end
-
-  # FrameNavigated: emit on navigation events
-  @browsing_context.on(:dom_content_loaded) do
-    page.emit(:framenavigated, self)
-  end
-
-  @browsing_context.on(:fragment_navigated) do
-    page.emit(:framenavigated, self)
-  end
-end
-
-# Frame#create_frame_target
-def create_frame_target(browsing_context)
-  frame = Frame.from(self, browsing_context)
-  @frames[browsing_context.id] = frame
-
-  # FrameAttached: emit for the new child frame
-  page.emit(:frameattached, frame)
-
-  # Only cleanup, NO FrameDetached here
-  browsing_context.once(:closed) do
-    @frames.delete(browsing_context.id)
-  end
-
-  frame
-end
-```
-
-### Common Mistake
-
-**Wrong**: Emitting `:framedetached` in `create_frame_target` when child's context closes.
-
-**Correct**: Each frame emits its own `:framedetached` in `initialize_frame` when its own browsing context closes.
-
-This matters because the event should be emitted by the frame instance that is being detached, not by its parent.
-
-## Page Event Emitter
-
-Page delegates to `Core::EventEmitter` for event handling:
-
-```ruby
-class Page
-  def initialize(...)
-    @emitter = Core::EventEmitter.new
-  end
-
-  def on(event, &block)
-    @emitter.on(event, &block)
-  end
-
-  def emit(event, data = nil)
-    @emitter.emit(event, data)
-  end
-end
-```
-
-## Files Changed
-
-- `lib/puppeteer/bidi/frame.rb`: Constructor signature, page method, parent_frame method, frame events
-- `lib/puppeteer/bidi/page.rb`: main_frame initialization, event emitter delegation
-
-## BiDi Protocol Limitations
-
-### Frame.frameElement with Shadow DOM
-
-**Status**: Not supported in BiDi protocol
-
-`Frame#frame_element` returns `nil` for iframes inside Shadow DOM (both open and closed).
-
-#### Root Cause
-
-| Protocol | Behavior | Mechanism |
-|----------|----------|-----------|
-| **CDP (Chrome)** | Works | Uses `DOM.getFrameOwner` command |
-| **BiDi (Firefox)** | Returns nil | Uses `document.querySelectorAll` (cannot traverse Shadow DOM) |
-
-#### Technical Details
-
-1. **CDP Implementation** (`cdp/Frame.js`):
-   ```javascript
-   const { backendNodeId } = await parent.client.send('DOM.getFrameOwner', {
-     frameId: this._id,
-   });
-   return await parent.mainRealm().adoptBackendNode(backendNodeId);
-   ```
-
-2. **BiDi Implementation** (base `api/Frame.js`):
-   ```javascript
-   const list = await parentFrame.isolatedRealm().evaluateHandle(() => {
-     return document.querySelectorAll('iframe,frame');
-   });
-   // Cannot find elements inside Shadow DOM
-   ```
-
-3. **WebDriver BiDi Specification**: No `DOM.getFrameOwner` equivalent command exists.
-
-#### Verification
-
-Tested with Puppeteer (Node.js) using both protocols:
-
-```
-=== Firefox (BiDi protocol) ===
-Frame element is NULL - Shadow DOM issue confirmed
-
-=== Chrome (CDP protocol) ===
-Frame element tagName: iframe
-```
-
-#### References
-
-- [Puppeteer Issue #13155](https://github.com/puppeteer/puppeteer/issues/13155) - Original bug report
-- [Puppeteer PR #13156](https://github.com/puppeteer/puppeteer/pull/13156) - CDP-only fix (October 2024)
-- [WebDriver BiDi Specification](https://w3c.github.io/webdriver-bidi/) - browsingContext module
-
-#### Test Status
-
-```ruby
-it 'should handle shadow roots', pending: 'BiDi protocol limitation: no DOM.getFrameOwner equivalent' do
-  # ...
-end
-```
-
-This is a **protocol limitation**, not an implementation bug in this library.
-
-## Commit Reference
-
-See commit: "Refactor Frame to use parent-based architecture following Puppeteer"