capybara-simulated 0.9.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!
@@ -434,6 +445,7 @@ module Capybara
 
       def dispose_frame_realms
         @realm_module_handles&.clear
+        @module_sw_ctxs&.clear
         @frame_realm_depths&.clear
         @frame_realm_parents&.clear
         @window_realm_meta&.clear
@@ -449,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
@@ -499,6 +511,7 @@ module Capybara
         # 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)
@@ -507,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
@@ -598,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}"
@@ -726,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
@@ -748,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
 
@@ -768,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, frame_viewport = 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) }
+        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
@@ -814,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, frame_viewport = 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}")
@@ -841,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) {
@@ -869,6 +890,15 @@ 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.
@@ -959,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
@@ -983,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 {
@@ -999,7 +1030,7 @@ 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;
@@ -1035,7 +1066,7 @@ 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.
@@ -1065,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
@@ -1108,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
@@ -1164,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) {
@@ -1191,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
         })
@@ -1239,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
@@ -1273,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
@@ -1315,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
@@ -1337,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;
@@ -1345,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
@@ -1356,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'));
             };
           })();
@@ -1369,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
@@ -1391,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
@@ -1400,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);
@@ -1425,6 +1526,10 @@ module Capybara
         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).
@@ -1447,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.9.0'
+    VERSION = '0.10.0'
   end
 end

data/lib/capybara/simulated/worker_runtime.rb

@@ -5,26 +5,49 @@ module Capybara
     # Engine-uniform adapter Browser#run_worker drives. Each engine
     # class (`V8Runtime`, `QuickJSRuntime`) has a `build_worker` class
     # method that constructs the engine-specific Context/VM and wires
-    # it through these five callbacks. Worker thread doesn't care
-    # which engine it's running on; it just calls `eval` / `call` /
+    # it through these callbacks. Worker thread doesn't care
+    # which engine it's running on; it just calls `eval_void` / `call` /
     # `drain_microtasks` / `drain_timers` / `has_ready_timer?` /
-    # `dispose`.
+    # `terminate` / `dispose`.
     class WorkerRuntime
-      def initialize(eval_fn:, call_fn:, drain_microtasks:, drain_timers:, has_ready_timer:, dispose:)
-        @eval             = eval_fn
-        @call             = call_fn
-        @drain_microtasks = drain_microtasks
-        @drain_timers     = drain_timers
-        @has_ready_timer  = has_ready_timer
-        @dispose          = dispose
+      def initialize(eval_void_fn:, call_fn:, drain_microtasks:, drain_timers:, has_ready_timer:, dispose:, terminate: nil, eval_module_graph: nil)
+        @eval_void         = eval_void_fn
+        @call              = call_fn
+        @drain_microtasks  = drain_microtasks
+        @drain_timers      = drain_timers
+        @has_ready_timer   = has_ready_timer
+        @dispose           = dispose
+        @terminate         = terminate
+        @eval_module_graph = eval_module_graph
       end
 
-      def eval(src)                  = @eval.call(src)
+      def eval_void(src)             = @eval_void.call(src)
       def call(name, *args)          = @call.call(name, *args)
       def drain_microtasks           = @drain_microtasks.call
       def drain_timers               = @drain_timers.call
       def has_ready_timer?           = @has_ready_timer.call
       def dispose                    = @dispose.call
+      # Stop whatever JavaScript this worker is running, FROM ANOTHER THREAD — the one thing the
+      # main thread can do to a worker that is inside a call, where the `:terminate` inbox message
+      # cannot reach it and `Thread#kill` does not land (see `Browser#stop_worker_js`). The call in
+      # flight ends as a terminated call; the worker's own loop then unwinds and disposes.
+      # `nil` on an engine with nothing to hand back — QuickJS — where this is a no-op.
+      def terminate                  = @terminate&.call
+      # Can this engine stop a call from ANOTHER thread at all? V8 can; QuickJS cannot. The
+      # boundary asks, because the answer changes what it should do next: where there is nothing
+      # to terminate, waiting for a terminate to work is pure delay and `Thread#kill` — which does
+      # land on that engine — is the right escalation.
+      def terminable?                = !@terminate.nil?
+
+      # Native ES-module evaluation of a worker MAIN script + its static import
+      # graph (a `{type: 'module'}` service worker). `fetch_import` is called on
+      # the worker's own thread for each resolved static import URL and returns
+      # the script source (raising fails the evaluation — an import that 404s or
+      # has a non-JS MIME type fails the module script, and with it the Run
+      # Service Worker job). nil on engines without a native module API
+      # (QuickJS) — the caller falls back to the classic-eval path.
+      def module_graph?                             = !@eval_module_graph.nil?
+      def eval_module_graph(src, url, fetch_import) = @eval_module_graph.call(src, url, fetch_import)
     end
   end
 end

data/lib/capybara/simulated.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 require 'capybara'
+# The rasteriser behind image decoding and the canvas surface — required HERE rather than lazily at
+# each use, because a bundle without it does not merely lose canvas: an image's intrinsic size feeds
+# LAYOUT, so pages with images would be laid out wrong while only warning. The gem is a hard
+# dependency; what can still be missing is the libvips SYSTEM library it binds to, so name it.
+begin
+  require 'vips'
+rescue LoadError => e
+  raise LoadError, "capybara-simulated needs the libvips system library (Debian/Ubuntu " \
+                   "`libvips42`, Homebrew `vips`, Gentoo `media-libs/vips`): #{e.message}"
+end
 require 'capybara/simulated/version'
 require 'capybara/simulated/driver'
 
@@ -24,6 +34,10 @@ module Capybara
     # set together. Read-and-cleared by the register_driver block.
     class << self
       attr_accessor :next_driver_viewport, :next_driver_user_agent
+
+      # Empty the process-wide HTTP cache (see `Driver#clear_http_cache`) — the
+      # module-level form for a hook that runs before any session exists.
+      def clear_http_cache = Browser.clear_http_cache
     end
   end
 end