capybara-lightpanda 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1c82db6d6a5d5662098021d24688d5ff16592b1cb6de95c2c422307487d91d0
-  data.tar.gz: 0f21620cae5dc33e640712565a64071a47d78e906520770bef8e2aa593b230ca
+  metadata.gz: a7ec772a2b4254837394ec6705d94c8759e750f0f2ba7ce12ac4d02bfdd30bf5
+  data.tar.gz: a65953b578a45f0f652f0f3dadc2334bfa6db4ae6c6f4d931da4d9730f3656a1
 SHA512:
-  metadata.gz: 27f0ce27958fdbb057b68b684429222cae534d0b32f06521608862a6407a5ceb89935cbfeb4ebfee7de70d7d7d78a92a6a36d547ffdae27171bef1a731606728
-  data.tar.gz: 492a709cf1117444126ac9429586dc861af46e8e52d779106478e7d96d4c3aff13c1756f9c6ece4d96f41610e4f79f3b7861d02d11eaf294cbc22594c5d28001
+  metadata.gz: 95af3574b27e16d24845f3bcdacc78779c8a036a81d7ab68870de8fd8bc957b8557a2beb9812f85030e7e1e74d994abf2f0d43e116ebb3c87069c52006012429
+  data.tar.gz: 20bf49585073a9d06e76da5460aeb143d653de2dab9a7d1a11d55b16603e9d956737147d712403416f3a8818967193e3150ebc7ae04dbf248ab52b3c62a40495

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.9.0] - 2026-06-18
+
+### Fixed
+
+- `send_keys(:ctrl, …)` (held or `[:ctrl, "a"]` array form) crashed with `NoMethodError` — `MODIFIERS` advertised `:ctrl` but `KEYS` lacked the entry. Both forms now dispatch Control correctly, and an unknown key symbol raises `ArgumentError` naming the key everywhere.
+- `Driver#headers` no longer reports phantom values after `reset!` — the cached `extra_headers` are cleared with the disposed BrowserContext.
+- A connection reset (RST) during the WebSocket handshake now raises `DeadBrowserError` like the FIN path instead of leaking a raw `Errno::ECONNRESET`.
+- A duplicate CDP response frame for an already-answered command id no longer kills the process (`IVar#try_set` on the message thread).
+
+### Changed
+
+- `Browser` is now composed of include-modules (`Browser::Runtime` / `Finder` / `Navigation` / `Modals` / `Console`) — pure code motion, public API unchanged (verified method-for-method by reflection).
+- The Network CDP domain has a single owner: `Network` captures the navigation response behind `Browser#status_code` / `#response_headers`, and traffic tracking is always on (cleared per `reset`, ferrum parity). `driver.network.disable` now visibly owns the caveat that it freezes status tracking.
+- Port-in-use recovery dispatches on a typed `PortInUseError` (subclass of `ProcessTimeoutError`, so existing rescues keep working) instead of matching the error message; HTTP download failures raise `BinaryError` instead of `BinaryNotFoundError`.
+- `Driver#reset!` rescues the gem's error hierarchy (plus `SystemCallError`/`IOError`) instead of `StandardError`, and warns on respawn — programmer errors no longer degrade into a silent browser restart per test.
+- `Node#shadow_root` routes through the guarded `#call` path: reading the shadow root of a detached host now raises `ObsoleteNode` (handled by Capybara's `automatic_reload`) instead of silently returning stale content.
+- Arrays without modifier symbols passed to `send_keys` now type via `insertText`, consistent with plain strings (previously synthesized per-char keyDown/keyUp).
+
+- No-args `evaluate_script` / `execute_script` send the expression with `replMode: true` (DevTools-console REPL semantics) instead of wrapping it in an IIFE. Top-level `const`/`let` can now be redeclared across calls *and* state persists between calls, matching what users see in the Chrome console. JS exceptions still raise `JavaScriptError`.
+
+### Removed
+
+- Dead internal API swept (pre-1.0 cleanup; none had a caller or documented use): `Binary.run` / `.exec` / `.fetch` / `.version` / `.path` and the `Binary::Result` struct; `Browser#document_node_id`; `Client#ws_url` / `#options` readers; `WebSocket#open?`. Cuprite/Ferrum drop-in surface is deliberately KEPT and documented: `Options#window_size` / `#headless` (accepted, inert) and the never-raised `MouseEventFailed` / `NoSuchPageError` / `StatusError` (peer-taxonomy mirrors so migrated rescue lists keep loading).
+- UPSTREAM_BUGS.md Bug #9 (`requestSubmit()` threw when a listener canceled the SubmitEvent) retired: fixed upstream, verified on the nightly this gem already requires. Contract tests pin both retired bugs in `test/features/upstream_bugs_test.rb`.
+
+## [0.8.0] - 2026-06-12
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6736 (published 2026-06-12). The driver refuses to start against older binaries.
+
+### Added
+
+- `lightpanda:binary:*` rake tasks now load automatically inside Rails apps (via a Railtie), and the "Lightpanda is too old" error suggests a require-the-gem one-liner instead of those rake tasks. The old hint was a dead end: the tasks weren't loaded in Rails apps at all, and even with the Railtie they only exist under `RAILS_ENV=test` when the gem sits in the `:test` Gemfile group. (Found beta-testing a private Rails suite.)
+- `Driver#render` as an alias of `save_screenshot`. capybara-screenshot calls `driver.render(path)` for drivers it doesn't know, so every failing test in a capybara-screenshot suite logged "Screenshot could not be saved: undefined method 'render'" — once per failure.
+- `Driver#headers=` / `#add_headers` / `#headers`, delegating to the existing `Network` support. Cuprite exposes header writers on the driver and real suites call them there (`page.driver.headers = …`).
+- `Cookies#[]` as an alias of `#get` — the Ferrum/Cuprite spelling (`browser.cookies["session_id"]`).
+- `Browser#console_logs` / `#clear_console_logs` — console messages captured since the last session reset, as `{type:, text:, timestamp:, args:}` hashes (driver-internal Turbo sentinels excluded, buffer capped at 1,000 entries). Suites that assert "no JS errors leaked" no longer need to wire a custom Ferrum-style logger: `page.driver.browser.console_logs.select { |m| m[:type] == "error" }`. Note that Lightpanda currently reports both `console.log` and `console.warn` as type `"info"` — filter on `text` when you need to distinguish them.
+
+### Changed
+
+- Modal assertions match dialogs by message text regardless of the alert/confirm/prompt type, like Selenium and Cuprite — `accept_alert` around a `data-confirm` delete button now works.
+- Clicks dispatch the full pointer sequence (mousedown → mouseup → click). Widgets that open on mousedown — select2 v3 dropdowns, for example — now react to `click` / `select_from`.
+- The driver no longer re-dispatches `readystatechange` itself. Lightpanda fires the event natively as of nightly 6736 (lightpanda-io/browser#2708), so the shim added in 0.7.0 became redundant and was removed. Behavior is unchanged for Turbo/Hotwire apps — `turbo:load` still fires on every visit, now from the browser's own event.
+
+### Fixed
+
+- A failed binary download that falls back to a stale cached binary now warns loudly on stderr (with the original error and a re-provision one-liner) instead of logging only under `LIGHTPANDA_DEBUG`. VCR-guarded suites hit this path silently — VCR's blocking error is a `StandardError`, unlike raw WebMock's — and the only visible symptom was a confusing "Lightpanda is too old" error much later.
+- Turbo Streams over ActionCable now connect. Page-initiated WebSocket upgrades carry the document's `Origin` header as of nightly 6736 (lightpanda-io/browser#2710, guaranteed by the new minimum build), so ActionCable's request-forgery protection accepts the connection instead of rejecting it with `Request origin not allowed: nil`. `turbo-cable-stream-source` elements reach `[connected]` and `turbo_stream_for` broadcasts (solid_cable or any adapter) arrive in specs. If you had added `config.action_cable.disable_request_forgery_protection = true` to your test environment to work around this, you can remove it.
+
 ## [0.7.0] - 2026-06-12
 
 ### Changed

data/lib/capybara/lightpanda/auto_scripts.rb

@@ -2,9 +2,35 @@
 
 module Capybara
   module Lightpanda
+    # Assembles the `_lightpanda` bundle injected once per session via
+    # Page.addScriptToEvaluateOnNewDocument (Browser#create_page).
+    #
+    # The bundle is split across plain-declaration source files in
+    # javascripts/ — none of which contain an IIFE or module syntax — so each
+    # file is readable in isolation and parses identically as a classic
+    # browser script and as a `new Function(...)` body (how the Bun harness in
+    # test/js/ loads predicates.js without a build step). This module is the
+    # "linker": it concatenates the parts in order and wraps them in the IIFE
+    # plus the idempotency guard.
     module AutoScripts
-      JS_PATH = File.expand_path("javascripts/index.js", __dir__).freeze
-      JS = File.read(JS_PATH).freeze
+      JS_DIR = File.expand_path("javascripts", __dir__).freeze
+
+      # Order matters: declarations (turbo, predicates) before the wiring
+      # (attach) that reads their names. banner is a leading comment block.
+      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
+      # _pendingTurboOps and desync the busy/idle sentinels console.rb reads).
+      # window._lightpanda is only set by attach.js (last), so the guard
+      # reflects "a previous full run completed".
+      JS = begin
+        body = PARTS.map { |name| File.read(File.join(JS_DIR, name)) }.join("\n")
+        "(function() {\n" \
+        "if (window._lightpanda) return;\n" \
+        "#{body}\n" \
+        "})();\n"
+      end.freeze
     end
   end
 end

data/lib/capybara/lightpanda/binary.rb

@@ -9,20 +9,6 @@ require "uri"
 module Capybara
   module Lightpanda
     class Binary
-      Result = Struct.new(:stdout, :stderr, :status) do
-        def success?
-          status.success?
-        end
-
-        def exit_code
-          status.exitstatus
-        end
-
-        def output
-          stdout.empty? ? stderr : stdout
-        end
-      end
-
       GITHUB_RELEASE_URL = "https://github.com/lightpanda-io/browser/releases/download"
 
       PLATFORMS = {
@@ -33,6 +19,13 @@ module Capybara
 
       DEFAULT_CACHE_TIME = 86_400
 
+      # One-liner that re-provisions the binary from a process with no
+      # HTTP-stubbing loaded (VCR/WebMock guard the test process itself).
+      # Referenced from the stale-fallback warning and BETA_TESTING.md.
+      PROVISION_HINT =
+        "bundle exec ruby -r capybara-lightpanda " \
+        "-e 'Capybara::Lightpanda::Binary.remove; puts Capybara::Lightpanda::Binary.update'"
+
       class << self
         # Set a specific release tag (e.g. "0.3.0") to pin downloads to that
         # release. When nil, the rolling "nightly" tag is used. The pin only
@@ -64,10 +57,6 @@ module Capybara
           yield self
         end
 
-        def path
-          @path ||= update
-        end
-
         # Canonical entrypoint: ensure the binary at install_path is current,
         # download if needed, return its path. Pinned (required_version set)
         # never re-downloads when present. Unpinned re-downloads when older
@@ -96,7 +85,36 @@ module Capybara
             return system_path
           end
 
-          download
+          # Stale-or-absent cache, nothing on PATH: refresh from the network.
+          # If that fails (GitHub 5xx, DNS/connect timeouts, SocketError) but a
+          # usable — if stale — binary is already cached, keep using it rather
+          # than hard-failing. A cold cache (nothing on disk) still surfaces the
+          # error. The MINIMUM_NIGHTLY_BUILD floor is enforced downstream in
+          # Process#start, so a sub-floor binary can't slip in.
+          #
+          # Deliberately StandardError, not Exception: WebMock's
+          # NetConnectNotAllowedError descends from Exception so it propagates
+          # through app rescue blocks by design — a test suite that blocks net
+          # connections SHOULD fail loudly here, not silently fall back. CI
+          # pre-provisions the binary outside that guard instead (real-apps.yml).
+          begin
+            download
+          rescue StandardError => e
+            raise unless File.executable?(destination)
+
+            # Kernel.warn, not log: log() is silent unless LIGHTPANDA_DEBUG or
+            # an explicit logger is set, and this fallback is exactly the
+            # moment the user needs to hear about — a VCR-guarded suite (whose
+            # UnhandledHTTPRequestError is a StandardError, unlike raw
+            # WebMock's Exception) lands here silently, keeps a stale binary,
+            # and later hits a confusing MINIMUM_NIGHTLY_BUILD floor error
+            # with no trace of the blocked download.
+            warn("[capybara-lightpanda] Binary download failed (#{e.class}: #{e.message}); " \
+                 "falling back to the cached binary at #{destination}. " \
+                 "If your suite stubs HTTP (VCR/WebMock), pre-provision from an " \
+                 "unstubbed process: #{PROVISION_HINT}")
+            destination
+          end
         end
 
         # Delete the cached binary. Returns the path that was deleted, or nil
@@ -109,7 +127,6 @@ module Capybara
           end
 
           File.delete(path)
-          @path = nil
           log("Removed #{path}")
           path
         end
@@ -126,30 +143,6 @@ module Capybara
           nil
         end
 
-        def run(*)
-          stdout, stderr, status = Open3.capture3(path, *)
-
-          Result.new(stdout: stdout, stderr: stderr, status: status)
-        rescue Errno::ENOENT
-          raise BinaryNotFoundError, "Lightpanda binary not found"
-        end
-
-        def exec(*)
-          Kernel.exec(path, *)
-        end
-
-        def fetch(url)
-          result = run("fetch", "--dump", url)
-          raise BinaryError, result.stderr unless result.success?
-
-          result.stdout
-        end
-
-        def version
-          result = run("version")
-          result.output.strip
-        end
-
         def download
           binary_name = platform_binary
           tag = required_version || "nightly"
@@ -161,7 +154,6 @@ module Capybara
 
           download_file(url, destination)
           FileUtils.chmod(0o755, destination)
-          @path = destination
 
           destination
         end
@@ -173,9 +165,15 @@ module Capybara
         #   suggest `brew update && brew upgrade lightpanda` (brew pins
         #   each user's binary at install time and doesn't refresh on its
         #   own when the tap publishes a newer nightly).
-        # - Path equals our own cache → suggest the gem's rake tasks; the
-        #   `remove` step is required because `update` honors `cache_time`
-        #   and would otherwise no-op on a too-old-but-not-yet-expired file.
+        # - Path equals our own cache → suggest the require-the-gem one-liner.
+        #   NOT the lightpanda:binary:* rake tasks: in a Rails app the gem
+        #   usually sits in the :test Gemfile group, so the tasks only exist
+        #   under RAILS_ENV=test (the Railtie can't help a plain `bundle exec
+        #   rake` in development), and outside Rails they're never loaded at
+        #   all. The one-liner requires the gem explicitly, so it works from
+        #   any environment. The `remove` step is required because `update`
+        #   honors `cache_time` and would otherwise no-op on a
+        #   too-old-but-not-yet-expired file.
         # - Anything else (user-managed install at a custom path) → keep
         #   the curl-overwrite suggestion, since we don't know how the file
         #   got there.
@@ -183,7 +181,7 @@ module Capybara
           if brew_managed?(binary_path)
             "brew update && brew upgrade lightpanda"
           elsif binary_path == install_path
-            "bundle exec rake lightpanda:binary:remove lightpanda:binary:update"
+            PROVISION_HINT
           else
             "curl -sL #{GITHUB_RELEASE_URL}/nightly/#{platform_binary} " \
               "-o #{binary_path} && chmod +x #{binary_path}"
@@ -272,7 +270,7 @@ module Capybara
         end
 
         def follow_redirects(uri, destination, limit = 10)
-          raise BinaryNotFoundError, "Too many redirects" if limit.zero?
+          raise BinaryError, "Too many redirects" if limit.zero?
 
           http_start(uri) do |http|
             request = Net::HTTP::Get.new(uri)
@@ -287,7 +285,7 @@ module Capybara
                 log("Redirected → #{response['location']}")
                 follow_redirects(URI.parse(response["location"]), destination, limit - 1)
               else
-                raise BinaryNotFoundError, "Failed to download binary: #{response.code} #{response.message}"
+                raise BinaryError, "Failed to download binary: #{response.code} #{response.message}"
               end
             end
           end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # Runtime.consoleAPICalled consumers: the user-facing console_logs
+      # ring buffer, the optional IO-logger stream, and the Turbo
+      # busy/idle sentinel tracking behind Browser#wait_for_idle.
+      module Console
+        # Console messages captured from `Runtime.consoleAPICalled` since the
+        # last `reset` (Turbo-tracker sentinels excluded). Loose hashes, like
+        # Network#traffic: `{type:, text:, timestamp:, args:}` where `type` is
+        # the console method name ("log", "error", "warning", ...), `text` joins
+        # the arguments' primitive values/descriptions, and `args` keeps the raw
+        # CDP RemoteObjects. Lets suites assert on JS console errors
+        # (`browser.console_logs.select { |m| m[:type] == "error" }`) the way
+        # peer drivers do via custom Ferrum loggers.
+        def console_logs
+          @console_logs_mutex.synchronize { @console_logs.dup }
+        end
+
+        def clear_console_logs
+          @console_logs_mutex.synchronize { @console_logs.clear }
+        end
+
+        private
+
+        def subscribe_to_console_logs
+          logger = @options.logger
+          return unless logger
+
+          on("Runtime.consoleAPICalled") do |params|
+            params["args"]&.each do |r|
+              value = r["value"]
+              next if turbo_sentinel?(value)
+
+              logger.puts(value)
+            end
+          end
+        end
+
+        TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
+        private_constant :TURBO_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.
+        def turbo_sentinel?(value)
+          value.is_a?(String) && value.start_with?(TURBO_SENTINEL_PREFIX)
+        end
+
+        # Oldest entries are dropped past this cap so a chatty page can't grow
+        # the buffer unbounded across a long session.
+        CONSOLE_LOGS_LIMIT = 1_000
+
+        # 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. Skips the Turbo
+        # activity-tracker sentinels — they're driver plumbing, not page output.
+        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)
+
+            entry = {
+              type: params["type"],
+              text: args.map { |a| a.fetch("value") { a["description"] }.to_s }.join(" "),
+              timestamp: params["timestamp"],
+              args: args,
+            }
+            @console_logs_mutex.synchronize do
+              @console_logs << entry
+              @console_logs.shift(@console_logs.size - CONSOLE_LOGS_LIMIT) if @console_logs.size > CONSOLE_LOGS_LIMIT
+            end
+          end
+        end
+
+        # Wire @turbo_event to the JS-side _signalTurbo emissions. The JS calls
+        # console.debug('__lightpanda_turbo_busy') / '_idle' on transitions across
+        # zero pending ops; Lightpanda forwards those to Runtime.consoleAPICalled.
+        # Idle → set the event (wakes any waiter); busy → reset.
+        #
+        # On Runtime.executionContextsCleared (navigation), unconditionally set
+        # the event: if we navigated away mid-busy state, no further idle signal
+        # would ever come from the old context, and we'd block for the full
+        # timeout. The new context will signal busy again if Turbo is active.
+        def subscribe_to_turbo_signals
+          on("Runtime.consoleAPICalled") do |params|
+            next unless params["args"].is_a?(Array)
+
+            marker = params["args"].first&.dig("value")
+            next unless turbo_sentinel?(marker)
+
+            case marker
+            when "#{TURBO_SENTINEL_PREFIX}busy" then @turbo_event.reset
+            when "#{TURBO_SENTINEL_PREFIX}idle" then @turbo_event.set
+            end
+          end
+
+          on("Runtime.executionContextsCleared") { @turbo_event.set }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # Element finding in the three dispatch contexts (document, node-
+      # scoped, iframe) plus the shared XPath/CSS find fragments and
+      # InvalidSelector translation.
+      module Finder
+        # Find elements in the current context (top frame or active frame).
+        # Returns an array of remote object ID strings.
+        def find(method, selector)
+          if @frame_stack.empty?
+            find_in_document(method, selector)
+          else
+            find_in_frame(method, selector)
+          end
+        end
+
+        # Find child elements within a specific node.
+        # Returns an array of remote object ID strings.
+        #
+        # Wrapped in `with_default_context_wait` so a click that triggered a
+        # navigation immediately before the find (e.g. a fill_in following a
+        # link that mutated the DOM) doesn't race against
+        # `Runtime.executionContextCreated` and surface as
+        # `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)
+          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)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        # 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.
+        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)
+          end
+        end
+
+        private
+
+        # Sentinel string thrown from FIND_*_JS when querySelectorAll rejects a
+        # malformed selector, so the Ruby side can convert JavaScriptError into
+        # Capybara::Lightpanda::InvalidSelector. Cuprite uses a JS subclass for
+        # the same purpose; a plain prefixed string keeps our inline JS simple.
+        INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
+
+        # The find algorithms exist in three dispatch contexts — element-scoped
+        # (FIND_WITHIN_JS), iframe-scoped (FIND_IN_FRAME_JS), and document-scoped
+        # (find_in_document's Runtime.evaluate fast path) — that differ only in
+        # how the document/root/selector expressions are derived. Each algorithm
+        # is defined ONCE here and instantiated per context via format(), so a
+        # fix (e.g. a new XPath error case) can't silently miss a copy.
+        #
+        # XPath routes through native `Document.evaluate` + `XPathResult`
+        # (Lightpanda PR #2305, in nightly >=6109); on parse error we return
+        # [] silently to match Capybara's internal XPath generator, which
+        # sometimes produces selectors with empty trailing predicates like
+        # `(...)[]` that native rejects but `has_element?` expects to behave
+        # as "not found" rather than raise InvalidSelector.
+        # `XPathResult.ORDERED_NODE_SNAPSHOT_TYPE` is `7` in the spec — inlined
+        # so the JS doesn't depend on the enum being defined as a constant.
+        XPATH_FIND_FRAGMENT = <<~JS
+          try {
+            var r = %<doc>s.evaluate(%<selector>s, %<root>s, null, 7, null);
+            var nodes = [];
+            for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+            return nodes;
+          } catch(e) { return []; }
+        JS
+
+        # For CSS, any throw from querySelectorAll means the selector is
+        # malformed — re-throw with the marker prefix so Ruby converts to
+        # InvalidSelector.
+        CSS_FIND_FRAGMENT = <<~JS.freeze
+          try { return Array.from(%<target>s.querySelectorAll(%<selector>s)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + %<selector>s); }
+        JS
+        private_constant :XPATH_FIND_FRAGMENT, :CSS_FIND_FRAGMENT
+
+        # 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')}
+          }
+        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) {
+            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')}
+          }
+        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.
+        PARENTS_JS = <<~JS
+          function() {
+            var nodes = [];
+            var p = this.parentNode;
+            while (p && p !== this.ownerDocument) {
+              nodes.push(p);
+              p = p.parentNode;
+            }
+            return nodes;
+          }
+        JS
+        private_constant :PARENTS_JS
+
+        def find_in_document(method, selector)
+          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`,
+            # which would inject a bare token into the JS source.
+            selector_literal = selector.to_s.inspect
+            # Same fragments as FIND_WITHIN_JS/FIND_IN_FRAME_JS, instantiated
+            # with the selector embedded as a literal: this hot path keeps its
+            # single Runtime.evaluate round-trip (no document-handle resolution).
+            fragment = if method == "xpath"
+                         format(XPATH_FIND_FRAGMENT, doc: "document", root: "document", selector: selector_literal)
+                       else
+                         format(CSS_FIND_FRAGMENT, target: "document", selector: selector_literal)
+                       end
+            result = evaluate_with_ref("(function() { #{fragment} })()")
+            extract_node_object_ids(result)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        def find_in_frame(method, selector)
+          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,
+                                      return_by_value: false)
+            extract_node_object_ids(result)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        def raise_invalid_selector(js_error, method, selector)
+          if js_error.message.include?(INVALID_SELECTOR_MARKER)
+            raise InvalidSelector.new("Invalid #{method} selector: #{selector.inspect}", method, selector)
+          end
+
+          raise js_error
+        end
+
+        # Extract individual node objectIds from a remote array reference.
+        # `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)
+          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") }
+          rescue Error
+            []
+          ensure
+            release_object(outer_id)
+          end
+        end
+      end
+    end
+  end
+end