capybara-lightpanda 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ffb56a5986bbbe2ecfd36662d9e8bfed778046344f013ec028121100f9f87a5
-  data.tar.gz: c9a86b39d5ab675b6e00dfeb22b26a8aaef10b3a4d88e7455ce517452ec1c317
+  metadata.gz: 1cb36e68fb7bcc35abcbae5a3417091eb54444f7b57e161cb44cb6436d243684
+  data.tar.gz: 9eff2c5cd278d16ed8ad55d106dca14dab3597a87c3315c46371b98672a35163
 SHA512:
-  metadata.gz: 883cc590c12520bf5be6c617c106ddf9b5e859384115b768ea2c1b434b4e62ee848354cf171facac43092577aec7ed8aef7dbd43871dc5b5c1415363d26e80e8
-  data.tar.gz: fbd160fa34522967f09275f5f9fd5da225f9f2ec365e233576a495be7e29873a221c1d42edf1cef8d585b7972c0813e6b15cb876f6eb1b6879836248144907ab
+  metadata.gz: 156126b7f57785869aca23b79fe02bc3fe7370cf5b2826999715d5e69794a6b62f8c69bb64601e5e67f935d946e2348274c8ec76d79b674930b239d6b2383677
+  data.tar.gz: c73dab9284d0d8e0091794e2f88674951bafc64af2fa2e87200926a60d7d86767f31cd5114d5348af51013fe3b4846f1066d0bdca886a5a1051432673b76ef52

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.2.2] - 2026-05-06
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6065 (published 2026-05-06). The driver refuses to start against older binaries.
+
+### Fixed
+
+- Turbo Drive `<form>` submissions now intercept correctly. Forms inside a
+  Hotwire / Turbo Drive page no longer crash on submit, and Turbo's `submit`
+  interceptors fire as they should — `click_button`, `find('form').submit`,
+  and Enter-key implicit submission all complete end-to-end.
+- `evaluate_script` and `execute_script` calls with top-level `const` / `let`
+  no longer collide across calls. Consecutive scripts that each declare the
+  same identifier used to fail with `Identifier 'foo' has already been
+  declared`; they're now isolated. `execute_script` also now raises on
+  JavaScript errors instead of silently swallowing them.
+- Same-document fragment-only `<a href="#…">` clicks update the URL hash
+  instead of triggering a real navigation. Tests that drive DOM updates from
+  an anchor click no longer lose pending `setTimeout` callbacks or have form
+  values cleared from under them.
+- `body` returns an empty string rather than crashing during the brief window
+  after `reset_session!` when the new session has a target but no document yet.
+- Stale element references during cross-document navigation now resolve to
+  `nil` internally instead of bubbling a browser error up to your test,
+  letting Capybara's automatic-reload pick a fresh element.
+
+### Internal
+
+- One internal polyfill removed: Lightpanda now matches the spec when a DOM
+  event listener throws (a throwing listener no longer halts the rest of the
+  bubble walk), so the gem doesn't need to compensate. No code change required
+  on your end.
+
+## [0.2.1] - 2026-05-05
+
+### Fixed
+
+- Turbo Frame links now correctly swap the frame instead of falling through to a full-page navigation. Affects any test that clicks a link or submits a form inside a `<turbo-frame>`.
+- Internal driver errors (`NoMethodError`, `NameError`, `Errno::*`) inside `extract_node_object_ids` and `page_ready?` are no longer swallowed and silently downgraded to `[]` / `false` — they surface as real exceptions so bugs are visible.
+
+### Internal
+
+- Local test suite migrated from RSpec to Minitest::Spec. The Capybara shared-spec battery (`spec/features/session_spec.rb`) still runs on RSpec.
+
 ## [0.2.0] - 2026-05-04
 
 Reliability and feature polish as Lightpanda matured. **Update Lightpanda before upgrading**: this release requires a current nightly (the gem will tell you if yours is too old).

data/lib/capybara/lightpanda/binary.rb

@@ -73,7 +73,7 @@ module Capybara
         end
 
         def find
-          env_path = ENV.fetch("LIGHTPANDA_PATH", nil)
+          env_path = ENV.fetch("LIGHTPANDA_BIN", nil)
           return env_path if env_path && File.executable?(env_path)
 
           path_binary = find_in_path

data/lib/capybara/lightpanda/browser.rb

@@ -8,7 +8,7 @@ module Capybara
     class Browser
       extend Forwardable
 
-      attr_reader :options, :process, :client, :target_id, :session_id, :frame_stack
+      attr_reader :options, :process, :client, :target_id, :session_id, :browser_context_id, :frame_stack
 
       delegate %i[on off] => :client
 
@@ -29,6 +29,7 @@ module Capybara
         @client = nil
         @target_id = nil
         @session_id = nil
+        @browser_context_id = nil
         @started = false
         @page_events_enabled = false
         @modal_messages = []
@@ -52,13 +53,25 @@ module Capybara
           @client = Client.new(@process.ws_url, @options)
         end
 
+        create_browser_context
         create_page
 
         @started = true
       end
 
+      # Per-session BrowserContext (Chrome's incognito-profile primitive).
+      # Cookies, storage, and targets created within the context are wiped
+      # when it's disposed — so `reset` is one CDP call instead of an
+      # explicit cookies.clear / storage.clear / close-target dance.
+      # Mirrors ferrum's Contexts model.
+      def create_browser_context
+        result = @client.command("Target.createBrowserContext")
+        @browser_context_id = result["browserContextId"]
+      end
+
       def create_page
-        result = @client.command("Target.createTarget", { url: "about:blank" })
+        result = @client.command("Target.createTarget",
+                                 { url: "about:blank", browserContextId: @browser_context_id }.compact)
         @target_id = result["targetId"]
 
         attach_result = @client.command("Target.attachToTarget", { targetId: @target_id, flatten: true })
@@ -78,6 +91,33 @@ module Capybara
         start
       end
 
+      # Wipe per-session state — cookies, storage, all targets — and start
+      # over with a fresh BrowserContext. Mirrors ferrum's Browser#reset:
+      # one CDP call (`Target.disposeBrowserContext`) does the work that
+      # would otherwise require explicit cookies.clear / storage.clear /
+      # close-target dance, and the browser auto-isolates state for the
+      # new context. Driver#reset! delegates here.
+      #
+      # Side benefit: avoids `Page.navigate("about:blank")` against a
+      # non-blank tab, which doesn't actually replace the document on
+      # current Lightpanda nightly (lightpanda-io/browser#2363). The
+      # context-disposal path sidesteps that bug entirely.
+      def reset
+        dispose_browser_context
+        @client.clear_subscriptions
+        @page_events_enabled = false
+        @modal_handler_installed = false
+        @modal_messages.clear
+        @frame_stack.clear
+        # Network#reset, not #clear: disposing the BrowserContext also
+        # destroyed the Network domain and its subscriptions, so we must
+        # flip @enabled back to false — otherwise the next #enable
+        # short-circuits and traffic tracking is silently dead.
+        @network&.reset
+        create_browser_context
+        create_page
+      end
+
       # Recover after a WebSocket disconnect or process crash during navigation.
       # Restarts the process if it died, then creates a fresh client and page.
       def reconnect
@@ -88,6 +128,9 @@ module Capybara
         raise DeadBrowserError, "Cannot reconnect: no WebSocket URL" unless ws_url
 
         @client = Client.new(ws_url, @options)
+        # Process may have died; the old browserContextId is gone with it.
+        @browser_context_id = nil
+        create_browser_context
         create_page
         @page_events_enabled = false
       end
@@ -106,6 +149,9 @@ module Capybara
         @client = nil
         @process = nil
         @started = false
+        @browser_context_id = nil
+        @target_id = nil
+        @session_id = nil
         @modal_handler_installed = false
         @frame_stack.clear
       end
@@ -192,7 +238,11 @@ module Capybara
       end
 
       def body
-        evaluate("document.documentElement.outerHTML")
+        # Guard against the brief window after a fresh BrowserContext / target
+        # is created where the V8 context exists but `document.documentElement`
+        # is still null. Hit by Capybara's `#reset_session! resets page body`
+        # spec since the 0.2.0 Ferrum-style reset rewrite.
+        evaluate("(document.documentElement && document.documentElement.outerHTML) || ''")
       end
       alias html body
 
@@ -201,10 +251,29 @@ module Capybara
       # and dispatch via Runtime.callFunctionOn so `arguments[i]` is bound.
       # Both paths use `returnByValue: false` and unwrap so DOM-node returns
       # come back as `{ "__lightpanda_node__" => ... }` for the Driver to wrap.
+      #
+      # Even the no-args path wraps the expression in an IIFE to isolate
+      # top-level `const`/`let` declarations. Upstream Lightpanda retains
+      # those bindings across `Runtime.evaluate` calls (V8 starts each call
+      # with fresh lexical scope per spec), so a second `const sel = ...`
+      # raises `SyntaxError: Identifier 'sel' has already been declared`.
+      # Wrapping pushes the declarations into a function scope that gets
+      # discarded when the IIFE returns.
+      #
+      # Use direct `eval` inside the IIFE so the user's text can be a bare
+      # expression (`'foo'`), a `throw` statement, OR a multi-statement
+      # script with `const`/`let`. `eval`'s completion-value semantics
+      # return the last expression's value in all cases. A naive
+      # `return EXPR;` wrap would syntax-error on `throw …` and on
+      # multi-statement scripts.
       def evaluate(expression, *args)
         if args.empty?
-          response = page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: true)
-          raise JavaScriptError, response if response["exceptionDetails"]
+          wrapped = "(function(){return eval(#{expression.to_json})})()"
+          response = page_command("Runtime.evaluate", expression: wrapped, returnByValue: false, awaitPromise: true)
+          if response["exceptionDetails"]
+            debug_js_failure("evaluate", expression, response)
+            raise JavaScriptError, response
+          end
 
           return unwrap_call_result(response["result"])
         end
@@ -214,9 +283,20 @@ module Capybara
       end
 
       # Execute JS without returning a value.
+      #
+      # Like `evaluate`, the no-args path wraps in an IIFE — same upstream
+      # `const`/`let` leak. Also raises on JS exceptions so silent
+      # failures don't mask test bugs (the previous fast path swallowed them
+      # because `awaitPromise: false` was checked but `exceptionDetails` was
+      # not).
       def execute(expression, *args)
         if args.empty?
-          page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: false)
+          wrapped = "(function(){#{expression}})()"
+          response = page_command("Runtime.evaluate", expression: wrapped, returnByValue: false, awaitPromise: false)
+          if response["exceptionDetails"]
+            debug_js_failure("execute", expression, response)
+            raise JavaScriptError, response
+          end
           return nil
         end
 
@@ -225,6 +305,15 @@ module Capybara
         nil
       end
 
+      # When LIGHTPANDA_DEBUG=1 is set, log the JS expression and full CDP
+      # response for every JsException to STDERR. Invaluable for isolating
+      # which exact JS triggers an upstream Lightpanda bug.
+      def debug_js_failure(site, expression, response)
+        return unless ENV["LIGHTPANDA_DEBUG"]
+
+        warn "[lightpanda:#{site}] expression:\n#{expression}\n[lightpanda:#{site}] response:\n#{response.inspect}\n"
+      end
+
       # Evaluate async JS with a callback. The user's script receives
       # the callback as its last argument (`arguments[arguments.length - 1]`),
       # matching Capybara's evaluate_async_script contract.
@@ -249,7 +338,10 @@ module Capybara
       # Evaluate JS and return a RemoteObject reference (for DOM nodes, arrays).
       def evaluate_with_ref(expression)
         response = page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: true)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("evaluate_with_ref", expression, response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -269,7 +361,10 @@ module Capybara
         params[:arguments] = args.map { |a| serialize_argument(a) } unless args.empty?
 
         response = page_command("Runtime.callFunctionOn", **params)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("call_function_on", function_declaration, response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -304,6 +399,8 @@ module Capybara
       def find_within(remote_object_id, method, selector)
         result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, return_by_value: false)
         extract_node_object_ids(result)
+      rescue JavaScriptError => e
+        raise_invalid_selector(e, method, selector)
       end
 
       # objectId of document.activeElement, or nil if none/document detached.
@@ -528,20 +625,32 @@ module Capybara
         raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
       end
 
+      # Sentinel string thrown from FIND_*_JS when querySelectorAll rejects a
+      # malformed selector, so the Ruby side can convert JavaScriptError into
+      # Capybara::Lightpanda::InvalidSelector. Cuprite uses a JS subclass for
+      # the same purpose; a plain prefixed string keeps our inline JS simple.
+      INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
+
       # JS function for finding elements within a node.
-      # Works in any execution context (top frame or iframe).
-      FIND_WITHIN_JS = <<~JS
+      # Works in any execution context (top frame or iframe). Any throw from
+      # querySelectorAll means the selector is malformed (the spec only allows
+      # SYNTAX_ERR DOMException; Lightpanda's V8 currently throws a generic
+      # Error with messages like "InvalidClassSelector"). Re-throw with the
+      # marker prefix so Ruby converts to InvalidSelector regardless.
+      FIND_WITHIN_JS = <<~JS.freeze
         function(method, selector) {
           if (method === 'xpath') {
             if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, this);
             return [];
           }
-          try { return Array.from(this.querySelectorAll(selector)); } catch(e) { return []; }
+          try { return Array.from(this.querySelectorAll(selector)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
         }
       JS
+      private_constant :FIND_WITHIN_JS
 
       # JS function for finding elements in an iframe's contentDocument.
-      FIND_IN_FRAME_JS = <<~JS
+      FIND_IN_FRAME_JS = <<~JS.freeze
         function(method, selector) {
           var doc;
           try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
@@ -550,9 +659,11 @@ module Capybara
             if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, doc);
             return [];
           }
-          try { return Array.from(doc.querySelectorAll(selector)); } catch(e) { return []; }
+          try { return Array.from(doc.querySelectorAll(selector)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
         }
       JS
+      private_constant :FIND_IN_FRAME_JS
 
       def find_in_document(method, selector)
         with_default_context_wait do
@@ -563,12 +674,18 @@ module Capybara
           js = if method == "xpath"
                  "(typeof _lightpanda !== 'undefined') ? _lightpanda.xpathFind(#{selector_literal}, document) : []"
                else
-                 "(function() { try { return Array.from(document.querySelectorAll(#{selector_literal})); } " \
-                   "catch(e) { return []; } })()"
+                 <<~CSS_FIND
+                   (function() {
+                     try { return Array.from(document.querySelectorAll(#{selector_literal})); }
+                     catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + #{selector_literal}); }
+                   })()
+                 CSS_FIND
                end
           result = evaluate_with_ref(js)
           extract_node_object_ids(result)
         end
+      rescue JavaScriptError => e
+        raise_invalid_selector(e, method, selector)
       end
 
       def find_in_frame(method, selector)
@@ -576,6 +693,16 @@ module Capybara
         result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
                                   return_by_value: false)
         extract_node_object_ids(result)
+      rescue JavaScriptError => e
+        raise_invalid_selector(e, method, selector)
+      end
+
+      def raise_invalid_selector(js_error, method, selector)
+        if js_error.message.include?(INVALID_SELECTOR_MARKER)
+          raise InvalidSelector.new("Invalid #{method} selector: #{selector.inspect}", method, selector)
+        end
+
+        raise js_error
       end
 
       # Extract individual node objectIds from a remote array reference.
@@ -592,12 +719,13 @@ module Capybara
 
         release_object(result["objectId"])
         ids
-      rescue StandardError
+      rescue Error
         []
       end
 
       def register_auto_scripts
         page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::JS)
+        page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::POLYFILLS_JS)
       end
 
       def subscribe_to_console_logs
@@ -716,7 +844,10 @@ module Capybara
       end
 
       def handle_evaluate_response(response)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("handle_evaluate_response", "(unknown — already-issued call)", response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -738,7 +869,10 @@ module Capybara
           arguments: args.map { |a| serialize_argument(a) },
         }
         response = page_command("Runtime.callFunctionOn", **params)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("call_with_args", function_declaration, response)
+          raise JavaScriptError, response
+        end
 
         return_by_value ? handle_evaluate_response(response) : unwrap_call_result(response["result"])
       end
@@ -839,6 +973,21 @@ module Capybara
         nil
       end
 
+      def dispose_browser_context
+        return unless @browser_context_id
+
+        begin
+          @client.command("Target.disposeBrowserContext", { browserContextId: @browser_context_id })
+        rescue StandardError
+          # Context may already be disposed or the WS may be down; we
+          # recreate either way.
+        ensure
+          @browser_context_id = nil
+          @target_id = nil
+          @session_id = nil
+        end
+      end
+
       def restart_process_if_dead
         return unless @process && !@process.alive?
 
@@ -927,7 +1076,7 @@ module Capybara
 
         url_changed = starting_url.nil? || state["u"] != starting_url
         url_changed && %w[complete interactive].include?(state["r"])
-      rescue StandardError
+      rescue Error
         false
       end
 

data/lib/capybara/lightpanda/client/subscriber.rb

@@ -4,9 +4,18 @@ module Capybara
   module Lightpanda
     class Client
       class Subscriber
-        def initialize
+        # Default error sink: write a one-line warning so a misbehaving handler
+        # is visible without crashing the CDP message thread. Tests can inject
+        # a custom proc via `on_error:` to capture failures.
+        DEFAULT_ON_ERROR = lambda do |event, error|
+          warn("[capybara-lightpanda] subscriber callback for #{event.inspect} raised " \
+               "#{error.class}: #{error.message}")
+        end
+
+        def initialize(on_error: DEFAULT_ON_ERROR)
           @subscriptions = Hash.new { |h, k| h[k] = [] }
           @mutex = Mutex.new
+          @on_error = on_error
         end
 
         def subscribe(event, &block)
@@ -25,10 +34,28 @@ module Capybara
           end
         end
 
+        # Run every callback registered for `event`. Exceptions in one
+        # callback must not stop the others or propagate out — the message
+        # thread sets `abort_on_exception = true`, so an unhandled raise
+        # would tear down the entire CDP connection.
+        #
+        # Two layers of rescue:
+        #   1. The callback itself may raise — route to @on_error.
+        #   2. @on_error itself may raise (custom hook, broken stderr) —
+        #      swallow at the last level so the dispatch loop survives.
         def dispatch(event, params)
           callbacks = @mutex.synchronize { @subscriptions[event].dup }
 
-          callbacks.each { |callback| callback.call(params) }
+          callbacks.each do |callback|
+            callback.call(params)
+          rescue StandardError => e
+            begin
+              @on_error.call(event, e)
+            rescue StandardError
+              # The error sink failed — nothing to do but keep going. We
+              # cannot log here without re-entering the broken path.
+            end
+          end
         end
 
         def subscribed?(event)

data/lib/capybara/lightpanda/client.rb

@@ -60,6 +60,13 @@ module Capybara
         @subscriber.unsubscribe(event, block)
       end
 
+      # Drop all event subscriptions without closing the WebSocket. Used by
+      # Browser#recreate_page so a fresh target's event handlers don't pile
+      # up on top of the previous target's subscriptions.
+      def clear_subscriptions
+        @subscriber.clear
+      end
+
       def close
         @ws&.close
         @message_thread&.join(1) || @message_thread&.kill

data/lib/capybara/lightpanda/driver.rb

@@ -196,12 +196,12 @@ module Capybara
 
       # -- Lifecycle --
 
+      # Thin Cuprite-style wrapper. The interesting work — disposing the
+      # BrowserContext (cookies, storage, all targets) and starting a fresh
+      # one — happens in Browser#reset.
       def reset!
-        browser.clear_frames
-        browser.reset_modals
-        browser.cookies.clear
-        browser.network.clear
-        browser.go_to("about:blank")
+        browser.reset
+        @started = false
       rescue StandardError
         @browser&.quit
         @browser = nil

data/lib/capybara/lightpanda/errors.rb

@@ -46,11 +46,36 @@ module Capybara
       attr_reader :class_name, :stack_trace
 
       def initialize(response)
-        @class_name = response.dig("exceptionDetails", "exception", "className")
-        @stack_trace = response.dig("exceptionDetails", "stackTrace")
-        message = response.dig("exceptionDetails", "exception", "description") ||
-                  response.dig("exceptionDetails", "text")
-        super(message)
+        details = response["exceptionDetails"] || {}
+        exception = details["exception"] || {}
+        @class_name = exception["className"]
+        @stack_trace = details["stackTrace"]
+        super(build_message(details, exception))
+      end
+
+      private
+
+      def build_message(details, exception)
+        base = exception["description"] || details["text"] || "JsException"
+        parts = [base]
+        parts << "(#{@class_name})" if @class_name && !base.include?(@class_name)
+        if (val = exception["value"])
+          parts << "value=#{val.inspect}"
+        end
+        if @stack_trace && (frames = @stack_trace["callFrames"])
+          parts << format_stack(frames)
+        end
+        parts.join(" | ")
+      end
+
+      def format_stack(frames)
+        formatted = frames.first(5).map { |f| format_frame(f) }
+        "stack:\n  #{formatted.join("\n  ")}"
+      end
+
+      def format_frame(frame)
+        name = frame["functionName"].to_s.empty? ? "<anon>" : frame["functionName"]
+        "#{name} @ #{frame['url']}:#{frame['lineNumber']}:#{frame['columnNumber']}"
       end
     end
 

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

@@ -0,0 +1,212 @@
+// Polyfills compensant des limitations du binaire Lightpanda.
+// Chaque section est gardée par un test de feature : dès qu'upstream implémente
+// l'API native, le polyfill devient un no-op et peut être retiré.
+// Voir UPSTREAM_BUGS.md à la racine du gem pour les repros et liens d'issues.
+(function () {
+  "use strict";
+
+  // ── Bug #7 — HTMLFormElement / HTMLButtonElement / HTMLInputElement form-* IDL gaps ──
+  // Lightpanda doesn't expose `form.enctype`, `form.method`, `form.action`,
+  // `form.target`, nor the submitter-side `formEnctype` / `formMethod` /
+  // `formAction` / `formTarget` overrides. Per WHATWG HTML these must always
+  // return a string (with the spec's missing-value default) so consumers can
+  // call `.toLowerCase()` etc. directly. Turbo's `FormSubmission` constructor
+  // does exactly that and crashes with `Cannot read properties of undefined
+  // (reading 'toLowerCase')` when it touches enctype.
+  //
+  // Polyfill strategy: only define the IDL getter when it's missing on the
+  // prototype, so a future Lightpanda nightly that adds native support wins
+  // automatically. Each getter falls back to the underlying attribute, with
+  // the spec's default if the attribute is absent. For submitter overrides
+  // (formEnctype, formMethod, etc.) we return the empty string when the
+  // override attribute is unset — Turbo and Hotwire all use the
+  // `submitter.formX || form.X` idiom, which resolves correctly when the
+  // submitter side returns "".
+  (function patchFormIDL() {
+    var ENCTYPE_VALUES = ["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"];
+    function normEnctype(v) {
+      if (!v) return "application/x-www-form-urlencoded";
+      v = String(v).toLowerCase();
+      return ENCTYPE_VALUES.indexOf(v) >= 0 ? v : "application/x-www-form-urlencoded";
+    }
+    function normMethod(v) {
+      if (!v) return "get";
+      v = String(v).toLowerCase();
+      return (v === "post" || v === "dialog") ? v : "get";
+    }
+    function defineIfMissing(proto, name, getter) {
+      if (!proto || name in proto) return;
+      try { Object.defineProperty(proto, name, { configurable: true, enumerable: true, get: getter }); } catch (_) {}
+    }
+    if (typeof HTMLFormElement !== "undefined") {
+      var fp = HTMLFormElement.prototype;
+      defineIfMissing(fp, "enctype", function () { return normEnctype(this.getAttribute("enctype")); });
+      defineIfMissing(fp, "method",  function () { return normMethod(this.getAttribute("method")); });
+      defineIfMissing(fp, "action",  function () {
+        var a = this.getAttribute("action");
+        if (a == null || a === "") return (this.ownerDocument && this.ownerDocument.URL) || "";
+        try { return new URL(a, (this.ownerDocument && this.ownerDocument.URL) || undefined).href; }
+        catch (_) { return a; }
+      });
+      defineIfMissing(fp, "target",  function () { return this.getAttribute("target") || ""; });
+    }
+    function patchSubmitter(Ctor) {
+      if (typeof Ctor === "undefined") return;
+      var p = Ctor.prototype;
+      // Empty string is the spec's missing-value default for the submitter-side
+      // IDL attrs — keep Turbo's `submitter.formX || form.X` idiom flowing
+      // through to the form's value.
+      defineIfMissing(p, "formEnctype", function () {
+        var v = this.getAttribute("formenctype");
+        return v == null ? "" : normEnctype(v);
+      });
+      defineIfMissing(p, "formMethod", function () {
+        var v = this.getAttribute("formmethod");
+        return v == null ? "" : normMethod(v);
+      });
+      defineIfMissing(p, "formAction", function () {
+        var a = this.getAttribute("formaction");
+        if (a == null || a === "") return "";
+        try { return new URL(a, (this.ownerDocument && this.ownerDocument.URL) || undefined).href; }
+        catch (_) { return a; }
+      });
+      defineIfMissing(p, "formTarget", function () { return this.getAttribute("formtarget") || ""; });
+      defineIfMissing(p, "formNoValidate", function () { return this.hasAttribute("formnovalidate"); });
+    }
+    patchSubmitter(typeof HTMLButtonElement !== "undefined" ? HTMLButtonElement : null);
+    patchSubmitter(typeof HTMLInputElement  !== "undefined" ? HTMLInputElement  : null);
+  })();
+
+  // ── Bug #4 — HTMLDialogElement.{showModal, show, close} non implémentés ──
+  // https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
+  if (typeof HTMLDialogElement !== "undefined") {
+    var dproto = HTMLDialogElement.prototype;
+    if (typeof dproto.showModal !== "function") {
+      dproto.showModal = function () {
+        if (this.hasAttribute("open")) {
+          throw new (window.DOMException || Error)(
+            "The element already has an 'open' attribute, and therefore cannot be opened modally.",
+            "InvalidStateError"
+          );
+        }
+        this.setAttribute("open", "");
+      };
+    }
+    if (typeof dproto.show !== "function") {
+      dproto.show = function () {
+        if (!this.hasAttribute("open")) this.setAttribute("open", "");
+      };
+    }
+    if (typeof dproto.close !== "function") {
+      dproto.close = function (returnValue) {
+        if (!this.hasAttribute("open")) return;
+        this.removeAttribute("open");
+        if (returnValue !== undefined) this.returnValue = String(returnValue);
+        this.dispatchEvent(new Event("close"));
+      };
+    }
+  }
+
+  // ── Bug #8 (added 2026-05-05) — sync remove + re-add lost across dispatch phases ──
+  // WHATWG DOM specifies that each phase of a dispatch snapshots `currentTarget`'s
+  // listener list AT THAT PHASE. Listeners removed and re-added during the capture
+  // phase correctly appear in the bubble-phase snapshot in Chrome/Cuprite. Lightpanda
+  // takes the snapshot once at dispatch start, so a remove+add during capture loses
+  // the listener for the in-flight bubble. This breaks Turbo's `FormSubmitObserver`
+  // pattern, where `submitCaptured` does `remove+add` on its own `submitBubbled` to
+  // ensure that handler runs LAST in bubble — under Lightpanda, `submitBubbled` is
+  // dropped entirely and Turbo never intercepts form submissions.
+  //
+  // Native form submission via `requestSubmit()` doesn't route through JS-exposed
+  // `dispatchEvent`, so we can't detect "in-flight dispatch" by patching that. The
+  // workaround instead targets the remove+add idiom directly: defer every
+  // `removeEventListener` to a microtask. When `addEventListener` runs in the same
+  // synchronous turn with the SAME (target, type, fn, capture), we cancel the
+  // pending remove — the listener was never actually unregistered, so the in-flight
+  // bubble snapshot still contains it. Genuine removes (no matching add follows)
+  // happen at end-of-tick, indistinguishable from the unpatched behavior modulo
+  // tick boundary.
+  //
+  // Scope: only capture-phase `submit` listeners, the exact tuple Turbo Drive
+  // uses. This avoids changing observable DOM semantics for arbitrary
+  // remove/dispatch sequences elsewhere on the page — synchronous remove +
+  // dispatch outside this narrow tuple still fires the native `removeEventListener`
+  // path immediately.
+  //
+  // Trade-offs (within the narrowed scope):
+  //   • Code that removes a capture-phase submit listener and then reads
+  //     listener state synchronously before the microtask flush will see it
+  //     as still-attached. No known framework does this on `submit`.
+  //   • If something removes capture-phase submit listener X then adds Y of
+  //     the same type/capture before the flush, the add happens immediately
+  //     but the deferred remove fires after, removing X *after* Y is
+  //     registered. Y persists, X is gone. Same end state as without the
+  //     polyfill, just reordered in time.
+  (function patchListenerLifecycle() {
+    if (!window.EventTarget || !EventTarget.prototype.addEventListener) return;
+    if (typeof Promise === "undefined") return; // need microtasks
+    var origAdd    = EventTarget.prototype.addEventListener;
+    var origRemove = EventTarget.prototype.removeEventListener;
+
+    function captureFlag(opts) {
+      return opts === true || (opts && typeof opts === "object" && opts.capture === true);
+    }
+
+    function inScope(type, capture) {
+      return type === "submit" && capture === true;
+    }
+
+    var pending = [];      // [{ target, type, fn, capture, cancelled }]
+    var flushScheduled = false;
+
+    function scheduleFlush() {
+      if (flushScheduled) return;
+      flushScheduled = true;
+      Promise.resolve().then(function () {
+        flushScheduled = false;
+        var queue = pending;
+        pending = [];
+        for (var i = 0; i < queue.length; i++) {
+          var r = queue[i];
+          if (r.cancelled) continue;
+          try {
+            origRemove.call(r.target, r.type, r.fn, r.capture);
+          } catch (_) {}
+        }
+      });
+    }
+
+    EventTarget.prototype.removeEventListener = function (type, fn, opts) {
+      var capture = captureFlag(opts);
+      if (!fn || !inScope(type, capture)) return origRemove.call(this, type, fn, opts);
+      pending.push({
+        target:    this,
+        type:      type,
+        fn:        fn,
+        capture:   capture,
+        cancelled: false,
+      });
+      scheduleFlush();
+    };
+
+    EventTarget.prototype.addEventListener = function (type, fn, opts) {
+      if (!fn) return origAdd.call(this, type, fn, opts);
+      var capture = captureFlag(opts);
+      if (inScope(type, capture)) {
+        // Cancel a pending remove for the same tuple (LIFO so the most recent
+        // pending remove wins for the remove-then-add idiom). Always call
+        // native add too: addEventListener is idempotent per DOM spec, and
+        // skipping risks losing the listener on a later unmatched remove.
+        for (var i = pending.length - 1; i >= 0; i--) {
+          var r = pending[i];
+          if (r.cancelled) continue;
+          if (r.target === this && r.type === type && r.fn === fn && r.capture === capture) {
+            r.cancelled = true;
+            break;
+          }
+        }
+      }
+      return origAdd.call(this, type, fn, opts);
+    };
+  })();
+})();

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"
@@ -229,6 +237,8 @@ module Capybara
 
       def backend_node_id
         @backend_node_id ||= driver.browser.backend_node_id(@remote_object_id)
+      rescue BrowserError
+        nil
       end
 
       private
@@ -355,7 +365,93 @@ module Capybara
         end
       end
 
-      CLICK_JS = "function() { this.click() }"
+      # 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 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 EventCtor = (typeof MouseEvent !== 'undefined') ? MouseEvent : Event;
+          var clickEvt = new EventCtor('click', { bubbles: true, cancelable: true });
+          var notCancelled = this.dispatchEvent(clickEvt);
+          if (!notCancelled || clickEvt.defaultPrevented) return;
+          var tag = this.tagName;
+          var type = (this.type || '').toLowerCase();
+          var isSubmitButton =
+            (tag === 'BUTTON' && (type === 'submit' || type === '')) ||
+            (tag === 'INPUT' && (type === 'submit' || type === 'image'));
+          if (isSubmitButton && this.form) {
+            // Lightpanda raises a JsException from requestSubmit when a
+            // bubble-phase listener (e.g. Turbo's submitBubbled) calls
+            // preventDefault + stopImmediatePropagation on the SubmitEvent.
+            // Per HTML spec a cancelled submission should be a silent no-op.
+            // Log unexpected errors via console.warn so they remain
+            // diagnosable (LIGHTPANDA_DEBUG surfaces console output) instead
+            // of silently swallowing future regressions.
+            try {
+              this.form.requestSubmit(this);
+            } catch (e) {
+              try { console.warn('[capybara-lightpanda] requestSubmit threw:', e && e.message ? e.message : e); } catch (_) {}
+            }
+          } else if (tag === 'A' && this.href && this.target !== '_blank') {
+            // Same-document fragment-only navigation: just update hash (or do
+            // nothing if identical). Mirrors Chrome — assigning location.href
+            // to a same-document URL on Lightpanda triggers a real navigation
+            // tick that cancels pending setTimeout callbacks and clears form
+            // values, which breaks any test driving DOM updates from a click
+            // handler on `<a href="#...">`.
+            var dest = new URL(this.href, document.baseURI);
+            var here = new URL(window.location.href);
+            if (dest.origin === here.origin && dest.pathname === here.pathname &&
+                dest.search === here.search) {
+              if (dest.hash !== here.hash) {
+                window.location.hash = dest.hash;
+              }
+            } else {
+              window.location.href = this.href;
+            }
+          }
+        }
+      JS
+
+      # 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 {
+            event = new Event(name, init);
+          }
+          this.dispatchEvent(event);
+        }
+      JS
 
       VISIBLE_JS = "function() { return _lightpanda.isVisible(this); }"
 
@@ -382,7 +478,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
 
@@ -464,8 +567,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/process.rb

@@ -8,7 +8,7 @@ module Capybara
       READY_PATTERN = /server running.*address\s*=\s*(\d+\.\d+\.\d+\.\d+:\d+)/m
       ADDRESS_IN_USE_PATTERN = /err=AddressInUse/
 
-      # Floor for the cookie/navigation/redirect/modal/keyboard/css/forms
+      # Floor for the cookie/navigation/redirect/modal/keyboard/css/forms/dispatch
       # fixes the gem now relies on: PR #2255 (Network.clearBrowserCookies
       # empty params + Network.getAllCookies), PR #2257
       # (window.location.pathname/.search assignment triggers navigation),
@@ -22,10 +22,13 @@ module Capybara
       # 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). Build
-      # 6005 = main HEAD 0420802f (2026-05-04); ships in nightly published
-      # 2026-05-04 03:44 UTC for all four platforms.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6005")
+      # PR #2342 (<summary> click toggles parent <details>.open),
+      # PR #2352 (HTMLInputElement.pattern + patternMismatch via V8 RegExp),
+      # PR #2368 (events: report listener exceptions instead of halting
+      # dispatch — lets us drop the polyfills.js patchDispatch IIFE).
+      # Build 6065 = main HEAD 61364437 (2026-05-06, PR #2368 merge);
+      # ships in nightly published 2026-05-06 ~03:30 UTC for all four platforms.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6065")
 
       attr_reader :pid, :ws_url, :version, :nightly_build
 

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.2.0"
+    VERSION = "0.2.2"
   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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Navid Emad
@@ -81,6 +81,7 @@ files:
 - lib/capybara/lightpanda/errors.rb
 - lib/capybara/lightpanda/frame.rb
 - lib/capybara/lightpanda/javascripts/index.js
+- lib/capybara/lightpanda/javascripts/polyfills.js
 - lib/capybara/lightpanda/keyboard.rb
 - lib/capybara/lightpanda/logger.rb
 - lib/capybara/lightpanda/network.rb