capybara-lightpanda 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f6c1cfdad13de4569b3d79828d9d19848b166e220b6a91329c7c0cb2fa9781
-  data.tar.gz: 2f7c90bb35b746682f5533c9d7ebfe1b64fbf7aea1f53a6c93f563428d9f3b46
+  metadata.gz: c3e05fa2b4d3b676fc6dfdd88fb5c4c65b7c2d84ae979a3c6b2cc6bcfddbd712
+  data.tar.gz: ded427c3ae0148dc351d7b43ade13daf7c4f8aebc1c6492c0480b5a146d116f9
 SHA512:
-  metadata.gz: 1d1632dc29185af1e1d1c594abd7a9fe4b0af584585aa6c6534428d59b23316174db581d901bd7d67430b2e708c664c9c7175918cfeca4d386ba95453816b910
-  data.tar.gz: 76a79eed2e960c294a09c1ee8882014d543c5695cd519d51c3d9560ca7b153b085ae4161f18e2a11a301465b95c0cc71140a269c3c8970c86e93d291430630cb
+  metadata.gz: a7d53b5fa0e8d971ca16b9d82a96b65c313e1663313775959b226f97d530e8c84ee19d33b4ec085983bb5d659ff262de97aa6d2501b24ffe0df25755589dae9b
+  data.tar.gz: c2bf56759b971c045a46a589c0b6bcfa31ee2de84c6f995b62731c973b99dec8b03fb9d10f22c4e4a445673ae3c1659ddfc87dd2ea19a5a32ccc9491097993d6

data/CHANGELOG.md

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

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

@@ -13,8 +13,8 @@ module Capybara
     # a blocking `wait`, the way ferrum's Downloads does.
     #
     # Navigation downloads require Content-Disposition: attachment, not just a
-    # MIME type. New browsers also honor an anchor's download attribute (build
-    # 11097 / 1.1 release line); Node#click lets that native activation finish.
+    # 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 +

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

@@ -92,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;
 }
@@ -116,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

@@ -135,7 +135,7 @@ module Capybara
       end
 
       def click(_keys = [], **_options)
-        call(CLICK_JS, native_anchor_downloads?)
+        call(CLICK_JS)
         driver.browser.wait_for_idle
       end
 
@@ -376,18 +376,6 @@ module Capybara
 
       private
 
-      # Below #4124 a download attribute suppresses native activation entirely,
-      # so the manual navigation is still needed for attachment responses.
-      # The API has no feature marker: keep the floor path through 1.0.x and
-      # enable native download activation on build 11097 / the 1.1 release line.
-      def native_anchor_downloads?
-        browser = driver.browser
-        build = browser.nightly_build
-        return build >= Gem::Version.new("11097") if build
-
-        browser.release && browser.release >= Gem::Version.new("1.1.0")
-      end
-
       def find_hinted(method, selector, hints)
         driver.browser.find_within_hinted(@remote_object_id, method, selector, self.class.hint_spec(**hints))
               .map { |oid, cache| self.class.new(driver, oid, cache, frame_scoped: @frame_scoped) }
@@ -607,7 +595,7 @@ module Capybara
       # 6167 as duplicate `turbo:submit-start` events; the first request
       # gets aborted by the second and Turbo never renders the response.
       CLICK_JS = <<~JS
-        function(nativeAnchorDownloads) {
+        function() {
           var EventCtor = (typeof MouseEvent !== 'undefined') ? MouseEvent : Event;
           // Emulate coordinate hit-testing without a layout engine. In a real
           // browser a pointer click on a container lands on its frontmost
@@ -672,11 +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. Navigating
-          // again cancels it and replaces the document. Keep the complete
-          // synthetic event sequence and its cancellation, but stop here on
-          // browsers that support the download attribute.
-          if (nativeAnchorDownloads && link && link.hasAttribute('download')) 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.16.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.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Navid Emad