capybara-lightpanda 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f039526ec34b172b3824416cd6b7679720cabcb75455a1c3c46bbf0cc11b5d7b
-  data.tar.gz: '087e752b5baa7d09d43541e90654732e042f28535d53248fab9ab2769f656c01'
+  metadata.gz: a7ec772a2b4254837394ec6705d94c8759e750f0f2ba7ce12ac4d02bfdd30bf5
+  data.tar.gz: a65953b578a45f0f652f0f3dadc2334bfa6db4ae6c6f4d931da4d9730f3656a1
 SHA512:
-  metadata.gz: b2430399381dbcb55f54eafbbb9fb81cc3c4ac5956e4bbc16d5dfe70fb1f347f7f8dfdf60044134c87ae739200911d22e986ce9b4d0a37a2f21ebf74887e50f1
-  data.tar.gz: 500584b0da1e6bd82737e213fdd13e10395334e0c971923e2f7fdcb78758251f36f50361272b66c1838a781bf134b724c7b1cc77761dfb28a9b6cfbd8de65d31
+  metadata.gz: 95af3574b27e16d24845f3bcdacc78779c8a036a81d7ab68870de8fd8bc957b8557a2beb9812f85030e7e1e74d994abf2f0d43e116ebb3c87069c52006012429
+  data.tar.gz: 20bf49585073a9d06e76da5460aeb143d653de2dab9a7d1a11d55b16603e9d956737147d712403416f3a8818967193e3150ebc7ae04dbf248ab52b3c62a40495

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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.

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 = {
@@ -71,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
@@ -145,7 +127,6 @@ module Capybara
           end
 
           File.delete(path)
-          @path = nil
           log("Removed #{path}")
           path
         end
@@ -162,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"
@@ -197,7 +154,6 @@ module Capybara
 
           download_file(url, destination)
           FileUtils.chmod(0o755, destination)
-          @path = destination
 
           destination
         end
@@ -314,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)
@@ -329,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

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # JS dialog handling via Lightpanda's LP.handleJavaScriptDialog
+      # pre-arm model (PR #2261): accept/dismiss are sent BEFORE the
+      # triggering action; Page.javascriptDialogOpening supplies the text.
+      module Modals
+        # -- Modal/Dialog Support --
+        # Lightpanda's JS dialogs (alert/confirm/prompt) are driven via the
+        # `LP.handleJavaScriptDialog` pre-arm model (PR #2261, nightly ≥5900):
+        # the client sends `LP.handleJavaScriptDialog {accept, promptText}`
+        # BEFORE the action that triggers the dialog, and the response is
+        # consumed when the dialog opens. `Page.javascriptDialogOpening` still
+        # fires, so we capture the message text for `find_modal`. Single-shot:
+        # `pending_dialog_response` is one slot, so a second pre-arm before
+        # the first dialog opens overwrites the first.
+
+        def prepare_modals
+          return if @modal_handler_installed
+
+          enable_page_events
+
+          on("Page.javascriptDialogOpening") do |params|
+            entry = { type: params["type"], message: params["message"] }
+            @modal_messages_mutex.synchronize { @modal_messages << entry }
+          end
+
+          @modal_handler_installed = true
+        end
+
+        def accept_modal(_type, text: nil)
+          prepare_modals
+          params = { accept: true }
+          params[:promptText] = text if text
+          page_command("LP.handleJavaScriptDialog", **params)
+        end
+
+        def dismiss_modal(_type)
+          prepare_modals
+          page_command("LP.handleJavaScriptDialog", accept: false)
+        end
+
+        # `type` is accepted for the error message only: like Selenium (where
+        # alert/confirm are indistinguishable) and Cuprite (whose dialog handler
+        # accepts whatever fires), we deliberately do NOT reject a dialog whose
+        # reported type differs from the one Capybara asked for. Real suites
+        # wrap `data-confirm` deletes in `accept_alert` (e.g. solidus admin) and
+        # expect it to work; only the message text is matched.
+        def find_modal(type, text: nil, wait: options.timeout)
+          regexp = text.is_a?(Regexp) ? text : (text && Regexp.new(Regexp.escape(text.to_s)))
+          last_seen_message = nil
+          claimed = nil
+          Utils::Wait.until(timeout: wait, interval: 0.05) do
+            claimed = pop_modal_message(regexp)
+            next true if claimed
+
+            last_seen_message = peek_last_modal_message || last_seen_message
+            false
+          end
+          claimed[:message]
+        rescue TimeoutError
+          raise_modal_not_found(type, text, last_seen_message)
+        end
+
+        private
+
+        # Pop the first queued dialog whose message matches the requested
+        # pattern (any dialog when `regexp` is nil). Returns the entry or nil.
+        # Serialized with the message-thread writer.
+        def pop_modal_message(regexp)
+          @modal_messages_mutex.synchronize do
+            match = @modal_messages.find do |m|
+              regexp.nil? || m[:message].to_s.match?(regexp)
+            end
+            @modal_messages.delete(match) if match
+            match
+          end
+        end
+
+        # Most recent dialog message of any type, for diagnostics.
+        def peek_last_modal_message
+          @modal_messages_mutex.synchronize { @modal_messages.last&.dig(:message) }
+        end
+
+        def raise_modal_not_found(type, text, last_seen_message)
+          if last_seen_message
+            raise Capybara::ModalNotFound,
+                  "Unable to find #{type} modal with #{text} - found '#{last_seen_message}' instead."
+          end
+          raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
+        end
+
+        private :prepare_modals
+      end
+    end
+  end
+end