capybara-lightpanda 0.9.0 → 0.10.0

data/lib/capybara/lightpanda/javascripts/predicates.js

@@ -92,61 +92,25 @@ function isContentEditable(el) {
   return false;
 }
 
-// visibleText's block-detection tables. A node is block-level if its computed
-// `display` is in BLOCK_DISP or its tag is in BLOCK_TAG (the tag table catches
-// elements whose display we can't resolve and elements that are block by UA
-// default). Hoisted to IIFE scope so they're built once at injection, not
-// re-allocated on every visibleText() call.
-var BLOCK_DISP = { BLOCK:1, FLEX:1, GRID:1, 'LIST-ITEM':1, TABLE:1, 'TABLE-ROW':1,
-                   'TABLE-CAPTION':1, 'TABLE-CELL':1 };
-var BLOCK_TAG = { ADDRESS:1, ARTICLE:1, ASIDE:1, BLOCKQUOTE:1, DETAILS:1, DIALOG:1,
-                  DIV:1, DL:1, DT:1, DD:1, FIELDSET:1, FIGCAPTION:1, FIGURE:1,
-                  FOOTER:1, FORM:1, H1:1, H2:1, H3:1, H4:1, H5:1, H6:1, HEADER:1,
-                  HGROUP:1, HR:1, LI:1, MAIN:1, NAV:1, OL:1, P:1, PRE:1, SECTION:1,
-                  TABLE:1, TR:1, UL:1 };
-
-// Walk descendants and accumulate text from visible nodes only. Inserts
-// newlines around block-display containers so paragraphs/lists render with
-// natural breaks (Capybara expects this from Chrome's innerText).
-// Lightpanda's innerText returns textContent verbatim (no rendering, so no
-// hidden-descendant filtering), so we DIY the visibility filtering here.
+// Capybara's "visible text" = WebDriver getText semantics, which native
+// innerText alone doesn't provide at two edges: a non-rendered element must
+// yield "" (innerText returns textContent per the HTML getter's step 1), and a
+// ShadowRoot/DocumentFragment has no innerText at all. So we gate on visibility
+// and otherwise delegate the rendered-text collection — block line breaks +
+// display:none descendant skipping + whitespace — to native innerText
+// (Lightpanda #2785/#2795, guaranteed by the build floor). node.rb#visible_text
+// normalizes the whitespace on top.
 function visibleText(el) {
-  // Collapse runs of ASCII whitespace (preserving NBSP) to a single space —
-  // matches Chrome's innerText whitespace handling for text nodes.
-  function normText(s) {
-    return s.replace(/[\t\n\r\f\v ]+/g, ' ');
-  }
-
-  function walk(node) {
-    if (node.nodeType === 3) return normText(node.nodeValue);
-    // DocumentFragment / ShadowRoot — no element of its own to test
-    // for visibility, just walk children.
-    if (node.nodeType === 11) {
-      var fout = '';
-      for (var k = 0; k < node.childNodes.length; k++) fout += walk(node.childNodes[k]);
-      return fout;
-    }
-    if (node.nodeType !== 1) return '';
-    if (!isVisible(node)) return '';
-    var tag = (node.tagName || '').toUpperCase();
-    if (tag === 'TEXTAREA') return node.value || '';
-    if (tag === 'BR') return '\n';
-    var win = node.ownerDocument.defaultView || window;
-    var style = win.getComputedStyle(node);
-    var disp = (style.display || '').toUpperCase();
-    var isBlock = BLOCK_DISP[disp] || BLOCK_TAG[tag];
-    var out = '';
-    for (var i = 0; i < node.childNodes.length; i++) {
-      out += walk(node.childNodes[i]);
-    }
-    // Block-level elements get wrapped in \n…\n only when they actually
-    // contribute visible text. An empty <div> between two inline siblings
-    // would otherwise introduce a phantom line break that Chrome's
-    // innerText algorithm collapses out (required line breaks around
-    // empty blocks coalesce in the line-collapse pass).
-    if (isBlock && /\S/.test(out)) out = '\n' + out + '\n';
-    return out;
+  if (el.nodeType === 1) return isVisible(el) ? el.innerText : '';
+  // ShadowRoot / DocumentFragment: no innerText of its own. Concatenate the
+  // native innerText of each visible element child with the text nodes between
+  // them — collapsing the latter's whitespace to a single space so template
+  // newlines between inline children render as a separating space, not a break.
+  var out = '';
+  for (var i = 0; i < el.childNodes.length; i++) {
+    var c = el.childNodes[i];
+    if (c.nodeType === 3) out += c.nodeValue.replace(/[\t\n\r\f\v ]+/g, ' ');
+    else if (c.nodeType === 1 && isVisible(c)) out += c.innerText;
   }
-
-  return walk(el);
+  return out;
 }

data/lib/capybara/lightpanda/network.rb

@@ -150,10 +150,11 @@ module Capybara
       # The handlers also capture the last top-level navigation response
       # (mirrors capybara-playwright-driver's navigation_request? hook). CDP
       # normally marks the main-document response via
-      # `Network.responseReceived.type`, but Lightpanda omits that field on
-      # responses (only emits `type` on requestWillBeSent) — so match the
-      # long way: remember the document requestId, store the response whose
-      # requestId equals it.
+      # `Network.responseReceived.type`. Lightpanda only started emitting that
+      # field on responses in build 8318 (#3037) — far above the gem's floor —
+      # so match the long way instead: remember the document requestId, store
+      # the response whose requestId equals it. Works on every supported build;
+      # don't "simplify" it to read response.type until the floor clears 8318.
       def subscribe
         @request_handler = build_request_handler
         @response_handler = build_response_handler
@@ -161,6 +162,16 @@ module Capybara
         browser.on("Network.responseReceived", &@response_handler)
       end
 
+      # Redirects follow Chrome's shape (Lightpanda since #3175, build ≥8602):
+      # every followed hop re-emits requestWillBeSent with the SAME requestId
+      # and the 3xx riding along as `redirectResponse`; the 3xx never gets a
+      # responseReceived of its own. So the hop's event is what closes the
+      # previous entry — without it that entry stays `response: nil` forever,
+      # pending_connections wedges at ≥1 and every wait_for_idle burns its
+      # full timeout after the first redirect (Ferrum's
+      # subscribe_request_will_be_sent does the same close). Deliberately NOT
+      # fed into @last_navigation_response: status_code must report the final
+      # hop, and the redirected requestWillBeSent resets it below anyway.
       def build_request_handler
         lambda do |params|
           if params["type"] == "Document"
@@ -175,6 +186,9 @@ module Capybara
             response: nil,
           }
           @traffic_mutex.synchronize do
+            if (redirect = params["redirectResponse"]) && (previous = last_open_entry(params["requestId"]))
+              previous[:response] = response_summary(redirect)
+            end
             @traffic << entry
             @traffic.shift(@traffic.size - TRAFFIC_LIMIT) if @traffic.size > TRAFFIC_LIMIT
           end
@@ -190,18 +204,30 @@ module Capybara
             }
           end
           @traffic_mutex.synchronize do
-            request = @traffic.find { |t| t[:request_id] == params["requestId"] }
+            # Last open entry, not `find`: after a redirect chain several
+            # entries share the requestId and only the newest is still open.
+            request = last_open_entry(params["requestId"])
             next unless request
 
-            request[:response] = {
-              status: params.dig("response", "status"),
-              headers: params.dig("response", "headers"),
-              mime_type: params.dig("response", "mimeType"),
-            }
+            request[:response] = response_summary(params["response"])
           end
         end
       end
 
+      # Caller holds @traffic_mutex.
+      def last_open_entry(request_id)
+        @traffic.reverse_each.find { |t| t[:request_id] == request_id && t[:response].nil? }
+      end
+
+      def response_summary(response)
+        response ||= {}
+        {
+          status: response["status"],
+          headers: response["headers"],
+          mime_type: response["mimeType"],
+        }
+      end
+
       def unsubscribe
         browser.off("Network.requestWillBeSent", @request_handler) if @request_handler
         browser.off("Network.responseReceived", @response_handler) if @response_handler

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,29 @@ 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
 
@@ -371,37 +418,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 +491,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 +521,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 +579,7 @@ module Capybara
                 window.location.hash = dest.hash;
               }
             } else {
-              window.location.href = this.href;
+              window.location.href = hit.href;
             }
           }
         }
@@ -532,17 +612,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);
           });
@@ -699,34 +792,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,36 @@ 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.
       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
       attr_writer :ws_url
 
       def initialize(options = {})
@@ -36,9 +58,11 @@ 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)
         @ws_url = options[:ws_url]
         @logger = parse_logger(options[:logger])
       end
@@ -62,6 +86,8 @@ module Capybara
           browser_path: browser_path,
           headless: headless,
           logger: logger,
+          save_path: save_path,
+          raise_on_unhandled_modal: raise_on_unhandled_modal,
         }
         h[:ws_url] = @ws_url if @ws_url
         h
@@ -69,6 +95,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