puppeteer-bidi 0.0.1.beta1

data/lib/puppeteer/bidi/query_handler.rb

@@ -0,0 +1,397 @@
+require 'singleton'
+
+module Puppeteer
+  module Bidi
+    # @api private
+    class QueryHandler
+      include Singleton
+
+      QUERY_SEPARATORS = %w[= /].freeze
+      BUILTIN_QUERY_HANDLERS = {
+        'aria' => 'ARIAQueryHandler',
+        'pierce' => 'PierceQueryHandler',
+        'xpath' => 'XPathQueryHandler',
+        'text' => 'TextQueryHandler'
+      }.freeze
+
+      Result = Data.define(:updated_selector, :polling, :query_handler)
+
+      def get_query_handler_and_selector(selector)
+        builtin_query_handler_entries.each do |name, handler|
+          if (result = detect_handler_from_selector(name, handler, selector))
+            return result
+          end
+        end
+
+        analyze_default_query_handler(selector)
+      end
+
+      private
+
+      class SelectorAnalysis
+        attr_reader :selector
+
+        def initialize(selector)
+          @selector = selector
+        end
+
+        def requires_raf_polling?
+          pseudo_class_present?
+        end
+
+        private
+
+        def pseudo_class_present?
+          in_string = nil
+          escape = false
+          bracket_depth = 0
+
+          selector.each_char.with_index do |char, index|
+            if escape
+              escape = false
+              next
+            end
+
+            if in_string
+              if char == '\\'
+                escape = true
+              elsif char == in_string
+                in_string = nil
+              end
+              next
+            end
+
+            case char
+            when '"', "'"
+              in_string = char
+            when '['
+              bracket_depth += 1
+            when ']'
+              bracket_depth -= 1 if bracket_depth.positive?
+            when '\\'
+              escape = true
+            when ':'
+              next_char = selector[index + 1]
+              next if next_char == ':'
+              return true if bracket_depth.zero?
+            end
+          end
+
+          false
+        end
+      end
+
+      def builtin_query_handler_entries
+        Enumerator.new do |y|
+          BUILTIN_QUERY_HANDLERS.each do |name, const_name|
+            if (handler = resolve_handler_constant(const_name))
+              y << [name, handler]
+            end
+          end
+        end
+      end
+
+      def detect_handler_from_selector(name, handler, selector)
+        QUERY_SEPARATORS.each do |separator|
+          prefix = "#{name}#{separator}"
+          next unless selector.start_with?(prefix)
+
+          updated_selector = selector[prefix.length..]
+          return Result.new(
+            updated_selector: updated_selector,
+            polling: (name == 'aria' ? 'raf' : 'mutation'),
+            query_handler: handler,
+          )
+        end
+
+        nil
+      end
+
+      def analyze_default_query_handler(selector)
+        analysis = SelectorAnalysis.new(selector)
+        polling = analysis.requires_raf_polling? ? 'raf' : 'mutation'
+
+        Result.new(
+          updated_selector: selector,
+          polling: polling,
+          query_handler: resolve_handler_constant('CSSQueryHandler'),
+        )
+      end
+
+      def default_query_handler_result(selector)
+        Result.new(
+          updated_selector: selector,
+          polling: 'mutation',
+          query_handler: resolve_handler_constant('CSSQueryHandler'),
+        )
+      end
+
+      def resolve_handler_constant(const_name)
+        return const_name if const_name.is_a?(Module)
+
+        Puppeteer::Bidi.const_get(const_name, false)
+      rescue NameError
+        nil
+      end
+
+      def build_query_handler_result(handler, selector, handler_name)
+        {
+          updated_selector: selector,
+          polling: (handler_name == 'aria' ? 'raf' : 'mutation'),
+          query_handler: handler,
+        }
+      end
+    end
+
+    class BaseQueryHandler
+      # Query for a single element matching the selector
+      # @param element [ElementHandle] Element to query from
+      # @param selector [String] Selector to match
+      # @return [ElementHandle, nil] Found element or nil
+      def run_query_one(element, selector)
+        realm = element.frame.isolated_realm
+
+        # Adopt the element into the isolated realm first.
+        # This ensures the realm is valid and triggers puppeteer_util reset if needed
+        # after navigation (mirrors Puppeteer's @bindIsolatedHandle decorator pattern).
+        adopted_element = realm.adopt_handle(element)
+
+        result = realm.call_function(
+          query_one_script,
+          false,
+          arguments: [
+            Serializer.serialize(realm.puppeteer_util_lazy_arg),
+            adopted_element.remote_value,
+            Serializer.serialize(selector)
+          ]
+        )
+
+        return nil if result['type'] == 'exception'
+
+        result_value = result['result']
+        return nil if result_value['type'] == 'null' || result_value['type'] == 'undefined'
+
+        handle = JSHandle.from(result_value, realm.core_realm)
+        return nil unless handle.is_a?(ElementHandle)
+
+        element.frame.main_realm.transfer_handle(handle)
+      ensure
+        adopted_element&.dispose
+      end
+
+      # Query for all elements matching the selector
+      # @param element [ElementHandle] Element to query from
+      # @param selector [String] Selector to match
+      # @return [Array<ElementHandle>] Array of found elements
+      def run_query_all(element, selector)
+        realm = element.frame.isolated_realm
+
+        # Adopt the element into the isolated realm first.
+        # This ensures the realm is valid and triggers puppeteer_util reset if needed
+        # after navigation (mirrors Puppeteer's @bindIsolatedHandle decorator pattern).
+        adopted_element = realm.adopt_handle(element)
+
+        result = realm.call_function(
+          query_all_script,
+          true,
+          arguments: [
+            Serializer.serialize(realm.puppeteer_util_lazy_arg),
+            adopted_element.remote_value,
+            Serializer.serialize(selector)
+          ]
+        )
+
+        return [] if result['type'] == 'exception'
+
+        result_value = result['result']
+        return [] unless result_value['type'] == 'array'
+
+        handles = result_value['value'].map do |element_value|
+          JSHandle.from(element_value, realm.core_realm)
+        end.select { |h| h.is_a?(ElementHandle) }
+
+        handles.map { |h| element.frame.main_realm.transfer_handle(h) }
+      ensure
+        adopted_element&.dispose
+      end
+
+      def wait_for(element_or_frame, selector, visible: nil, hidden: nil, timeout: nil, polling: nil, &block)
+        if element_or_frame.is_a?(Frame)
+          wait_for_in_frame(element_or_frame, nil, selector, visible: visible, hidden: hidden, timeout: timeout, polling: polling, &block)
+        elsif element_or_frame.is_a?(ElementHandle)
+          frame = element_or_frame.frame
+          root = frame.isolated_realm.adopt_handle(element_or_frame)
+          wait_for_in_frame(frame, root, selector, visible: visible, hidden: hidden, timeout: timeout, polling: polling, &block)
+        else
+          raise ArgumentError, "Unsupported query root: #{element_or_frame.class}"
+        end
+      end
+
+      private
+
+      def query_one_script
+        raise NotImplementedError, "#{self.class}#query_one_script must be implemented"
+      end
+
+      def query_all_script
+        raise NotImplementedError, "#{self.class}#query_all_script must be implemented"
+      end
+
+      def wait_for_selector_script
+        raise NotImplementedError, "#{self.class}#wait_for_selector_script must be implemented"
+      end
+
+      def wait_for_in_frame(frame, root, selector, visible:, hidden:, timeout:, polling:, &block)
+        raise FrameDetachedError if frame.detached?
+
+        visibility = if visible
+                        true
+                      elsif hidden
+                        false
+                      end
+
+        resolved_polling = (visible || hidden ? 'raf' : polling)
+
+        options = {}
+        options[:polling] = resolved_polling if resolved_polling
+        options[:timeout] = timeout if timeout
+
+        begin
+          handle = frame.isolated_realm.wait_for_function(
+            wait_for_selector_script,
+            options,
+            frame.isolated_realm.puppeteer_util_lazy_arg,
+            selector,
+            root,
+            visibility,
+            &block
+          )
+
+          return nil unless handle
+
+          unless handle.is_a?(ElementHandle)
+            begin
+              handle.dispose
+            rescue StandardError
+              # Ignored: primitive handles may not support dispose.
+            end
+            return nil
+          end
+
+          frame.main_realm.transfer_handle(handle)
+        rescue Puppeteer::Bidi::TimeoutError => e
+          raise Puppeteer::Bidi::TimeoutError,
+                "Waiting for selector `#{selector}` failed: Waiting failed: #{e.message.split(': ').last}"
+        rescue StandardError => e
+          message = "Waiting for selector `#{selector}` failed"
+          alias_selector = selector.sub('//*', '//')
+          if alias_selector != selector
+            message = "#{message} | alias: Waiting for selector `#{alias_selector}` failed"
+          end
+          raise StandardError.new(message), cause: e
+        end
+      end
+    end
+
+    class CSSQueryHandler < BaseQueryHandler
+      private
+
+      def query_one_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, element, selector) => {
+          return PuppeteerUtil.cssQuerySelector(element, selector);
+        }
+        JAVASCRIPT
+      end
+
+      def query_all_script
+        <<~JAVASCRIPT
+        async (PuppeteerUtil, element, selector) => {
+          return [...PuppeteerUtil.cssQuerySelectorAll(element, selector)];
+        }
+        JAVASCRIPT
+      end
+
+      def wait_for_selector_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, selector, root, visibility) => {
+          const element = PuppeteerUtil.cssQuerySelector(root || document, selector);
+          return PuppeteerUtil.checkVisibility(element, visibility === null ? undefined : visibility);
+        }
+        JAVASCRIPT
+      end
+    end
+
+    class XPathQueryHandler < BaseQueryHandler
+      private
+
+      def query_one_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, element, selector) => {
+          for (const result of PuppeteerUtil.xpathQuerySelectorAll(element, selector, 1)) {
+            return result;
+          }
+          return null;
+        }
+        JAVASCRIPT
+      end
+
+      def query_all_script
+        <<~JAVASCRIPT
+        async (PuppeteerUtil, element, selector) => {
+          return [...PuppeteerUtil.xpathQuerySelectorAll(element, selector)];
+        }
+        JAVASCRIPT
+      end
+
+      def wait_for_selector_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, selector, root, visibility) => {
+          let element = null;
+          for (const result of PuppeteerUtil.xpathQuerySelectorAll(root || document, selector, 1)) {
+            element = result;
+            break;
+          }
+          return PuppeteerUtil.checkVisibility(element, visibility === null ? undefined : visibility);
+        }
+        JAVASCRIPT
+      end
+    end
+
+    class TextQueryHandler < BaseQueryHandler
+      private
+
+      def query_one_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, element, selector) => {
+          for (const result of PuppeteerUtil.textQuerySelectorAll(element, selector)) {
+            return result;
+          }
+          return null;
+        }
+        JAVASCRIPT
+      end
+
+      def query_all_script
+        <<~JAVASCRIPT
+        async (PuppeteerUtil, element, selector) => {
+          return [...PuppeteerUtil.textQuerySelectorAll(element, selector)];
+        }
+        JAVASCRIPT
+      end
+
+      def wait_for_selector_script
+        <<~JAVASCRIPT
+        (PuppeteerUtil, selector, root, visibility) => {
+          let element = null;
+          for (const result of PuppeteerUtil.textQuerySelectorAll(root || document, selector)) {
+            element = result;
+            break;
+          }
+          return PuppeteerUtil.checkVisibility(element, visibility === null ? undefined : visibility);
+        }
+        JAVASCRIPT
+      end
+    end
+  end
+end

data/lib/puppeteer/bidi/realm.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Puppeteer
+  module Bidi
+    # Base realm abstraction that mirrors Puppeteer's Realm class hierarchy.
+    # 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
+
+      def initialize(timeout_settings)
+        @timeout_settings = timeout_settings
+        @task_manager = TaskManager.new
+        @disposed = false
+      end
+
+      def environment
+        raise NotImplementedError, 'Subclass must expose its environment object'
+      end
+
+      def page
+        env = environment
+        return env.page if env.respond_to?(:page)
+
+        raise NotImplementedError, 'Environment must expose a page reference'
+      end
+
+      def default_timeout
+        @timeout_settings.timeout
+      end
+
+      def wait_for_function(page_function, options = {}, *args, &block)
+        ensure_environment_active!
+
+        polling = options[:polling] || 'raf'
+        if polling.is_a?(Numeric) && polling < 0
+          raise ArgumentError, "Cannot poll with non-positive interval: #{polling}"
+        end
+
+        timeout = options.key?(:timeout) ? options[:timeout] : default_timeout
+        wait_task_options = {
+          polling: polling,
+          timeout: timeout,
+          root: options[:root]
+        }
+
+        result = WaitTask.new(self, wait_task_options, page_function, *args).result
+
+        Async(&block).wait if block
+
+        result.wait
+      end
+
+      def dispose
+        return if @disposed
+
+        @disposed = true
+        @task_manager.terminate_all(Error.new('waitForFunction failed: frame got detached.'))
+      end
+
+      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
+      def adopt_handle(handle)
+        raise ArgumentError, 'handle must be a JSHandle' unless handle.is_a?(JSHandle)
+
+        evaluate_handle('(node) => node', handle)
+      end
+
+      # 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
+      def transfer_handle(handle)
+        raise ArgumentError, 'handle must be a JSHandle' unless handle.is_a?(JSHandle)
+
+        return handle if handle.realm.equal?(self)
+
+        adopted = adopt_handle(handle)
+        handle.dispose
+        adopted
+      end
+
+      private
+
+      def ensure_environment_active!
+        env = environment
+        return unless env.respond_to?(:detached?)
+
+        raise FrameDetachedError if env.detached?
+      end
+    end
+
+    # 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
+
+      def initialize(frame, core_realm)
+        @frame = frame
+        @core_realm = core_realm
+        @puppeteer_util_handle = nil
+        @puppeteer_util_lazy_arg = nil
+        super(frame.page.timeout_settings)
+
+        setup_core_realm_callbacks
+      end
+
+      def environment
+        @frame
+      end
+
+      def page
+        @frame.page
+      end
+
+      def evaluate(script, *args)
+        ensure_environment_active!
+
+        result = execute_with_core(script, args).wait
+        handle_evaluation_exception(result) if result['type'] == 'exception'
+
+        actual_result = result['result'] || result
+        Deserializer.deserialize(actual_result)
+      end
+
+      def evaluate_handle(script, *args)
+        ensure_environment_active!
+
+        result = execute_with_core(script, args).wait
+        handle_evaluation_exception(result) if result['type'] == 'exception'
+
+        JSHandle.from(result['result'], @core_realm)
+      end
+
+      def call_function(function_declaration, await_promise, **options)
+        ensure_environment_active!
+
+        result = @core_realm.call_function(function_declaration, await_promise, **options).wait
+        handle_evaluation_exception(result) if result['type'] == 'exception'
+
+        result
+      end
+
+      def puppeteer_util
+        return @puppeteer_util_handle if @puppeteer_util_handle
+
+        script = "(function() { const module = { exports: {} }; #{PUPPETEER_INJECTED_SOURCE}; return module.exports.default; })()"
+        @puppeteer_util_handle = evaluate_handle(script)
+      end
+
+      def puppeteer_util_lazy_arg
+        @puppeteer_util_lazy_arg ||= LazyArg.create { puppeteer_util }
+      end
+
+      def reset_puppeteer_util_handle!
+        handle = @puppeteer_util_handle
+        @puppeteer_util_handle = nil
+        @puppeteer_util_lazy_arg = nil
+        return unless handle
+
+        begin
+          handle.dispose
+        rescue StandardError
+          # The realm might already be gone; ignore cleanup failures.
+        end
+      end
+
+      def wait_for_function(page_function, options = {}, *args, &block)
+        raise FrameDetachedError if @frame.detached?
+
+        super
+      end
+
+      def dispose
+        reset_puppeteer_util_handle!
+        super
+      end
+
+      private
+
+      def execute_with_core(script, args)
+        script_trimmed = script.strip
+
+        is_iife = script_trimmed.match?(/\)\s*\(\s*\)\s*\z/)
+        is_function = !is_iife && (
+          script_trimmed.match?(/\A\s*(?:async\s+)?(?:\(.*?\)|[a-zA-Z_$][\w$]*)\s*=>/) ||
+          script_trimmed.match?(/\A\s*(?:async\s+)?function\s*\w*\s*\(/)
+        )
+
+        if is_function
+          serialized_args = args.map { |arg| Serializer.serialize(arg) }
+          options = {}
+          options[:arguments] = serialized_args unless serialized_args.empty?
+          @core_realm.call_function(script_trimmed, true, **options)
+        else
+          @core_realm.evaluate(script_trimmed, true)
+        end
+      end
+
+      def handle_evaluation_exception(result)
+        exception_details = result['exceptionDetails']
+        return unless exception_details
+
+        text = exception_details['text'] || 'Evaluation failed'
+        exception = exception_details['exception']
+
+        error_message = text
+
+        if exception && exception['type'] != 'error'
+          thrown_value = Deserializer.deserialize(exception)
+          error_message = "Evaluation failed: #{thrown_value}"
+        end
+
+        raise error_message
+      end
+
+      def setup_core_realm_callbacks
+        @core_realm.environment = @frame if @core_realm.respond_to?(:environment=)
+
+        destroyed_listener = proc do |payload|
+          reason = payload.is_a?(Hash) ? payload[:reason] : payload
+          task_manager.terminate_all(Error.new(reason || 'Realm destroyed'))
+          dispose
+        end
+
+        updated_listener = proc do
+          reset_puppeteer_util_handle!
+          task_manager.rerun_all
+        end
+
+        @core_realm.on(:destroyed, &destroyed_listener)
+        @core_realm.on(:updated, &updated_listener)
+      end
+    end
+  end
+end