capybara-lightpanda 0.1.0 → 0.2.1

data/lib/capybara/lightpanda/network.rb

@@ -9,6 +9,8 @@ module Capybara
         @browser = browser
         @traffic = []
         @enabled = false
+        @request_handler = nil
+        @response_handler = nil
       end
 
       def enable
@@ -22,7 +24,13 @@ module Capybara
       def disable
         return unless @enabled
 
+        # Tell the browser to stop emitting BEFORE unsubscribing locally:
+        # otherwise an in-flight Network.responseReceived can race past the
+        # already-removed handler and leave a `response: nil` entry in
+        # @traffic for the matching request — which then trips
+        # wait_for_idle's pending count on a future call.
         browser.command("Network.disable")
+        unsubscribe
         @enabled = false
       end
 
@@ -34,6 +42,18 @@ module Capybara
         @traffic.clear
       end
 
+      # Wipe local state without sending Network.disable. Called by
+      # Browser#reset after Target.disposeBrowserContext, which destroys
+      # the subscriptions and the Network domain along with the context —
+      # leaving @enabled true would silently no-op the next #enable.
+      # Also unsubscribes locally so we don't rely on the caller having
+      # cleared the Subscriber first.
+      def reset
+        unsubscribe
+        @traffic.clear
+        @enabled = false
+      end
+
       def headers=(headers)
         @extra_headers = headers
         browser.page_command("Network.setExtraHTTPHeaders", headers: headers)
@@ -65,7 +85,7 @@ module Capybara
       private
 
       def subscribe
-        browser.on("Network.requestWillBeSent") do |params|
+        @request_handler = lambda do |params|
           @traffic << {
             request_id: params["requestId"],
             url: params.dig("request", "url"),
@@ -75,7 +95,7 @@ module Capybara
           }
         end
 
-        browser.on("Network.responseReceived") do |params|
+        @response_handler = lambda do |params|
           request = @traffic.find { |t| t[:request_id] == params["requestId"] }
 
           next unless request
@@ -86,6 +106,16 @@ module Capybara
             mime_type: params.dig("response", "mimeType"),
           }
         end
+
+        browser.on("Network.requestWillBeSent", &@request_handler)
+        browser.on("Network.responseReceived", &@response_handler)
+      end
+
+      def unsubscribe
+        browser.off("Network.requestWillBeSent", @request_handler) if @request_handler
+        browser.off("Network.responseReceived", @response_handler) if @response_handler
+        @request_handler = nil
+        @response_handler = nil
       end
     end
   end

data/lib/capybara/lightpanda/node.rb

@@ -116,6 +116,14 @@ module Capybara
         call("function() { this.dispatchEvent(new MouseEvent('mouseover', {bubbles: true, cancelable: true})) }")
       end
 
+      # Dispatch an arbitrary DOM event by name. Mirrors Cuprite's Node#trigger
+      # — picks the right Event constructor for known mouse/focus/form names
+      # and falls back to a generic Event for everything else (so callers can
+      # fire custom events like `node.trigger('lp:custom')`).
+      def trigger(event)
+        call(TRIGGER_JS, event.to_s)
+      end
+
       def set(value, **_options)
         case tag_name
         when "input"
@@ -246,8 +254,6 @@ module Capybara
         raise ObsoleteNode.new(self, "Node is no longer attached to the document")
       end
 
-      # Trigger implicit form submission via the IMPLICIT_SUBMIT_JS pipeline
-      # (same fetch+swap as CLICK_JS, but without a submitter).
       def implicit_submit
         call(IMPLICIT_SUBMIT_JS)
         driver.browser.wait_for_idle
@@ -277,7 +283,7 @@ module Capybara
       # HTML implicit-submission: a trailing \n in a text-like input is like the
       # user pressing Enter — submits the form when there's a default submit
       # button OR exactly one text control. Strip the \n, set the value, then
-      # route through IMPLICIT_SUBMIT_JS so CLICK_JS's fetch+swap runs.
+      # trigger submission via IMPLICIT_SUBMIT_JS.
       def fill_text_input(type, str)
         if str.end_with?("\n") && TEXT_LIKE_INPUT_TYPES.include?(type)
           call(SET_VALUE_JS, truncate_to_maxlength(str.chomp))
@@ -341,13 +347,6 @@ module Capybara
         driver.browser.with_default_context_wait do
           driver.browser.call_function_on(@remote_object_id, function_declaration, *args)
         end
-      rescue BrowserError => e
-        case e.message
-        when /MouseEventFailed/i
-          raise MouseEventFailed.new(self, e.response&.dig("message"))
-        else
-          raise
-        end
       rescue JavaScriptError => e
         case e.class_name
         when "InvalidSelector"
@@ -355,148 +354,84 @@ module Capybara
         else
           raise
         end
+      rescue BrowserError => e
+        case e.message
+        when /MouseEventFailed/i
+          raise MouseEventFailed.new(self, e.response&.dig("message"))
+        else
+          raise
+        end
       end
 
-      # Form-submit click bypass for Lightpanda.
+      # Native `this.click()` reaches all ancestors on the happy path, but if any
+      # listener throws (Stimulus / Turbo edge cases) Lightpanda halts dispatch
+      # instead of reporting the exception per DOM §2.9 step 4 (see UPSTREAM_BUGS.md
+      # Bug #3). Dispatching via JS routes through `polyfills.js`'s patchDispatch
+      # IIFE, which catches the throw and re-walks parents manually so document-
+      # level delegated handlers still see the event.
       #
-      # Lightpanda's `form.submit()` does NOT navigate — it parses, validates, but
-      # never issues an HTTP request. And `document.write()` is a no-op (verified
-      # 2026-04-26: body length unchanged after open/write/close). So both the
-      # native submit path and the previous `fetch+document.write` workaround leave
-      # the page on the original URL with the form still rendered.
+      # We dispatch a `MouseEvent` (not a generic `Event`) because Turbo's link
+      # and form interceptors guard with `event instanceof MouseEvent` before
+      # they consider intercepting — a synthetic `Event('click')` is silently
+      # ignored by Turbo Frame / Drive, and CLICK_JS would then fall through to
+      # the manual default action below, which does a full-page navigation
+      # instead of a frame swap.
       #
-      # For submit-button clicks we instead `fetch` the form action ourselves,
-      # parse the response with `DOMParser`, swap `document.body.innerHTML`, and
-      # `history.replaceState` the response URL. `_lightpanda` and the XPath
-      # polyfill survive the swap because we don't reload the document.
-      #
-      # For non-submit elements (links, regular buttons, anchors) we fall through
-      # to native `this.click()`. Turbo Drive's click handler — when Turbo is
-      # loaded — intercepts that natively, runs its own fetch+replaceWith, and
-      # works fine on Lightpanda after the `#id` rewriter polyfill in index.js.
+      # For submit buttons (`<button type=submit>`, `<input type=submit>`,
+      # `<input type=image>`): route through `form.requestSubmit(this)` so the
+      # browser dispatches a real `SubmitEvent` with submitter set, honors the
+      # submitter's `formaction` / `formmethod` / `formenctype`, and includes
+      # the submitter's name/value in the form data. A manual
+      # `dispatchEvent(new Event('submit'))` + `form.submit()` would lose all of
+      # that and break Turbo Drive / Hotwire form handling. We can't rely on
+      # the synthetic click's default action because synthetic events don't
+      # trigger the implicit form-submission default action per DOM spec.
       CLICK_JS = <<~JS
         function() {
-          var tag = this.tagName.toLowerCase();
+          var EventCtor = (typeof MouseEvent !== 'undefined') ? MouseEvent : Event;
+          var clickEvt = new EventCtor('click', { bubbles: true, cancelable: true });
+          var notCancelled = true;
+          try {
+            notCancelled = this.dispatchEvent(clickEvt);
+          } catch (e) { /* patchDispatch in polyfills.js rescues bubble phase */ }
+          if (!notCancelled || clickEvt.defaultPrevented) return;
+          var tag = this.tagName;
           var type = (this.type || '').toLowerCase();
-          // <button> with no `type` attribute defaults to submit per HTML.
-          var isSubmitBtn = (tag === 'button' && (type === '' || type === 'submit')) ||
-                            (tag === 'input' && (type === 'submit' || type === 'image'));
-          var form = isSubmitBtn ? this.form : null;
-          // Lightpanda doesn't propagate label clicks to their associated
-          // form control the way browsers do, so when Capybara clicks a
-          // <label> for a hidden checkbox/radio (automatic_label_click)
-          // we explicitly forward the click.
-          if (tag === 'label') {
-            this.click();
-            var ctrl = null;
-            var forId = this.getAttribute('for');
-            if (forId) ctrl = this.ownerDocument.getElementById(forId);
-            if (!ctrl) ctrl = this.querySelector('input, select, textarea');
-            if (ctrl) {
-              var ctype = (ctrl.type || '').toLowerCase();
-              if (ctype === 'checkbox' || ctype === 'radio') ctrl.click();
-            }
-            return;
-          }
-          if (!form) {
-            this.click();
-            // Lightpanda doesn't toggle <details> when its <summary> is clicked.
-            // Walk up to the nearest <details> (only if click hit a summary
-            // and we haven't been preventDefault'd by user JS) and flip `open`.
-            if (tag === 'summary') {
-              var d = this.parentNode;
-              while (d && d.nodeType === 1 && d.tagName.toLowerCase() !== 'details') {
-                d = d.parentNode;
-              }
-              if (d && d.tagName && d.tagName.toLowerCase() === 'details') {
-                d.open = !d.open;
-              }
-            }
-            return;
-          }
-
-          // Fire the submit event first so user JS handlers can intercept and
-          // preventDefault — but skip this when Turbo is loaded, because Turbo's
-          // submit pipeline throws on Lightpanda (and the gem already handles the
-          // navigation below). Turbo's link-click pipeline still works fine.
-          if (typeof Turbo === 'undefined') {
-            var ev;
-            if (typeof SubmitEvent === 'function') {
-              ev = new SubmitEvent('submit', { bubbles: true, cancelable: true, submitter: this });
-            } else {
-              ev = new Event('submit', { bubbles: true, cancelable: true });
-              ev.submitter = this;
-            }
-            var allowed = form.dispatchEvent(ev);
-            if (!allowed) return;
-          }
-
-          // No handler intercepted — fetch + swap ourselves because Lightpanda's
-          // native form.submit() does not navigate.
-          // Pass the submitter so the button is serialized at its document
-          // position alongside the form's other named controls.
-          var formData;
-          try { formData = new FormData(form, this); }
-          catch (e) { formData = new FormData(form); }
-          var submitterName = this.getAttribute('name');
-          if (submitterName && !formData.has(submitterName)) {
-            // Lightpanda's FormData(form, submitter) may omit a <button> with no
-            // explicit value attribute; HTML says the value falls back to
-            // textContent, so feed that in ourselves when the entry is missing.
-            var submitterValue = this.getAttribute('value');
-            if (submitterValue === null) {
-              submitterValue = (tag === 'button') ? (this.textContent || '') : '';
-            }
-            formData.append(submitterName, submitterValue);
+          var isSubmitButton =
+            (tag === 'BUTTON' && (type === 'submit' || type === '')) ||
+            (tag === 'INPUT' && (type === 'submit' || type === 'image'));
+          if (isSubmitButton && this.form) {
+            this.form.requestSubmit(this);
+          } else if (tag === 'A' && this.href && this.target !== '_blank') {
+            window.location.href = this.href;
           }
+        }
+      JS
 
-          var action = this.getAttribute('formaction') || form.getAttribute('action') || window.location.href;
-          try { action = new URL(action, window.location.href).href; } catch (e) {}
-          var method = (this.getAttribute('formmethod') || form.getAttribute('method') || 'GET').toUpperCase();
-
-          var enctype = (this.getAttribute('formenctype') ||
-                         form.getAttribute('enctype') ||
-                         'application/x-www-form-urlencoded').toLowerCase();
-          // Lightpanda's URLSearchParams.toString() drops the `=` when the value
-          // is an empty string (`{key: ""}` serializes as `key`, not `key=`),
-          // which makes the server parse the field as nil instead of "". Lightpanda
-          // also doesn't perform the HTML-spec LF→CRLF normalization for textarea
-          // values during form submission. Build the query string by hand so both
-          // round-trip correctly.
-          var formEncode = function(fd) {
-            var pairs = [];
-            for (var entry of fd.entries()) {
-              var value = entry[1];
-              if (typeof value === 'string') {
-                // Normalize line endings to CRLF per HTML form-data set spec.
-                value = value.replace(/\\r\\n|\\r|\\n/g, '\\r\\n');
-              }
-              pairs.push(encodeURIComponent(entry[0]).replace(/%20/g, '+') +
-                         '=' +
-                         encodeURIComponent(value).replace(/%20/g, '+'));
-            }
-            return pairs.join('&');
-          };
-          var opts = { method: method, credentials: 'same-origin', redirect: 'follow' };
-          if (method === 'GET') {
-            var sep = action.indexOf('?') >= 0 ? '&' : '?';
-            action = action + sep + formEncode(formData);
-          } else if (enctype === 'multipart/form-data') {
-            // Pass FormData directly — fetch sets Content-Type with the correct boundary.
-            opts.body = formData;
+      # Mirrors Cuprite's trigger map. Picks the right Event constructor based
+      # on the event name so listeners that key on `event instanceof MouseEvent`
+      # / `instanceof SubmitEvent` see what they expect; everything else goes
+      # through a generic Event so custom names ("turbo:load", "lp:custom")
+      # still dispatch. Each constructor is feature-detected (`typeof X !==
+      # 'undefined'`) before use so a missing IDL on Lightpanda falls back
+      # to plain Event rather than throwing.
+      TRIGGER_JS = <<~JS
+        function(name) {
+          var MOUSE = ['click','dblclick','mousedown','mouseenter','mouseleave',
+                       'mousemove','mouseover','mouseout','mouseup','contextmenu'];
+          var FOCUS = ['blur','focus','focusin','focusout'];
+          var init = { bubbles: true, cancelable: true };
+          var event;
+          if (MOUSE.indexOf(name) !== -1 && typeof MouseEvent !== 'undefined') {
+            event = new MouseEvent(name, init);
+          } else if (FOCUS.indexOf(name) !== -1 && typeof FocusEvent !== 'undefined') {
+            event = new FocusEvent(name, init);
+          } else if (name === 'submit' && typeof SubmitEvent !== 'undefined') {
+            event = new SubmitEvent(name, init);
           } else {
-            opts.headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
-            opts.body = formEncode(formData);
+            event = new Event(name, init);
           }
-
-          return fetch(action, opts).then(function(r) {
-            return r.text().then(function(html) { return { url: r.url, html: html }; });
-          }).then(function(o) {
-            var doc = new DOMParser().parseFromString(o.html, 'text/html');
-            document.title = (doc.title || '');
-            document.body.innerHTML = doc.body.innerHTML;
-            try { history.replaceState(null, '', o.url); } catch (e) {}
-          });
+          this.dispatchEvent(event);
         }
       JS
 
@@ -525,7 +460,14 @@ module Capybara
                             autofocus: 'autofocus', required: 'required' };
           var prop = BOOL_PROP[name.toLowerCase()];
           if (prop && this[prop] !== undefined) return this[prop];
-          return this.getAttribute(name);
+          if (this.hasAttribute(name)) return this.getAttribute(name);
+          // Property-only fallback: things like `validationMessage` have no
+          // backing HTML attribute. Return primitives only — DOM-node properties
+          // (form, options, etc.) shouldn't leak through.
+          var live = this[name];
+          if (live === null || live === undefined) return null;
+          var t = typeof live;
+          return (t === 'string' || t === 'number' || t === 'boolean') ? live : null;
         }
       JS
 
@@ -548,77 +490,25 @@ module Capybara
         }
       JS
 
-      # HTML implicit-submission: when the user presses Enter in a text-like
-      # field, the form is submitted if either (a) there's a default submit
-      # button, or (b) the form has exactly one submittable text control.
-      # `this` is the input. Mirror CLICK_JS's submit pipeline so the gem's
-      # fetch+swap path runs (Lightpanda's form.submit() doesn't navigate).
+      # HTML implicit-submission: a trailing \n in a text-like input acts like
+      # pressing Enter — submits the form if it has a default submit button OR
+      # exactly one submittable text control. Click the default button (so
+      # click handlers fire) or fall back to `form.requestSubmit()` so the
+      # `submit` event still dispatches.
       IMPLICIT_SUBMIT_JS = <<~JS
         function() {
           var form = this.form;
           if (!form) return;
-          var hasDefault = !!form.querySelector(
+          var btn = form.querySelector(
             'button[type=submit], button:not([type]), input[type=submit], input[type=image]'
           );
-          if (!hasDefault) {
-            var textInputs = form.querySelectorAll(
-              'input[type=text], input[type=email], input[type=password], ' +
-              'input[type=url], input[type=tel], input[type=search], ' +
-              'input[type=number], input:not([type])'
-            );
-            if (textInputs.length !== 1) return;
-          }
-
-          if (typeof Turbo === 'undefined') {
-            var ev;
-            if (typeof SubmitEvent === 'function') {
-              ev = new SubmitEvent('submit', { bubbles: true, cancelable: true });
-            } else {
-              ev = new Event('submit', { bubbles: true, cancelable: true });
-            }
-            var allowed = form.dispatchEvent(ev);
-            if (!allowed) return;
-          }
-
-          var formData = new FormData(form);
-          var action = form.getAttribute('action') || window.location.href;
-          try { action = new URL(action, window.location.href).href; } catch (e) {}
-          var method = (form.getAttribute('method') || 'GET').toUpperCase();
-          var enctype = (form.getAttribute('enctype') || 'application/x-www-form-urlencoded').toLowerCase();
-
-          var formEncode = function(fd) {
-            var pairs = [];
-            for (var entry of fd.entries()) {
-              var value = entry[1];
-              if (typeof value === 'string') {
-                value = value.replace(/\\r\\n|\\r|\\n/g, '\\r\\n');
-              }
-              pairs.push(encodeURIComponent(entry[0]).replace(/%20/g, '+') +
-                         '=' +
-                         encodeURIComponent(value).replace(/%20/g, '+'));
-            }
-            return pairs.join('&');
-          };
-
-          var opts = { method: method, credentials: 'same-origin', redirect: 'follow' };
-          if (method === 'GET') {
-            var sep = action.indexOf('?') >= 0 ? '&' : '?';
-            action = action + sep + formEncode(formData);
-          } else if (enctype === 'multipart/form-data') {
-            opts.body = formData;
-          } else {
-            opts.headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
-            opts.body = formEncode(formData);
-          }
-
-          return fetch(action, opts).then(function(r) {
-            return r.text().then(function(html) { return { url: r.url, html: html }; });
-          }).then(function(o) {
-            var doc = new DOMParser().parseFromString(o.html, 'text/html');
-            document.title = (doc.title || '');
-            document.body.innerHTML = doc.body.innerHTML;
-            try { history.replaceState(null, '', o.url); } catch (e) {}
-          });
+          if (btn) { btn.click(); return; }
+          var textInputs = form.querySelectorAll(
+            'input[type=text], input[type=email], input[type=password], ' +
+            'input[type=url], input[type=tel], input[type=search], ' +
+            'input[type=number], input:not([type])'
+          );
+          if (textInputs.length === 1) form.requestSubmit();
         }
       JS
 
@@ -659,8 +549,6 @@ module Capybara
 
       SET_CHECKBOX_JS = <<~JS
         function(value) {
-          // Use `click()` so user-installed click/change handlers fire and
-          // observe a real toggle. No-op if already in the requested state.
           if (this.checked !== value) this.click();
         }
       JS

data/lib/capybara/lightpanda/options.rb

@@ -7,17 +7,24 @@ module Capybara
     class Options
       DEFAULT_TIMEOUT = ENV.fetch("LIGHTPANDA_DEFAULT_TIMEOUT", 15).to_i
       DEFAULT_PROCESS_TIMEOUT = ENV.fetch("LIGHTPANDA_PROCESS_TIMEOUT", 10).to_i
+      # Bounded budget for the WebSocket TCP+Upgrade handshake. Distinct from
+      # `timeout` (per-CDP-command budget) because a handshake either succeeds
+      # in a few hundred ms or won't — bleeding the full command budget into
+      # it just delays the eventual failure.
+      DEFAULT_HANDSHAKE_TIMEOUT = ENV.fetch("LIGHTPANDA_HANDSHAKE_TIMEOUT", 5).to_i
       DEFAULT_HOST = "127.0.0.1"
       DEFAULT_PORT = 9222
       DEFAULT_WINDOW_SIZE = [1024, 768].freeze
 
-      attr_accessor :host, :port, :timeout, :process_timeout, :window_size, :browser_path, :headless, :logger
+      attr_accessor :host, :port, :timeout, :handshake_timeout, :process_timeout,
+                    :window_size, :browser_path, :headless, :logger
       attr_writer :ws_url
 
       def initialize(options = {})
         @host = options.fetch(:host, DEFAULT_HOST)
         @port = options.fetch(:port, DEFAULT_PORT)
         @timeout = options.fetch(:timeout, DEFAULT_TIMEOUT)
+        @handshake_timeout = options.fetch(:handshake_timeout, DEFAULT_HANDSHAKE_TIMEOUT)
         @process_timeout = options.fetch(:process_timeout, DEFAULT_PROCESS_TIMEOUT)
         @window_size = options.fetch(:window_size, DEFAULT_WINDOW_SIZE)
         @browser_path = options[:browser_path]
@@ -39,6 +46,7 @@ module Capybara
           host: host,
           port: port,
           timeout: timeout,
+          handshake_timeout: handshake_timeout,
           process_timeout: process_timeout,
           window_size: window_size,
           browser_path: browser_path,

data/lib/capybara/lightpanda/process.rb

@@ -1,14 +1,32 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module Capybara
   module Lightpanda
     class Process
-      READY_PATTERN = /server running.*address=(\d+\.\d+\.\d+\.\d+:\d+)/
+      READY_PATTERN = /server running.*address\s*=\s*(\d+\.\d+\.\d+\.\d+:\d+)/m
       ADDRESS_IN_USE_PATTERN = /err=AddressInUse/
 
-      # First nightly with Page.addScriptToEvaluateOnNewDocument (PR #1993, merged 2026-03-30).
-      # The gem relies on this for XPath polyfill auto-injection.
-      MINIMUM_NIGHTLY_BUILD = 5267
+      # Floor for the cookie/navigation/redirect/modal/keyboard/css/forms
+      # fixes the gem now relies on: PR #2255 (Network.clearBrowserCookies
+      # empty params + Network.getAllCookies), PR #2257
+      # (window.location.pathname/.search assignment triggers navigation),
+      # PR #2265 (URL fragment inherited across fragment-less redirect),
+      # PR #2261 (LP.handleJavaScriptDialog pre-arm), PR #2283 (Referer on
+      # cross-page nav), PR #2292 (KeyboardEvent.keyCode/charCode), PR #2294
+      # (UA stylesheet display:none for HEAD/SCRIPT/STYLE/NOSCRIPT/TEMPLATE/
+      # TITLE/[type=hidden]), PR #2308 (textarea LF→CRLF), PR #2312 (<input
+      # type=image> click submits form), PR #2315 (:disabled honors fieldset/
+      # optgroup ancestors), PR #2322 (LP dialog defaultText fallback when
+      # promptText is null), PR #2324 (<label> click runs activation behavior
+      # on labeled control), PR #2286 (HTML constraint validation API:
+      # el.validity, validationMessage, checkValidity, reportValidity),
+      # PR #2342 (<summary> click toggles parent <details>.open),
+      # PR #2352 (HTMLInputElement.pattern + patternMismatch via V8 RegExp).
+      # Build 6051 = main HEAD d360fcc0 (2026-05-04); ships in nightly
+      # published 2026-05-05 ~03:30 UTC for all four platforms.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6051")
 
       attr_reader :pid, :ws_url, :version, :nightly_build
 
@@ -76,14 +94,17 @@ module Capybara
       def check_minimum_version(binary_path)
         stdout, = Open3.capture3(binary_path, "version")
         @version = stdout.strip
-        @nightly_build = @version[/nightly\.(\d+)/, 1]&.to_i
+        # 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
 
         raise BinaryError,
               "Lightpanda #{@version} is too old. " \
-              "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
-              "(Page.addScriptToEvaluateOnNewDocument support). " \
+              "This gem requires build >= #{MINIMUM_NIGHTLY_BUILD}. " \
               "Update: curl -sL https://github.com/lightpanda-io/browser/releases/download/nightly/" \
               "#{Binary.platform_binary} -o #{binary_path} && chmod +x #{binary_path}"
       rescue Errno::ENOENT
@@ -204,17 +225,22 @@ module Capybara
         @pid = nil
       end
 
+      # Auto-recover when a previous Lightpanda is still bound to our port.
+      # Best-effort: relies on `lsof` to map port → pid (macOS / most Linux
+      # distros). Where `lsof` isn't on PATH, we surface a clear error rather
+      # than silently failing the retry — the user can free the port manually.
       def kill_process_on_port(port)
         port = port.to_i
         return if port <= 0
 
-        pids = `lsof -ti tcp:#{port} 2>/dev/null`.strip
-        return if pids.empty?
-
-        pids.split("\n").each do |pid_str|
-          pid = pid_str.strip.to_i
-          next if pid <= 0
+        pids = pids_listening_on(port)
+        if pids.nil?
+          raise BinaryError,
+                "Port #{port} is in use and `lsof` is unavailable to identify the holder. " \
+                "Free the port manually or install lsof to enable automatic recovery."
+        end
 
+        pids.each do |pid|
           ::Process.kill("TERM", pid)
         rescue Errno::ESRCH, Errno::EPERM
           nil
@@ -223,6 +249,20 @@ module Capybara
         sleep 0.5
       end
 
+      # Returns an array of PIDs holding the TCP port, [] if none, or nil if
+      # `lsof` itself isn't available on this system.
+      def pids_listening_on(port)
+        stdout, _, status = Open3.capture3("lsof", "-ti", "tcp:#{port}")
+        return [] unless status.success?
+
+        stdout.split("\n").filter_map do |line|
+          pid = line.strip.to_i
+          pid.positive? ? pid : nil
+        end
+      rescue Errno::ENOENT
+        nil
+      end
+
       # Class method so the finalizer proc doesn't capture `self` (which
       # would prevent GC from ever running the finalizer).
       class << self

data/lib/capybara/lightpanda/utils/attempt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    module Utils
+      # Generic retry helper for transient CDP-class errors. Mirrors ferrum's
+      # Utils::Attempt — extracted so callsites don't have to rebuild the
+      # rescue/sleep loop. Default `max` and `wait` match ferrum's
+      # INTERMITTENT_ATTEMPTS / INTERMITTENT_SLEEP so behavior is predictable
+      # across the two ecosystems.
+      module Attempt
+        INTERMITTENT_ATTEMPTS = 6
+        INTERMITTENT_SLEEP = 0.1
+
+        def self.with_retry(errors:, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP)
+          attempts = 0
+          begin
+            yield
+          rescue *Array(errors)
+            attempts += 1
+            raise if attempts >= max
+
+            sleep wait
+            retry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/capybara/lightpanda/xpath_polyfill.rb

@@ -5,6 +5,11 @@ module Capybara
     module XPathPolyfill
       JS_PATH = File.expand_path("javascripts/index.js", __dir__).freeze
       JS = File.read(JS_PATH).freeze
+
+      # Polyfills pour les APIs DOM manquantes du binaire Lightpanda.
+      # Voir UPSTREAM_BUGS.md à la racine du gem.
+      POLYFILLS_PATH = File.expand_path("javascripts/polyfills.js", __dir__).freeze
+      POLYFILLS_JS = File.read(POLYFILLS_PATH).freeze
     end
   end
 end