puppeteer-bidi 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59931b8cfbf15b649c6d4202eed284ab7c5e7f50dfbbbbeae1ec0e15423aa9bf
-  data.tar.gz: 21eed43df8ece3625be9a701730d5f736a6f4ba02a894631af957bf61b1b5e7c
+  metadata.gz: 7242d594b90af9ed2739ef56e234d3d26805cf19d688212e9b0b68ad823a96c2
+  data.tar.gz: 6bca1fe1f82165851376466367cee72ec59f10fabb6b2970a70bcffde5ef42b6
 SHA512:
-  metadata.gz: 4e677ea4db58824f6b25ce4e78c587a1e8cae7dfdb9881a4eb0e47f562fe4f8d9c67ead75e9b93b3a870722856097997000d873067fc6d28e89e114afe225c19
-  data.tar.gz: 54b4d4dc626bb50f72871e8ff560321c0345f31f9ce60f0409cbb0afe3145f379f863180412497b3e5f830fe758faacdeacf573c58a71e09223def214991652c
+  metadata.gz: 1c7f73fa6f5351d1e1e12a87388e56c05faa11286bf724e400ec97e19092a81a6e22c6718970c028305717afdaf560ddd16dbfa6f499b5dbc28313b8b55d3347
+  data.tar.gz: ad2cc2f58a6da1d6bff87bde5eab283536f46aa160bbc3ac197c6574f9fd5f35950ca47331c9363feea4a93eaa8af76322f38b123e31d9212206d01e01d2d9d4

data/API_COVERAGE.md

@@ -2,7 +2,7 @@
 
 - Puppeteer commit: `7d750c25cb29764f2fb31cb90b750a8eec350199`
 - Generated by: `development/generate_api_coverage.rb`
-- Coverage: `174/274` (`63.50%`)
+- Coverage: `182/265` (`68.68%`)
 
 ## Browser (Puppeteer::Bidi::Browser)
 
@@ -111,7 +111,7 @@
 | `Frame.addStyleTag` | `Puppeteer::Bidi::Frame#add_style_tag` | ❌ |
 | `Frame.childFrames` | `Puppeteer::Bidi::Frame#child_frames` | ✅ |
 | `Frame.click` | `Puppeteer::Bidi::Frame#click` | ✅ |
-| `Frame.content` | `Puppeteer::Bidi::Frame#content` | ❌ |
+| `Frame.content` | `Puppeteer::Bidi::Frame#content` | ✅ |
 | `Frame.evaluate` | `Puppeteer::Bidi::Frame#evaluate` | ✅ |
 | `Frame.evaluateHandle` | `Puppeteer::Bidi::Frame#evaluate_handle` | ✅ |
 | `Frame.focus` | `Puppeteer::Bidi::Frame#focus` | ❌ |
@@ -254,12 +254,12 @@
 | `Page.emulateVisionDeficiency` | `Puppeteer::Bidi::Page#emulate_vision_deficiency` | ❌ |
 | `Page.evaluate` | `Puppeteer::Bidi::Page#evaluate` | ✅ |
 | `Page.evaluateHandle` | `Puppeteer::Bidi::Page#evaluate_handle` | ✅ |
-| `Page.evaluateOnNewDocument` | `Puppeteer::Bidi::Page#evaluate_on_new_document` | ❌ |
-| `Page.exposeFunction` | `Puppeteer::Bidi::Page#expose_function` | ❌ |
+| `Page.evaluateOnNewDocument` | `Puppeteer::Bidi::Page#evaluate_on_new_document` | ✅ |
+| `Page.exposeFunction` | `Puppeteer::Bidi::Page#expose_function` | ✅ |
 | `Page.focus` | `Puppeteer::Bidi::Page#focus` | ✅ |
 | `Page.frames` | `Puppeteer::Bidi::Page#frames` | ✅ |
-| `Page.getDefaultNavigationTimeout` | `Puppeteer::Bidi::Page#get_default_navigation_timeout` | ❌ |
-| `Page.getDefaultTimeout` | `Puppeteer::Bidi::Page#get_default_timeout` | ❌ |
+| `Page.getDefaultNavigationTimeout` | `Puppeteer::Bidi::Page#get_default_navigation_timeout` | ✅ |
+| `Page.getDefaultTimeout` | `Puppeteer::Bidi::Page#get_default_timeout` | ✅ |
 | `Page.goBack` | `Puppeteer::Bidi::Page#go_back` | ✅ |
 | `Page.goForward` | `Puppeteer::Bidi::Page#go_forward` | ✅ |
 | `Page.goto` | `Puppeteer::Bidi::Page#goto` | ✅ |
@@ -275,8 +275,8 @@
 | `Page.pdf` | `Puppeteer::Bidi::Page#pdf` | ❌ |
 | `Page.queryObjects` | `Puppeteer::Bidi::Page#query_objects` | ❌ |
 | `Page.reload` | `Puppeteer::Bidi::Page#reload` | ✅ |
-| `Page.removeExposedFunction` | `Puppeteer::Bidi::Page#remove_exposed_function` | ❌ |
-| `Page.removeScriptToEvaluateOnNewDocument` | `Puppeteer::Bidi::Page#remove_script_to_evaluate_on_new_document` | ❌ |
+| `Page.removeExposedFunction` | `Puppeteer::Bidi::Page#remove_exposed_function` | ✅ |
+| `Page.removeScriptToEvaluateOnNewDocument` | `Puppeteer::Bidi::Page#remove_script_to_evaluate_on_new_document` | ✅ |
 | `Page.resize` | `Puppeteer::Bidi::Page#resize` | ❌ |
 | `Page.screencast` | `Puppeteer::Bidi::Page#screencast` | ❌ |
 | `Page.screenshot` | `Puppeteer::Bidi::Page#screenshot` | ✅ |
@@ -286,7 +286,7 @@
 | `Page.setCacheEnabled` | `Puppeteer::Bidi::Page#set_cache_enabled` | ✅ |
 | `Page.setContent` | `Puppeteer::Bidi::Page#set_content` | ✅ |
 | `Page.setCookie` | `Puppeteer::Bidi::Page#set_cookie` | ✅ |
-| `Page.setDefaultNavigationTimeout` | `Puppeteer::Bidi::Page#set_default_navigation_timeout` | ❌ |
+| `Page.setDefaultNavigationTimeout` | `Puppeteer::Bidi::Page#set_default_navigation_timeout` | ✅ |
 | `Page.setDefaultTimeout` | `Puppeteer::Bidi::Page#set_default_timeout` | ✅ |
 | `Page.setDragInterception` | `Puppeteer::Bidi::Page#set_drag_interception` | ❌ |
 | `Page.setExtraHTTPHeaders` | `Puppeteer::Bidi::Page#set_extra_http_headers` | ✅ |
@@ -329,17 +329,3 @@
 | `PuppeteerNode.trimCache` | `Puppeteer::Bidi.trim_cache` | ❌ |
 | `Puppeteer.unregisterCustomQueryHandler` | `Puppeteer::Bidi.unregister_custom_query_handler` | ❌ |
 
-## Target (Puppeteer::Bidi::Target)
-
-| Node.js | Ruby | Supported |
-| --- | --- | :---: |
-| `Target.asPage` | `Puppeteer::Bidi::Target#as_page` | ❌ |
-| `Target.browser` | `Puppeteer::Bidi::Target#browser` | ❌ |
-| `Target.browserContext` | `Puppeteer::Bidi::Target#browser_context` | ❌ |
-| `Target.createCDPSession` | `Puppeteer::Bidi::Target#create_cdp_session` | ❌ |
-| `Target.opener` | `Puppeteer::Bidi::Target#opener` | ❌ |
-| `Target.page` | `Puppeteer::Bidi::Target#page` | ❌ |
-| `Target.type` | `Puppeteer::Bidi::Target#type` | ❌ |
-| `Target.url` | `Puppeteer::Bidi::Target#url` | ❌ |
-| `Target.worker` | `Puppeteer::Bidi::Target#worker` | ❌ |
-

data/CLAUDE/expose_function_implementation.md

@@ -0,0 +1,271 @@
+# 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.md

@@ -201,6 +201,7 @@ See the [CLAUDE/](CLAUDE/) directory for detailed implementation guides:
 - **[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

data/development/generate_api_coverage.rb

@@ -211,9 +211,9 @@ NODE_OWNER_ALIASES = {
   "HTTPResponse" => "HTTPResponse",
   "filechooser" => "FileChooser",
   "fileChooser" => "FileChooser",
-  "FileChooser" => "FileChooser",
-  "target" => "Target",
-  "Target" => "Target"
+  "FileChooser" => "FileChooser"
+  # Note: Target is excluded from coverage tracking due to significant
+  # implementation differences between Node.js and Ruby versions.
 }.freeze
 
 def canonical_node_owner(owner)
@@ -232,8 +232,9 @@ RUBY_OWNER_CONSTANTS = {
   "Mouse" => "Puppeteer::Bidi::Mouse",
   "HTTPRequest" => "Puppeteer::Bidi::HTTPRequest",
   "HTTPResponse" => "Puppeteer::Bidi::HTTPResponse",
-  "FileChooser" => "Puppeteer::Bidi::FileChooser",
-  "Target" => "Puppeteer::Bidi::Target"
+  "FileChooser" => "Puppeteer::Bidi::FileChooser"
+  # Note: Target is excluded from coverage tracking due to significant
+  # implementation differences between Node.js and Ruby versions.
 }.freeze
 
 def safe_constantize(name)

data/lib/puppeteer/bidi/async_utils.rb

@@ -28,29 +28,45 @@ module Puppeteer
       # @yield [async_task] Execute a task within the timeout, optionally receiving Async::Task
       # @return [Async::Task] Async task that resolves/rejects once the operation completes
       def async_timeout(timeout_ms, task = nil, &block)
-        timeout_seconds = timeout_ms / 1000.0
-
         if task
-          Async do |async_task|
-            async_task.with_timeout(timeout_seconds) do
+          return Async do |async_task|
+            if timeout_ms == 0
               if task.is_a?(Proc)
                 args = task.arity.positive? ? [async_task] : []
                 task.call(*args)
               else
                 await(task)
               end
+            else
+              timeout_seconds = timeout_ms / 1000.0
+              async_task.with_timeout(timeout_seconds) do
+                if task.is_a?(Proc)
+                  args = task.arity.positive? ? [async_task] : []
+                  task.call(*args)
+                else
+                  await(task)
+                end
+              end
             end
           end
-        elsif block
-          Async do |async_task|
-            async_task.with_timeout(timeout_seconds) do
+        end
+
+        if block
+          return Async do |async_task|
+            if timeout_ms == 0
               args = block.arity.positive? ? [async_task] : []
               await(block.call(*args))
+            else
+              timeout_seconds = timeout_ms / 1000.0
+              async_task.with_timeout(timeout_seconds) do
+                args = block.arity.positive? ? [async_task] : []
+                await(block.call(*args))
+              end
             end
           end
-        else
-          raise ArgumentError, 'AsyncUtils.async_timeout requires a task or block'
         end
+
+        raise ArgumentError, 'AsyncUtils.async_timeout requires a task or block'
       end
 
       def promise_all(*tasks)

data/lib/puppeteer/bidi/browser.rb

@@ -91,7 +91,8 @@ module Puppeteer
 
         # Start transport connection in background thread with Sync reactor
         # Sync is the preferred way to run async code at the top level
-        AsyncUtils.async_timeout((timeout || 30) * 1000, transport.connect).wait
+        timeout_ms = ((timeout || 30) * 1000).to_i
+        AsyncUtils.async_timeout(timeout_ms, transport.connect).wait
 
         connection = Connection.new(transport)
 

data/lib/puppeteer/bidi/core/browser.rb

@@ -81,6 +81,9 @@ module Puppeteer
           if options[:contexts]
             params[:contexts] = options[:contexts].map(&:id)
           end
+          if options.key?(:arguments) || options.key?("arguments")
+            params[:arguments] = options[:arguments] || options["arguments"]
+          end
           params[:sandbox] = options[:sandbox] if options[:sandbox]
 
           Async do

data/lib/puppeteer/bidi/core/session.rb

@@ -140,6 +140,7 @@ module Puppeteer
             'network.authRequired',
             'script.realmCreated',
             'script.realmDestroyed',
+            'script.message',
             'log.entryAdded',
             'input.fileDialogOpened',
           ]