capybara-lightpanda 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f039526ec34b172b3824416cd6b7679720cabcb75455a1c3c46bbf0cc11b5d7b
-  data.tar.gz: '087e752b5baa7d09d43541e90654732e042f28535d53248fab9ab2769f656c01'
+  metadata.gz: 11c82a5cc9cde03ae1a231efb72764a35c77beda531118960fb499c209348a3e
+  data.tar.gz: 66f4b3190f2dcc158925fd26e7b7b0590a8460d9789737d8bb08c3d5f9deed6b
 SHA512:
-  metadata.gz: b2430399381dbcb55f54eafbbb9fb81cc3c4ac5956e4bbc16d5dfe70fb1f347f7f8dfdf60044134c87ae739200911d22e986ce9b4d0a37a2f21ebf74887e50f1
-  data.tar.gz: 500584b0da1e6bd82737e213fdd13e10395334e0c971923e2f7fdcb78758251f36f50361272b66c1838a781bf134b724c7b1cc77761dfb28a9b6cfbd8de65d31
+  metadata.gz: 1dc37a8e9df8fb0533718e9aa17f35cb7dc162251a0f5f46e036b054afcbeec2da928277ac3af60ac592493d80357913f1f8d2384d671baa2e802905b6357c09
+  data.tar.gz: 95c360b046406da232e6104fe9cb10aa158fedc2ff4e3cdeaa7c12042bc3bd725d9825bd8e2c730365e46c0f9f884c02c4a523af1ce9e4d582fc5aa760093e99

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [0.10.0] - 2026-08-19
+
+> **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8448 **or a tagged release ≥ 0.3.7**. The driver refuses to start below either floor and tells you which version it found. If you pin the browser (see below), pin `0.3.7` or newer.
+
+### Added
+
+- **Tagged Lightpanda releases are accepted, and can be pinned.** Set `Capybara::Lightpanda::Binary.required_version = "0.3.7"` and the driver downloads that exact release, so CI runs against the same browser every time instead of whatever the rolling nightly is that morning. Pinned binaries live in their own path (`~/.cache/lightpanda/lightpanda-0.3.7`), so several can coexist and a stale nightly can no longer shadow the pin. The docs have a CI recipe, including the pre-provisioning step suites that stub HTTP (VCR/WebMock) need.
+- **File downloads.** When your app sends a file with `Content-Disposition: attachment` (`send_file`, `send_data`), the browser saves it to disk. `page.driver.downloads` lists the completed files, `page.driver.wait_for_download` blocks until in-flight ones finish. Turned on automatically when a destination exists: the new `:save_path` driver option, else `Capybara.save_path`. Responses that rely on MIME type alone (a bare `text/csv` with no `Content-Disposition`) are rendered as a page, not downloaded.
+- **Uncaught JavaScript errors are captured.** `page.driver.browser.page_errors` returns every uncaught exception and unhandled promise rejection from page JS (message, file, line, column, stack). Previously a handler dying on a `TypeError` left `console_logs` empty and the failure surfaced far away as `ElementNotFound`. Kept separate from `console_logs`, which still holds only explicit `console.*` calls.
+- **`raise_on_unhandled_modal` driver option.** A `confirm`/`prompt`/`alert` that opens outside an `accept_*`/`dismiss_*` block used to be silently cancelled by the browser, so a runaway confirm cancelled the action and the spec still passed. The driver now warns on stderr naming the dialog text; with `raise_on_unhandled_modal: true` it raises `Capybara::Lightpanda::UnhandledModalError` from the click or `visit` that opened it. Wrapped dialogs are unaffected.
+- **Window API.** `page.current_window.resize_to(w, h)`, `.size`, `.maximize`, `current_window_handle`/`window_handles`, `switch_to_window` — all single-window (Lightpanda has one page per connection; `open_new_window` says so). One sharp edge: resizing changes `window.innerWidth` and `matchMedia` immediately but does not re-evaluate `@media` for the page already loaded, so **resize, then `visit`** for responsive specs.
+- **The `:window_size` driver option now does something.** It sets the viewport that `window.innerWidth`/`innerHeight`, `matchMedia` and `@media` rules see, so `@media`-gated markup resolves at the size you ask for. Nothing reflows (there is no layout engine), so an element off-viewport is not reported as obscured.
+- **Selenium-named helpers shared across Rails suites work.** `page.driver.browser.logs.get(:browser)` (the "no JS errors" helper), `browser.execute_async_script` (axe-core), `element.native.send_keys(...)`, and `browser.execute_cdp` for raw protocol calls. `browser.switch_to.alert` raises with a message pointing at `accept_confirm`/`accept_alert` — dialogs here are answered before they open, so there is nothing to switch to afterwards.
+- `Node#path` returns an XPath that re-finds the element (Capybara's contract), and `"(: Shadow DOM element - no XPath :)"` for an element inside a shadow root, as Selenium does. `Node#exists?` answers whether a node is still attached without raising.
+- **Intel Macs and arm64 Linux** (Graviton-class CI runners) are supported; Lightpanda publishes binaries for both, the gem just refused to look them up.
+
+### Changed
+
+- **Minimum Lightpanda version raised** (nightly 8448 / release 0.3.7). What that buys your suite: elements hidden by Tailwind v4's layered CSS are correctly invisible; `<form method="dialog">` closes its dialog (the Turbo-confirm pattern in Spree 5's admin) instead of navigating away; `select` reaches options inside `<optgroup>`; pages scheduling more than 512 timers no longer stall; dynamically inserted scripts load and fire `load`/`error` correctly; setting a `<select>` value can no longer crash the browser mid-spec; and non-ASCII download filenames come through intact.
+- **`Element#drop` hands files to the browser** instead of streaming their bytes through the driver, so there is no longer a size ceiling on dropped files and `file.type` is what the browser sniffs. Same call, same behavior for the page. Capybara's own `Element#drop` shared specs now run against the driver.
+- **Visible text is what the browser renders.** `text` uses the browser's own `innerText`, so block breaks, hidden descendants and whitespace match what a real browser reports, instead of the driver's approximation.
+- **Clicking a wrapper element reaches the widget inside it.** A click on a plain container descends to the first interactive child a pointer would have hit, so select2 dropdowns (and similar widgets that bind on an inner node) open when a helper clicks the outer container.
+- **`hover` fires `mouseenter` as well as `mouseover`**, so Stimulus `mouseenter->` actions, Floating UI and tippy menus open. CSS `:hover` rules still do not apply (no pointer state).
+- Default `window_size` is `[1920, 1080]`, Lightpanda's own default, rather than `[1024, 768]`; suites that want the old size pass it explicitly. An invalid `window_size` raises `ArgumentError` at driver construction.
+- Large `execute_script` payloads (axe-core-sized bundles and bigger) no longer drop the connection: the CDP message cap is 100 MiB.
+- More of Capybara's shared specs run and pass, and stay as regression cover: shadow DOM (`#shadow_root` finding/clicking/text), `node #style`/`#matches_style?`, `send_keys` key events, and `fetch`/XHR `FormData` submissions.
+
+### Fixed
+
+- **A redirect no longer stalls `wait_for_network_idle` for the rest of the session.** After any `redirect_to` (post-create, post-login), `page.driver.network.pending_connections` stayed at 1 and every `wait_for_network_idle` burned its full timeout. Redirect chains are tracked correctly now, `network.traffic` shows the 302 and the final 200 on the right URLs, and `status_code` still reports the final page. Regular clicks and visits were never affected.
+- **A pinned browser version was silently ignored** whenever a binary was already cached, so CI kept running the nightly the pin was meant to replace. Pins are now self-verifying (see Added).
+- **An interrupted browser download no longer corrupts the cached binary.** The refresh wrote over the file in place, so a dropped connection left a zero-byte "executable" that the fallback path then handed back as usable. Downloads go to a temp file and are renamed into place atomically.
+
+### Internal
+
+- Docs site resynced with what the gem does; a local `script/real-app` harness boots the real-apps CI targets and captures `console_logs`/`network.traffic` per failing example.
+
+## [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/README.md

@@ -20,6 +20,16 @@ Self-contained — built-in CDP client, no external browser-client gem required.
 
 </div>
 
+## Requirements
+
+| | |
+|---|---|
+| **Ruby** | ≥ 3.3 — CI covers 3.3 and 4.0 |
+| **Capybara** | ≥ 3.0, < 5 |
+| **Platforms** | Linux `x86_64` · Linux `aarch64` · macOS Apple Silicon · macOS Intel · Windows through WSL2 (no native Windows build upstream) |
+
+An unsupported host raises `UnsupportedPlatformError` at boot, naming what it detected — it never fails halfway through a suite.
+
 ## Install
 
 Add this to your `Gemfile` and run `bundle install`:
@@ -44,7 +54,10 @@ driven_by :lightpanda
 > The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
 
 > [!IMPORTANT]
-> Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), but `@media` rules and `window.matchMedia()` evaluate against a fixed 1920×1080 viewport — there is no resize emulation. Any spec whose visibility depends on a non-desktop viewport — for example a mobile-only CTA shown via `@media (max-width: …)` — should stay on Cuprite (or whichever full-browser driver you were already using). The [dual-driver setup](https://navidemad.github.io/capybara-lightpanda/#docs) routes the layout-sensitive minority to Cuprite and the structural majority to Lightpanda for speed.
+> Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), and `@media` / `window.matchMedia()` evaluate against the `window_size` you configure — so a mobile-only CTA gated by `@media (max-width: …)` resolves at the width you ask for. What's missing is *layout*: nothing reflows, `getBoundingClientRect` stays synthetic, and there is no real scroll. Specs that assert on pixel geometry, scrolling, or screenshots — plus the two that catch people out, a second browser tab and a menu revealed purely by CSS `:hover` — should stay on Cuprite (or whichever full-browser driver you were already using). The [per-spec dual-driver setup](https://navidemad.github.io/capybara-lightpanda/docs/#dual-per-spec) routes that minority to Cuprite and the structural majority to Lightpanda for speed.
+
+> [!TIP]
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "0.3.7"`. Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
 
 ## Credits
 

data/lib/capybara/lightpanda/auto_scripts.rb

@@ -2,9 +2,37 @@
 
 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.
+      # turbo.js and errors.js register their listeners at top level and expose
+      # nothing through attach.js, so they only need to run inside the IIFE.
+      PARTS = %w[banner.js turbo.js errors.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,24 +9,21 @@ 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"
 
+      # Upstream publishes all four arch/OS combinations on every channel —
+      # verified 2026-07-26 against the `nightly` tag and release 0.3.6 (the
+      # MINIMUM_RELEASE floor, so any acceptable pin carries them too). Intel
+      # macOS and arm64 Linux were absent here and raised
+      # UnsupportedPlatformError on machines upstream ships a binary for: Intel
+      # MacBooks, and Graviton / arm64 CI runners. normalize_arch folds arm64 ->
+      # aarch64, so the arm64 rows are unreachable defensive duplicates kept for
+      # symmetry with the pre-existing arm64-darwin one.
       PLATFORMS = {
         %w[x86_64 linux] => "lightpanda-x86_64-linux",
+        %w[aarch64 linux] => "lightpanda-aarch64-linux",
+        %w[arm64 linux] => "lightpanda-aarch64-linux",
+        %w[x86_64 darwin] => "lightpanda-x86_64-macos",
         %w[aarch64 darwin] => "lightpanda-aarch64-macos",
         %w[arm64 darwin] => "lightpanda-aarch64-macos",
       }.freeze
@@ -71,10 +68,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 +138,6 @@ module Capybara
           end
 
           File.delete(path)
-          @path = nil
           log("Removed #{path}")
           path
         end
@@ -162,42 +154,45 @@ 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
-
+        # Downloads into a sibling temp file and renames it into place only
+        # once the transfer finished.
+        #
+        # Writing straight to `destination` corrupted a working binary on any
+        # interrupted transfer: File.open(_, "wb") truncates the existing file
+        # the moment the request starts, and truncation KEEPS the mode bits —
+        # so a dropped connection left a partial file that still answered
+        # File.executable? => true. #update's "fall back to the cached binary"
+        # rescue then handed that corpse back as if it were the usable stale
+        # binary, warning as though nothing was wrong. That is the common path,
+        # not an edge case: past cache_time, #update calls #download precisely
+        # when a good binary is already sitting at `destination`.
+        #
+        # rename(2) within one directory is atomic, so a concurrent reader sees
+        # either the old binary or the new one, never a half-written one. The
+        # temp file is a sibling (not Dir.tmpdir) so the rename never crosses a
+        # filesystem, and chmod happens before it so the binary is never
+        # visible non-executable. Two racing downloads get distinct temp names
+        # and both rename a complete file — last writer wins, both are valid.
         def download
           binary_name = platform_binary
           tag = required_version || "nightly"
-          url = "#{GITHUB_RELEASE_URL}/#{tag}/#{binary_name}"
+          url = "#{release_url}/#{tag}/#{binary_name}"
           destination = install_path
 
           log("Downloading #{binary_name} (#{tag}) → #{destination}")
           FileUtils.mkdir_p(File.dirname(destination))
 
-          download_file(url, destination)
-          FileUtils.chmod(0o755, destination)
-          @path = destination
+          # ::Process, not Process — Capybara::Lightpanda::Process would win.
+          temp = "#{destination}.download-#{::Process.pid}"
+          begin
+            download_file(url, temp)
+            FileUtils.chmod(0o755, temp)
+            File.rename(temp, destination)
+          ensure
+            # No-op on success (rename consumed it). ensure, not rescue, so an
+            # Interrupt mid-download cleans up too; rm_f ignores a missing file.
+            FileUtils.rm_f(temp)
+          end
 
           destination
         end
@@ -218,12 +213,20 @@ module Capybara
         #   any environment. The `remove` step is required because `update`
         #   honors `cache_time` and would otherwise no-op on a
         #   too-old-but-not-yet-expired file.
+        # - Path equals our cache AND a pin is set → the version is a deliberate
+        #   choice, so tell the user to raise the pin. The re-provision one-liner
+        #   would be a dead end here: it re-downloads the same pinned release and
+        #   lands on the identical "too old" error.
         # - Anything else (user-managed install at a custom path) → keep
         #   the curl-overwrite suggestion, since we don't know how the file
         #   got there.
         def update_hint(binary_path)
           if brew_managed?(binary_path)
             "brew update && brew upgrade lightpanda"
+          elsif binary_path == install_path && required_version
+            "Capybara::Lightpanda::Binary.required_version is pinned to " \
+              "#{required_version} — raise the pin to a newer release, " \
+              "or unset it to track the rolling nightly."
           elsif binary_path == install_path
             PROVISION_HINT
           else
@@ -247,16 +250,31 @@ module Capybara
 
         # Path the gem writes the downloaded binary to. Honors a
         # user-configured install_dir; otherwise falls back to default_binary_path.
+        #
+        # A pin gets its own filename (`lightpanda-0.3.5`) rather than sharing
+        # the rolling-nightly one. `update` only checks that a file EXISTS at
+        # this path, not which version it holds, so on a shared path a nightly
+        # left over from an earlier run would be accepted as "the pin" — setting
+        # required_version on any machine with a warm cache (every CI runner
+        # restoring a cache, every existing dev checkout) would silently keep
+        # running the nightly it was meant to replace. Version-scoping makes the
+        # pin self-verifying and lets several pins coexist in one cache dir.
         def install_path
-          if @install_dir
-            File.join(@install_dir, "lightpanda")
-          else
-            default_binary_path
-          end
+          dir = @install_dir || File.dirname(default_binary_path)
+          basename = required_version ? "lightpanda-#{required_version}" : "lightpanda"
+
+          File.join(dir, basename)
         end
 
         private
 
+        # Release host, as its own method so tests can point #download at a
+        # local socket and exercise the real streaming writer (which is where
+        # the truncation bug lived) instead of stubbing it out.
+        def release_url
+          GITHUB_RELEASE_URL
+        end
+
         # Detects a Homebrew-managed binary by checking whether `path` is a
         # symlink that resolves into a `/Cellar/` directory — the convention
         # both `/opt/homebrew` (Apple Silicon) and `/usr/local` (Intel /
@@ -314,7 +332,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 +347,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,190 @@
+# 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
+
+        # Uncaught page exceptions and unhandled promise rejections since the
+        # last `reset`: `{kind:, message:, url:, line:, column:, stack:,
+        # timestamp:}`, where `kind` is "error" or "unhandledrejection".
+        #
+        # Deliberately NOT folded into #console_logs. Chrome reports an
+        # uncaught exception through Runtime.exceptionThrown rather than
+        # consoleAPICalled, and Playwright/Puppeteer expose it as `pageerror`
+        # separately from `console` — so a suite that greps console_logs for
+        # errors on those stacks doesn't see exceptions there either. Merging
+        # them would also start failing every suite that already asserts
+        # console_logs holds no errors.
+        #
+        # Lightpanda emits no Runtime.exceptionThrown at all, so the source is
+        # a passive listener pair in javascripts/errors.js reporting over the
+        # console.debug sentinel channel. It sees what reaches `window`:
+        # exceptions a framework catches itself (Stimulus's handleError, any
+        # try/catch) never arrive, and a cross-origin script collapses to
+        # "Script error." with no detail. Partial by construction — but the
+        # alternative is the zero visibility that made the solidus taxon-tree
+        # failure take a hand-injected listener to explain.
+        def page_errors
+          @page_errors_mutex.synchronize { @page_errors.dup }
+        end
+
+        def clear_page_errors
+          @page_errors_mutex.synchronize { @page_errors.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 driver_sentinel?(value)
+
+              logger.puts(value)
+            end
+          end
+        end
+
+        TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
+        private_constant :TURBO_SENTINEL_PREFIX
+
+        PAGE_ERROR_SENTINEL_PREFIX = "__lightpanda_page_error_"
+        private_constant :PAGE_ERROR_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
+
+        # javascripts/errors.js reports uncaught page errors over the same
+        # console.debug channel, prefix + JSON payload.
+        def page_error_sentinel?(value)
+          value.is_a?(String) && value.start_with?(PAGE_ERROR_SENTINEL_PREFIX)
+        end
+
+        # Anything the injected bundle emits for the driver's own benefit. Every
+        # consoleAPICalled consumer filters on this, not on one prefix — missing
+        # a sentinel here leaks driver plumbing into user-facing output.
+        def driver_sentinel?(value)
+          turbo_sentinel?(value) || page_error_sentinel?(value)
+        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. Driver sentinels are
+        # plumbing, not page output: the Turbo ones are dropped, and the
+        # page-error ones are rerouted to @page_errors instead.
+        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)
+
+            if page_error_sentinel?(first)
+              record_page_error(first, params["timestamp"])
+              next
+            end
+
+            entry = {
+              type: params["type"],
+              text: args.map { |a| a.fetch("value") { a["description"] }.to_s }.join(" "),
+              timestamp: params["timestamp"],
+              args: args,
+            }
+            push_capped(@console_logs, @console_logs_mutex, entry, CONSOLE_LOGS_LIMIT)
+          end
+        end
+
+        # Same cap and reasoning as CONSOLE_LOGS_LIMIT: a page erroring inside a
+        # loop (a rejected fetch on an interval) must not grow this unbounded.
+        PAGE_ERRORS_LIMIT = 1_000
+
+        # Parse one `__lightpanda_page_error_<json>` sentinel into @page_errors.
+        # A payload that won't parse is still worth surfacing — dropping it would
+        # turn "the page threw" into silence, which is the whole failure mode
+        # this exists to end — so it lands with the raw text as the message.
+        def record_page_error(sentinel, timestamp)
+          json = sentinel.delete_prefix(PAGE_ERROR_SENTINEL_PREFIX)
+          fields = begin
+            JSON.parse(json)
+          rescue JSON::ParserError
+            { "kind" => "error", "message" => json }
+          end
+
+          entry = {
+            kind: fields["kind"] || "error",
+            message: fields["message"].to_s,
+            url: fields["url"].to_s,
+            line: fields["line"],
+            column: fields["column"],
+            stack: fields["stack"],
+            timestamp: timestamp,
+          }
+          push_capped(@page_errors, @page_errors_mutex, entry, PAGE_ERRORS_LIMIT)
+        end
+
+        def push_capped(buffer, mutex, entry, limit)
+          mutex.synchronize do
+            buffer << entry
+            buffer.shift(buffer.size - limit) if buffer.size > limit
+          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