capybara-lightpanda 0.14.2 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 197930c8808e3cb4d58ce97952b13e657dfbf8e7d200a98b03a5e71e7afdc87f
-  data.tar.gz: 6401c206e53dce565b29eab2e4c4b01bbf141a88c81025bc12b584b7cc0e75af
+  metadata.gz: a8f6c1cfdad13de4569b3d79828d9d19848b166e220b6a91329c7c0cb2fa9781
+  data.tar.gz: 2f7c90bb35b746682f5533c9d7ebfe1b64fbf7aea1f53a6c93f563428d9f3b46
 SHA512:
-  metadata.gz: 0cfe0bd2b2491e8b26715110950286a74e9bd1a7816d52a76b87cc601814ed4dd4faabf5665108f82624d6720581bdc7560c82445220456cb089a13313618857
-  data.tar.gz: 84fb972984583e315cf20f0a70a114238015aa29c49786a6aec5f329556518fc63ee5bb2204e430ccdb81e014943535cc2899c1ec40fb673d3f641bf5b201063
+  metadata.gz: 1d1632dc29185af1e1d1c594abd7a9fe4b0af584585aa6c6534428d59b23316174db581d901bd7d67430b2e708c664c9c7175918cfeca4d386ba95453816b910
+  data.tar.gz: 76a79eed2e960c294a09c1ee8882014d543c5695cd519d51c3d9560ca7b153b085ae4161f18e2a11a301465b95c0cc71140a269c3c8970c86e93d291430630cb

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.16.0] - 2026-10-26
+
+### Fixed
+
+- **`trigger(:click)` waits for the page it loads.** Calling `element.trigger(:click)` on a link or submit button returned before the new page arrived, so the next step ran against the old page. It now waits the way `click` does.
+- **Clicking a `<a download>` link no longer cancels the download on recent nightlies.** From nightly 11097 (and the upcoming 1.1 release line), Lightpanda starts the download itself when a link has a `download` attribute. The driver then also went to the same URL, which cancelled the download and replaced the page. The driver now leaves the download to the browser. Older browsers behave as before.
+- **`obscured?` sees overlays inside a shadow root.** On browsers that can hit-test inside shadow trees (recent nightlies), an element covered by another element in the same shadow root now counts as obscured; before, it was always reported as not obscured. Older browsers give the same answer as before.
+
+## [0.15.0] - 2026-10-23
+
+> **Update Lightpanda before upgrading.** This release requires Lightpanda **1.0.2** or a nightly build ≥ 10965. The driver refuses anything older and names the version it found. Pin `1.0.2` for a reproducible browser.
+
+### Added
+
+- **The driver keeps Lightpanda's recent output.** `browser.process.output` returns the browser's last 100 lines of output. When the browser crashes during a navigation, the `DeadBrowserError` message quotes the last 20 of those lines, so the crash is no longer silent.
+
+### Changed
+
+- **`page_errors` now reads the browser's own exception reports.** It used to rely on a script the driver injected into every page to listen for errors. It now reads `Runtime.exceptionThrown`, the event Chrome clients use, which Lightpanda emits from 1.0.2. The entries look the same as before. Two differences: an error that the page cancels itself (an `error` listener calling `preventDefault()`) is no longer listed, as in Chrome; and the driver no longer adds a listener script to your pages.
+- **Finding elements by text is much faster.** `find("li", text: "…")` used to ask the browser about every candidate one by one. Visibility and text are now checked inside the find itself: on a list of 300 items, that's 4 round-trips instead of about 500.
+
+### Fixed
+
+- **`page_errors` no longer lists rejections the page handled.** On Lightpanda 1.0.1, a promise rejected and caught in the same tick (`asyncFn().catch(handler)`, `Promise.reject(e).catch(handler)`) still showed up in `page_errors` as an unhandled rejection. The new browser floor fixes this.
+- **`find` and `click` work before the first `visit`.** On a fresh session, or right after `reset_session!`, finding an element built with `execute_script` raised `ReferenceError: _lightpanda is not defined`.
+- **Delegated `change` and `submit` handlers fire again under jQuery 1.x.** jQuery 1.x checks at load time whether the browser supports these events on `window`. Lightpanda used to fail that check, so jQuery switched to its old Internet Explorer workaround and no delegated `change` or `submit` handler ever ran (Solidus admin, Backbone-era apps). The new browser floor fixes this; no code change required on your end.
+- **`send_keys` types numbers, as Selenium does.** `send_keys [1, :tab]` used to drop the `1` silently and send only the Tab.
+- **An HTML5 drag ends with `drop` or `dragleave`, never both.** `drag_to` fired `dragleave` and then `drop` on a target that accepted the drag. Libraries such as Pragmatic drag and drop read that `dragleave` as the drag leaving the window and dropped onto nothing.
+- **`drag_to` keeps every `dragover` inside the viewport on recent nightlies.** From nightly 10661, the target could end up above the window, so the first `dragover` reported a negative `clientY`, which sortable lists and dropzones that hit-test on coordinates misread. The driver now centers the target itself, as Chrome does.
+- **Elements inside a shadow root are no longer reported as obscured.** `obscured?` reported every shadow DOM element as covered by its own host.
+- **`trigger(:input)` sends a real `InputEvent`.** Listeners that read `event.inputType` got `undefined`; they now get `"insertText"`, as when typing.
+- **`evaluate_script` no longer times out on a string that ends in half an emoji.** The result was dropped and the call waited for the full timeout. The broken character now comes back as `�`.
+- **Passing an element from a previous page to `execute_script` lets Capybara find it again.** It used to raise a plain `BrowserError`; Capybara now treats the element as obsolete and finds it again in the new page.
+
 ## [0.14.2] - 2026-10-14
 
 ### Fixed

data/README.md

@@ -14,7 +14,7 @@ Self-contained — built-in CDP client, no external browser-client gem required.
 <strong>Capybara</strong>&nbsp;&nbsp;→&nbsp;&nbsp;<code>capybara-lightpanda</code>&nbsp;&nbsp;→&nbsp;&nbsp;<a href="https://lightpanda.io/"><img src="docs/static/img/lightpanda-logo.svg" alt="Lightpanda" height="22" valign="middle"></a>&nbsp;<a href="https://github.com/lightpanda-io/browser/stargazers"><img src="https://img.shields.io/github/stars/lightpanda-io/browser?logo=github&label=stars" alt="GitHub stars" valign="middle"></a>
 
 [![Capybara::Lightpanda — faster system tests for Rails, without Chromium](docs/static/img/banner.png)](https://navidemad.github.io/capybara-lightpanda/)
-<sub><em>Configuration · dual-driver setups · Turbo Rails · capability matrix · beta-testing guide</em></sub>
+<sub><em>Configuration · setup recipes · Turbo Rails · known limitations · beta-testing guide</em></sub>
 
 [![Read the docs](https://img.shields.io/badge/https%3A%2F%2Fnavidemad.github.io%2Fcapybara--lightpanda-→%20Visit%20the%20website-1F2937?style=for-the-badge)](https://navidemad.github.io/capybara-lightpanda/)
 
@@ -54,16 +54,16 @@ driven_by :lightpanda
 > The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
 
 > [!IMPORTANT]
-> 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.
+> 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 can't pass here, nor can the two that catch people out: a second browser tab and a menu revealed purely by CSS `:hover`. See [known limitations](https://navidemad.github.io/capybara-lightpanda/docs/#limits).
 
 > [!TIP]
-> 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).
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "1.0.2"` (the tagged release the gem's current floor is pinned to — nightly build 10965 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
 
 - [Lightpanda](https://lightpanda.io/) — the headless browser
 - [Capybara](https://github.com/teamcapybara/capybara) — the test framework
-- Inspired by the [Cuprite](https://github.com/rubycdp/cuprite) / [Ferrum](https://github.com/rubycdp/ferrum) architecture and [`lightpanda-ruby`](https://github.com/marcoroth/lightpanda-ruby)
+- Inspired by the [Ferrum](https://github.com/rubycdp/ferrum) architecture and [`lightpanda-ruby`](https://github.com/marcoroth/lightpanda-ruby)
 
 Patterns adapted from these MIT-licensed projects (cookies API, frame switching, node call/error conventions, retry/event utilities) are acknowledged with the original copyright notices in [NOTICE.md](NOTICE.md).
 

data/lib/capybara/lightpanda/auto_scripts.rb

@@ -17,9 +17,9 @@ module Capybara
 
       # Order matters: declarations (turbo, predicates) before the wiring
       # (attach) that reads their names. banner is a leading comment block.
-      # turbo.js and errors.js register their listeners at top level and expose
-      # nothing through attach.js, so they only need to run inside the IIFE.
-      PARTS = %w[banner.js turbo.js errors.js predicates.js attach.js].freeze
+      # turbo.js registers its listeners at top level and exposes nothing
+      # through attach.js, so it only needs to run inside the IIFE.
+      PARTS = %w[banner.js turbo.js predicates.js attach.js].freeze
 
       # The guard short-circuits a repeat run before turbo.js can register its
       # listeners a second time (double-registration would double-count

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

@@ -35,14 +35,13 @@ module Capybara
         # them would also start failing every suite that already asserts
         # console_logs holds no errors.
         #
-        # Lightpanda emits no Runtime.exceptionThrown at all, so the source is
-        # a passive listener pair in javascripts/errors.js reporting over the
-        # console.debug sentinel channel. It sees what reaches `window`:
-        # exceptions a framework catches itself (Stimulus's handleError, any
-        # try/catch) never arrive, and a cross-origin script collapses to
-        # "Script error." with no detail. Partial by construction — but the
-        # alternative is the zero visibility that made the solidus taxon-tree
-        # failure take a hand-injected listener to explain.
+        # The source is Runtime.exceptionThrown, as in Chrome: Lightpanda emits
+        # it for an uncaught exception (#3905, build 10450) and an unhandled
+        # rejection (#4096, 10904), in iframes too (#4115, 10910). What it
+        # reports is what reaches `window` uncancelled: an exception a framework
+        # catches itself (Stimulus's handleError, any try/catch) never arrives,
+        # nor does one a page `error` listener cancels with preventDefault. The
+        # driver's own scripts raise JavaScriptError instead and never land here.
         def page_errors
           @page_errors_mutex.synchronize { @page_errors.dup }
         end
@@ -51,6 +50,63 @@ module Capybara
           @page_errors_mutex.synchronize { @page_errors.clear }
         end
 
+        REJECTION_TEXT = "Uncaught (in promise)"
+        private_constant :REJECTION_TEXT
+
+        # Cap the stack: a deep recursion stack can be megabytes, and the buffer
+        # keeps up to PAGE_ERRORS_LIMIT of them.
+        STACK_LIMIT = 4_000
+        private_constant :STACK_LIMIT
+
+        # One Runtime.exceptionThrown event as a page_errors entry. The shape is
+        # the one javascripts/errors.js produced from the DOM `error` /
+        # `unhandledrejection` events before this event replaced it, so suites
+        # written against it keep working:
+        # - message: an Error's "Name: message" (the description up to its
+        #   first stack frame), or a thrown primitive's value. A rejection's
+        #   message drops the "Name: " prefix, as `reason.message` did.
+        # - line/column: 1-based like ErrorEvent's lineno/colno (CDP counts
+        #   from 0), and nil for a rejection, which carries no location.
+        # - stack: the Error's description, which is its stack, or nil for a
+        #   thrown primitive. Lightpanda sends no structured stackTrace.
+        def self.page_error_entry(params)
+          details = params["exceptionDetails"] || {}
+          exception = details["exception"] || {}
+          rejection = details["text"] == REJECTION_TEXT
+          stack = exception["subtype"] == "error" ? exception["description"].to_s : nil
+
+          {
+            kind: rejection ? "unhandledrejection" : "error",
+            message: page_error_message(exception, stack, rejection),
+            url: details["url"].to_s,
+            line: rejection ? nil : one_based(details["lineNumber"]),
+            column: rejection ? nil : one_based(details["columnNumber"]),
+            stack: stack&.slice(0, STACK_LIMIT),
+            timestamp: params["timestamp"],
+          }
+        end
+
+        def self.one_based(position)
+          position + 1 if position
+        end
+
+        def self.page_error_message(exception, stack, rejection)
+          return primitive_text(exception) unless stack
+
+          summary = stack.split(/\n\s+at /, 2).first
+          prefix = "#{exception['className']}: "
+          rejection && summary.start_with?(prefix) ? summary.delete_prefix(prefix) : summary
+        end
+
+        # What String(value) gave for a thrown or rejected non-Error.
+        def self.primitive_text(exception)
+          return exception["value"].nil? ? "null" : exception["value"].to_s if exception.key?("value")
+
+          [exception["unserializableValue"], exception["description"], exception["type"]]
+            .find { |v| v.is_a?(String) && !v.empty? }.to_s
+        end
+        private_class_method :page_error_message, :one_based, :primitive_text
+
         private
 
         def subscribe_to_console_logs
@@ -83,9 +139,6 @@ module Capybara
         TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
         private_constant :TURBO_SENTINEL_PREFIX
 
-        PAGE_ERROR_SENTINEL_PREFIX = "__lightpanda_page_error_"
-        private_constant :PAGE_ERROR_SENTINEL_PREFIX
-
         # The Turbo activity tracker signals busy/idle via console.debug
         # sentinels (see subscribe_to_turbo_signals); every consoleAPICalled
         # consumer must filter them out of user-facing output.
@@ -93,17 +146,12 @@ module Capybara
           value.is_a?(String) && value.start_with?(TURBO_SENTINEL_PREFIX)
         end
 
-        # javascripts/errors.js reports uncaught page errors over the same
-        # console.debug channel, prefix + JSON payload.
-        def page_error_sentinel?(value)
-          value.is_a?(String) && value.start_with?(PAGE_ERROR_SENTINEL_PREFIX)
-        end
-
         # Anything the injected bundle emits for the driver's own benefit. Every
-        # consoleAPICalled consumer filters on this, not on one prefix — missing
-        # a sentinel here leaks driver plumbing into user-facing output.
+        # consoleAPICalled consumer filters on this, not on one prefix — a new
+        # sentinel added to turbo_sentinel?'s side only would leak driver
+        # plumbing into user-facing output.
         def driver_sentinel?(value)
-          turbo_sentinel?(value) || page_error_sentinel?(value)
+          turbo_sentinel?(value)
         end
 
         # Oldest entries are dropped past this cap so a chatty page can't grow
@@ -113,20 +161,12 @@ module Capybara
         # Ring-buffer every console.* call for `Browser#console_logs`. Separate
         # from subscribe_to_console_logs (which streams to an optional IO logger)
         # so capture works without any logger configured. Driver sentinels are
-        # plumbing, not page output: the Turbo ones are dropped, and the
-        # page-error ones are rerouted to @page_errors instead.
+        # plumbing, not page output, so they are dropped.
         def subscribe_to_console_capture
           on("Runtime.consoleAPICalled") do |params|
             args = params["args"]
             next unless args.is_a?(Array)
-
-            first = args.first&.dig("value")
-            next if turbo_sentinel?(first)
-
-            if page_error_sentinel?(first)
-              record_page_error(first, params["timestamp"])
-              next
-            end
+            next if driver_sentinel?(args.first&.dig("value"))
 
             entry = {
               type: params["type"],
@@ -142,28 +182,10 @@ module Capybara
         # loop (a rejected fetch on an interval) must not grow this unbounded.
         PAGE_ERRORS_LIMIT = 1_000
 
-        # Parse one `__lightpanda_page_error_<json>` sentinel into @page_errors.
-        # A payload that won't parse is still worth surfacing — dropping it would
-        # turn "the page threw" into silence, which is the whole failure mode
-        # this exists to end — so it lands with the raw text as the message.
-        def record_page_error(sentinel, timestamp)
-          json = sentinel.delete_prefix(PAGE_ERROR_SENTINEL_PREFIX)
-          fields = begin
-            JSON.parse(json)
-          rescue JSON::ParserError
-            { "kind" => "error", "message" => json }
+        def subscribe_to_page_errors
+          on("Runtime.exceptionThrown") do |params|
+            push_capped(@page_errors, @page_errors_mutex, Console.page_error_entry(params), PAGE_ERRORS_LIMIT)
           end
-
-          entry = {
-            kind: fields["kind"] || "error",
-            message: fields["message"].to_s,
-            url: fields["url"].to_s,
-            line: fields["line"],
-            column: fields["column"],
-            stack: fields["stack"],
-            timestamp: timestamp,
-          }
-          push_capped(@page_errors, @page_errors_mutex, entry, PAGE_ERRORS_LIMIT)
         end
 
         def push_capped(buffer, mutex, entry, limit)

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

@@ -10,10 +10,17 @@ module Capybara
         # Find elements in the current context (top frame or active frame).
         # Returns an array of remote object ID strings.
         def find(method, selector)
+          find_hinted(method, selector).map(&:first)
+        end
+
+        # Like #find, but with Capybara's finder hints answered in the same
+        # round-trip (see `_lightpanda.findHints`). Returns `[objectId, cache]`
+        # pairs; `cache` is {} when `spec` is nil or the page couldn't answer.
+        def find_hinted(method, selector, spec = nil)
           if @frame_stack.empty?
-            find_in_document(method, selector)
+            find_in_document(method, selector, spec)
           else
-            find_in_frame(method, selector)
+            find_in_frame(method, selector, spec)
           end
         end
 
@@ -27,9 +34,14 @@ module Capybara
         # `NoExecutionContextError`. `find_in_document` and `find_in_frame`
         # already use the same wrapper; `find_within` was the odd one out.
         def find_within(remote_object_id, method, selector)
+          find_within_hinted(remote_object_id, method, selector).map(&:first)
+        end
+
+        def find_within_hinted(remote_object_id, method, selector, spec = nil)
           with_default_context_wait do
-            result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, return_by_value: false)
-            extract_node_object_ids(result)
+            result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, spec,
+                                      return_by_value: false)
+            extract_hinted_nodes(result)
           end
         rescue JavaScriptError => e
           raise_invalid_selector(e, method, selector)
@@ -37,12 +49,12 @@ module Capybara
 
         # Ancestor chain of `remote_object_id` from parentNode up to (but
         # excluding) `document`, returned as an array of remote object IDs.
-        # Mirrors Cuprite's JS `parents` helper. Same `with_default_context_wait`
-        # wrapping as `find_within` — same race window applies.
+        # Same `with_default_context_wait` wrapping as `find_within` — same
+        # race window applies.
         def parents_of(remote_object_id)
           with_default_context_wait do
             result = call_function_on(remote_object_id, PARENTS_JS, return_by_value: false)
-            extract_node_object_ids(result)
+            extract_hinted_nodes(result).map(&:first)
           end
         end
 
@@ -50,8 +62,8 @@ module Capybara
 
         # 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.
+        # Capybara::Lightpanda::InvalidSelector. A plain prefixed string keeps
+        # our inline JS simple.
         INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
 
         # The find algorithms exist in three dispatch contexts — element-scoped
@@ -90,32 +102,39 @@ module Capybara
         # JS function for finding elements within a node.
         # Works in any execution context (top frame or iframe).
         FIND_WITHIN_JS = <<~JS.freeze
-          function(method, selector) {
-            if (method === 'xpath') {
-              #{format(XPATH_FIND_FRAGMENT, doc: 'this.ownerDocument', root: 'this', selector: 'selector')}
-            }
-            #{format(CSS_FIND_FRAGMENT, target: 'this', selector: 'selector')}
+          function(method, selector, spec) {
+            var self = this;
+            var nodes = (function() {
+              if (method === 'xpath') {
+                #{format(XPATH_FIND_FRAGMENT, doc: 'self.ownerDocument', root: 'self', selector: 'selector')}
+              }
+              #{format(CSS_FIND_FRAGMENT, target: 'self', selector: 'selector')}
+            })();
+            return spec ? _lightpanda.findHints(nodes, spec) : nodes;
           }
         JS
         private_constant :FIND_WITHIN_JS
 
         # JS function for finding elements in an iframe's contentDocument.
         FIND_IN_FRAME_JS = <<~JS.freeze
-          function(method, selector) {
+          function(method, selector, spec) {
             var doc;
             try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
             if (!doc) return [];
-            if (method === 'xpath') {
-              #{format(XPATH_FIND_FRAGMENT, doc: 'doc', root: 'doc', selector: 'selector')}
-            }
-            #{format(CSS_FIND_FRAGMENT, target: 'doc', selector: 'selector')}
+            var nodes = (function() {
+              if (method === 'xpath') {
+                #{format(XPATH_FIND_FRAGMENT, doc: 'doc', root: 'doc', selector: 'selector')}
+              }
+              #{format(CSS_FIND_FRAGMENT, target: 'doc', selector: 'selector')}
+            })();
+            return spec ? _lightpanda.findHints(nodes, spec) : nodes;
           }
         JS
         private_constant :FIND_IN_FRAME_JS
 
         # Walks `parentNode` from `this` up to (but excluding) `document`,
         # returning the chain as a JS array. Each entry is an element node so
-        # `extract_node_object_ids` can wrap them as Lightpanda::Nodes.
+        # `extract_hinted_nodes` can wrap them as Lightpanda::Nodes.
         PARENTS_JS = <<~JS
           function() {
             var nodes = [];
@@ -129,7 +148,7 @@ module Capybara
         JS
         private_constant :PARENTS_JS
 
-        def find_in_document(method, selector)
+        def find_in_document(method, selector, spec)
           with_default_context_wait do
             # Coerce Symbol selectors (e.g. Capybara warning path lets `have_css(:p)`
             # through) to a string before quoting. Symbol#inspect returns `:p`,
@@ -143,19 +162,21 @@ module Capybara
                        else
                          format(CSS_FIND_FRAGMENT, target: "document", selector: selector_literal)
                        end
-            result = evaluate_with_ref("(function() { #{fragment} })()")
-            extract_node_object_ids(result)
+            nodes = "(function() { #{fragment} })()"
+            nodes = "_lightpanda.findHints(#{nodes}, #{JSON.generate(spec)})" if spec
+            result = evaluate_with_ref(nodes)
+            extract_hinted_nodes(result)
           end
         rescue JavaScriptError => e
           raise_invalid_selector(e, method, selector)
         end
 
-        def find_in_frame(method, selector)
+        def find_in_frame(method, selector, spec)
           with_default_context_wait do
             frame_node = @frame_stack.last
-            result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
+            result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector, spec,
                                       return_by_value: false)
-            extract_node_object_ids(result)
+            extract_hinted_nodes(result)
           end
         rescue JavaScriptError => e
           raise_invalid_selector(e, method, selector)
@@ -169,27 +190,57 @@ module Capybara
           raise js_error
         end
 
-        # Extract individual node objectIds from a remote array reference.
+        # Extract `[objectId, cache]` pairs from a remote array reference. The
+        # hints, when findHints ran, are a JSON string on the array's own
+        # `__lightpandaHints` property, read from the same getProperties call.
         # `ensure release_object` so the outer array handle is freed even when
         # property walking raises — without this, a transient CDP error during
         # property enumeration leaks one V8 handle per failed find call.
-        def extract_node_object_ids(result)
+        def extract_hinted_nodes(result)
           return [] unless result && result["objectId"]
 
           outer_id = result["objectId"]
           begin
             props = get_object_properties(outer_id)
             properties = props["result"] || []
-            properties
-              .select { |p| p["name"] =~ /\A\d+\z/ }
-              .sort_by { |p| p["name"].to_i }
-              .filter_map { |p| p.dig("value", "objectId") }
+            ids = properties
+                  .select { |p| p["name"] =~ /\A\d+\z/ }
+                  .sort_by { |p| p["name"].to_i }
+                  .filter_map { |p| p.dig("value", "objectId") }
+            ids.zip(parse_hints(properties, ids.size))
           rescue Error
             []
           ensure
             release_object(outer_id)
           end
         end
+
+        # One cache per node, keyed the way Capybara reads #initial_cache. A
+        # missing, malformed or mis-sized payload yields empty caches, so
+        # Capybara asks each node itself — never a wrong answer.
+        def parse_hints(properties, count)
+          raw = properties.find { |p| p["name"] == "__lightpandaHints" }&.dig("value", "value")
+          hints = decode_hints(raw)
+          return Array.new(count) { {} } unless hints&.size == count
+
+          hints.map { |h| symbolize_hint(h) }
+        end
+
+        # Capybara may consume these after a DOM mutation during lazy Result
+        # enumeration. Accept only well-typed immutable answers, never mutable
+        # visibility/style/position or a payload from an incompatible helper.
+        def symbolize_hint(hint)
+          return {} unless hint.is_a?(Hash) && hint.keys == ["tag_name"] && hint["tag_name"].is_a?(String)
+
+          { tag_name: hint["tag_name"] }
+        end
+
+        def decode_hints(raw)
+          hints = raw.is_a?(String) ? JSON.parse(raw) : nil
+          hints.is_a?(Array) ? hints : nil
+        rescue JSON::ParserError
+          nil
+        end
       end
     end
   end

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

@@ -57,8 +57,8 @@ module Capybara
         # Surface a dialog that opened with no pre-arm. Called from the main
         # thread after every action that can open one (Browser#wait_for_idle,
         # #go_to). Warns by default; raises when the driver was built with
-        # `raise_on_unhandled_modal: true` (Cuprite's option name). Either way
-        # the dialog is already gone — Lightpanda's default resolved it.
+        # `raise_on_unhandled_modal: true`. Either way the dialog is already
+        # gone — Lightpanda's default resolved it.
         def check_unhandled_modal!
           entry = @modal_messages_mutex.synchronize do
             e = @unhandled_modal
@@ -74,11 +74,12 @@ module Capybara
         end
 
         # `type` is accepted for the error message only: like Selenium (where
-        # alert/confirm are indistinguishable) and Cuprite (whose dialog handler
-        # accepts whatever fires), we deliberately do NOT reject a dialog whose
-        # reported type differs from the one Capybara asked for. Real suites
-        # wrap `data-confirm` deletes in `accept_alert` (e.g. solidus admin) and
-        # expect it to work; only the message text is matched.
+        # alert/confirm are indistinguishable) and other CDP drivers (whose
+        # dialog handler accepts whatever fires), we deliberately do NOT
+        # reject a dialog whose reported type differs from the one Capybara
+        # asked for. Real suites wrap `data-confirm` deletes in `accept_alert`
+        # (e.g. solidus admin) and expect it to work; only the message text is
+        # matched.
         def find_modal(type, text: nil, wait: options.timeout)
           regexp = text.is_a?(Regexp) ? text : (text && Regexp.new(Regexp.escape(text.to_s)))
           last_seen_message = nil

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

@@ -90,7 +90,16 @@ module Capybara
 
           return unless @client.closed?
 
-          raise DeadBrowserError, "Lightpanda crashed navigating to #{url}"
+          raise DeadBrowserError, "Lightpanda crashed navigating to #{url}#{crash_output}"
+        end
+
+        # The browser's own last words, when we spawned it: a panic or an
+        # assertion only ever shows up on its stderr.
+        def crash_output
+          lines = @process&.output&.last(20)
+          return "" if lines.nil? || lines.empty?
+
+          "\nLast Lightpanda output:\n#{lines.join("\n")}"
         end
 
         def safe_current_url

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

@@ -271,10 +271,10 @@ module Capybara
         # 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
+        # V8 refuses to return a cyclic object by value. Below 10255 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.
+        # upstream #3831 (in the floor) `window` lands here and raised. Both it
+        # and a plain self-referencing object return CyclicObject.
         def serialize_remote_object(object_id)
           json = page_command(
             "Runtime.callFunctionOn",

data/lib/capybara/lightpanda/browser.rb

@@ -165,6 +165,7 @@ module Capybara
         @turbo_event.set
         subscribe_to_console_logs
         subscribe_to_console_capture
+        subscribe_to_page_errors
         subscribe_to_execution_context
         subscribe_to_navigation
         subscribe_to_document_ready
@@ -187,7 +188,7 @@ module Capybara
       end
 
       # Download destination: explicit :save_path option wins, else
-      # Capybara.save_path (Cuprite parity). nil => downloads stay off.
+      # Capybara.save_path. nil => downloads stay off.
       def configured_download_path
         @options.save_path ||
           (defined?(Capybara) && Capybara.respond_to?(:save_path) ? Capybara.save_path : nil)
@@ -553,8 +554,15 @@ module Capybara
         page_command("LP.configureLoading", subFrame: true, worker: true)
       end
 
+      # Registration only covers documents created *after* it, and the target
+      # already holds its about:blank document. Evaluate the bundle there too,
+      # or a session that runs `find`/`click` before its first `visit` (DOM built
+      # by execute_script, or right after reset_session!) hits
+      # `ReferenceError: _lightpanda is not defined`. The bundle's own
+      # `if (window._lightpanda) return;` guard makes the second run a no-op.
       def register_auto_scripts
         page_command("Page.addScriptToEvaluateOnNewDocument", source: AutoScripts::JS)
+        page_command("Runtime.evaluate", expression: AutoScripts::JS)
       end
 
       # Apply the `window_size` option as a JS-visible viewport: it drives
@@ -687,9 +695,10 @@ module Capybara
       # After a click that navigated, the next action must not run before the
       # new page's JS has wired its handlers: Stimulus, Bootstrap's data-api
       # and Turbo load as module scripts, which run after the document commits
-      # and before DOMContentLoaded. Cuprite waits for the load event. The
-      # event is awaited briefly, then document.readyState is polled for the
-      # rest of the budget, as #go_to does (lightpanda-io/browser#1801: page
+      # and before DOMContentLoaded. Chrome-based drivers wait for the load
+      # event. The event is awaited briefly, then document.readyState is
+      # polled for the rest of the budget, as #go_to does
+      # (lightpanda-io/browser#1801: page
       # events may never come). Never raises: a page that never settles costs
       # the timeout once, then the action returns as it did before.
       DOCUMENT_READY_EVENT_WAIT = 2

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

@@ -214,12 +214,31 @@ module Capybara
           raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
+        # A JS string can hold a lone UTF-16 surrogate ("😀".slice(0, 1));
+        # Lightpanda escapes it as `\ud83d`, which Ruby's json rejects.
+        # Dropping that frame left its command waiting out the full timeout,
+        # so retry once with every lone surrogate replaced by U+FFFD — what
+        # Chrome and Ferrum (#648) hand back for the same value.
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e
-          warn_parse_failure(e.message)
+          begin
+            JSON.parse(replace_lone_surrogates(data), max_nesting: false)
+          rescue JSON::ParserError
+            warn_parse_failure(e.message)
 
-          nil
+            nil
+          end
+        end
+
+        # Alternation order matters: a valid lead+trail pair is consumed
+        # whole, then a lone surrogate, then any other escape (`\\`, `\"`,
+        # a non-surrogate `\uXXXX`) is skipped as-is — scanning left to
+        # right so `\\ud800` (an escaped backslash, then text) survives.
+        SURROGATE_ESCAPE = /\\u[dD][89abAB]\h{2}\\u[dD][c-fC-F]\h{2}|(\\u[dD][89a-fA-F]\h{2})|\\./m
+
+        def replace_lone_surrogates(data)
+          data.gsub(SURROGATE_ESCAPE) { |escape| Regexp.last_match(1) ? "\\uFFFD" : escape }
         end
 
         # Dedupe identical parse-failure warnings per WebSocket instance.