capybara-lightpanda 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b898fd26a9e25f95263b605f022264cd2a132bbca82081bd931fe542c88673e
-  data.tar.gz: 4776e1326f56cd6f123538b130dfb7de1edb1a745a45574e31520a1a5227ce94
+  metadata.gz: 2515195575d1146f7cd14f479801360770c65d39d84c2bdc58be987e503bda88
+  data.tar.gz: ab94aba998ccafb870e109504e7f33dd22a35bcd2ba79750cfd2bb79226feaf1
 SHA512:
-  metadata.gz: 025d4fd23a6f0b4379c6e34d878610b657a06dcf33ab5490b606e5e42ed2e452475860283df232f8c397bbf1b48144f0d89be33bf7e5a70fe430a14e26bfb1a7
-  data.tar.gz: 16193011f9ea880c74300a45491ab5dbe36abe55e0a080fe1f65edf36d9722daf6e9842de361f498068952970f3f2d975a64d8b92eb8ecaf2600c01b342caf34
+  metadata.gz: 3eadd479f7c543354a89c3f69a1be6ee94be6067b52171766c3da1b3c9b091a9e404c987e9af11c5230c89e8df319013822748b0bd6ba0e7e56ebd143f3e7689
+  data.tar.gz: fec1bbad25a59b177b6ac117e82bf65eef995196f233aa96742f71b2def90133132b913c0591bf40f2ca554d09cb4e6b26cbb132a0f3ae5e7ab811efa4504914

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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.

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 = "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

@@ -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() }")
         driver.browser.keyboard.type(*)
+        driver.browser.wait_for_idle
       end
 
       def tag_name

data/lib/capybara/lightpanda/process.rb

@@ -201,7 +201,37 @@ 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). 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.
       #
@@ -210,15 +240,15 @@ 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. 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
@@ -226,6 +256,56 @@ module Capybara
       # silently accept a binary the nightly channel rejects.
       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
 
       def initialize(options)
@@ -273,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
@@ -371,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

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.11.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.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Navid Emad