puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta2

data/CLAUDE/porting_puppeteer.md

@@ -1,234 +0,0 @@
-# Porting Puppeteer to Ruby
-
-Best practices for implementing Puppeteer features in puppeteer-bidi.
-
-## 1. Reference Implementation First
-
-**Always consult the official Puppeteer implementation before implementing features:**
-
-- **TypeScript source files**:
-  - `packages/puppeteer-core/src/bidi/Page.ts` - High-level Page API
-  - `packages/puppeteer-core/src/bidi/BrowsingContext.ts` - Core BiDi context
-  - `packages/puppeteer-core/src/api/Page.ts` - Common Page interface
-
-- **Test files**:
-  - `test/src/screenshot.spec.ts` - Screenshot test suite
-  - `test/golden-firefox/` - Golden images for visual regression testing
-
-**Example workflow:**
-
-```ruby
-# 1. Read Puppeteer's TypeScript implementation
-# 2. Understand the BiDi protocol calls being made
-# 3. Implement Ruby equivalent with same logic flow
-# 4. Port corresponding test cases
-```
-
-## 2. Test Infrastructure Setup
-
-**Use async-http for test servers** (lightweight + Async-friendly):
-
-```ruby
-# spec/support/test_server.rb
-endpoint = Async::HTTP::Endpoint.parse("http://127.0.0.1:#{@port}")
-
-server = Async::HTTP::Server.for(endpoint) do |request|
-  if handler = lookup_route(request.path)
-    notify_request(request.path)
-    respond_with_handler(handler, request)
-  else
-    serve_static_asset(request)
-  end
-end
-
-server.run
-```
-
-**Helper pattern for integration tests:**
-
-```ruby
-# Optimized helper - reuses shared browser, creates new page per test
-def with_test_state
-  page = $shared_browser.new_page
-  context = $shared_browser.default_browser_context
-
-  begin
-    yield(page: page, server: $shared_test_server, browser: $shared_browser, context: context)
-  ensure
-    page.close unless page.closed?
-  end
-end
-```
-
-## 3. BiDi Protocol Data Deserialization
-
-**BiDi returns values in special format - always deserialize:**
-
-```ruby
-# BiDi response format:
-# [["width", {"type" => "number", "value" => 500}],
-#  ["height", {"type" => "number", "value" => 1000}]]
-
-def deserialize_result(result)
-  value = result['value']
-  return value unless value.is_a?(Array)
-
-  # Convert to Ruby Hash
-  if value.all? { |item| item.is_a?(Array) && item.length == 2 }
-    value.each_with_object({}) do |(key, val), hash|
-      hash[key] = deserialize_value(val)
-    end
-  else
-    value
-  end
-end
-
-def deserialize_value(val)
-  case val['type']
-  when 'number' then val['value']
-  when 'string' then val['value']
-  when 'boolean' then val['value']
-  when 'undefined', 'null' then nil
-  else val['value']
-  end
-end
-```
-
-## 4. Implementing Puppeteer-Compatible APIs
-
-**Follow Puppeteer's exact logic flow:**
-
-Example: `fullPage` screenshot implementation
-
-```ruby
-# From Puppeteer's Page.ts:
-# if (options.fullPage) {
-#   if (!options.captureBeyondViewport) {
-#     // Resize viewport to full page
-#   }
-# } else {
-#   options.captureBeyondViewport = false;
-# }
-
-if full_page
-  unless capture_beyond_viewport
-    scroll_dimensions = evaluate(...)
-    set_viewport(scroll_dimensions)
-    begin
-      data = capture_screenshot(origin: 'viewport')
-    ensure
-      set_viewport(original_viewport)  # Always restore
-    end
-  else
-    options[:origin] = 'document'
-  end
-elsif !clip
-  capture_beyond_viewport = false  # Match Puppeteer behavior
-end
-```
-
-**Key principles:**
-
-- Use `begin/ensure` blocks for cleanup (viewport restoration, etc.)
-- Match Puppeteer's parameter defaults exactly
-- Follow the same conditional logic order
-
-## 5. Layer Architecture
-
-**Maintain clear separation:**
-
-```
-High-level API (lib/puppeteer/bidi/)
-├── Browser        - User-facing browser interface
-├── BrowserContext - Session management
-└── Page           - Page automation API
-
-Core Layer (lib/puppeteer/bidi/core/)
-├── Session        - BiDi session management
-├── Browser        - Low-level browser operations
-├── UserContext    - BiDi user context
-└── BrowsingContext - BiDi browsing context (tab/frame)
-```
-
-## 6. Setting Page Content
-
-**Use data URLs with base64 encoding:**
-
-```ruby
-def set_content(html, wait_until: 'load')
-  # Encode HTML in base64 to avoid URL encoding issues
-  encoded = Base64.strict_encode64(html)
-  data_url = "data:text/html;base64,#{encoded}"
-  goto(data_url, wait_until: wait_until)
-end
-```
-
-**Why base64:**
-
-- Avoids URL encoding issues with special characters
-- Handles multi-byte characters correctly
-- Standard approach in browser automation tools
-
-## 7. Viewport Restoration
-
-**Always restore viewport after temporary changes:**
-
-```ruby
-# Save current viewport (may be nil)
-original_viewport = viewport
-
-# If no viewport set, save window size
-unless original_viewport
-  original_size = evaluate('({ width: window.innerWidth, height: window.innerHeight })')
-  original_viewport = { width: original_size['width'].to_i, height: original_size['height'].to_i }
-end
-
-# Change viewport temporarily
-set_viewport(width: new_width, height: new_height)
-
-begin
-  # Do work
-ensure
-  # Always restore
-  set_viewport(**original_viewport) if original_viewport
-end
-```
-
-## 8. Test Assets Policy
-
-**CRITICAL**: Always use Puppeteer's official test assets without modification.
-
-- **Source**: https://github.com/puppeteer/puppeteer/tree/main/test/assets
-- **Rule**: Never modify test asset files (HTML, CSS, images) in `spec/assets/`
-- **Verification**: Before creating PR, verify all `spec/assets/` files match Puppeteer's official versions
-
-```bash
-# During development - OK to experiment
-vim spec/assets/test.html  # Temporary modification for debugging
-
-# Before PR - MUST revert to official
-curl -sL https://raw.githubusercontent.com/puppeteer/puppeteer/main/test/assets/test.html \
-  -o spec/assets/test.html
-```
-
-**Why this matters**: Test assets are designed to test specific edge cases (rotated elements, complex layouts, etc.). Using simplified versions defeats the purpose of these tests.
-
-## 9. API Coverage Update
-
-**IMPORTANT**: When implementing new Puppeteer API methods, update `API_COVERAGE.md`:
-
-1. Find the corresponding entry in the table (e.g., `Browser.userAgent`, `Page.setUserAgent`)
-2. Change the status from `❌` to `✅`
-3. Update the coverage count at the top of the file
-
-```markdown
-# Before
-- Coverage: `156/274` (`56.93%`)
-| `Browser.userAgent` | `Puppeteer::Bidi::Browser#user_agent` | ❌ |
-
-# After (implemented 2 new methods: 156 + 2 = 158)
-- Coverage: `158/274` (`57.66%`)
-| `Browser.userAgent` | `Puppeteer::Bidi::Browser#user_agent` | ✅ |
-```
-
-**CI will fail** if API_COVERAGE.md is not updated when new methods are implemented. The API Coverage check compares implemented methods against the coverage file.

data/CLAUDE/query_handler.md

@@ -1,194 +0,0 @@
-# QueryHandler Implementation
-
-The QueryHandler system provides extensible selector handling for CSS, XPath, text, and other selector types.
-
-## Architecture
-
-```
-QueryHandler (singleton)
-├── get_query_handler_and_selector(selector)
-│   └── Returns: { updated_selector, polling, query_handler }
-
-BaseQueryHandler
-├── run_query_one(element, selector)  → ElementHandle | nil
-├── run_query_all(element, selector)  → Array<ElementHandle>
-└── wait_for(element_or_frame, selector, options)
-
-Implementations:
-├── CSSQueryHandler   - Default, uses cssQuerySelector/cssQuerySelectorAll
-├── XPathQueryHandler - xpath/ prefix, uses xpathQuerySelectorAll
-└── TextQueryHandler  - text/ prefix, uses textQuerySelectorAll
-```
-
-## Selector Prefixes
-
-| Prefix    | Handler            | Example                     |
-| --------- | ------------------ | --------------------------- |
-| (none)    | CSSQueryHandler    | `div.foo`, `#id`            |
-| `xpath/`  | XPathQueryHandler  | `xpath/html/body/div`       |
-| `text/`   | TextQueryHandler   | `text/Hello World`          |
-| `aria/`   | ARIAQueryHandler   | `aria/Submit[role="button"]`|
-| `pierce/` | PierceQueryHandler | `pierce/.shadow-element`    |
-
-## Implementation Pattern
-
-All query handlers follow the same pattern: override `query_one_script`, `query_all_script`, and `wait_for_selector_script` to define the JavaScript that runs in the browser.
-
-```ruby
-class CSSQueryHandler < BaseQueryHandler
-  private
-
-  def query_one_script
-    <<~JAVASCRIPT
-    (PuppeteerUtil, element, selector) => {
-      return PuppeteerUtil.cssQuerySelector(element, selector);
-    }
-    JAVASCRIPT
-  end
-
-  def query_all_script
-    <<~JAVASCRIPT
-    async (PuppeteerUtil, element, selector) => {
-      return [...PuppeteerUtil.cssQuerySelectorAll(element, selector)];
-    }
-    JAVASCRIPT
-  end
-
-  def wait_for_selector_script
-    <<~JAVASCRIPT
-    (PuppeteerUtil, selector, root, visibility) => {
-      const element = PuppeteerUtil.cssQuerySelector(root || document, selector);
-      return PuppeteerUtil.checkVisibility(element, visibility === null ? undefined : visibility);
-    }
-    JAVASCRIPT
-  end
-end
-```
-
-## TextQueryHandler - Special Case
-
-`textQuerySelectorAll` cannot be extracted via `toString()` because it references helper functions (`f`, `m`, `d`) that are only available within the PuppeteerUtil closure. So TextQueryHandler uses a different pattern: call `textQuerySelectorAll` directly from PuppeteerUtil instead of recreating the function.
-
-```ruby
-class TextQueryHandler < BaseQueryHandler
-  private
-
-  def query_one_script
-    <<~JAVASCRIPT
-    (PuppeteerUtil, element, selector) => {
-      for (const result of PuppeteerUtil.textQuerySelectorAll(element, selector)) {
-        return result;
-      }
-      return null;
-    }
-    JAVASCRIPT
-  end
-
-  def query_all_script
-    <<~JAVASCRIPT
-    async (PuppeteerUtil, element, selector) => {
-      return [...PuppeteerUtil.textQuerySelectorAll(element, selector)];
-    }
-    JAVASCRIPT
-  end
-end
-```
-
-## Handle Adoption Pattern
-
-After navigation, the sandbox realm is destroyed and `puppeteer_util` handles become stale. The solution is to adopt the element into the isolated realm BEFORE calling any query methods:
-
-```ruby
-def run_query_one(element, selector)
-  realm = element.frame.isolated_realm
-
-  # Adopt the element into the isolated realm first.
-  # This ensures the realm is valid and triggers puppeteer_util reset if needed
-  # after navigation (mirrors Puppeteer's @bindIsolatedHandle decorator pattern).
-  adopted_element = realm.adopt_handle(element)
-
-  result = realm.call_function(
-    query_one_script,
-    false,
-    arguments: [
-      Serializer.serialize(realm.puppeteer_util_lazy_arg),
-      adopted_element.remote_value,
-      Serializer.serialize(selector)
-    ]
-  )
-
-  # ... handle result ...
-ensure
-  adopted_element&.dispose
-end
-```
-
-**Why this matters:**
-
-1. After navigation, sandbox realm is destroyed
-2. `:updated` event that resets `puppeteer_util` isn't fired until we call INTO the sandbox
-3. Calling `adopt_handle` first ensures the realm exists and is valid
-4. Then `puppeteer_util` will be fresh (re-evaluated if realm was recreated)
-
-## Debugging
-
-Use `DEBUG_BIDI_COMMAND=1` to see protocol messages:
-
-```bash
-DEBUG_BIDI_COMMAND=1 bundle exec rspec spec/integration/queryhandler_spec.rb:8
-```
-
-This shows:
-1. PuppeteerUtil being evaluated in sandbox
-2. The query function being called with arguments
-3. The result being returned
-
-## Adding New Query Handlers
-
-1. Create a new class extending `BaseQueryHandler`
-2. Override `query_one_script`, `query_all_script`, and `wait_for_selector_script`
-3. Register in `BUILTIN_QUERY_HANDLERS` constant
-4. The script receives `(PuppeteerUtil, element, selector)` as arguments
-5. Return the element(s) found or null/empty array
-
-```ruby
-class MyQueryHandler < BaseQueryHandler
-  private
-
-  def query_one_script
-    <<~JAVASCRIPT
-    (PuppeteerUtil, element, selector) => {
-      // Use PuppeteerUtil.myQuerySelector if available
-      // Or implement custom logic
-      return element.querySelector(selector);
-    }
-    JAVASCRIPT
-  end
-
-  def query_all_script
-    <<~JAVASCRIPT
-    async (PuppeteerUtil, element, selector) => {
-      return [...element.querySelectorAll(selector)];
-    }
-    JAVASCRIPT
-  end
-
-  def wait_for_selector_script
-    <<~JAVASCRIPT
-    (PuppeteerUtil, selector, root, visibility) => {
-      const element = (root || document).querySelector(selector);
-      return PuppeteerUtil.checkVisibility(element, visibility === null ? undefined : visibility);
-    }
-    JAVASCRIPT
-  end
-end
-```
-
-## Test Coverage
-
-Tests are in `spec/integration/queryhandler_spec.rb`:
-
-- Text selectors: 12 tests (query_selector, query_selector_all, shadow DOM piercing, etc.)
-- XPath selectors: 6 tests (in Page and ElementHandle)
-
-Tests ported from Puppeteer's `test/src/queryhandler.spec.ts`.

data/CLAUDE/reactor_runner.md

@@ -1,111 +0,0 @@
-# ReactorRunner - Using Browser Outside Sync Blocks
-
-## Problem
-
-The socketry/async library requires all async operations to run inside a `Sync do ... end` block. However, some use cases cannot wrap their entire code in a Sync block:
-
-```ruby
-# This pattern doesn't work with plain async:
-browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
-at_exit { browser.close }  # Called outside any Sync block!
-
-Sync do
-  page = browser.new_page
-  page.goto("https://example.com")
-end
-```
-
-The `at_exit` hook runs after the Sync block has finished, so `browser.close` would fail.
-
-## Solution: ReactorRunner
-
-`ReactorRunner` creates a dedicated Async reactor in a background thread and provides a way to execute code within that reactor from any thread.
-
-### How It Works
-
-1. **Background Thread with Reactor**: ReactorRunner spawns a new thread that runs `Sync do ... end` with an `Async::Queue` for receiving jobs
-2. **Proxy Pattern**: Returns a `Proxy` object that wraps the real Browser and forwards all method calls through the ReactorRunner
-3. **Automatic Detection**: `launch_browser_instance` and `connect_to_browser_instance` check `Async::Task.current` to decide whether to use ReactorRunner
-
-### Architecture
-
-```
-Main Thread                     Background Thread (ReactorRunner)
-    │                                    │
-    │  launch_browser_instance()         │
-    │  ─────────────────────────────────>│ Sync do
-    │                                    │   Browser.launch()
-    │  <─────────────────────────────────│   (browser created)
-    │  returns Proxy                     │
-    │                                    │
-    │  proxy.new_page()                  │
-    │  ─────────────────────────────────>│   browser.new_page()
-    │  <─────────────────────────────────│   (returns page)
-    │                                    │
-    │  at_exit { proxy.close }           │
-    │  ─────────────────────────────────>│   browser.close()
-    │                                    │ end
-    │                                    │
-```
-
-### Key Components
-
-#### ReactorRunner
-
-- Creates background thread with `Sync` reactor
-- Uses `Async::Queue` to receive jobs from other threads
-- `sync(&block)` method executes block in reactor and returns result
-- Handles proper cleanup when closed
-
-#### ReactorRunner::Proxy
-
-- Extends `SimpleDelegator` for transparent method forwarding
-- Wraps/unwraps return values (e.g., Page becomes Proxy too)
-- `owns_runner: true` means closing browser also closes the ReactorRunner
-- Handles edge cases like calling `close` after runner is already closed
-
-### Usage Patterns
-
-#### Pattern 1: Block-based (Recommended)
-
-```ruby
-Puppeteer::Bidi.launch do |browser|
-  page = browser.new_page
-  # ... use browser
-end  # automatically closed
-```
-
-#### Pattern 2: Instance with at_exit
-
-```ruby
-browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
-at_exit { browser.close }
-
-Sync do
-  page = browser.new_page
-  page.goto("https://example.com")
-end
-```
-
-#### Pattern 3: Inside existing Async context
-
-```ruby
-Sync do
-  # No ReactorRunner used - browser is returned directly
-  browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
-  page = browser.new_page
-  # ...
-  browser.close
-end
-```
-
-### Implementation Notes
-
-1. **Thread Safety**: `Async::Queue` handles cross-thread communication safely
-2. **Proxyable Check**: Only `Puppeteer::Bidi::*` objects (excluding Core layer) are wrapped in Proxy
-3. **Error Handling**: Errors in reactor are propagated back to calling thread via `Async::Promise`
-4. **Type Annotations**: Return type is `Browser` (Proxy is an internal detail)
-
-### Reference
-
-This pattern is inspired by [async-webdriver](https://github.com/socketry/async-webdriver) by Samuel Williams (author of socketry/async).