capybara-lightpanda 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2515195575d1146f7cd14f479801360770c65d39d84c2bdc58be987e503bda88
-  data.tar.gz: ab94aba998ccafb870e109504e7f33dd22a35bcd2ba79750cfd2bb79226feaf1
+  metadata.gz: 759abeb96b5d6898d9458d2e81af39b97d155766cfd2c80fa1ed363409a6aff6
+  data.tar.gz: 66d54d836501ab8ec7d3cc23ffc389f58777c938a19490f9dc81a076819b4489
 SHA512:
-  metadata.gz: 3eadd479f7c543354a89c3f69a1be6ee94be6067b52171766c3da1b3c9b091a9e404c987e9af11c5230c89e8df319013822748b0bd6ba0e7e56ebd143f3e7689
-  data.tar.gz: fec1bbad25a59b177b6ac117e82bf65eef995196f233aa96742f71b2def90133132b913c0591bf40f2ca554d09cb4e6b26cbb132a0f3ae5e7ab811efa4504914
+  metadata.gz: ffdc46e2b18c6ce822fb7765cc668bfda6594e1ce27f9ad88b29e4d9a34f6882b80aad54fcb0581d460e68b3fbcaaaa853017f825295b1a8758a244da520d12d
+  data.tar.gz: 6ae51661f2a7108ec85bebf773965dd792f74d04b80cdff7c5992b41be5c32f15b3d7e08d97a64212a64a812be4ebe811f222ad6fa91866888d1f6e50a805b71

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.14.0] - 2026-10-11
+
+### Fixed
+
+- **`evaluate_script` returns `Capybara::Lightpanda::CyclicObject` for a result that references itself, as Cuprite returns `Ferrum::CyclicObject`.** A self-referencing object used to raise `BrowserError: Object reference chain is too long`. So did `evaluate_script("window")` on recent Lightpanda nightlies, and on older builds it came back as a broken element.
+- **`Cookies#load` keeps restoring a file when one cookie is malformed.** Recent Lightpanda nightlies reject a cookie with a `;` or control character in its name or value, as Chrome does, where older builds stored it. A file saved from an older build could hold such a cookie, and `load` stopped at it with a `BrowserError`. It now skips that cookie and names it in its warning, like any other cookie the browser refuses. `Cookies#set` still raises for it.
+- **Clicking a `javascript:` link no longer breaks the page on recent Lightpanda nightlies.** On nightly 10261 and later, clicking `<a href="javascript:void(0)">` (select2, Bootstrap toggles, older jQuery code) left the page unusable: every later `find` or `evaluate_script` raised `NoExecutionContextError` until the next `visit`. The link's code still runs, once, and the page stays.
+- **A click waits for the page it navigates to, even when the server is slow.** `click` used to return after about 50 ms, before a link, `window.location` assignment or form submission had loaded the next page whenever the server took longer than that (a slow action, a redirect). The very next `current_url` or `assert_current_path(..., wait: 0)` then read the page being left. The click now waits for the new page, as in Cuprite. Clicks that don't navigate are as fast as before, and so are `pushState` and anchor clicks. A navigation that fails, such as a refused connection, doesn't make the click wait for the timeout. `send_keys` waits the same way when Enter submits a form.
+- **`go_back` and `go_forward` keep the page when the history entry comes from `pushState`.** They used to reload the document from the server, so the page's JavaScript state was lost and no `popstate` event fired: a "browser back button" test on a step-by-step page could not pass. They now behave like the browser's buttons: the page stays, `popstate` fires and `current_url` is up to date when the call returns. Going back or forward to another page still loads it, and the call waits for it. Lightpanda limit: on Lightpanda 1.0.0 this only applies when the two entries differ by their `#fragment`. When `pushState` changed the path (Turbo Drive, client-side routers), 1.0.0 still reloads the page ([lightpanda-io/browser#3726](https://github.com/lightpanda-io/browser/issues/3726)); nightly builds from 10239 keep it.
+- **Clicking a link inside an iframe navigates the iframe, not the whole page.** Inside `within_frame`, `click_link` used to replace the whole page with the link's target, and a `#fragment` link in a frame did the same. Links with `target="_top"` or `target="_parent"` still leave the frame, as in Chrome.
+- **Scripts run inside the frame within `within_frame`.** `execute_script`, `evaluate_script` and `evaluate_async_script` used to run against the page around the frame, so `document` and `window` were the top page's. They now see the frame's document, as in Chrome.
+- **An element found in an iframe goes stale when that iframe navigates.** It used to keep answering from the old document: empty text, not visible, clicks that did nothing. Capybara never found it again. It is now treated as obsolete, as in Chrome, and Capybara's automatic reload finds the element in the new page.
+- **`select` works in a form that has a field named `disabled`.** On recent Lightpanda nightlies, an `<input name="disabled">` made every option in its form read as disabled, so `select` silently did nothing.
+
+## [0.13.0] - 2026-10-03
+
+> **Update Lightpanda before upgrading.** This release requires Lightpanda **1.0.0** or a nightly build ≥ 9994. The driver refuses anything older and names the version it found. Tagged releases work again: pin `1.0.0` for a reproducible browser.
+
+### Changed
+
+- **Cross-origin requests follow CORS, as in Chrome.** Lightpanda 1.0.0 enforces CORS by default, and the driver doesn't turn it off, so a `fetch` or XHR your app sends from `127.0.0.1` to `localhost` (or to another port) is blocked there just as Chrome would block it. Suites already green on Cuprite or Selenium are unaffected. A blocked request is listed in `network.traffic` with an `:error` and no response, and it no longer stalls `wait_for_network_idle` (see Fixed).
+- **`Cookies#set` returns whether the browser accepted the cookie.** Lightpanda now refuses `SameSite=None` without `Secure`. `set` returns `false` in that case instead of dropping the cookie silently. `Cookies#load` repairs cookie files saved by older versions, which marked every cookie `SameSite=None`, and warns about any cookie it still can't restore.
+
+### Fixed
+
+- **Clicking a field focuses it again.** On current Lightpanda builds, `click` followed by `send_keys` sent the keys to the page body instead of the clicked field. Clicking a field, a label or a contenteditable region now focuses it, and clicking empty space blurs the focused element, as in Chrome. Capybara's `active_element` specs now pass.
+- **`send_keys` appends to a field's existing value.** On a field that was pre-filled and not yet focused, `send_keys("x")` produced `"xfoo"` instead of `"foox"`. Typing now starts at the end of the value, as in chromedriver. If you need to type at a specific position, focus the field and place the caret yourself first.
+- **Backspace, Delete, Tab, Escape and the arrow keys reach the page.** Previously only keys that type a character were delivered, so these keys did nothing. They now edit fields, move the caret and extend the selection with Shift. A `beforeinput` handler can cancel an edit, which input-mask libraries rely on.
+- **Ctrl/Cmd shortcuts no longer type a character.** `send_keys([:ctrl, "a"])` used to insert a stray `a`. Your shortcut handlers still receive the key.
+- **`select` never picks a disabled option, and picks the right one when values repeat.** When several options shared the same value, the first one was always selected.
+- **Failed requests no longer stall `wait_for_network_idle`.** A request that failed without a response (blocked by CORS, refused connection) stayed pending until the timeout expired.
+- **`console_logs` shows objects.** `console.log({a: 1})`, arrays and DOM elements used to appear as empty text. They now appear as a short description.
+- **A browser crash no longer takes your test process down with it.** If the connection died unexpectedly, the error could be raised somewhere unrelated in your test, or abort a server before its cleanup ran. Commands now fail cleanly with `DeadBrowserError`, waiting commands are released immediately, and each crashed browser releases its connection instead of keeping it open until garbage collection.
+- **`matchMedia` listeners fire when you resize the window.** `resize_window_to` now runs the JavaScript breakpoint handlers. Stylesheet `@media` rules still only apply after the next `visit`.
+
 ## [0.12.0] - 2026-08-28
 
 > **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8875, and the rolling `nightly` tag now carries it (8982 as of 2026-08-28), so updating the browser is all it takes. **No tagged Lightpanda release is new enough yet**: 0.3.7 is below the floor, so version pinning stays unavailable until Lightpanda ships its next release.

data/README.md

@@ -57,7 +57,7 @@ driven_by :lightpanda
 > Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), and `@media` / `window.matchMedia()` evaluate against the `window_size` you configure — so a mobile-only CTA gated by `@media (max-width: …)` resolves at the width you ask for. What's missing is *layout*: nothing reflows, `getBoundingClientRect` stays synthetic, and there is no real scroll. Specs that assert on pixel geometry, scrolling, or screenshots — plus the two that catch people out, a second browser tab and a menu revealed purely by CSS `:hover` — should stay on Cuprite (or whichever full-browser driver you were already using). The [per-spec dual-driver setup](https://navidemad.github.io/capybara-lightpanda/docs/#dual-per-spec) routes that minority to Cuprite and the structural majority to Lightpanda for speed.
 
 > [!TIP]
-> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "0.3.8"`. (0.3.8 is the first release that will clear the gem's current floor, nightly build 8875 — until upstream tags it, the driver needs the rolling `nightly` tag.) Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "1.0.0"` (the tagged release the gem's current floor is pinned to — nightly build 9994 is that release's commit). Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
 
 ## Credits
 

data/lib/capybara/lightpanda/browser/console.rb

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

data/lib/capybara/lightpanda/browser/navigation.rb

@@ -33,12 +33,20 @@ module Capybara
         end
         alias goto go_to
 
+        # Back/forward go through the page's own History API, like the
+        # browser's buttons: an entry created by `pushState` is restored in
+        # the same document (JS state kept, `popstate` fired synchronously),
+        # while an entry from another document starts a real navigation that
+        # `wait_for_idle` sniffs and waits out. CDP's
+        # `Page.navigateToHistoryEntry` is not an option — Lightpanda reloads
+        # the document even for a `pushState` entry. Both are no-ops at either
+        # end of the session history.
         def back
-          wait_for_navigation { navigate_history(-1) }
+          traverse_history("history.back()")
         end
 
         def forward
-          wait_for_navigation { navigate_history(+1) }
+          traverse_history("history.forward()")
         end
 
         def refresh
@@ -98,23 +106,13 @@ module Capybara
           await_navigation(&)
         end
 
-        # Step the session history by `offset` (-1 = back, +1 = forward) using
-        # native CDP. `Page.getNavigationHistory` returns the entry list and
-        # `currentIndex`; `Page.navigateToHistoryEntry` jumps to the chosen
-        # entry's `id`. No-op when the offset would step past either end so
-        # the behavior matches `history.back()` / `history.forward()` on a
-        # bounded session history.
-        def navigate_history(offset)
-          history = page_command("Page.getNavigationHistory")
-          target_index = history["currentIndex"] + offset
-          entries = history["entries"]
-          return if target_index.negative? || target_index >= entries.length
-
-          page_command("Page.navigateToHistoryEntry", entryId: entries[target_index]["id"])
+        def traverse_history(expression)
+          page_command("Runtime.evaluate", expression: expression)
+          wait_for_idle
         end
 
         # Common navigation lifecycle shared by `wait_for_page_load` (fresh
-        # `Page.navigate`) and `wait_for_navigation` (back / forward / reload).
+        # `Page.navigate`) and `wait_for_navigation` (reload).
         # Subscribes to Page.loadEventFired, runs the trigger, waits briefly for
         # the event, falls back to readyState polling for the remaining budget.
         # The handler is unsubscribed via `ensure` so a raising trigger doesn't

data/lib/capybara/lightpanda/browser/runtime.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
+require "singleton"
+
 module Capybara
   module Lightpanda
+    # Stands in for a script result that has no Ruby representation because it
+    # references itself — `window`, or `a.self = a` — so `returnByValue` can't
+    # serialize it. Ferrum returns its own `Ferrum::CyclicObject` the same way.
+    class CyclicObject
+      include Singleton
+
+      def inspect
+        %(#<#{self.class} JavaScript object that cannot be represented in Ruby>)
+      end
+    end
+
     class Browser
       # JS evaluation and RemoteObject plumbing: Runtime.evaluate /
       # callFunctionOn dispatch, result serialization (Ferrum's
@@ -23,7 +36,15 @@ module Capybara
         # later calls, like the DevTools console) but allows redeclaration.
         # Completion-value semantics cover a bare expression (`'foo'`), a
         # `throw` statement, and multi-statement scripts alike.
-        def evaluate(expression, *args)
+        #
+        # `frame` (an `<iframe>` Node, `frame_stack.last` inside `within_frame`)
+        # runs the script against that frame's globals — see call_with_args.
+        # There the script goes through the frame's indirect `eval` rather than
+        # REPL mode: same completion-value semantics, `var` still lands on the
+        # frame's window, but a top-level `const`/`let` lives only for its call.
+        def evaluate(expression, *args, frame: nil)
+          return call_with_args(FRAME_EVAL_JS, [expression], frame: frame) if frame && args.empty?
+
           if args.empty?
             response = page_command("Runtime.evaluate", expression: expression, returnByValue: false,
                                                         awaitPromise: true, replMode: true)
@@ -33,7 +54,7 @@ module Capybara
           end
 
           wrapped = "function() { return #{expression} }"
-          call_with_args(wrapped, args)
+          call_with_args(wrapped, args, frame: frame)
         end
 
         # Execute JS without returning a value.
@@ -43,7 +64,12 @@ module Capybara
         # 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)
+        def execute(expression, *args, frame: nil)
+          if frame && args.empty?
+            call_with_args(FRAME_EXECUTE_JS, [expression], return_by_value: true, frame: frame)
+            return nil
+          end
+
           if args.empty?
             response = page_command("Runtime.evaluate", expression: expression, returnByValue: false,
                                                         awaitPromise: false, replMode: true)
@@ -52,7 +78,7 @@ module Capybara
           end
 
           wrapped = "function() { #{expression} }"
-          call_with_args(wrapped, args, return_by_value: false)
+          call_with_args(wrapped, args, return_by_value: false, frame: frame)
           nil
         end
 
@@ -77,7 +103,7 @@ module Capybara
         # 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.
-        def evaluate_async(expression, *args, wait: @options.timeout)
+        def evaluate_async(expression, *args, wait: @options.timeout, frame: nil)
           timeout_ms = (wait * 1000).to_i
           wrapped = <<~JS
             function() {
@@ -92,7 +118,7 @@ module Capybara
               });
             }
           JS
-          call_with_args(wrapped, args)
+          call_with_args(wrapped, args, frame: frame)
         end
 
         # Evaluate JS and return a RemoteObject reference (for DOM nodes, arrays).
@@ -142,6 +168,19 @@ module Capybara
           # itself timed out / failed in transport.
         end
 
+        # Compiles the declaration (first argument) with the frame's `eval` and
+        # applies it to the rest. `this` is the `<iframe>` element.
+        FRAME_APPLY_JS = <<~JS
+          function(declaration) {
+            var fn = this.contentWindow.eval('(' + declaration + ')');
+            return fn.apply(null, Array.prototype.slice.call(arguments, 1));
+          }
+        JS
+        # Indirect eval: global code in the frame, like a classic script.
+        FRAME_EVAL_JS = "function(source) { return (0, eval)(source); }"
+        # No return, so a script ending in a pending Promise isn't awaited.
+        FRAME_EXECUTE_JS = "function(source) { (0, eval)(source); }"
+
         private
 
         def serialize_argument(arg)
@@ -167,17 +206,32 @@ module Capybara
         # When `return_by_value: false` (the default) the return value is unwrapped via
         # `unwrap_call_result` so that DOM nodes come back as `{ "__lightpanda_node__" => ... }`
         # hashes the Driver can wrap as Capybara nodes.
-        def call_with_args(function_declaration, args, return_by_value: false)
-          # document_object_id returns a fresh RemoteObject handle every call.
-          # Release it on the way out so long-running shared-spec sessions don't
-          # accumulate orphaned V8 handles between resets.
-          doc_oid = document_object_id
+        #
+        # With `frame`, the function is compiled by the frame's own `eval`, so
+        # its free names (`window`, `document`, `location`) are the frame's, and
+        # called from the `<iframe>` element. Running it in the frame's own
+        # execution context instead would not do: Lightpanda runs every
+        # callFunctionOn in the top context, so node handles found inside a
+        # frame belong to that context and can't be passed into another
+        # ("Argument should belong to the same JavaScript world").
+        def call_with_args(function_declaration, args, return_by_value: false, frame: nil)
+          arguments = args.map { |a| serialize_argument(a) }
+          if frame
+            target = frame.remote_object_id
+            arguments.unshift({ value: function_declaration })
+            function_declaration = FRAME_APPLY_JS
+          else
+            # document_object_id returns a fresh RemoteObject handle every call.
+            # Release it on the way out so long-running shared-spec sessions
+            # don't accumulate orphaned V8 handles between resets.
+            target = doc_oid = document_object_id
+          end
           params = {
-            objectId: doc_oid,
+            objectId: target,
             functionDeclaration: function_declaration,
             returnByValue: return_by_value,
             awaitPromise: true,
-            arguments: args.map { |a| serialize_argument(a) },
+            arguments: arguments,
           }
           response = page_command("Runtime.callFunctionOn", **params)
           raise_on_js_error!("call_with_args", function_declaration, response)
@@ -216,6 +270,11 @@ module Capybara
         # Re-fetch a remote object as JSON-serializable value for plain objects/arrays.
         # Cheaper than walking properties and good enough for shared specs. Releases
         # the original handle so long-lived sessions don't accumulate leaked objectIds.
+        #
+        # V8 refuses to return a cyclic object by value. Through 1.0.0 every
+        # Zig-backed object, `window` included, came back as a node; since
+        # upstream #3831 (build 10255) `window` lands here and raised. Both it
+        # and a plain self-referencing object now return CyclicObject.
         def serialize_remote_object(object_id)
           json = page_command(
             "Runtime.callFunctionOn",
@@ -224,10 +283,17 @@ module Capybara
             returnByValue: true
           )
           handle_evaluate_response(json, "function() { return this }")
+        rescue BrowserError => e
+          raise unless CYCLIC_VALUE_ERRORS.any? { |message| e.message.to_s.include?(message) }
+
+          CyclicObject.instance
         ensure
           release_object(object_id)
         end
 
+        CYCLIC_VALUE_ERRORS = ["Object reference chain is too long", "Object couldn't be returned by value"].freeze
+        private_constant :CYCLIC_VALUE_ERRORS
+
         # Walk an array's own indexed properties via `Runtime.getProperties`,
         # unwrapping each element through the regular result pipeline so that
         # DOM-node entries surface as `{ "__lightpanda_node__" => ... }` instead

data/lib/capybara/lightpanda/browser/selenium_compat.rb

@@ -85,9 +85,10 @@ module Capybara
         # Selenium's `execute_async_script`: the script receives a completion
         # callback as its last argument. Same contract as
         # Driver#evaluate_async_script, minus the DOM-node unwrapping — callers
-        # on this path (axe-core et al.) hand back plain JSON.
+        # on this path (axe-core et al.) hand back plain JSON. Runs in the
+        # current frame, as Selenium's does.
         def execute_async_script(script, *)
-          evaluate_async(script.to_s.strip, *)
+          evaluate_async(script.to_s.strip, *, frame: frame_stack.last)
         end
 
         # Selenium's raw-CDP escape hatch, as used by

data/lib/capybara/lightpanda/browser.rb

@@ -166,6 +166,7 @@ module Capybara
         subscribe_to_console_logs
         subscribe_to_console_capture
         subscribe_to_execution_context
+        subscribe_to_navigation
         subscribe_to_turbo_signals
         # Network owns the Network.* domain: enabling installs traffic
         # tracking AND the navigation-response capture behind status_code.
@@ -423,17 +424,25 @@ module Capybara
       # (title, current_url, …) without racing the navigation lifecycle.
       #
       # Sniff window: the action returns synchronously, but the CDP events
-      # signalling its async fallout (Runtime.executionContextsCleared for
-      # full nav; the turbo sentinel for Turbo) arrive later on the dispatch
-      # thread. We poll briefly for either signal — if neither fires within
-      # the window, assume the action was inert and exit fast.
+      # signalling its async fallout arrive later on the dispatch thread. We
+      # poll briefly for any of them — a main-frame navigation start (see
+      # subscribe_to_navigation), Runtime.executionContextsCleared, or the
+      # turbo sentinel — and if none fires within the window, assume the
+      # action was inert and exit fast. Lightpanda announces a navigation
+      # ~5 ms after the click but only swaps the execution context once the
+      # response lands, so watching the context alone returned on the old
+      # document whenever the server took longer than the window.
       SNIFF_WINDOW = 0.05
       private_constant :SNIFF_WINDOW
 
       def wait_for_idle
         prior_context_iteration = @default_context_event.iteration
+        prior_navigation_iteration = @navigation_event.iteration
         sniff_deadline = monotonic_time + SNIFF_WINDOW
+        navigating = false
         loop do
+          navigating = @navigation_event.iteration > prior_navigation_iteration
+          break if navigating
           break if @default_context_event.iteration > prior_context_iteration
           break unless @turbo_event.set?
           break if monotonic_time > sniff_deadline
@@ -441,6 +450,9 @@ module Capybara
           sleep 0.001
         end
 
+        # Only a navigation this action started is awaited: one left pending
+        # by an earlier load must not make every later click pay the timeout.
+        @navigation_event.wait(@options.timeout) if navigating
         @default_context_event.wait(@options.timeout)
         @turbo_event.wait(@options.timeout)
         check_unhandled_modal!
@@ -607,6 +619,53 @@ module Capybara
         page_command("Runtime.enable")
       end
 
+      # Track cross-document navigations of the main frame, from the moment
+      # they start until the frame stops loading. Same-document ones
+      # (pushState, fragment) emit Page.navigatedWithinDocument instead and
+      # never reset the event, so they don't make wait_for_idle block; nor do
+      # iframe navigations (other frameId). The main frame shares the
+      # target's id.
+      #
+      # It ends at whichever comes first: the main frame's new default
+      # execution context (the new document committed — enough even when
+      # the load event never comes, lightpanda-io/browser#1801) or
+      # Page.frameStoppedLoading. A navigation whose request fails
+      # (connection refused, DNS) emits neither — only Network.loadingFailed for the
+      # document request — so that ends it too, keyed by the requestId the
+      # main-frame Document request was sent with. Needs Page.enable, which
+      # the first go_to turns on; a page that was never visited has no
+      # navigation to click into.
+      def subscribe_to_navigation
+        @navigation_event = Utils::Event.new
+        @navigation_event.set
+        @navigation_request_id = nil
+
+        on("Page.frameStartedNavigating") do |params|
+          @navigation_event.reset if main_frame_navigation_start?(params)
+        end
+        on("Network.requestWillBeSent") do |params|
+          @navigation_request_id = params["requestId"] if main_frame_document_request?(params)
+        end
+        on("Page.frameStoppedLoading") do |params|
+          @navigation_event.set if params["frameId"] == @target_id
+        end
+        on("Runtime.executionContextCreated") do |params|
+          aux = params.dig("context", "auxData") || {}
+          @navigation_event.set if aux["isDefault"] && aux["frameId"] == @target_id
+        end
+        on("Network.loadingFailed") do |params|
+          @navigation_event.set if params["requestId"] == @navigation_request_id
+        end
+      end
+
+      def main_frame_navigation_start?(params)
+        params["frameId"] == @target_id && !params["navigationType"].to_s.match?(/same/i)
+      end
+
+      def main_frame_document_request?(params)
+        params["type"] == "Document" && params["frameId"] == @target_id
+      end
+
       def close_client_silently
         @client&.close
       rescue StandardError

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

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

data/lib/capybara/lightpanda/client.rb

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