capybara-lightpanda 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b898fd26a9e25f95263b605f022264cd2a132bbca82081bd931fe542c88673e
-  data.tar.gz: 4776e1326f56cd6f123538b130dfb7de1edb1a745a45574e31520a1a5227ce94
+  metadata.gz: 3c435f7a8f49c34c68012f2c34cb4f9766531acbdd61e9e3f70e4ac9395d54e3
+  data.tar.gz: 11cca4dc77a1b415eff5e0e45796e9f806ee36169c8ad0c672c0947d2281f834
 SHA512:
-  metadata.gz: 025d4fd23a6f0b4379c6e34d878610b657a06dcf33ab5490b606e5e42ed2e452475860283df232f8c397bbf1b48144f0d89be33bf7e5a70fe430a14e26bfb1a7
-  data.tar.gz: 16193011f9ea880c74300a45491ab5dbe36abe55e0a080fe1f65edf36d9722daf6e9842de361f498068952970f3f2d975a64d8b92eb8ecaf2600c01b342caf34
+  metadata.gz: '07464388df9304ea1f4bf3bbde2c6dfd1c654d787690d47d3d3d62f6f89c22860a24185f14c839979e0d6fb1aebfb030aee97c450894d8da418357341994a4dd'
+  data.tar.gz: 03d0b12cf3cb0728639faed14706fffce40f1287f65b714f4126d4a4da8063071ac9423e6a1b040e68dfc6473e451d29658944a8bfa4d5db3c462520c0b260c6

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.13.0] - 2026-10-03
+
+> **Update Lightpanda before upgrading.** This release requires Lightpanda **1.0.0** or a nightly build ≥ 9994. The driver refuses anything older and names the version it found. Tagged releases work again: pin `1.0.0` for a reproducible browser.
+
+### Changed
+
+- **Cross-origin requests follow CORS, as in Chrome.** Lightpanda 1.0.0 enforces CORS by default, and the driver doesn't turn it off, so a `fetch` or XHR your app sends from `127.0.0.1` to `localhost` (or to another port) is blocked there just as Chrome would block it. Suites already green on Cuprite or Selenium are unaffected. A blocked request is listed in `network.traffic` with an `:error` and no response, and it no longer stalls `wait_for_network_idle` (see Fixed).
+- **`Cookies#set` returns whether the browser accepted the cookie.** Lightpanda now refuses `SameSite=None` without `Secure`. `set` returns `false` in that case instead of dropping the cookie silently. `Cookies#load` repairs cookie files saved by older versions, which marked every cookie `SameSite=None`, and warns about any cookie it still can't restore.
+
+### Fixed
+
+- **Clicking a field focuses it again.** On current Lightpanda builds, `click` followed by `send_keys` sent the keys to the page body instead of the clicked field. Clicking a field, a label or a contenteditable region now focuses it, and clicking empty space blurs the focused element, as in Chrome. Capybara's `active_element` specs now pass.
+- **`send_keys` appends to a field's existing value.** On a field that was pre-filled and not yet focused, `send_keys("x")` produced `"xfoo"` instead of `"foox"`. Typing now starts at the end of the value, as in chromedriver. If you need to type at a specific position, focus the field and place the caret yourself first.
+- **Backspace, Delete, Tab, Escape and the arrow keys reach the page.** Previously only keys that type a character were delivered, so these keys did nothing. They now edit fields, move the caret and extend the selection with Shift. A `beforeinput` handler can cancel an edit, which input-mask libraries rely on.
+- **Ctrl/Cmd shortcuts no longer type a character.** `send_keys([:ctrl, "a"])` used to insert a stray `a`. Your shortcut handlers still receive the key.
+- **`select` never picks a disabled option, and picks the right one when values repeat.** When several options shared the same value, the first one was always selected.
+- **Failed requests no longer stall `wait_for_network_idle`.** A request that failed without a response (blocked by CORS, refused connection) stayed pending until the timeout expired.
+- **`console_logs` shows objects.** `console.log({a: 1})`, arrays and DOM elements used to appear as empty text. They now appear as a short description.
+- **A browser crash no longer takes your test process down with it.** If the connection died unexpectedly, the error could be raised somewhere unrelated in your test, or abort a server before its cleanup ran. Commands now fail cleanly with `DeadBrowserError`, waiting commands are released immediately, and each crashed browser releases its connection instead of keeping it open until garbage collection.
+- **`matchMedia` listeners fire when you resize the window.** `resize_window_to` now runs the JavaScript breakpoint handlers. Stylesheet `@media` rules still only apply after the next `visit`.
+
+## [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.

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.8"`. (0.3.8 is the first release that will clear the gem's current floor, nightly build 8796 — 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).
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "1.0.0"` (the tagged release the gem's current floor is pinned to — nightly build 9994 is that release's commit). 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/console.rb

@@ -59,14 +59,27 @@ module Capybara
 
           on("Runtime.consoleAPICalled") do |params|
             params["args"]&.each do |r|
-              value = r["value"]
-              next if driver_sentinel?(value)
+              next if driver_sentinel?(r["value"])
 
-              logger.puts(value)
+              logger.puts(console_arg_text(r))
             end
           end
         end
 
+        # One console argument as text. Since upstream #3504 (build 9414)
+        # Lightpanda sends `value` for primitives only — an object, array or
+        # DOM node arrives as a RemoteObject with a `description` (sometimes
+        # empty), a `className` and a `type`. Reading `value` alone printed
+        # objects as blank lines in the logger and DOM nodes as "" in
+        # console_logs; fall through to the first non-empty descriptor,
+        # the way DevTools labels an object it can't preview.
+        def console_arg_text(arg)
+          return arg["value"].to_s if arg.key?("value")
+
+          [arg["unserializableValue"], arg["description"], arg["className"], arg["type"]]
+            .find { |v| v.is_a?(String) && !v.empty? }.to_s
+        end
+
         TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
         private_constant :TURBO_SENTINEL_PREFIX
 
@@ -117,7 +130,7 @@ module Capybara
 
             entry = {
               type: params["type"],
-              text: args.map { |a| a.fetch("value") { a["description"] }.to_s }.join(" "),
+              text: args.map { |a| console_arg_text(a) }.join(" "),
               timestamp: params["timestamp"],
               args: args,
             }

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/client/web_socket.rb

@@ -33,14 +33,19 @@ module Capybara
           @driver_mutex.synchronize { @driver.text(message) }
         end
 
+        # The socket is closed even when the connection is already dead. A
+        # browser that dies first makes the reader thread #mark_dead the
+        # connection (status :closed or :error) without closing the socket,
+        # and an early return here then left the TCPSocket — one descriptor
+        # per crashed browser — open until GC finalized it (ferrum #639).
         def close
-          return if @status == :closed
-
-          @status = :closing
-          @messages.close
-          @driver_mutex.synchronize { @driver&.close }
-          @thread&.join(1) || @thread&.kill
-          @socket&.close
+          unless @status == :closed
+            @status = :closing
+            @messages.close
+            @driver_mutex.synchronize { @driver&.close }
+            @thread&.join(1) || @thread&.kill
+          end
+          close_socket
           @status = :closed
         end
 
@@ -54,8 +59,24 @@ module Capybara
           mark_dead
         end
 
+        # Single home for the "dead implies queue closed" invariant: every
+        # path that gives up on the connection must close @messages so the
+        # Client message thread's blocking pop returns. Public because the
+        # Client calls it when its own message thread dies — either transport
+        # thread dying means the connection is dead.
+        def mark_dead(status = :closed)
+          @status = status
+          @messages.close
+        end
+
         private
 
+        def close_socket
+          @socket&.close unless @socket.nil? || @socket.closed?
+        rescue IOError, SystemCallError
+          # Already torn down by the peer; nothing left to release.
+        end
+
         def connect
           uri = URI.parse(@url)
 
@@ -95,19 +116,25 @@ module Capybara
 
           @driver.on(:error) do |event|
             # Do NOT raise here. This callback fires synchronously from
-            # @driver.parse(data) inside the reader thread, which sets
-            # abort_on_exception = true. Raising DeadBrowserError escapes
-            # the reader's narrow IO rescue and aborts the entire Ruby
-            # process. Mark the connection dead and let Client#command
-            # surface DeadBrowserError on its next dispatch via closed?.
+            # @driver.parse(data) inside the reader thread. Mark the
+            # connection dead and let Client#command surface DeadBrowserError
+            # on its next dispatch via closed?.
             @logger&.puts("✗ WebSocket error: #{event.message}")
             mark_dead(:error)
           end
         end
 
+        # The reader must never take the host process down. With
+        # abort_on_exception an error the narrow IO rescue doesn't expect
+        # (Errno::ETIMEDOUT is a SystemCallError, not an IOError) was re-raised
+        # on the main thread wherever it happened to be: a spec failure blamed
+        # on an unrelated call, or a server dying with its `ensure` never
+        # reaching browser.quit. Any error here means the connection is dead —
+        # report it and let the next command raise DeadBrowserError
+        # (mirrors ferrum #632).
         def start_reader_thread
           @thread = Thread.new do
-            Thread.current.abort_on_exception = true
+            Thread.current.abort_on_exception = false
 
             loop do
               break if @status == :closed || @status == :closing
@@ -120,6 +147,10 @@ module Capybara
               rescue Errno::ECONNRESET, Errno::EPIPE, IOError
                 mark_dead
                 break
+              rescue StandardError => e
+                warn "Capybara::Lightpanda: WebSocket reader died: #{e.class}: #{e.message}"
+                mark_dead(:error)
+                break
               end
             end
           end
@@ -144,14 +175,6 @@ module Capybara
           raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
-        # Single home for the "dead implies queue closed" invariant: every
-        # path that gives up on the connection must close @messages so the
-        # Client message thread's blocking pop returns.
-        def mark_dead(status = :closed)
-          @status = status
-          @messages.close
-        end
-
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e

data/lib/capybara/lightpanda/client.rb

@@ -102,12 +102,31 @@ module Capybara
         @pendings.each_value { |ivar| ivar.try_set(nil) }
       end
 
+      # The message thread must never take the host process down: with
+      # abort_on_exception, anything handle_message raised was re-raised on
+      # the main thread mid-whatever-it-was-doing. An unexpected error here
+      # means the connection is dead — mark it so and stop (ferrum #632).
+      #
+      # The `ensure` is also the fail-fast for a connection that dies
+      # *underneath* us: the WebSocket's mark_dead closes @messages, pop
+      # returns nil, the loop ends, and every blocked caller is released to
+      # raise DeadBrowserError instead of waiting out its full timeout
+      # (ferrum #630). Ordering is what makes that work — mark_dead flips the
+      # status before it closes the queue, so by the time the waiters wake,
+      # `@ws.closed?` is already true.
       def start_message_thread
         @message_thread = Thread.new do
-          Thread.current.abort_on_exception = true
-
-          while (message = @ws.messages.pop)
-            handle_message(message)
+          Thread.current.abort_on_exception = false
+
+          begin
+            while (message = @ws.messages.pop)
+              handle_message(message)
+            end
+          rescue StandardError => e
+            warn "Capybara::Lightpanda: CDP message thread died: #{e.class}: #{e.message}"
+            @ws.mark_dead(:error)
+          ensure
+            fail_pending_commands
           end
         end
       end
@@ -117,8 +136,8 @@ module Capybara
           pending = @pendings[message["id"]]
           # try_set, not set: a duplicate frame for an already-answered id
           # (Lightpanda emits occasional malformed/duplicate frames — see
-          # upstream-wishlist.md A41) would raise MultipleAssignmentError on
-          # this thread, and abort_on_exception would kill the whole process.
+          # upstream-wishlist.md A41) would raise MultipleAssignmentError and
+          # kill the connection for a frame we should simply ignore.
           pending&.try_set(message)
         elsif message["method"]
           @subscriber.dispatch(message["method"], message["params"])

data/lib/capybara/lightpanda/cookies.rb

@@ -79,7 +79,12 @@ module Capybara
       # Ferrum/Cuprite spelling: `browser.cookies["session_id"]`.
       alias [] get
 
-      def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, # rubocop:disable Metrics/ParameterLists
+      # Returns whether the browser accepted the cookie (ferrum parity).
+      # Lightpanda answers `{success: false}` and drops the cookie for an
+      # invalid combination — notably `same_site: "None"` without `secure`
+      # since upstream #3529 (build 9877), Chrome's rule — so callers that
+      # need it to stick should check the result.
+      def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, # rubocop:disable Metrics/ParameterLists, Naming/PredicateMethod
               same_site: nil, expires: nil)
         params = {
           name: name,
@@ -96,7 +101,8 @@ module Capybara
         params[:sameSite] = same_site if %w[Strict Lax None].include?(same_site)
         params[:expires] = expires.to_i if expires
 
-        browser.command("Network.setCookie", **params)
+        result = browser.command("Network.setCookie", **params)
+        !(result.is_a?(Hash) && result["success"] == false)
       end
 
       def remove(name:, domain: nil, path: "/")
@@ -119,10 +125,13 @@ module Capybara
       # Load cookies from a YAML file produced by `store` and re-set them.
       # CDP requires either domain or url for each cookie; entries from `store`
       # already include domain, so they round-trip cleanly. Returns true on
-      # success (intentionally not a predicate — mirrors ferrum's API).
+      # success (intentionally not a predicate — mirrors ferrum's API). A
+      # cookie the browser refuses is reported on stderr rather than raised,
+      # so one bad entry doesn't abort restoring the rest.
       def load(path = "cookies.yml") # rubocop:disable Naming/PredicateMethod
         cookies = YAML.load_file(path)
-        cookies.each { |c| restore_cookie(c) }
+        rejected = cookies.reject { |c| restore_cookie(c) }.map { |c| c.transform_keys(&:to_s)["name"] }
+        warn "Capybara::Lightpanda: the browser refused cookies from #{path}: #{rejected.join(', ')}" if rejected.any?
         true
       end
 
@@ -140,11 +149,24 @@ module Capybara
           http_only: attrs["httpOnly"] || false,
         }
         params[:domain] = attrs["domain"] if attrs["domain"]
-        params[:same_site] = attrs["sameSite"] if attrs["sameSite"]
+        same_site = restored_same_site(attrs)
+        params[:same_site] = same_site if same_site
         exp = attrs["expires"]
         params[:expires] = Time.at(exp) if exp.is_a?(Numeric) && exp.positive?
         set(**params)
       end
+
+      # Lightpanda below build 9877 reported every cookie without a SameSite
+      # attribute as "None", so a file stored then is full of insecure
+      # SameSite=None cookies — which the browser now rejects (Chrome's rule,
+      # upstream #3529). Leaving SameSite unset restores what the cookie
+      # actually was: unspecified, i.e. Lax-by-default.
+      def restored_same_site(attrs)
+        same_site = attrs["sameSite"]
+        return nil if same_site == "None" && !attrs["secure"]
+
+        same_site
+      end
     end
   end
 end

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

@@ -12,5 +12,6 @@ window._lightpanda = {
   isObscured: isObscured,
   isDisabled: isDisabled,
   isContentEditable: isContentEditable,
+  pointerFocusTarget: pointerFocusTarget,
   visibleText: visibleText
 };

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

@@ -17,7 +17,7 @@
 // separately because checkVisibility's defaults (per spec) ignore it.
 //
 // External `<link rel=stylesheet>` ARE fetched and applied — the gem
-// always passes --enable-external-stylesheets (Lightpanda PR #2487,
+// always passes `--load-resources stylesheet` (Lightpanda PR #2487,
 // guaranteed by the build floor) — so stylesheet-driven `display:none`
 // participates in this check. The remaining gap is viewport emulation:
 // `@media` rules and `matchMedia()` evaluate against the hardcoded
@@ -92,6 +92,43 @@ function isContentEditable(el) {
   return false;
 }
 
+// The element a real pointer press on `el` would focus: the nearest focusable
+// inclusive ancestor, or null when the press lands on nothing focusable (Chrome
+// then moves focus to the body). Lightpanda's handleClick stopped focusing
+// controls in upstream #3702 (build 9968), and an untrusted `mousedown` — the
+// only kind CLICK_JS can dispatch — never runs the focus default, so the
+// driver has to apply it itself or `click` then `page.send_keys` types nowhere.
+function pointerFocusTarget(el) {
+  function isEditingHost(n) {
+    if (!n.hasAttribute || !n.hasAttribute('contenteditable')) return false;
+    return (n.getAttribute('contenteditable') || '').toLowerCase() !== 'false';
+  }
+  function isFocusable(n) {
+    if (isDisabled(n)) return false;
+    switch ((n.tagName || '').toUpperCase()) {
+      case 'INPUT': return (n.getAttribute('type') || '').toLowerCase() !== 'hidden';
+      case 'SELECT': case 'TEXTAREA': case 'BUTTON': case 'IFRAME': case 'SUMMARY': return true;
+      case 'A': case 'AREA': return n.hasAttribute('href');
+    }
+    return n.hasAttribute('tabindex');
+  }
+
+  for (var n = el; n && n.nodeType === 1; n = n.parentElement) {
+    // A press on a <label> lands on its control (the label's activation
+    // behavior); the label itself is never focusable.
+    if ((n.tagName || '').toUpperCase() === 'LABEL' && n.control) {
+      return isFocusable(n.control) ? n.control : null;
+    }
+    if (isEditingHost(n)) {
+      // Focus goes to the outermost element of a contiguous editable region.
+      while (n.parentElement && isEditingHost(n.parentElement)) n = n.parentElement;
+      return n;
+    }
+    if (isFocusable(n)) return n;
+  }
+  return null;
+}
+
 // 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

data/lib/capybara/lightpanda/keyboard.rb

@@ -171,19 +171,37 @@ module Capybara
         release_modifiers(active_mods)
       end
 
+      # A chord with Ctrl or Meta is a command, not text: Chrome inserts
+      # nothing for Ctrl+A, it selects. Since upstream #3542 (build 9580)
+      # Lightpanda inserts whatever the keyDown's `text` carries, so sending
+      # `text` with Ctrl held typed a stray "a" into the field. The keyDown
+      # still names the key, so shortcut handlers (`e.ctrlKey && e.key ===
+      # "a"`) fire exactly as before.
+      COMMAND_MODIFIERS = %i[ctrl control meta command].freeze
+      private_constant :COMMAND_MODIFIERS
+
       def dispatch_modified_char(char, modifier_value, modifiers)
-        text = modifiers.include?(:shift) ? self.class.shifted(char) : char
-        send_key_event("keyDown", { key: text, text: text, unmodifiedText: char }, modifiers: modifier_value)
-        send_key_event("keyUp", { key: text }, modifiers: modifier_value)
+        key = modifiers.include?(:shift) ? self.class.shifted(char) : char
+        definition = { key: key, unmodifiedText: char }
+        definition[:text] = key unless modifiers.intersect?(COMMAND_MODIFIERS)
+        send_key_event("keyDown", definition, modifiers: modifier_value)
+        send_key_event("keyUp", { key: key }, modifiers: modifier_value)
       end
 
       def key_definition(key)
         KEYS.fetch(key) { raise ArgumentError, "Unknown key: #{key.inspect}" }
       end
 
+      # Always `keyDown`, never `rawKeyDown`. Chrome's convention (Ferrum,
+      # Puppeteer) is rawKeyDown for keys that carry no `text`, but Lightpanda's
+      # Input.dispatchKeyEvent drops rawKeyDown on the floor as a
+      # Chrome-internal type (input.zig: `if (params.type == .rawKeyDown)
+      # return;`). Under that convention every text-less key — Backspace,
+      # Delete, Tab, Escape, the arrows — silently never reached the page,
+      # while Enter and Space (which have `text`) did. Lightpanda synthesizes
+      # its own keypress from a keyDown, so there is nothing to double-fire.
       def raw_dispatch(definition, modifiers: 0)
-        type = definition[:text] ? "keyDown" : "rawKeyDown"
-        send_key_event(type, definition, modifiers: modifiers)
+        send_key_event("keyDown", definition, modifiers: modifiers)
         send_key_event("keyUp", definition, modifiers: modifiers)
       end
 

data/lib/capybara/lightpanda/network.rb

@@ -20,7 +20,7 @@ module Capybara
         @traffic = []
         @traffic_mutex = Mutex.new
         @enabled = false
-        @request_handler = @response_handler = nil
+        @request_handler = @response_handler = @failure_handler = nil
         @last_navigation_response = nil
         @document_request_id = nil
       end
@@ -111,10 +111,10 @@ module Capybara
         browser.page_command("Network.setExtraHTTPHeaders", headers: {})
       end
 
-      # Count of in-flight requests (those with no response yet recorded).
+      # Count of in-flight requests (no response and no failure recorded yet).
       # Cheap predicate-friendly accessor (ferrum parity).
       def pending_connections
-        @traffic_mutex.synchronize { @traffic.count { |t| t[:response].nil? } }
+        @traffic_mutex.synchronize { @traffic.count { |t| open?(t) } }
       end
 
       # True when no more than `connections` requests are in-flight.
@@ -158,8 +158,10 @@ module Capybara
       def subscribe
         @request_handler = build_request_handler
         @response_handler = build_response_handler
+        @failure_handler = build_failure_handler
         browser.on("Network.requestWillBeSent", &@request_handler)
         browser.on("Network.responseReceived", &@response_handler)
+        browser.on("Network.loadingFailed", &@failure_handler)
       end
 
       # Redirects follow Chrome's shape (Lightpanda since #3175, build ≥8602):
@@ -184,6 +186,7 @@ module Capybara
             method: params.dig("request", "method"),
             timestamp: params["timestamp"],
             response: nil,
+            error: nil,
           }
           @traffic_mutex.synchronize do
             if (redirect = params["redirectResponse"]) && (previous = last_open_entry(params["requestId"]))
@@ -214,9 +217,31 @@ module Capybara
         end
       end
 
+      # A request that never gets a response — refused connection, CORS
+      # block, abort — ends with Network.loadingFailed instead. Without this
+      # handler its entry stayed open forever, so pending_connections never
+      # reached zero and every wait_for_idle burned its full timeout. Routine
+      # since Lightpanda enforces CORS by default (upstream #3654, build 9883:
+      # a blocked fetch reports errorText "CorsBlocked"). Ferrum closes its
+      # exchange on the same event.
+      def build_failure_handler
+        lambda do |params|
+          @traffic_mutex.synchronize do
+            request = last_open_entry(params["requestId"])
+            next unless request
+
+            request[:error] = params["errorText"].to_s
+          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? }
+        @traffic.reverse_each.find { |t| t[:request_id] == request_id && open?(t) }
+      end
+
+      def open?(entry)
+        entry[:response].nil? && entry[:error].nil?
       end
 
       def response_summary(response)
@@ -231,8 +256,10 @@ module Capybara
       def unsubscribe
         browser.off("Network.requestWillBeSent", @request_handler) if @request_handler
         browser.off("Network.responseReceived", @response_handler) if @response_handler
+        browser.off("Network.loadingFailed", @failure_handler) if @failure_handler
         @request_handler = nil
         @response_handler = nil
+        @failure_handler = nil
       end
     end
   end

data/lib/capybara/lightpanda/node.rb

@@ -256,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() }")
+        call(SEND_KEYS_FOCUS_JS)
         driver.browser.keyboard.type(*)
+        driver.browser.wait_for_idle
       end
 
       def tag_name
@@ -593,7 +609,21 @@ module Capybara
           // Cancelling mousedown suppresses focus/text-selection in a real
           // browser but never the click, so the click below is dispatched
           // unconditionally.
-          hit.dispatchEvent(new EventCtor('mousedown', { bubbles: true, cancelable: true }));
+          var pressed = hit.dispatchEvent(new EventCtor('mousedown', { bubbles: true, cancelable: true }));
+          // mousedown's default action moves focus. Ours is untrusted, so the
+          // browser won't do it (and since upstream #3702 its click handling
+          // doesn't either): focus what the press landed on, or blur the
+          // current field when it landed on nothing focusable — Chrome's
+          // behavior, and what `click` then `page.send_keys` relies on.
+          if (pressed && window._lightpanda) {
+            var doc = hit.ownerDocument;
+            var focusTarget = _lightpanda.pointerFocusTarget(hit);
+            if (focusTarget) {
+              if (doc.activeElement !== focusTarget) focusTarget.focus();
+            } else if (doc.activeElement && doc.activeElement !== doc.body && doc.activeElement.blur) {
+              doc.activeElement.blur();
+            }
+          }
           hit.dispatchEvent(new EventCtor('mouseup', { bubbles: true, cancelable: true }));
           var clickEvt = new EventCtor('click', { bubbles: true, cancelable: true });
           var notCancelled = hit.dispatchEvent(clickEvt);
@@ -902,8 +932,46 @@ module Capybara
         }
       JS
 
+      # Focuses the element keys are about to be typed into, WebDriver's
+      # "Element Send Keys" way (what chromedriver's focus script does): an
+      # element that did NOT already have focus gets its caret after its
+      # content. Since upstream #3424 (build 9234) `Input.insertText` inserts
+      # at the caret, and a value seeded by the `value=` attribute leaves the
+      # caret at 0 — without this, `send_keys("x")` on a pre-filled field
+      # typed "xfoo" where Chrome types "foox". An element that already has
+      # focus keeps its caret, so `page.send_keys` mid-edit continues in place.
+      # A non-focusable target (focus() is a no-op on those since upstream
+      # #3592, build 9646) must not leave the previous field focused, or its
+      # keys land there: blur it so they go to the body, as in Chrome.
+      SEND_KEYS_FOCUS_JS = <<~JS
+        function() {
+          var doc = this.ownerDocument;
+          if (doc.activeElement === this) return;
+          this.focus();
+          if (doc.activeElement !== this) {
+            if (doc.activeElement && doc.activeElement !== doc.body && doc.activeElement.blur) doc.activeElement.blur();
+            return;
+          }
+          if (typeof this.setSelectionRange === 'function') {
+            // Throws on types without a selection (email, number, …) — those
+            // have no caret to place.
+            try {
+              var end = String(this.value || '').length;
+              this.setSelectionRange(end, end);
+            } catch (e) {}
+          }
+        }
+      JS
+
+      # A disabled option (or one in a disabled <optgroup>/<select>) is not
+      # selectable by a user, and Capybara's shared spec expects selecting one
+      # to be a no-op (rack_test: `return if disabled?`). Both IDL routes —
+      # `sel.value =` and `option.selected = true` — select it per spec;
+      # Lightpanda's `value` getter used to skip disabled options and hide that,
+      # until upstream #3502 (build 9424).
       SELECT_OPTION_JS = <<~JS
         function() {
+          if (_lightpanda.isDisabled(this)) return;
           var sel = this.parentElement;
           while (sel && (sel.tagName || '').toUpperCase() !== 'SELECT') sel = sel.parentElement;
           if (!sel) {
@@ -913,14 +981,10 @@ module Capybara
             // that path itself; just no-op here.
             return;
           }
-          if (sel.multiple) {
-            this.selected = true;
-          } else {
-            // Lightpanda doesn't auto-deselect siblings when we set
-            // `option.selected`, so mirror what a real browser does and
-            // route the change through the parent's `value`.
-            sel.value = this.value;
-          }
+          // Selects exactly this option — not the first one sharing its
+          // value — and, in a single <select>, deselects the rest (upstream
+          // #3375, guaranteed by the floor).
+          this.selected = true;
           sel.dispatchEvent(new Event('input', {bubbles: true}));
           sel.dispatchEvent(new Event('change', {bubbles: true}));
         }

data/lib/capybara/lightpanda/options.rb

@@ -47,13 +47,12 @@ 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.
+      # load_images: adds `image` to the `--load-resources` value so `<img>`
+      # elements are fetched over the network (upstream #3230, build >= 8834,
+      # in the floor). 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`.
       attr_accessor :host, :port, :timeout, :handshake_timeout, :process_timeout,
                     :window_size, :browser_path, :headless, :logger, :save_path,
                     :raise_on_unhandled_modal, :load_images

data/lib/capybara/lightpanda/process.rb

@@ -63,10 +63,10 @@ module Capybara
       # returns spec-correct booleans. Lets _lightpanda.isVisible detect
       # inline-@media-gated hides via el.checkVisibility() without any
       # gem-side workaround),
-      # PR #2487 (css: external <link rel="stylesheet"> fetch behind the
-      # --enable-external-stylesheets flag — build_args now passes that flag
-      # unconditionally, so the floor MUST include the build that introduced
-      # it; the flag is a fatal UnknownOption on builds < 6353),
+      # PR #2487 (css: external <link rel="stylesheet"> fetch behind a CLI
+      # flag — build_args passes it unconditionally, so the floor MUST include
+      # the build that introduced it; since #3305 (8946) the spelling is
+      # `--load-resources stylesheet`, see the 2026-09-06 bump),
       # PR #2498 (StyleManager: author display rule beats UA [hidden] — fixes
       # the Stimulus/Alpine dropdown ElementNotFound),
       # PR #2635 (dom: DOM.setFileInputFiles backs input.files + fires change
@@ -201,7 +201,70 @@ module Capybara
       # 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.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("8796")
+      #
+      # 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).
+      #
+      # 2026-09-06 bump 8875 -> 9058. The binding constraint is the lockstep
+      # with MINIMUM_RELEASE below: 9058 is exactly `git rev-list --count
+      # 0.4.0`, the newest tagged release, so this is as high as the nightly
+      # floor can go without naming a release that does not exist. Two fixes
+      # the gem now asserts on ride along:
+      #   #3298 (8937) Backspace/Delete through CDP Input.dispatchKeyEvent
+      #     actually edit an <input>/<textarea>: a trusted `beforeinput`
+      #     (cancelable) then `input` with inputType deleteContentBackward /
+      #     deleteContentForward, via the text_entry.zig mixin. Below 8937 the
+      #     keys were dead, so Node#send_keys(:backspace) silently did nothing.
+      #     Pinned by test/features/keyboard_editing_test.rb.
+      #   #3305 (8946) renamed --enable-external-stylesheets to
+      #     `--load-resources stylesheet` and --log-filter-scopes to
+      #     --log-filter; build_args now passes the new spelling, which is a
+      #     fatal UnknownOption below 8946. (The same PR flipped iframes and
+      #     workers off by default — Browser#configure_loading re-enables them
+      #     per BrowserContext, and did so before this bump.)
+      #
+      # 2026-10-03 bump 9058 -> 9994 (= release 1.0.0, the new lockstep cap).
+      # Retired or ungated by it:
+      #   #3375 (9071) option.selected deselects its siblings — SELECT_OPTION_JS
+      #     dropped its `sel.value =` detour, which selected the FIRST option
+      #     sharing a value rather than the one Capybara resolved.
+      #   #3378 (9207) matchMedia `change` fires on a viewport override —
+      #     viewport_test.rb's pin runs un-gated.
+      #   #3414 / #3420 / #3422 / #3424 (9217-9234, ours) trusted
+      #     `beforeinput` is cancelable; `.value =` moves the caret to the end;
+      #     a child-text <textarea> can be selected; arrows/Home/End move the
+      #     caret — the `send_keys should send special characters` skip is
+      #     gone and keyboard_editing_test.rb pins all four.
+      # Behavior changes the floor now guarantees, all compensated or
+      # Chrome-parity: #3654 (9883) CORS enforced by default (blocked requests
+      # end in Network.loadingFailed, which Network consumes); #3529 (9877)
+      # SameSite=None without Secure refused (Cookies#set reports it);
+      # #3702 (9968) click no longer focuses (CLICK_JS focuses itself).
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("9994")
 
       # Second, equivalent floor for the *release* channel.
       #
@@ -210,21 +273,66 @@ 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. As of 2026-08-25 NO published release clears the 8796
-      # floor — 0.3.7 (build 8671) predates the draggable-IDL and
-      # coordinate-flooring fixes 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 8834, 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` >= 8796 and update the
-      # lockstep table in process_test.rb.
+      # nightly floor. 1.0.0 (2026-10-02) is build 9994 — exactly the nightly
+      # floor, which is no accident: the floor was raised *to* the release so
+      # both channels gate the same commit. (0.4.1 = 9463 and 0.4.0 = 9058
+      # predate fixes the floor exists for.)
       #
       # 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.8")
+      MINIMUM_RELEASE = Gem::Version.new("1.0.0")
+
+      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
 
@@ -273,38 +381,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
@@ -369,10 +451,6 @@ module Capybara
           @options.port.to_s,
           "--log_level",
           "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.
-          "--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
           # Chrome's inbound DevTools buffer. An inbound message over the cap is
@@ -387,12 +465,23 @@ 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
+        # Sub-resource loading is one comma-separated `--load-resources` value
+        # (Config.LoadResources is a packed struct the CLI parser fills from a
+        # comma list — the flag is NOT repeatable). Every kind defaults OFF
+        # since #3305 (build 8946).
+        #   stylesheet — always on (PR #2487, build >= 6353) so linked CSS
+        #     contributes to checkVisibility / getComputedStyle; see
+        #     .claude/rules/lightpanda-io.md limitation #5. The spelling
+        #     `--load-resources stylesheet` is a fatal UnknownOption below 8946,
+        #     which the floor clears.
+        #   image — opt-in (upstream #3230, build >= 8834): images never feed
+        #     the DOM predicates, so the default spends no bandwidth on them.
+        #     See Options#load_images.
+        #   iframe / worker — deliberately NOT here. Browser#configure_loading
+        #     re-enables both over CDP (LP.configureLoading) per BrowserContext.
+        resources = ["stylesheet"]
+        resources << "image" if @options.load_images
+        base.push("--load-resources", resources.join(","))
         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.11.0"
+    VERSION = "0.13.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Navid Emad
@@ -129,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Capybara driver for the Lightpanda headless browser
 test_files: []