capybara-lightpanda 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcfaa2e5c56f74e8f6068a969ee03d669d11d49de80ae360fb4a62a96833c8f3
-  data.tar.gz: 3a22106094a7f2de8c3447f9573286e90a4158f25f88b06701cf4540ab9e2147
+  metadata.gz: c3e05fa2b4d3b676fc6dfdd88fb5c4c65b7c2d84ae979a3c6b2cc6bcfddbd712
+  data.tar.gz: ded427c3ae0148dc351d7b43ade13daf7c4f8aebc1c6492c0480b5a146d116f9
 SHA512:
-  metadata.gz: ebf7c506245fdc550ff5ac3bc643dfe6369c4324642bffe8fb4a27f891f009eaaa842effe0bb7386dfc6d50819ad934d0a3df0e7f67e4fb222116baa5a957955
-  data.tar.gz: 2aaef86e3c5a6c1a4e25c3476790352564df15c0b46c18c02745b5999e587a35090ff88837340dec8e00f977a828ec3ce1eaf9a505b10abfb0412e2538cf4d13
+  metadata.gz: a7d53b5fa0e8d971ca16b9d82a96b65c313e1663313775959b226f97d530e8c84ee19d33b4ec085983bb5d659ff262de97aa6d2501b24ffe0df25755589dae9b
+  data.tar.gz: c2bf56759b971c045a46a589c0b6bcfa31ee2de84c6f995b62731c973b99dec8b03fb9d10f22c4e4a445673ae3c1659ddfc87dd2ea19a5a32ccc9491097993d6

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.17.0] - 2026-11-05
+
+> **Update Lightpanda before upgrading.** This release requires Lightpanda **1.0.3** or a nightly build ≥ 11647. The driver refuses anything older and names the version it found. Pin `1.0.3` for a reproducible browser.
+
+### Changed
+
+- **`<a download>` links download natively on Lightpanda 1.0.3.** The driver used to wait for a 1.1 release before letting the browser handle a link's `download` attribute itself, so on 1.0.3 it also went to the link's URL. Every supported browser now handles it natively, and the driver leaves the download to it.
+
+### Fixed
+
+- **`reset_session!` no longer starts a browser just to reset it.** Resetting a session that never opened a page used to launch Lightpanda first. When that launch failed, the reset waited for the full process timeout a second time.
+- **Contenteditable elements are detected as browsers detect them.** `contenteditable="plaintext-only"` now counts as editable. An unrecognised value such as `contenteditable="bogus"` now inherits from its parent instead of making the element editable. A page with `document.designMode = "on"` is editable throughout. SVG elements are ignored. This affects which element a click focuses and where `send_keys` types.
+- **A stalled browser can no longer hang a command past its timeout.** The timeout used to cover only the wait for the reply, so a browser that had stopped reading could hold the call much longer while it was still being sent. Sending and waiting now share one deadline.
+
+## [0.16.0] - 2026-10-26
+
+### Fixed
+
+- **`trigger(:click)` waits for the page it loads.** Calling `element.trigger(:click)` on a link or submit button returned before the new page arrived, so the next step ran against the old page. It now waits the way `click` does.
+- **Clicking a `<a download>` link no longer cancels the download on recent nightlies.** From nightly 11097 (and the upcoming 1.1 release line), Lightpanda starts the download itself when a link has a `download` attribute. The driver then also went to the same URL, which cancelled the download and replaced the page. The driver now leaves the download to the browser. Older browsers behave as before.
+- **`obscured?` sees overlays inside a shadow root.** On browsers that can hit-test inside shadow trees (recent nightlies), an element covered by another element in the same shadow root now counts as obscured; before, it was always reported as not obscured. Older browsers give the same answer as before.
+
 ## [0.15.0] - 2026-10-23
 
 > **Update Lightpanda before upgrading.** This release requires Lightpanda **1.0.2** or a nightly build ≥ 10965. The driver refuses anything older and names the version it found. Pin `1.0.2` for a reproducible browser.

data/README.md

@@ -57,7 +57,7 @@ driven_by :lightpanda
 > 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 can't pass here, nor can the two that catch people out: a second browser tab and a menu revealed purely by CSS `:hover`. See [known limitations](https://navidemad.github.io/capybara-lightpanda/docs/#limits).
 
 > [!TIP]
-> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "1.0.2"` (the tagged release the gem's current floor is pinned to — nightly build 10965 is that release's commit). 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).
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "1.0.3"` (the tagged release the gem's current floor is pinned to — nightly build 11647 is that release's commit). 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/client/web_socket.rb

@@ -5,6 +5,7 @@ require "socket"
 require "websocket/driver"
 
 require_relative "../utils/attempt"
+require_relative "../utils/wait"
 
 module Capybara
   module Lightpanda
@@ -26,17 +27,27 @@ module Capybara
           connect
         end
 
-        # `timeout` bounds how long the browser may go without taking any of
-        # the frame's bytes (see #write); nil falls back to options.timeout.
-        def send_message(message, timeout: nil)
+        # The frame must be sent by `deadline` (monotonic seconds; Client#command
+        # passes the command's own deadline) or within `timeout` seconds; both
+        # nil fall back to options.timeout. A frame still queued behind the
+        # socket lock at the deadline wrote nothing, so it raises TimeoutError
+        # and the connection stays usable; one cut off mid-write kills the
+        # connection (see #write).
+        def send_message(message, timeout: nil, deadline: nil)
           raise DeadBrowserError, "WebSocket is not open" unless @status == :open
 
+          deadline ||= Utils::Wait.deadline(timeout || @options.timeout)
           @logger&.puts("\n\n▶ #{@logger.elapsed_time} #{message}")
-          @driver_mutex.synchronize do
-            @write_timeout = timeout
+          unless acquire_driver_lock?(deadline)
+            raise TimeoutError, "Frame not sent before its deadline: another frame held the socket"
+          end
+
+          begin
+            @write_deadline = deadline
             @driver.text(message)
           ensure
-            @write_timeout = nil
+            @write_deadline = nil
+            @driver_mutex.unlock
           end
         end
 
@@ -65,11 +76,11 @@ module Capybara
         # on Lightpanda's single thread) would block a plain write forever
         # once the frame outgrows the socket buffers, holding the lock that
         # every other command, the reader's parse and #close need — and the
-        # command timeout only starts after the write returns. So the write
-        # gives up once the browser takes no byte for the timeout; the wait
-        # restarts on every partial write, so a slow but moving peer is fine
-        # (ferrum #644). Close and pong frames have no command timeout and
-        # fall back to options.timeout rather than waiting forever.
+        # command would never time out. So the write gives up at the frame's
+        # deadline even when the peer is still taking bytes: a trickling peer
+        # must not hold the lock past the caller's budget (ferrum #644). Close
+        # and pong frames have no command deadline; they give up once the
+        # browser takes no byte for options.timeout.
         def write(data)
           until data.empty?
             written = @socket.write_nonblock(data, exception: false)
@@ -96,7 +107,9 @@ module Capybara
         private
 
         def wait_for_socket(state)
-          timeout = @write_timeout || @options.timeout
+          timeout = @write_deadline ? Utils::Wait.remaining(@write_deadline) : @options.timeout
+          return false if timeout <= 0
+
           state == :wait_readable ? @socket.wait_readable(timeout) : @socket.wait_writable(timeout)
         end
 
@@ -104,10 +117,28 @@ module Capybara
         # mark it dead (the reader and message threads stop, pending commands
         # are released) and close the socket.
         def abandon_stalled_write
-          timeout = @write_timeout || @options.timeout
+          reason = if @write_deadline
+                     "Browser did not take the whole frame before the command's deadline"
+                   else
+                     "Browser accepted no data for #{@options.timeout}s"
+                   end
           mark_dead(:error)
           close_socket
-          raise DeadBrowserError, "Browser accepted no data for #{timeout}s and is likely stuck; connection closed"
+          raise DeadBrowserError, "#{reason} and is likely stuck; connection closed"
+        end
+
+        # Mutex has no timed lock. Poll try_lock with a short capped backoff:
+        # the lock is normally held for one frame write or one parse.
+        def acquire_driver_lock?(deadline)
+          delay = 0.0005
+          until @driver_mutex.try_lock
+            remaining = Utils::Wait.remaining(deadline)
+            return false if remaining <= 0
+
+            sleep([delay, remaining].min)
+            delay = [delay * 2, 0.01].min
+          end
+          true
         end
 
         def close_socket

data/lib/capybara/lightpanda/client.rb

@@ -20,21 +20,26 @@ module Capybara
         start_message_thread
       end
 
+      # `timeout` bounds the whole command: waiting for the socket lock, writing
+      # the frame and waiting for the response all draw on one deadline, so a
+      # slow send can't stretch a command past its budget.
       def command(method, params = {}, async: false, session_id: nil, timeout: nil)
         message = build_message(method, params, session_id: session_id)
         effective_timeout = timeout || @options.timeout
+        deadline = Utils::Wait.deadline(effective_timeout)
 
         if async
-          @ws.send_message(JSON.generate(message), timeout: effective_timeout)
+          @ws.send_message(JSON.generate(message), deadline: deadline)
           return true
         end
 
         pending = Concurrent::IVar.new
         @pendings[message[:id]] = pending
 
-        @ws.send_message(JSON.generate(message), timeout: effective_timeout)
+        @ws.send_message(JSON.generate(message), deadline: deadline)
 
-        response = pending.value!(effective_timeout)
+        # value!(0) still returns a response that landed during the send.
+        response = pending.value!(Utils::Wait.remaining(deadline))
 
         if response.nil?
           raise DeadBrowserError, "Browser closed during #{method}" if @ws.closed?

data/lib/capybara/lightpanda/downloads.rb

@@ -12,10 +12,10 @@ module Capybara
     # `Browser.downloadProgress`. We mirror those into a completed-files list +
     # a blocking `wait`, the way ferrum's Downloads does.
     #
-    # IMPORTANT: the trigger is `Content-Disposition: attachment`, NOT MIME
-    # type. A `text/csv` (or any) response without that header is rendered as a
-    # normal navigation, not downloaded — which is why Capybara's MIME-triggered
-    # `:download` shared spec stays in capybara_skip.
+    # Navigation downloads require Content-Disposition: attachment, not just a
+    # MIME type. The floor also honors an anchor's download attribute (upstream
+    # #4124, 11097); Node#click lets that native activation finish.
+    # Capybara's MIME-only :download shared spec still stays in capybara_skip.
     #
     # Structure deliberately mirrors Network (same browser ref, same mutex +
     # subscribe/unsubscribe lifecycle, same reset-after-disposeBrowserContext

data/lib/capybara/lightpanda/driver.rb

@@ -322,7 +322,14 @@ module Capybara
       # turns programmer errors (e.g. a NoMethodError in browser.rb) into a
       # silent quit-and-respawn on every example with zero signal. The warn
       # keeps repeated respawns visible.
+      #
+      # With no browser (never visited, or the launch itself failed) there is
+      # nothing to reset: `browser` would spawn Lightpanda just to reset it,
+      # and a failed launch would cost a second process timeout in teardown.
+      # The next visit launches as usual.
       def reset!
+        return unless @browser
+
         browser.reset
       rescue Error, SystemCallError, IOError => e
         warn "[capybara-lightpanda] reset! failed (#{e.class}: #{e.message}); respawning browser"

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

@@ -11,6 +11,7 @@ window._lightpanda = {
   isVisible: isVisible,
   isObscured: isObscured,
   isDisabled: isDisabled,
+  contentEditableState: contentEditableState,
   isContentEditable: isContentEditable,
   pointerFocusTarget: pointerFocusTarget,
   visibleText: visibleText,

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

@@ -54,17 +54,24 @@ function isObscured(el) {
   if (cx < 0 || cy < 0 || cx > w || cy > h) return true;
   var hit = doc.elementFromPoint(cx, cy);
   if (!hit) return true;
-  if (hit === el) return false;
-  if (el.contains(hit)) return false;
-  // A hit inside a shadow tree is retargeted to its host, and there is no
-  // ShadowRoot.elementFromPoint to look further, so landing on one of el's own
-  // hosts is the best "not obscured" answer available.
-  var root = el.getRootNode ? el.getRootNode() : doc;
+  // Document hit testing retargets a shadow child to its outermost host.
+  // Check each enclosing shadow tree from the outside in: an inner root must
+  // never let us see through an overlay covering its host in an outer root.
+  var roots = [], root = el.getRootNode ? el.getRootNode() : doc;
   while (root && root !== doc && root.host) {
-    if (hit === root.host) return false;
+    roots.push(root);
     root = root.host.getRootNode();
   }
-  return true;
+  for (var i = roots.length - 1; i >= 0; i--) {
+    root = roots[i];
+    if (hit !== root.host) break;
+    // Older supported builds have no shadow hit testing. A hit on our own
+    // host remains the best available evidence that the child is actionable.
+    if (typeof root.elementFromPoint !== 'function') return false;
+    hit = root.elementFromPoint(cx, cy);
+    if (!hit) return true;
+  }
+  return hit !== el && !el.contains(hit);
 }
 
 // Capybara's `Node#disabled?` is more permissive than CSS `:disabled`:
@@ -85,19 +92,32 @@ function isDisabled(el) {
   return false;
 }
 
-// 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.
+// The element's own contenteditable state: true for the "", "true" and
+// "plaintext-only" values, false for "false", null for inherit (no attribute,
+// an invalid value, or a non-HTML element — the attribute is HTML-only).
+// Mirrors upstream Element.contentEditableState.
+function contentEditableState(el) {
+  if (el.namespaceURI !== 'http://www.w3.org/1999/xhtml') return null;
+  if (!el.hasAttribute || !el.hasAttribute('contenteditable')) return null;
+  var v = (el.getAttribute('contenteditable') || '').toLowerCase();
+  if (v === '' || v === 'true' || v === 'plaintext-only') return true;
+  if (v === 'false') return false;
+  return null;
+}
+
+// True if the element can be edited: the nearest contenteditable attribute in
+// a true or false state decides, then the document's designMode. The native
+// `isContentEditable` agrees from upstream #4210 (11229, in the floor; checked
+// on 1.0.3), but SVG elements have no such getter and pointerFocusTarget needs
+// each element's own state, so the walk stays.
 function isContentEditable(el) {
-  var n = el;
-  while (n && n.nodeType === 1) {
-    if (n.hasAttribute && n.hasAttribute('contenteditable')) {
-      var v = (n.getAttribute('contenteditable') || '').toLowerCase();
-      return v !== 'false';
+  for (var n = el; n; n = n.parentNode) {
+    if (n.nodeType === 1) {
+      var state = contentEditableState(n);
+      if (state !== null) return state;
+    } else if (n.nodeType === 9) {
+      return String(n.designMode).toLowerCase() === 'on';
     }
-    n = n.parentElement;
   }
   return false;
 }
@@ -109,9 +129,15 @@ function isContentEditable(el) {
 // only kind CLICK_JS can dispatch — never runs the focus default, so the
 // driver has to apply it itself or `click` then `page.send_keys` types nowhere.
 function pointerFocusTarget(el) {
+  // A contenteditable attribute in the true state, or the body of a
+  // designMode document (Chrome edits and focuses the body, not <html>).
   function isEditingHost(n) {
-    if (!n.hasAttribute || !n.hasAttribute('contenteditable')) return false;
-    return (n.getAttribute('contenteditable') || '').toLowerCase() !== 'false';
+    var state = contentEditableState(n);
+    if (state !== null) return state;
+    var root = n.parentNode, doc = root && root.parentNode;
+    return (n.tagName || '').toUpperCase() === 'BODY' &&
+      (root.tagName || '').toUpperCase() === 'HTML' &&
+      !!doc && doc.nodeType === 9 && String(doc.designMode).toLowerCase() === 'on';
   }
   function isFocusable(n) {
     if (isDisabled(n)) return false;

data/lib/capybara/lightpanda/node.rb

@@ -178,7 +178,9 @@ module Capybara
       # generic Event for everything else (so callers can fire custom events
       # like `node.trigger('lp:custom')`).
       def trigger(event)
-        call(TRIGGER_JS, event.to_s)
+        name = event.to_s
+        call(TRIGGER_JS, name)
+        driver.browser.wait_for_idle if name == "click"
       end
 
       def set(value, **_options)
@@ -658,6 +660,11 @@ module Capybara
           var external = !!scheme && !/^(https?|about|blob|data|file|javascript)$/i.test(scheme[1]);
           var notCancelled = hit.dispatchEvent(clickEvt);
           if (external || !notCancelled || clickEvt.defaultPrevented) return;
+          // Native activation has already started the download (upstream
+          // #4124, 11097, in the floor). Navigating again cancels it and
+          // replaces the document. Keep the complete synthetic event sequence
+          // and its cancellation, but stop here.
+          if (link && link.hasAttribute('download')) return;
           var tag = hit.tagName;
           // A `javascript:` link never navigates: the click's own activation
           // behavior has already run its code. Assigning it to location.href

data/lib/capybara/lightpanda/process.rb

@@ -302,7 +302,19 @@ module Capybara
       #   #3658 (10657) client rects follow the scroll and
       #     DOM.scrollIntoViewIfNeeded is real — HTML5_DRAG_JS centers the
       #     drop target itself because scrollIntoView ignores `block`.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("10965")
+      #
+      # 2026-11-05 bump 10965 -> 11647 (= release 1.0.3, the new lockstep cap;
+      # the bad-port block #4430 at 11651, CORS exposed headers #4242 at 11663
+      # and the x86_64 macOS CPU baseline #4450 at 11672 stay above it).
+      # Retired or ungated by it:
+      #   #4124 (11097) native anchor downloads — Node#click no longer asks a
+      #     version gate before skipping its own navigation for a download
+      #     link; that gate wanted release 1.1.0 although 1.0.3 carries it.
+      # Rides along: CSS nesting #3962 (10976), blank-page timers #4148
+      # (11012), ShadowRoot hit testing #4184 (11071), same-document
+      # navigateToHistoryEntry #3903 (11113), native isContentEditable #4210
+      # (11229), contenteditable Backspace/Delete/Ctrl+A #4415 (11610).
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("11647")
 
       # Lines of browser output #output keeps (ferrum keeps the same 100).
       OUTPUT_LINES = 100
@@ -314,16 +326,16 @@ module Capybara
       # bare "0.3.6" carrying no commit counter at all, and MINIMUM_NIGHTLY_BUILD
       # has nothing to compare against. Releases are cut from the same trunk, so
       # a release is acceptable exactly when its own commit count clears the
-      # nightly floor. 1.0.2 (2026-10-23) is build 10965 — exactly the nightly
+      # nightly floor. 1.0.3 (2026-11-05) is build 11647 — exactly the nightly
       # floor, which is no accident: the floor was raised *to* the release so
-      # both channels gate the same commit. (1.0.1 = 10641 predates fixes the
+      # both channels gate the same commit. (1.0.2 = 10965 predates fixes the
       # floor exists for.)
       #
       # INVARIANT: every MINIMUM_NIGHTLY_BUILD bump must also move this to the
       # first release containing that build (`git rev-list --count <tag>` in the
       # browser repo tells you). Leaving it behind would let the release channel
       # silently accept a binary the nightly channel rejects.
-      MINIMUM_RELEASE = Gem::Version.new("1.0.2")
+      MINIMUM_RELEASE = Gem::Version.new("1.0.3")
 
       class << self
         # `lightpanda version` prints one of two shapes, and the gem supports

data/lib/capybara/lightpanda/utils/wait.rb

@@ -42,6 +42,16 @@ module Capybara
         def self.monotonic_time
           ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
         end
+
+        # A point `seconds` from now on the monotonic clock.
+        def self.deadline(seconds)
+          monotonic_time + seconds
+        end
+
+        # Seconds left before `deadline`, never negative.
+        def self.remaining(deadline)
+          [deadline - monotonic_time, 0].max
+        end
       end
     end
   end

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.15.0"
+    VERSION = "0.17.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Navid Emad