puppeteer-bidi 0.0.1.beta1 → 0.0.1.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a2905e58b0b31a75a0b286fa14986def369fe62d122dd62dc6432a763070ea9
-  data.tar.gz: b6cb21ba581490c0cbe28ae4515498660091ec9653df2c6d8c1e4b9d5f34197e
+  metadata.gz: e48c2e579cbfaa59695d2bef7808b5d1e06a6eaabc32373c76922bb1546bc1b1
+  data.tar.gz: 1b7c45fd354031cbeb4fb79c44de2b60dfeb3daee83347c852cfb3ead069813e
 SHA512:
-  metadata.gz: 68c9e714dd633886188df24ccedc71139ac4ed8f5525e470c99b0c802dcdc5ce261279fea56b2c60dd6456a245b056acf987d9cd43cd6283c33f3bca2f568794
-  data.tar.gz: beb1f011607f387f10329db6078a91d41eb5582631256f742655af39d7ea15638aa3d29c3e7c44a1fce4072585c141898147c783be65b1cf20deda1a73e25d4f
+  metadata.gz: e871963ebf26bcd8739be7860c50f62fbb39869950f9a674369f6685a6971fa669d6d1df69b9e684adada354c6219fb11e5982a8c2103cac6425d5e32eb8dbb1
+  data.tar.gz: d3b5db4e138484081966a678e8e2f9f70d5c9031fcadd00631368920abbf8eb92d2f1f92beea34d48272b87e3bf63521a9e57d71e339667f2113d87fc8f3c495

data/CLAUDE.md

@@ -113,6 +113,50 @@ 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`
+   - Union type aliases that rbs-inline doesn't preserve
+
+**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
@@ -68,9 +68,18 @@ module Puppeteer
         }
       end
 
+      # @rbs!
+      #   type launch_options = {
+      #     ?executable_path: String,
+      #     ?user_data_dir: String,
+      #     ?headless: bool,
+      #     ?args: Array[String],
+      #     ?timeout: Numeric
+      #   }
+
       # Launch a new Firefox browser instance
-      # @rbs **options: untyped
-      # @rbs return: Browser
+      # @rbs **options: launch_options -- Launch options
+      # @rbs return: Browser -- Browser instance
       def self.launch(**options)
         launcher = BrowserLauncher.new(
           executable_path: options[:executable_path],
@@ -95,27 +104,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 +162,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: (target) -> boolish -- Predicate evaluated against each Target
+      # @rbs return: target -- Matching target
       def wait_for_target(timeout: nil, &predicate)
         predicate ||= ->(_target) { true }
         timeout_ms = timeout || 30_000
@@ -237,8 +256,8 @@ module Puppeteer
 
       private
 
-      # @rbs &block: (Target) -> void
-      # @rbs return: Enumerator[Target, void]
+      # @rbs &block: (target) -> void -- Block to yield each target to
+      # @rbs return: Enumerator[target, void] -- Enumerator of targets
       def each_target(&block)
         return enum_for(:each_target) unless block_given?
         return unless @core_browser
@@ -260,8 +279,8 @@ module Puppeteer
         end
       end
 
-      # @rbs predicate: (Target) -> boolish
-      # @rbs return: Target?
+      # @rbs predicate: ^(target) -> boolish -- Predicate to match targets
+      # @rbs return: target? -- Matching target or nil
       def find_target(predicate)
         each_target do |target|
           return target if predicate.call(target)
@@ -269,8 +288,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 })