puppeteer-bidi 0.0.3.beta1 → 0.0.3.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56fae0e1e155b3fe5bcce854ac7ff615c86af3815b0b9b186bf97fa905421a00
-  data.tar.gz: 3b13efc226d2a7d84da91056679707ff3d0b3a5d511f2211c9cfc4da1c0fef23
+  metadata.gz: eb435eba199162f3270ff09d0efeaf728935717f0c690a0549f176f1be06e072
+  data.tar.gz: 7a39e4c65471997c4d37f4558459121a9370769dbf341b7f45b6d2441175b60e
 SHA512:
-  metadata.gz: abd414f479202d7f642c6f3b4b0ce3db308a18c5116bd4545483b88cf03193cdfb49e41931e596b3cb99c7699ac8f6773ba4ffff7bf160dd8f0a165745f6d0cc
-  data.tar.gz: 62c840fafb7844a586286eb5776b58763e2d7d3547194233e74e75d997aeb239d875fa263b20dbdfe0a326bc2608748c5c4cc479148299096a6b11f43d116cca
+  metadata.gz: 1d9b44c59dda746bae25de8ad9e37c9576867fd5f39b434e39e0ea2cb1ce30d05e943496d787e9cc254d5747af1ce8514818dce67c5778861345617788c2b6af
+  data.tar.gz: 5d80cc021677292638eb0103cf7aca8f9c87309fcb858425360b1ac6f937f2d5d1e5386c5b30e738589fc787ab7f609a271af18d682ac9452b95ae5fec25d765

data/lib/puppeteer/bidi/browser.rb

@@ -64,6 +64,8 @@ module Puppeteer
         @browser_contexts = {
           default_user_context.id => @default_browser_context
         }
+
+        register_exit_cleanup if @launcher
       end
 
       # Launch a new Firefox browser instance
@@ -342,6 +344,19 @@ module Puppeteer
 
       private
 
+      # @rbs return: void
+      def register_exit_cleanup
+        at_exit do
+          next if @closed || @disconnected
+
+          begin
+            @launcher&.kill
+          rescue StandardError => e
+            debug_error(e)
+          end
+        end
+      end
+
       def debug_error(error)
         return unless ENV['DEBUG_BIDI_COMMAND']
 

data/lib/puppeteer/bidi/reactor_runner.rb

@@ -116,7 +116,18 @@ module Puppeteer
           raise Error, "ReactorRunner is closed"
         end
 
-        promise.wait
+        # Ruby 4.0: Async::Promise#wait can wake spuriously; retry until resolved.
+        loop do
+          begin
+            return promise.wait
+          rescue TypeError => e
+            raise unless e.message == "exception class/object expected"
+            next unless promise.resolved?
+            value = promise.value
+            raise value if value.is_a?(Exception)
+            return value
+          end
+        end
       end
 
       # @rbs return: void

data/lib/puppeteer/bidi/transport.rb

@@ -108,8 +108,11 @@ module Puppeteer
             warn "Failed to parse BiDi message: #{e.message}"
           end
         end
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
+        # Connection closed - this is expected during shutdown, no need to warn
       rescue => e
-        warn "Transport receive error: #{e.message}"
+        # Only warn for unexpected errors if we weren't intentionally closed
+        warn "Transport receive error: #{e.message}" unless @closed
       ensure
         close unless @closed
       end

data/lib/puppeteer/bidi/version.rb

@@ -2,6 +2,6 @@
 
 module Puppeteer
   module Bidi
-    VERSION = "0.0.3.beta1"
+    VERSION = "0.0.3.beta3"
   end
 end

data/sig/_external.rbs

@@ -33,6 +33,7 @@ module Async
     def resolve: (T) -> void
     def reject: (Exception) -> void
     def resolved?: () -> bool
+    def value: () -> T?
   end
 
   class TimeoutError < StandardError

data/sig/puppeteer/bidi/browser.rbs

@@ -118,6 +118,9 @@ module Puppeteer
 
       private
 
+      # @rbs return: void
+      def register_exit_cleanup: () -> void
+
       def debug_error: (untyped error) -> untyped
 
       # @rbs &block: (BrowserTarget | PageTarget | FrameTarget) -> void -- Block to yield each target to

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppeteer-bidi
 version: !ruby/object:Gem::Version
-  version: 0.0.3.beta1
+  version: 0.0.3.beta3
 platform: ruby
 authors:
 - YusukeIwaki
@@ -77,38 +77,12 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
-- AGENTS.md
 - API_COVERAGE.md
-- CLAUDE.md
-- CLAUDE/README.md
-- CLAUDE/async_programming.md
-- CLAUDE/click_implementation.md
-- CLAUDE/core_layer_gotchas.md
-- CLAUDE/error_handling.md
-- CLAUDE/expose_function_implementation.md
-- CLAUDE/file_chooser.md
-- CLAUDE/frame_architecture.md
-- CLAUDE/javascript_evaluation.md
-- CLAUDE/jshandle_implementation.md
-- CLAUDE/keyboard_implementation.md
-- CLAUDE/mouse_implementation.md
-- CLAUDE/navigation_waiting.md
-- CLAUDE/porting_puppeteer.md
-- CLAUDE/query_handler.md
-- CLAUDE/reactor_runner.md
-- CLAUDE/rspec_pending_vs_skip.md
-- CLAUDE/selector_evaluation.md
-- CLAUDE/test_server_routes.md
-- CLAUDE/testing_strategy.md
-- CLAUDE/two_layer_architecture.md
-- CLAUDE/wrapped_element_click.md
 - DEVELOPMENT.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - Steepfile
-- development/generate_api_coverage.rb
-- development/puppeteer_revision.txt
 - lib/puppeteer/bidi.rb
 - lib/puppeteer/bidi/async_utils.rb
 - lib/puppeteer/bidi/browser.rb

data/AGENTS.md

@@ -1,44 +0,0 @@
-# Repository Guidelines
-
-## Start Here (Project-Specific Guidance)
-
-- Read `CLAUDE.md` and `CLAUDE/` first; they define the core async architecture, porting workflow, and testing strategy.
-- Ruby: requires `>= 3.2` (CI covers 3.2–3.4). Prefer a version manager (`rbenv`, `asdf`, etc.) over system Ruby.
-
-## Project Structure & Module Organization
-
-- `lib/puppeteer/bidi/`: user-facing API (sync, calls `.wait`).
-- `lib/puppeteer/bidi/core/`: low-level BiDi core (async, returns `Async::Task`).
-- `spec/integration/`: browser-driven specs; fixtures in `spec/assets/`.
-
-## Build, Test, and Development Commands
-
-- See `DEVELOPMENT.md` for the full command list and environment variables.
-- Run RSpec via `rbenv exec bundle exec rspec ...` when using rbenv.
-
-## Coding Style & Naming Conventions
-
-- Ruby: 2-space indent, double-quoted strings, ~120 char lines; follow RuboCop (`.rubocop.yml`).
-- BiDi-only: do not introduce CDP-related ports.
-- Async: core returns `Async::Task`; upper layer must call `.wait` on every core call (see `CLAUDE/two_layer_architecture.md`).
-- Reviews to watch: WS messages can be handled out-of-order; “wait for event” code must not hang (register listeners before commands, handle “already happened”, cancel on errors).
-
-## Testing Guidelines
-
-- Prefer `spec/integration/` and the shared-browser `with_test_state` pattern (see `CLAUDE/testing_strategy.md`).
-- Use `pending` for browser limitations vs `skip` for unimplemented features.
-
-## Commit & Pull Request Guidelines
-
-- See `DEVELOPMENT.md` for commit, PR, and release conventions.
-
-## Agent Notes (Porting/Review)
-
-- When porting from upstream TS, mirror optional vs default fields: defaults are for validation, and optional keys should be omitted from payloads unless explicitly provided.
-- Match upstream error messages as closely as possible (including interpolated values) so tests align with Puppeteer.
-- In core layer option checks, use key presence (`options.key?`) when upstream uses `'in'` to distinguish "missing" from `nil`.
-- During reviews, compare both implementation (`packages/puppeteer-core/src/bidi/*.ts`) and tests (`test/src/page.spec.ts`) to catch behavior parity gaps.
-
-## Security & Configuration Tips
-
-- Do not commit credentials; review network-fetched changes (e.g., `scripts/update_injected_source.rb` → `lib/puppeteer/bidi/injected.js`) carefully.

data/CLAUDE/README.md

@@ -1,158 +0,0 @@
-# Detailed Implementation Documentation
-
-This directory contains detailed documentation for specific implementation topics in puppeteer-bidi.
-
-## Quick Reference
-
-| Document | Topic | Key Takeaway |
-|----------|-------|--------------|
-| [async_programming.md](async_programming.md) | Fiber-based async | Use Async, NOT concurrent-ruby |
-| [two_layer_architecture.md](two_layer_architecture.md) | Core vs Upper layer | Always call `.wait` on Core methods |
-| [porting_puppeteer.md](porting_puppeteer.md) | Implementing features | Study TypeScript first, port tests |
-| [query_handler.md](query_handler.md) | Selector handling | Override script methods, use PuppeteerUtil |
-| [javascript_evaluation.md](javascript_evaluation.md) | JS evaluation | IIFE detection is critical |
-| [jshandle_implementation.md](jshandle_implementation.md) | Handle management | resultOwnership must be 'root' |
-| [selector_evaluation.md](selector_evaluation.md) | Selector methods | Use `eval_on_selector` not `$eval` |
-| [error_handling.md](error_handling.md) | Custom exceptions | Type-safe error handling |
-| [click_implementation.md](click_implementation.md) | Click & mouse | session.subscribe is mandatory |
-| [wrapped_element_click.md](wrapped_element_click.md) | Wrapped elements | Use getClientRects() |
-| [navigation_waiting.md](navigation_waiting.md) | waitForNavigation | Event-driven with Async::Promise |
-| [testing_strategy.md](testing_strategy.md) | Test optimization | Browser reuse = 19x faster |
-| [frame_architecture.md](frame_architecture.md) | Frame hierarchy | `(parent, browsing_context)` |
-| [rspec_pending_vs_skip.md](rspec_pending_vs_skip.md) | Test documentation | Use `pending` for Firefox |
-| [test_server_routes.md](test_server_routes.md) | Dynamic routes | `server.set_route` for tests |
-
-## Architecture & Patterns
-
-### [Async Programming](async_programming.md)
-
-Guide to Fiber-based async programming with socketry/async.
-
-**Key concepts:**
-- Use Async (Fiber-based), NOT concurrent-ruby (Thread-based)
-- No Mutex needed - cooperative multitasking
-- WebSocket messages must use `Async do` for non-blocking processing
-
-### [Two-Layer Architecture](two_layer_architecture.md)
-
-Core vs Upper layer separation for async complexity management.
-
-**Key concepts:**
-- Core layer returns `Async::Task`
-- Upper layer calls `.wait` on all Core methods
-- User-facing API is synchronous
-
-### [Porting Puppeteer](porting_puppeteer.md)
-
-Best practices for implementing Puppeteer features in Ruby.
-
-**Key concepts:**
-- Study TypeScript implementation first
-- Port corresponding test cases
-- Use official test assets without modification
-
-## Implementation Details
-
-### [QueryHandler](query_handler.md)
-
-Extensible selector handling for CSS, XPath, text selectors.
-
-**Key concepts:**
-- Override `query_one_script` and `query_all_script`
-- TextQueryHandler uses PuppeteerUtil directly (closure dependency)
-- Handle adoption pattern for navigation
-
-### [JavaScript Evaluation](javascript_evaluation.md)
-
-Implementation of `evaluate()` and `evaluate_handle()`.
-
-**Key concepts:**
-- IIFE must be detected and treated as expressions
-- Always deserialize BiDi results before returning
-
-### [JSHandle and ElementHandle](jshandle_implementation.md)
-
-Handle management and BiDi protocol parameters.
-
-**Key concepts:**
-- Set `resultOwnership: 'root'` to get handles
-- Handle parameters must be arrays
-
-### [Selector Evaluation](selector_evaluation.md)
-
-Implementation of `eval_on_selector` methods.
-
-**Key concepts:**
-- Delegation pattern: Page → Frame → ElementHandle
-- Always dispose handles in ensure blocks
-
-### [Click Implementation](click_implementation.md)
-
-Mouse input and click functionality.
-
-**Key concepts:**
-- Must call `session.subscribe` for events
-- URL updates happen via events
-
-### [Wrapped Element Click](wrapped_element_click.md)
-
-Clicking wrapped/multi-line text elements.
-
-**Key concepts:**
-- Use getClientRects() for wrapped elements
-- Viewport clipping ensures clicks stay visible
-
-### [Navigation Waiting](navigation_waiting.md)
-
-waitForNavigation patterns.
-
-**Key concepts:**
-- Event-driven with Async::Promise
-- Attach to existing navigations before block execution
-
-### [Frame Architecture](frame_architecture.md)
-
-Parent-based frame hierarchy.
-
-**Key concepts:**
-- First parameter is `parent` (Page or Frame)
-- Enables future iframe support
-
-### [Error Handling](error_handling.md)
-
-Custom exception types.
-
-**Key concepts:**
-- Use custom exceptions for type-safe rescue
-- Include contextual data in exceptions
-
-## Testing
-
-### [Testing Strategy](testing_strategy.md)
-
-Test organization and optimization.
-
-**Key concepts:**
-- Reuse browser across tests for 19x speedup
-- Use official Puppeteer test assets
-
-### [RSpec: pending vs skip](rspec_pending_vs_skip.md)
-
-Documenting browser limitations.
-
-**Key concepts:**
-- Use `pending` for Firefox BiDi limitations
-- Use `skip` for unimplemented features
-
-### [Test Server Routes](test_server_routes.md)
-
-Dynamic route handling for tests.
-
-**Key concepts:**
-- `server.set_route(path)` for intercepting requests
-- `server.wait_for_request(path)` for synchronization
-
-## Related Documentation
-
-- **Main guide**: [CLAUDE.md](../CLAUDE.md) - High-level development guide
-- **Core layer**: [lib/puppeteer/bidi/core/README.md](../lib/puppeteer/bidi/core/README.md) - Core BiDi abstraction layer

data/CLAUDE/async_programming.md

@@ -1,158 +0,0 @@
-# Async Programming with socketry/async
-
-This project uses the [socketry/async](https://github.com/socketry/async) library for asynchronous operations.
-
-## Why Async Instead of concurrent-ruby?
-
-**IMPORTANT**: This project uses `Async` (Fiber-based), **NOT** `concurrent-ruby` (Thread-based).
-
-| Feature               | Async (Fiber-based)                                    | concurrent-ruby (Thread-based)         |
-| --------------------- | ------------------------------------------------------ | -------------------------------------- |
-| **Concurrency Model** | Cooperative multitasking (like JavaScript async/await) | Preemptive multitasking                |
-| **Race Conditions**   | Not possible within a Fiber                            | Requires Mutex, locks, etc.            |
-| **Synchronization**   | Not needed (cooperative)                               | Required (Mutex, Semaphore)            |
-| **Mental Model**      | Similar to JavaScript async/await                      | Traditional thread programming         |
-| **Bug Risk**          | Lower (no race conditions)                             | Higher (race conditions, deadlocks)    |
-
-**Key advantages:**
-
-- **No race conditions**: Fibers yield control cooperatively, so no concurrent access to shared state
-- **No Mutex needed**: Since there are no race conditions, no synchronization primitives required
-- **Similar to JavaScript**: If you understand `async/await` in JavaScript, you understand Async in Ruby
-- **Easier to reason about**: Code executes sequentially within a Fiber until it explicitly yields
-
-**Example:**
-
-```ruby
-# DON'T: Use concurrent-ruby (Thread-based, requires Mutex)
-require 'concurrent'
-@pending = Concurrent::Map.new  # Thread-safe map
-promise = Concurrent::Promises.resolvable_future
-promise.fulfill(value)
-
-# DO: Use Async (Fiber-based, no synchronization needed)
-require 'async/promise'
-@pending = {}  # Plain Hash is safe with Fibers
-promise = Async::Promise.new
-promise.resolve(value)
-```
-
-## Best Practices
-
-1. **Use `Sync` at top level**: When running async code at the top level of a thread or application, use `Sync { }` instead of `Async { }`
-
-   ```ruby
-   Thread.new do
-     Sync do
-       # async operations here
-     end
-   end
-   ```
-
-2. **Reactor lifecycle**: The reactor is automatically managed by `Sync { }`. No need to create explicit `Async::Reactor` instances in application code.
-
-3. **Background operations**: For long-running background tasks (like WebSocket connections), wrap `Sync { }` in a Thread:
-
-   ```ruby
-   connection_task = Thread.new do
-     Sync do
-       transport.connect  # Async operation that blocks until connection closes
-     end
-   end
-   ```
-
-4. **Promise usage**: Use `Async::Promise` for async coordination:
-
-   ```ruby
-   promise = Async::Promise.new
-
-   # Resolve the promise
-   promise.resolve(value)
-
-   # Wait for the promise with timeout
-   Async do |task|
-     task.with_timeout(5) do
-       result = promise.wait
-     end
-   end.wait
-   ```
-
-5. **No Mutex needed**: Since Async is Fiber-based, you don't need Mutex for shared state within the same event loop
-
-## AsyncUtils: Promise.all and Promise.race
-
-The `lib/puppeteer/bidi/async_utils.rb` module provides JavaScript-like Promise utilities:
-
-```ruby
-# Promise.all - Wait for all tasks to complete
-results = AsyncUtils.promise_all(
-  -> { sleep 0.1; 'first' },
-  -> { sleep 0.2; 'second' },
-  -> { sleep 0.05; 'third' }
-)
-# => ['first', 'second', 'third'] (in order, runs in parallel)
-
-# Promise.race - Return the first to complete
-result = AsyncUtils.promise_race(
-  -> { sleep 0.3; 'slow' },
-  -> { sleep 0.1; 'fast' },
-  -> { sleep 0.2; 'medium' }
-)
-# => 'fast' (cancels remaining tasks)
-```
-
-**When to use AsyncUtils:**
-
-- **Parallel task execution**: Running multiple independent async operations
-- **Racing timeouts**: First of multiple operations to complete
-- **NOT for event-driven waiting**: Use `Async::Promise` directly for event listeners
-
-## WebSocket Message Handling Pattern
-
-**CRITICAL**: BiDi message handling must use `Async do` to process messages asynchronously:
-
-```ruby
-# lib/puppeteer/bidi/transport.rb
-while (message = connection.read)
-  next if message.nil?
-
-  # DO: Use Async do for non-blocking message processing
-  Async do
-    data = JSON.parse(message)
-    debug_print_receive(data)
-    @on_message&.call(data)
-  rescue StandardError => e
-    # Handle errors
-  end
-end
-```
-
-**Why this matters:**
-
-- **Without `Async do`**: Message processing blocks the message loop, preventing other messages from being read
-- **With `Async do`**: Each message is processed in a separate fiber, allowing concurrent message handling
-- **Prevents deadlocks**: When multiple operations are waiting for responses, they can all be processed concurrently
-
-**Example of the problem this solves:**
-
-```ruby
-# Without Async do:
-# 1. Message A arrives and starts processing
-# 2. Processing A calls wait_for_navigation which waits for Message B
-# 3. Message B arrives but can't be read because Message A is still being processed
-# 4. DEADLOCK
-
-# With Async do:
-# 1. Message A arrives and starts processing in Fiber 1
-# 2. Fiber 1 yields when calling wait (cooperative multitasking)
-# 3. Message B can now be read and processed in Fiber 2
-# 4. Both messages complete successfully
-```
-
-This pattern is essential for the BiDi protocol's bidirectional communication model.
-
-## References
-
-- [Async Best Practices](https://socketry.github.io/async/guides/best-practices/)
-- [Async Documentation](https://socketry.github.io/async/)
-- [Async::Barrier Guide](https://socketry.github.io/async/guides/tasks/index.html)