puppeteer-bidi 0.0.1.beta1 → 0.0.1.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a2905e58b0b31a75a0b286fa14986def369fe62d122dd62dc6432a763070ea9
-  data.tar.gz: b6cb21ba581490c0cbe28ae4515498660091ec9653df2c6d8c1e4b9d5f34197e
+  metadata.gz: 4a297f926102da482b6ffaecf8f894cb95dffb910f6743ebc75d0414f1aae00f
+  data.tar.gz: 81c8b08b57b53ca739af7e864723686965278d60bd5d0d1197aff31dd37b299f
 SHA512:
-  metadata.gz: 68c9e714dd633886188df24ccedc71139ac4ed8f5525e470c99b0c802dcdc5ce261279fea56b2c60dd6456a245b056acf987d9cd43cd6283c33f3bca2f568794
-  data.tar.gz: beb1f011607f387f10329db6078a91d41eb5582631256f742655af39d7ea15638aa3d29c3e7c44a1fce4072585c141898147c783be65b1cf20deda1a73e25d4f
+  metadata.gz: 519a8a8e1dccfc046de5c8bea356a59d3b5e40e79e8040f85fbbe370f1530170ccbd555b32a242841d132130ef4da85eeedc58bac3f554ab34159faa0b807826
+  data.tar.gz: d60e4cb2eb5caf33a055d394861814f4ecd3f8b561796ff5cb69cce17a5efe59ae3e07cc98e9e5c46b90a68944f20090cfccb6726849cf774f0f0f015fbffaf1

data/CLAUDE.md

@@ -86,14 +86,15 @@ Use [rbs-inline](https://github.com/soutaro/rbs-inline) for type annotations in
 class Example
   attr_reader :name #: String
 
-  # @rbs name: String
+  # @rbs name: String -- The name to set
   # @rbs return: void
   def initialize(name)
     @name = name
   end
 
-  # @rbs selector: String
-  # @rbs return: ElementHandle?
+  # 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
@@ -103,8 +104,10 @@ end
 **Conventions:**
 - Use `A?` for nullable types (not `A | nil`)
 - Use `A | B | nil` for union types with nil
-- Add space around `--` for inline comments: `# @rbs name: String -- the name`
+- **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`
 
 **Generate RBS files:**
 ```bash
@@ -113,6 +116,49 @@ 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

data/README.md

@@ -471,7 +471,14 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ### Type Annotations
 
-This gem includes RBS type definitions generated by [rbs-inline](https://github.com/soutaro/rbs-inline).
+This gem includes RBS type definitions generated by [rbs-inline](https://github.com/soutaro/rbs-inline). Type checking is performed with [Steep](https://github.com/soutaro/steep).
+
+```bash
+bundle exec rake rbs       # Generate RBS files
+bundle exec steep check    # Run type checker
+```
+
+For development guidelines on type annotations, see `CLAUDE.md`.
 
 ## Contributing
 

data/Steepfile

@@ -0,0 +1,36 @@
+# Steepfile for type checking
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Standard library
+  library "json"
+  library "base64"
+  library "fileutils"
+  library "uri"
+  library "net-http"
+
+  # Configure diagnostic severity
+  # Start with lenient settings and tighten over time
+  # Using :hint for issues that don't block CI, :warning for informational
+  configure_code_diagnostics do |hash|
+    # Ignore common Ruby patterns that are hard to type
+    hash[Steep::Diagnostic::Ruby::UnannotatedEmptyCollection] = :hint
+
+    # Gradual typing: treat missing methods and type mismatches as hints
+    # These can be tightened to :warning or :error as type coverage improves
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :hint
+    hash[Steep::Diagnostic::Ruby::NoMethod] = :hint
+    hash[Steep::Diagnostic::Ruby::UnresolvedOverloading] = :hint
+    hash[Steep::Diagnostic::Ruby::IncompatibleAssignment] = :hint
+    hash[Steep::Diagnostic::Ruby::ArgumentTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::ReturnTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::BlockTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::BreakTypeMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::ImplicitBreakValueMismatch] = :hint
+    hash[Steep::Diagnostic::Ruby::UnexpectedBlockGiven] = :hint
+    hash[Steep::Diagnostic::Ruby::UnexpectedPositionalArgument] = :hint
+  end
+end

data/lib/puppeteer/bidi/async_utils.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'async'
 require 'async/promise'

data/lib/puppeteer/bidi/browser.rb

@@ -12,9 +12,9 @@ module Puppeteer
       attr_reader :process #: untyped
       attr_reader :default_browser_context #: BrowserContext
 
-      # @rbs connection: Connection
-      # @rbs launcher: BrowserLauncher?
-      # @rbs return: Browser
+      # @rbs connection: Connection -- BiDi connection
+      # @rbs launcher: BrowserLauncher? -- Browser launcher instance
+      # @rbs return: Browser -- Browser instance
       def self.create(connection:, launcher: nil)
         # Create a new BiDi session
         session = Core::Session.from(
@@ -48,10 +48,10 @@ module Puppeteer
         )
       end
 
-      # @rbs connection: Connection
-      # @rbs launcher: BrowserLauncher?
-      # @rbs core_browser: Core::Browser
-      # @rbs session: Core::Session
+      # @rbs connection: Connection -- BiDi connection
+      # @rbs launcher: BrowserLauncher? -- Browser launcher instance
+      # @rbs core_browser: Core::Browser -- Core browser instance
+      # @rbs session: Core::Session -- BiDi session
       # @rbs return: void
       def initialize(connection:, launcher:, core_browser:, session:)
         @connection = connection
@@ -69,8 +69,12 @@ module Puppeteer
       end
 
       # Launch a new Firefox browser instance
-      # @rbs **options: untyped
-      # @rbs return: Browser
+      # @rbs executable_path: String
+      # @rbs user_data_dir: String
+      # @rbs headless: bool
+      # @rbs args: Array[String]
+      # @rbs timeout: Numeric
+      # @rbs return: Browser -- Browser instance
       def self.launch(**options)
         launcher = BrowserLauncher.new(
           executable_path: options[:executable_path],
@@ -95,27 +99,37 @@ module Puppeteer
         browser
       end
 
+      # Connect to an existing Firefox browser instance
+      # @rbs ws_endpoint: String -- WebSocket endpoint URL
+      # @rbs return: Browser -- Browser instance
+      def self.connect(ws_endpoint)
+        transport = Transport.new(ws_endpoint)
+        AsyncUtils.async_timeout(30 * 1000, transport.connect).wait
+        connection = Connection.new(transport)
+        create(connection: connection, launcher: nil)
+      end
+
       # Get BiDi session status
-      # @rbs return: untyped
+      # @rbs return: untyped -- Session status
       def status
-        @connection.send_command('session.status')
+        @connection.async_send_command('session.status').wait
       end
 
       # Create a new page (Puppeteer-like API)
-      # @rbs return: Page
+      # @rbs return: Page -- New page instance
       def new_page
         @default_browser_context.new_page
       end
 
       # Get all pages
-      # @rbs return: Array[Page]
+      # @rbs return: Array[Page] -- All pages
       def pages
         @default_browser_context.pages
       end
 
       # Register event handler
-      # @rbs event: String | Symbol
-      # @rbs &block: (untyped) -> void
+      # @rbs event: String | Symbol -- Event name
+      # @rbs &block: (untyped) -> void -- Event handler
       # @rbs return: void
       def on(event, &block)
         @connection.on(event, &block)
@@ -143,9 +157,9 @@ module Puppeteer
       end
 
       # Wait until a target (top-level browsing context) satisfies the predicate.
-      # @rbs timeout: Integer?
-      # @rbs &predicate: (Target) -> boolish
-      # @rbs return: Target
+      # @rbs timeout: Integer? -- Timeout in milliseconds (default: 30000)
+      # @rbs &predicate: (BrowserTarget | PageTarget | FrameTarget) -> boolish -- Predicate evaluated against each Target
+      # @rbs return: BrowserTarget | PageTarget | FrameTarget -- Matching target
       def wait_for_target(timeout: nil, &predicate)
         predicate ||= ->(_target) { true }
         timeout_ms = timeout || 30_000
@@ -237,8 +251,8 @@ module Puppeteer
 
       private
 
-      # @rbs &block: (Target) -> void
-      # @rbs return: Enumerator[Target, void]
+      # @rbs &block: (BrowserTarget | PageTarget | FrameTarget) -> void -- Block to yield each target to
+      # @rbs return: Enumerator[BrowserTarget | PageTarget | FrameTarget, void] -- Enumerator of targets
       def each_target(&block)
         return enum_for(:each_target) unless block_given?
         return unless @core_browser
@@ -260,8 +274,8 @@ module Puppeteer
         end
       end
 
-      # @rbs predicate: (Target) -> boolish
-      # @rbs return: Target?
+      # @rbs predicate: ^(BrowserTarget | PageTarget | FrameTarget) -> boolish -- Predicate to match targets
+      # @rbs return: (BrowserTarget | PageTarget | FrameTarget)? -- Matching target or nil
       def find_target(predicate)
         each_target do |target|
           return target if predicate.call(target)
@@ -269,8 +283,8 @@ module Puppeteer
         nil
       end
 
-      # @rbs user_context: Core::UserContext
-      # @rbs return: BrowserContext?
+      # @rbs user_context: Core::UserContext -- User context to get browser context for
+      # @rbs return: BrowserContext? -- Browser context or nil
       def browser_context_for(user_context)
         return @browser_contexts[user_context.id] if @browser_contexts.key?(user_context.id)
 

data/lib/puppeteer/bidi/browser_context.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Puppeteer
   module Bidi
     # BrowserContext represents an isolated browsing session
     # This is a high-level wrapper around Core::UserContext
     class BrowserContext
-      attr_reader :user_context, :browser
+      attr_reader :user_context #: Core::UserContext
+      attr_reader :browser #: Browser
 
+      # @rbs browser: Browser -- Parent browser instance
+      # @rbs user_context: Core::UserContext -- Associated user context
+      # @rbs return: void
       def initialize(browser, user_context)
         @browser = browser
         @user_context = user_context
@@ -14,18 +19,21 @@ module Puppeteer
       end
 
       # Create a new page (tab/window)
-      # @return [Page] New page instance
+      # @rbs return: Page -- New page instance
       def new_page
         browsing_context = @user_context.create_browsing_context('tab')
         page_for(browsing_context)
       end
 
       # Get all pages in this context
-      # @return [Array<Page>] All pages
+      # @rbs return: Array[Page] -- All pages
       def pages
         @pages.values
       end
 
+      # Get or create a Page for the given browsing context
+      # @rbs browsing_context: Core::BrowsingContext -- Browsing context
+      # @rbs return: Page -- Page instance
       def page_for(browsing_context)
         @pages[browsing_context.id] ||= begin
           page = Page.new(self, browsing_context)
@@ -39,12 +47,13 @@ module Puppeteer
       end
 
       # Close the browser context
+      # @rbs return: void
       def close
         @user_context.close
       end
 
       # Check if context is closed
-      # @return [Boolean] Whether the context is closed
+      # @rbs return: bool -- Whether the context is closed
       def closed?
         @user_context.disposed?
       end

data/lib/puppeteer/bidi/browser_launcher.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'open3'
 require 'tmpdir'

data/lib/puppeteer/bidi/connection.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'async'
 require 'async/promise'
@@ -11,23 +12,25 @@ module Puppeteer
       class TimeoutError < Error; end
       class ProtocolError < Error; end
 
-      DEFAULT_TIMEOUT = 30_000 # 30 seconds in milliseconds
+      DEFAULT_TIMEOUT = 30_000 #: Integer -- 30 seconds in milliseconds
 
+      # @rbs transport: Transport
+      # @rbs return: void
       def initialize(transport)
         @transport = transport
         @next_id = 1
-        @pending_commands = {}
-        @event_listeners = {}
+        @pending_commands = {} #: Hash[Integer, Hash[Symbol, untyped]]
+        @event_listeners = {} #: Hash[String, Array[^(untyped) -> void]]
         @closed = false
 
         setup_transport_handlers
       end
 
       # Send a BiDi command and wait for response
-      # @param method [String] BiDi method name (e.g., 'browsingContext.navigate')
-      # @param params [Hash] Command parameters
-      # @param timeout [Integer] Timeout in milliseconds
-      # @return [Hash] Command result
+      # @rbs method: String
+      # @rbs params: Hash[String | Symbol, untyped]
+      # @rbs timeout: Integer
+      # @rbs return: Async::Task[Hash[String, untyped]]
       def async_send_command(method, params = {}, timeout: DEFAULT_TIMEOUT)
         raise ProtocolError, 'Connection is closed' if @closed
 
@@ -81,14 +84,18 @@ module Puppeteer
       end
 
       # Subscribe to BiDi events
-      # @param event [String] Event name (e.g., 'browsingContext.navigationStarted')
-      # @param block [Proc] Event handler
+      # @rbs event: String
+      # @rbs &block: (untyped) -> void
+      # @rbs return: void
       def on(event, &block)
         @event_listeners[event] ||= []
         @event_listeners[event] << block
       end
 
       # Unsubscribe from BiDi events
+      # @rbs event: String
+      # @rbs &block: ((untyped) -> void)?
+      # @rbs return: void
       def off(event, &block)
         return unless @event_listeners[event]
 
@@ -100,6 +107,7 @@ module Puppeteer
       end
 
       # Close the connection
+      # @rbs return: void
       def close
         return if @closed
 
@@ -114,18 +122,21 @@ module Puppeteer
         @transport.close
       end
 
+      # @rbs return: bool
       def closed?
         @closed
       end
 
       private
 
+      # @rbs return: Integer
       def next_id
         id = @next_id
         @next_id += 1
         id
       end
 
+      # @rbs return: void
       def setup_transport_handlers
         @transport.on_message do |message|
           handle_message(message)
@@ -136,6 +147,8 @@ module Puppeteer
         end
       end
 
+      # @rbs message: Hash[String, untyped]
+      # @rbs return: void
       def handle_message(message)
         # Response to a command (has 'id' field)
         if message['id']
@@ -148,6 +161,8 @@ module Puppeteer
         end
       end
 
+      # @rbs message: Hash[String, untyped]
+      # @rbs return: void
       def handle_response(message)
         id = message['id']
         pending = @pending_commands.delete(id)
@@ -161,6 +176,8 @@ module Puppeteer
         pending[:promise].resolve(message)
       end
 
+      # @rbs message: Hash[String, untyped]
+      # @rbs return: void
       def handle_event(message)
         method = message['method']
         params = message['params'] || {}

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Puppeteer
   module Bidi
@@ -9,8 +10,8 @@ module Puppeteer
         include Disposable::DisposableMixin
 
         # Create a browser instance from a session
-        # @param session [Session] BiDi session
-        # @return [Browser] Browser instance
+        # @rbs session: Session -- BiDi session
+        # @rbs return: Async::Task[Browser] -- Browser instance
         def self.from(session)
           browser = new(session)
           Async do
@@ -44,18 +45,19 @@ module Puppeteer
         alias disposed? disconnected?
 
         # Get the default user context
-        # @return [UserContext] Default user context
+        # @rbs return: UserContext? -- Default user context
         def default_user_context
           @user_contexts[UserContext::DEFAULT]
         end
 
         # Get all user contexts
-        # @return [Array<UserContext>] All user contexts
+        # @rbs return: Array[UserContext] -- All user contexts
         def user_contexts
           @user_contexts.values
         end
 
         # Close the browser
+        # @rbs return: Async::Task[void]
         def close
           Async do
             return if @closed
@@ -69,11 +71,9 @@ module Puppeteer
         end
 
         # Add a preload script to the browser
-        # @param function_declaration [String] JavaScript function to preload
-        # @param options [Hash] Preload script options
-        # @option options [Array<BrowsingContext>] :contexts Contexts to apply to
-        # @option options [String] :sandbox Sandbox name
-        # @return [String] Script ID
+        # @rbs function_declaration: String -- JavaScript function to preload
+        # @rbs **options: untyped -- Preload script options
+        # @rbs return: Async::Task[String] -- Script ID
         def add_preload_script(function_declaration, **options)
           raise BrowserDisconnectedError, @reason if disconnected?
 
@@ -90,16 +90,16 @@ module Puppeteer
         end
 
         # Remove a preload script
-        # @param script [String] Script ID
+        # @rbs script: String -- Script ID
+        # @rbs return: Async::Task[untyped]
         def remove_preload_script(script)
           raise BrowserDisconnectedError, @reason if disconnected?
           @session.async_send_command('script.removePreloadScript', { script: script })
         end
 
         # Create a new user context
-        # @param options [Hash] User context options
-        # @option options [Hash] :proxy Proxy configuration
-        # @return [UserContext] New user context
+        # @rbs **options: untyped -- User context options
+        # @rbs return: Async::Task[UserContext] -- New user context
         def create_user_context(**options)
           raise BrowserDisconnectedError, @reason if disconnected?
 
@@ -122,7 +122,8 @@ module Puppeteer
         end
 
         # Remove a network intercept
-        # @param intercept [String] Intercept ID
+        # @rbs intercept: String -- Intercept ID
+        # @rbs return: Async::Task[untyped]
         def remove_intercept(intercept)
           raise BrowserDisconnectedError, @reason if disconnected?
           @session.async_send_command('network.removeIntercept', { intercept: intercept })