capybara-lightpanda 0.9.0 → 0.11.0

data/lib/capybara/lightpanda/process.rb

@@ -97,11 +97,136 @@ module Capybara
       # merged 2026-06-12) made the index.js readystatechange re-dispatch
       # shim redundant, so it was removed — on builds without #2708 Turbo's
       # PageObserver never reaches pageLoaded() and turbo:load never fires.
-      # Build 6736 = first published nightly carrying the #2708 merge — now
-      # the binding floor.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6736")
+      # Build 6736 carried the #2708 merge.
+      # PR #2722 (Browser.setDownloadBehavior streams Content-Disposition:
+      # attachment responses to disk under downloadPath + emits
+      # Browser.downloadWillBegin / downloadProgress, merged 2026-06-19) backs
+      # the Downloads tracker (downloads.rb) wired in Browser#create_page. On
+      # builds < 7545 setDownloadBehavior is a bare success no-op — every
+      # download would silently never be written to disk — so the floor MUST
+      # include it. Note Lightpanda triggers downloads on Content-Disposition:
+      # attachment, NOT by MIME type (a text/csv response without that header
+      # is rendered as a normal navigation), which is why Capybara's
+      # MIME-triggered :download shared spec stays in capybara_skip.
+      # Build 7545 = the #2722 merge (a808386c).
+      # PR #2785 (build 7550, improve innerText + outerText) AND PR #2795
+      # (build 7571, innerText uses StyleManager visibility) make native
+      # Element.innerText implement the HTML rendered-text collection steps —
+      # block line breaks + skipping display:none descendants. The
+      # _lightpanda.visibleText predicate (predicates.js) now delegates the
+      # rendered-text collection to native innerText (keeping only a visibility
+      # gate + ShadowRoot fragment walk), so the floor MUST include #2795; on
+      # builds < 7571 innerText returns textContent verbatim (no block breaks,
+      # leaks display:none text).
+      # Build 7571 = the #2795 merge (48ed689c).
+      # PR #2719 (css: apply @layer block rules to the cascade, merged
+      # 2026-07-17) makes StyleManager rank `@layer` rules correctly. Before it,
+      # a rule inside an `@layer` block was dropped from the cascade entirely,
+      # so an element hidden by an `@layer` `display: none` — the default shape
+      # of Tailwind v4's generated CSS — reported `checkVisibility() === true`.
+      # `_lightpanda.isVisible` (predicates.js) terminates in checkVisibility(),
+      # so on builds < 8160 Capybara believes such elements are visible and acts
+      # on them: clicks land on hidden nodes and `assert_no_selector` passes for
+      # visible ones. That is a wrong-answer bug rather than an exception, which
+      # is exactly the kind users can't diagnose, so the floor MUST include it.
+      # Build 8160 = the #2719 merge (b19b5725).
+      # PR #2983 (css: respect @layer priority, merged 2026-07-24) is the second
+      # half of that same fix and the reason 8160 is NOT sufficient. #2719 only
+      # made rules inside an `@layer` block *participate* in the cascade; it
+      # ranked them by specificity + document order alone. #2983 widened
+      # VisibilityRule.priority to carry a 12-bit layer rank, so layer order
+      # finally beats specificity as the spec requires. On builds 8160–8280 a
+      # page whose layers disagree about `display` resolves to the wrong rule —
+      # Tailwind v4's `@layer utilities` losing to `@layer base` is the common
+      # shape — and `_lightpanda.isVisible` (predicates.js) terminates in
+      # checkVisibility(), so Capybara again believes hidden elements are
+      # visible. Same undiagnosable wrong-answer class as #2719 itself, so the
+      # floor MUST include it.
+      # Build 8281 = the #2983 merge (76e2e7e6).
+      # PR #3015 (cdp: sanitize non-UTF-8 values, merged 2026-07-24) fixes
+      # issue #2992: a legacy-encoded Content-Disposition filename made
+      # Browser.downloadWillBegin emit `suggestedFilename` as a JSON array of
+      # bytes instead of a string. Downloads#build_will_handler does
+      # File.basename(params["suggestedFilename"].to_s), so below this build it
+      # records a "[130, 160, ...]" basename and Driver#downloads hands back a
+      # path that does not exist.
+      # Build 8283 = the #3015 merge (8fbcc7e5).
+      # PR #3054 (forms: close the ancestor dialog on method=dialog submission,
+      # merged 2026-07-25) makes `<form method="dialog">` close its nearest
+      # ancestor <dialog>, set returnValue from the submitter's IDL value, fire
+      # close, and perform no navigation. Below it the submission falls through
+      # to a GET navigation and the dialog stays open forever — which is the
+      # <dialog>+Turbo-confirm idiom Spree 5's admin uses for every destroy
+      # confirmation. There is no gem-side workaround to guard this: the only
+      # defense is the floor.
+      # Build 8311 = the #3054 merge (c917cadc).
+      # PR #3058 (forms: include optgroup children in a select's list of
+      # options, merged 2026-07-26) makes `<option>`s inside an `<optgroup>`
+      # reachable through HTMLSelectElement (options / value / selectedIndex /
+      # submission). Below it Capybara's `select` cannot find a grouped option
+      # at all and there is no gem-side workaround — a plain ElementNotFound on
+      # any grouped <select>. Build 8328 = the #3058 merge (c7182354).
+      # PR #3080 (webapi: increase max timer count, merged 2026-07-29) lifts the
+      # one-shot setTimeout cap 512 → 2048 (Airbnb-class pages schedule 600+);
+      # below it timers past the cap are silently dropped and page JS stalls in
+      # ways that read as Capybara timeouts. Build 8412 = the #3080 merge.
+      # PR #3081 + #3082/#3085 (script load/error events; dynamic scripts whose
+      # `src` is set via setAttribute, merged 2026-07-30) — below them an
+      # inline script fired no load event, a throwing script still fired
+      # `load`, and a setAttribute('src') script never loaded, which breaks
+      # loader idioms (importmap shims, lazy widget bootstraps) that gate the
+      # UI Capybara waits for. Builds 8414/8419.
+      # PR #3087 (fix: potential UAF when an option's value is programmatically
+      # 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) — 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
+      # per context), and build 8305 (#3048) derives scrollWidth/scrollHeight
+      # from element content (the gem keeps scroll as a no-op either way).
+      # PR #2664 (Emulation.setDeviceMetricsOverride, build 7556) is subsumed:
+      # Browser#set_viewport calls it on every create_page to honor the
+      # `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.
+      #
+      # 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.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("8796")
+
+      # Second, equivalent floor for the *release* channel.
+      #
+      # Tagged releases are built with `-Dversion=<tag>`, which resolves to a
+      # plain semver with no pre-release tag — so `lightpanda version` prints a
+      # 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.
+      #
+      # 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")
 
-      attr_reader :pid, :ws_url, :version, :nightly_build
+      attr_reader :pid, :ws_url, :version, :nightly_build, :release
 
       def initialize(options)
         @options = options
@@ -109,6 +234,7 @@ module Capybara
         @ws_url = nil
         @version = nil
         @nightly_build = nil
+        @release = nil
         @stdout_r = nil
         @stdout_w = nil
         @stderr_r = nil
@@ -147,20 +273,37 @@ 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.
       def check_minimum_version(binary_path)
         stdout, = Open3.capture3(binary_path, "version")
         @version = stdout.strip
-        # Accept either `nightly.NNNN` (publicly distributed builds) or
-        # `dev.NNNN` (locally compiled trees) — the build number is the same
-        # `git rev-list --count HEAD` counter, just labelled differently.
-        build = @version[/(?:nightly|dev)\.(\d+)/, 1]
-        @nightly_build = Gem::Version.new(build) if build
 
-        return if @nightly_build && @nightly_build >= MINIMUM_NIGHTLY_BUILD
+        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 build >= #{MINIMUM_NIGHTLY_BUILD}. " \
+              "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
+              "or release >= #{MINIMUM_RELEASE}. " \
               "Update: #{Binary.update_hint(binary_path)}"
       rescue Errno::ENOENT
         # Binary not runnable — let attempt_start handle it
@@ -230,7 +373,26 @@ module Capybara
           # 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
+          # dropped with WS close 1009 and NO JSON-RPC error — the whole CDP
+          # connection dies (wishlist A44). The 1 MiB default already covers
+          # axe-core (~553 KB), but larger injected bundles (jQuery + plugins,
+          # instrumentation) via execute_script exceed it (Node#drop used to as
+          # well, before files moved to DOM.setFileInputFiles). The reader
+          # buffer grows lazily (16 KB at init),
+          # so a high cap costs nothing until a big message actually arrives.
+          # Flag added in PR #2760 (build 7441) — below the floor, so guaranteed.
+          "--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.9.0"
+    VERSION = "0.11.0"
   end
 end

data/lib/capybara-lightpanda.rb

@@ -14,6 +14,7 @@ require_relative "capybara/lightpanda/utils/wait"
 require_relative "capybara/lightpanda/client"
 require_relative "capybara/lightpanda/headers"
 require_relative "capybara/lightpanda/network"
+require_relative "capybara/lightpanda/downloads"
 require_relative "capybara/lightpanda/cookies"
 require_relative "capybara/lightpanda/keyboard"
 require_relative "capybara/lightpanda/browser"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Navid Emad
@@ -79,16 +79,19 @@ files:
 - lib/capybara/lightpanda/browser/modals.rb
 - lib/capybara/lightpanda/browser/navigation.rb
 - lib/capybara/lightpanda/browser/runtime.rb
+- lib/capybara/lightpanda/browser/selenium_compat.rb
 - lib/capybara/lightpanda/client.rb
 - lib/capybara/lightpanda/client/subscriber.rb
 - lib/capybara/lightpanda/client/web_socket.rb
 - lib/capybara/lightpanda/cookies.rb
+- lib/capybara/lightpanda/downloads.rb
 - lib/capybara/lightpanda/driver.rb
 - lib/capybara/lightpanda/element_extension.rb
 - lib/capybara/lightpanda/errors.rb
 - lib/capybara/lightpanda/headers.rb
 - lib/capybara/lightpanda/javascripts/attach.js
 - lib/capybara/lightpanda/javascripts/banner.js
+- lib/capybara/lightpanda/javascripts/errors.js
 - lib/capybara/lightpanda/javascripts/predicates.js
 - lib/capybara/lightpanda/javascripts/turbo.js
 - lib/capybara/lightpanda/keyboard.rb
@@ -126,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Capybara driver for the Lightpanda headless browser
 test_files: []