capybara-lightpanda 0.2.2 → 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,11 +32,13 @@ module Capybara
         @started = false
         @page_events_enabled = false
         @modal_messages = []
+        @modal_messages_mutex = Mutex.new
         @modal_handler_installed = false
         @frame_stack = []
-        @frames = Concurrent::Hash.new
         @turbo_event = Utils::Event.new
         @turbo_event.set
+        @last_navigation_response = nil
+        @document_request_id = nil
 
         start
       end
@@ -77,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
@@ -105,15 +100,7 @@ module Capybara
       def reset
         dispose_browser_context
         @client.clear_subscriptions
-        @page_events_enabled = false
-        @modal_handler_installed = false
-        @modal_messages.clear
-        @frame_stack.clear
-        # 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
@@ -130,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
@@ -153,7 +161,7 @@ module Capybara
         @target_id = nil
         @session_id = nil
         @modal_handler_installed = false
-        @frame_stack.clear
+        clear_frames
       end
 
       def command(method, **params)
@@ -217,11 +225,11 @@ module Capybara
       end
 
       def back
-        wait_for_navigation { execute("history.back()") }
+        wait_for_navigation { navigate_history(-1) }
       end
 
       def forward
-        wait_for_navigation { execute("history.forward()") }
+        wait_for_navigation { navigate_history(+1) }
       end
 
       def refresh
@@ -246,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.
@@ -377,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).
@@ -396,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")
@@ -416,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
@@ -461,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
@@ -514,17 +538,9 @@ 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)
@@ -538,25 +554,6 @@ module Capybara
         @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):
@@ -573,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
@@ -593,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 '#{last_message}' instead."
+                "Unable to find modal dialog with #{text} - found '#{matching_type_message}' instead."
+        end
+        if any_message
+          raise Capybara::ModalNotFound,
+                "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
@@ -632,16 +655,26 @@ module Capybara
       INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
 
       # JS function for finding elements within a node.
-      # Works in any execution context (top frame or iframe). Any throw from
-      # querySelectorAll means the selector is malformed (the spec only allows
-      # SYNTAX_ERR DOMException; Lightpanda's V8 currently throws a generic
-      # Error with messages like "InvalidClassSelector"). Re-throw with the
-      # marker prefix so Ruby converts to InvalidSelector regardless.
+      # Works in any execution context (top frame or iframe). For CSS, any
+      # throw from querySelectorAll means the selector is malformed
+      # (re-throw with the marker prefix so Ruby converts to InvalidSelector).
+      # 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.
       FIND_WITHIN_JS = <<~JS.freeze
         function(method, selector) {
           if (method === 'xpath') {
-            if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, this);
-            return [];
+            try {
+              var r = this.ownerDocument.evaluate(selector, this, null, 7, null);
+              var nodes = [];
+              for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+              return nodes;
+            } catch(e) { return []; }
           }
           try { return Array.from(this.querySelectorAll(selector)); }
           catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
@@ -656,8 +689,12 @@ module Capybara
           try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
           if (!doc) return [];
           if (method === 'xpath') {
-            if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, doc);
-            return [];
+            try {
+              var r = doc.evaluate(selector, doc, null, 7, null);
+              var nodes = [];
+              for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+              return nodes;
+            } catch(e) { return []; }
           }
           try { return Array.from(doc.querySelectorAll(selector)); }
           catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
@@ -665,14 +702,41 @@ module Capybara
       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
+          # XPath parse errors return [] silently to match Capybara's expected
+          # "not found" behavior (see FIND_WITHIN_JS comment above for why).
           js = if method == "xpath"
-                 "(typeof _lightpanda !== 'undefined') ? _lightpanda.xpathFind(#{selector_literal}, document) : []"
+                 <<~XPATH_FIND
+                   (function() {
+                     try {
+                       var r = document.evaluate(#{selector_literal}, document, null, 7, null);
+                       var nodes = [];
+                       for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+                       return nodes;
+                     } catch(e) { return []; }
+                   })()
+                 XPATH_FIND
                else
                  <<~CSS_FIND
                    (function() {
@@ -689,10 +753,12 @@ module Capybara
       end
 
       def find_in_frame(method, selector)
-        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)
+        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
@@ -706,26 +772,29 @@ module Capybara
       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
@@ -770,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.
@@ -861,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,
@@ -875,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"
@@ -890,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"]
@@ -953,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
 
@@ -1012,6 +1088,21 @@ module Capybara
         await_navigation(&)
       end
 
+      # Step the session history by `offset` (-1 = back, +1 = forward) using
+      # native CDP. `Page.getNavigationHistory` returns the entry list and
+      # `currentIndex`; `Page.navigateToHistoryEntry` jumps to the chosen
+      # entry's `id`. No-op when the offset would step past either end so
+      # the behavior matches `history.back()` / `history.forward()` on a
+      # bounded session history.
+      def navigate_history(offset)
+        history = page_command("Page.getNavigationHistory")
+        target_index = history["currentIndex"] + offset
+        entries = history["entries"]
+        return if target_index.negative? || target_index >= entries.length
+
+        page_command("Page.navigateToHistoryEntry", entryId: entries[target_index]["id"])
+      end
+
       # Common navigation lifecycle shared by `wait_for_page_load` (fresh
       # `Page.navigate`) and `wait_for_navigation` (back / forward / reload).
       # Subscribes to Page.loadEventFired, runs the trigger, waits briefly for
@@ -1041,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(