puppeteer-bidi 0.0.1.beta1 → 0.0.1.beta2

data/lib/puppeteer/bidi/page.rb

@@ -15,8 +15,8 @@ module Puppeteer
       attr_reader :browser_context #: BrowserContext
       attr_reader :timeout_settings #: TimeoutSettings
 
-      # @rbs browser_context: BrowserContext
-      # @rbs browsing_context: Core::BrowsingContext
+      # @rbs browser_context: BrowserContext -- Parent browser context
+      # @rbs browsing_context: Core::BrowsingContext -- Associated browsing context
       # @rbs return: void
       def initialize(browser_context, browsing_context)
         @browser_context = browser_context
@@ -29,41 +29,41 @@ module Puppeteer
       # Following Puppeteer's trustedEmitter pattern
 
       # Register an event listener
-      # @rbs event: Symbol | String
-      # @rbs &block: (untyped) -> void
+      # @rbs event: Symbol | String -- Event name
+      # @rbs &block: (untyped) -> void -- Event handler
       # @rbs return: void
       def on(event, &block)
         @emitter.on(event, &block)
       end
 
       # Register a one-time event listener
-      # @rbs event: Symbol | String
-      # @rbs &block: (untyped) -> void
+      # @rbs event: Symbol | String -- Event name
+      # @rbs &block: (untyped) -> void -- Event handler
       # @rbs return: void
       def once(event, &block)
         @emitter.once(event, &block)
       end
 
       # Remove an event listener
-      # @rbs event: Symbol | String
-      # @rbs &block: (untyped) -> void
+      # @rbs event: Symbol | String -- Event name
+      # @rbs &block: (untyped) -> void -- Event handler to remove
       # @rbs return: void
       def off(event, &block)
         @emitter.off(event, &block)
       end
 
       # Emit an event to all registered listeners
-      # @rbs event: Symbol | String
-      # @rbs data: untyped
+      # @rbs event: Symbol | String -- Event name
+      # @rbs data: untyped -- Event data
       # @rbs return: void
       def emit(event, data = nil)
         @emitter.emit(event, data)
       end
 
       # Navigate to a URL
-      # @rbs url: String
-      # @rbs wait_until: String
-      # @rbs return: HTTPResponse?
+      # @rbs url: String -- URL to navigate to
+      # @rbs wait_until: String -- When to consider navigation complete ('load', 'domcontentloaded')
+      # @rbs return: HTTPResponse? -- Main response
       def goto(url, wait_until: 'load')
         assert_not_closed
 
@@ -71,20 +71,20 @@ module Puppeteer
       end
 
       # Set page content
-      # @rbs html: String
-      # @rbs wait_until: String
+      # @rbs html: String -- HTML content to set
+      # @rbs wait_until: String -- When to consider content set ('load', 'domcontentloaded')
       # @rbs return: void
       def set_content(html, wait_until: 'load')
         main_frame.set_content(html, wait_until: wait_until)
       end
 
       # Take a screenshot
-      # @rbs path: String?
-      # @rbs type: String
-      # @rbs full_page: bool
-      # @rbs clip: Hash[Symbol, Numeric]?
-      # @rbs capture_beyond_viewport: bool
-      # @rbs return: String
+      # @rbs path: String? -- File path to save screenshot
+      # @rbs type: String -- Image type ('png' or 'jpeg')
+      # @rbs full_page: bool -- Capture full page
+      # @rbs clip: Hash[Symbol, Numeric]? -- Clip region
+      # @rbs capture_beyond_viewport: bool -- Capture beyond viewport
+      # @rbs return: String -- Base64-encoded image data
       def screenshot(path: nil, type: 'png', full_page: false, clip: nil, capture_beyond_viewport: true)
         assert_not_closed
 
@@ -207,82 +207,82 @@ module Puppeteer
       end
 
       # Evaluate JavaScript in the page context
-      # @rbs script: String
-      # @rbs *args: untyped
-      # @rbs return: untyped
+      # @rbs script: String -- JavaScript code to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the script
+      # @rbs return: untyped -- Result of evaluation
       def evaluate(script, *args)
         main_frame.evaluate(script, *args)
       end
 
       # Evaluate JavaScript and return a handle to the result
-      # @rbs script: String
-      # @rbs *args: untyped
-      # @rbs return: JSHandle
+      # @rbs script: String -- JavaScript code to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the script
+      # @rbs return: JSHandle -- Handle to the result
       def evaluate_handle(script, *args)
         main_frame.evaluate_handle(script, *args)
       end
 
       # Query for an element matching the selector
-      # @rbs selector: String
-      # @rbs return: ElementHandle?
+      # @rbs selector: String -- Selector to query
+      # @rbs return: ElementHandle? -- Matching element or nil
       def query_selector(selector)
         main_frame.query_selector(selector)
       end
 
       # Query for all elements matching the selector
-      # @rbs selector: String
-      # @rbs return: Array[ElementHandle]
+      # @rbs selector: String -- Selector to query
+      # @rbs return: Array[ElementHandle] -- All matching elements
       def query_selector_all(selector)
         main_frame.query_selector_all(selector)
       end
 
       # Evaluate a function on the first element matching the selector
-      # @rbs selector: String
-      # @rbs page_function: String
-      # @rbs *args: untyped
-      # @rbs return: untyped
+      # @rbs selector: String -- Selector to query
+      # @rbs page_function: String -- JavaScript function to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the function
+      # @rbs return: untyped -- Evaluation result
       def eval_on_selector(selector, page_function, *args)
         main_frame.eval_on_selector(selector, page_function, *args)
       end
 
       # Evaluate a function on all elements matching the selector
-      # @rbs selector: String
-      # @rbs page_function: String
-      # @rbs *args: untyped
-      # @rbs return: untyped
+      # @rbs selector: String -- Selector to query
+      # @rbs page_function: String -- JavaScript function to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the function
+      # @rbs return: untyped -- Evaluation result
       def eval_on_selector_all(selector, page_function, *args)
         main_frame.eval_on_selector_all(selector, page_function, *args)
       end
 
       # Click an element matching the selector
-      # @rbs selector: String
-      # @rbs button: String
-      # @rbs count: Integer
-      # @rbs delay: Numeric?
-      # @rbs offset: Hash[Symbol, Numeric]?
+      # @rbs selector: String -- Selector to click
+      # @rbs button: String -- Mouse button ('left', 'right', 'middle')
+      # @rbs count: Integer -- Number of clicks
+      # @rbs delay: Numeric? -- Delay between clicks in ms
+      # @rbs offset: Hash[Symbol, Numeric]? -- Click offset from element center
       # @rbs return: void
       def click(selector, button: Mouse::LEFT, count: 1, delay: nil, offset: nil)
         main_frame.click(selector, button: button, count: count, delay: delay, offset: offset)
       end
 
       # Type text into an element matching the selector
-      # @rbs selector: String
-      # @rbs text: String
-      # @rbs delay: Numeric
+      # @rbs selector: String -- Selector to type into
+      # @rbs text: String -- Text to type
+      # @rbs delay: Numeric -- Delay between key presses in ms
       # @rbs return: void
       def type(selector, text, delay: 0)
         main_frame.type(selector, text, delay: delay)
       end
 
       # Hover over an element matching the selector
-      # @rbs selector: String
+      # @rbs selector: String -- Selector to hover
       # @rbs return: void
       def hover(selector)
         main_frame.hover(selector)
       end
 
       # Focus an element matching the selector
-      # @rbs selector: String
+      # @rbs selector: String -- Selector to focus
       # @rbs return: void
       def focus(selector)
         handle = main_frame.query_selector(selector)
@@ -296,13 +296,13 @@ module Puppeteer
       end
 
       # Get the page title
-      # @rbs return: String
+      # @rbs return: String -- Page title
       def title
         evaluate('document.title')
       end
 
       # Get the page URL
-      # @rbs return: String
+      # @rbs return: String -- Page URL
       def url
         @browsing_context.url
       end
@@ -316,19 +316,19 @@ module Puppeteer
       end
 
       # Check if page is closed
-      # @rbs return: bool
+      # @rbs return: bool -- Whether page is closed
       def closed?
         @browsing_context.closed?
       end
 
       # Get the main frame
-      # @rbs return: Frame
+      # @rbs return: Frame -- Main frame
       def main_frame
         @main_frame ||= Frame.from(self, @browsing_context)
       end
 
       # Get the focused frame
-      # @rbs return: Frame
+      # @rbs return: Frame -- Focused frame
       def focused_frame
         assert_not_closed
 
@@ -368,46 +368,46 @@ module Puppeteer
 
       # Get all frames (main frame + all nested child frames)
       # Following Puppeteer's pattern of returning all frames recursively
-      # @rbs return: Array[Frame]
+      # @rbs return: Array[Frame] -- All frames
       def frames
         collect_frames(main_frame)
       end
 
       # Get the mouse instance
-      # @rbs return: Mouse
+      # @rbs return: Mouse -- Mouse instance
       def mouse
         @mouse ||= Mouse.new(@browsing_context)
       end
 
       # Get the keyboard instance
-      # @rbs return: Keyboard
+      # @rbs return: Keyboard -- Keyboard instance
       def keyboard
         @keyboard ||= Keyboard.new(self, @browsing_context)
       end
 
       # Wait for a function to return a truthy value
-      # @rbs page_function: String
-      # @rbs options: Hash[Symbol, untyped]
-      # @rbs *args: untyped
-      # @rbs &block: ((JSHandle) -> void)?
-      # @rbs return: JSHandle
+      # @rbs page_function: String -- JavaScript function to evaluate
+      # @rbs options: Hash[Symbol, untyped] -- Wait options (timeout, polling)
+      # @rbs *args: untyped -- Arguments to pass to the function
+      # @rbs &block: ((JSHandle) -> void)? -- Optional block called with result
+      # @rbs return: JSHandle -- Handle to the truthy result
       def wait_for_function(page_function, options = {}, *args, &block)
         main_frame.wait_for_function(page_function, options, *args, &block)
       end
 
       # Wait for an element matching the selector to appear in the page
-      # @rbs selector: String
-      # @rbs visible: bool?
-      # @rbs hidden: bool?
-      # @rbs timeout: Numeric?
-      # @rbs &block: ((ElementHandle?) -> void)?
-      # @rbs return: ElementHandle?
+      # @rbs selector: String -- Selector to wait for
+      # @rbs visible: bool? -- Wait for element to be visible
+      # @rbs hidden: bool? -- Wait for element to be hidden
+      # @rbs timeout: Numeric? -- Wait timeout in ms
+      # @rbs &block: ((ElementHandle?) -> void)? -- Optional block called with element
+      # @rbs return: ElementHandle? -- Element or nil if hidden
       def wait_for_selector(selector, visible: nil, hidden: nil, timeout: nil, &block)
         main_frame.wait_for_selector(selector, visible: visible, hidden: hidden, timeout: timeout, &block)
       end
 
       # Set the default timeout for waiting operations (e.g., waitForFunction).
-      # @rbs timeout: Numeric
+      # @rbs timeout: Numeric -- Timeout in ms
       # @rbs return: void
       def set_default_timeout(timeout)
         raise ArgumentError, 'timeout must be a non-negative number' unless timeout.is_a?(Numeric) && timeout >= 0
@@ -416,24 +416,24 @@ module Puppeteer
       end
 
       # Get the current default timeout in milliseconds.
-      # @rbs return: Numeric
+      # @rbs return: Numeric -- Timeout in ms
       def default_timeout
         @timeout_settings.timeout
       end
 
       # Wait for navigation to complete
-      # @rbs timeout: Numeric
-      # @rbs wait_until: String
-      # @rbs &block: (-> void)?
-      # @rbs return: HTTPResponse?
+      # @rbs timeout: Numeric -- Navigation timeout in ms
+      # @rbs wait_until: String -- When to consider navigation complete
+      # @rbs &block: (-> void)? -- Optional block to trigger navigation
+      # @rbs return: HTTPResponse? -- Response or nil
       def wait_for_navigation(timeout: 30000, wait_until: 'load', &block)
         main_frame.wait_for_navigation(timeout: timeout, wait_until: wait_until, &block)
       end
 
       # Wait for a file chooser to be opened
-      # @rbs timeout: Numeric?
-      # @rbs &block: (-> void)?
-      # @rbs return: FileChooser
+      # @rbs timeout: Numeric? -- Wait timeout in ms
+      # @rbs &block: (-> void)? -- Optional block to trigger file chooser
+      # @rbs return: FileChooser -- File chooser instance
       def wait_for_file_chooser(timeout: nil, &block)
         assert_not_closed
 
@@ -485,9 +485,9 @@ module Puppeteer
 
       # Wait for network to be idle (no more than concurrency connections for idle_time)
       # Based on Puppeteer's waitForNetworkIdle implementation
-      # @rbs idle_time: Numeric
-      # @rbs timeout: Numeric
-      # @rbs concurrency: Integer
+      # @rbs idle_time: Numeric -- Time to wait for idle in ms
+      # @rbs timeout: Numeric -- Wait timeout in ms
+      # @rbs concurrency: Integer -- Max allowed inflight requests
       # @rbs return: void
       def wait_for_network_idle(idle_time: 500, timeout: 30000, concurrency: 0)
         assert_not_closed
@@ -554,8 +554,8 @@ module Puppeteer
       end
 
       # Set viewport size
-      # @rbs width: Integer
-      # @rbs height: Integer
+      # @rbs width: Integer -- Viewport width in pixels
+      # @rbs height: Integer -- Viewport height in pixels
       # @rbs return: void
       def set_viewport(width:, height:)
         @viewport = { width: width, height: height }
@@ -568,7 +568,7 @@ module Puppeteer
       end
 
       # Get current viewport size
-      # @rbs return: Hash[Symbol, Integer]?
+      # @rbs return: Hash[Symbol, Integer]? -- Viewport dimensions
       def viewport
         @viewport
       end
@@ -577,7 +577,7 @@ module Puppeteer
       alias default_timeout= set_default_timeout
 
       # Set JavaScript enabled state
-      # @rbs enabled: bool
+      # @rbs enabled: bool -- Whether JavaScript is enabled
       # @rbs return: void
       def set_javascript_enabled(enabled)
         assert_not_closed
@@ -585,7 +585,7 @@ module Puppeteer
       end
 
       # Check if JavaScript is enabled
-      # @rbs return: bool
+      # @rbs return: bool -- Whether JavaScript is enabled
       def javascript_enabled?
         @browsing_context.javascript_enabled?
       end
@@ -593,8 +593,8 @@ module Puppeteer
       private
 
       # Recursively collect all frames starting from the given frame
-      # @rbs frame: Frame
-      # @rbs return: Array[Frame]
+      # @rbs frame: Frame -- Starting frame
+      # @rbs return: Array[Frame] -- All frames in subtree
       def collect_frames(frame)
         result = [frame]
         frame.child_frames.each do |child|

data/lib/puppeteer/bidi/query_handler.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
 require 'singleton'
 
 module Puppeteer

data/lib/puppeteer/bidi/realm.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Puppeteer
   module Bidi
@@ -6,18 +7,24 @@ module Puppeteer
     # Provides shared lifecycle management for WaitTask instances.
     # https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Realm.ts
     class Realm
-      attr_reader :task_manager
+      attr_reader :task_manager #: TaskManager
 
+      # @rbs timeout_settings: TimeoutSettings -- Timeout settings
+      # @rbs return: void
       def initialize(timeout_settings)
         @timeout_settings = timeout_settings
         @task_manager = TaskManager.new
         @disposed = false
       end
 
+      # Get the environment object (must be implemented by subclass)
+      # @rbs return: untyped -- Environment object
       def environment
         raise NotImplementedError, 'Subclass must expose its environment object'
       end
 
+      # Get the page for this realm
+      # @rbs return: Page -- Page instance
       def page
         env = environment
         return env.page if env.respond_to?(:page)
@@ -25,10 +32,18 @@ module Puppeteer
         raise NotImplementedError, 'Environment must expose a page reference'
       end
 
+      # Get the default timeout
+      # @rbs return: Numeric -- Default timeout in ms
       def default_timeout
         @timeout_settings.timeout
       end
 
+      # Wait for a function to return a truthy value
+      # @rbs page_function: String -- JavaScript function to evaluate
+      # @rbs options: Hash[Symbol, untyped] -- Wait options (timeout, polling, root)
+      # @rbs *args: untyped -- Arguments to pass to the function
+      # @rbs &block: ((JSHandle) -> void)? -- Optional block called with result
+      # @rbs return: JSHandle -- Handle to the truthy result
       def wait_for_function(page_function, options = {}, *args, &block)
         ensure_environment_active!
 
@@ -51,6 +66,8 @@ module Puppeteer
         result.wait
       end
 
+      # Dispose this realm
+      # @rbs return: void
       def dispose
         return if @disposed
 
@@ -58,14 +75,16 @@ module Puppeteer
         @task_manager.terminate_all(Error.new('waitForFunction failed: frame got detached.'))
       end
 
+      # Check if this realm is disposed
+      # @rbs return: bool -- Whether realm is disposed
       def disposed?
         @disposed
       end
 
       # Adopt a handle from another realm into this realm.
       # Mirrors Puppeteer's BidiRealm#adoptHandle implementation.
-      # @param handle [JSHandle] The handle to adopt
-      # @return [JSHandle] Handle that belongs to this realm
+      # @rbs handle: JSHandle -- The handle to adopt
+      # @rbs return: JSHandle -- Handle that belongs to this realm
       def adopt_handle(handle)
         raise ArgumentError, 'handle must be a JSHandle' unless handle.is_a?(JSHandle)
 
@@ -74,8 +93,8 @@ module Puppeteer
 
       # Transfer a handle into this realm, disposing of the original.
       # Mirrors Puppeteer's BidiRealm#transferHandle implementation.
-      # @param handle [JSHandle] Handle that may belong to another realm
-      # @return [JSHandle] Handle adopted into this realm
+      # @rbs handle: JSHandle -- Handle that may belong to another realm
+      # @rbs return: JSHandle -- Handle adopted into this realm
       def transfer_handle(handle)
         raise ArgumentError, 'handle must be a JSHandle' unless handle.is_a?(JSHandle)
 
@@ -88,6 +107,8 @@ module Puppeteer
 
       private
 
+      # Ensure the environment is still active
+      # @rbs return: void
       def ensure_environment_active!
         env = environment
         return unless env.respond_to?(:detached?)
@@ -99,8 +120,11 @@ module Puppeteer
     # Concrete realm that wraps the default window realm for a Frame.
     # https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts
     class FrameRealm < Realm
-      attr_reader :core_realm
+      attr_reader :core_realm #: Core::WindowRealm
 
+      # @rbs frame: Frame -- Frame instance
+      # @rbs core_realm: Core::WindowRealm -- Core window realm
+      # @rbs return: void
       def initialize(frame, core_realm)
         @frame = frame
         @core_realm = core_realm
@@ -111,14 +135,22 @@ module Puppeteer
         setup_core_realm_callbacks
       end
 
+      # Get the frame environment
+      # @rbs return: Frame -- Frame instance
       def environment
         @frame
       end
 
+      # Get the page
+      # @rbs return: Page -- Page instance
       def page
         @frame.page
       end
 
+      # Evaluate JavaScript in this realm
+      # @rbs script: String -- JavaScript code to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the script
+      # @rbs return: untyped -- Evaluation result
       def evaluate(script, *args)
         ensure_environment_active!
 
@@ -129,6 +161,10 @@ module Puppeteer
         Deserializer.deserialize(actual_result)
       end
 
+      # Evaluate JavaScript and return a handle to the result
+      # @rbs script: String -- JavaScript code to evaluate
+      # @rbs *args: untyped -- Arguments to pass to the script
+      # @rbs return: JSHandle -- Handle to the result
       def evaluate_handle(script, *args)
         ensure_environment_active!
 
@@ -138,6 +174,11 @@ module Puppeteer
         JSHandle.from(result['result'], @core_realm)
       end
 
+      # Call a function in the realm
+      # @rbs function_declaration: String -- Function source code
+      # @rbs await_promise: bool -- Whether to await promise results
+      # @rbs **options: untyped -- Additional options
+      # @rbs return: Hash[String, untyped] -- Evaluation result
       def call_function(function_declaration, await_promise, **options)
         ensure_environment_active!
 
@@ -147,6 +188,8 @@ module Puppeteer
         result
       end
 
+      # Get the Puppeteer utility handle
+      # @rbs return: JSHandle -- Puppeteer utility handle
       def puppeteer_util
         return @puppeteer_util_handle if @puppeteer_util_handle
 
@@ -154,10 +197,14 @@ module Puppeteer
         @puppeteer_util_handle = evaluate_handle(script)
       end
 
+      # Get or create lazy arg for Puppeteer utility
+      # @rbs return: LazyArg -- Lazy argument for Puppeteer utility
       def puppeteer_util_lazy_arg
         @puppeteer_util_lazy_arg ||= LazyArg.create { puppeteer_util }
       end
 
+      # Reset the Puppeteer utility handle
+      # @rbs return: void
       def reset_puppeteer_util_handle!
         handle = @puppeteer_util_handle
         @puppeteer_util_handle = nil
@@ -171,12 +218,20 @@ module Puppeteer
         end
       end
 
+      # Wait for a function to return a truthy value
+      # @rbs page_function: String -- JavaScript function to evaluate
+      # @rbs options: Hash[Symbol, untyped] -- Wait options
+      # @rbs *args: untyped -- Arguments to pass to the function
+      # @rbs &block: ((JSHandle) -> void)? -- Optional block called with result
+      # @rbs return: JSHandle -- Handle to the truthy result
       def wait_for_function(page_function, options = {}, *args, &block)
         raise FrameDetachedError if @frame.detached?
 
         super
       end
 
+      # Dispose this realm
+      # @rbs return: void
       def dispose
         reset_puppeteer_util_handle!
         super
@@ -184,6 +239,10 @@ module Puppeteer
 
       private
 
+      # Execute script with core realm
+      # @rbs script: String -- JavaScript code
+      # @rbs args: Array[untyped] -- Arguments
+      # @rbs return: Async::Task[Hash[String, untyped]] -- Evaluation result
       def execute_with_core(script, args)
         script_trimmed = script.strip
 
@@ -203,6 +262,9 @@ module Puppeteer
         end
       end
 
+      # Handle evaluation exception from result
+      # @rbs result: Hash[String, untyped] -- Evaluation result containing exception
+      # @rbs return: void
       def handle_evaluation_exception(result)
         exception_details = result['exceptionDetails']
         return unless exception_details
@@ -220,6 +282,8 @@ module Puppeteer
         raise error_message
       end
 
+      # Set up core realm event callbacks
+      # @rbs return: void
       def setup_core_realm_callbacks
         @core_realm.environment = @frame if @core_realm.respond_to?(:environment=)
 

data/lib/puppeteer/bidi/serializer.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'json'
 require 'puppeteer/bidi/lazy_arg'