capybara-lightpanda 0.9.0 → 0.11.0

data/lib/capybara/lightpanda/node.rb

@@ -13,6 +13,22 @@ module Capybara
         @remote_object_id = remote_object_id
       end
 
+      # Capybara::Driver::Node#native returns the constructor's second argument,
+      # which here is the raw CDP objectId — a String. So the Selenium/Cuprite
+      # idiom `element.native.send_keys(...)` (solidus's
+      # return_authorizations_spec.rb does exactly that) died with
+      # "undefined method 'send_keys' for an instance of String". This driver
+      # has no lower-level node object behind the Capybara one — the CDP handle
+      # IS this Node (see #remote_object_id) — so `native` is self.
+      #
+      # Safe against Capybara::Driver::Node#==, which compares `native ==
+      # other.native` and would recurse forever on a self-returning `native`:
+      # #== and #eql? below are full overrides that never call super and never
+      # read #native.
+      def native
+        self
+      end
+
       def text
         call("function() { return this.textContent }")
       end
@@ -21,10 +37,11 @@ module Capybara
         filter_text(call("function() { return this.textContent }"))
       end
 
-      # Lightpanda's innerText returns textContent verbatim (no rendering, so no
-      # hidden-descendant filtering). Walk descendants ourselves, skipping nodes
-      # that fail VISIBLE_JS, and emit newlines around block-display elements
-      # (the part of innerText behavior we still need).
+      # Delegates to _lightpanda.visibleText, which gates on visibility (a
+      # not-visible element reads as "" — WebDriver semantics) and otherwise
+      # hands the rendered-text collection (block line breaks + display:none
+      # descendant skipping) to native innerText (#2785/#2795). We normalize the
+      # whitespace here to match Capybara's expected Chrome semantics.
       def visible_text
         call(VISIBLE_TEXT_JS).to_s
                              .gsub(/\A[[:space:]&&[^\u00A0]]+/, "")
@@ -69,6 +86,17 @@ module Capybara
         previous
       end
 
+      # Quiet form of the `isConnected` guard every other operation carries:
+      # true while the node is still attached to a live document, false once
+      # it has been detached or its document navigated away (mirrors Ferrum's
+      # `Node#exists?`, whose probe is `DOM.resolveNode`). Anything else that
+      # goes wrong still raises — only "gone" is turned into false.
+      def exists?
+        call("function() { return true; }")
+      rescue ObsoleteNode, NodeNotFoundError, NoExecutionContextError
+        false
+      end
+
       # Routed through #call (not a bare call_function_on) so a detached
       # host raises ObsoleteNode like every other node operation — Capybara's
       # automatic_reload then re-finds the host instead of silently reading
@@ -107,8 +135,15 @@ module Capybara
         call("function() { this.dispatchEvent(new MouseEvent('dblclick', {bubbles: true, cancelable: true})) }")
       end
 
+      # A real pointer entering an element fires `mouseover` (bubbling) AND
+      # `mouseenter` (non-bubbling), in that order. Dispatching only `mouseover`
+      # silently no-ops the `mouseenter->menu#open` Stimulus idiom and the
+      # Floating UI / tippy-style menus built on it — the dominant hover-menu
+      # pattern in Rails apps — so fire both. CSS `:hover` still reveals nothing
+      # (upstream tracks no pointer state); test/features/hover_test.rb pins
+      # both halves.
       def hover
-        call("function() { this.dispatchEvent(new MouseEvent('mouseover', {bubbles: true, cancelable: true})) }")
+        call(HOVER_JS)
       end
 
       # Kept as a deliberate no-op despite upstream now tracking scroll position
@@ -150,17 +185,64 @@ module Capybara
       end
 
       # Capybara's drag-and-drop API (`Element#drop`). String/Pathname arguments
-      # are file paths — read here and rebuilt as `File` objects in the page;
-      # Hash arguments are `{ mime_type => data }` string drops. We assemble a
-      # `DataTransfer` and fire `dragenter` -> `dragover` -> `drop` on this
-      # element, so HTML5 dropzones see the payload via `event.dataTransfer`.
+      # are file paths; Hash arguments are `{ mime_type => data }` string drops.
+      # We assemble a `DataTransfer` and fire `dragenter` -> `dragover` -> `drop`
+      # on this element, so HTML5 dropzones see the payload via
+      # `event.dataTransfer`.
+      #
+      # Files reach the page the way Cuprite's #316 does it: a hidden
+      # `<input type=file>` is attached to this element's document,
+      # `DOM.setFileInputFiles` points it at the paths (the browser reads the
+      # bytes off disk itself), and the drop JS moves `input.files` into the
+      # DataTransfer and removes the input. Previously the bytes were base64'd
+      # into the `Runtime.callFunctionOn` message, which capped a drop at
+      # ~70 MB under `--cdp-max-message-size` and pinned every byte in Ruby;
+      # now the size ceiling is Lightpanda's own file handling. Paths are read
+      # on the machine running Lightpanda (local for the spawned process),
+      # exactly like `attach_file`.
       #
       # DataTransfer/DataTransferItem/DragEvent landed upstream in PR #2671
       # (build ≥6699) and are guaranteed by the MINIMUM_NIGHTLY_BUILD floor;
       # without them the drop JS raises "DataTransfer is not defined".
       def drop(*args)
-        files, strings = partition_drop_args(args)
-        call(DROP_JS, files.to_json, strings.to_json)
+        paths, strings = partition_drop_args(args)
+        input = paths.empty? ? nil : attach_drop_input(paths)
+        call(DROP_JS, input, strings.to_json)
+        nil
+      end
+
+      # Maps Capybara's documented drop_modifiers aliases onto the DragEvent
+      # init keys (`ctrlKey`, `metaKey`, ...). Same table as Cuprite's #315.
+      DRAG_MODIFIER_ALIASES = { control: :ctrl, command: :meta, cmd: :meta }.freeze
+
+      # Capybara's `Element#drag_to` — HTML5 half only. HTML5_DRAG_JS replays
+      # Capybara's own Selenium HTML5_DRAG_DROP_SCRIPT (the same source
+      # Cuprite's drag.js ports): dragstart on the draggable ancestor, then
+      # dragenter -> 2x dragover -> dragleave/drop -> dragend, setTimeout-paced,
+      # sharing one DataTransfer so `setData` in the page's dragstart handler is
+      # readable at drop. Runs through `evaluate_async` (the script signals
+      # completion via the appended callback), so the drag has fully played out
+      # before this method returns.
+      #
+      # The legacy path is coordinate-based mouse dragging, which Lightpanda
+      # cannot express (no layout to produce coordinates from) — it raises
+      # instead of silently no-oping. `html5: nil` auto-detects like Selenium
+      # does, via LEGACY_DRAG_CHECK_JS: we dispatch a synthetic mousedown where
+      # Selenium presses a real button, then apply the same
+      # prevented-or-no-draggable-ancestor test.
+      #
+      # `steps:`/`scroll:` (Cuprite's legacy-path knobs) are accepted and
+      # ignored so suites migrating from cuprite don't ArgumentError.
+      def drag_to(other, html5: nil, delay: 0.05, drop_modifiers: [], **)
+        keys = Array(drop_modifiers).map { |m| DRAG_MODIFIER_ALIASES.fetch(m.to_sym, m.to_sym).to_s }
+        html5 = !call(LEGACY_DRAG_CHECK_JS) if html5.nil?
+        unless html5
+          raise NotImplementedError,
+                "drag_to needs coordinate mouse dispatch for non-HTML5 (legacy) drags, which Lightpanda " \
+                "cannot do (no layout). Pass `html5: true` to force HTML5 DragEvent simulation."
+        end
+
+        driver.browser.evaluate_async(HTML5_DRAG_JS, self, other, (delay * 1000).to_i, keys)
         nil
       end
 
@@ -371,37 +453,26 @@ module Capybara
       # here and base64-encoded so binary content survives the JSON hop; Hashes
       # are `{ type => data }` string drops. Returns `[files, strings]`.
       def partition_drop_args(args)
-        files = []
+        paths = []
         strings = []
         args.each do |arg|
           if arg.is_a?(Hash)
             arg.each { |type, data| strings << { type: type.to_s, data: data.to_s } }
           else
-            path = arg.to_s
-            files << {
-              name: File.basename(path),
-              type: drop_mime_for(path),
-              b64: [File.binread(path)].pack("m0"),
-            }
+            paths << File.expand_path(arg.to_s)
           end
         end
-        [files, strings]
+        [paths, strings]
       end
 
-      # The dropzone handler only reads `file.name`, but real upload widgets key
-      # off `file.type`, so map the common upload extensions and fall back to a
-      # generic binary type.
-      DROP_MIME_TYPES = {
-        ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".png" => "image/png",
-        ".gif" => "image/gif", ".webp" => "image/webp", ".svg" => "image/svg+xml",
-        ".pdf" => "application/pdf", ".txt" => "text/plain", ".csv" => "text/csv",
-        ".json" => "application/json", ".html" => "text/html", ".xml" => "application/xml",
-        ".zip" => "application/zip",
-      }.freeze
-      private_constant :DROP_MIME_TYPES
-
-      def drop_mime_for(path)
-        DROP_MIME_TYPES.fetch(File.extname(path).downcase, "application/octet-stream")
+      # Hidden `<input type=file multiple>` in this element's own document (so
+      # drops inside an iframe stay in that frame's DOM), pre-loaded via
+      # DOM.setFileInputFiles. Returned as a Node so it can be bound as a
+      # callFunctionOn argument; DROP_JS removes it once the files are moved.
+      def attach_drop_input(paths)
+        oid = call(CREATE_DROP_INPUT_JS, return_by_value: false)["objectId"]
+        driver.browser.set_file_input_files(oid, paths)
+        self.class.new(driver, oid)
       end
 
       # Whitespace-normalized text (Cuprite pattern). Capybara's text matchers compare
@@ -455,6 +526,18 @@ module Capybara
         JS
       end
 
+      # `mouseenter` carries `bubbles: false` per spec — it is dispatched on the
+      # target only, not walked up the ancestor chain the way a real pointer
+      # would. That covers the handler-on-the-hovered-element case (every
+      # Stimulus `mouseenter->` action) and stops short of emulating pointer
+      # geometry we don't have.
+      HOVER_JS = <<~JS
+        function() {
+          this.dispatchEvent(new MouseEvent('mouseover', {bubbles: true, cancelable: true}));
+          this.dispatchEvent(new MouseEvent('mouseenter', {bubbles: false, cancelable: true}));
+        }
+      JS
+
       # We dispatch a `MouseEvent` (not a generic `Event`) because Turbo's link
       # and form interceptors guard with `event instanceof MouseEvent` before
       # they consider intercepting — a synthetic `Event('click')` is silently
@@ -473,25 +556,57 @@ module Capybara
       CLICK_JS = <<~JS
         function() {
           var EventCtor = (typeof MouseEvent !== 'undefined') ? MouseEvent : Event;
+          // Emulate coordinate hit-testing without a layout engine. In a real
+          // browser a pointer click on a container lands on its frontmost
+          // descendant: THAT element is the event target, and the sequence
+          // bubbles UP from there (so the container's own handlers still fire).
+          // Lightpanda has no geometry — every rect is a hardcoded ~5x5, so
+          // document.elementFromPoint(center) just returns the container — so
+          // when `this` is a plain non-interactive wrapper we walk DOWN to the
+          // first visible child, repeatedly, stopping at the first element that
+          // is itself interactive or carries a click handler (onclick /
+          // role=button). That lands on the element a centered pointer would
+          // hit, so widgets that bind their handlers on an inner node fire:
+          // select2 v3 binds its open handler on the inner .select2-choice
+          // (single, mousedown) / .select2-choices (multi, click), the FIRST
+          // child of the .select2-container that Capybara helpers click. We
+          // can't use "single visible child" as a guard — select2 keeps an
+          // offscreen .select2-focusser <input> sibling that has no geometry to
+          // distinguish, so it reads as a second visible child. The descent
+          // never starts from an interactive element, so a normal
+          // button/link/input click still lands exactly on `this`.
+          var INTERACTIVE = { A: 1, BUTTON: 1, INPUT: 1, SELECT: 1, TEXTAREA: 1,
+                              OPTION: 1, LABEL: 1, SUMMARY: 1 };
+          var hit = this;
+          while (!INTERACTIVE[hit.tagName] &&
+                 !hit.hasAttribute('onclick') &&
+                 hit.getAttribute('role') !== 'button') {
+            var next = null, ch = hit.children;
+            for (var i = 0; i < ch.length; i++) {
+              if (!window._lightpanda || _lightpanda.isVisible(ch[i])) { next = ch[i]; break; }
+            }
+            if (!next) break;
+            hit = next;
+          }
           // Real pointer clicks are a mousedown -> mouseup -> click sequence,
           // and widgets like select2 open on `mousedown`, not `click`.
           // Cancelling mousedown suppresses focus/text-selection in a real
           // browser but never the click, so the click below is dispatched
           // unconditionally.
-          this.dispatchEvent(new EventCtor('mousedown', { bubbles: true, cancelable: true }));
-          this.dispatchEvent(new EventCtor('mouseup', { bubbles: true, cancelable: true }));
+          hit.dispatchEvent(new EventCtor('mousedown', { bubbles: true, cancelable: true }));
+          hit.dispatchEvent(new EventCtor('mouseup', { bubbles: true, cancelable: true }));
           var clickEvt = new EventCtor('click', { bubbles: true, cancelable: true });
-          var notCancelled = this.dispatchEvent(clickEvt);
+          var notCancelled = hit.dispatchEvent(clickEvt);
           if (!notCancelled || clickEvt.defaultPrevented) return;
-          var tag = this.tagName;
-          if (tag === 'A' && this.href && this.target !== '_blank') {
+          var tag = hit.tagName;
+          if (tag === 'A' && hit.href && hit.target !== '_blank') {
             // Same-document fragment-only navigation: just update hash (or do
             // nothing if identical). Mirrors Chrome — assigning location.href
             // to a same-document URL on Lightpanda triggers a real navigation
             // tick that cancels pending setTimeout callbacks and clears form
             // values, which breaks any test driving DOM updates from a click
             // handler on `<a href="#...">`.
-            var dest = new URL(this.href, document.baseURI);
+            var dest = new URL(hit.href, document.baseURI);
             var here = new URL(window.location.href);
             if (dest.origin === here.origin && dest.pathname === here.pathname &&
                 dest.search === here.search) {
@@ -499,7 +614,7 @@ module Capybara
                 window.location.hash = dest.hash;
               }
             } else {
-              window.location.href = this.href;
+              window.location.href = hit.href;
             }
           }
         }
@@ -532,17 +647,30 @@ module Capybara
         }
       JS
 
-      # Build a DataTransfer from the JSON payloads and replay the HTML5 drop
-      # sequence on this element. Files arrive base64-encoded and are rebuilt
-      # with `atob` (Blob accepts the binary string directly); string drops are
-      # added as typed items so the page can read them via getData/getAsString.
+      CREATE_DROP_INPUT_JS = <<~JS
+        function() {
+          var doc = this.ownerDocument || document;
+          var input = doc.createElement('input');
+          input.type = 'file';
+          input.multiple = true;
+          input.style.display = 'none';
+          input.setAttribute('data-lightpanda-drop-input', '');
+          (doc.body || doc.documentElement).appendChild(input);
+          return input;
+        }
+      JS
+
+      # Build a DataTransfer from the pre-loaded hidden input (files) and the
+      # JSON string payloads (typed items), then replay the HTML5 drop sequence
+      # on this element. The input is removed once its files are moved.
       DROP_JS = <<~JS
-        function(filesJson, stringsJson) {
+        function(input, stringsJson) {
           var el = this;
           var dt = new DataTransfer();
-          JSON.parse(filesJson).forEach(function(f) {
-            dt.items.add(new File([atob(f.b64)], f.name, { type: f.type }));
-          });
+          if (input) {
+            for (var i = 0; i < input.files.length; i++) dt.items.add(input.files[i]);
+            input.remove();
+          }
           JSON.parse(stringsJson).forEach(function(s) {
             dt.items.add(s.data, s.type);
           });
@@ -552,6 +680,151 @@ module Capybara
         }
       JS
 
+      # Selenium's MOUSEDOWN_TRACKER + LEGACY_DRAG_CHECK folded into one round
+      # trip. Selenium presses a real mouse button before checking; we dispatch
+      # a synthetic mousedown so drag libraries that preventDefault on it
+      # (mouse-based / fallback DnD) still steer the check toward the legacy
+      # path. Returns true when the drag would need the legacy (coordinate)
+      # path: mousedown prevented / never observed, or no draggable ancestor.
+      LEGACY_DRAG_CHECK_JS = <<~JS
+        function() {
+          var doc = this.ownerDocument || document;
+          var prevented = null;
+          doc.addEventListener('mousedown', function(ev) { prevented = ev.defaultPrevented; }, { once: true });
+          this.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true }));
+          if (prevented === true || prevented === null) return true;
+          var el = this;
+          do {
+            if (el.draggable) return false;
+          } while ((el = el.parentElement));
+          return true;
+        }
+      JS
+
+      # Ported near-verbatim from Capybara's Selenium driver
+      # (capybara/selenium/extensions/html5_drag.rb, HTML5_DRAG_DROP_SCRIPT) —
+      # the same source Cuprite's #315 drag.js ports — kept close to ease
+      # future syncs. Upstream quirks preserved deliberately: `rectPt.top` in
+      # pointOnRect (DOMPoint has no .top, that branch just falls through), the
+      # undeclared `key` loop variable, and `callback.call(true)`. The
+      # `source.draggable` reads are native — the HTMLElement.draggable IDL
+      # shipped upstream in #3257 (build 8793, guaranteed by the floor; the
+      # `_lightpanda.isDraggable` polyfill was retired with that bump).
+      # Coordinates come from getBoundingClientRect, which Lightpanda
+      # synthesizes without layout — dropzones reading clientX/Y get
+      # plausible-but-synthetic (integer since #3259) numbers.
+      HTML5_DRAG_JS = <<~JS
+        function rectCenter(rect){
+          return new DOMPoint(
+            (rect.left + rect.right)/2,
+            (rect.top + rect.bottom)/2
+          );
+        }
+
+        function pointOnRect(pt, rect) {
+          var rectPt = rectCenter(rect);
+          var slope = (rectPt.y - pt.y) / (rectPt.x - pt.x);
+
+          if (pt.x <= rectPt.x) { // left side
+            var minXy = slope * (rect.left - pt.x) + pt.y;
+            if (rect.top <= minXy && minXy <= rect.bottom)
+              return new DOMPoint(rect.left, minXy);
+          }
+
+          if (pt.x >= rectPt.x) { // right side
+            var maxXy = slope * (rect.right - pt.x) + pt.y;
+            if (rect.top <= maxXy && maxXy <= rect.bottom)
+              return new DOMPoint(rect.right, maxXy);
+          }
+
+          if (pt.y <= rectPt.y) { // top side
+            var minYx = (rectPt.top - pt.y) / slope + pt.x;
+            if (rect.left <= minYx && minYx <= rect.right)
+              return new DOMPoint(minYx, rect.top);
+          }
+
+          if (pt.y >= rectPt.y) { // bottom side
+            var maxYx = (rect.bottom - pt.y) / slope + pt.x;
+            if (rect.left <= maxYx && maxYx <= rect.right)
+              return new DOMPoint(maxYx, rect.bottom);
+          }
+
+          return new DOMPoint(pt.x,pt.y);
+        }
+
+        function dragEnterTarget() {
+          target.scrollIntoView({behavior: 'instant', block: 'center', inline: 'center'});
+          var targetRect = target.getBoundingClientRect();
+          var sourceCenter = rectCenter(source.getBoundingClientRect());
+
+          for (var i = 0; i < drop_modifier_keys.length; i++) {
+            key = drop_modifier_keys[i];
+            if (key == "control"){
+              key = "ctrl"
+            }
+            opts[key + 'Key'] = true;
+          }
+
+          var dragEnterEvent = new DragEvent('dragenter', opts);
+          target.dispatchEvent(dragEnterEvent);
+
+          // fire 2 dragover events to simulate dragging with a direction
+          var entryPoint = pointOnRect(sourceCenter, targetRect)
+          var dragOverOpts = Object.assign({clientX: entryPoint.x, clientY: entryPoint.y}, opts);
+          var dragOverEvent = new DragEvent('dragover', dragOverOpts);
+          target.dispatchEvent(dragOverEvent);
+          window.setTimeout(dragOnTarget, step_delay);
+        }
+
+        function dragOnTarget() {
+          var targetCenter = rectCenter(target.getBoundingClientRect());
+          var dragOverOpts = Object.assign({clientX: targetCenter.x, clientY: targetCenter.y}, opts);
+          var dragOverEvent = new DragEvent('dragover', dragOverOpts);
+          target.dispatchEvent(dragOverEvent);
+          window.setTimeout(dragLeave, step_delay, dragOverEvent.defaultPrevented, dragOverOpts);
+        }
+
+        function dragLeave(drop, dragOverOpts) {
+          var dragLeaveOptions = Object.assign({}, opts, dragOverOpts);
+          var dragLeaveEvent = new DragEvent('dragleave', dragLeaveOptions);
+          target.dispatchEvent(dragLeaveEvent);
+          if (drop) {
+            var dropEvent = new DragEvent('drop', dragLeaveOptions);
+            target.dispatchEvent(dropEvent);
+          }
+          var dragEndEvent = new DragEvent('dragend', dragLeaveOptions);
+          source.dispatchEvent(dragEndEvent);
+          callback.call(true);
+        }
+
+        var source = arguments[0],
+            target = arguments[1],
+            step_delay = arguments[2],
+            drop_modifier_keys = arguments[3],
+            callback = arguments[4];
+
+        var dt = new DataTransfer();
+        var opts = { cancelable: true, bubbles: true, dataTransfer: dt };
+
+        while (source && !source.draggable) {
+          source = source.parentElement;
+        }
+
+        if (source.tagName == 'A'){
+          dt.setData('text/uri-list', source.href);
+          dt.setData('text', source.href);
+        }
+        if (source.tagName == 'IMG'){
+          dt.setData('text/uri-list', source.src);
+          dt.setData('text', source.src);
+        }
+
+        var dragEvent = new DragEvent('dragstart', opts);
+        source.dispatchEvent(dragEvent);
+
+        window.setTimeout(dragEnterTarget, step_delay);
+      JS
+
       VISIBLE_JS = "function() { return _lightpanda.isVisible(this); }"
 
       VISIBLE_TEXT_JS = "function() { return _lightpanda.visibleText(this); }"
@@ -699,34 +972,53 @@ module Capybara
 
       OBSCURED_JS = "function() { return _lightpanda.isObscured(this); }"
 
+      # Capybara's contract for Element#path is an XPath that re-finds the very
+      # same node (`node #path returns xpath which points to itself`), so this
+      # emits `/HTML/BODY/DIV[2]/P[1]` rather than the CSS-ish
+      # `html > body > div:nth-of-type(2) > p` it used to. Chrome exposes no
+      # native equivalent either; Cuprite hand-rolls the same walk.
+      #
+      # Every step is indexed, including single children: `P[1]` and `P` select
+      # the same node, but the explicit index keeps the output stable if a
+      # sibling appears later, and it is what Chrome DevTools' "Copy XPath"
+      # produces. Positions count same-tag preceding siblings, which is exactly
+      # XPath's own positional semantics.
+      #
+      # No `id`-based shortcut: an `//*[@id="x"]` prefix is shorter but stops
+      # pointing at *this* node the moment the document has a duplicate id,
+      # which malformed real-world pages routinely do.
+      #
+      # An element inside a shadow root has no document-level XPath at all
+      # (XPath doesn't cross shadow boundaries, and a `/SPAN[1]` computed from
+      # the shadow tree would re-find some unrelated light-DOM node). Selenium's
+      # driver returns the sentinel string below in that case and Capybara's
+      # shared `node #path` spec pins it, so mirror it rather than emit a path
+      # that lies.
       GET_PATH_JS = <<~JS
         function() {
           var el = this;
-          var path = [];
+          if (el.getRootNode && typeof ShadowRoot !== 'undefined' && el.getRootNode() instanceof ShadowRoot) {
+            return '(: Shadow DOM element - no XPath :)';
+          }
+          var steps = [];
           while (el && el.nodeType === Node.ELEMENT_NODE) {
-            var selector = el.nodeName.toLowerCase();
-            if (el.id) {
-              selector += '#' + el.id;
-              path.unshift(selector);
-              break;
-            } else {
-              var sibling = el;
-              var nth = 1;
-              while (sibling = sibling.previousElementSibling) {
-                if (sibling.nodeName.toLowerCase() === el.nodeName.toLowerCase()) nth++;
-              }
-              if (nth > 1) selector += ':nth-of-type(' + nth + ')';
+            var name = el.nodeName.toUpperCase();
+            var index = 1;
+            var sibling = el;
+            while (sibling = sibling.previousElementSibling) {
+              if (sibling.nodeName.toUpperCase() === name) index++;
             }
-            path.unshift(selector);
-            el = el.parentNode;
+            steps.unshift(name + '[' + index + ']');
+            el = el.parentElement;
           }
-          return path.join(' > ');
+          return '/' + steps.join('/');
         }
       JS
 
       # Internal wire format, not API — aligned with browser.rb's convention
       # of private_constant for its JS snippets.
-      private_constant :CLICK_JS, :TRIGGER_JS, :DROP_JS, :SHADOW_ROOT_JS, :VISIBLE_JS, :VISIBLE_TEXT_JS,
+      private_constant :CLICK_JS, :TRIGGER_JS, :DROP_JS, :CREATE_DROP_INPUT_JS, :SHADOW_ROOT_JS, :VISIBLE_JS,
+                       :VISIBLE_TEXT_JS,
                        :PROPERTY_OR_ATTRIBUTE_JS, :GET_VALUE_JS, :SET_VALUE_JS,
                        :IMPLICIT_SUBMIT_JS, :SELECT_OPTION_JS, :UNSELECT_OPTION_JS,
                        :SET_CHECKBOX_JS, :EDITABLE_HOST_JS, :DISABLED_JS, :GET_STYLE_JS,

data/lib/capybara/lightpanda/options.rb

@@ -20,14 +20,43 @@ module Capybara
       # `Capybara::Lightpanda.configure { |c| c.port = 9222 }` when external
       # tooling needs a known address.
       DEFAULT_PORT = 0
-      DEFAULT_WINDOW_SIZE = [1024, 768].freeze
+      # Mirrors Lightpanda's own `Viewport.default` (1920x1080) rather than
+      # Cuprite's 1024x768. window_size is applied for real now (see below), so
+      # a 1024x768 default would silently shrink the viewport of every existing
+      # suite and flip `@media` branches under them. Matching the browser's
+      # native default keeps `window_size` truthful AND leaves default
+      # behavior byte-identical to before it was wired up.
+      DEFAULT_WINDOW_SIZE = [1920, 1080].freeze
 
-      # window_size and headless are accepted for Cuprite drop-in
-      # compatibility (standard options at driver registration) but are
-      # inert: Lightpanda has no rendering engine, so there is nothing to
-      # resize, and headless is the only mode it runs in.
+      # window_size drives Emulation.setDeviceMetricsOverride via
+      # Browser#set_viewport on every create_page. This is a JS-visible
+      # viewport only — it sets window.innerWidth/innerHeight and the viewport
+      # that `matchMedia` / `@media` evaluate against, so responsive branches
+      # resolve at the size you ask for. It is NOT real layout: Lightpanda has
+      # no rendering engine, so getBoundingClientRect stays synthetic and
+      # nothing reflows. Sizing down will not make an off-viewport element
+      # report as obscured.
+      # headless is accepted for Cuprite drop-in compatibility but inert —
+      # headless is the only mode Lightpanda runs in.
+      # save_path: directory for downloaded files (Cuprite parity). nil falls
+      # back to Capybara.save_path at create_page time; downloads stay off when
+      # both are nil (Browser#create_page only opts in when a path exists).
+      # raise_on_unhandled_modal: a JS dialog that opens with no
+      # accept_modal/dismiss_modal pre-arm in flight is resolved by Lightpanda's
+      # silent default (confirm → cancel, prompt → null, alert → dismissed), so
+      # a runaway confirm cancels the action and the spec can still pass. false
+      # (default, Cuprite parity) warns on stderr; true raises
+      # UnhandledModalError from the action that opened it.
+      # load_images: passes `--load-resources image` so `<img>` elements are
+      # fetched over the network (upstream #3230, build >= 8834). Off by
+      # default, matching Lightpanda's default of skipping image fetches
+      # entirely. When on, image requests ride the Network domain like any
+      # other — they show in `network.traffic` and count toward
+      # `wait_for_network_idle`. On builds < 8834 the flag is a fatal
+      # UnknownOption at boot, so only enable against binaries that have it.
       attr_accessor :host, :port, :timeout, :handshake_timeout, :process_timeout,
-                    :window_size, :browser_path, :headless, :logger
+                    :window_size, :browser_path, :headless, :logger, :save_path,
+                    :raise_on_unhandled_modal, :load_images
       attr_writer :ws_url
 
       def initialize(options = {})
@@ -36,9 +65,12 @@ module Capybara
         @timeout = options.fetch(:timeout, DEFAULT_TIMEOUT)
         @handshake_timeout = options.fetch(:handshake_timeout, DEFAULT_HANDSHAKE_TIMEOUT)
         @process_timeout = options.fetch(:process_timeout, DEFAULT_PROCESS_TIMEOUT)
-        @window_size = options.fetch(:window_size, DEFAULT_WINDOW_SIZE)
+        @window_size = validate_window_size(options.fetch(:window_size, DEFAULT_WINDOW_SIZE))
         @browser_path = options[:browser_path]
         @headless = options.fetch(:headless, true)
+        @save_path = options[:save_path]
+        @raise_on_unhandled_modal = options.fetch(:raise_on_unhandled_modal, false)
+        @load_images = options.fetch(:load_images, false)
         @ws_url = options[:ws_url]
         @logger = parse_logger(options[:logger])
       end
@@ -62,6 +94,9 @@ module Capybara
           browser_path: browser_path,
           headless: headless,
           logger: logger,
+          save_path: save_path,
+          raise_on_unhandled_modal: raise_on_unhandled_modal,
+          load_images: load_images,
         }
         h[:ws_url] = @ws_url if @ws_url
         h
@@ -69,6 +104,17 @@ module Capybara
 
       private
 
+      # Validated here rather than at apply time so a bad value fails before
+      # Browser#initialize spawns a Lightpanda process — raising later would
+      # orphan it. Upstream reads a 0 dimension as "keep the current one", so
+      # forwarding junk would half-apply a viewport instead of failing.
+      def validate_window_size(size)
+        width, height = size
+        return size if width.is_a?(Integer) && height.is_a?(Integer) && width.positive? && height.positive?
+
+        raise ArgumentError, "window_size must be [width, height] of positive Integers, got #{size.inspect}"
+      end
+
       def parse_logger(logger)
         return logger if logger.is_a?(Capybara::Lightpanda::Logger)
         return Capybara::Lightpanda::Logger.new(logger) if logger