puppeteer-ruby 0.45.6 → 0.50.0.alpha5

data/lib/puppeteer/page.rb

@@ -1,5 +1,8 @@
+# rbs_inline: enabled
+
 require 'base64'
 require 'json'
+require 'objspace'
 require "stringio"
 
 require_relative './page/metrics'
@@ -13,13 +16,14 @@ class Puppeteer::Page
   include Puppeteer::IfPresent
   using Puppeteer::DefineAsyncMethod
 
-  # @param {!Puppeteer.CDPSession} client
-  # @param {!Puppeteer.Target} target
-  # @param {boolean} ignoreHTTPSErrors
-  # @param {?Puppeteer.Viewport} defaultViewport
-  # @return {!Promise<!Page>}
-  def self.create(client, target, ignore_https_errors, default_viewport)
-    page = Puppeteer::Page.new(client, target, ignore_https_errors)
+  # @rbs client: Puppeteer::CDPSession -- CDP session for the page
+  # @rbs target: Puppeteer::Target -- Target associated with the page
+  # @rbs ignore_https_errors: bool -- Ignore HTTPS errors
+  # @rbs default_viewport: Puppeteer::Viewport? -- Default viewport for new pages
+  # @rbs network_enabled: bool -- Whether network events are enabled
+  # @rbs return: Puppeteer::Page -- Created page instance
+  def self.create(client, target, ignore_https_errors, default_viewport, network_enabled: true)
+    page = Puppeteer::Page.new(client, target, ignore_https_errors, network_enabled: network_enabled)
     page.init
     if default_viewport
       page.viewport = default_viewport
@@ -27,30 +31,40 @@ class Puppeteer::Page
     page
   end
 
-  # @param {!Puppeteer.CDPSession} client
-  # @param {!Puppeteer.Target} target
-  # @param {boolean} ignoreHTTPSErrors
-  def initialize(client, target, ignore_https_errors)
+  # @rbs client: Puppeteer::CDPSession -- CDP session for the page
+  # @rbs target: Puppeteer::Target -- Target associated with the page
+  # @rbs ignore_https_errors: bool -- Ignore HTTPS errors
+  # @rbs network_enabled: bool -- Whether network events are enabled
+  # @rbs return: void -- No return value
+  def initialize(client, target, ignore_https_errors, network_enabled: true)
     @closed = false
     @client = client
     @target = target
+    @tab_id = nil
     @keyboard = Puppeteer::Keyboard.new(client)
     @mouse = Puppeteer::Mouse.new(client, @keyboard)
     @timeout_settings = Puppeteer::TimeoutSettings.new
     @touchscreen = Puppeteer::TouchScreen.new(client, @keyboard)
     # @accessibility = Accessibility.new(client)
-    @frame_manager = Puppeteer::FrameManager.new(client, self, ignore_https_errors, @timeout_settings)
+    @frame_manager = Puppeteer::FrameManager.new(client, self, ignore_https_errors, @timeout_settings, network_enabled: network_enabled)
     @emulation_manager = Puppeteer::EmulationManager.new(client)
     @tracing = Puppeteer::Tracing.new(client)
     @page_bindings = {}
+    @page_binding_ids = {}
     @coverage = Puppeteer::Coverage.new(client)
     @javascript_enabled = true
     @screenshot_task_queue = ScreenshotTaskQueue.new
+    @inflight_requests = Set.new
+    @request_intercepted_listener_map = ObjectSpace::WeakMap.new
+    @attached_sessions = Set.new
 
     @workers = {}
     @user_drag_interception_enabled = false
+    @service_worker_bypassed = false
 
-    @target.target_manager.add_target_interceptor(@client, method(:handle_attached_to_target))
+    @attached_session_listener_id = @client.add_event_listener(CDPSessionEmittedEvents::Ready) do |session|
+      handle_attached_to_session(session)
+    end
     @target_gone_listener_id = @target.target_manager.add_event_listener(
       TargetManagerEmittedEvents::TargetGone,
       &method(:handle_detached_from_target)
@@ -68,15 +82,21 @@ class Puppeteer::Page
 
     network_manager = @frame_manager.network_manager
     network_manager.on_event(NetworkManagerEmittedEvents::Request) do |event|
+      @inflight_requests.add(event)
       emit_event(PageEmittedEvents::Request, event)
     end
     network_manager.on_event(NetworkManagerEmittedEvents::Response) do |event|
       emit_event(PageEmittedEvents::Response, event)
     end
+    network_manager.on_event(NetworkManagerEmittedEvents::RequestServedFromCache) do |event|
+      emit_event(PageEmittedEvents::RequestServedFromCache, event)
+    end
     network_manager.on_event(NetworkManagerEmittedEvents::RequestFailed) do |event|
+      @inflight_requests.delete(event)
       emit_event(PageEmittedEvents::RequestFailed, event)
     end
     network_manager.on_event(NetworkManagerEmittedEvents::RequestFinished) do |event|
+      @inflight_requests.delete(event)
       emit_event(PageEmittedEvents::RequestFinished, event)
     end
     @file_chooser_interception_is_disabled = false
@@ -112,8 +132,9 @@ class Puppeteer::Page
     @client.on_event('Page.fileChooserOpened') do |event|
       handle_file_chooser(event)
     end
-    @target.is_closed_promise.then do
-      @target.target_manager.remove_target_interceptor(@client, method(:handle_attached_to_target))
+    Async do
+      @target.is_closed_promise.wait
+      @client.remove_event_listener(@attached_session_listener_id)
       @target.target_manager.remove_event_listener(@target_gone_listener_id)
 
       emit_event(PageEmittedEvents::Close)
@@ -130,63 +151,137 @@ class Puppeteer::Page
     emit_event(PageEmittedEvents::WorkerDestroyed, worker)
   end
 
-  private def handle_attached_to_target(target, _)
+  private def handle_attached_to_session(session)
+    return if @attached_sessions.include?(session)
+    @attached_sessions << session
+    session.on(CDPSessionEmittedEvents::Ready) do |child_session|
+      handle_attached_to_session(child_session)
+    end
+
+    target = session.target
+    return unless target
+    handle_attached_to_target(target)
+  end
+
+  private def handle_attached_to_target(target)
     @frame_manager.handle_attached_to_target(target)
-    if target.raw_type == 'worker'
-      #   const session = createdTarget._session();
-      #   assert(session);
-      #   const worker = new WebWorker(
-      #     session,
-      #     createdTarget.url(),
-      #     this.#addConsoleMessage.bind(this),
-      #     this.#handleException.bind(this)
-      #   );
-      #   this.#workers.set(session.id(), worker);
-      #   this.emit(PageEmittedEvents.WorkerCreated, worker);
+    session = target.session
+    if session && target.raw_type != 'worker'
+      @frame_manager.network_manager.add_client(session)
     end
+    if target.raw_type == 'worker'
+      return unless session
 
-    if target.session
-      @target.target_manager.add_target_interceptor(target.session, method(:handle_attached_to_target))
+      console_api_called = lambda do |world, event|
+        values = event['args'].map do |arg|
+          remote_object = Puppeteer::RemoteObject.new(arg)
+          Puppeteer::JSHandle.create(context: world.execution_context, remote_object: remote_object)
+        end
+        add_console_message(event['type'], values, event['stackTrace'])
+      end
+      exception_thrown = method(:handle_exception)
+
+      worker = Puppeteer::CdpWebWorker.new(
+        session,
+        target.url,
+        target.target_id,
+        target.raw_type,
+        console_api_called,
+        exception_thrown,
+        network_manager: @frame_manager.network_manager,
+      )
+      @workers[session.id] = worker
+      emit_event(PageEmittedEvents::WorkerCreated, worker)
     end
+
   end
 
+  # @rbs return: Array[untyped] -- Initialization results
   def init
-    await_all(
+    Puppeteer::AsyncUtils.await_promise_all(
       @frame_manager.async_init(@target.target_id),
       @client.async_send_message('Performance.enable'),
       @client.async_send_message('Log.enable'),
     )
   end
 
+  # @rbs return: bool -- Whether drag interception is enabled
   def drag_interception_enabled?
     @user_drag_interception_enabled
   end
   alias_method :drag_interception_enabled, :drag_interception_enabled?
 
-  # @param event_name [Symbol]
+  # @rbs event_name: (String | Symbol) -- Page event name
+  # @rbs &block: ^(untyped) -> void -- Event handler
+  # @rbs return: String -- Listener ID
   def on(event_name, &block)
     unless PageEmittedEvents.values.include?(event_name.to_s)
       raise ArgumentError.new("Unknown event name: #{event_name}. Known events are #{PageEmittedEvents.values.to_a.join(", ")}")
     end
 
     if event_name.to_s == 'request'
-      super('request') do |req|
-        req.enqueue_intercept_action(-> { block.call(req) })
+      wrapped = ->(req) { req.enqueue_intercept_action(-> { block.call(req) }) }
+      if (listeners = @request_intercepted_listener_map[block])
+        listeners << wrapped
+      else
+        @request_intercepted_listener_map[block] = [wrapped]
       end
+      super('request', &wrapped)
+    else
+      super(event_name.to_s, &block)
     end
-
-    super(event_name.to_s, &block)
   end
 
-  # @param event_name [Symbol]
+  # @rbs event_name: (String | Symbol) -- Page event name
+  # @rbs &block: ^(untyped) -> void -- Event handler
+  # @rbs return: String -- Listener ID
   def once(event_name, &block)
     unless PageEmittedEvents.values.include?(event_name.to_s)
       raise ArgumentError.new("Unknown event name: #{event_name}. Known events are #{PageEmittedEvents.values.to_a.join(", ")}")
     end
 
-    super(event_name.to_s, &block)
+    if event_name.to_s == 'request'
+      wrapped = ->(req) { req.enqueue_intercept_action(-> { block.call(req) }) }
+      if (listeners = @request_intercepted_listener_map[block])
+        listeners << wrapped
+      else
+        @request_intercepted_listener_map[block] = [wrapped]
+      end
+      super('request', &wrapped)
+    else
+      super(event_name.to_s, &block)
+    end
+  end
+
+  # @rbs event_name_or_id: (String | Symbol) -- Page event name or listener ID
+  # @rbs listener: Proc? -- Event handler to remove
+  # @rbs return: void -- No return value
+  def off(event_name_or_id, listener = nil, &block)
+    listener ||= block
+    if listener && PageEmittedEvents.values.include?(event_name_or_id.to_s)
+      event_name = event_name_or_id.to_s
+      if event_name == 'request'
+        listeners = @request_intercepted_listener_map[listener]
+        wrapped = listeners&.shift
+        return unless wrapped
+        if listeners.empty?
+          if @request_intercepted_listener_map.respond_to?(:delete)
+            @request_intercepted_listener_map.delete(listener)
+          else
+            @request_intercepted_listener_map[listener] = nil
+          end
+        end
+        super(event_name, wrapped)
+      else
+        super(event_name, listener)
+      end
+    else
+      super(event_name_or_id)
+    end
   end
 
+  # @rbs event: Hash[String, untyped] -- File chooser event payload
+  # @rbs return: void -- No return value
   def handle_file_chooser(event)
     return if @file_chooser_interceptors.empty?
 
@@ -196,33 +291,29 @@ class Puppeteer::Page
     @file_chooser_interceptors.clear
     file_chooser = Puppeteer::FileChooser.new(element, event)
     interceptors.each do |promise|
-      promise.fulfill(file_chooser)
+      promise.resolve(file_chooser)
     end
   end
 
-  class FileChooserTimeoutError < StandardError
-    def initialize(timeout:)
-      super("waiting for filechooser failed: timeout #{timeout}ms exceeded")
-    end
-  end
-
-  # @param timeout [Integer]
-  # @return [Puppeteer::FileChooser]
+  # @rbs timeout: Numeric? -- Timeout in milliseconds
+  # @rbs return: Puppeteer::FileChooser -- File chooser handle
   def wait_for_file_chooser(timeout: nil)
     if @file_chooser_interceptors.empty?
       @client.send_message('Page.setInterceptFileChooserDialog', enabled: true)
     end
 
     option_timeout = timeout || @timeout_settings.timeout
-    promise = resolvable_future
+    promise = Async::Promise.new
     @file_chooser_interceptors << promise
 
     begin
-      Timeout.timeout(option_timeout / 1000.0) do
-        promise.value!
+      if option_timeout == 0
+        promise.wait
+      else
+        Puppeteer::AsyncUtils.async_timeout(option_timeout, promise).wait
       end
-    rescue Timeout::Error
-      raise FileChooserTimeoutError.new(timeout: option_timeout)
+    rescue Async::TimeoutError
+      raise Puppeteer::TimeoutError.new("Waiting for `FileChooser` failed: #{option_timeout}ms exceeded")
     ensure
       @file_chooser_interceptors.delete(promise)
     end
@@ -230,23 +321,46 @@ class Puppeteer::Page
 
   define_async_method :async_wait_for_file_chooser
 
-  # @param [Puppeteer::Geolocation]
+  # @rbs geolocation: Puppeteer::Geolocation -- Geolocation override
+  # @rbs return: void -- No return value
   def geolocation=(geolocation)
     @client.send_message('Emulation.setGeolocationOverride', geolocation.to_h)
   end
 
-  attr_reader :javascript_enabled, :target, :client
+  attr_reader :javascript_enabled, :service_worker_bypassed, :target, :client
+
+  # @rbs return: String -- Tab target id
+  def _tab_id
+    return @tab_id if @tab_id
+
+    parent_session = @client.respond_to?(:parent_session) ? @client.parent_session : nil
+    @tab_id = parent_session&.target&.target_id || @target.target_id
+  end
+
+  # @rbs other: Object -- Other object to compare
+  # @rbs return: bool -- Equality result
+  def ==(other)
+    other = other.__getobj__ if other.is_a?(Puppeteer::ReactorRunner::Proxy)
+    return true if equal?(other)
+    return false unless other.is_a?(Puppeteer::Page)
+    return false unless @target&.target_id && other.target&.target_id
+
+    @target.target_id == other.target.target_id
+  end
   alias_method :javascript_enabled?, :javascript_enabled
+  alias_method :service_worker_bypassed?, :service_worker_bypassed
 
+  # @rbs return: Puppeteer::Browser -- Owning browser
   def browser
     @target.browser
   end
 
+  # @rbs return: Puppeteer::BrowserContext -- Owning browser context
   def browser_context
     @target.browser_context
   end
 
-  class TargetCrashedError < StandardError; end
+  class TargetCrashedError < Puppeteer::Error; end
 
   private def handle_target_crashed
     emit_event(PageEmittedEvents::Error, TargetCrashedError.new('Page crashed!'))
@@ -275,58 +389,79 @@ class Puppeteer::Page
     end
   end
 
+  # @rbs return: Puppeteer::Frame -- Main frame
   def main_frame
     @frame_manager.main_frame
   end
 
-  attr_reader :touch_screen, :coverage, :tracing, :accessibility
+  attr_reader :touchscreen, :coverage, :tracing, :accessibility
+  alias_method :touch_screen, :touchscreen
 
+  # @rbs block: Proc? -- Optional block for instance_eval
+  # @rbs return: Puppeteer::Keyboard -- Keyboard instance
   def keyboard(&block)
     @keyboard.instance_eval(&block) unless block.nil?
 
     @keyboard
   end
 
+  # @rbs return: Array[Puppeteer::Frame] -- All frames
   def frames
     @frame_manager.frames
   end
 
+  # @rbs return: Array[untyped] -- Active web workers
   def workers
     @workers.values
   end
 
-  # @param value [Bool]
+  # @rbs value: bool -- Enable request interception
+  # @rbs return: void -- No return value
   def request_interception=(value)
     @frame_manager.network_manager.request_interception = value
   end
 
+  # @rbs enabled: bool -- Enable drag interception
+  # @rbs return: void -- No return value
   def drag_interception_enabled=(enabled)
     @user_drag_interception_enabled = enabled
     @client.send_message('Input.setInterceptDrags', enabled: enabled)
   end
 
+  # @rbs bypass: bool -- Bypass service workers
+  # @rbs return: void -- No return value
+  def service_worker_bypassed=(bypass)
+    @service_worker_bypassed = bypass
+    @client.send_message('Network.setBypassServiceWorker', bypass: bypass)
+  end
+
+  # @rbs enabled: bool -- Enable offline mode
+  # @rbs return: void -- No return value
   def offline_mode=(enabled)
     @frame_manager.network_manager.offline_mode = enabled
   end
 
-  # @param network_condition [Puppeteer::NetworkCondition|nil]
+  # @rbs network_condition: Puppeteer::NetworkCondition? -- Network condition override
+  # @rbs return: void -- No return value
   def emulate_network_conditions(network_condition)
     @frame_manager.network_manager.emulate_network_conditions(network_condition)
   end
 
-  # @param {number} timeout
+  # @rbs timeout: Numeric? -- Default navigation timeout in milliseconds
+  # @rbs return: void -- No return value
   def default_navigation_timeout=(timeout)
     @timeout_settings.default_navigation_timeout = timeout
   end
 
-  # @param {number} timeout
+  # @rbs timeout: Numeric? -- Default timeout in milliseconds
+  # @rbs return: void -- No return value
   def default_timeout=(timeout)
     @timeout_settings.default_timeout = timeout
   end
 
   # `$()` in JavaScript.
-  # @param {string} selector
-  # @return {!Promise<?Puppeteer.ElementHandle>}
+  # @rbs selector: String -- CSS selector
+  # @rbs return: Puppeteer::ElementHandle? -- Matching element or nil
   def query_selector(selector)
     main_frame.query_selector(selector)
   end
@@ -335,18 +470,19 @@ class Puppeteer::Page
   define_async_method :async_query_selector
 
   # `$$()` in JavaScript.
-  # @param {string} selector
-  # @return {!Promise<!Array<!Puppeteer.ElementHandle>>}
-  def query_selector_all(selector)
-    main_frame.query_selector_all(selector)
+  # @rbs selector: String -- CSS selector
+  # @rbs isolate: bool? -- Use isolated world for queries
+  # @rbs return: Array[Puppeteer::ElementHandle] -- Matching elements
+  def query_selector_all(selector, isolate: nil)
+    main_frame.query_selector_all(selector, isolate: isolate)
   end
   alias_method :SS, :query_selector_all
 
   define_async_method :async_query_selector_all
 
-  # @param {Function|string} pageFunction
-  # @param {!Array<*>} args
-  # @return {!Promise<!Puppeteer.JSHandle>}
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @rbs return: Puppeteer::JSHandle -- Handle to evaluation result
   def evaluate_handle(page_function, *args)
     context = main_frame.execution_context
     context.evaluate_handle(page_function, *args)
@@ -354,17 +490,18 @@ class Puppeteer::Page
 
   define_async_method :async_evaluate_handle
 
-  # @param {!Puppeteer.JSHandle} prototypeHandle
-  # @return {!Promise<!Puppeteer.JSHandle>}
+  # @rbs prototype_handle: Puppeteer::JSHandle -- Prototype handle
+  # @rbs return: Puppeteer::JSHandle -- Handle to query result
   def query_objects(prototype_handle)
     context = main_frame.execution_context
     context.query_objects(prototype_handle)
   end
 
   # `$eval()` in JavaScript.
-  # @param selector [String]
-  # @param page_function [String]
-  # @return [Object]
+  # @rbs selector: String -- CSS selector
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @rbs return: untyped -- Evaluation result
   def eval_on_selector(selector, page_function, *args)
     main_frame.eval_on_selector(selector, page_function, *args)
   end
@@ -373,9 +510,10 @@ class Puppeteer::Page
   define_async_method :async_eval_on_selector
 
   # `$$eval()` in JavaScript.
-  # @param selector [String]
-  # @param page_function [String]
-  # @return [Object]
+  # @rbs selector: String -- CSS selector
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @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
@@ -384,15 +522,16 @@ class Puppeteer::Page
   define_async_method :async_eval_on_selector_all
 
   # `$x()` in JavaScript. $ is not allowed to use as a method name in Ruby.
-  # @param {string} expression
-  # @return {!Promise<!Array<!Puppeteer.ElementHandle>>}
+  # @rbs expression: String -- XPath expression
+  # @rbs return: Array[Puppeteer::ElementHandle] -- Matching elements
   def Sx(expression)
     main_frame.Sx(expression)
   end
 
   define_async_method :async_Sx
 
-  # @return [Array<Hash>]
+  # @rbs urls: Array[String] -- URLs to fetch cookies for
+  # @rbs return: Array[Hash[String, untyped]] -- Cookies list
   def cookies(*urls)
     @client.send_message('Network.getCookies', urls: (urls.empty? ? [url] : urls))['cookies']
   end
@@ -406,6 +545,8 @@ class Puppeteer::Page
     raise ArgumentError.new("Each coookie must have #{requires.join(" and ")} attribute.")
   end
 
+  # @rbs cookies: Array[Hash[Symbol | String, untyped]] -- cookies parameter
+  # @rbs return: void -- No return value
   def delete_cookie(*cookies)
     assert_cookie_params(cookies, requires: %i(name))
 
@@ -417,6 +558,8 @@ class Puppeteer::Page
     end
   end
 
+  # @rbs cookies: Array[Hash[Symbol | String, untyped]] -- cookies parameter
+  # @rbs return: void -- No return value
   def set_cookie(*cookies)
     assert_cookie_params(cookies, requires: %i(name value))
 
@@ -434,24 +577,27 @@ class Puppeteer::Page
     end
   end
 
-  # @param url [String?]
-  # @param path [String?]
-  # @param content [String?]
-  # @param type [String?]
-  # @param id [String?]
+  # @rbs url: String? -- Script URL
+  # @rbs path: String? -- Path to script file
+  # @rbs content: String? -- Script contents
+  # @rbs type: String? -- Script type
+  # @rbs id: String? -- Script element ID
+  # @rbs return: Puppeteer::ElementHandle -- Script element handle
   def add_script_tag(url: nil, path: nil, content: nil, type: nil, id: nil)
     main_frame.add_script_tag(url: url, path: path, content: content, type: type, id: id)
   end
 
-  # @param url [String?]
-  # @param path [String?]
-  # @param content [String?]
+  # @rbs url: String? -- Stylesheet URL
+  # @rbs path: String? -- Path to stylesheet file
+  # @rbs content: String? -- Stylesheet contents
+  # @rbs return: Puppeteer::ElementHandle -- Style element handle
   def add_style_tag(url: nil, path: nil, content: nil)
     main_frame.add_style_tag(url: url, path: path, content: content)
   end
 
-  # @param name [String]
-  # @param puppeteer_function [Proc]
+  # @rbs name: String -- Binding name
+  # @rbs puppeteer_function: Proc -- Ruby callback
+  # @rbs return: void -- No return value
   def expose_function(name, puppeteer_function)
     if @page_bindings[name]
       raise ArgumentError.new("Failed to add page binding with name `#{name}` already exists!")
@@ -486,42 +632,79 @@ class Puppeteer::Page
 
     source = JavaScriptFunction.new(add_page_binding, ['exposedFun', name]).source
     @client.send_message('Runtime.addBinding', name: name)
-    @client.send_message('Page.addScriptToEvaluateOnNewDocument', source: source)
+    script = @client.send_message('Page.addScriptToEvaluateOnNewDocument', source: source)
+    @page_binding_ids[name] = script['identifier']
 
     promises = @frame_manager.frames.map do |frame|
       frame.async_evaluate("() => #{source}")
     end
-    await_all(*promises)
+    Puppeteer::AsyncUtils.await_promise_all(*promises)
+
+    nil
+  end
+
+  # @rbs name: String -- Binding name
+  # @rbs return: void -- No return value
+  def remove_exposed_function(name)
+    identifier = @page_binding_ids[name]
+    unless identifier
+      raise ArgumentError.new("Function with name \"#{name}\" does not exist")
+    end
+
+    @page_binding_ids.delete(name)
+    @page_bindings.delete(name)
+
+    @client.send_message('Runtime.removeBinding', name: name)
+    @client.send_message('Page.removeScriptToEvaluateOnNewDocument', identifier: identifier)
 
+    remove_script = '(name) => { delete window[name]; }'
+    @frame_manager.frames.each do |frame|
+      frame.evaluate(remove_script, name)
+    rescue StandardError
+      nil
+    end
     nil
   end
 
-  # @param username [String?]
-  # @param password [String?]
+  # @rbs username: String? -- HTTP basic auth username
+  # @rbs password: String? -- HTTP basic auth password
+  # @rbs return: void -- No return value
   def authenticate(username: nil, password: nil)
     @frame_manager.network_manager.authenticate(username: username, password: password)
   end
 
-  # @param headers [Hash]
+  # @rbs headers: Hash[String, String] -- Extra HTTP headers
+  # @rbs return: void -- No return value
   def extra_http_headers=(headers)
     @frame_manager.network_manager.extra_http_headers = headers
   end
 
-  # @param user_agent [String]
-  # @param user_agent_metadata [Hash]
+  # @rbs user_agent: String -- User agent string
+  # @rbs user_agent_metadata: Hash[String, untyped]? -- User agent metadata
+  # @rbs return: void -- No return value
   def set_user_agent(user_agent, user_agent_metadata = nil)
     @frame_manager.network_manager.set_user_agent(user_agent, user_agent_metadata)
   end
   alias_method :user_agent=, :set_user_agent
 
+  # @rbs return: Puppeteer::Page::Metrics -- Page metrics
   def metrics
     response = @client.send_message('Performance.getMetrics')
     Metrics.new(response['metrics'])
   end
 
-  class PageError < StandardError ; end
+  class PageError < Puppeteer::Error ; end
 
   private def handle_exception(exception_details)
+    exception = exception_details['exception']
+    if exception
+      is_error_object = exception['type'] == 'object' && exception['subtype'] == 'error'
+      if !is_error_object && !exception.key?('objectId')
+        emit_event(PageEmittedEvents::PageError, Puppeteer::RemoteObject.new(exception).value)
+        return
+      end
+    end
+
     message = Puppeteer::ExceptionDetails.new(exception_details).message
     err = PageError.new(message)
     #   err.stack = ''; // Don't report clientside error with a node stack attached
@@ -554,6 +737,8 @@ class Puppeteer::Page
     add_console_message(event['type'], values, event['stackTrace'])
   end
 
+  # @rbs event: Hash[String, untyped] -- Binding called payload
+  # @rbs return: void -- No return value
   def handle_binding_called(event)
     execution_context_id = event['executionContextId']
     payload =
@@ -595,13 +780,18 @@ class Puppeteer::Page
         JavaScriptFunction.new(deliver_error, [name, seq, err.message]).source
       end
 
-    @client.async_send_message('Runtime.evaluate', expression: expression, contextId: execution_context_id).rescue do |error|
+    Async do
+      @client.async_send_message('Runtime.evaluate', expression: expression, contextId: execution_context_id).wait
+    rescue => error
       debug_puts(error)
     end
   end
 
   private def add_console_message(type, args, stack_trace)
-    text_tokens = args.map { |arg| arg.remote_object.value }
+    text_tokens = args.map do |arg|
+      value = arg.remote_object.value
+      value.nil? ? arg.to_s : value
+    end
 
     stack_trace_locations =
       if stack_trace && stack_trace['callFrames']
@@ -624,7 +814,7 @@ class Puppeteer::Page
     unless %w(alert confirm prompt beforeunload).include?(dialog_type)
       raise ArgumentError.new("Unknown javascript dialog type: #{dialog_type}")
     end
-    dialog = Puppeteer::Dialog.new(@client,
+    dialog = Puppeteer::CdpDialog.new(@client,
               type: dialog_type,
               message: event['message'],
               default_value: event['defaultPrompt'])
@@ -641,72 +831,101 @@ class Puppeteer::Page
     @client.send_message('Emulation.setDefaultBackgroundColorOverride')
   end
 
-  # @return [String]
+  # @rbs return: String? -- Page URL
   def url
     main_frame.url
   end
 
-  # @return [String]
+  # @rbs return: String -- Page HTML content
   def content
     main_frame.content
   end
 
-  # @param html [String]
-  # @param timeout [Integer]
-  # @param wait_until [String|Array<String>]
+  # @rbs html: String -- HTML content
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs return: void -- No return value
   def set_content(html, timeout: nil, wait_until: nil)
     main_frame.set_content(html, timeout: timeout, wait_until: wait_until)
   end
 
-  # @param html [String]
+  # @rbs html: String -- HTML content
+  # @rbs return: void -- No return value
   def content=(html)
     main_frame.set_content(html)
   end
 
-  # @param url [String]
-  # @param rederer [String]
-  # @param timeout [number|nil]
-  # @param wait_until [string|nil] 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
-  def goto(url, referer: nil, timeout: nil, wait_until: nil)
-    main_frame.goto(url, referer: referer, timeout: timeout, wait_until: wait_until)
+  # @rbs url: String -- URL to navigate
+  # @rbs referer: String? -- Referer header value
+  # @rbs referer: String? -- Referer header value
+  # @rbs referrer_policy: String? -- Referrer policy
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs return: Puppeteer::HTTPResponse? -- Navigation response
+  def goto(url, referer: nil, referrer_policy: nil, timeout: nil, wait_until: nil)
+    main_frame.goto(
+      url,
+      referer: referer,
+      referrer_policy: referrer_policy,
+      timeout: timeout,
+      wait_until: wait_until,
+    )
   end
 
-  # @param timeout [number|nil]
-  # @param wait_until [string|nil] 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
-  # @return [Puppeteer::HTTPResponse]
-  def reload(timeout: nil, wait_until: nil)
-    wait_for_navigation(timeout: timeout, wait_until: wait_until) do
-      @client.send_message('Page.reload')
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs ignore_cache: bool? -- Skip cache when reloading
+  # @rbs return: Puppeteer::HTTPResponse? -- Navigation response
+  def reload(timeout: nil, wait_until: nil, ignore_cache: nil)
+    params = {}
+    params[:ignoreCache] = ignore_cache unless ignore_cache.nil?
+
+    wait_for_navigation(timeout: timeout, wait_until: wait_until, ignore_same_document_navigation: true) do
+      if params.empty?
+        @client.send_message('Page.reload')
+      else
+        @client.send_message('Page.reload', **params)
+      end
     end
   end
 
-  def wait_for_navigation(timeout: nil, wait_until: nil)
-    main_frame.send(:wait_for_navigation, timeout: timeout, wait_until: wait_until)
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs ignore_same_document_navigation: bool -- Ignore same-document navigation
+  # @rbs return: Puppeteer::HTTPResponse? -- Navigation response
+  def wait_for_navigation(timeout: nil, wait_until: nil, ignore_same_document_navigation: false)
+    main_frame.send(
+      :wait_for_navigation,
+      timeout: timeout,
+      wait_until: wait_until,
+      ignore_same_document_navigation: ignore_same_document_navigation,
+    )
   end
 
   # @!method async_wait_for_navigation(timeout: nil, wait_until: nil)
   #
-  # @param timeout [number|nil]
-  # @param wait_until [string|nil] 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
   define_async_method :async_wait_for_navigation
 
   private def wait_for_network_manager_event(event_name, predicate:, timeout:)
     option_timeout = timeout || @timeout_settings.timeout
 
-    promise = resolvable_future
+    promise = Async::Promise.new
 
     listener_id = @frame_manager.network_manager.add_event_listener(event_name) do |event_target|
-      if predicate.call(event_target)
-        promise.fulfill(event_target)
+      if Puppeteer::AsyncUtils.await(predicate.call(event_target))
+        promise.resolve(event_target)
       end
     end
 
     begin
-      # Timeout.timeout(0) means "no limit" for timeout.
-      Timeout.timeout(option_timeout / 1000.0) do
-        await_any(promise, session_close_promise)
+      if option_timeout == 0
+        Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+      else
+        Puppeteer::AsyncUtils.async_timeout(option_timeout, -> {
+          Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+        }).wait
       end
-    rescue Timeout::Error
+    rescue Async::TimeoutError
       raise Puppeteer::TimeoutError.new("waiting for #{event_name} failed: timeout #{option_timeout}ms exceeded")
     ensure
       @frame_manager.network_manager.remove_event_listener(listener_id)
@@ -716,22 +935,25 @@ class Puppeteer::Page
   private def wait_for_frame_manager_event(*event_names, predicate:, timeout:)
     option_timeout = timeout || @timeout_settings.timeout
 
-    promise = resolvable_future
+    promise = Async::Promise.new
 
     listener_ids = event_names.map do |event_name|
       @frame_manager.add_event_listener(event_name) do |event_target|
-        if predicate.call(event_target)
-          promise.fulfill(event_target) unless promise.resolved?
+        if Puppeteer::AsyncUtils.await(predicate.call(event_target))
+          promise.resolve(event_target) unless promise.resolved?
         end
       end
     end
 
     begin
-      # Timeout.timeout(0) means "no limit" for timeout.
-      Timeout.timeout(option_timeout / 1000.0) do
-        await_any(promise, session_close_promise)
+      if option_timeout == 0
+        Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+      else
+        Puppeteer::AsyncUtils.async_timeout(option_timeout, -> {
+          Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+        }).wait
       end
-    rescue Timeout::Error
+    rescue Async::TimeoutError
       raise Puppeteer::TimeoutError.new("waiting for #{event_names.join(" or ")} failed: timeout #{option_timeout}ms exceeded")
     ensure
       listener_ids.each do |listener_id|
@@ -741,13 +963,17 @@ class Puppeteer::Page
   end
 
   private def session_close_promise
-    @disconnect_promise ||= resolvable_future do |future|
+    @disconnect_promise ||= Async::Promise.new.tap do |future|
       @client.observe_first(CDPSessionEmittedEvents::Disconnected) do
         future.reject(Puppeteer::CDPSession::Error.new('Target Closed'))
       end
     end
   end
 
+  # @rbs url: String? -- URL to match
+  # @rbs predicate: Proc? -- Predicate to match
+  # @rbs timeout: Numeric? -- Timeout in milliseconds
+  # @rbs return: Puppeteer::HTTPRequest -- Matching request
   def wait_for_request(url: nil, predicate: nil, timeout: nil)
     if !url && !predicate
       raise ArgumentError.new('url or predicate must be specified')
@@ -778,10 +1004,12 @@ class Puppeteer::Page
   # Waits until request matches the given predicate
   #  wait_for_request(predicate: -> (req){ req.url.start_with?('https://example.com/search') })
   #
-  # @param url [String]
-  # @param predicate [Proc(Puppeteer::HTTPRequest -> Boolean)]
   define_async_method :async_wait_for_request
 
+  # @rbs url: String? -- URL to match
+  # @rbs predicate: Proc? -- Predicate to match
+  # @rbs timeout: Numeric? -- Timeout in milliseconds
+  # @rbs return: Puppeteer::HTTPResponse -- Matching response
   def wait_for_response(url: nil, predicate: nil, timeout: nil)
     if !url && !predicate
       raise ArgumentError.new('url or predicate must be specified')
@@ -804,10 +1032,68 @@ class Puppeteer::Page
 
   # @!method async_wait_for_response(url: nil, predicate: nil, timeout: nil)
   #
-  # @param url [String]
-  # @param predicate [Proc(Puppeteer::HTTPRequest -> Boolean)]
   define_async_method :async_wait_for_response
 
+  # @rbs idle_time: Numeric -- Idle time to wait for in milliseconds
+  # @rbs timeout: Numeric? -- Timeout in milliseconds
+  # @rbs concurrency: Integer -- Allowed number of concurrent requests
+  # @rbs return: void -- No return value
+  def wait_for_network_idle(idle_time: 500, timeout: nil, concurrency: 0)
+    option_timeout = timeout || @timeout_settings.timeout
+
+    promise = Async::Promise.new
+    idle_timer = nil
+
+    schedule_idle = lambda do
+      return if @inflight_requests.size > concurrency
+
+      idle_timer&.stop
+      idle_timer = Async do
+        Puppeteer::AsyncUtils.sleep_seconds(idle_time / 1000.0)
+        unless promise.resolved? || @inflight_requests.size > concurrency
+          promise.resolve(nil)
+        end
+      end
+    end
+
+    # Use raw listener to avoid request interception queue delaying idle tracking.
+    request_listener = add_event_listener('request') do
+      idle_timer&.stop
+      idle_timer = nil
+    end
+    request_finished_listener = on('requestfinished') do
+      schedule_idle.call
+    end
+    request_failed_listener = on('requestfailed') do
+      schedule_idle.call
+    end
+
+    schedule_idle.call
+
+    begin
+      if option_timeout == 0
+        Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+      else
+        Puppeteer::AsyncUtils.async_timeout(option_timeout, -> {
+          Puppeteer::AsyncUtils.await_promise_race(promise, session_close_promise)
+        }).wait
+      end
+    rescue Async::TimeoutError
+      raise Puppeteer::TimeoutError.new("waiting for network idle failed: timeout #{option_timeout}ms exceeded")
+    ensure
+      off(request_listener)
+      off(request_finished_listener)
+      off(request_failed_listener)
+      idle_timer&.stop
+    end
+  end
+
+  define_async_method :async_wait_for_network_idle
+
+  # @rbs url: String? -- URL to match
+  # @rbs predicate: Proc? -- Predicate to match
+  # @rbs timeout: Numeric? -- Timeout in milliseconds
+  # @rbs return: Puppeteer::Frame -- Matching frame
   def wait_for_frame(url: nil, predicate: nil, timeout: nil)
     if !url && !predicate
       raise ArgumentError.new('url or predicate must be specified')
@@ -836,18 +1122,18 @@ class Puppeteer::Page
 
   # @!method async_wait_for_frame(url: nil, predicate: nil, timeout: nil)
   #
-  # @param url [String]
-  # @param predicate [Proc(Puppeteer::Frame -> Boolean)]
   define_async_method :async_wait_for_frame
 
-  # @param timeout [number|nil]
-  # @param wait_until [string|nil] 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs return: Puppeteer::HTTPResponse? -- Navigation response
   def go_back(timeout: nil, wait_until: nil)
     go(-1, timeout: timeout, wait_until: wait_until)
   end
 
-  # @param timeout [number|nil]
-  # @param wait_until [string|nil] 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
+  # @rbs timeout: Numeric? -- Navigation timeout in milliseconds
+  # @rbs wait_until: String | Array[String] | nil -- Lifecycle events to wait for
+  # @rbs return: Puppeteer::HTTPResponse? -- Navigation response
   def go_forward(timeout: nil, wait_until: nil)
     go(+1, timeout: timeout, wait_until: wait_until)
   end
@@ -856,37 +1142,44 @@ class Puppeteer::Page
     history = @client.send_message('Page.getNavigationHistory')
     entries = history['entries']
     index = history['currentIndex'] + delta
-    if_present(entries[index]) do |entry|
-      wait_for_navigation(timeout: timeout, wait_until: wait_until) do
-        @client.send_message('Page.navigateToHistoryEntry', entryId: entry['id'])
-      end
+    if index < 0 || index >= entries.length
+      raise Puppeteer::Error.new('History entry to navigate to not found.')
+    end
+    entry = entries[index]
+    wait_for_navigation(timeout: timeout, wait_until: wait_until) do
+      @client.send_message('Page.navigateToHistoryEntry', entryId: entry['id'])
     end
   end
 
   # Brings page to front (activates tab).
+  # @rbs return: void -- No return value
   def bring_to_front
     @client.send_message('Page.bringToFront')
   end
 
-  # @param device [Device]
+  # @rbs device: Puppeteer::Device -- Device descriptor
+  # @rbs return: void -- No return value
   def emulate(device)
     self.viewport = device.viewport
     self.user_agent = device.user_agent
   end
 
-  # @param {boolean} enabled
+  # @rbs enabled: bool -- Enable JavaScript
+  # @rbs return: void -- No return value
   def javascript_enabled=(enabled)
     return if @javascript_enabled == enabled
     @javascript_enabled = enabled
     @client.send_message('Emulation.setScriptExecutionDisabled', value: !enabled)
   end
 
-  # @param enabled [Boolean]
+  # @rbs enabled: bool -- Enable bypassing CSP
+  # @rbs return: void -- No return value
   def bypass_csp=(enabled)
     @client.send_message('Page.setBypassCSP', enabled: enabled)
   end
 
-  # @param media_type [String|Symbol|nil] either of (media, print, nil)
+  # @rbs media_type: (String | Symbol)? -- Media type override
+  # @rbs return: void -- No return value
   def emulate_media_type(media_type)
     media_type_str = media_type.to_s
     unless ['screen', 'print', ''].include?(media_type_str)
@@ -895,7 +1188,8 @@ class Puppeteer::Page
     @client.send_message('Emulation.setEmulatedMedia', media: media_type_str)
   end
 
-  # @param factor [Number|nil] Factor at which the CPU will be throttled (2x, 2.5x. 3x, ...). Passing `nil` disables cpu throttling.
+  # @rbs factor: Numeric? -- CPU throttling rate
+  # @rbs return: void -- No return value
   def emulate_cpu_throttling(factor)
     if factor.nil? || factor >= 1
       @client.send_message('Emulation.setCPUThrottlingRate', rate: factor || 1)
@@ -904,7 +1198,8 @@ class Puppeteer::Page
     end
   end
 
-  # @param features [Array]
+  # @rbs features: Array[Hash[Symbol, untyped]]? -- Media feature overrides
+  # @rbs return: void -- No return value
   def emulate_media_features(features)
     if features.nil?
       @client.send_message('Emulation.setEmulatedMedia', features: nil)
@@ -919,7 +1214,8 @@ class Puppeteer::Page
     end
   end
 
-  # @param timezone_id [String?]
+  # @rbs timezone_id: String? -- Timezone ID
+  # @rbs return: void -- No return value
   def emulate_timezone(timezone_id)
     @client.send_message('Emulation.setTimezoneOverride', timezoneId: timezone_id || '')
   rescue => err
@@ -939,6 +1235,8 @@ class Puppeteer::Page
     tritanopia
   ].freeze
 
+  # @rbs vision_deficiency_type: String? -- Vision deficiency type
+  # @rbs return: void -- No return value
   def emulate_vision_deficiency(vision_deficiency_type)
     value = vision_deficiency_type || 'none'
     unless VISION_DEFICIENCY_TYPES.include?(value)
@@ -947,8 +1245,9 @@ class Puppeteer::Page
     @client.send_message('Emulation.setEmulatedVisionDeficiency', type: value)
   end
 
-  # @param is_user_active [Boolean]
-  # @param is_screen_unlocked [Boolean]
+  # @rbs is_user_active: bool? -- User activity override
+  # @rbs is_screen_unlocked: bool? -- Screen unlocked override
+  # @rbs return: void -- No return value
   def emulate_idle_state(is_user_active: nil, is_screen_unlocked: nil)
     overrides = {
       isUserActive: is_user_active,
@@ -962,7 +1261,8 @@ class Puppeteer::Page
     end
   end
 
-  # @param viewport [Viewport]
+  # @rbs viewport: Puppeteer::Viewport? -- Viewport settings
+  # @rbs return: void -- No return value
   def viewport=(viewport)
     needs_reload = @emulation_manager.emulate_viewport(viewport)
     @viewport = viewport
@@ -971,9 +1271,9 @@ class Puppeteer::Page
 
   attr_reader :viewport
 
-  # @param {Function|string} pageFunction
-  # @param {!Array<*>} args
-  # @return {!Promise<*>}
+  # @rbs page_function: String -- page_function parameter
+  # @rbs args: Array[untyped] -- args parameter
+  # @rbs return: untyped -- Result
   def evaluate(page_function, *args)
     main_frame.evaluate(page_function, *args)
   end
@@ -981,11 +1281,15 @@ class Puppeteer::Page
   define_async_method :async_evaluate
 
   class JavaScriptFunction
+    # @rbs expression: String -- Function expression
+    # @rbs args: Array[untyped] -- Arguments for evaluation
+    # @rbs return: void -- No return value
     def initialize(expression, args)
       @expression = expression
       @args = args
     end
 
+    # @rbs return: String -- Generated source
     def source
       "(#{@expression})(#{arguments})"
     end
@@ -996,15 +1300,21 @@ class Puppeteer::Page
   end
 
   class JavaScriptExpression
+    # @rbs expression: String -- Expression to evaluate
+    # @rbs return: void -- No return value
     def initialize(expression)
       @expression = expression
     end
 
+    # @rbs return: String -- Generated source
     def source
       @expression
     end
   end
 
+  # @rbs page_function: String -- page_function parameter
+  # @rbs args: Array[untyped] -- args parameter
+  # @rbs return: Hash[String, untyped] -- CDP response
   def evaluate_on_new_document(page_function, *args)
     source =
       if ['=>', 'async', 'function'].any? { |keyword| page_function.include?(keyword) }
@@ -1016,23 +1326,32 @@ class Puppeteer::Page
     @client.send_message('Page.addScriptToEvaluateOnNewDocument', source: source)
   end
 
-  # @param {boolean} enabled
+  # @rbs identifier: String -- Script identifier to remove
+  # @rbs return: void
+  def remove_script_to_evaluate_on_new_document(identifier)
+    @client.send_message('Page.removeScriptToEvaluateOnNewDocument', identifier: identifier)
+  end
+
+  # @rbs enabled: bool -- Enable cache usage
   def cache_enabled=(enabled)
     @frame_manager.network_manager.cache_enabled = enabled
   end
 
-  # @return [String]
+  # @rbs return: String -- Page title
   def title
     main_frame.title
   end
 
-  # @param type [String] "png"|"jpeg"|"webp"
-  # @param path [String]
-  # @param full_page [Boolean]
-  # @param clip [Hash]
-  # @param quality [Integer]
-  # @param omit_background [Boolean]
-  # @param encoding [String]
+  # @rbs type: String? -- Image format
+  # @rbs path: String? -- File path to save
+  # @rbs full_page: bool? -- Capture full page
+  # @rbs clip: Hash[Symbol, Numeric]? -- Clip rectangle
+  # @rbs quality: Integer? -- JPEG quality
+  # @rbs omit_background: bool? -- Omit background for PNG
+  # @rbs encoding: String? -- Encoding (base64 or binary)
+  # @rbs capture_beyond_viewport: bool? -- Capture beyond viewport
+  # @rbs from_surface: bool? -- Capture from surface
+  # @rbs return: String -- Screenshot data
   def screenshot(type: nil,
                  path: nil,
                  full_page: nil,
@@ -1055,14 +1374,14 @@ class Puppeteer::Page
     }.compact
     screenshot_options = ScreenshotOptions.new(options)
 
+    guard = browser_context.start_screenshot
     @screenshot_task_queue.post_task do
       screenshot_task(screenshot_options.type, screenshot_options)
     end
+  ensure
+    guard&.release
   end
 
-  # @param {"png"|"jpeg"} format
-  # @param {!ScreenshotOptions=} options
-  # @return {!Promise<!Buffer|!String>}
   private def screenshot_task(format, screenshot_options)
     @client.send_message('Target.activateTarget', targetId: @target.target_id)
 
@@ -1129,13 +1448,15 @@ class Puppeteer::Page
     buffer
   end
 
-  class PrintToPdfIsNotImplementedError < StandardError
+  class PrintToPdfIsNotImplementedError < Puppeteer::Error
+    # @rbs return: void -- No return value
     def initialize
       super('pdf() is only available in headless mode. See https://github.com/puppeteer/puppeteer/issues/1829')
     end
   end
 
-  # @return [Enumerable<String>]
+  # @rbs options: Hash[Symbol, untyped] -- PDF options
+  # @rbs return: Enumerable[String] -- PDF data chunks
   def create_pdf_stream(options = {})
     timeout_helper = Puppeteer::TimeoutHelper.new('Page.printToPDF',
                       timeout_ms: options[:timeout],
@@ -1158,7 +1479,8 @@ class Puppeteer::Page
     ).read_as_chunks
   end
 
-  # @return [String]
+  # @rbs options: Hash[Symbol, untyped] -- PDF options
+  # @rbs return: String -- PDF data
   def pdf(options = {})
     chunks = create_pdf_stream(options)
 
@@ -1186,65 +1508,79 @@ class Puppeteer::Page
     end
   end
 
-  # @param run_before_unload [Boolean]
+  # @rbs run_before_unload: bool -- Whether to run beforeunload handlers
+  # @rbs return: void -- No return value
   def close(run_before_unload: false)
-    unless @client.connection
-      raise 'Protocol error: Connection closed. Most likely the page has been closed.'
-    end
+    guard = browser_context.wait_for_screenshot_operations
+    begin
+      unless @client.connection
+        raise 'Protocol error: Connection closed. Most likely the page has been closed.'
+      end
 
-    if run_before_unload
-      @client.send_message('Page.close')
-    else
-      @client.connection.send_message('Target.closeTarget', targetId: @target.target_id)
-      await @target.is_closed_promise
+      if run_before_unload
+        @client.send_message('Page.close')
+      else
+        @client.connection.send_message('Target.closeTarget', targetId: @target.target_id)
+        @target.is_closed_promise.wait
 
-      # @closed sometimes remains false, so wait for @closed = true with 100ms timeout.
-      25.times do
-        break if @closed
-        sleep 0.004
+        # @closed sometimes remains false, so wait for @closed = true with 100ms timeout.
+        25.times do
+          break if @closed
+          Puppeteer::AsyncUtils.sleep_seconds(0.004)
+        end
       end
+    rescue Puppeteer::Connection::ProtocolError => err
+      raise unless err.message.match?(/Target closed/i)
+    ensure
+      guard&.release
     end
   end
 
-  # @return [boolean]
+  # @rbs return: bool -- Whether the page is closed
   def closed?
     @closed
   end
 
   attr_reader :mouse
 
-  # @param selector [String]
-  # @param delay [Number]
-  # @param button [String] "left"|"right"|"middle"
-  # @param click_count [Number]
-  def click(selector, delay: nil, button: nil, click_count: nil)
-    main_frame.click(selector, delay: delay, button: button, click_count: click_count)
+  # @rbs selector: String -- CSS selector
+  # @rbs delay: Numeric? -- Delay between down and up (ms)
+  # @rbs button: String? -- Mouse button
+  # @rbs click_count: Integer? -- Deprecated: use count (click_count only sets clickCount)
+  # @rbs count: Integer? -- Number of clicks to perform
+  # @rbs return: void -- No return value
+  def click(selector, delay: nil, button: nil, click_count: nil, count: nil)
+    main_frame.click(selector, delay: delay, button: button, click_count: click_count, count: count)
   end
 
   define_async_method :async_click
 
-  # @param {string} selector
+  # @rbs selector: String -- CSS selector
+  # @rbs return: void -- No return value
   def focus(selector)
     main_frame.focus(selector)
   end
 
   define_async_method :async_focus
 
-  # @param {string} selector
+  # @rbs selector: String -- CSS selector
+  # @rbs return: void -- No return value
   def hover(selector)
     main_frame.hover(selector)
   end
 
-  # @param {string} selector
-  # @param {!Array<string>} values
-  # @return {!Promise<!Array<string>>}
+  # @rbs selector: String -- CSS selector
+  # @rbs values: Array[String] -- Option values to select
+  # @rbs return: Array[String] -- Selected values
   def select(selector, *values)
     main_frame.select(selector, *values)
   end
 
   define_async_method :async_select
 
-  # @param selector [String]
+  # @rbs selector: String? -- CSS selector
+  # @rbs block: Proc? -- Optional block for Object#tap usage
+  # @rbs return: Puppeteer::Page | nil -- Page instance or nil
   def tap(selector: nil, &block)
     # resolves double meaning of tap.
     if selector.nil? && block
@@ -1253,54 +1589,60 @@ class Puppeteer::Page
       # browser.new_page.tap do |page|
       #   ...
       # end
-      super(&block)
-    else
-      # Puppeteer's Page#tap.
-      main_frame.tap(selector)
+      block.call(self)
+      return self
     end
+
+    # Puppeteer's Page#tap.
+    main_frame.tap(selector)
+    nil
   end
 
   define_async_method :async_tap
 
-  # @param selector [String]
-  # @param text [String]
-  # @param delay [Number]
+  # @rbs selector: String -- CSS selector
+  # @rbs text: String -- Text to type
+  # @rbs delay: Numeric? -- Delay between key presses (ms)
+  # @rbs return: void -- No return value
   def type_text(selector, text, delay: nil)
     main_frame.type_text(selector, text, delay: delay)
   end
 
   define_async_method :async_type_text
 
-  # @param selector [String]
-  # @param visible [Boolean] Wait for element visible (not 'display: none' nor 'visibility: hidden') on true. default to false.
-  # @param hidden [Boolean] Wait for element invisible ('display: none' nor 'visibility: hidden') on true. default to false.
-  # @param timeout [Integer]
+  # @rbs selector: String -- CSS selector
+  # @rbs visible: bool? -- Wait for element to be visible
+  # @rbs hidden: bool? -- Wait for element to be hidden
+  # @rbs timeout: Numeric? -- Maximum wait time in milliseconds
+  # @rbs return: Puppeteer::ElementHandle? -- Matching element or nil
   def wait_for_selector(selector, visible: nil, hidden: nil, timeout: nil)
     main_frame.wait_for_selector(selector, visible: visible, hidden: hidden, timeout: timeout)
   end
 
   define_async_method :async_wait_for_selector
 
-  # @param milliseconds [Integer] the number of milliseconds to wait.
+  # @rbs milliseconds: Numeric -- Time to wait in milliseconds
+  # @rbs return: void -- No return value
   def wait_for_timeout(milliseconds)
     main_frame.wait_for_timeout(milliseconds)
   end
 
-  # @param xpath [String]
-  # @param visible [Boolean] Wait for element visible (not 'display: none' nor 'visibility: hidden') on true. default to false.
-  # @param hidden [Boolean] Wait for element invisible ('display: none' nor 'visibility: hidden') on true. default to false.
-  # @param timeout [Integer]
+  # @rbs xpath: String -- XPath expression
+  # @rbs visible: bool? -- Wait for element to be visible
+  # @rbs hidden: bool? -- Wait for element to be hidden
+  # @rbs timeout: Numeric? -- Maximum wait time in milliseconds
+  # @rbs return: Puppeteer::ElementHandle? -- Matching element or nil
   def wait_for_xpath(xpath, visible: nil, hidden: nil, timeout: nil)
     main_frame.wait_for_xpath(xpath, visible: visible, hidden: hidden, timeout: timeout)
   end
 
   define_async_method :async_wait_for_xpath
 
-  # @param page_function [String]
-  # @param args [Integer|Array]
-  # @param polling [String]
-  # @param timeout [Integer]
-  # @return [Puppeteer::JSHandle]
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @rbs polling: String | Numeric | nil -- Polling strategy
+  # @rbs timeout: Numeric? -- Maximum wait time in milliseconds
+  # @rbs return: Puppeteer::JSHandle -- Handle to evaluation result
   def wait_for_function(page_function, args: [], polling: nil, timeout: nil)
     main_frame.wait_for_function(page_function, args: args, polling: polling, timeout: timeout)
   end