capybara-simulated 0.8.0 → 0.10.0

data/lib/capybara/simulated/v8_runtime.rb

@@ -11,8 +11,17 @@
 
 require 'digest'
 require 'fileutils'
+require 'uri'
 require 'rusty_racer'
 
+# The engine is a SOFT dependency (the gemspec names no version), so say what
+# we need here rather than letting it surface as a NoMethodError from inside
+# `rebuild_ctx`'s warm-reset rescue, which would report it as a failed reset.
+# 0.2.1: Context#eval_void / Script#run_void. 0.2.0: Module#graph_async?.
+unless RustyRacer::Context.method_defined?(:eval_void)
+  raise LoadError, "capybara-simulated needs rusty_racer >= 0.2.1 (found #{RustyRacer::VERSION})"
+end
+
 require_relative 'runtime_shared'
 require_relative 'script_cache'
 require_relative 'worker_runtime'
@@ -27,7 +36,7 @@ begin
   # 8900×8900 fixture through the transfer-buffer path). Match
   # Discourse's own testem flag of 4 GB so the test fits.
   #
-  # rusty_racer >= 0.1.4 installs a near-heap-limit callback on every isolate,
+  # rusty_racer installs a near-heap-limit callback on every isolate,
   # so EXCEEDING this cap raises a catchable `RustyRacer::V8OutOfMemoryError`
   # (and the isolate recovers) instead of V8 aborting the whole process with a
   # fatal "Reached heap limit". So this value doubles as the memory backstop: a
@@ -113,6 +122,7 @@ module Capybara
         # policy), so a returned eval/call has already run its end-of-script
         # microtasks.
         def eval(src)          = @ctx.eval(src)
+        def eval_void(src)     = @ctx.eval_void(src)
         def call(name, *args)  = @ctx.call(name, *args)
 
         # Record every attach so `create_context` can replay them: the bridge
@@ -152,8 +162,8 @@ module Capybara
         def terminate                        = @iso.terminate
         def dispose                          = @iso.dispose
         def perform_microtask_checkpoint     = @iso.perform_microtask_checkpoint
-        # V8 heap accounting + a forced full GC (rusty >= 0.1.9, the gem's
-        # floor). Used by the per-visit heap-pressure relief in `rebuild_ctx`.
+        # V8 heap accounting + a forced full GC. Used by the per-visit
+        # heap-pressure relief in `rebuild_ctx`.
         def heap_statistics                  = @iso.heap_statistics
         def low_memory_notification          = @iso.low_memory_notification
 
@@ -336,6 +346,7 @@ module Capybara
       end
 
       def eval(code)         = ctx.eval(code.to_s)
+      def eval_void(code)    = ctx.eval_void(code.to_s)
       def call(name, *args)
         result = ctx.call(name, *args)
         ScriptCache.warm_pending!
@@ -426,8 +437,15 @@ module Capybara
       # through its own navigation.
       def window_realm_meta = (@window_realm_meta ||= {})
 
+      # Is this realm a TOP-LEVEL browsing context? The main realm is, and so is an auxiliary
+      # window realm — `frame_realm_parents` records 0 for one because it has no parent FRAME,
+      # which is not the same as being nested in the main window. An ancestor walk (the focus
+      # chain, most of all) has to stop here rather than step into the opener.
+      def top_level_realm?(realm_id) = realm_id.to_i.zero? || window_realm_meta.key?(realm_id.to_i)
+
       def dispose_frame_realms
         @realm_module_handles&.clear
+        @module_sw_ctxs&.clear
         @frame_realm_depths&.clear
         @frame_realm_parents&.clear
         @window_realm_meta&.clear
@@ -443,14 +461,14 @@ module Capybara
       # / module state, exactly like the main page's per-visit rebuild. `parent_id`
       # keeps the new realm's `parent`/`top` wired to the owning realm. The
       # Browser then re-points the iframe element at the new id (`__csimRebindFrameRealm`).
-      def reload_frame_realm(old_id, parent_id, url, body, content_type)
+      def reload_frame_realm(old_id, parent_id, url, body, content_type, client_id = nil)
         # A re-navigated document discards its child browsing contexts, so dispose the old realm's
         # DESCENDANT frame realms too — not just old_id. The JS src-reassignment path gets this for
         # free (the old document's iframe elements go away → DOM-unregister disposes their realms);
         # the Ruby reload path (navigate_realm_self_get/_post) rebuilds without that DOM teardown, so
         # a descendant frame's realm would otherwise linger and its contentWindow stay live.
         dispose_frame_realm_tree(old_id)
-        create_frame_realm(ctx, url, body, content_type, parent_id)
+        create_frame_realm(ctx, url, body, content_type, parent_id, nil, nil, nil, nil, nil, nil, client_id)
       end
 
       # Dispose a frame realm and every descendant frame realm (transitively), deepest first so a
@@ -471,7 +489,11 @@ module Capybara
         # Like reload_frame_realm, a re-navigated window discards its child browsing contexts — dispose
         # the descendant frame realms too, not just old_id, so a popup's iframes don't linger.
         dispose_frame_realm_tree(old_id)
-        create_window_realm(url, body, content_type, opener_id: meta[:opener_id], window_name: meta[:window_name])
+        create_window_realm(
+          url, body, content_type,
+          opener_id: meta[:opener_id], window_name: meta[:window_name],
+          about_base: meta[:about_base], about_origin: meta[:about_origin]
+        )
       end
 
       # Tear down a single frame realm (e.g. a descendant frame destroyed when an
@@ -483,7 +505,13 @@ module Capybara
         @browser.revoke_realm_blobs(id) rescue nil
         # Drop it from the SW Client registry so matchAll stops returning a dead client.
         @browser.sw_unregister_client(id) rescue nil
+        # A dedicated worker is owned by the context that created it — discarding the context
+        # terminates it (and unregisters its own client record).
+        @browser.terminate_realm_workers(id) rescue nil
+        # If it held the focus chain, focus returns to the top-level browsing context.
+        @browser.note_realm_discarded(id) rescue nil
         @realm_module_handles&.delete(id)
+        @module_sw_ctxs&.delete(id)
         @frame_realm_depths&.delete(id)
         @frame_realm_parents&.delete(id)
         @window_realm_meta&.delete(id)
@@ -492,7 +520,7 @@ module Capybara
         # unregister path (its iframe element going away), but a WINDOW realm has no
         # element — this is its only eviction, and it covers the reload (dispose +
         # recreate) path too, where the old id would otherwise leak in the set.
-        ctx.eval("globalThis.__csimChildRealmIds && globalThis.__csimChildRealmIds.delete(#{id.to_i});") rescue nil
+        ctx.eval_void("globalThis.__csimChildRealmIds && globalThis.__csimChildRealmIds.delete(#{id.to_i});") rescue nil
         fr = frame_realms.delete(id)
         fr.dispose rescue nil if fr
         nil
@@ -583,7 +611,7 @@ module Capybara
             # contexts N -> 1). See `relieve_heap_pressure`.
             relieve_heap_pressure
             attach_host_fns(@ctx)
-            @ctx.eval('__csim_installWorker();')
+            @ctx.eval_void('__csim_installWorker();')
             return @ctx
           rescue StandardError => e
             warn "[capybara-simulated] warm context reset failed, falling back to cold rebuild: #{e.class}: #{e.message}"
@@ -711,7 +739,7 @@ module Capybara
       # occasional JS-side infinite loop would otherwise stall the whole
       # run; the timeout converts the hang into a
       # `RustyRacer::ScriptTerminatedError` on that one example — whose
-      # `#message` / `#js_backtrace` (rusty >= 0.1.10) name the looping JS
+      # `#message` / `#js_backtrace` name the looping JS
       # frame (function + source position), so an in-V8 hang is diagnosable
       # from the failure alone, no live debugger attach needed. The
       # terminate escalates through any nested frames (it is
@@ -733,7 +761,7 @@ module Capybara
       def build_ctx
         c = Ctx.new(snapshot: @snapshot || self.class.snapshot, timeout: CALL_TIMEOUT_MS)
         attach_host_fns(c)
-        c.eval('__csim_installWorker();')
+        c.eval_void('__csim_installWorker();')
         c
       end
 
@@ -753,8 +781,8 @@ module Capybara
       # id (or nil on failure — then the bridge keeps its same-realm fallback).
       # The bridge maps `iframe.contentWindow` to `RustyRacer.contextGlobal(id)`.
       def attach_frame_realm_loader(c)
-        c.attach('__csim_createFrameRealm', ->(url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil, frame_about_base = nil) {
-          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id, frame_name, frame_doc_origin, frame_location_origin, js_url_source, frame_about_base) }
+        c.attach('__csim_createFrameRealm', ->(url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil, frame_about_base = nil, frame_viewport = nil, client_id = nil) {
+          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id, frame_name, frame_doc_origin, frame_location_origin, js_url_source, frame_about_base, frame_viewport, client_id) }
         })
         # Re-navigating an iframe (src/srcdoc reassigned) builds a fresh realm;
         # the bridge calls this to tear down the superseded one so it doesn't
@@ -799,14 +827,14 @@ module Capybara
       # document — rebind realm-executing variants on top, then reseed per-realm JS.
       def seed_realm_bridge(realm)
         has_bridge = realm.eval("typeof __csimLoadDocument === 'function'")
-        realm.eval(RuntimeShared.snapshot_src) unless has_bridge
+        realm.eval_void(RuntimeShared.snapshot_src) unless has_bridge
         attach_run_script_with_cache(realm)
         attach_realm_esm_entry(realm)
         reseed_realm_js(realm)
         realm
       end
 
-      def create_frame_realm(parent_ctx, url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil, frame_about_base = nil)
+      def create_frame_realm(parent_ctx, url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil, frame_about_base = nil, frame_viewport = nil, client_id = nil)
         depth = (frame_realm_depths[parent_id] || 0) + 1
         if depth > MAX_FRAME_DEPTH
           @browser.log_console('warn', "iframe nesting depth #{depth} exceeds #{MAX_FRAME_DEPTH}; not building #{url}")
@@ -826,7 +854,15 @@ module Capybara
         # `top` propagates up the chain (the main realm's `top` is itself). A
         # nested frame thus reaches its TRUE parent, not unconditionally the
         # main frame. `parent_id` is an integer the marshaller carries verbatim.
-        realm.eval(<<~JS)
+        #
+        # eval_void, and not by preference: a statement list's completion value is
+        # its last statement's, so this block evaluates to the WindowProxy it just
+        # assigned — and marshalling a value RUNS JS, so the proxy's `ownKeys` trap
+        # throws SecurityError at a cross-origin parent. That lands after every
+        # write here has already succeeded, aborting the rest of the frame's boot
+        # (leaving it on the snapshot's default origin) over a value we never asked
+        # for. Every eval below whose value we discard is spelled the same way.
+        realm.eval_void(<<~JS)
           if (globalThis.#{HOST_NAMESPACE_NAME} && typeof globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal === 'function') {
             var __parentWin = globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal(#{parent_id.to_i});
             if (__parentWin) {
@@ -854,10 +890,24 @@ module Capybara
         # HTML / control bytes survive (Ruby's String#inspect is NOT a faithful
         # JS string escaper — it mangles \a, \e, and binary bytes).
         realm.call('__csimUpdateLocation', url.to_s) unless url.to_s.empty?
+        # The navigation's reserved client id — this document's realm ADOPTS it as its
+        # service-worker Client identity (`event.resultingClientId` resolves to THIS
+        # client after commit). Seeded BEFORE the document loads so the realm's own
+        # client reports (sw-client.js clientId()) already carry it; the browser-side
+        # alias keeps message routing and record minting coherent (sw_adopt_client_id).
+        unless client_id.to_s.empty?
+          realm.eval_void("globalThis.__csimClientId = #{JSON.generate(client_id.to_s)};")
+          @browser.sw_adopt_client_id(realm.id, client_id.to_s)
+        end
         # Set window.name from the container's `name` attribute BEFORE the document
         # loads, so a frame whose load handler reads window.name to identify itself
         # (declarative-shadow declarative-child-frame) sees it.
         realm.call('__csimSetWindowName', frame_name.to_s) unless frame_name.nil?
+        # The frame's viewport is its container's content box, measured by the parent realm. Seed it
+        # BEFORE the document loads so load-time `innerWidth` reads and `@media` evaluation see the
+        # frame's own size rather than the top window's. `nil` = an unrendered container, which is a
+        # 0x0 window — pass it through rather than skipping, or the frame keeps the top-level size.
+        realm.call('__csimFrameViewportChanged', frame_viewport)
         # Seed the frame's document origin (opaque/inherited) BEFORE the document
         # loads, so its load-time scripts read the right self.origin. nil → a
         # real-URL frame whose origin is its own location origin.
@@ -881,21 +931,31 @@ module Capybara
         # (sw_note_realm_controller); recording it BEFORE the load also lets a NESTED frame built during
         # this frame's load inherit the controller.
         opaque = opaque_frame_url?(url)
-        # A sandboxed frame WITHOUT allow-same-origin has an OPAQUE origin (doc origin 'null') and is
-        # cross-origin to its creator, so it does NOT inherit the creator's controller (srcdoc-iframe:
-        # "sandboxed srcdoc should not inherit"). allow-same-origin restores the parent origin → inherits.
-        inheritable = opaque && frame_doc_origin.to_s != 'null'
-        ctrl   = @browser.sw_client_controller_for(url.to_s)
-        ctrl ||= @browser.sw_inherited_controller_for(parent_id) if inheritable
-        if ctrl
-          realm.call('__csim_swSetControllerDirect', *ctrl)
-          # Only an OPAQUE (about:blank / srcdoc) frame is mirrored into the SW's clients.matchAll():
-          # a real-URL frame's registration would fire during its SYNCHRONOUS SW nav-fetch (main thread
-          # blocked on @sw_nav_outbox), perturbing worker timing — the http-src client model is deferred.
-          @browser.sw_note_realm_controller(realm.id, ctrl)
-          @browser.sw_register_client(realm.id, url.to_s, 'window', 'nested', ctrl[0]) if opaque
+        # A sandboxed frame WITHOUT allow-same-origin has an OPAQUE origin (doc origin 'null'), which
+        # is cross-origin to everything — so it is NOT CONTROLLED AT ALL. It inherits no controller
+        # from its creator (srcdoc-iframe: "sandboxed srcdoc should not inherit"), its subresource
+        # fetches never reach the SW, and it is absent from `clients.matchAll()`. Excluding it from
+        # only the client registry would not hold: a controlled frame's first subresource fetch
+        # re-registers it lazily from the fetch event (js/src/workers.js clientFor). The SW does still
+        # answer its NAVIGATION request, because a CSP-header sandbox is knowable only FROM that
+        # response (sandboxed-iframe-fetch-event, "Service worker should NOT control the sandboxed
+        # page"). allow-same-origin restores the parent origin, and a real-URL frame carries no
+        # explicit origin at all (nil = its own location origin) — both are controlled normally.
+        if frame_doc_origin.to_s != 'null'
+          ctrl   = @browser.sw_client_controller_for(url.to_s)
+          ctrl ||= @browser.sw_inherited_controller_for(parent_id) if opaque
+          if ctrl
+            # Wiring the controller is what registers this frame as a client — the realm reports
+            # itself from installController (js/src/sw-client.js), before the document below loads.
+            realm.call('__csim_swSetControllerDirect', *ctrl)
+            @browser.sw_note_realm_controller(realm.id, ctrl)
+          end
         end
         realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
+        # This document now has a URL and any host-wired controller, so it can announce itself
+        # as a service-worker client — an UNCONTROLLED context is still a client of its origin
+        # and must show up in `matchAll({includeUncontrolled: true})`.
+        realm.call('__csim_swReportClient') rescue nil
         # A `javascript:` URL frame: the initial empty document is now loaded and
         # parent/top are wired, so evaluate the URL's script in the realm (global
         # scope). Per HTML, only a STRING result navigates the frame to a new
@@ -929,6 +989,7 @@ module Capybara
         # including any module handles its scripts compiled before the throw.
         if realm
           @realm_module_handles&.delete(realm.id)
+          @module_sw_ctxs&.delete(realm.id)
           realm.dispose rescue nil
         end
         nil
@@ -944,7 +1005,7 @@ module Capybara
       # a native `__csimFrameWindowProxyFor`, so `popup.document` is a real
       # same-isolate Document (cross-window adoptNode works). The single isolate also
       # makes a same-origin window far cheaper than today's isolate-per-window.
-      def create_window_realm(url, body, content_type, opener_id: nil, window_name: nil, doc_origin: nil, location_origin: nil)
+      def create_window_realm(url, body, content_type, opener_id: nil, window_name: nil, doc_origin: nil, location_origin: nil, about_base: nil, about_origin: nil)
         realm = seed_realm_bridge(ctx.create_context)
         # Mark it a top-level window realm so its location setter routes to
         # __csimWindowRealmNavigate (reload THIS realm) rather than the frame-nav or
@@ -953,7 +1014,7 @@ module Capybara
         # `window.closed` (flag-backed) and `window.close()` (marks closed; the realm
         # lingers inert until the Browser tears the isolate down — matching a real
         # closed window whose proxy stays valid and reports closed === true).
-        realm.eval(<<~JS)
+        realm.eval_void(<<~JS)
           globalThis.__csimIsWindowRealm = true;
           globalThis.__csimWindowClosedFlag = false;
           try {
@@ -969,14 +1030,28 @@ module Capybara
         # guard is on nil, not on 0 (0 is falsy but real here). Assigning globalThis.opener
         # routes through the bridge's opener setter (stores the override the getter returns).
         unless opener_id.nil?
-          realm.eval(<<~JS)
+          realm.eval_void(<<~JS)
             if (typeof globalThis.__csimFrameWindowProxyFor === 'function') {
               var __op = globalThis.__csimFrameWindowProxyFor(#{opener_id.to_i});
               if (__op) globalThis.opener = __op;
             }
           JS
         end
-        realm.call('__csimUpdateLocation', url.to_s)        unless url.to_s.empty?
+        # `window.open()` with no URL opens about:blank — that IS the new document's URL, and a
+        # realm built from the snapshot would otherwise keep reporting the OPENER's (making the
+        # popup a phantom duplicate of its opener everywhere a document URL is read, the service-
+        # worker client set included). Its ORIGIN and its BASE url are inherited from the opener,
+        # exactly as an empty <iframe>'s are (create_frame_realm's frame_about_base): the origin
+        # so the popup isn't cross-origin to the window that opened it, the base so relative
+        # resolution inside it still targets the opener's document.
+        if url.to_s.empty?
+          realm.call('__csimUpdateLocation', 'about:blank')
+          realm.call('__csimSetAboutBaseURL', about_base.to_s)   unless about_base.to_s.empty?
+          doc_origin      ||= about_origin unless about_origin.to_s.empty?
+          location_origin ||= about_origin unless about_origin.to_s.empty?
+        else
+          realm.call('__csimUpdateLocation', url.to_s)
+        end
         realm.call('__csimSetWindowName', window_name.to_s) unless window_name.nil?
         realm.call('__csimSetDocumentOrigin', doc_origin.to_s)         unless doc_origin.nil?
         realm.call('__csimSetLocationOrigin', location_origin.to_s)    unless location_origin.nil?
@@ -991,12 +1066,14 @@ module Capybara
         # Register with the opener (main) realm's child-realm set so `drainChildRealms`
         # steps THIS realm's event loop too — otherwise its queued tasks (e.g. a
         # BroadcastChannel delivery from a blob document) never fire.
-        ctx.eval("(globalThis.__csimChildRealmIds || (globalThis.__csimChildRealmIds = new Set())).add(#{realm.id});")
+        ctx.eval_void("(globalThis.__csimChildRealmIds || (globalThis.__csimChildRealmIds = new Set())).add(#{realm.id});")
         # Remember the window's opener / name so a self-navigation (reload_window_realm
         # builds a FRESH realm) can carry them across — a real popup keeps window.opener
         # and window.name through its own navigation.
-        window_realm_meta[realm.id] = {opener_id: opener_id, window_name: window_name}
+        window_realm_meta[realm.id] = {opener_id: opener_id, window_name: window_name, about_base: about_base, about_origin: about_origin}
         realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
+        # As in create_frame_realm: an auxiliary window is a client of its origin too.
+        realm.call('__csim_swReportClient') rescue nil
         realm.call('__csimFireWindowLoad') rescue nil
         realm.id
       rescue StandardError => e
@@ -1019,9 +1096,19 @@ module Capybara
       # by default, or a frame realm + its realm-local cache (Module handles are
       # context-bound; sharing the main cache would link a frame's imports
       # against main-context modules).
-      def eval_esm_module(url, inline_src = nil, target: nil, handles: nil)
+      def eval_esm_module(url, inline_src = nil, target: nil, handles: nil, sw: nil)
         target  ||= ctx
         handles ||= native_module_handles
+        # A CONTROLLED document's module-graph source fetches dispatch SW fetch
+        # events (destination 'script', mode 'cors'). The context is recorded per
+        # REALM (not scoped to this call) so a dynamic `import()` resolved later
+        # by the isolate resolver still finds it; `root` carries the entry URL,
+        # whose fetch alone uses the element's own `integrity` attribute.
+        # KNOWN LOSS (documented divergence): one slot per realm means the LAST
+        # evaluated script's fetch options win — a deferred import() from an
+        # earlier script picks up the later script's credentials/root. Spec wants
+        # per-referring-script options; no vendored test observes the difference.
+        module_sw_ctxs[realm_key(target)] = sw&.merge(root: url.to_s)
         m = native_module_for(url, inline_src, target, handles)
         return nil unless m
         begin
@@ -1062,7 +1149,27 @@ module Capybara
       def native_module_for(url, inline_src, target, handles)
         return handles[url] if handles.key?(url)
         url_s = url.to_s
-        src = inline_src || @browser.rack_fetch_body(url_s)
+        src   = inline_src
+        if src.nil? && (sw = module_sw_ctxs[realm_key(target)])
+          # Only the graph's ENTRY fetch carries the element's integrity
+          # attribute; every other module resolves integrity from the import map
+          # (HTML "resolve a module integrity metadata").
+          integ = url_s == sw[:root] ? sw[:integrity].to_s : ''
+          integ = @browser.importmap_integrity(url_s) if integ.empty?
+          r = @browser.sw_script_subresource_fetch(
+            sw[:handle],
+            url_s,
+            sw[:client_id],
+            sw[:referrer],
+            'script',
+            'cors',
+            sw[:credentials] || 'same-origin',
+            integrity: integ
+          )
+          return handles[url] = nil if r && r['blocked']   # respondWith failed the load
+          src = r && r['body']
+        end
+        src ||= @browser.rack_fetch_body(url_s)
         return handles[url] = nil unless src
         body = module_body(url_s, src)
         # No-cd warm path: once this isolate has compiled a URL, its in-memory
@@ -1118,8 +1225,8 @@ module Capybara
       # realm-correctness as static `<script type=module>` via
       # `attach_realm_esm_entry`.
       def attach_native_module_loader(c)
-        c.attach('__csim_evalEsmEntry', ->(url, inline) {
-          RuntimeShared.safe_call { eval_esm_module(url, inline) }
+        c.attach('__csim_evalEsmEntry', ->(url, inline, *sw) {
+          RuntimeShared.safe_call { eval_esm_module(url, inline, sw: esm_sw_ctx(sw)) }
           nil
         })
         c.dynamic_import_resolver = ->(specifier, referrer, initiating) {
@@ -1145,11 +1252,43 @@ module Capybara
         (@realm_module_handles ||= {})[realm_id] ||= {}
       end
 
+      # realm -> SW fetch context for module-source fetches (see eval_esm_module).
+      # Invalidated exactly like native_module_handles (a service worker OUTLIVES
+      # navigation, so a stale entry would be ACTIVE, not inert: the next page's
+      # dynamic import would dispatch fetch events for an uncontrolled document);
+      # frame-realm entries also drop with their realm in the dispose paths.
+      def module_sw_ctxs
+        @module_sw_ctxs ||= {}
+        key = [ctx.object_id, ctx.generation]
+        if @module_sw_ctxs_key != key
+          @module_sw_ctxs     = {}
+          @module_sw_ctxs_key = key
+        end
+        @module_sw_ctxs
+      end
+
+      def realm_key(target)
+        target.equal?(ctx) ? 0 : target.id
+      end
+
+      # The optional [handle, clientId, referrer, credentials, integrity] tail
+      # moduleSwCtx (bridge.entry.js) appends to __csim_evalEsmEntry, or nil.
+      def esm_sw_ctx(sw)
+        return nil unless sw && sw[0].to_i.positive?
+        {
+          handle:      sw[0].to_i,
+          client_id:   sw[1].to_s,
+          referrer:    sw[2].to_s,
+          credentials: sw[3].to_s,
+          integrity:   sw[4].to_s
+        }
+      end
+
       # Frame-document `<script type=module>` entry, bound to the realm.
       def attach_realm_esm_entry(realm)
-        realm.attach('__csim_evalEsmEntry', ->(url, inline) {
+        realm.attach('__csim_evalEsmEntry', ->(url, inline, *sw) {
           RuntimeShared.safe_call {
-            eval_esm_module(url, inline, target: realm, handles: realm_module_handles(realm.id))
+            eval_esm_module(url, inline, target: realm, handles: realm_module_handles(realm.id), sw: esm_sw_ctx(sw))
           }
           nil
         })
@@ -1193,15 +1332,7 @@ module Capybara
         # pay the rendezvous round-trip.
         c.attach('__csim_runScriptCached', ->(label, body) {
           RuntimeShared.safe_call {
-            # Trailing `;undefined` suppresses the script's COMPLETION VALUE so
-            # `script.run`'s return crosses the V8→Ruby boundary on the trivial
-            # marshalling fast path. Without it, a large inline script ending
-            # in a jQuery-ish expression returns a `ce.fn.init` (array-like,
-            # non-cloneable) that drags through the deep-copy filter —
-            # pure waste, since the value is discarded (`nil` below). The SHA keys
-            # the bytecode cache on the COMPILED source, so the suffix must be
-            # hashed and fed to `queue_warm` too (else cached_data is rejected).
-            src = "#{body}\n;undefined"
+            src = body.to_s
             # No-cd warm path, mirroring `native_module_for`: once this
             # isolate has compiled a (label, bytesize), re-visits compile
             # straight against V8's source-keyed in-memory cache — skipping
@@ -1227,7 +1358,13 @@ module Capybara
               @compiled_script_keys[key] = true if key
             end
             begin
-              script.run
+              # run_void, not run: a `<script>`'s completion value is nobody's
+              # answer, and marshalling it would drag a large inline script's
+              # trailing jQuery-ish expression (a non-cloneable `ce.fn.init`)
+              # through the deep-copy filter for nothing. This is why `src` is
+              # the body verbatim — it used to carry a `;undefined` suffix, which
+              # then had to be hashed into the bytecode-cache key as well.
+              script.run_void
             ensure
               script.dispose
             end
@@ -1269,17 +1406,15 @@ module Capybara
         # as the QuickJS runner does. Swallowing here would turn a
         # throwing leading-`const` inline script into a silent `load`.
         c.attach('__csim_runScriptEval', ->(label, body) {
-          # Trailing `;undefined` makes the script's COMPLETION VALUE undefined so
-          # `c.eval`'s return crosses the V8→Ruby boundary on the trivial
-          # marshalling fast path. Without it, a leading-lexical inline script
-          # ending in a jQuery-ish expression (`const cfg=…; $(…)`) returns a
-          # `ce.fn.init` (array-like, non-cloneable) here, which falls into the
-          # deep-copy filter slow-path — pure waste, since the value
-          # is discarded (`nil` below). The `//# sourceURL` line is a comment and
-          # doesn't affect the completion value; lexical declarations persist as a
+          # A `<script>`'s completion value is nobody's answer, and reading it is
+          # not free: a leading-lexical inline script ending in a jQuery-ish
+          # expression (`const cfg=…; $(…)`) evaluates to a `ce.fn.init`
+          # (array-like, non-cloneable) that drags through the deep-copy filter,
+          # and a hostile getter in there would raise an error this call has no
+          # business raising. `eval_void` says so outright, replacing the trailing
+          # `;undefined` this used to append. Lexical declarations persist as a
           # side effect of eval, independent of the completion value.
-          c.eval("#{body}\n;undefined\n//# sourceURL=#{label.to_s.tr("\n", ' ')}")
-          nil
+          c.eval_void("#{body}\n//# sourceURL=#{label.to_s.tr("\n", ' ')}")
         })
         install_run_script_dispatcher(c)
       end
@@ -1291,7 +1426,7 @@ module Capybara
       # run after the attaches it captures (`attach_run_script_with_cache`
       # installs it last for exactly that reason).
       def install_run_script_dispatcher(c)
-        c.eval(<<~JS)
+        c.eval_void(<<~JS)
           (function () {
             const cached    = globalThis.__csim_runScriptCached;
             const runEval   = globalThis.__csim_runScriptEval;
@@ -1299,6 +1434,18 @@ module Capybara
             // Leading top-level lexical declaration, after optional BOM /
             // whitespace / line+block comments / a "use strict" prologue.
             const LEADS_LEXICAL = /^[\\s\\uFEFF]*(?:(?:\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/)\\s*)*(?:["']use strict["'];?\\s*)?(?:export\\s+)?(?:const|let|class)[\\s{\\[]/;
+            // A top-level lexical declaration can also sit MID-file (WPT's
+            // cookie-helper.sub.js opens with an IIFE and declares `const
+            // wait_for_message` at line 129) — under `(0, eval)` it block-scopes
+            // and later <script>s see a ReferenceError. Detect it by a
+            // declaration at COLUMN 0 of any line: real top-level declarations
+            // in unminified files start unindented, function-body ones are
+            // indented. Residual known gap: a one-line `stmt; const CFG = …`
+            // (declaration mid-LINE) still takes the fast path and loses the
+            // binding — no observed page does this. A false positive (a template
+            // literal's line starting with `const `) merely routes through the
+            // always-correct ctx.eval path.
+            const MID_LEXICAL = /^(?:const|let|class)[\\s{\\[]/m;
             // A "use strict" directive prologue. A classic <script> evaluates as a
             // top-level Script, where top-level `var` / `function` declarations
             // bind on the global object even in strict mode — but the JS-only
@@ -1310,7 +1457,7 @@ module Capybara
             const LEADS_USE_STRICT = /^[\\s\\uFEFF]*(?:(?:\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/)\\s*)*["']use strict["']/;
             globalThis.__csim_runScript = function (label, body) {
               if (body.length >= threshold) return cached(label, body);
-              if (LEADS_LEXICAL.test(body) || LEADS_USE_STRICT.test(body)) return runEval(label || 'csim-eval', body);
+              if (LEADS_LEXICAL.test(body) || LEADS_USE_STRICT.test(body) || MID_LEXICAL.test(body)) return runEval(label || 'csim-eval', body);
               (0, eval)(body + '\\n//# sourceURL=' + (label || 'csim-eval'));
             };
           })();
@@ -1323,8 +1470,8 @@ module Capybara
       # `__csim_installWorker()` post-snapshot init; the `__csim_runScript`
       # dispatcher comes from `attach_run_script_with_cache` (realm-bound).
       def reseed_realm_js(c)
-        c.eval("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
-        c.eval('__csim_installWorker();')
+        c.eval_void("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
+        c.eval_void('__csim_installWorker();')
       end
 
       # Class-level attach so Worker isolates (Ruby-thread-owned
@@ -1345,7 +1492,7 @@ module Capybara
         # microtask-checkpoint semantics. Alias it to the namespace's native
         # in-isolate checkpoint so callers pay ~sub-µs instead of an
         # attached-fn cross-thread round-trip.
-        c.eval("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
+        c.eval_void("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
         # Register the bridge's recorder for V8's promise-reject notifications
         # — the channel that surfaces rejections NO handler ever sees
         # (fire-and-forget async functions, bare `Promise.reject`); the
@@ -1354,7 +1501,7 @@ module Capybara
         # unhandled-rejection.js leaves registration to us. Main realm only —
         # the recorder routes per-realm via `contextGlobal` itself, and a
         # frame-realm registration would dangle once that realm is disposed.
-        c.eval(<<~JS)
+        c.eval_void(<<~JS)
           if (typeof globalThis.#{HOST_NAMESPACE_NAME}.setPromiseRejectHandler === 'function' &&
               typeof globalThis.__csimPromiseRejected === 'function') {
             globalThis.#{HOST_NAMESPACE_NAME}.setPromiseRejectHandler(globalThis.__csimPromiseRejected);
@@ -1375,7 +1522,14 @@ module Capybara
         # deliver_worker_messages): client.postMessage, clients.claim (set the client's controller),
         # and a controlled fetch's respondWith result. See run_worker for the closures.
         c.attach('__csim_swPostToClient', ->(client_id, data) { sw_hooks[:post_to_client]&.call(client_id, data); nil }) if sw_hooks[:post_to_client]
+        c.attach('__csim_swFocusClient',   ->(client_id)       { sw_hooks[:focus_client]&.call(client_id);       nil }) if sw_hooks[:focus_client]
+        c.attach('__csim_swNavigateClient', ->(client_id, url, nav_id) { sw_hooks[:navigate_client]&.call(client_id, url, nav_id); nil }) if sw_hooks[:navigate_client]
         c.attach('__csim_swClaim',        ->                  { sw_hooks[:claim]&.call; nil }) if sw_hooks[:claim]
+        c.attach('__csim_swSkipWaitingRequest', ->             { sw_hooks[:skip_waiting]&.call; nil }) if sw_hooks[:skip_waiting]
+        c.attach('__csim_swNoteRouterRules',    ->             { sw_hooks[:router]&.call; nil }) if sw_hooks[:router]
+        c.attach('__csim_swRaceNetwork', ->(fetch_id, realm_id, url, method) { sw_hooks[:race_network]&.call(fetch_id, realm_id, url, method); nil }) if sw_hooks[:race_network]
+        c.attach('__csim_swUnregisterRequest',  ->             { sw_hooks[:unregister]&.call; nil }) if sw_hooks[:unregister]
+        c.attach('__csim_swExtendedChanged',    ->(n)          { sw_hooks[:extended]&.call(n); nil }) if sw_hooks[:extended]
         c.attach('__csim_swFetchRespond', ->(fetch_id, resp, realm_id) { sw_hooks[:fetch_respond]&.call(fetch_id, resp, realm_id); nil }) if sw_hooks[:fetch_respond]
         c.attach('__csim_swFetchStream',  ->(fetch_id, kind, payload, realm_id) { sw_hooks[:fetch_stream]&.call(fetch_id, kind, payload, realm_id); nil }) if sw_hooks[:fetch_stream]
         # Cross-isolate MessagePort channel signals (a worker/SW port endpoint + its outbound messages).
@@ -1398,15 +1552,56 @@ module Capybara
         # join the realm's shared global lexical environment where later code sees them.
         # `(0, eval)` would block-scope them to the eval and they'd vanish. `c.eval` is
         # the top-level-script path (same as the worker's own body eval).
-        c.attach('__csim_workerImportEval', ->(src) { c.eval(src.to_s); nil })
-        c.eval('__csim_installWorkerScope();')
+        c.attach('__csim_workerImportEval', ->(src) { c.eval_void(src.to_s) })
+        c.eval_void('__csim_installWorkerScope();')
         WorkerRuntime.new(
-          eval_fn:           ->(s)     { c.eval(s.to_s) },
+          eval_void_fn:      ->(s)     { c.eval_void(s.to_s) },
           call_fn:           ->(n, *a) { c.call(n.to_s, *a) },
           drain_microtasks:  ->        { c.perform_microtask_checkpoint },
           drain_timers:      ->        { c.call('__drainTimers', 50) },
           has_ready_timer:   ->        { !!c.call('__hasReadyTimer') },
-          dispose:           ->        { c.dispose rescue nil }
+          dispose:           ->        { c.dispose rescue nil },
+          # Called from the SESSION BOUNDARY's thread, not this worker's: V8's terminate is
+          # thread-safe by design, and it is the only way to end a call that is already running.
+          terminate:         ->        { c.terminate rescue nil },
+          # A `{type: 'module'}` service worker's main script + static import graph,
+          # via V8's native module API (the same surface the main realm's
+          # eval_esm_module uses). The whole graph resolves through the root's
+          # instantiate callback (V8 calls it per unresolved edge, transitively);
+          # `fetch_import` runs on the worker's own thread and raises to fail the
+          # evaluation. Specifier resolution is PLAIN URL resolution — a worker has
+          # no document, so the page's importmap does not apply, and a bare
+          # specifier is a resolution failure per the spec.
+          eval_module_graph: lambda {|src, url, fetch_import|
+            src_text = RuntimeShared.utf8_text(src.to_s.dup)
+            handles = {}
+            root = c.compile_module(src_text, filename: url.to_s)
+            handles[url.to_s] = root
+            root.instantiate do |spec, ref|
+              s = spec.to_s
+              resolved =
+                if s.match?(%r{\A[a-z]+://}i)
+                  s
+                elsif s.start_with?('/', './', '../')
+                  URI.join((ref || url).to_s, s).to_s
+                else
+                  raise "Failed to resolve module specifier '#{s}'"
+                end
+              handles[resolved] ||= c.compile_module(RuntimeShared.utf8_text(fetch_import.call(resolved).to_s.dup), filename: resolved)
+            end
+            # Top-level await is disallowed in a service worker module ("Run Service
+            # Worker" fails the script; Chrome rejects the registration). V8's
+            # IsGraphAsync (Module#graph_async?) answers it for the WHOLE
+            # instantiated graph, which is what the spec asks: TLA hiding in an
+            # imported module fails too. Per-module `[[HasTLA]]` would name the
+            # offender but not this question — it can't see an imported module's
+            # await. This lambda serves service workers only; a dedicated module
+            # worker, where TLA is legal, would need the check parameterized.
+            raise 'Top-level await is disallowed in a service worker' if root.graph_async?
+
+            root.evaluate
+            nil
+          }
         )
       end
     end

data/lib/capybara/simulated/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Simulated
-    VERSION = '0.8.0'
+    VERSION = '0.10.0'
   end
 end