capybara-simulated 0.8.0 → 0.9.0

data/lib/capybara/simulated/browser.rb

@@ -134,6 +134,11 @@ module Capybara
       # debounce fires" tests (Discourse refetchForSearch / doubled-filter, Avo
       # filters) still observe the intermediate state across several polls.
       FF_TRANSIENT_GUARD_POLLS = (ENV['CSIM_FF_TRANSIENT_GUARD_POLLS'] || '6').to_i
+      # The display the window lives on. Mirrors the JS-side `screen` /
+      # initial `innerWidth` / `innerHeight` (js/src/platform-globals.js)
+      # — the window starts filling it, `resize_to` moves the viewport
+      # off it, and `maximize` / `fullscreen` restore it.
+      SCREEN_SIZE = [1024, 768].freeze
       SETTLE_DRAIN_MS = 32
       SETTLE_MAX_ITER = 10
       # Per-`run_loop_step` task cap (its `maxIter`). Bounds a self-rescheduling
@@ -437,6 +442,8 @@ module Capybara
         # it. Both keyed by realm id, cleared when the last worker exits.
         @sw_clients          = {}
         @sw_realm_controller = {}
+        # The realm holding the focus chain (`note_focused_realm`); nil until a first focus.
+        @focused_realm_id    = nil
         # Cross-isolate MessagePort channels: channel id → {realm:, sw:} endpoints. A port
         # transferred between a client realm and a worker/SW isolate registers both ends here;
         # the browser relays each side's postMessage to the other. Cleared with the workers.
@@ -1006,6 +1013,15 @@ module Capybara
         nil
       end
 
+      # Capybara's `scroll_to(:current, offset: [dx, dy])` routes here — a scroll relative to the
+      # element's current offset, clamped to its scrollable range like a browser does.
+      def scroll_by(handle, dx, dy)
+        tick_real_time
+        ensure_alive_after_tick(handle)
+        dom_call('__csimScrollBy', handle, dx.to_f, dy.to_f)
+        settle
+      end
+
       # Capybara::Driver::Node surface — Node calls `check_stale`
       # before each read, and that advances the virtual clock.
       def all_text(handle)     = text(handle)
@@ -1841,7 +1857,11 @@ module Capybara
         @viewport_width  = w.to_i
         @viewport_height = h.to_i
         invalidate_find_cache
-        @runtime.eval("globalThis.innerWidth = #{@viewport_width}; globalThis.innerHeight = #{@viewport_height};")
+        # One slot for the viewport (`__csimViewport`): `innerWidth` / `innerHeight` are
+        # `[Replaceable]` accessors over it, the `@media` cascade and the layout engine read it
+        # directly, and the setter re-pushes every live frame's content box — a frame lays out
+        # against its container, which just changed size too.
+        @runtime.eval("globalThis.__csimSetViewport(#{@viewport_width}, #{@viewport_height});")
         # Recompute the cascade `@media` rules against the new
         # viewport so visibility checks (Capybara `visible?`,
         # `getComputedStyle().display`) re-reflect mobile-breakpoint
@@ -1861,8 +1881,13 @@ module Capybara
         @runtime.eval("try { (globalThis.dispatchEvent || function(){})(new Event('resize')); } catch (_) {}")
         nil
       end
-      def viewport_width                  ; @viewport_width  || 1024 ; end
-      def viewport_height                 ; @viewport_height || 768  ; end
+      def viewport_width                  ; @viewport_width  || SCREEN_SIZE[0] ; end
+      def viewport_height                 ; @viewport_height || SCREEN_SIZE[1] ; end
+      # What `maximize` / `fullscreen` restore. A driver configured with a viewport is a mobile
+      # session (`default_viewport`, the same channel `reset!` uses to keep it mobile across
+      # resets), and maximizing must not silently promote it to desktop — its "display" is the
+      # viewport it was built with.
+      def screen_size                     ; @default_viewport || SCREEN_SIZE ; end
       # Capybara-initiated `page.go_back` runs from Ruby, not inside a
       # JS call, so it's safe to rebuild the Context synchronously. The
       # `force:` flag bypasses the deferral that `history_go` uses to
@@ -3842,7 +3867,7 @@ module Capybara
       # worker's `__csim_workerPostMessage` host fn closes over its
       # handle and routes outgoing messages onto a shared outbox the
       # main settle drains.
-      def worker_spawn(url, shared: false, service: false, creator_key: nil)
+      def worker_spawn(url, shared: false, service: false, creator_key: nil, realm_id: 0, controller_handle: 0)
         handle       = (@worker_seq += 1)
         target       = resolve_against_current(url.to_s)
         # A worker script from a blob: URL in a DIFFERENT storage partition than this
@@ -3867,11 +3892,37 @@ module Capybara
         return worker_fail(handle, 'Worker script could not be loaded') if target.start_with?('blob:') && body.to_s.empty?
         # Pending until the worker's initial script has run (see @worker_initializing).
         @worker_init_lock.synchronize { @worker_initializing += 1 }
+        # A SERVICE worker may call `clients.matchAll()` while its script is still EVALUATING —
+        # before install, before any inbox drain — so its mirror has to be populated before the
+        # script runs. Snapshot it here, on the main thread that owns the registry, and let
+        # run_worker inject it pre-eval. The FOCUS chain rides along for the same reason
+        # `seed_client_mirror` pairs the two: `focused` is browser state the worker isolate cannot
+        # ask for, so without it an early `matchAll` reports every client unfocused and returns
+        # them in creation rather than focus-first order.
+        seed = service ? {clients: sw_client_records_for(handle), focused: focused_client_ids} : nil
         thread = Thread.new do
           Thread.current.report_on_exception = false
-          run_worker(handle, target, body, inbox, outbox, engine_class, shared: shared, service: service, creator_key: creator_key)
+          run_worker(
+            handle, target, body, inbox, outbox, engine_class,
+            shared:      shared,
+            service:     service,
+            creator_key: creator_key,
+            seed:        seed
+          )
+        end
+        # `service:` marks a SERVICE worker. The client mirror is pushed to every service worker
+        # (a client belongs to the ORIGIN; `controlled` only says whether a given worker controls
+        # it), and a dedicated/shared worker has no client registry to push into.
+        # `realm:` is the browsing context that created this worker — a dedicated worker belongs to
+        # it and is terminated when it is discarded (terminate_realm_workers).
+        @workers[handle] = {thread: thread, inbox: inbox, service: service, realm: realm_id.to_i}
+        # A dedicated / shared worker is a client of its ORIGIN — type 'worker' / 'sharedworker',
+        # frameType 'none' — whether or not a service worker's scope covers its script; only the
+        # `controlled` flag turns on that scope match, exactly as it does for a browsing context.
+        # A service worker is not itself a client of anything.
+        unless service
+          sw_note_worker_client(handle, target, shared, worker_controller_handle(target, shared, controller_handle))
         end
-        @workers[handle] = {thread: thread, inbox: inbox}
         handle
       end
 
@@ -3887,7 +3938,12 @@ module Capybara
       def worker_post_to_worker(handle, data)
         w = @workers[handle.to_i]
         return unless w
+        # Counted globally (what settle reads) AND per worker, so a worker that dies still owing
+        # replies can hand back exactly what it holds. A LISTEN-ONLY worker never answers at all,
+        # so without the per-worker tally its share is only released by the reset that fires when
+        # the LAST worker goes — which never happens while a service worker is registered.
         @worker_in_flight += 1
+        w[:in_flight] = w[:in_flight].to_i + 1
         w[:inbox] << data.to_s
       end
 
@@ -3959,11 +4015,28 @@ module Capybara
       # The active worker handle at an EXACT scope (0 if none) — see __csim_swActiveHandleForScope.
       def sw_active_handle_for_scope(scope) = @sw_registrations[scope.to_s].to_i
 
+      # Does `handle` still control any client? HTML's "try activate" holds an installed worker in
+      # the WAITING slot for exactly as long as the outgoing worker has controllees — that is what
+      # makes `registration.waiting` non-null, which is how every "a new version is available"
+      # banner detects an update.
+      def sw_worker_controls_clients?(handle)
+        h = handle.to_i
+        return false if h.zero?
+
+        @sw_clients.any? {|_id, entry| entry[:handle] == h }
+      end
+
       # Mirror a registration's active-worker handle into Ruby, keyed by its (serialized) scope.
       # Emitted by the client lifecycle at activation; survives rebuild_ctx so a navigation can
       # find its controlling SW even after the destination realm's JS was rebuilt.
       def sw_register_scope(scope, handle)
+        # A service worker we haven't seen before starts with an EMPTY client mirror, and every
+        # context that already existed is one of its clients (a client belongs to the origin).
+        # Gating on "this handle is new" rather than on the registry being empty is what makes a
+        # SECOND registration see them too.
+        fresh = !@sw_registrations.value?(handle.to_i)
         @sw_registrations[scope.to_s] = handle.to_i
+        seed_client_mirror(handle.to_i) if fresh
         # Flush any clients.claim() that arrived before this scope was mirrored (a worker's
         # `activate → clients.claim()` fires decoupled from the client-side lifecycle that populates
         # @sw_registrations, so the claim can be drained first — see the claim handler above).
@@ -3974,6 +4047,48 @@ module Capybara
         nil
       end
 
+      # Every known client as `handle` sees it — `controlled` is per-worker, so it is decided here
+      # rather than at each call site.
+      private def sw_client_records_for(handle)
+        @sw_clients.each_value.map {|entry| entry[:rec].merge('controlled' => entry[:handle] == handle) }
+      end
+
+      # Fill a newly-registered service worker's client mirror. Two sources, because a client's
+      # record has two possible authors: a browsing context describes ITSELF (only the realm knows
+      # its URL / frame type / controller), while a worker client has no such voice and is only in
+      # the host registry. Replay the registry first, then ask the realms — a realm's own report
+      # simply refreshes its record.
+      private def seed_client_mirror(handle)
+        if (w = @workers[handle])
+          sw_client_records_for(handle).each do |rec|
+            w[:inbox] << {kind: 'client_register', client: rec}
+          end
+          focused = focused_client_ids
+          w[:inbox] << {kind: 'client_focus', ids: focused} if focused.any?
+        end
+        request_client_reports
+      end
+
+      # Ask every live browsing context to announce itself as a service-worker client. Each realm
+      # reports its own URL / frame type / controller (js/src/sw-client.js), so nothing here has
+      # to model what a realm is — the same broadcast shape as a claim.
+      private def request_client_reports = broadcast_to_realms('__csim_swReportClient')
+
+      # Call a host fn in EVERY live browsing context — the main realm and each frame/window realm.
+      # Service-worker registration state is per-realm (each has its own registration objects), so
+      # anything that changes it has to reach all of them.
+      private def broadcast_to_realms(fn, *args)
+        @runtime.call(fn, *args) rescue nil
+        return nil unless @runtime.respond_to?(:frame_realm_ids)
+
+        @runtime.frame_realm_ids.each do |rid|
+          @runtime.realm_call(rid, fn, *args) if @runtime.frame_realm_alive?(rid)
+        rescue StandardError
+          nil
+        end
+        nil
+      end
+
       # Deliver a clients.claim() to EVERY in-scope client: broadcast to the main realm AND every
       # frame realm; each self-checks whether its own document is in the claiming registration's
       # scope (__csim_swClaimClient) so no realm→URL map is needed here. has_fetch = the SW's
@@ -4049,6 +4164,56 @@ module Capybara
         [handle, w[:has_fetch] != false, w[:script_url].to_s, scope]
       end
 
+      # The handle of the service worker controlling a newly spawned worker, or nil.
+      #
+      # A worker with a REAL script URL is matched against registration scopes like any other
+      # client, whatever its creator is doing: clients-matchall-client-types creates its dedicated
+      # worker from the (out-of-scope, uncontrolled) top-level page and still expects a plain
+      # `matchAll({type: 'worker'})` to return it.
+      #
+      # A blob: / data: script URL is OPAQUE — a UUID no scope could ever cover — so such a worker
+      # takes its creator's controller instead (clients-matchall-blob-url-worker: controlled when
+      # an in-scope frame creates it, uncontrolled when an out-of-scope page does). That has to be
+      # the creating realm's LIVE controller, handed over at `new Worker(…)` time: control usually
+      # arrives after load via `clients.claim()`, so a controller snapshotted when the realm was
+      # BUILT is stale by then, and would report such a worker uncontrolled.
+      private def worker_controller_handle(url, shared, creator_controller)
+        return sw_client_controller_for(url)&.first if url.to_s.match?(%r{\Ahttps?://}i)
+        # A SHARED worker has no single creating context to inherit from.
+        return nil if shared
+
+        h = creator_controller.to_i
+        h.zero? || !@workers[h] ? nil : h
+      end
+
+      # Terminate every dedicated / shared worker a discarded browsing context created. A worker
+      # is owned by its creating context: when that context goes away the worker is terminated,
+      # so it must stop being a service-worker client too (worker_terminate unregisters it).
+      # Without this a frame's worker outlives its frame — a leaked thread AND a leaked client.
+      def terminate_realm_workers(realm_id)
+        rid = realm_id.to_i
+        return nil if rid.zero?
+
+        @workers.select {|_h, w| w[:realm] == rid && !w[:service] }.each do |handle, w|
+          # Everything `worker_terminate` does EXCEPT waiting for the thread. That wait is two
+          # blocking joins with a `Thread#kill` between them, and this runs on the frame-disposal
+          # path — which a frame-heavy app takes on every navigation, so a join here is a
+          # per-navigation stall on the main thread (rule 3). Asking the worker to stop is enough:
+          # it breaks its own poll loop and the thread exits on its own.
+          # The reap must still happen, and happen HERE: it releases the reply-pending counters the
+          # worker still holds and resets them once the last worker is gone, without which
+          # `polling?` stays true for the rest of the session.
+          @workers.delete(handle)
+          detach_worker(handle, w)
+          # Racing the still-live thread is benign: a fallback reply it also answers is dropped
+          # (the client's pending-fetch entry is one-shot), and the only real cost is that a blob
+          # URL minted in the moment between the revoke and the thread noticing `:terminate` can
+          # leak — far cheaper than stalling every navigation.
+          reap_worker(handle, w)
+        end
+        nil
+      end
+
       # The controller an OPAQUE child browsing context (about:blank / srcdoc)
       # inherits from its creator. An about:blank document has no URL to scope-match,
       # so it's controlled by its parent's active service worker (HTML "create and
@@ -4071,29 +4236,248 @@ module Capybara
         nil
       end
 
-      # Register a controlled client (a frame/window realm) with its controlling SW
-      # so `clients.matchAll()` / `getClientByURL` reflect the real client set — not
-      # only clients that happened to postMessage the worker. The client id is
-      # realm-scoped (`client-<realm>`), stable for the realm's life. Pushed to the
-      # SW inbox (processed FIFO, so it precedes any later message that matchAll's it).
-      def sw_register_client(realm_id, url, type, frame_type, handle)
-        w = @workers[handle.to_i] or return
-        rec = {'id' => "client-#{realm_id.to_i}", 'url' => url.to_s, 'type' => type.to_s, 'frameType' => frame_type.to_s}
-        @sw_clients[realm_id.to_i] = {handle: handle.to_i, rec: rec}
-        w[:inbox] << {kind: 'client_register', client: rec}
+      # Every live service worker's handle. A service-worker client belongs to the ORIGIN, not
+      # to one registration — `matchAll({includeUncontrolled: true})` must see contexts this
+      # worker doesn't control — so the client mirror goes to all of them.
+      private def sw_worker_handles = @workers.select {|_h, w| w[:service] }.keys
+
+      # Mirror a browsing context into every service worker's client set. `controller_handle` is
+      # the worker that CONTROLS it, or nil for an uncontrolled context — and `controlled` is
+      # per-worker, since a client controlled by worker A is genuinely uncontrolled from B's
+      # point of view. Reported by the realm itself (js/src/sw-client.js) at document load and
+      # whenever control is installed, because only the realm knows its own URL and frame type.
+      # The client id is realm-scoped and stable for the realm's life. Pushed to the SW inbox,
+      # which is FIFO, so it precedes any later message that matchAll's it.
+      def sw_note_client(realm_id, url, frame_type, controller_handle = nil)
+        note_client(sw_client_id(realm_id), url, 'window', frame_type, controller_handle)
+      end
+
+      # A dedicated / shared WORKER that a service worker controls is a client too — with no
+      # visibilityState or focus (those are WindowClient's), `frameType` 'none', and its script
+      # URL. Keyed by worker handle, which outlives nothing else and is unique per worker.
+      def sw_note_worker_client(handle, url, shared, controller_handle)
+        note_client(sw_worker_client_id(handle), url, shared ? 'sharedworker' : 'worker', 'none', controller_handle)
+      end
+
+      private def note_client(client_id, url, type, frame_type, controller_handle)
+        ctrl = controller_handle.to_i
+        ctrl = nil if ctrl.zero?
+        rec  = {'id' => client_id, 'url' => url.to_s, 'type' => type.to_s, 'frameType' => frame_type.to_s}
+        @sw_clients[client_id] = {handle: ctrl, rec: rec}
+        focused = focused_client_ids
+        sw_worker_handles.each do |h|
+          w = @workers[h] or next
+          # A re-registration with the same id refreshes the record, so a client that CHANGES
+          # controller needs no explicit removal: every worker is told, and the one that lost it
+          # simply learns `controlled` is now false.
+          w[:inbox] << {kind: 'client_register', client: rec.merge('controlled' => h == ctrl)}
+          # A client arriving after focus already moved needs the current id too — `client_focus`
+          # is only pushed on CHANGE, so this worker would otherwise never learn about it.
+          w[:inbox] << {kind: 'client_focus', ids: focused} if focused.any?
+        end
+        nil
+      end
+
+      # Navigate a client's browsing context on behalf of `WindowClient.navigate()`, then answer the
+      # worker waiting on it. The reply carries where the client ENDED UP:
+      #   url   — the final URL, when the result is same-origin (the promise resolves with the client)
+      #   ''    — the result is CROSS-ORIGIN, which the spec resolves with null rather than handing
+      #           back a client this worker has no business seeing
+      #   error — the navigation was refused (mixed content, or a context we can't navigate), a
+      #           TypeError rejection
+      # MIXED CONTENT is checked here rather than JS-side because "is this a secure context" is the
+      # host's knowledge: an https client may not be navigated to http.
+      # Queued, not performed here: `deliver_worker_messages` runs inside the `@ticking` guard, and
+      # navigating rebuilds a realm (a top-level one rebuilds the whole context). Doing that
+      # mid-drain would pull the rug from under the rest of the batch — the sw_msgs / claims /
+      # fetch_resps still to be delivered would address realms that no longer exist — and from any
+      # node handle an in-flight find is holding. `drain_pending_navigation` is where every other
+      # navigation intent lands, well clear of the V8 call we are inside.
+      def sw_navigate_client(handle, client_id, url, nav_id)
+        (@sw_pending_client_navs ||= []) << {handle: handle.to_i, client: client_id.to_s, url: url.to_s, nav_id: nav_id.to_i}
+        nil
+      end
+
+      def consume_pending_sw_client_nav
+        return if @sw_pending_client_navs.nil? || @sw_pending_client_navs.empty?
+
+        navs = @sw_pending_client_navs
+        @sw_pending_client_navs = nil
+        navs.each {|e| perform_sw_client_navigate(e[:handle], e[:client], e[:url], e[:nav_id]) }
+        nil
+      end
+
+      private def perform_sw_client_navigate(handle, client_id, url, nav_id)
+        realm_id = sw_client_realm(client_id)
+        return sw_navigate_reply(handle, nav_id, '', '', 'the client is not a navigable browsing context') if realm_id.nil?
+
+        from = client_realm_url(realm_id)
+        return sw_navigate_reply(handle, nav_id, '', '', 'mixed content is not allowed') if mixed_content_navigation?(from, url)
+
+        # Identify the browsing CONTEXT before navigating — a frame navigation rebuilds its realm,
+        # so the realm id is not stable across it, but the iframe element that owns it is.
+        parent    = realm_id.zero? ? nil : @runtime.frame_realm_parent(realm_id)
+        container = realm_id.zero? ? nil : frame_container_handle(realm_id, parent)
+        navigate_client_realm(realm_id, url)
+        landed_realm = realm_id.zero? ? 0 : (realm_for_container(parent, container) || realm_id)
+        landed       = client_realm_url(landed_realm)
+        # A cross-origin result is reported as "no client": the spec resolves navigate() with null
+        # rather than handing back a client this worker has no business seeing.
+        origin = url_origin(landed)
+        return sw_navigate_reply(handle, nav_id, '', '', nil) if landed.empty? || origin.nil? || origin != url_origin(from)
+
+        # The client id is realm-derived, so the rebuild MOVED it. Reply with the id of the context
+        # as it is NOW — handing back the pre-navigation id would give the worker a client whose
+        # postMessage is silently dropped and whose focus() would point the focus chain at a
+        # discarded realm (see the sw_clientid_model note).
+        sw_navigate_reply(handle, nav_id, landed, sw_client_id(landed_realm), nil)
+      rescue StandardError => e
+        sw_navigate_reply(handle, nav_id, '', '', "navigation failed: #{e.message}")
+      end
+
+      private def sw_navigate_reply(handle, nav_id, url, client_id, error)
+        w = @workers[handle.to_i] or return nil
+        w[:inbox] << {kind: 'client_navigate_result', nav_id: nav_id.to_i, url: url.to_s, client: client_id.to_s, error: error.to_s}
         nil
       end
 
+      # The realm currently backing a browsing context, named by the iframe element that owns it.
+      # The element outlives every realm rebuild a navigation causes, so it — not the realm id —
+      # is what identifies the context across one.
+      private def realm_for_container(parent, container)
+        return nil if container.nil? || container.zero? || !@runtime.respond_to?(:frame_realm_ids)
+
+        @runtime.frame_realm_ids.find do |rid|
+          @runtime.frame_realm_alive?(rid) && frame_container_handle(rid, parent) == container
+        rescue StandardError
+          false
+        end
+      end
+
+      private def client_realm_url(realm_id)
+        (realm_id.to_i.zero? ? @current_url : frame_realm_url(realm_id)).to_s
+      end
+
+      # An https document may not be navigated to an http one (mixed content); the reverse, and
+      # any non-http(s) scheme, is not this check's business.
+      private def mixed_content_navigation?(from, to)
+        from.to_s.downcase.start_with?('https://') && to.to_s.downcase.start_with?('http://')
+      end
+
+      # Re-navigate the browsing context behind a client id — the main window or a frame realm.
+      private def navigate_client_realm(realm_id, url)
+        return visit(url) if realm_id.zero?
+
+        navigate_realm_self_get(realm_id, url, record: false)
+      end
+
       # Drop a client whose realm was disposed (frame navigated away / removed) so
       # matchAll stops returning a dead client. No-op for an unregistered realm.
       def sw_unregister_client(realm_id)
         @sw_realm_controller.delete(realm_id.to_i)
-        entry = @sw_clients.delete(realm_id.to_i) or return
-        w = @workers[entry[:handle]] or return
-        w[:inbox] << {kind: 'client_unregister', id: entry[:rec]['id']}
+        unregister_client(sw_client_id(realm_id))
+      end
+
+      private def unregister_client(client_id)
+        @sw_clients.delete(client_id) or return nil
+
+        sw_worker_handles.each do |h|
+          w = @workers[h] or next
+          w[:inbox] << {kind: 'client_unregister', id: client_id}
+        end
+        # Losing a controllee can be what finally lets a worker parked in `waiting` activate (the
+        # non-skipWaiting half of "try activate"). Gated on a realm having actually parked one, so
+        # the ordinary client-churn path stays free of a per-unregister broadcast (rule 3).
+        broadcast_to_realms('__csim_swTryActivate') if @sw_activation_parked
+        nil
+      end
+
+      # A realm parked a worker in the waiting slot. Recorded so `unregister_client` knows whether
+      # a try-activate broadcast could possibly matter.
+      def sw_note_activation_parked
+        @sw_activation_parked = true
+        nil
+      end
+
+      # A browsing context was discarded. HTML hands focus back to the top-level traversable
+      # when the focused navigable goes away, so a realm that held the focus chain must not
+      # keep it — otherwise `WindowClient.focused` stays true for a client that no longer exists.
+      def note_realm_discarded(realm_id)
+        note_focused_realm(0) if @focused_realm_id == realm_id.to_i
+        nil
+      end
+
+      # The focused BROWSING CONTEXT (HTML "focused area of the top-level traversable"):
+      # the realm whose document owns the focus chain. Reported by the realm that commits a
+      # focus — focusing an <iframe> hands focus to its NESTED context, so that realm is
+      # reported rather than the container's. Feeds `WindowClient.focused`, which is why the
+      # change is mirrored into every SW that holds a client (they can't query the browser).
+      def note_focused_realm(realm_id)
+        rid = realm_id.to_i
+        return nil if @focused_realm_id == rid
+
+        @focused_realm_id = rid
+        ids = focused_client_ids
+        sw_worker_handles.each do |handle|
+          w = @workers[handle] or next
+          w[:inbox] << {kind: 'client_focus', ids: ids}
+        end
         nil
       end
 
+      # Every client id that counts as focused: the focused context AND its ANCESTORS.
+      # `WindowClient.focused` follows `document.hasFocus()`, which is true for the whole chain
+      # up from the focused frame — a page containing the focused iframe is itself focused
+      # (clients-matchall-include-uncontrolled expects the top-level window and the focused
+      # nested frame to BOTH report true). Not a single winner, despite the name of the field.
+      def focused_client_ids
+        return [] if @focused_realm_id.nil?
+
+        ids = []
+        rid = @focused_realm_id
+        16.times do
+          ids << sw_client_id(rid)
+          # A top-level browsing context ends the chain: the main realm, and an auxiliary window
+          # (whose OPENER is not its ancestor — `document.hasFocus()` is false in the opener while
+          # the popup holds the focus, so its client must not be dragged in).
+          break if top_level_realm?(rid)
+
+          rid = @runtime.respond_to?(:frame_realm_parent) ? @runtime.frame_realm_parent(rid).to_i : 0
+        end
+        ids.uniq
+      end
+
+      # A realm with no parent NAVIGABLE. Without the runtime's window/frame maps (QuickJS has no
+      # realms at all) only the main realm can be one.
+      private def top_level_realm?(realm_id)
+        return true if realm_id.to_i.zero?
+
+        @runtime.respond_to?(:top_level_realm?) ? @runtime.top_level_realm?(realm_id) : true
+      end
+
+      # A worker's service-worker Client id. Distinct from the realm ids below so the
+      # client-message router can tell a worker client from a browsing context.
+      def sw_worker_client_id(handle) = "client-worker-#{handle.to_i}"
+
+      # A realm's service-worker Client id. The MAIN realm (id 0) is 'client-window'; every
+      # other realm is `client-<realm>`. The same two spellings are produced JS-side by
+      # sw-client.js's clientId() and the FetchEvent clientKey (js/src/workers.js), and read
+      # back by the client-message router below — so they must be minted in exactly one place.
+      def sw_client_id(realm_id) = realm_id.to_i.zero? ? 'client-window' : "client-#{realm_id.to_i}"
+
+      # The realm a client id names — the inverse of `sw_client_id`, nil for an unrecognized id.
+      def sw_client_realm(client_id)
+        id = client_id.to_s
+        return 0 if id == 'client-window'
+
+        (m = /\Aclient-(\d+)\z/.match(id)) ? m[1].to_i : nil
+      end
+
+      # The worker handle a client id names, or nil when the id is not a worker client's.
+      def sw_client_worker(client_id)
+        (m = /\Aclient-worker-(\d+)\z/.match(client_id.to_s)) ? m[1].to_i : nil
+      end
+
       # ── Cross-isolate MessagePort channel relay (client realm ↔ worker/SW isolate) ──
       # Each endpoint self-registers when it (de)serializes the transferred port.
       def port_channel_endpoint_realm(channel, realm_id)
@@ -4241,7 +4625,7 @@ module Capybara
       def worker_terminate(handle)
         w = @workers.delete(handle.to_i)
         return unless w
-        w[:inbox] << :terminate
+        detach_worker(handle.to_i, w)
         # Most clean shutdowns are <10 ms; the kill is the fallback
         # for blocked workers. Join again AFTER the kill so the thread is actually
         # dead before we revoke its URLs — `Thread#kill` is async, and a worker
@@ -4252,6 +4636,32 @@ module Capybara
           w[:thread].kill
           w[:thread].join(WORKER_TERMINATE_GRACE)
         end
+        reap_worker(handle.to_i, w)
+      end
+
+      # Ask a worker to stop and stop treating it as a client. Split out of `worker_terminate` so the
+      # realm-disposal path can do it WITHOUT the thread joins below (see terminate_realm_workers).
+      # A dedicated / shared worker is a service-worker client (worker_spawn registers it), and a
+      # terminated one must stop showing up in matchAll — the same leak sw_unregister_client
+      # prevents for a disposed realm. A no-op for a SERVICE worker, which is never a client.
+      private def detach_worker(handle, w)
+        unregister_client(sw_worker_client_id(handle))
+        w[:inbox] << :terminate
+      end
+
+      # Everything that must happen once a worker is out of `@workers`, whether or not we waited for
+      # its thread: drain what it will never answer, release the counters it still holds, and revoke
+      # what it created. Load-bearing — the counter reset at the end only fires when the LAST worker
+      # goes, so skipping this path leaves `polling?` stuck true for the rest of the session and
+      # every later negative assertion burns the full wait.
+      private def reap_worker(handle, w)
+        # Hand back every plain postMessage this worker still owes a reply for — queued OR already
+        # consumed by a listen-only handler that will never answer. Only a reply releases these,
+        # and a dead worker sends none; leaving them counted pins `worker_pending?` (and so
+        # `polling?`) true for the rest of the session, making every later negative assertion wait
+        # out the full timeout.
+        @worker_in_flight = [0, @worker_in_flight - w[:in_flight].to_i].max
+        w[:in_flight] = 0
         # The dead worker never answers what was still queued in its inbox: post the matching
         # fallback replies so the reply-pending counters drain (a controlled fetch falls back to
         # the network) instead of taxing every later settle's bounded wait. Mid-dispatch deaths
@@ -4306,7 +4716,10 @@ module Capybara
         broadcasts,  rest0  = events.partition {|e| e[:kind] == 'broadcast' }
         port_ends,   rest0b = rest0.partition  {|e| e[:kind] == 'port_endpoint' }
         port_msgs,   rest0c = rest0b.partition {|e| e[:kind] == 'port_msg' }
-        sw_msgs,     rest1  = rest0c.partition {|e| e[:kind] == 'sw_client_msg' }
+        sw_focuses,  rest0c2 = rest0c.partition {|e| e[:kind] == 'sw_client_focus' }
+        sw_navs,     rest0c3 = rest0c2.partition {|e| e[:kind] == 'sw_client_navigate' }
+        skip_waits,  rest0d  = rest0c3.partition {|e| e[:kind] == 'sw_skip_waiting' }
+        sw_msgs,     rest1  = rest0d.partition {|e| e[:kind] == 'sw_client_msg' }
         swacks,      rest2  = rest1.partition  {|e| e[:kind] == 'swack' }
         claims,      rest3  = rest2.partition  {|e| e[:kind] == 'sw_claim' }
         fetch_resps,   rest4  = rest3.partition  {|e| e[:kind] == 'fetch_response' }
@@ -4316,6 +4729,20 @@ module Capybara
         # A worker/SW registering its end of a cross-isolate MessagePort channel — record it BEFORE
         # the message events below, so a port message carried in the same drain can already route.
         port_ends.each {|e| port_channel_endpoint_sw(e[:channel], e[:handle]) }
+        # `WindowClient.focus()` — the worker asked to move the focus chain to a client. Applied
+        # BEFORE the messages below, so a SW that focuses a client and then reports its own
+        # matchAll() in the same turn sees the move it just made.
+        sw_focuses.each do |e|
+          rid = sw_client_realm(e[:client]) and note_focused_realm(rid)
+        end
+        # `WindowClient.navigate()` — only QUEUED here (see sw_navigate_client). It must not run
+        # before the sw_msgs / claims / fetch_resps below: the worker emitted those FIRST, and a
+        # navigation discards the realm they address. Queuing preserves the worker's own ordering
+        # and keeps the realm rebuild out of the `@ticking` guard.
+        sw_navs.each {|e| sw_navigate_client(e[:handle], e[:client], e[:url], e[:nav_id]) }
+        # `skipWaiting()` — release a worker parked in the waiting slot. Broadcast, because the
+        # registration objects holding that parked continuation are per-realm.
+        skip_waits.each {|e| broadcast_to_realms('__csim_swSkipWaiting', e[:handle]) }
         # A worker/SW port → its remote (client-realm) peer: relay to that realm's channel endpoint.
         # If the client hasn't registered its endpoint yet (it decodes the transferred port in the
         # sw_client_msg processed just below), BUFFER until port_channel_endpoint_realm flushes.
@@ -4335,12 +4762,20 @@ module Capybara
         # the client's message `source` is exact. A message to a DISCARDED frame realm is dropped
         # (matching a real browser — a message to a gone client is discarded, not misrouted to top).
         sw_msgs.each do |e|
-          m = /\Aclient-(\d+)\z/.match(e[:client].to_s)
-          if m
-            rid = m[1].to_i
-            @runtime.realm_call(rid, '__csim_swDeliverClientMessage', e[:data], e[:handle]) if @runtime.frame_realm_alive?(rid)
-          else
+          rid = sw_client_realm(e[:client])
+          if (wh = sw_client_worker(e[:client]))
+            # A worker CLIENT (a dedicated/shared worker the SW controls) — deliver to its own
+            # isolate's `navigator.serviceWorker`, not to a browsing context, and not to the
+            # worker's creator-facing `self.onmessage` (which is where a bare 'message' would land).
+            (w = @workers[wh]) && w[:inbox] << {kind: 'sw_client_message', data: e[:data], handle: e[:handle]}
+          elsif rid.nil?
+            # An id naming nothing we know. Dropping matches a real browser (a message to a gone
+            # client is discarded); delivering it to the main realm would MISROUTE it.
+            nil
+          elsif rid.zero?
             @runtime.call('__csim_swDeliverClientMessage', e[:data], e[:handle])
+          elsif @runtime.frame_realm_alive?(rid)
+            @runtime.realm_call(rid, '__csim_swDeliverClientMessage', e[:data], e[:handle])
           end
         end
         # clients.claim(): the claiming worker takes control of EVERY in-scope client — including
@@ -4388,6 +4823,9 @@ module Capybara
         @sw_msg_wait_deadline     = nil if acks.size.positive? || swacks.size.positive?
         # `__error` postbacks don't correspond to a prior post, so bottom out at zero.
         @worker_in_flight = [0, @worker_in_flight - msgs.size].max
+        # Mirror the release onto the answering worker's own tally, so what `reap_worker` hands
+        # back when it dies is exactly what it still owes.
+        msgs.each {|e| (w = @workers[e[:handle].to_i]) && (w[:in_flight] = [0, w[:in_flight].to_i - 1].max) }
         @runtime.call('__csim_deliverWorkerMessages', msgs) unless msgs.empty?
         events.size
       end
@@ -4415,9 +4853,9 @@ module Capybara
       # `window.open(url, name)` from JS — returns the new (or reused, by name)
       # window's handle, or nil. The URL is resolved against THIS document so a
       # relative `window.open('/x')` targets the right origin/path.
-      def open_child_window(url, name, opener_realm_id = 0)
+      def open_child_window(url, name, opener_realm_id = 0, about_base = nil, about_origin = nil)
         return nil unless @driver.respond_to?(:open_window_from_js)
-        @driver.open_window_from_js(self, url.to_s, name.to_s, opener_realm_id.to_i)
+        @driver.open_window_from_js(self, url.to_s, name.to_s, opener_realm_id.to_i, about_base.to_s, about_origin.to_s)
       end
 
       # A `target=_blank`/named link/area activation from a frame or window realm in
@@ -4437,10 +4875,13 @@ module Capybara
       # works (dom/nodes/remove-and-adopt-thcrash). Returns nil to fall back to the
       # separate-VM aux-window path. First stage: about:blank only (a non-blank
       # same-origin URL still takes the aux path until realm URL-loading lands).
-      def open_window_realm(url, name: nil, opener_realm_id: 0)
+      def open_window_realm(url, name: nil, opener_realm_id: 0, about_base: nil, about_origin: nil)
         return nil unless @runtime.respond_to?(:create_window_realm)
         return nil unless url.nil?
-        @runtime.create_window_realm('', '', 'text/html', window_name: name, opener_id: opener_realm_id)
+        @runtime.create_window_realm(
+          '', '', 'text/html',
+          window_name: name, opener_id: opener_realm_id, about_base: about_base, about_origin: about_origin
+        )
       end
 
       # `targetWindow.postMessage(data, origin)` — route to the target window's
@@ -5289,6 +5730,7 @@ module Capybara
         @sw_pending_claims   = []
         @sw_clients          = {}
         @sw_realm_controller = {}
+        @focused_realm_id    = nil
         @port_channels       = {}
         @sw_nav_outbox.clear
         @transfer_buffer_lock.synchronize {
@@ -5638,7 +6080,7 @@ module Capybara
       # `build_worker` factory, evaluates the worker script, then
       # loops draining microtasks + timers + inbox until `:terminate`
       # lands or an exception propagates.
-      private def run_worker(handle, url, body, inbox, outbox, engine_class, shared: false, service: false, creator_key: nil)
+      private def run_worker(handle, url, body, inbox, outbox, engine_class, shared: false, service: false, creator_key: nil, seed: nil)
         # Release the spawn-time `@worker_initializing` count exactly once, however
         # this method exits (normal start, `self.close()`, or an exception), so
         # worker_pending? doesn't stay stuck true forever.
@@ -5673,7 +6115,17 @@ module Capybara
         sw_has_fetch = false
         sw_hooks = {
           post_to_client: ->(client_id, data) { outbox << {handle: handle, kind: 'sw_client_msg', client: client_id, data: data.to_s} },
+          # WindowClient.focus() — moving the focus chain is cross-realm browser state, so the
+          # worker asks rather than does. Delivered by deliver_worker_messages, which echoes the
+          # move back to every SW as a `client_focus`.
+          focus_client:   ->(client_id)       { outbox << {handle: handle, kind: 'sw_client_focus', client: client_id} },
+          # WindowClient.navigate() — like focus_client, the browser owns the act; unlike it, the
+          # worker is waiting on the OUTCOME (final URL / cross-origin / refusal), so the reply
+          # comes back on this worker's inbox keyed by nav_id.
+          navigate_client: ->(client_id, url, nav_id) { outbox << {handle: handle, kind: 'sw_client_navigate', client: client_id, url: url.to_s, nav_id: nav_id.to_i} },
           claim:          ->                  { outbox << {handle: handle, kind: 'sw_claim', has_fetch: sw_has_fetch} },
+          # skipWaiting() — the waiting slot is client-side, so the request rides the outbox.
+          skip_waiting:   ->                  { outbox << {handle: handle, kind: 'sw_skip_waiting'} },
           fetch_respond:  ->(fetch_id, resp, realm_id) { sw_deliver_fetch_response(handle, fetch_id.to_i, resp.to_s, outbox, realm_id.to_i) },
           # A streaming respondWith frame (start / chunk / close / error) for a controlled client's
           # fetch — rides the outbox in emission order so the client realm reassembles the body
@@ -5715,6 +6167,12 @@ module Capybara
         # A service worker runs in a ServiceWorkerGlobalScope: adjust the worker scope
         # (no blob-URL minting; SW lifecycle stubs) BEFORE its script runs.
         rt.eval('__csim_installServiceWorkerScope();') if service
+        # Seed the client mirror BEFORE the script evaluates: `clients.matchAll()` at top level is a
+        # real pattern (clients-matchall-on-evaluation), and an empty mirror there returns nothing.
+        if seed
+          seed[:clients].each {|rec| rt.call('__csim_swRegisterClient', rec) }
+          rt.call('__csim_swNoteFocusedClient', seed[:focused]) if seed[:focused].any?
+        end
         rt.eval(body)
         rt.drain_microtasks
         # Drive the service worker's lifecycle: fire `install`, then `activate`, draining each
@@ -5796,6 +6254,21 @@ module Capybara
               # pending counter): the inbox is FIFO, so it's processed before any later message
               # whose handler matchAll's the client.
               rt.call('__csim_swRegisterClient', msg[:client])
+            elsif msg.is_a?(Hash) && msg[:kind] == 'client_focus'
+              # The focus chain moved: `WindowClient.focused` is per-browsing-context state the
+              # worker isolate can't read, so the browser pushes the focused client's id on every
+              # change (and once at registration, for a worker that started after the move).
+              rt.call('__csim_swNoteFocusedClient', msg[:ids])
+            elsif msg.is_a?(Hash) && msg[:kind] == 'client_navigate_result'
+              # The outcome of a WindowClient.navigate() this worker is awaiting — settles the
+              # promise it is holding (js/src/workers.js __csim_swClientNavigateResult).
+              rt.call('__csim_swClientNavigateResult', msg[:nav_id], msg[:url], msg[:client], msg[:error])
+            elsif msg.is_a?(Hash) && msg[:kind] == 'sw_client_message'
+              # A service worker → THIS worker, which is one of its clients: `client.postMessage`
+              # targets the client's `navigator.serviceWorker` 'message' event, which a worker
+              # isolate has just like a document (WorkerNavigator.serviceWorker). Fire-and-forget,
+              # like the register/focus mirrors — the SW's send is not awaiting a reply.
+              rt.call('__csim_swDeliverClientMessage', msg[:data], msg[:handle])
             elsif msg.is_a?(Hash) && msg[:kind] == 'client_unregister'
               # The client's realm was disposed — drop it so matchAll stops returning a dead client.
               rt.call('__csim_swUnregisterClient', msg[:id])
@@ -7316,6 +7789,7 @@ module Capybara
         end
       end
       def drain_pending_navigation
+        consume_pending_sw_client_nav
         consume_pending_location
         consume_pending_frame_nav
         consume_pending_frame_submit
@@ -7353,7 +7827,9 @@ module Capybara
       # in place rather than appending. Both the state and (when given)
       # the URL are mirrored on Ruby's slot so a subsequent back to
       # this entry restores the same state.
-      def history_state(url, state = nil)
+      def history_state(url, state = nil, realm_id = 0)
+        return note_frame_same_document_url(realm_id.to_i, url) unless realm_id.to_i.zero?
+
         if url
           resolved = resolve_against_current(url.to_s)
           record_url_transition(resolved)
@@ -7371,13 +7847,41 @@ module Capybara
       # Mirror that on the Ruby side so `Capybara#go_back` traverses
       # within the pushState chain (fires `popstate`) and only crosses
       # to a real reload when the back hits a `:visit` boundary.
-      def history_push(url, state = nil)
+      def history_push(url, state = nil, realm_id = 0)
+        return note_frame_same_document_url(realm_id.to_i, url) unless realm_id.to_i.zero?
+
         resolved = resolve_against_current(url.to_s)
         record_url_transition(resolved)
         @current_url = resolved
         record_history({method: :get, url: resolved, state: state, kind: :push_state})
       end
 
+      # A SAME-DOCUMENT URL change (pushState / replaceState / a fragment navigation) made by a
+      # NESTED browsing context. It belongs to that frame's own session history — mirroring it onto
+      # the top document's would make `current_url` report a URL no window is at, which is what an
+      # iframe'd SPA does on every navigation. Recorded as the current entry's URL (rather than a
+      # new entry) so a later `location.reload()` refetches the pushState'd URL, not the stale
+      # `src`; in-frame same-document TRAVERSAL over such entries is still unmodelled.
+      # A same-isolate window realm (a popup) has no iframe container and so no entry to update —
+      # its handle is 0, and not touching the top history is already the fix there.
+      private def note_frame_same_document_url(realm_id, url)
+        return nil if url.nil? || realm_id.zero?
+
+        parent = @runtime.frame_realm_parent(realm_id)
+        handle = frame_container_handle(realm_id, parent)
+        return nil if handle.zero?
+
+        h = (@frame_histories ||= {})[[parent, handle]] ||= {entries: [], idx: -1}
+        if h[:idx].negative?
+          # Seed entry 0 from the document as it is NOW — this runs before the location update,
+          # so it still reads the URL the frame was loaded at.
+          h[:entries] << frame_history_entry(realm_id)
+          h[:idx] = 0
+        end
+        h[:entries][h[:idx]] = (h[:entries][h[:idx]] || {}).merge(url: url.to_s)
+        nil
+      end
+
       # Total history entries (after forward-tail truncation), surfaced
       # to JS `history.length` via the `__historyLength` host fn.
       def history_length