capybara-lightpanda 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11c82a5cc9cde03ae1a231efb72764a35c77beda531118960fb499c209348a3e
-  data.tar.gz: 66f4b3190f2dcc158925fd26e7b7b0590a8460d9789737d8bb08c3d5f9deed6b
+  metadata.gz: 2515195575d1146f7cd14f479801360770c65d39d84c2bdc58be987e503bda88
+  data.tar.gz: ab94aba998ccafb870e109504e7f33dd22a35bcd2ba79750cfd2bb79226feaf1
 SHA512:
-  metadata.gz: 1dc37a8e9df8fb0533718e9aa17f35cb7dc162251a0f5f46e036b054afcbeec2da928277ac3af60ac592493d80357913f1f8d2384d671baa2e802905b6357c09
-  data.tar.gz: 95c360b046406da232e6104fe9cb10aa158fedc2ff4e3cdeaa7c12042bc3bd725d9825bd8e2c730365e46c0f9f884c02c4a523af1ce9e4d582fc5aa760093e99
+  metadata.gz: 3eadd479f7c543354a89c3f69a1be6ee94be6067b52171766c3da1b3c9b091a9e404c987e9af11c5230c89e8df319013822748b0bd6ba0e7e56ebd143f3e7689
+  data.tar.gz: fec1bbad25a59b177b6ac117e82bf65eef995196f233aa96742f71b2def90133132b913c0591bf40f2ca554d09cb4e6b26cbb132a0f3ae5e7ab811efa4504914

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.12.0] - 2026-08-28
+
+> **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8875, and the rolling `nightly` tag now carries it (8982 as of 2026-08-28), so updating the browser is all it takes. **No tagged Lightpanda release is new enough yet**: 0.3.7 is below the floor, so version pinning stays unavailable until Lightpanda ships its next release.
+
+### Added
+
+- **The keyboard activates things.** Pressing Enter on a button, link or submit input — and Space on a button, checkbox or radio — now does what it does in a real browser: the control activates, forms submit, checkboxes toggle. Previously `send_keys(:enter)` and `send_keys(:space)` were silently ignored on those controls, so keyboard-accessibility specs passed by doing nothing. Printable keys also emit `keypress` now, and a handler that cancels `keypress` correctly suppresses Enter's implicit form submission.
+- **A closed `<dialog>` is properly hidden.** Text and controls inside a `<dialog>` that has never been opened no longer match Capybara's default visibility filter. Suites using the `<dialog>`-as-confirmation idiom (Turbo, Spree 5's admin) could previously "find" and click a confirm button that was not on screen — passing where Chrome would have raised `ElementNotFound`.
+- **Uppercase inline styles hide elements.** `style="display: NONE"` and `style="visibility: HIDDEN"` are now treated as hidden, matching the CSS spec's case-insensitive keywords. Legacy templates and CMS output that upcase keywords no longer read as visible.
+- **`ws_url:` accepts `localhost`.** Connecting to an externally-managed Lightpanda over `ws://localhost:PORT/` works; previously only an IP literal such as `ws://127.0.0.1:PORT/` was accepted by the browser's handshake.
+
+### Fixed
+
+- **Keyboard-triggered navigation is waited for.** Now that Enter activates a submit button, pressing it starts a real navigation — but `send_keys` returned without waiting for it, so the very next `current_url` (or any non-waiting assertion) could still report the previous page. Keystrokes now settle the page the same way a click does. As with a click, a navigation whose server round-trip is slow still needs one of Capybara's waiting matchers, such as `have_current_path`.
+
+- **Iframes keep working when the browser stops loading them by default.** Lightpanda build 8946 turns off `<iframe>` and Web Worker loading unless asked: the parser still puts the iframe in the DOM, but no frame is ever created, so `within_frame` and `switch_to_frame` find nothing and report no cause. The driver now asks for both on every session, which holds today's behavior across the change and needs no newer browser — the request is understood by every build the gem supports. Nothing to configure. If you run the rolling nightly, take this before your browser passes 8946.
+
+- **A browser you manage yourself is version-checked like one the gem spawns.** `ws_url:` was the only way into the driver that skipped the version floor: a Lightpanda too old for the gem connected happily, then failed further along as a CDP error naming neither the version nor the option that let it through. The driver now reads the version over CDP at connect and refuses anything below the floor, with the same message the spawn path produces. An endpoint that cannot report a version at all — a Lightpanda older than the command, or a Chrome pointed at by mistake — is refused for the same reason. `page.driver.browser.version`, `.nightly_build` and `.release` report the browser on this path now instead of returning `nil`.
+
+## [0.11.0] - 2026-08-25
+
+> **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8796 (2026-08-25 or newer). **No tagged Lightpanda release is new enough yet**: 0.3.7 is below the floor and is now refused, so version pinning is unavailable until Lightpanda ships its next release — CI runs on the rolling nightly in the meantime.
+
+### Added
+
+- **Drag and drop between elements.** `element.drag_to(target)` performs an HTML5 drag — `dragstart` through `drop` with a shared `DataTransfer`, so dropzone pages and `setData`/`getData` handlers behave as in Chrome, and drag events carry whole-number coordinates like Chrome's. Libraries that only respond to real mouse movement (SortableJS's fallback mode) remain out of reach — there is still no layout engine to drive a pointer through.
+- **`load_images` driver option.** `load_images: true` makes the browser fetch `<img>` sources over the network, so image requests appear in `network.traffic` and are counted by `wait_for_network_idle` — useful for suites that assert on image traffic. Off by default (images are skipped entirely, as before). Needs a nightly from 2026-08-26 onward.
+- **Screenshots show the page.** `save_screenshot` — and the automatic failure screenshots capybara-screenshot takes — now produce a real rendering of the page's content instead of a fixed placeholder image. It is a text-layout rendering, useful for seeing what the DOM held at failure time; pixel-accurate visual regression still needs a full browser.
+
+### Removed
+
+- The internal workaround for reading an element's `draggable` state is gone now that the browser answers natively — no change required on your end.
+
 ## [0.10.0] - 2026-08-19
 
 > **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8448 **or a tagged release ≥ 0.3.7**. The driver refuses to start below either floor and tells you which version it found. If you pin the browser (see below), pin `0.3.7` or newer.

data/README.md

@@ -57,7 +57,7 @@ driven_by :lightpanda
 > Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), and `@media` / `window.matchMedia()` evaluate against the `window_size` you configure — so a mobile-only CTA gated by `@media (max-width: …)` resolves at the width you ask for. What's missing is *layout*: nothing reflows, `getBoundingClientRect` stays synthetic, and there is no real scroll. Specs that assert on pixel geometry, scrolling, or screenshots — plus the two that catch people out, a second browser tab and a menu revealed purely by CSS `:hover` — should stay on Cuprite (or whichever full-browser driver you were already using). The [per-spec dual-driver setup](https://navidemad.github.io/capybara-lightpanda/docs/#dual-per-spec) routes that minority to Cuprite and the structural majority to Lightpanda for speed.
 
 > [!TIP]
-> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "0.3.7"`. Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "0.3.8"`. (0.3.8 is the first release that will clear the gem's current floor, nightly build 8875 — until upstream tags it, the driver needs the rolling `nightly` tag.) Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
 
 ## Credits
 

data/lib/capybara/lightpanda/browser.rb

@@ -73,28 +73,34 @@ module Capybara
         end
       end
 
-      # Lightpanda binary version (e.g. "lightpanda 0.2.9 nightly.5267") and
-      # parsed nightly build number, captured at Process startup. nil when
-      # the gem is connecting to an externally-managed Lightpanda via ws_url.
+      # Lightpanda version string (e.g. "1.0.0-nightly.8925+a7bda0ea5") and its
+      # parsed build number. Learned from `lightpanda version` at Process
+      # startup on the spawn path, and from the CDP `LP.version` command when
+      # connecting to an externally-managed browser via ws_url — so these are
+      # populated either way, and a caller inspecting them does not have to
+      # know which path built the session.
       def version
-        @process&.version
+        @process&.version || @remote_version
       end
 
       # Set on the nightly/dev channel only; nil for a tagged release, which
       # carries no build counter. `release` is its mirror image — exactly one of
-      # the two is non-nil once the process has started.
+      # the two is non-nil once the session is up.
       def nightly_build
-        @process&.nightly_build
+        @process&.nightly_build || @remote_nightly_build
       end
 
       def release
-        @process&.release
+        @process&.release || @remote_release
       end
 
       def initialize(options = {})
         @options = Options.new(options)
         @process = nil
         @client = nil
+        @remote_version = nil
+        @remote_nightly_build = nil
+        @remote_release = nil
         @target_id = nil
         @session_id = nil
         @browser_context_id = nil
@@ -121,6 +127,7 @@ module Capybara
 
         if @options.ws_url?
           @client = Client.new(@options.ws_url, @options)
+          check_remote_version
         else
           @process = Process.new(@options)
           @process.start
@@ -152,6 +159,9 @@ module Capybara
         attach_result = @client.command("Target.attachToTarget", { targetId: @target_id, flatten: true })
         @session_id = attach_result["sessionId"]
 
+        # Must precede the first navigation: sub-resource loading is a
+        # per-BrowserContext setting read while the document loads.
+        configure_loading
         @turbo_event.set
         subscribe_to_console_logs
         subscribe_to_console_capture
@@ -498,6 +508,34 @@ module Capybara
 
       private
 
+      # Keep iframes and workers loading.
+      #
+      # Upstream #3305 (build 8946) turned `Config.LoadResources` into a
+      # four-field struct defaulting every sub-resource to false, so
+      # `Frame.iframeAddedCallback` now returns early unless `iframe` is set:
+      # the parser still registers the `<iframe>` in the DOM, but no child
+      # frame is ever created. That silently breaks `switch_to_frame` and
+      # Capybara's `within_frame` — core driver API, not an optional extra —
+      # and there is no CLI opt-in the gem can use below 8946, because the
+      # `--load-resources` *value* `iframe` only parses from that build.
+      #
+      # The `subFrame`/`worker` params predate #3305 and simply write a
+      # different field after it, which makes this the one form that spans the
+      # whole supported range: a no-op below 8946 where both already defaulted
+      # on, load-bearing above it, and no MINIMUM_NIGHTLY_BUILD bump either way.
+      #
+      # Workers are included to hold the gem's behavior still across the flip
+      # rather than to satisfy a feature we ship: a worker that silently never
+      # runs is the same debugging trap as an iframe that silently never loads.
+      #
+      # Not rescued on purpose. LP.configureLoading predates the floor by a
+      # wide margin, so a failure here means the endpoint is not a Lightpanda
+      # we understand, and swallowing it would restore the exact silence this
+      # call exists to prevent.
+      def configure_loading
+        page_command("LP.configureLoading", subFrame: true, worker: true)
+      end
+
       def register_auto_scripts
         page_command("Page.addScriptToEvaluateOnNewDocument", source: AutoScripts::JS)
       end
@@ -590,6 +628,44 @@ module Capybara
         end
       end
 
+      # Binary.update_hint would be a lie here: it prints a curl into a path the
+      # gem controls, and under ws_url the browser is somebody else's process on
+      # possibly another host.
+      REMOTE_UPDATE_HINT = "the gem does not manage that browser — " \
+                           "update the Lightpanda serving ws_url yourself."
+      private_constant :REMOTE_UPDATE_HINT
+
+      # The spawn path runs `lightpanda version` before the browser is even up
+      # (Process#check_minimum_version). An externally-managed browser has no
+      # binary to shell out to, so the same floor is enforced over CDP instead:
+      # `LP.version` returns the identical string the CLI prints, and
+      # Process.check_version! is the one parser both channels share.
+      #
+      # Without this, `ws_url:` was the one way into the driver that skipped the
+      # floor entirely — an old browser connected happily and then failed later
+      # as an unrelated-looking CDP error, with nothing naming the real cause.
+      #
+      # A browser that cannot answer `LP.version` is refused rather than assumed
+      # new enough, matching the spawn path's rule that an unidentifiable binary
+      # never passes. Two things land here: a Lightpanda predating the LP domain,
+      # and a Chrome someone pointed ws_url at by mistake — the second being easy
+      # to do and previously diagnosable only by watching later commands fail.
+      #
+      # Only #start calls this. #reconnect deliberately does not: it re-dials the
+      # same endpoint, whose version cannot have changed, and the crash-recovery
+      # path should not spend a round-trip re-asking.
+      def check_remote_version
+        result = @client.command("LP.version")
+        @remote_version, @remote_nightly_build, @remote_release =
+          Process.check_version!(result["version"]) { REMOTE_UPDATE_HINT }
+      rescue BrowserError, TimeoutError => e
+        raise BinaryError,
+              "Could not read the Lightpanda version at #{@options.ws_url} " \
+              "(LP.version failed: #{e.message}). ws_url: must point at a " \
+              "Lightpanda CDP endpoint new enough to answer LP.version; the gem " \
+              "cannot verify a browser it does not manage."
+      end
+
       def restart_process_if_dead
         return unless @process && !@process.alive?
 

data/lib/capybara/lightpanda/node.rb

@@ -211,6 +211,41 @@ module Capybara
         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
+
       def select_option
         call(SELECT_OPTION_JS)
       end
@@ -221,9 +256,25 @@ module Capybara
         raise Capybara::UnselectNotAllowed, "Cannot unselect option from single select box."
       end
 
+      # The trailing `wait_for_idle` mirrors #click, and for the same reason.
+      # Since upstream #3264 (build >= 8842) `Input.dispatchKeyEvent` builds a
+      # *trusted* KeyboardEvent, so Enter on a submit input / <a href> and
+      # Space on a button or checkbox synthesize a real activation click —
+      # which means a keystroke can now start a navigation. Before #3264 it
+      # could not, which is why this settle step was historically absent; its
+      # absence then showed up as `current_url` being read against the
+      # outgoing document (test/features/keyboard_activation_test.rb).
+      #
+      # Caveat, shared with #click: `wait_for_idle` only sniffs for ~50 ms
+      # (Browser::SNIFF_WINDOW) and watches Runtime.executionContextsCleared,
+      # which Lightpanda emits when the *response* lands, not when the request
+      # starts. A navigation whose server round-trip exceeds that window is
+      # therefore still not awaited here — use Capybara's waiting matchers
+      # (`have_current_path`) for those, as you would after a click.
       def send_keys(*)
         call("function() { this.focus() }")
         driver.browser.keyboard.type(*)
+        driver.browser.wait_for_idle
       end
 
       def tag_name
@@ -645,6 +696,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); }"

data/lib/capybara/lightpanda/options.rb

@@ -47,9 +47,16 @@ module Capybara
       # 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, :save_path,
-                    :raise_on_unhandled_modal
+                    :raise_on_unhandled_modal, :load_images
       attr_writer :ws_url
 
       def initialize(options = {})
@@ -63,6 +70,7 @@ module Capybara
         @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
@@ -88,6 +96,7 @@ module Capybara
           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

data/lib/capybara/lightpanda/process.rb

@@ -180,7 +180,8 @@ module Capybara
       # set, merged 2026-07-30) — a use-after-free in exactly the path
       # `Node#select_option`/`Node#set` on a <select> drives, i.e. a browser
       # crash surfacing as DeadBrowserError mid-spec.
-      # Build 8448 = the #3087 merge (6d824c88) — now the binding floor.
+      # Build 8448 = the #3087 merge (6d824c88) — the binding floor of the
+      # 2026-07-30 bump.
       # Subsumed by 8448, recorded so they are not re-derived: build 8298 made
       # Network.enable idempotent (the gem never hit it — the Notification is
       # per-BrowserContext and Network#enable's @enabled guard means one enable
@@ -191,7 +192,46 @@ module Capybara
       # `window_size` option. Note the override only reached
       # Page.getLayoutMetrics later (~build 8300); the gem does not depend on
       # that half, so it is NOT part of the floor.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("8448")
+      #
+      # 2026-08-25 bump 8448 -> 8796: #3257 (HTMLElement.draggable IDL, build
+      # 8793) and #3259 (MouseEvent coordinate getters floor to integers
+      # Chrome-style, build 8796; PointerEvent stays fractional). The floor
+      # guarantees native `.draggable`, so the drag scripts in node.rb read it
+      # verbatim — the `_lightpanda.isDraggable` polyfill was retired with
+      # this bump — and drag events carry integer clientX/Y (the shared spec
+      # asserting that runs un-skipped). Build 8796 = the #3259 merge
+      # (341a01570), which is also the 2026-08-25 nightly cut.
+      #
+      # 2026-08-26 bump 8796 -> 8875, four fixes the gem now asserts on:
+      #   #3264 (8842) CDP Input.dispatchKeyEvent builds a *trusted*
+      #     KeyboardEvent, so frame/user_input.zig fires `keypress` on
+      #     printable/Enter keydowns and synthesizes a trusted PointerEvent
+      #     click for Enter on <button>/<a href>/input[submit|button|reset|
+      #     image] and Space-keyup on those plus checkbox/radio. That click is
+      #     a real activation event (PointerEvent.Proto = MouseEvent), so
+      #     Node#send_keys(:enter) submits/navigates and send_keys(:space)
+      #     toggles a checkbox — both were no-ops below 8842. No gem code
+      #     drives it; Keyboard never sends CDP `type: "char"`, so nothing
+      #     double-fires. Pinned by test/features/keyboard_activation_test.rb.
+      #   #3269 (8868) adds `dialog:not([open]) { display: none }` to the
+      #     UA-stylesheet truth checkVisibility() and getComputedStyle().display
+      #     share, so a closed <dialog> AND its subtree read as non-visible.
+      #     Below 8868 Capybara matched text and controls inside a never-opened
+      #     dialog. Pinned by test/features/upstream_bugs_test.rb (Bug #4).
+      #   #3270 (8857) inline-style keyword matching in checkVisibility /
+      #     getComputedStyle is case-insensitive for display / visibility /
+      #     opacity / pointer-events, so `style="display: NONE"` hides.
+      #     Feeds _lightpanda.isVisible. Pinned by visibility_keywords_test.rb.
+      #   #3256 (8875) the CDP WS handshake accepts the exact lowercase
+      #     `Host: localhost:<port>` form (bare `localhost`, `LOCALHOST:<port>`
+      #     and `localhost.evil.com:<port>` still 403). Below 8875 only an IP
+      #     literal passed, so a user-supplied `ws_url:` had to say 127.0.0.1.
+      #     Pinned by test/features/ws_url_host_test.rb.
+      # Build 8875 = the #3256 merge (f2169836e). NOTE: this floor leads the
+      # nightly channel — the 2026-08-26 nightly is 8855 — so it lands with the
+      # next nightly cut. #3267 (8880, Authorization stripped on cross-origin
+      # redirects) arrives with the same floor but drives nothing gem-side.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("8875")
 
       # Second, equivalent floor for the *release* channel.
       #
@@ -200,15 +240,71 @@ module Capybara
       # bare "0.3.6" carrying no commit counter at all, and MINIMUM_NIGHTLY_BUILD
       # has nothing to compare against. Releases are cut from the same trunk, so
       # a release is acceptable exactly when its own commit count clears the
-      # nightly floor: 0.3.7 is build 8671, well past the #3087 merge (8448)
-      # this floor exists for. (0.3.6 is only 8318 — it predates the optgroup
-      # fix and everything after it, which is why this pin had to move.)
+      # nightly floor. As of 2026-08-26 NO published release clears the 8875
+      # floor — 0.3.7 (build 8671) predates every fix the floor exists for — so
+      # this pin names the NEXT release. 0.3.8 is not tagged yet; any future tag
+      # is cut from a trunk already past build 8886, so it clears the floor by
+      # construction. Until upstream tags it, the release channel is
+      # deliberately unusable (nightly-only), reported with the standard
+      # too-old error. When 0.3.8 ships: verify
+      # `git rev-list --count 0.3.8` >= 8875 and update the lockstep table in
+      # process_test.rb.
       #
       # INVARIANT: every MINIMUM_NIGHTLY_BUILD bump must also move this to the
       # first release containing that build (`git rev-list --count <tag>` in the
       # browser repo tells you). Leaving it behind would let the release channel
       # silently accept a binary the nightly channel rejects.
-      MINIMUM_RELEASE = Gem::Version.new("0.3.7")
+      MINIMUM_RELEASE = Gem::Version.new("0.3.8")
+
+      class << self
+        # `lightpanda version` prints one of two shapes, and the gem supports
+        # both so a suite can either track nightly or pin a reproducible
+        # release:
+        #
+        #   "1.0.0-nightly.8285+de85a51d"  rolling nightly (also "dev.NNNN" for
+        #                                  a locally compiled tree — same
+        #                                  `git rev-list --count HEAD` counter,
+        #                                  different label). Checked against
+        #                                  MINIMUM_NIGHTLY_BUILD.
+        #   "0.3.5"                        a tagged release: bare semver, no
+        #                                  build metadata. Checked against
+        #                                  MINIMUM_RELEASE.
+        #
+        # The release form is matched anchored — a bare semver and nothing else
+        # — so a stray "1.2.3" inside some other string can never be mistaken
+        # for a release. Anything that matches neither shape stays a hard
+        # failure: a version we cannot identify is never assumed to be new
+        # enough.
+        #
+        # Lives on the class, not the instance, because there are two ways to
+        # learn a version and only one of them involves a Process: the spawn
+        # path shells out to the binary, while an externally-managed browser
+        # (`ws_url:`) is asked over CDP. `LP.version` returns the identical
+        # string the CLI prints, so both channels share this one parser rather
+        # than drifting apart — the drift being how `ws_url:` shipped with no
+        # floor check at all.
+        #
+        # Returns [version, nightly_build, release]; exactly one of the latter
+        # two is non-nil. The update hint is yielded rather than passed so the
+        # caller's hint-building only runs on the failure path.
+        def check_version!(raw)
+          version = raw.to_s.strip
+
+          if (build = version[/(?:nightly|dev)\.(\d+)/, 1])
+            nightly_build = Gem::Version.new(build)
+            return [version, nightly_build, nil] if nightly_build >= MINIMUM_NIGHTLY_BUILD
+          elsif (tag = version[/\A\d+\.\d+\.\d+\z/])
+            release = Gem::Version.new(tag)
+            return [version, nil, release] if release >= MINIMUM_RELEASE
+          end
+
+          raise BinaryError,
+                "Lightpanda #{version} is too old. " \
+                "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
+                "or release >= #{MINIMUM_RELEASE}. " \
+                "Update: #{yield}"
+        end
+      end
 
       attr_reader :pid, :ws_url, :version, :nightly_build, :release
 
@@ -257,38 +353,12 @@ module Capybara
 
       private
 
-      # `lightpanda version` prints one of two shapes, and the gem supports both
-      # so a suite can either track nightly or pin a reproducible release:
-      #
-      #   "1.0.0-nightly.8285+de85a51d"  rolling nightly (also "dev.NNNN" for a
-      #                                  locally compiled tree — same
-      #                                  `git rev-list --count HEAD` counter,
-      #                                  different label). Checked against
-      #                                  MINIMUM_NIGHTLY_BUILD.
-      #   "0.3.5"                        a tagged release: bare semver, no build
-      #                                  metadata. Checked against MINIMUM_RELEASE.
-      #
-      # The release form is matched anchored — a bare semver and nothing else —
-      # so a stray "1.2.3" inside some other string can never be mistaken for a
-      # release. Anything that matches neither shape stays a hard failure: a
-      # binary we cannot identify is never assumed to be new enough.
+      # Shells the floor check out to the binary. The ws_url path can't — see
+      # Browser#check_remote_version, which feeds the same parser from CDP.
       def check_minimum_version(binary_path)
         stdout, = Open3.capture3(binary_path, "version")
-        @version = stdout.strip
-
-        if (build = @version[/(?:nightly|dev)\.(\d+)/, 1])
-          @nightly_build = Gem::Version.new(build)
-          return if @nightly_build >= MINIMUM_NIGHTLY_BUILD
-        elsif (tag = @version[/\A\d+\.\d+\.\d+\z/])
-          @release = Gem::Version.new(tag)
-          return if @release >= MINIMUM_RELEASE
-        end
-
-        raise BinaryError,
-              "Lightpanda #{@version} is too old. " \
-              "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
-              "or release >= #{MINIMUM_RELEASE}. " \
-              "Update: #{Binary.update_hint(binary_path)}"
+        @version, @nightly_build, @release =
+          self.class.check_version!(stdout) { Binary.update_hint(binary_path) }
       rescue Errno::ENOENT
         # Binary not runnable — let attempt_start handle it
       end
@@ -355,7 +425,7 @@ module Capybara
           "info",
           # External stylesheet fetch (PR #2487, build >= 6353 — enforced by the
           # floor). Always on so linked CSS contributes to checkVisibility /
-          # getComputedStyle; see .claude/rules/lightpanda-io.md limitation #6.
+          # getComputedStyle; see .claude/rules/lightpanda-io.md limitation #5.
           "--enable-external-stylesheets",
           # Raise the inbound CDP WebSocket message cap from Lightpanda's 1 MiB
           # default (Config.zig `cdp_max_message_size`) to 100 MiB, matching
@@ -371,6 +441,12 @@ module Capybara
           "--cdp-max-message-size",
           (100 * 1024 * 1024).to_s,
         ]
+        # Opt-in image fetching (upstream #3230, build >= 8834). Deliberately
+        # NOT always-on like --enable-external-stylesheets: images never feed
+        # the DOM predicates, so the default spends no bandwidth on them. On
+        # builds < 8834 the flag is a fatal UnknownOption at boot — see
+        # Options#load_images.
+        base.push("--load-resources", "image") if @options.load_images
         extra = ENV.fetch("LIGHTPANDA_EXTRA_ARGS", "").split
         base + extra
       end

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.10.0"
+    VERSION = "0.12.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Navid Emad