puppeteer-bidi 0.0.1.beta1

data/lib/puppeteer/bidi/element_handle.rb

@@ -0,0 +1,602 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Puppeteer
+  module Bidi
+    # ElementHandle represents a reference to a DOM element
+    # Based on Puppeteer's BidiElementHandle implementation
+    # This extends JSHandle with DOM-specific methods
+    class ElementHandle < JSHandle
+      # Bounding box data class representing element position and dimensions
+      BoundingBox = Data.define(:x, :y, :width, :height)
+
+      # Point data class representing a coordinate
+      Point = Data.define(:x, :y)
+
+      # Box model data class representing element's CSS box model
+      # Each quad (content, padding, border, margin) contains 4 Points representing corners
+      # Corners are ordered: top-left, top-right, bottom-right, bottom-left
+      BoxModel = Data.define(:content, :padding, :border, :margin, :width, :height)
+
+      # Factory method to create ElementHandle from remote value
+      # @rbs remote_value: Hash[String, untyped]
+      # @rbs realm: Core::Realm
+      # @rbs return: ElementHandle
+      def self.from(remote_value, realm)
+        new(realm, remote_value)
+      end
+
+      # Query for a descendant element matching the selector
+      # Supports CSS selectors and prefixed selectors (xpath/, text/, aria/, pierce/)
+      # @rbs selector: String
+      # @rbs return: ElementHandle?
+      def query_selector(selector)
+        assert_not_disposed
+
+        result = QueryHandler.instance.get_query_handler_and_selector(selector)
+        result.query_handler.new.run_query_one(self, result.updated_selector)
+      end
+
+      # Query for all descendant elements matching the selector
+      # Supports CSS selectors and prefixed selectors (xpath/, text/, aria/, pierce/)
+      # @rbs selector: String
+      # @rbs return: Array[ElementHandle]
+      def query_selector_all(selector)
+        assert_not_disposed
+
+        result = QueryHandler.instance.get_query_handler_and_selector(selector)
+        result.query_handler.new.run_query_all(self, result.updated_selector)
+      end
+
+      # Evaluate a function on the first element matching the selector
+      # @rbs selector: String
+      # @rbs page_function: String
+      # @rbs *args: untyped
+      # @rbs return: untyped
+      def eval_on_selector(selector, page_function, *args)
+        assert_not_disposed
+
+        element_handle = query_selector(selector)
+        raise SelectorNotFoundError, selector unless element_handle
+
+        begin
+          element_handle.evaluate(page_function, *args)
+        ensure
+          element_handle.dispose
+        end
+      end
+
+      # Evaluate a function on all elements matching the selector
+      # @rbs selector: String
+      # @rbs page_function: String
+      # @rbs *args: untyped
+      # @rbs return: untyped
+      def eval_on_selector_all(selector, page_function, *args)
+        assert_not_disposed
+
+        # Get all matching elements
+        element_handles = query_selector_all(selector)
+
+        begin
+          # Create an array handle containing all element handles
+          # Use evaluateHandle to create an array in the browser context
+          array_handle = @realm.call_function(
+            '(...elements) => elements',
+            false,
+            arguments: element_handles.map(&:remote_value)
+          ).wait
+
+          # Create a JSHandle for the array
+          array_js_handle = JSHandle.from(array_handle['result'], @realm)
+
+          begin
+            # Evaluate the page_function with the array as first argument
+            array_js_handle.evaluate(page_function, *args)
+          ensure
+            array_js_handle.dispose
+          end
+        ensure
+          # Dispose all element handles
+          element_handles.each(&:dispose)
+        end
+      end
+
+      # Wait for an element matching the selector to appear as a descendant of this element
+      # @rbs selector: String
+      # @rbs visible: bool?
+      # @rbs hidden: bool?
+      # @rbs timeout: Numeric?
+      # @rbs &block: ((ElementHandle?) -> void)?
+      # @rbs return: ElementHandle?
+      def wait_for_selector(selector, visible: nil, hidden: nil, timeout: nil, &block)
+        result = QueryHandler.instance.get_query_handler_and_selector(selector)
+        result.query_handler.new.wait_for(self, result.updated_selector, visible: visible, hidden: hidden, polling: result.polling, timeout: timeout, &block)
+      end
+
+      # Click the element
+      # @rbs button: String
+      # @rbs count: Integer
+      # @rbs delay: Numeric?
+      # @rbs offset: Hash[Symbol, Numeric]?
+      # @rbs return: void
+      def click(button: 'left', count: 1, delay: nil, offset: nil)
+        assert_not_disposed
+
+        scroll_into_view_if_needed
+        point = clickable_point(offset: offset)
+
+        frame.page.mouse.click(point.x, point.y, button: button, count: count, delay: delay)
+      end
+
+      # Type text into the element
+      # @rbs text: String
+      # @rbs delay: Numeric
+      # @rbs return: void
+      def type(text, delay: 0)
+        assert_not_disposed
+
+        # Focus the element first
+        focus
+
+        # Get keyboard instance - use frame.page to access the page
+        # Following Puppeteer's pattern: this.frame.page().keyboard
+        keyboard = Keyboard.new(frame.page, @realm.browsing_context)
+        keyboard.type(text, delay: delay)
+      end
+
+      # Press a key on the element
+      # @rbs key: String
+      # @rbs delay: Numeric?
+      # @rbs text: String?
+      # @rbs return: void
+      def press(key, delay: nil, text: nil)
+        assert_not_disposed
+
+        # Focus the element first
+        focus
+
+        # Get keyboard instance - use frame.page to access the page
+        # Following Puppeteer's pattern: this.frame.page().keyboard
+        keyboard = Keyboard.new(frame.page, @realm.browsing_context)
+        keyboard.press(key, delay: delay, text: text)
+      end
+
+      # Get the frame this element belongs to
+      # Following Puppeteer's pattern: realm.environment
+      # @rbs return: Frame
+      def frame
+        @realm.environment
+      end
+
+      # Get the content frame for iframe/frame elements
+      # Returns the frame that the iframe/frame element refers to
+      # @rbs return: Frame?
+      def content_frame
+        assert_not_disposed
+
+        handle = evaluate_handle(<<~JS)
+          element => {
+            if (element instanceof HTMLIFrameElement || element instanceof HTMLFrameElement) {
+              return element.contentWindow;
+            }
+            return undefined;
+          }
+        JS
+
+        begin
+          value = handle.remote_value
+          if value['type'] == 'window'
+            # Find the frame with matching browsing context ID
+            context_id = value.dig('value', 'context')
+            return nil unless context_id
+
+            frame.page.frames.find { |f| f.browsing_context.id == context_id }
+          else
+            nil
+          end
+        ensure
+          handle.dispose
+        end
+      end
+
+      # Check if the element is visible
+      # An element is considered visible if:
+      # - It has computed styles
+      # - Its visibility is not 'hidden' or 'collapse'
+      # - Its bounding box is not empty (width > 0 AND height > 0)
+      # @rbs return: bool
+      def visible?
+        check_visibility(true)
+      end
+
+      # Check if the element is hidden
+      # An element is considered hidden if:
+      # - It has no computed styles
+      # - Its visibility is 'hidden' or 'collapse'
+      # - Its bounding box is empty (width == 0 OR height == 0)
+      # @rbs return: bool
+      def hidden?
+        check_visibility(false)
+      end
+
+      # Convert the current handle to the given element type
+      # Validates that the element matches the expected tag name
+      # @rbs tag_name: String
+      # @rbs return: ElementHandle
+      def to_element(tag_name)
+        assert_not_disposed
+
+        is_matching = evaluate('(node, tagName) => node.nodeName === tagName.toUpperCase()', tag_name)
+        raise "Element is not a(n) `#{tag_name}` element" unless is_matching
+
+        self
+      end
+
+      # Focus the element
+      # @rbs return: void
+      def focus
+        assert_not_disposed
+
+        evaluate('element => element.focus()')
+      end
+
+      # Hover over the element
+      # Scrolls element into view if needed and moves mouse to element center
+      # @rbs return: void
+      def hover
+        assert_not_disposed
+
+        scroll_into_view_if_needed
+        point = clickable_point
+        frame.page.mouse.move(point.x, point.y)
+      end
+
+      # Upload files to this element (for <input type="file">)
+      # Following Puppeteer's implementation: ElementHandle.uploadFile -> Frame.setFiles
+      # @rbs *files: String
+      # @rbs return: void
+      def upload_file(*files)
+        assert_not_disposed
+
+        # Resolve relative paths to absolute paths
+        files = files.map do |file|
+          if File.absolute_path?(file)
+            file
+          else
+            File.expand_path(file)
+          end
+        end
+
+        frame.set_files(self, files)
+      end
+
+      # Get the remote value as a SharedReference for BiDi commands
+      # @rbs return: Hash[Symbol, String]
+      def remote_value_as_shared_reference
+        if @remote_value['sharedId']
+          { sharedId: @remote_value['sharedId'] }
+        else
+          { handle: @remote_value['handle'] }
+        end
+      end
+
+      # Scroll element into view if needed
+      # @rbs return: void
+      def scroll_into_view_if_needed
+        assert_not_disposed
+
+        # Check if element is already visible
+        return if intersecting_viewport?(threshold: 1)
+
+        scroll_into_view
+      end
+
+      # Scroll element into view
+      # @rbs return: void
+      def scroll_into_view
+        assert_not_disposed
+
+        evaluate('element => element.scrollIntoView({block: "center", inline: "center", behavior: "instant"})')
+      end
+
+      # Check if element is intersecting the viewport
+      # @rbs threshold: Numeric
+      # @rbs return: bool
+      def intersecting_viewport?(threshold: 0)
+        assert_not_disposed
+
+        result = evaluate(<<~JS, threshold)
+          (element, threshold) => {
+            return new Promise(resolve => {
+              const observer = new IntersectionObserver(entries => {
+                resolve(entries[0].intersectionRatio > threshold);
+                observer.disconnect();
+              });
+              observer.observe(element);
+            });
+          }
+        JS
+
+        result
+      end
+
+      # Get clickable point for the element
+      # @rbs offset: Hash[Symbol, Numeric]?
+      # @rbs return: Point
+      def clickable_point(offset: nil)
+        assert_not_disposed
+
+        box = clickable_box
+        raise 'Node is either not clickable or not an Element' unless box
+
+        if offset
+          Point.new(
+            x: box[:x] + offset[:x],
+            y: box[:y] + offset[:y]
+          )
+        else
+          Point.new(
+            x: box[:x] + box[:width] / 2,
+            y: box[:y] + box[:height] / 2
+          )
+        end
+      end
+
+      # Get the bounding box of the element
+      # Uses getBoundingClientRect() to get the element's position and size
+      # @rbs return: BoundingBox?
+      def bounding_box
+        assert_not_disposed
+
+        result = evaluate(<<~JS)
+          element => {
+            if (!(element instanceof Element)) {
+              return null;
+            }
+            const rect = element.getBoundingClientRect();
+            return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
+          }
+        JS
+
+        return nil unless result
+
+        # Return nil if element has zero dimensions (not visible)
+        return nil if result['width'].zero? && result['height'].zero?
+
+        BoundingBox.new(
+          x: result['x'],
+          y: result['y'],
+          width: result['width'],
+          height: result['height']
+        )
+      end
+
+      # Get the box model of the element (content, padding, border, margin)
+      # @rbs return: BoxModel?
+      def box_model
+        assert_not_disposed
+
+        model = evaluate(<<~JS)
+          element => {
+            if (!(element instanceof Element)) {
+              return null;
+            }
+            // Element is not visible
+            if (element.getClientRects().length === 0) {
+              return null;
+            }
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            const offsets = {
+              padding: {
+                left: parseInt(style.paddingLeft, 10),
+                top: parseInt(style.paddingTop, 10),
+                right: parseInt(style.paddingRight, 10),
+                bottom: parseInt(style.paddingBottom, 10),
+              },
+              margin: {
+                left: -parseInt(style.marginLeft, 10),
+                top: -parseInt(style.marginTop, 10),
+                right: -parseInt(style.marginRight, 10),
+                bottom: -parseInt(style.marginBottom, 10),
+              },
+              border: {
+                left: parseInt(style.borderLeftWidth, 10),
+                top: parseInt(style.borderTopWidth, 10),
+                right: parseInt(style.borderRightWidth, 10),
+                bottom: parseInt(style.borderBottomWidth, 10),
+              },
+            };
+            const border = [
+              {x: rect.left, y: rect.top},
+              {x: rect.left + rect.width, y: rect.top},
+              {x: rect.left + rect.width, y: rect.top + rect.height},
+              {x: rect.left, y: rect.top + rect.height},
+            ];
+            const padding = transformQuadWithOffsets(border, offsets.border);
+            const content = transformQuadWithOffsets(padding, offsets.padding);
+            const margin = transformQuadWithOffsets(border, offsets.margin);
+            return {
+              content,
+              padding,
+              border,
+              margin,
+              width: rect.width,
+              height: rect.height,
+            };
+
+            function transformQuadWithOffsets(quad, offsets) {
+              return [
+                {
+                  x: quad[0].x + offsets.left,
+                  y: quad[0].y + offsets.top,
+                },
+                {
+                  x: quad[1].x - offsets.right,
+                  y: quad[1].y + offsets.top,
+                },
+                {
+                  x: quad[2].x - offsets.right,
+                  y: quad[2].y - offsets.bottom,
+                },
+                {
+                  x: quad[3].x + offsets.left,
+                  y: quad[3].y - offsets.bottom,
+                },
+              ];
+            }
+          }
+        JS
+
+        return nil unless model
+
+        # Convert raw arrays to Point objects for each quad
+        BoxModel.new(
+          content: model['content'].map { |p| Point.new(x: p['x'], y: p['y']) },
+          padding: model['padding'].map { |p| Point.new(x: p['x'], y: p['y']) },
+          border: model['border'].map { |p| Point.new(x: p['x'], y: p['y']) },
+          margin: model['margin'].map { |p| Point.new(x: p['x'], y: p['y']) },
+          width: model['width'],
+          height: model['height']
+        )
+      end
+
+      # Get the clickable box for the element
+      # Uses getClientRects() to handle wrapped/multi-line elements correctly
+      # Following Puppeteer's implementation:
+      # https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts#clickableBox
+      # @rbs return: Hash[Symbol, Numeric]?
+      def clickable_box
+        assert_not_disposed
+
+        # Get client rects - returns multiple boxes for wrapped elements
+        boxes = evaluate(<<~JS)
+          element => {
+            if (!(element instanceof Element)) {
+              return null;
+            }
+            return [...element.getClientRects()].map(rect => {
+              return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
+            });
+          }
+        JS
+
+        return nil unless boxes&.is_a?(Array) && !boxes.empty?
+
+        # Intersect boxes with frame boundaries
+        intersect_bounding_boxes_with_frame(boxes)
+
+        # TODO: Handle parent frames (for iframe support)
+        # frame = self.frame
+        # while (parent_frame = frame.parent_frame)
+        #   # Adjust coordinates for parent frame offset
+        # end
+
+        # Find first box with valid dimensions
+        box = boxes.find { |rect| rect['width'] >= 1 && rect['height'] >= 1 }
+        return nil unless box
+
+        {
+          x: box['x'],
+          y: box['y'],
+          width: box['width'],
+          height: box['height']
+        }
+      end
+
+      private
+
+      # Intersect bounding boxes with frame viewport boundaries
+      # Modifies boxes in-place to clip them to visible area
+      # @rbs boxes: Array[Hash[String, Numeric]]
+      # @rbs return: void
+      def intersect_bounding_boxes_with_frame(boxes)
+        # Get document dimensions using element's evaluate (which handles deserialization)
+        dimensions = evaluate(<<~JS)
+          element => {
+            return {
+              documentWidth: element.ownerDocument.documentElement.clientWidth,
+              documentHeight: element.ownerDocument.documentElement.clientHeight
+            };
+          }
+        JS
+
+        document_width = dimensions['documentWidth']
+        document_height = dimensions['documentHeight']
+
+        # Intersect each box with document boundaries
+        boxes.each do |box|
+          intersect_bounding_box(box, document_width, document_height)
+        end
+      end
+
+      # Intersect a single bounding box with given width/height boundaries
+      # Modifies box in-place
+      # @rbs box: Hash[String, Numeric]
+      # @rbs width: Numeric
+      # @rbs height: Numeric
+      # @rbs return: void
+      def intersect_bounding_box(box, width, height)
+        # Clip width
+        box['width'] = [
+          box['x'] >= 0 ?
+            [width - box['x'], box['width']].min :
+            [width, box['width'] + box['x']].min,
+          0
+        ].max
+
+        # Clip height
+        box['height'] = [
+          box['y'] >= 0 ?
+            [height - box['y'], box['height']].min :
+            [height, box['height'] + box['y']].min,
+          0
+        ].max
+
+        # Ensure non-negative coordinates
+        box['x'] = [box['x'], 0].max
+        box['y'] = [box['y'], 0].max
+      end
+
+      # Check element visibility
+      # @rbs visible: bool
+      # @rbs return: bool
+      def check_visibility(visible)
+        assert_not_disposed
+
+        evaluate(<<~JS, visible)
+          (node, visible) => {
+            const HIDDEN_VISIBILITY_VALUES = ['hidden', 'collapse'];
+
+            if (!node) {
+              return visible === false;
+            }
+
+            // For text nodes, check parent element
+            const element = node.nodeType === Node.TEXT_NODE ? node.parentElement : node;
+            if (!element) {
+              return visible === false;
+            }
+
+            const style = window.getComputedStyle(element);
+            const rect = element.getBoundingClientRect();
+            const isBoundingBoxEmpty = rect.width === 0 || rect.height === 0;
+
+            const isVisible = style &&
+              !HIDDEN_VISIBILITY_VALUES.includes(style.visibility) &&
+              !isBoundingBoxEmpty;
+
+            return visible === isVisible;
+          }
+        JS
+      end
+
+      # String representation includes element type
+      # @rbs return: String
+      def to_s
+        return 'ElementHandle@disposed' if disposed?
+        'ElementHandle@node'
+      end
+    end
+  end
+end

data/lib/puppeteer/bidi/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Puppeteer
+  module Bidi
+    class Error < StandardError; end
+
+    # Raised when attempting to use a disposed JSHandle or ElementHandle
+    class JSHandleDisposedError < Error
+      def initialize
+        super('JSHandle is disposed')
+      end
+    end
+
+    # Raised when attempting to use a closed Page
+    class PageClosedError < Error
+      def initialize
+        super('Page is closed')
+      end
+    end
+
+    # Raised when attempting to use a detached Frame
+    class FrameDetachedError < Error
+      def initialize(message = 'Frame is detached')
+        super(message)
+      end
+    end
+
+    # Raised when a selector does not match any elements
+    class SelectorNotFoundError < Error
+      attr_reader :selector
+
+      def initialize(selector)
+        @selector = selector
+        super("Error: failed to find element matching selector \"#{selector}\"")
+      end
+    end
+
+    # Raised when a timeout occurs (e.g., navigation timeout)
+    class TimeoutError < Error
+    end
+  end
+end

data/lib/puppeteer/bidi/file_chooser.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Puppeteer
+  module Bidi
+    # FileChooser represents a file chooser dialog opened by an input element
+    # Based on Puppeteer's FileChooser implementation
+    class FileChooser
+      # @param element [ElementHandle] The input element that opened the file chooser
+      # @param multiple [Boolean] Whether multiple files can be selected
+      def initialize(element, multiple)
+        @element = element
+        @multiple = multiple
+        @handled = false
+      end
+
+      # Check if multiple files can be selected
+      # @return [Boolean] True if multiple files can be selected
+      def multiple?
+        @multiple
+      end
+
+      # Accept the file chooser with the given file paths
+      # @param paths [Array<String>] File paths to accept
+      # @raise [RuntimeError] If the file chooser has already been handled
+      # @raise [RuntimeError] If multiple files passed to single-file input
+      def accept(paths)
+        raise 'Cannot accept FileChooser which is already handled!' if @handled
+
+        # Validate that single-file inputs don't receive multiple files
+        if !@multiple && paths.length > 1
+          raise 'Multiple file paths passed to a file input that does not accept multiple files'
+        end
+
+        @handled = true
+        @element.upload_file(*paths)
+      end
+
+      # Cancel the file chooser
+      # @raise [RuntimeError] If the file chooser has already been handled
+      def cancel
+        raise 'Cannot cancel FileChooser which is already handled!' if @handled
+
+        @handled = true
+        @element.evaluate(<<~JAVASCRIPT)
+        element => {
+          element.dispatchEvent(new Event('cancel', {bubbles: true}));
+        }
+        JAVASCRIPT
+      end
+    end
+  end
+end