capybara-lightpanda 0.3.0 → 0.4.0

data/lib/capybara/lightpanda/browser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "forwardable"
-require "concurrent-ruby"
 
 module Capybara
   module Lightpanda
@@ -33,12 +32,13 @@ module Capybara
         @started = false
         @page_events_enabled = false
         @modal_messages = []
+        @modal_messages_mutex = Mutex.new
         @modal_handler_installed = false
         @frame_stack = []
-        @frame_locators = []
-        @frames = Concurrent::Hash.new
         @turbo_event = Utils::Event.new
         @turbo_event.set
+        @last_navigation_response = nil
+        @document_request_id = nil
 
         start
       end
@@ -78,20 +78,14 @@ module Capybara
         attach_result = @client.command("Target.attachToTarget", { targetId: @target_id, flatten: true })
         @session_id = attach_result["sessionId"]
 
-        @frames.clear
         @turbo_event.set
         subscribe_to_console_logs
         subscribe_to_execution_context
-        subscribe_to_frame_events
         subscribe_to_turbo_signals
+        subscribe_to_navigation_response
         register_auto_scripts
       end
 
-      def restart
-        quit
-        start
-      end
-
       # Wipe per-session state — cookies, storage, all targets — and start
       # over with a fresh BrowserContext. Mirrors ferrum's Browser#reset:
       # one CDP call (`Target.disposeBrowserContext`) does the work that
@@ -106,15 +100,7 @@ module Capybara
       def reset
         dispose_browser_context
         @client.clear_subscriptions
-        @page_events_enabled = false
-        @modal_handler_installed = false
-        @modal_messages.clear
-        clear_frames
-        # Network#reset, not #clear: disposing the BrowserContext also
-        # destroyed the Network domain and its subscriptions, so we must
-        # flip @enabled back to false — otherwise the next #enable
-        # short-circuits and traffic tracking is silently dead.
-        @network&.reset
+        clear_session_state
         create_browser_context
         create_page
       end
@@ -131,9 +117,30 @@ module Capybara
         @client = Client.new(ws_url, @options)
         # Process may have died; the old browserContextId is gone with it.
         @browser_context_id = nil
+        clear_session_state
         create_browser_context
         create_page
+      end
+
+      # Per-session in-memory state that must be wiped whenever the underlying
+      # CDP connection is replaced (#reset disposes the BrowserContext, #reconnect
+      # builds a fresh Client). Without this, a mid-test process crash leaves
+      # stale frame_stack Nodes (whose objectIds belong to the dead V8 context)
+      # and a `@modal_handler_installed = true` flag that makes prepare_modals
+      # short-circuit on the new client, so find_modal silently sees no
+      # javascriptDialogOpening events.
+      def clear_session_state
         @page_events_enabled = false
+        @modal_handler_installed = false
+        @modal_messages_mutex.synchronize { @modal_messages.clear }
+        @last_navigation_response = nil
+        @document_request_id = nil
+        clear_frames
+        # Network#reset, not #clear: disposing the BrowserContext also
+        # destroyed the Network domain and its subscriptions, so we must
+        # flip @enabled back to false — otherwise the next #enable
+        # short-circuits and traffic tracking is silently dead.
+        @network&.reset
       end
 
       def quit
@@ -247,6 +254,21 @@ module Capybara
       end
       alias html body
 
+      # HTTP status of the last document navigation; nil before the first
+      # navigation completes. Driven by the Network.responseReceived
+      # subscription installed in create_page.
+      def status_code
+        @last_navigation_response&.dig(:status)
+      end
+
+      # Response headers of the last document navigation, wrapped in a Headers
+      # instance so `["Content-Type"]` works despite CDP lowercasing keys.
+      # Returns an empty Headers (not nil) so callers can chain `[]` safely.
+      def response_headers
+        raw = @last_navigation_response&.dig(:headers) || {}
+        Headers.new.tap { |h| raw.each { |k, v| h[k.to_s.downcase] = v } }
+      end
+
       # Evaluate JS and return a serialized value.
       # No-args fast path uses Runtime.evaluate; with args we wrap as a function
       # and dispatch via Runtime.callFunctionOn so `arguments[i]` is bound.
@@ -378,11 +400,15 @@ module Capybara
         page_command("Runtime.getProperties", objectId: remote_object_id, ownProperties: true)
       end
 
-      # Release a remote object reference to free V8 memory.
+      # Release a remote object reference to free V8 memory. Cleanup is
+      # best-effort: callers wrap their work in `ensure release_object(...)`,
+      # so a TimeoutError or transport hiccup here must not propagate out of
+      # the ensure block and bury the original failure.
       def release_object(remote_object_id)
         page_command("Runtime.releaseObject", objectId: remote_object_id)
-      rescue BrowserError
-        # Object may already be released or context destroyed
+      rescue Error
+        # Object may already be released, context destroyed, or the CDP call
+        # itself timed out / failed in transport.
       end
 
       # Find elements in the current context (top frame or active frame).
@@ -397,13 +423,33 @@ module Capybara
 
       # 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)
-        result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, return_by_value: false)
-        extract_node_object_ids(result)
+        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
+
       # objectId of document.activeElement, or nil if none/document detached.
       def active_element
         result = evaluate_with_ref("document.activeElement")
@@ -417,17 +463,6 @@ module Capybara
         page_command("DOM.describeNode", objectId: remote_object_id).dig("node", "backendNodeId")
       end
 
-      def css(selector)
-        node_ids = page_command("DOM.querySelectorAll", nodeId: document_node_id, selector: selector)
-        node_ids["nodeIds"] || []
-      end
-
-      def at_css(selector)
-        result = page_command("DOM.querySelector", nodeId: document_node_id, selector: selector)
-
-        result["nodeId"]
-      end
-
       def screenshot(path: nil, format: :png, quality: nil, full_page: false, encoding: :binary)
         params = { format: format.to_s }
         params[:quality] = quality if quality && format == :jpeg
@@ -462,18 +497,6 @@ module Capybara
         end
       end
 
-      # Wait for any pending Turbo operations to complete. Event-driven: the
-      # injected JS in index.js calls `console.debug('__lightpanda_turbo_busy')`
-      # when the pending-ops counter rises above 0 and `_idle` when it returns
-      # to 0. We toggle @turbo_event accordingly (see subscribe_to_turbo_signals).
-      #
-      # Pages without Turbo never trigger _turboStart, so no sentinels fire and
-      # @turbo_event stays set (initial state) — wait returns immediately. Same
-      # for Turbo-loaded pages that have no pending work.
-      def wait_for_turbo
-        @turbo_event.wait(@options.timeout)
-      end
-
       # Wait for the page to settle after an action that may have kicked off
       # a Turbo fetch OR a full-page navigation. Used by Node#click and
       # Node#implicit_submit so callers can immediately read updated state
@@ -515,52 +538,22 @@ module Capybara
       end
 
       # -- Frame Support --
-      # Two parallel views of frames:
-      #
-      #   * `frame_stack` (Array<Node>) — the Capybara `switch_to_frame` stack;
-      #     drives where `find` resolves selectors. Stored as Nodes so
-      #     callFunctionOn can scope to the iframe's contentDocument.
-      #
-      #   * `@frames` (Concurrent::Hash<String, Frame>) — metadata view
-      #     populated from Page.frame{Attached,Navigated,Detached,...} events.
-      #     Used for diagnostics / introspection (frames, main_frame, frame_by).
-      #     Lightpanda's frame events are not reliable enough to drive
-      #     navigation waits, so this is read-only metadata.
+      # `frame_stack` (Array<Node>) is the Capybara `switch_to_frame` stack;
+      # it drives where `find` resolves selectors. Stored as Nodes so
+      # callFunctionOn can scope to the iframe's contentDocument.
 
       def push_frame(node)
         @frame_stack.push(node)
-        @frame_locators.push(capture_frame_locator(node))
       end
 
       def pop_frame
-        @frame_locators.pop
         @frame_stack.pop
       end
 
       def clear_frames
-        @frame_locators.clear
         @frame_stack.clear
       end
 
-      # All frames currently attached to the page (main frame + iframes).
-      def frames
-        @frames.values
-      end
-
-      # The top-level frame, or nil if it hasn't been registered yet (events
-      # arrive asynchronously after Page.enable).
-      def main_frame
-        @frames.each_value.find(&:main?)
-      end
-
-      def frame_by(id: nil, name: nil)
-        if id
-          @frames[id]
-        elsif name
-          @frames.each_value.find { |f| f.name == name }
-        end
-      end
-
       # -- Modal/Dialog Support --
       # Lightpanda's JS dialogs (alert/confirm/prompt) are driven via the
       # `LP.handleJavaScriptDialog` pre-arm model (PR #2261, nightly ≥5900):
@@ -577,7 +570,8 @@ module Capybara
         enable_page_events
 
         on("Page.javascriptDialogOpening") do |params|
-          @modal_messages << { type: params["type"], message: params["message"] }
+          entry = { type: params["type"], message: params["message"] }
+          @modal_messages_mutex.synchronize { @modal_messages << entry }
         end
 
         @modal_handler_installed = true
@@ -597,34 +591,59 @@ module Capybara
 
       def find_modal(type, text: nil, wait: options.timeout)
         regexp = text.is_a?(Regexp) ? text : (text && Regexp.new(Regexp.escape(text.to_s)))
-        deadline = monotonic_time + wait
-        last_message = nil
-        loop do
-          msg = @modal_messages.find { |m| m[:type] == type.to_s }
-          if msg
-            last_message = msg[:message]
-            if regexp.nil? || last_message.match?(regexp)
-              @modal_messages.delete(msg)
-              return last_message
-            end
-          end
-          break if monotonic_time > deadline
-
-          sleep 0.05
+        last_matching_type_message = nil
+        last_seen_message = nil
+        claimed = nil
+        Utils::Wait.until(timeout: wait, interval: 0.05) do
+          claimed = pop_modal_message(type.to_s, regexp)
+          next true if claimed
+
+          last = peek_last_modal_message(type.to_s)
+          last_matching_type_message = last[:matching_type] || last_matching_type_message
+          last_seen_message = last[:any] || last_seen_message
+          false
         end
-        raise_modal_not_found(text, last_message)
+        claimed[:message]
+      rescue TimeoutError
+        raise_modal_not_found(type, text, last_matching_type_message, last_seen_message)
       end
 
-      def reset_modals
-        @modal_messages.clear
+      private
+
+      # Pop the first queued dialog whose type matches and (when `regexp` is
+      # non-nil) whose message matches the requested pattern. Returns the
+      # entry or nil. Serialized with the message-thread writer.
+      def pop_modal_message(type, regexp)
+        @modal_messages_mutex.synchronize do
+          match = @modal_messages.find do |m|
+            m[:type] == type && (regexp.nil? || m[:message].to_s.match?(regexp))
+          end
+          @modal_messages.delete(match) if match
+          match
+        end
       end
 
-      private
+      # Inspect the queue for diagnostics. Returns the most recent message
+      # of the requested type (if any) AND the most recent message of any
+      # type so the failure message can hint at a type mismatch.
+      def peek_last_modal_message(type)
+        @modal_messages_mutex.synchronize do
+          {
+            matching_type: @modal_messages.reverse.find { |m| m[:type] == type }&.dig(:message),
+            any: @modal_messages.last&.dig(:message),
+          }
+        end
+      end
 
-      def raise_modal_not_found(text, last_message)
-        if last_message
+      def raise_modal_not_found(type, text, matching_type_message, any_message)
+        if matching_type_message
+          raise Capybara::ModalNotFound,
+                "Unable to find modal dialog with #{text} - found '#{matching_type_message}' instead."
+        end
+        if any_message
           raise Capybara::ModalNotFound,
-                "Unable to find modal dialog with #{text} - found '#{last_message}' instead."
+                "Unable to find #{type} modal#{" with #{text}" if text} - " \
+                "a different dialog fired with message '#{any_message}'."
         end
         raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
       end
@@ -683,77 +702,21 @@ module Capybara
       JS
       private_constant :FIND_IN_FRAME_JS
 
-      # Captures identifying attributes of an iframe element at push_frame
-      # time so we can re-resolve it later if its contextId is churned by
-      # lightpanda-io/browser#2400. id/name/src are tried in order; `index`
-      # (position among iframes in the owning document) is the last-resort
-      # fallback when none of the attributes is present.
-      CAPTURE_FRAME_LOCATOR_JS = <<~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 siblings = this.ownerDocument.querySelectorAll('iframe');
-          var index = -1;
-          for (var i = 0; i < siblings.length; i++) {
-            if (siblings[i] === this) { index = i; break; }
+          var nodes = [];
+          var p = this.parentNode;
+          while (p && p !== this.ownerDocument) {
+            nodes.push(p);
+            p = p.parentNode;
           }
-          return {
-            id: this.getAttribute('id'),
-            name: this.getAttribute('name'),
-            src: this.getAttribute('src'),
-            index: index,
-          };
+          return nodes;
         }
       JS
-      private_constant :CAPTURE_FRAME_LOCATOR_JS
-
-      # Picks the iframe inside `this.contentDocument` matching a locator
-      # produced by CAPTURE_FRAME_LOCATOR_JS. Used to re-resolve a nested
-      # iframe element when its parent iframe has just been refreshed.
-      RESOLVE_NESTED_IFRAME_JS = <<~JS
-        function(locator) {
-          var doc;
-          try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
-          if (!doc) return null;
-          var iframes = doc.querySelectorAll('iframe');
-          for (var i = 0; i < iframes.length; i++) {
-            var f = iframes[i];
-            if (locator.id && f.getAttribute('id') === locator.id) return f;
-            if (locator.name && f.getAttribute('name') === locator.name) return f;
-            if (locator.src && f.getAttribute('src') === locator.src) return f;
-          }
-          if (typeof locator.index === 'number' && locator.index >= 0 && locator.index < iframes.length) {
-            return iframes[locator.index];
-          }
-          return null;
-        }
-      JS
-      private_constant :RESOLVE_NESTED_IFRAME_JS
-
-      # Same shape as RESOLVE_NESTED_IFRAME_JS but reads `document` directly
-      # for the top-level case where `this` is unbound (Runtime.evaluate).
-      RESOLVE_ROOT_IFRAME_JS = <<~JS
-        (function(locator) {
-          var iframes = document.querySelectorAll('iframe');
-          for (var i = 0; i < iframes.length; i++) {
-            var f = iframes[i];
-            if (locator.id && f.getAttribute('id') === locator.id) return f;
-            if (locator.name && f.getAttribute('name') === locator.name) return f;
-            if (locator.src && f.getAttribute('src') === locator.src) return f;
-          }
-          if (typeof locator.index === 'number' && locator.index >= 0 && locator.index < iframes.length) {
-            return iframes[locator.index];
-          }
-          return null;
-        })
-      JS
-      private_constant :RESOLVE_ROOT_IFRAME_JS
-
-      # Lightweight stand-in for a Node when refresh_frame_stack! re-resolves
-      # an iframe. The only field anyone reads off frame_stack entries is
-      # remote_object_id (browser.rb find_in_frame, driver.rb frame_url /
-      # frame_title), so a Struct with that one field is sufficient and
-      # avoids constructing real Node instances (which need a Driver ref).
-      FrameRef = Struct.new(:remote_object_id)
-      private_constant :FrameRef
+      private_constant :PARENTS_JS
 
       def find_in_document(method, selector)
         with_default_context_wait do
@@ -790,26 +753,11 @@ module Capybara
       end
 
       def find_in_frame(method, selector)
-        refreshed = false
-        begin
-          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 NoExecutionContextError
-          # Issue #2400: a child iframe navigation re-emits executionContextCreated
-          # for the main-frame V8 context under the child's frameId, churning the
-          # iframe's executionContextId. Our stored remote_object_id is bound to
-          # the old contextId, so callFunctionOn raises "Cannot find context with
-          # specified id". with_default_context_wait can't help — the default
-          # context is fine; only the iframe handle is stale. Re-resolve the
-          # stack from locators captured at push_frame time and retry once.
-          raise if refreshed || !refresh_frame_stack!
-
-          refreshed = true
-          retry
+        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)
@@ -823,84 +771,30 @@ module Capybara
         raise js_error
       end
 
-      # Snapshot iframe identifying attributes at push_frame time so we can
-      # re-find the element after lightpanda-io/browser#2400 churns its
-      # contextId. Returns a Hash on success or nil if the call fails — the
-      # latter blocks refresh attempts for this stack entry but leaves the
-      # original behaviour intact (caller falls through to the upstream
-      # error). Best-effort: never raises.
-      def capture_frame_locator(node)
-        call_function_on(node.remote_object_id, CAPTURE_FRAME_LOCATOR_JS)
-      rescue BrowserError
-        nil
-      end
-
-      # Re-resolve every level of @frame_stack from locators captured at
-      # push_frame time. Replaces stack entries in-place with FrameRef
-      # holders whose objectIds are bound to the current contextId.
-      # Returns true on success, false if any level can't be resolved
-      # (missing locator, iframe removed from DOM, fresh CDP error).
-      # Called from find_in_frame on NoExecutionContextError; failure is
-      # not fatal — the caller re-raises the original error.
-      def refresh_frame_stack!
-        return false if @frame_stack.empty?
-        return false if @frame_locators.any?(&:nil?)
-
-        fresh = []
-        @frame_locators.each_with_index do |locator, level|
-          node = level.zero? ? resolve_root_iframe(locator) : resolve_nested_iframe(fresh.last, locator)
-          return false unless node
-
-          fresh << node
-        end
-
-        @frame_stack.replace(fresh)
-        true
-      rescue BrowserError
-        false
-      end
-
-      def resolve_root_iframe(locator)
-        # Runtime.evaluate doesn't accept call arguments, so inline the
-        # locator as a JSON literal into the invocation expression. The
-        # locator was captured from the browser's own getAttribute reads
-        # at push_frame time, so JSON.generate is safe.
-        expression = "(#{RESOLVE_ROOT_IFRAME_JS})(#{locator.to_json})"
-        result = evaluate_with_ref(expression)
-        return nil unless result && result["objectId"]
-
-        FrameRef.new(result["objectId"])
-      end
-
-      def resolve_nested_iframe(parent, locator)
-        result = call_function_on(parent.remote_object_id, RESOLVE_NESTED_IFRAME_JS, locator,
-                                  return_by_value: false)
-        return nil unless result && result["objectId"]
-
-        FrameRef.new(result["objectId"])
-      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"]
 
-        props = get_object_properties(result["objectId"])
-        properties = props["result"] || []
-
-        ids = properties
-              .select { |p| p["name"] =~ /\A\d+\z/ }
-              .sort_by { |p| p["name"].to_i }
-              .filter_map { |p| p.dig("value", "objectId") }
-
-        release_object(result["objectId"])
-        ids
-      rescue Error
-        []
+        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
 
       def register_auto_scripts
-        page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::JS)
-        page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::POLYFILLS_JS)
+        page_command("Page.addScriptToEvaluateOnNewDocument", source: AutoScripts::JS)
       end
 
       def subscribe_to_console_logs
@@ -945,43 +839,41 @@ module Capybara
         on("Runtime.executionContextsCleared") { @turbo_event.set }
       end
 
-      # Maintain @frames from Page.frame* events. Subscribed once per page
-      # (create_page resets @frames and re-subscribes on a fresh client, so
-      # handlers don't accumulate across reconnects). Loading-state events
-      # are best-effort: Lightpanda's Page.frameStoppedLoading is unreliable
-      # on complex pages (#1801), so we track state for diagnostics only.
-      def subscribe_to_frame_events
-        on("Page.frameAttached") { |params| handle_frame_attached(params) }
-        on("Page.frameNavigated") { |params| handle_frame_navigated(params) }
-        on("Page.frameStartedLoading") { |params| set_frame_state(params["frameId"], :started_loading) }
-        on("Page.frameStoppedLoading") { |params| set_frame_state(params["frameId"], :stopped_loading) }
-        on("Page.frameDetached") { |params| handle_frame_detached(params) }
-      end
+      # Remember the latest top-level navigation response so
+      # `Driver#status_code` / `#response_headers` can answer it. Mirrors the
+      # capybara-playwright-driver page hook that captures
+      # `request.navigation_request?` (lib/capybara/playwright/page.rb#L33-L37);
+      # CDP normally signals "this is the main-document response" via
+      # `Network.responseReceived.type`, but Lightpanda omits that field on
+      # responses (only emits `type` on `Network.requestWillBeSent`). So we
+      # do the matching the long way: capture the document requestId from
+      # `requestWillBeSent {type: "Document"}`, then store the response whose
+      # `requestId` equals it. Re-installed per `create_page` so the new
+      # BrowserContext after `Driver#reset!` starts with a fresh slot.
+      #
+      # Caveat: sending `Network.disable` (e.g. through `driver.network.disable`)
+      # also silences this handler — they share the same CDP toggle.
+      def subscribe_to_navigation_response
+        @last_navigation_response = nil
+        @document_request_id = nil
 
-      def handle_frame_attached(params)
-        parent_id, frame_id = params.values_at("parentFrameId", "frameId")
-        @frames[frame_id] ||= Frame.new(frame_id, parent_id)
-      end
+        on("Network.requestWillBeSent") do |params|
+          next unless params["type"] == "Document"
 
-      def handle_frame_navigated(params)
-        frame_data = params["frame"] || {}
-        frame_id = frame_data["id"]
-        return unless frame_id
+          @document_request_id = params["requestId"]
+          @last_navigation_response = nil
+        end
 
-        frame = @frames[frame_id] ||= Frame.new(frame_id, frame_data["parentId"])
-        frame.name = frame_data["name"]
-        frame.url = frame_data["url"]
-        frame.state = :navigated
-      end
+        on("Network.responseReceived") do |params|
+          next unless params["requestId"] == @document_request_id
 
-      def handle_frame_detached(params)
-        frame = @frames.delete(params["frameId"])
-        frame&.state = :detached
-      end
+          @last_navigation_response = {
+            status: params.dig("response", "status"),
+            headers: params.dig("response", "headers") || {},
+          }
+        end
 
-      def set_frame_state(frame_id, state)
-        frame = @frames[frame_id]
-        frame.state = state if frame
+        command("Network.enable")
       end
 
       # Track default-execution-context availability via Runtime events.
@@ -1036,8 +928,12 @@ module Capybara
       # `unwrap_call_result` so that DOM nodes come back as `{ "__lightpanda_node__" => ... }`
       # hashes the Driver can wrap as Capybara nodes.
       def call_with_args(function_declaration, args, return_by_value: false)
+        # document_object_id returns a fresh RemoteObject handle every call.
+        # Release it on the way out so long-running shared-spec sessions don't
+        # accumulate orphaned V8 handles between resets.
+        doc_oid = document_object_id
         params = {
-          objectId: document_object_id,
+          objectId: doc_oid,
           functionDeclaration: function_declaration,
           returnByValue: return_by_value,
           awaitPromise: true,
@@ -1050,12 +946,18 @@ module Capybara
         end
 
         return_by_value ? handle_evaluate_response(response) : unwrap_call_result(response["result"])
+      ensure
+        release_object(doc_oid) if doc_oid
       end
 
       # Translate a non-by-value Runtime result into a plain Ruby value, surfacing
       # DOM nodes as `{ "__lightpanda_node__" => "..." }` so the Driver can wrap
       # them. The sentinel key (rather than a plain "objectId") prevents
       # misclassifying user JS that legitimately returns `{ objectId: "x" }`.
+      #
+      # When the result carries an objectId we can't unwrap (function, regexp,
+      # date, …), release the handle before falling back to `result["value"]`
+      # so V8 doesn't accumulate orphaned references across long sessions.
       def unwrap_call_result(result)
         return nil if result["type"] == "undefined"
         return nil if result["subtype"] == "null"
@@ -1065,6 +967,8 @@ module Capybara
           return { "__lightpanda_node__" => object_id } if result["subtype"] == "node"
           return serialize_remote_array(object_id) if result["subtype"] == "array"
           return serialize_remote_object(object_id) if result["type"] == "object"
+
+          release_object(object_id)
         end
 
         result["value"]
@@ -1128,17 +1032,14 @@ module Capybara
           rescue DeadBrowserError
             raise
           rescue StandardError
-            # reconnect itself failed (process won't restart, port stuck, etc.)
+            # reconnect itself failed (process won't restart, port stuck, etc.).
+            # Fall through to the raise below — a second immediate reconnect
+            # attempt would just duplicate the failure we already swallowed.
           end
         end
 
         return unless @client.closed?
 
-        begin
-          reconnect
-        rescue StandardError
-          nil
-        end
         raise DeadBrowserError, "Lightpanda crashed navigating to #{url}"
       end
 
@@ -1231,28 +1132,28 @@ module Capybara
       end
 
       # Poll document.readyState as a fallback when Page.loadEventFired
-      # doesn't fire. When starting_url is provided, the poll ignores
+      # doesn't fire (CLAUDE.md rules call this out as load-bearing — do
+      # not remove). When starting_url is provided, the poll ignores
       # readyState values from the old page (e.g. about:blank reports
       # "complete" while the new page is still loading in the background).
       def poll_ready_state(timeout, loaded_event: nil, starting_url: nil)
-        deadline = monotonic_time + timeout
         # Use a short per-evaluation timeout because Lightpanda may block
         # all commands while navigating. Without this, a single evaluate()
         # call would consume the entire @options.timeout, making the poll
         # loop effectively a single attempt.
         poll_cmd_timeout = [timeout / 5.0, 2].max
 
-        loop do
-          break if loaded_event&.set?
-          break if @client.closed?
-          break if page_ready?(poll_cmd_timeout, starting_url)
-          break if monotonic_time > deadline
-
-          sleep 0.1
+        Utils::Wait.until(timeout: timeout, interval: 0.1) do
+          loaded_event&.set? || @client.closed? || page_ready?(poll_cmd_timeout, starting_url)
         end
+      rescue TimeoutError
+        # Expected — readyState fallback exhausted its budget. The caller
+        # (await_navigation) keeps going and lets handle_navigation_crash
+        # decide whether the session is recoverable.
       end
 
       POLL_STATE_JS = "(function(){return{r:document.readyState,u:location.href}})()"
+      private_constant :POLL_STATE_JS
 
       def page_ready?(cmd_timeout, starting_url)
         response = @client.command(