puppeteer-bidi 0.0.1.beta10 → 0.0.1

data/lib/puppeteer/bidi/page.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-require 'base64'
-require 'fileutils'
+require "base64"
+require "fileutils"
+require "uri"
+require "async/semaphore"
 
 module Puppeteer
   module Bidi
@@ -10,6 +12,58 @@ module Puppeteer
     # This is a high-level wrapper around Core::BrowsingContext
     class Page
       DEFAULT_TIMEOUT = 30_000 #: Integer
+      UNIT_TO_PIXELS = {
+        "px" => 1,
+        "in" => 96,
+        "cm" => 37.8,
+        "mm" => 3.78
+      }.freeze
+      PAPER_FORMATS = {
+        "letter" => {
+          "cm" => { width: 21.59, height: 27.94 },
+          "in" => { width: 8.5, height: 11 }
+        },
+        "legal" => {
+          "cm" => { width: 21.59, height: 35.56 },
+          "in" => { width: 8.5, height: 14 }
+        },
+        "tabloid" => {
+          "cm" => { width: 27.94, height: 43.18 },
+          "in" => { width: 11, height: 17 }
+        },
+        "ledger" => {
+          "cm" => { width: 43.18, height: 27.94 },
+          "in" => { width: 17, height: 11 }
+        },
+        "a0" => {
+          "cm" => { width: 84.1, height: 118.9 },
+          "in" => { width: 33.1102, height: 46.811 }
+        },
+        "a1" => {
+          "cm" => { width: 59.4, height: 84.1 },
+          "in" => { width: 23.3858, height: 33.1102 }
+        },
+        "a2" => {
+          "cm" => { width: 42, height: 59.4 },
+          "in" => { width: 16.5354, height: 23.3858 }
+        },
+        "a3" => {
+          "cm" => { width: 29.7, height: 42 },
+          "in" => { width: 11.6929, height: 16.5354 }
+        },
+        "a4" => {
+          "cm" => { width: 21, height: 29.7 },
+          "in" => { width: 8.2677, height: 11.6929 }
+        },
+        "a5" => {
+          "cm" => { width: 14.8, height: 21 },
+          "in" => { width: 5.8268, height: 8.2677 }
+        },
+        "a6" => {
+          "cm" => { width: 10.5, height: 14.8 },
+          "in" => { width: 4.1339, height: 5.8268 }
+        }
+      }.freeze
 
       attr_reader :browsing_context #: Core::BrowsingContext
       attr_reader :browser_context #: BrowserContext
@@ -23,6 +77,15 @@ module Puppeteer
         @browsing_context = browsing_context
         @timeout_settings = TimeoutSettings.new(DEFAULT_TIMEOUT)
         @emitter = Core::EventEmitter.new
+        @request_interception_semaphore = Async::Semaphore.new(1)
+        @request_handlers = begin
+          ObjectSpace::WeakMap.new
+        rescue NameError
+          {}
+        end
+        @request_interception = nil
+        @auth_interception = nil
+        @credentials = nil
       end
 
       # Event emitter delegation methods
@@ -33,7 +96,18 @@ module Puppeteer
       # @rbs &block: (untyped) -> void -- Event handler
       # @rbs return: void
       def on(event, &block)
-        @emitter.on(event, &block)
+        return @emitter.on(event, &block) unless event.to_sym == :request
+
+        wrapper = @request_handlers[block]
+        unless wrapper
+          wrapper = lambda do |request|
+            request.enqueue_intercept_action do
+              block.call(request)
+            end
+          end
+          @request_handlers[block] = wrapper
+        end
+        @emitter.on(event, &wrapper)
       end
 
       # Register a one-time event listener
@@ -49,6 +123,16 @@ module Puppeteer
       # @rbs &block: (untyped) -> void -- Event handler to remove
       # @rbs return: void
       def off(event, &block)
+        if event.to_sym == :request && block
+          # WeakMap#delete was added in Ruby 3.3, so we need to handle older versions
+          wrapper = if @request_handlers.respond_to?(:delete)
+                      @request_handlers.delete(block)
+                    else
+                      @request_handlers[block]
+                    end
+          return @emitter.off(event, &(wrapper || block))
+        end
+
         @emitter.off(event, &block)
       end
 
@@ -60,6 +144,19 @@ module Puppeteer
         @emitter.emit(event, data)
       end
 
+      # @rbs return: bool -- Whether any network interception is enabled
+      def network_interception_enabled?
+        !@request_interception.nil? || !@auth_interception.nil?
+      end
+
+      # @rbs return: Hash[Symbol, String]?
+      def credentials
+        @credentials
+      end
+
+      # @rbs return: Async::Semaphore -- Serialize request interception handling
+      attr_reader :request_interception_semaphore
+
       # Navigate to a URL
       # @rbs url: String -- URL to navigate to
       # @rbs wait_until: String -- When to consider navigation complete ('load', 'domcontentloaded')
@@ -181,12 +278,18 @@ module Puppeteer
             }
           end
 
+          clip_x, clip_y, clip_width, clip_height = process_clip(
+            clip_x: box[:x],
+            clip_y: box[:y],
+            clip_width: box[:width],
+            clip_height: box[:height],
+          )
           options[:clip] = {
             type: 'box',
-            x: box[:x],
-            y: box[:y],
-            width: box[:width],
-            height: box[:height]
+            x: clip_x,
+            y: clip_y,
+            width: clip_width,
+            height: clip_height
           }
         end
 
@@ -206,6 +309,115 @@ module Puppeteer
         data
       end
 
+      # Generate a PDF of the page.
+      # @rbs path: String? -- File path to save PDF
+      # @rbs scale: Numeric? -- Scale of the webpage rendering
+      # @rbs display_header_footer: bool? -- Display header and footer
+      # @rbs header_template: String? -- HTML template for header
+      # @rbs footer_template: String? -- HTML template for footer
+      # @rbs print_background: bool? -- Print background graphics
+      # @rbs landscape: bool? -- Print in landscape orientation
+      # @rbs page_ranges: String? -- Paper ranges to print (e.g. "1-5, 8")
+      # @rbs format: String? -- Paper format (e.g. "A4")
+      # @rbs width: String | Numeric? -- Paper width
+      # @rbs height: String | Numeric? -- Paper height
+      # @rbs prefer_css_page_size: bool? -- Prefer CSS @page size
+      # @rbs margin: Hash[Symbol, String | Numeric]? -- Paper margins
+      # @rbs omit_background: bool? -- Omit background
+      # @rbs tagged: bool? -- Generate tagged PDF
+      # @rbs outline: bool? -- Generate document outline
+      # @rbs timeout: Numeric? -- Timeout in ms (0 disables)
+      # @rbs wait_for_fonts: bool? -- Wait for document fonts to load
+      # @rbs return: String -- PDF data as binary string
+      def pdf(
+        path: nil,
+        scale: nil,
+        display_header_footer: nil,
+        header_template: nil,
+        footer_template: nil,
+        print_background: nil,
+        landscape: nil,
+        page_ranges: nil,
+        format: nil,
+        width: nil,
+        height: nil,
+        prefer_css_page_size: nil,
+        margin: nil,
+        omit_background: nil,
+        tagged: nil,
+        outline: nil,
+        timeout: nil,
+        wait_for_fonts: nil
+      )
+        assert_not_closed
+
+        timeout_ms = timeout.nil? ? @timeout_settings.timeout : timeout
+
+        options = {
+          scale: scale,
+          display_header_footer: display_header_footer,
+          header_template: header_template,
+          footer_template: footer_template,
+          print_background: print_background,
+          landscape: landscape,
+          page_ranges: page_ranges,
+          format: format,
+          width: width,
+          height: height,
+          prefer_css_page_size: prefer_css_page_size,
+          margin: margin,
+          omit_background: omit_background,
+          tagged: tagged,
+          outline: outline,
+          wait_for_fonts: wait_for_fonts
+        }.compact
+
+        parsed = parse_pdf_options(options, "cm")
+        ranges = parsed[:page_ranges]
+        page_ranges = ranges && !ranges.empty? ? ranges.split(", ") : []
+
+        begin
+          if timeout_ms == 0
+            main_frame.isolated_realm.evaluate("() => document.fonts.ready")
+          else
+            AsyncUtils.async_timeout(timeout_ms, -> do
+              main_frame.isolated_realm.evaluate("() => document.fonts.ready")
+            end).wait
+          end
+        rescue Async::TimeoutError
+          raise TimeoutError, "Timed out after waiting #{timeout_ms}ms"
+        end
+
+        print_options = {
+          background: parsed[:print_background],
+          margin: parsed[:margin],
+          orientation: parsed[:landscape] ? "landscape" : "portrait",
+          page: {
+            width: parsed[:width],
+            height: parsed[:height]
+          },
+          pageRanges: page_ranges,
+          scale: parsed[:scale],
+          shrinkToFit: !parsed[:prefer_css_page_size]
+        }
+
+        begin
+          data = if timeout_ms == 0
+                   @browsing_context.print(**print_options).wait
+                 else
+                   AsyncUtils.async_timeout(timeout_ms, -> do
+                     @browsing_context.print(**print_options).wait
+                   end).wait
+                 end
+        rescue Async::TimeoutError
+          raise TimeoutError, "Timed out after waiting #{timeout_ms}ms"
+        end
+
+        pdf_data = Base64.decode64(data)
+        File.binwrite(path, pdf_data) if path
+        pdf_data
+      end
+
       # Evaluate JavaScript in the page context
       # @rbs script: String -- JavaScript code to evaluate
       # @rbs *args: untyped -- Arguments to pass to the script
@@ -236,6 +448,24 @@ module Puppeteer
         main_frame.query_selector_all(selector)
       end
 
+      # Create a locator for a selector or function.
+      # @rbs selector: String? -- Selector to locate
+      # @rbs function: String? -- JavaScript function for function locator
+      # @rbs return: Locator -- Locator instance
+      def locator(selector = nil, function: nil)
+        assert_not_closed
+
+        if function
+          raise ArgumentError, "selector and function cannot both be set" if selector
+
+          FunctionLocator.create(self, function)
+        elsif selector
+          NodeLocator.create(self, selector)
+        else
+          raise ArgumentError, "selector or function must be provided"
+        end
+      end
+
       # Evaluate a function on the first element matching the selector
       # @rbs selector: String -- Selector to query
       # @rbs page_function: String -- JavaScript function to evaluate
@@ -281,6 +511,15 @@ module Puppeteer
         main_frame.hover(selector)
       end
 
+      # Select options on a <select> element matching the selector
+      # Triggers 'change' and 'input' events once all options are selected.
+      # @rbs selector: String -- Selector for <select> element
+      # @rbs *values: String -- Option values to select
+      # @rbs return: Array[String] -- Actually selected option values
+      def select(selector, *values)
+        main_frame.select(selector, *values)
+      end
+
       # Focus an element matching the selector
       # @rbs selector: String -- Selector to focus
       # @rbs return: void
@@ -307,6 +546,31 @@ module Puppeteer
         @browsing_context.url
       end
 
+      # Get the full HTML contents of the page, including the DOCTYPE.
+      # @rbs return: String -- Full HTML contents
+      def content
+        assert_not_closed
+
+        # Port of Puppeteer's Frame.content().
+        # https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Frame.ts
+        main_frame.evaluate(<<~JS)
+          () => {
+            let content = '';
+            for (const node of document.childNodes) {
+              switch (node) {
+                case document.documentElement:
+                  content += document.documentElement.outerHTML;
+                  break;
+                default:
+                  content += new XMLSerializer().serializeToString(node);
+                  break;
+              }
+            }
+            return content;
+          }
+        JS
+      end
+
       # Close the page
       # @rbs return: void
       def close
@@ -327,6 +591,72 @@ module Puppeteer
         @main_frame ||= Frame.from(self, @browsing_context)
       end
 
+      # Reloads the page.
+      # @rbs timeout: Numeric -- Navigation timeout in ms
+      # @rbs wait_until: String | Array[String] -- When to consider navigation complete
+      # @rbs ignore_cache: bool -- Whether to ignore the browser cache
+      # @rbs return: HTTPResponse? -- Response or nil
+      def reload(timeout: 30000, wait_until: 'load', ignore_cache: false)
+        assert_not_closed
+
+        reload_options = {}
+        reload_options[:ignoreCache] = true if ignore_cache
+
+        wait_for_navigation(timeout: timeout, wait_until: wait_until) do
+          @browsing_context.reload(**reload_options).wait
+        end
+      end
+
+      # Enable or disable request interception.
+      # @rbs enable: bool -- Whether to enable interception
+      # @rbs return: void
+      def set_request_interception(enable)
+        assert_not_closed
+
+        @request_interception = toggle_interception(
+          ["beforeRequestSent"],
+          @request_interception,
+          enable,
+        )
+      end
+
+      # Set extra HTTP headers for the page.
+      # @rbs headers: Hash[String, String] -- Extra headers
+      # @rbs return: void
+      def set_extra_http_headers(headers)
+        assert_not_closed
+
+        normalized = {}
+        headers.each do |key, value|
+          normalized[key.to_s] = value.to_s
+        end
+        @browsing_context.set_extra_http_headers(normalized).wait
+      end
+
+      # Authenticate to HTTP Basic auth challenges.
+      # @rbs credentials: Hash[Symbol, String]? -- Credentials (username/password) or nil to disable
+      # @rbs return: void
+      def authenticate(credentials)
+        assert_not_closed
+
+        @auth_interception = toggle_interception(
+          ["authRequired"],
+          @auth_interception,
+          !credentials.nil?,
+        )
+
+        @credentials = credentials
+      end
+
+      # Enable or disable cache.
+      # @rbs enabled: bool -- Whether to enable cache
+      # @rbs return: void
+      def set_cache_enabled(enabled)
+        assert_not_closed
+
+        @browsing_context.set_cache_behavior(enabled ? "default" : "bypass").wait
+      end
+
       # Get the focused frame
       # @rbs return: Frame -- Focused frame
       def focused_frame
@@ -430,6 +760,199 @@ module Puppeteer
         main_frame.wait_for_navigation(timeout: timeout, wait_until: wait_until, &block)
       end
 
+      # Wait for a request that matches a URL or predicate.
+      # @rbs url_or_predicate: String | ^(HTTPRequest) -> boolish -- URL or predicate
+      # @rbs timeout: Numeric? -- Timeout in ms (0 for infinite)
+      # @rbs &block: (-> void)? -- Optional block to trigger the request
+      # @rbs return: HTTPRequest
+      def wait_for_request(url_or_predicate, timeout: nil, &block)
+        assert_not_closed
+
+        timeout_ms = timeout.nil? ? @timeout_settings.timeout : timeout
+        predicate = if url_or_predicate.is_a?(Proc)
+                      url_or_predicate
+                    else
+                      ->(request) { request.url == url_or_predicate }
+                    end
+
+        promise = Async::Promise.new
+        listener = proc do |request|
+          next unless predicate.call(request)
+
+          promise.resolve(request) unless promise.resolved?
+        end
+
+        begin
+          on(:request, &listener)
+          Async(&block).wait if block
+
+          if timeout_ms == 0
+            promise.wait
+          else
+            AsyncUtils.async_timeout(timeout_ms, promise).wait
+          end
+        ensure
+          off(:request, &listener)
+        end
+      end
+
+      # Wait for a response that matches a URL or predicate.
+      # @rbs url_or_predicate: String | ^(HTTPResponse) -> boolish -- URL or predicate
+      # @rbs timeout: Numeric? -- Timeout in ms (0 for infinite)
+      # @rbs &block: (-> void)? -- Optional block to trigger the response
+      # @rbs return: HTTPResponse
+      def wait_for_response(url_or_predicate, timeout: nil, &block)
+        assert_not_closed
+
+        timeout_ms = timeout.nil? ? @timeout_settings.timeout : timeout
+        predicate = if url_or_predicate.is_a?(Proc)
+                      url_or_predicate
+                    else
+                      ->(response) { response.url == url_or_predicate }
+                    end
+
+        promise = Async::Promise.new
+        listener = proc do |response|
+          next unless predicate.call(response)
+
+          promise.resolve(response) unless promise.resolved?
+        end
+
+        begin
+          on(:response, &listener)
+          Async(&block).wait if block
+
+          if timeout_ms == 0
+            promise.wait
+          else
+            AsyncUtils.async_timeout(timeout_ms, promise).wait
+          end
+        ensure
+          off(:response, &listener)
+        end
+      end
+
+      # Retrieve cookies for the current page.
+      # @rbs *urls: Array[String] -- URLs to filter cookies by
+      # @rbs return: Array[Hash[String, untyped]]
+      def cookies(*urls)
+        assert_not_closed
+
+        normalized_urls = (urls.empty? ? [url] : urls).map do |cookie_url|
+          parse_cookie_url_strict(cookie_url)
+        end
+
+        @browsing_context.get_cookies.wait
+                         .map { |cookie| CookieUtils.bidi_to_puppeteer_cookie(cookie) }
+                         .select do |cookie|
+                           normalized_urls.any? do |normalized_url|
+                             CookieUtils.test_url_match_cookie(cookie, normalized_url)
+                           end
+                         end
+      end
+
+      # Set cookies for the current page.
+      # @rbs *cookies: Array[Hash[String, untyped]] -- Cookie data
+      # @rbs **cookie: untyped -- Single cookie via keyword arguments
+      # @rbs return: void
+      def set_cookie(*cookies, **cookie)
+        assert_not_closed
+
+        cookies = cookies.dup
+        cookies << cookie unless cookie.empty?
+
+        page_url = url
+        page_url_starts_with_http = page_url&.start_with?("http")
+
+        cookies.each do |raw_cookie|
+          normalized_cookie = CookieUtils.normalize_cookie_input(raw_cookie)
+          cookie_url = normalized_cookie["url"].to_s
+          if cookie_url.empty? && page_url_starts_with_http
+            cookie_url = page_url
+          end
+
+          if cookie_url == "about:blank"
+            raise ArgumentError, "Blank page can not have cookie \"#{normalized_cookie["name"]}\""
+          end
+          if cookie_url.start_with?("data:")
+            raise ArgumentError, "Data URL page can not have cookie \"#{normalized_cookie["name"]}\""
+          end
+
+          partition_key = normalized_cookie["partitionKey"]
+          if !partition_key.nil? && !partition_key.is_a?(String)
+            raise ArgumentError, "BiDi only allows domain partition keys"
+          end
+
+          normalized_url = parse_cookie_url(cookie_url)
+          domain = normalized_cookie["domain"] || normalized_url&.host
+          if domain.nil?
+            raise ArgumentError, "At least one of the url and domain needs to be specified"
+          end
+
+          bidi_cookie = {
+            "domain" => domain,
+            "name" => normalized_cookie["name"],
+            "value" => { "type" => "string", "value" => normalized_cookie["value"] },
+          }
+          bidi_cookie["path"] = normalized_cookie["path"] if normalized_cookie.key?("path")
+          bidi_cookie["httpOnly"] = normalized_cookie["httpOnly"] if normalized_cookie.key?("httpOnly")
+          bidi_cookie["secure"] = normalized_cookie["secure"] if normalized_cookie.key?("secure")
+          if normalized_cookie.key?("sameSite") && !normalized_cookie["sameSite"].nil?
+            bidi_cookie["sameSite"] = CookieUtils.convert_cookies_same_site_cdp_to_bidi(
+              normalized_cookie["sameSite"]
+            )
+          end
+          expiry = CookieUtils.convert_cookies_expiry_cdp_to_bidi(normalized_cookie["expires"])
+          bidi_cookie["expiry"] = expiry unless expiry.nil?
+          bidi_cookie.merge!(CookieUtils.cdp_specific_cookie_properties_from_puppeteer_to_bidi(
+                               normalized_cookie,
+                               "sameParty",
+                               "sourceScheme",
+                               "priority",
+                               "url"
+                             ))
+
+          if partition_key
+            @browser_context.user_context.set_cookie(bidi_cookie, source_origin: partition_key).wait
+          else
+            @browsing_context.set_cookie(bidi_cookie).wait
+          end
+        end
+      end
+
+      # Delete cookies from the current page.
+      # @rbs *cookies: Array[Hash[String, untyped]] -- Cookie filters
+      # @rbs **cookie: untyped -- Single cookie filter via keyword arguments
+      # @rbs return: void
+      def delete_cookie(*cookies, **cookie)
+        assert_not_closed
+
+        cookies = cookies.dup
+        cookies << cookie unless cookie.empty?
+
+        page_url = url
+
+        tasks = cookies.map do |raw_cookie|
+          normalized_cookie = CookieUtils.normalize_cookie_input(raw_cookie)
+          cookie_url = normalized_cookie["url"] || page_url
+          normalized_url = parse_cookie_url(cookie_url.to_s)
+          domain = normalized_cookie["domain"] || normalized_url&.host
+          if domain.nil?
+            raise ArgumentError, "At least one of the url and domain needs to be specified"
+          end
+
+          filter = {
+            "domain" => domain,
+            "name" => normalized_cookie["name"],
+          }
+          filter["path"] = normalized_cookie["path"] if normalized_cookie.key?("path")
+
+          -> { @browsing_context.delete_cookie(filter).wait }
+        end
+
+        AsyncUtils.await_promise_all(*tasks) unless tasks.empty?
+      end
+
       # Wait for a file chooser to be opened
       # @rbs timeout: Numeric? -- Wait timeout in ms
       # @rbs &block: (-> void)? -- Optional block to trigger file chooser
@@ -567,6 +1090,55 @@ module Puppeteer
         ).wait
       end
 
+      # Set geolocation override
+      # @rbs longitude: Numeric -- Longitude between -180 and 180
+      # @rbs latitude: Numeric -- Latitude between -90 and 90
+      # @rbs accuracy: Numeric? -- Non-negative accuracy value
+      # @rbs return: void
+      def set_geolocation(longitude:, latitude:, accuracy: nil)
+        assert_not_closed
+
+        if longitude < -180 || longitude > 180
+          raise ArgumentError, "Invalid longitude \"#{longitude}\": precondition -180 <= LONGITUDE <= 180 failed."
+        end
+        if latitude < -90 || latitude > 90
+          raise ArgumentError, "Invalid latitude \"#{latitude}\": precondition -90 <= LATITUDE <= 90 failed."
+        end
+        accuracy_value = accuracy.nil? ? 0 : accuracy
+        if accuracy_value < 0
+          raise ArgumentError, "Invalid accuracy \"#{accuracy_value}\": precondition 0 <= ACCURACY failed."
+        end
+
+        coordinates = {
+          latitude: latitude,
+          longitude: longitude
+        }
+        coordinates[:accuracy] = accuracy unless accuracy.nil?
+
+        @browsing_context.set_geolocation_override(
+          coordinates: coordinates
+        ).wait
+      end
+
+      # Set user agent
+      # @rbs user_agent: String? -- User agent string or nil to restore original
+      # @rbs user_agent_metadata: Hash[Symbol, untyped]? -- Not supported in BiDi-only mode
+      # @rbs return: void
+      def set_user_agent(user_agent, user_agent_metadata = nil)
+        assert_not_closed
+
+        if user_agent.is_a?(Hash)
+          raise UnsupportedOperationError, "options hash is not supported in BiDi-only mode"
+        end
+
+        if user_agent_metadata
+          raise UnsupportedOperationError, "userAgentMetadata is not supported in BiDi-only mode"
+        end
+
+        user_agent = nil if user_agent == ""
+        @browsing_context.set_user_agent(user_agent).wait
+      end
+
       # Get current viewport size
       # @rbs return: Hash[Symbol, Integer]? -- Viewport dimensions
       def viewport
@@ -590,8 +1162,136 @@ module Puppeteer
         @browsing_context.javascript_enabled?
       end
 
+      # Navigate backward in history
+      # @rbs wait_until: String -- When to consider navigation complete
+      # @rbs timeout: Numeric -- Navigation timeout in ms
+      # @rbs return: HTTPResponse? -- Response or nil
+      def go_back(wait_until: 'load', timeout: 30000)
+        go(-1, wait_until: wait_until, timeout: timeout)
+      end
+
+      # Navigate forward in history
+      # @rbs wait_until: String -- When to consider navigation complete
+      # @rbs timeout: Numeric -- Navigation timeout in ms
+      # @rbs return: HTTPResponse? -- Response or nil
+      def go_forward(wait_until: 'load', timeout: 30000)
+        go(1, wait_until: wait_until, timeout: timeout)
+      end
+
       private
 
+      # Navigate history by delta.
+      #
+      # In Firefox, BFCache restores may emit `browsingContext.navigationStarted`
+      # without firing `domContentLoaded` / `load`. We treat such navigations as
+      # completed if we don't observe a navigation request shortly after start.
+      # @rbs delta: Integer -- Steps to go back (negative) or forward (positive)
+      # @rbs wait_until: String -- When to consider navigation complete
+      # @rbs timeout: Numeric -- Navigation timeout in ms
+      # @rbs return: HTTPResponse? -- Response or nil
+      def go(delta, wait_until:, timeout:)
+        assert_not_closed
+
+        load_event = wait_until == 'domcontentloaded' ? :dom_content_loaded : :load
+
+        started_promise = Async::Promise.new
+        load_promise = Async::Promise.new
+        navigation_request_promise = Async::Promise.new
+
+        navigation_id = nil
+        navigation_url = nil
+
+        session = @browsing_context.user_context.browser.session
+
+        history_listener = proc do
+          started_promise.resolve(:history_updated) unless started_promise.resolved?
+        end
+
+        fragment_listener = proc do
+          started_promise.resolve(:fragment_navigated) unless started_promise.resolved?
+        end
+
+        nav_started_listener = proc do |info|
+          next unless info['context'] == @browsing_context.id
+
+          navigation_id = info['navigation']
+          navigation_url = info['url']
+          started_promise.resolve(:navigation_started) unless started_promise.resolved?
+        end
+
+        request_listener = proc do |data|
+          request = data[:request]
+          next unless navigation_id
+          next unless request&.navigation == navigation_id
+
+          navigation_request_promise.resolve(nil) unless navigation_request_promise.resolved?
+        end
+
+        load_listener = proc do
+          load_promise.resolve(nil) unless load_promise.resolved?
+        end
+
+        closed_listener = proc do
+          started_promise.reject(PageClosedError.new) unless started_promise.resolved?
+        end
+
+        begin
+          session.on('browsingContext.navigationStarted', &nav_started_listener)
+          @browsing_context.on(:history_updated, &history_listener)
+          @browsing_context.on(:fragment_navigated, &fragment_listener)
+          @browsing_context.on(:request, &request_listener)
+          @browsing_context.once(load_event, &load_listener)
+          @browsing_context.once(:closed, &closed_listener)
+
+          @browsing_context.traverse_history(delta).wait
+        rescue Connection::ProtocolError => e
+          # "History entry with delta X not found" - at history edge
+          return nil if e.message.include?('not found')
+          raise
+        end
+
+        begin
+          # If nothing starts soon, assume we're at the history edge.
+          start_timeout_ms = [timeout.to_i, 500].min
+          start_type = AsyncUtils.async_timeout(start_timeout_ms, started_promise).wait
+        rescue Async::TimeoutError
+          return nil
+        end
+
+        case start_type
+        when :history_updated, :fragment_navigated
+          nil
+        when :navigation_started
+          # Determine BFCache restore (no navigation request) vs full navigation.
+          begin
+            AsyncUtils.async_timeout(200, navigation_request_promise).wait
+
+            begin
+              AsyncUtils.async_timeout(timeout, load_promise).wait
+            rescue Async::TimeoutError
+              raise Puppeteer::Bidi::TimeoutError, "Navigation timeout of #{timeout}ms exceeded"
+            end
+
+            HTTPResponse.for_bfcache(url: @browsing_context.url)
+          rescue Async::TimeoutError
+            # No navigation request observed: treat as BFCache restore.
+            @browsing_context.instance_variable_set(:@url, navigation_url) if navigation_url
+            @browsing_context.navigation&.dispose unless @browsing_context.navigation&.disposed?
+
+            HTTPResponse.for_bfcache(url: navigation_url || @browsing_context.url)
+          end
+        else
+          nil
+        end
+      ensure
+        session.off('browsingContext.navigationStarted', &nav_started_listener)
+        @browsing_context.off(:history_updated, &history_listener)
+        @browsing_context.off(:fragment_navigated, &fragment_listener)
+        @browsing_context.off(:request, &request_listener)
+        @browsing_context.off(load_event, &load_listener)
+        @browsing_context.off(:closed, &closed_listener)
+      end
+
       # Recursively collect all frames starting from the given frame
       # @rbs frame: Frame -- Starting frame
       # @rbs return: Array[Frame] -- All frames in subtree
@@ -603,11 +1303,163 @@ module Puppeteer
         result
       end
 
+      def parse_pdf_options(options, length_unit)
+        defaults = {
+          scale: 1,
+          display_header_footer: false,
+          header_template: "",
+          footer_template: "",
+          print_background: false,
+          landscape: false,
+          page_ranges: "",
+          prefer_css_page_size: false,
+          omit_background: false,
+          outline: false,
+          tagged: true,
+          wait_for_fonts: true
+        }
+
+        width = 8.5
+        height = 11
+        format = options[:format]
+        if format
+          format_key = format.to_s.downcase
+          format_dimensions = PAPER_FORMATS[format_key]
+          raise "Unknown paper format: #{format}" unless format_dimensions
+
+          dimensions = format_dimensions[length_unit]
+          width = dimensions[:width]
+          height = dimensions[:height]
+        else
+          width = convert_print_parameter_to_length_unit(options[:width], length_unit) || width
+          height = convert_print_parameter_to_length_unit(options[:height], length_unit) || height
+        end
+
+        margin_options = options[:margin]
+        if margin_options.is_a?(Hash)
+          margin_options = margin_options.transform_keys(&:to_sym)
+        else
+          margin_options = {}
+        end
+        margin = {
+          top: convert_print_parameter_to_length_unit(margin_options[:top], length_unit) || 0,
+          left: convert_print_parameter_to_length_unit(margin_options[:left], length_unit) || 0,
+          bottom: convert_print_parameter_to_length_unit(margin_options[:bottom], length_unit) || 0,
+          right: convert_print_parameter_to_length_unit(margin_options[:right], length_unit) || 0
+        }
+
+        options[:tagged] = true if options[:outline]
+
+        defaults.merge(options).merge(
+          width: width,
+          height: height,
+          margin: margin
+        )
+      end
+
+      def convert_print_parameter_to_length_unit(parameter, length_unit)
+        return nil if parameter.nil?
+
+        pixels = nil
+
+        if parameter.is_a?(Numeric)
+          pixels = parameter
+        elsif parameter.is_a?(String)
+          text = parameter
+          unit = text[-2, 2].to_s.downcase
+          if UNIT_TO_PIXELS.key?(unit)
+            value_text = text[0...-2]
+          else
+            unit = "px"
+            value_text = text
+          end
+          value = parse_print_parameter_value(text, value_text)
+          pixels = value * UNIT_TO_PIXELS[unit]
+        else
+          raise "page.pdf() Cannot handle parameter type: #{js_typeof(parameter)}"
+        end
+
+        pixels / UNIT_TO_PIXELS.fetch(length_unit)
+      end
+
+      def parse_print_parameter_value(text, value_text)
+        value = Float(value_text)
+        raise "Failed to parse parameter value: #{text}" if value.nan?
+
+        value
+      rescue ArgumentError
+        raise "Failed to parse parameter value: #{text}"
+      end
+
+      def js_typeof(value)
+        case value
+        when String
+          "string"
+        when Numeric
+          "number"
+        when TrueClass, FalseClass
+          "boolean"
+        when Proc, Method
+          "function"
+        else
+          "object"
+        end
+      end
+
       # Check if this page is closed and raise error if so
       # @rbs return: void
       def assert_not_closed
         raise PageClosedError if closed?
       end
+
+      # @rbs cookie_url: String -- Cookie URL
+      # @rbs return: URI::Generic? -- Parsed URL or nil
+      def parse_cookie_url(cookie_url)
+        return nil if cookie_url.nil? || cookie_url.empty?
+
+        URI.parse(cookie_url)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def parse_cookie_url_strict(cookie_url)
+        normalized_url = URI.parse(cookie_url.to_s)
+        if normalized_url.scheme.nil? ||
+           (normalized_url.scheme.match?(/\Ahttps?\z/i) && normalized_url.host.to_s.empty?)
+          raise ArgumentError, "Invalid URL"
+        end
+        normalized_url
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Invalid URL"
+      end
+
+      def toggle_interception(phases, interception, expected)
+        if expected && interception.nil?
+          return @browsing_context.add_intercept(phases: phases).wait
+        end
+        if !expected && interception
+          @browsing_context.user_context.browser.remove_intercept(interception).wait
+          return nil
+        end
+        interception
+      end
+
+      # @rbs clip_x: Numeric -- Clip x coordinate
+      # @rbs clip_y: Numeric -- Clip y coordinate
+      # @rbs clip_width: Numeric -- Clip width
+      # @rbs clip_height: Numeric -- Clip height
+      # @rbs return: Array[Integer] -- Processed clip [x, y, width, height]
+      # ref: https://github.com/puppeteer/puppeteer/commit/2275c3c0c801d42514d6de127b9b1537d20356a9
+      def process_clip(clip_x:, clip_y:, clip_width:, clip_height:)
+        rounded_x = clip_x.round
+        rounded_y = clip_y.round
+        [
+          rounded_x,
+          rounded_y,
+          (clip_width + (clip_x - rounded_x)).round,
+          (clip_height + (clip_y - rounded_y)).round,
+        ]
+      end
     end
   end
 end