capybara-lightpanda 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d38fc6a0a5cbba01bba3a0a1363d8e0577dc99c2cb8a77b81f407b273a91863b
-  data.tar.gz: 21cdea0aeba27736c52f800c22e850d80ea15d3c7bb1c6c9b173421bb227be7d
+  metadata.gz: bcfaa2e5c56f74e8f6068a969ee03d669d11d49de80ae360fb4a62a96833c8f3
+  data.tar.gz: 3a22106094a7f2de8c3447f9573286e90a4158f25f88b06701cf4540ab9e2147
 SHA512:
-  metadata.gz: ec4a2743650df3602c43fc393a82af00c19c5b44d59fab31156aed0b3252e8fb7f3c5f06df1b6e2fe994c9b974a1b21b29707c22c6bff571d4c2b6aca195add4
-  data.tar.gz: ba19fbd3c2754eae2b6d3af02584d739eba498b93e0e0ff392f9dc7a9feefdc1af1ff68081cd5b6963ca41c768cf8cebcf3b48b9debd9923e5142b15ac1c9223
+  metadata.gz: ebf7c506245fdc550ff5ac3bc643dfe6369c4324642bffe8fb4a27f891f009eaaa842effe0bb7386dfc6d50819ad934d0a3df0e7f67e4fb222116baa5a957955
+  data.tar.gz: 2aaef86e3c5a6c1a4e25c3476790352564df15c0b46c18c02745b5999e587a35090ff88837340dec8e00f977a828ec3ce1eaf9a505b10abfb0412e2538cf4d13

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [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
+
+- **A browser that stops reading no longer hangs the test process.** If Lightpanda got stuck (a page in an endless synchronous loop, a stopped process) while a large command was being sent, about 1 MB and up (a big `execute_script` bundle, for example), the send blocked forever: the command's timeout never started, every other command waited behind it, and so did quitting the browser, at exit included. Sending now gives up after the command's timeout and raises `DeadBrowserError`.
+- **Clicking a `mailto:` or `tel:` link keeps the page, as in Chrome.** On Lightpanda 1.0.0, clicking `<a href="mailto:someone@example.com">` left the page and loaded `example.com`, the host in the address. On nightlies 10261 to 10535, clicking a `tel:` link left the page unusable: every later call raised `NoExecutionContextError`. The page now stays and your own click handlers still run. The same applies to any link whose scheme the browser can't load (`sms:`, `ftp:`…).
+
 ## [0.14.1] - 2026-10-12
 
 ### 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