capybara-lightpanda 0.3.0 → 0.4.0

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

@@ -43,7 +43,7 @@ module Capybara
         end
 
         def closed?
-          @status == :closed
+          @status == :closed || @status == :error
         end
 
         def open?
@@ -102,10 +102,15 @@ module Capybara
           end
 
           @driver.on(:error) do |event|
+            # Do NOT raise here. This callback fires synchronously from
+            # @driver.parse(data) inside the reader thread, which sets
+            # abort_on_exception = true. Raising DeadBrowserError escapes
+            # the reader's narrow IO rescue and aborts the entire Ruby
+            # process. Mark the connection dead and let Client#command
+            # surface DeadBrowserError on its next dispatch via closed?.
+            @logger&.puts("✗ WebSocket error: #{event.message}")
             @status = :error
             @messages.close
-
-            raise DeadBrowserError, "WebSocket error: #{event.message}"
           end
         end
 
@@ -152,10 +157,25 @@ module Capybara
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e
-          warn "Failed to parse WebSocket message: #{e.message}"
+          warn_parse_failure(e.message)
 
           nil
         end
+
+        # Dedupe identical parse-failure warnings per WebSocket instance.
+        # Lightpanda occasionally emits CDP frames that embed a bare
+        # `undefined` token (invalid JSON — see upstream-wishlist.md A41)
+        # and a complex page reproduces the same frame on every load,
+        # which previously flooded test output with one warn per frame.
+        # Surface the first occurrence per unique error so the upstream
+        # regression stays visible, then suppress repeats.
+        def warn_parse_failure(message)
+          @parse_warnings ||= {}
+          return if @parse_warnings[message]
+
+          @parse_warnings[message] = true
+          warn "Failed to parse WebSocket message: #{message}"
+        end
       end
     end
   end

data/lib/capybara/lightpanda/client.rb

@@ -71,6 +71,11 @@ module Capybara
         @ws&.close
         @message_thread&.join(1) || @message_thread&.kill
         @subscriber.clear
+        # Wake any in-flight callers blocked on `pending.value!(timeout)` so
+        # they raise DeadBrowserError immediately (via the `@ws.closed?` check
+        # in #command) instead of stalling for the full @options.timeout — a
+        # 30s freeze per pending command on a dying browser.
+        fail_pending_commands
         @pendings.clear
       end
 
@@ -92,6 +97,14 @@ module Capybara
         @mutex.synchronize { @command_id += 1 }
       end
 
+      # Resolve every pending IVar with nil so blocked callers fall through
+      # `pending.value!(timeout)` immediately. `try_set` is a no-op if the
+      # IVar already carries a real response (race-safe against an in-flight
+      # handle_message that landed just before close).
+      def fail_pending_commands
+        @pendings.each_value { |ivar| ivar.try_set(nil) }
+      end
+
       def start_message_thread
         @message_thread = Thread.new do
           Thread.current.abort_on_exception = true

data/lib/capybara/lightpanda/cookies.rb

@@ -77,7 +77,8 @@ module Capybara
         find { |cookie| cookie.name == name }
       end
 
-      def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, expires: nil)
+      def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, # rubocop:disable Metrics/ParameterLists
+              same_site: nil, expires: nil)
         params = {
           name: name,
           value: value,
@@ -87,6 +88,10 @@ module Capybara
         }
 
         params[:domain] = domain if domain
+        # CDP rejects unknown SameSite values; pass through only the canonical
+        # spec strings ("Strict" / "Lax" / "None") so YAML noise from a hand-
+        # edited file doesn't reach the browser.
+        params[:sameSite] = same_site if %w[Strict Lax None].include?(same_site)
         params[:expires] = expires.to_i if expires
 
         browser.command("Network.setCookie", **params)
@@ -123,7 +128,7 @@ module Capybara
 
       # set() takes keyword args, but YAML round-trips give us a hash with the
       # raw CDP keys (camelCase). Normalize and forward.
-      def restore_cookie(hash)
+      def restore_cookie(hash) # rubocop:disable Metrics/PerceivedComplexity
         attrs = hash.transform_keys(&:to_s)
         params = {
           name: attrs["name"],
@@ -133,6 +138,7 @@ module Capybara
           http_only: attrs["httpOnly"] || false,
         }
         params[:domain] = attrs["domain"] if attrs["domain"]
+        params[:same_site] = attrs["sameSite"] if attrs["sameSite"]
         exp = attrs["expires"]
         params[:expires] = Time.at(exp) if exp.is_a?(Numeric) && exp.positive?
         set(**params)

data/lib/capybara/lightpanda/driver.rb

@@ -10,7 +10,7 @@ module Capybara
 
       attr_reader :app, :options
 
-      delegate %i[current_url title] => :browser
+      delegate %i[current_url title status_code response_headers] => :browser
 
       def initialize(app, options = {})
         super()
@@ -31,6 +31,22 @@ module Capybara
         false
       end
 
+      # Escape hatch to the underlying Browser for callers that need raw CDP
+      # access — e.g. Lightpanda's `LP.*` extensions (`getMarkdown`,
+      # `getSemanticTree`, `detectForms`, …) that aren't worth exposing through
+      # the Capybara DSL. Mirrors `capybara-playwright-driver`'s
+      # `with_playwright_page`. Yields the Browser; returns whatever the block
+      # returns.
+      #
+      #   driver.with_lightpanda_browser do |browser|
+      #     browser.page_command("LP.getMarkdown")
+      #   end
+      def with_lightpanda_browser(&block)
+        raise ArgumentError, "block must be given" unless block
+
+        block.call(browser)
+      end
+
       def visit(url)
         @started = true
         browser.go_to(url)
@@ -189,8 +205,11 @@ module Capybara
 
       def save_screenshot(path, **_options)
         browser.screenshot(path: path)
-      rescue BinaryError, BinaryNotFoundError
-        # Browser can't start (e.g., version too old) — don't crash teardown
+      rescue BinaryError, BinaryNotFoundError, BrowserError, TimeoutError
+        # Browser can't start (version too old), is already dead (DeadBrowserError),
+        # the CDP call timed out, or returned any other CDP-level error. Teardown
+        # screenshots are best-effort — swallow so the real test failure surfaces
+        # instead of a "browser already gone" stack trace.
         nil
       end
 
@@ -221,12 +240,15 @@ module Capybara
       end
 
       # Expanded error list for Capybara retry logic (Cuprite pattern).
+      # MouseEventFailed is in Cuprite's list, but Lightpanda has no
+      # rendering engine and the gem dispatches clicks through JS — the
+      # underlying CDP Input.dispatchMouseEvent path doesn't run, so
+      # MouseEventFailed is never raised.
       def invalid_element_errors
         [
           NodeNotFoundError,
           NoExecutionContextError,
           ObsoleteNode,
-          MouseEventFailed,
         ]
       end
 

data/lib/capybara/lightpanda/element_extension.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Escape hatch onto Capybara::Node::Element so users can reach our driver-level
+# Node (and its remote_object_id, `call`, etc.) without going through
+# `element.base`. Mirrors capybara-playwright-driver's
+# `with_playwright_element_handle` (lib/capybara/playwright/node.rb). The is_a?
+# guard keeps the patch safe when both this gem and another Capybara driver
+# are loaded in the same process.
+module Capybara
+  module Lightpanda
+    module ElementExtension
+      def with_lightpanda_node(&block)
+        raise ArgumentError, "block must be given" unless block
+        raise "#{base.inspect} is not a Capybara::Lightpanda::Node" unless base.is_a?(Capybara::Lightpanda::Node)
+
+        block.call(base)
+      end
+    end
+  end
+end
+Capybara::Node::Element.prepend(Capybara::Lightpanda::ElementExtension)

data/lib/capybara/lightpanda/headers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    # Hash subclass that downcases the lookup key. CDP returns response headers
+    # with lowercased names ("content-type"), but Capybara callers reach for
+    # the canonical casing ("Content-Type"). Mirrors capybara-playwright-driver's
+    # Headers class (lib/capybara/playwright/page.rb).
+    class Headers < Hash
+      def [](key)
+        super(key.to_s.downcase)
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/javascripts/index.js

@@ -84,56 +84,44 @@
     // Page.addScriptToEvaluateOnNewDocument.
 
     // Returns true if `el` is visible per Capybara's semantics. Lightpanda's
-    // UA stylesheet (PR #2294, nightly ≥5918) puts `display:none` on
-    // HEAD/SCRIPT/STYLE/NOSCRIPT/TEMPLATE/TITLE and `[type=hidden]`, and
-    // `[hidden]` / closed-<details> children also resolve to `display:none`
-    // through the cascade — so a single display:none walk catches the
-    // unrendered-element cases without an explicit tag list. `visibility`
-    // and offsetParent stay explicit because they aren't covered by display.
-    // `checkVisibility()` does the parent walk for us when available.
+    // `checkVisibility()` walks ancestors and rejects `display:none` from
+    // inline styles, stylesheets, and the UA sheet (PR #2294 — covers
+    // HEAD/SCRIPT/STYLE/NOSCRIPT/TEMPLATE/TITLE, `[hidden]`, `[type=hidden]`,
+    // closed-<details> children). `visibility:hidden|collapse` is handled
+    // separately because checkVisibility's defaults (per spec) ignore it.
     //
-    // `opts.checkOffsetParent` (default true): when true, also rejects
-    // elements with `offsetParent === null` as a fallback for ancestor
-    // `display:none`. The visible_text walker passes false because it
-    // already short-circuits when descending into hidden subtrees.
-    isVisible: function(el, opts) {
+    // Intentional upstream out-of-scope (upstream-wishlist.md C10):
+    // Lightpanda is a headless agentic browser and deliberately doesn't
+    // load external `<link rel=stylesheet>` or apply `@media` rules to
+    // the cascade, and `matchMedia()` returns false for every query.
+    // Responsive patterns that hide one of two mobile/desktop CTA
+    // duplicates via `@media (min-width: …) { display: none }` leak
+    // both variants past this check — Capybara then raises
+    // `Ambiguous: found 2 elements`. There is no in-gem fix: rebuilding
+    // the CSS cascade in JS would need a CSS parser, sync access to
+    // remote stylesheets, and a real media-query evaluator. Run
+    // cuprite for responsive-UI assertions.
+    isVisible: function(el) {
       if (!el || el.nodeType !== 1) return false;
-      var checkOffsetParent = !opts || opts.checkOffsetParent !== false;
-      var TAG = (el.tagName || '').toUpperCase();
-
       var win = el.ownerDocument.defaultView || window;
       var style = win.getComputedStyle(el);
       if (style.visibility === 'hidden' || style.visibility === 'collapse') return false;
-      if (typeof el.checkVisibility === 'function') {
-        if (!el.checkVisibility()) return false;
-      } else {
-        var node = el;
-        while (node && node.nodeType === 1) {
-          if (win.getComputedStyle(node).display === 'none') return false;
-          node = node.parentElement;
-        }
-      }
-      if (checkOffsetParent && el.offsetParent === null && style.position !== 'fixed' &&
-          TAG !== 'BODY' && TAG !== 'HTML') return false;
-      return true;
+      return el.checkVisibility();
     },
 
     // Returns true if the element is obscured at its center point — i.e.
     // hit-testing elementFromPoint at the center returns something that is
-    // not the element or its descendant. Display:none / visibility:hidden /
-    // [hidden] short-circuit to true because Lightpanda returns a fake
-    // bounding rect for display:none elements.
+    // not the element or its descendant. `visibility:hidden|collapse` is
+    // short-circuited explicitly because those elements still produce a
+    // layout box (so the rect-zero check below can't catch them); every
+    // other "not rendered" case (display:none, [hidden], descendants of
+    // either) falls out naturally because getBoundingClientRect returns
+    // DOMRect{0,0,0,0} for elements with no layout box.
     isObscured: function(el) {
       var doc = el.ownerDocument;
       var win = doc.defaultView || window;
       var style = win.getComputedStyle(el);
-      if (style.display === 'none') return true;
       if (style.visibility === 'hidden' || style.visibility === 'collapse') return true;
-      var anc = el;
-      while (anc && anc.nodeType === 1) {
-        if (anc.hasAttribute && anc.hasAttribute('hidden')) return true;
-        anc = anc.parentNode;
-      }
       var r = el.getBoundingClientRect();
       if (r.width === 0 || r.height === 0) return true;
       var cx = r.left + (r.width / 2);
@@ -163,13 +151,12 @@
       return false;
     },
 
-    // True if the element is the host of a contenteditable region — either
-    // its own isContentEditable is true, or any ancestor has a non-"false"
-    // `contenteditable` attribute. Lightpanda doesn't expose
-    // `isContentEditable` on every element, so we walk ancestors as a
-    // fallback.
+    // True if the element is the host of a contenteditable region: it (or any
+    // ancestor) has a non-"false" `contenteditable` attribute. Lightpanda's
+    // native `HTMLElement.isContentEditable` (PR #2310) is hardwired to return
+    // `false` for every element — it has no caret/keyboard editing pipeline —
+    // so the IDL property is useless here and we walk ancestors ourselves.
     isContentEditable: function(el) {
-      if (el.isContentEditable) return true;
       var n = el;
       while (n && n.nodeType === 1) {
         if (n.hasAttribute && n.hasAttribute('contenteditable')) {
@@ -212,7 +199,7 @@
           return fout;
         }
         if (node.nodeType !== 1) return '';
-        if (!self.isVisible(node, { checkOffsetParent: false })) return '';
+        if (!self.isVisible(node)) return '';
         var tag = (node.tagName || '').toUpperCase();
         if (tag === 'TEXTAREA') return node.value || '';
         if (tag === 'BR') return '\n';

data/lib/capybara/lightpanda/keyboard.rb

@@ -69,6 +69,23 @@ module Capybara
         shift: 8,
       }.freeze
 
+      # US-layout shifted variants of the printable ASCII characters that
+      # don't just upcase. Used by dispatch_modified_char so
+      # send_keys([:shift, "1"]) types "!" instead of "1". Letters fall
+      # through to String#upcase via the default branch.
+      SHIFT_MAP = {
+        "1" => "!", "2" => "@", "3" => "#", "4" => "$", "5" => "%",
+        "6" => "^", "7" => "&", "8" => "*", "9" => "(", "0" => ")",
+        "-" => "_", "=" => "+", "[" => "{", "]" => "}", "\\" => "|",
+        ";" => ":", "'" => "\"", "," => "<", "." => ">", "/" => "?",
+        "`" => "~",
+      }.freeze
+      private_constant :SHIFT_MAP
+
+      def self.shifted(char)
+        SHIFT_MAP[char] || char.upcase
+      end
+
       def initialize(browser)
         @browser = browser
       end
@@ -155,7 +172,7 @@ module Capybara
       end
 
       def dispatch_modified_char(char, modifier_value, modifiers)
-        text = modifiers.include?(:shift) ? char.upcase : char
+        text = modifiers.include?(:shift) ? self.class.shifted(char) : char
         send_key_event("keyDown", { key: text, text: text, unmodifiedText: char }, modifiers: modifier_value)
         send_key_event("keyUp", { key: text }, modifiers: modifier_value)
       end

data/lib/capybara/lightpanda/network.rb

@@ -8,6 +8,7 @@ module Capybara
       def initialize(browser)
         @browser = browser
         @traffic = []
+        @traffic_mutex = Mutex.new
         @enabled = false
         @request_handler = nil
         @response_handler = nil
@@ -35,11 +36,11 @@ module Capybara
       end
 
       def traffic
-        @traffic.dup
+        @traffic_mutex.synchronize { @traffic.dup }
       end
 
       def clear
-        @traffic.clear
+        @traffic_mutex.synchronize { @traffic.clear }
       end
 
       # Wipe local state without sending Network.disable. Called by
@@ -50,61 +51,89 @@ module Capybara
       # cleared the Subscriber first.
       def reset
         unsubscribe
-        @traffic.clear
+        @traffic_mutex.synchronize { @traffic.clear }
         @enabled = false
       end
 
+      # Setting extra headers also lazily enables the Network domain. Without
+      # this, headers were silently ignored until the caller separately ran
+      # `network.enable` (or `wait_for_network_idle`). Cuprite/Ferrum parity.
       def headers=(headers)
+        enable
         @extra_headers = headers
         browser.page_command("Network.setExtraHTTPHeaders", headers: headers)
       end
 
       def add_headers(headers)
+        enable
         @extra_headers = (@extra_headers || {}).merge(headers)
         browser.page_command("Network.setExtraHTTPHeaders", headers: @extra_headers)
       end
 
       def clear_headers
+        enable
         @extra_headers = {}
         browser.page_command("Network.setExtraHTTPHeaders", headers: {})
       end
 
-      def wait_for_idle(timeout: 5, connections: 0) # rubocop:disable Naming/PredicateMethod
-        started_at = Time.now
-
-        while Time.now - started_at < timeout
-          pending = @traffic.count { |t| t[:response].nil? }
-          return true if pending <= connections
+      # Count of in-flight requests (those with no response yet recorded).
+      # Cheap predicate-friendly accessor (ferrum parity).
+      def pending_connections
+        @traffic_mutex.synchronize { @traffic.count { |t| t[:response].nil? } }
+      end
 
-          sleep 0.1
-        end
+      # True when no more than `connections` requests are in-flight.
+      def idle?(connections = 0)
+        pending_connections <= connections
+      end
 
+      def wait_for_idle(timeout: 5, connections: 0)
+        wait_for_idle!(timeout: timeout, connections: connections)
+      rescue TimeoutError
         false
       end
 
+      # Raising variant of #wait_for_idle (ferrum parity). Returns true on
+      # success, raises TimeoutError on timeout so callers that treat the
+      # idle wait as a precondition don't have to remember to check a bool.
+      def wait_for_idle!(timeout: 5, connections: 0) # rubocop:disable Naming/PredicateMethod
+        Utils::Wait.until(
+          timeout: timeout,
+          interval: 0.1,
+          message: "Network did not become idle within #{timeout}s " \
+                   "(pending=#{pending_connections}, allowed=#{connections})"
+        ) { idle?(connections) }
+        true
+      end
+
       private
 
       def subscribe
+        # CDP events arrive on the message thread while wait_for_idle /
+        # pending_connections read from the main thread; serialize all
+        # @traffic mutations and reads through @traffic_mutex.
         @request_handler = lambda do |params|
-          @traffic << {
+          entry = {
             request_id: params["requestId"],
             url: params.dig("request", "url"),
             method: params.dig("request", "method"),
             timestamp: params["timestamp"],
             response: nil,
           }
+          @traffic_mutex.synchronize { @traffic << entry }
         end
 
         @response_handler = lambda do |params|
-          request = @traffic.find { |t| t[:request_id] == params["requestId"] }
-
-          next unless request
-
-          request[:response] = {
-            status: params.dig("response", "status"),
-            headers: params.dig("response", "headers"),
-            mime_type: params.dig("response", "mimeType"),
-          }
+          @traffic_mutex.synchronize do
+            request = @traffic.find { |t| t[:request_id] == params["requestId"] }
+            next unless request
+
+            request[:response] = {
+              status: params.dig("response", "status"),
+              headers: params.dig("response", "headers"),
+              mime_type: params.dig("response", "mimeType"),
+            }
+          end
         end
 
         browser.on("Network.requestWillBeSent", &@request_handler)

data/lib/capybara/lightpanda/node.rb

@@ -14,12 +14,10 @@ module Capybara
       end
 
       def text
-        ensure_connected
         call("function() { return this.textContent }")
       end
 
       def all_text
-        ensure_connected
         filter_text(call("function() { return this.textContent }"))
       end
 
@@ -28,7 +26,6 @@ module Capybara
       # that fail VISIBLE_JS, and emit newlines around block-display elements
       # (the part of innerText behavior we still need).
       def visible_text
-        ensure_connected
         call(VISIBLE_TEXT_JS).to_s
                              .gsub(/\A[[:space:]&&[^\u00A0]]+/, "")
                              .gsub(/[[:space:]&&[^\u00A0]]+\z/, "")
@@ -116,6 +113,17 @@ module Capybara
         call("function() { this.dispatchEvent(new MouseEvent('mouseover', {bubbles: true, cancelable: true})) }")
       end
 
+      # Lightpanda has no rendering engine — `window.scrollTo` / `scrollIntoView`
+      # are no-ops at the browser level, and `getBoundingClientRect` reflects
+      # logical-DOM geometry rather than scroll-aware viewport coords. So
+      # there's nothing to scroll. Silently succeed so callers like
+      # `session.scroll_to(find('#thing'))` (Selenium-flavoured specs leaning
+      # on real layout) don't crash with NotImplementedError; assertions that
+      # depend on post-scroll visibility are already gated by the cuprite
+      # fallback in dual-driver setups.
+      def scroll_to(*); end
+      def scroll_by(*); end
+
       # Dispatch an arbitrary DOM event by name. Mirrors Cuprite's Node#trigger
       # — picks the right Event constructor for known mouse/focus/form names
       # and falls back to a generic Event for everything else (so callers can
@@ -199,6 +207,13 @@ module Capybara
         call(GET_PATH_JS)
       end
 
+      # Ancestor chain from `parentNode` up to (but not including) `document`,
+      # returned as Lightpanda::Node wrappers. Mirrors Cuprite's `Node#parents`.
+      def parents
+        oids = driver.browser.parents_of(@remote_object_id)
+        oids.map { |oid| self.class.new(driver, oid) }
+      end
+
       def find_xpath(selector)
         object_ids = driver.browser.find_within(@remote_object_id, "xpath", selector)
         object_ids.map { |oid| self.class.new(driver, oid) }
@@ -243,19 +258,6 @@ module Capybara
 
       private
 
-      # Capybara's `automatic_reload` re-runs the original query when an element
-      # access raises one of the driver's `invalid_element_errors`. After a DOM
-      # mutation like `replaceWith`, our cached objectId still resolves to the
-      # detached node, so reads succeed (with stale data) and the auto-reload
-      # never fires. Detect detachment via `isConnected` and raise so the
-      # synchronize-loop notices and triggers a re-find.
-      def ensure_connected
-        connected = call("function() { return this.isConnected }")
-        return if connected
-
-        raise ObsoleteNode.new(self, "Node is no longer attached to the document")
-      end
-
       def implicit_submit
         call(IMPLICIT_SUBMIT_JS)
         driver.browser.wait_for_idle
@@ -277,6 +279,10 @@ module Capybara
           call(SET_VALUE_JS, format_time_value(value))
         when "datetime-local"
           call(SET_VALUE_JS, format_datetime_value(value))
+        when "month"
+          call(SET_VALUE_JS, format_month_value(value))
+        when "week"
+          call(SET_VALUE_JS, format_week_value(value))
         else
           fill_text_input(type, value.to_s)
         end
@@ -316,6 +322,22 @@ module Capybara
         value.to_time.strftime("%Y-%m-%dT%H:%M")
       end
 
+      def format_month_value(value)
+        return value.to_s if value.is_a?(String) || !value.respond_to?(:to_date)
+
+        value.to_date.strftime("%Y-%m")
+      end
+
+      # ISO 8601 week-of-year, "%G" giving the ISO week-numbering year so that
+      # the last days of December that belong to week 1 of the next year are
+      # rendered with the correct year. Matches Cuprite's `Node#set` for week
+      # inputs and what the user would type into a `<input type=week>` field.
+      def format_week_value(value)
+        return value.to_s if value.is_a?(String) || !value.respond_to?(:to_date)
+
+        value.to_date.strftime("%G-W%V")
+      end
+
       # `maxlength` only constrains user typing, not direct value assignment, but
       # Selenium-style drivers truncate to match what a user would have ended up
       # with. Honor it explicitly so Capybara-shared specs behave the same.
@@ -345,24 +367,41 @@ module Capybara
       # JS bodies may reference `_lightpanda.*` helpers — they're registered via
       # Page.addScriptToEvaluateOnNewDocument in every document (top frame and
       # iframes alike), so the namespace is available wherever `this` lives.
+      #
+      # The supplied declaration is wrapped with an `isConnected` guard so a
+      # detached node raises ObsoleteNode (in Driver#invalid_element_errors)
+      # instead of returning stale data from V8's still-live reference. After
+      # a DOM mutation like `replaceWith`, the cached objectId still resolves
+      # to the detached node, so reads succeed quietly and Capybara's
+      # automatic_reload never re-runs the original query.
       def call(function_declaration, *args)
+        guarded = wrap_with_attached_guard(function_declaration)
         driver.browser.with_default_context_wait do
-          driver.browser.call_function_on(@remote_object_id, function_declaration, *args)
+          driver.browser.call_function_on(@remote_object_id, guarded, *args)
         end
       rescue JavaScriptError => e
+        if e.message.include?(OBSOLETE_NODE_MARKER)
+          raise ObsoleteNode.new(self, "Node is no longer attached to the document")
+        end
+
         case e.class_name
         when "InvalidSelector"
           raise InvalidSelector.new(e.message, nil, args.first)
         else
           raise
         end
-      rescue BrowserError => e
-        case e.message
-        when /MouseEventFailed/i
-          raise MouseEventFailed.new(self, e.response&.dig("message"))
-        else
-          raise
-        end
+      end
+
+      OBSOLETE_NODE_MARKER = "LIGHTPANDA_OBSOLETE_NODE"
+      private_constant :OBSOLETE_NODE_MARKER
+
+      def wrap_with_attached_guard(function_declaration)
+        <<~JS
+          function() {
+            if (!this.isConnected) throw new Error(#{OBSOLETE_NODE_MARKER.inspect});
+            return (#{function_declaration}).apply(this, arguments);
+          }
+        JS
       end
 
       # We dispatch a `MouseEvent` (not a generic `Event`) because Turbo's link