capybara-simulated 0.4.0 → 0.6.0

data/lib/capybara/simulated/v8_runtime.rb

@@ -152,6 +152,10 @@ 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`.
+        def heap_statistics                  = @iso.heap_statistics
+        def low_memory_notification          = @iso.low_memory_notification
 
         def dynamic_import_resolver=(prc)
           @iso.dynamic_import_resolver = prc
@@ -360,6 +364,10 @@ module Capybara
       # Browser's `@current_realm_id` may still point at it; the Browser uses
       # this to raise a stale-element instead of running a frame handle op
       # against the main registry.
+      # Ids of every live frame / window realm in this isolate (excludes the main
+      # realm, id 0). Used to fan a BroadcastChannel post out to sibling realms.
+      def frame_realm_ids = frame_realms.keys
+
       def frame_realm_alive?(realm_id)
         !(realm_id.nil? || realm_id.zero?) && frame_realms.key?(realm_id)
       end
@@ -396,8 +404,29 @@ module Capybara
       # nothing else would ever free them.
       def frame_realms = (@frame_realms ||= {})
 
+      # Parent realm id per frame realm, captured at `create_frame_realm` time
+      # (parallel to `@frame_realm_depths`). Lets a form/navigation that reaches a
+      # frame via `contentWindow` (so it never entered `within_frame` and has no
+      # `@frame_stack` entry) recover the realm that OWNS the iframe element, to
+      # rebuild + rebind it. 0/nil = the main realm.
+      def frame_realm_parents = (@frame_realm_parents ||= {})
+
+      def frame_realm_parent(realm_id)
+        return 0 if realm_id.nil? || realm_id.zero?
+        frame_realm_parents[realm_id] || 0
+      end
+
+      # Per-window-realm metadata (opener id + window.name) captured at create time so a
+      # window's self-navigation (which builds a fresh realm via `reload_window_realm`)
+      # can carry them across, the way a real popup keeps `window.opener` / `window.name`
+      # through its own navigation.
+      def window_realm_meta = (@window_realm_meta ||= {})
+
       def dispose_frame_realms
         @realm_module_handles&.clear
+        @frame_realm_depths&.clear
+        @frame_realm_parents&.clear
+        @window_realm_meta&.clear
         return if @frame_realms.nil?
         @frame_realms.each_value {|fr| fr.dispose rescue nil }
         @frame_realms.clear
@@ -415,11 +444,35 @@ module Capybara
         create_frame_realm(ctx, url, body, content_type, parent_id)
       end
 
+      # Navigate a window realm (`win.location = …`): a FRESH realm for the new
+      # document, like reload_frame_realm — an in-place `__csimLoadDocument` on an
+      # already-loaded realm does NOT re-run inline scripts, but a fresh realm does.
+      # Returns the new realm's context id. (The opener's WindowProxy, keyed by the
+      # old id, goes stale across this — acceptable while no window.open test scripts
+      # the window after navigating it; a stable WindowProxy is future work.)
+      def reload_window_realm(old_id, url, body, content_type)
+        meta = window_realm_meta[old_id] || {}
+        dispose_frame_realm(old_id)
+        create_window_realm(url, body, content_type, opener_id: meta[:opener_id], window_name: meta[:window_name])
+      end
+
       # Tear down a single frame realm (e.g. a descendant frame destroyed when an
       # ancestor frame re-navigates). No-op for nil/0/unknown ids.
       def dispose_frame_realm(id)
         return if id.nil? || id.zero?
+        # The frame's browsing context is going away — revoke the blob URLs it
+        # created (url-lifetime "Removing an iframe").
+        @browser.revoke_realm_blobs(id) rescue nil
         @realm_module_handles&.delete(id)
+        @frame_realm_depths&.delete(id)
+        @frame_realm_parents&.delete(id)
+        @window_realm_meta&.delete(id)
+        # Evict from the main realm's child-realm set so `drainChildRealms` stops
+        # stepping a disposed context. A FRAME realm is also evicted via the DOM
+        # 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
         fr = frame_realms.delete(id)
         fr.dispose rescue nil if fr
         nil
@@ -499,6 +552,16 @@ module Capybara
         if @ctx
           begin
             @ctx.reset
+            # `@ctx.reset` swaps in a snapshot-fresh realm and `dispose_frame_realms`
+            # above tore down the visit's iframe realms — but V8 keeps those dead
+            # contexts as RECLAIMABLE GARBAGE: a per-frame realm (within_frame /
+            # `Isolate#create_context`) is a large GC root that V8's incremental
+            # GC won't collect between visits. Over a long run (esp. iframe-heavy
+            # pages) they pile toward the old-space cap, where the near-heap-limit
+            # GC thrashes instead of reclaiming. A full GC under pressure drops the
+            # used heap back to baseline (measured: ~450 MB -> ~150 MB, native
+            # contexts N -> 1). See `relieve_heap_pressure`.
+            relieve_heap_pressure
             attach_host_fns(@ctx)
             @ctx.eval('__csim_installWorker();')
             return @ctx
@@ -520,14 +583,7 @@ module Capybara
         # `ctx`), which rusty_racer's thread-confined isolates require. This
         # cold path is only the rare reset-failure fallback, so the inline
         # teardown isn't on the steady-state path.
-        if old
-          @@live_lock.synchronize { @@live.delete(old) }
-          begin
-            old.terminate rescue nil
-            old.dispose
-          rescue StandardError
-          end
-        end
+        dispose_ctx(old) if old
         @ctx = build_and_track_ctx
       end
 
@@ -536,6 +592,48 @@ module Capybara
       # path is the same operation.
       def reset_page = rebuild_ctx
 
+      # Memory-pressure threshold (MB) above which `rebuild_ctx` forces a full
+      # GC to reclaim dead per-frame realms (see the call site). Measured
+      # against used heap **+ external** (ArrayBuffer backing stores, image
+      # pixel buffers) — `used_heap_size` alone misses the external component,
+      # which on image-heavy specs is the bulk of the footprint. Default 1 GB:
+      # far above a normal single visit (~200-500 MB) so ordinary specs never
+      # trigger it, far below the 4 GB old-space cap so a multi-visit spec
+      # reclaims long before the near-heap-limit GC would thrash. `0` disables.
+      GC_PRESSURE_MB = (ENV['CSIM_V8_GC_PRESSURE_MB'] || '1024').to_i
+
+      # Opt-in heap accounting on every rebuild (CSIM_HEAP_DIAG). Resolved once
+      # at load (rule 3: don't re-read env per call); zero cost when off.
+      HEAP_DIAG = !ENV['CSIM_HEAP_DIAG'].nil?
+
+      # Forced full GC when V8-managed memory (used heap + external) crosses
+      # GC_PRESSURE_MB. The stat read is cheap (a counter snapshot every visit);
+      # the GC itself only fires once a multi-visit spec has actually piled up
+      # dead realms — measured at ~once per 25-50 iframe-heavy visits, reclaiming
+      # native contexts back to 1 and the heap to baseline — so the amortized
+      # cost is negligible while memory stays bounded. No-op when disabled
+      # (GC_PRESSURE_MB <= 0).
+      def relieve_heap_pressure
+        return unless GC_PRESSURE_MB.positive?
+        s    = @ctx.heap_statistics
+        over = (s[:used_heap_size].to_i + s[:external_memory].to_i) > GC_PRESSURE_MB * 1_048_576
+        if HEAP_DIAG
+          warn(format('[csim heap] used=%dMB ext=%dMB native_ctx=%d over=%s',
+                      s[:used_heap_size].to_i >> 20, s[:external_memory].to_i >> 20,
+                      s[:number_of_native_contexts].to_i, over))
+        end
+        return unless over
+        @ctx.low_memory_notification
+        if HEAP_DIAG
+          a = @ctx.heap_statistics
+          warn(format('[csim heap]   -> after GC used=%dMB native_ctx=%d',
+                      a[:used_heap_size].to_i >> 20, a[:number_of_native_contexts].to_i))
+        end
+      rescue StandardError
+        # A transient read failure — heap relief is best-effort, never fail a
+        # visit over it.
+      end
+
       # Built lazily on first use, on the calling (main) thread. There is no
       # pool / background pre-warm: under warm-compile the steady-state visit
       # reuses this one isolate via `Context#reset` (rebuild_ctx) and never
@@ -545,6 +643,7 @@ module Capybara
       # every isolate confined to one thread for its whole life. The one-time
       # synchronous build is ~3 ms.
       def ctx
+        return @ctx if @disposed   # don't resurrect a disposed runtime (closed window)
         @ctx ||= build_and_track_ctx
       end
 
@@ -555,11 +654,46 @@ module Capybara
         c
       end
 
+      # Terminate + dispose a tracked isolate and drop it from the at-exit
+      # `@@live` registry. Dispose FIRST and de-register only on success: if
+      # `dispose` raises (rescued), the isolate stays in `@@live` so the at_exit
+      # sweep retries it instead of leaking it un-disposed. Shared by the
+      # cold-rebuild fallback (`rebuild_ctx`) and `#dispose`.
+      def dispose_ctx(c)
+        return unless c
+        c.terminate rescue nil
+        c.dispose
+        @@live_lock.synchronize { @@live.delete(c) }
+      rescue StandardError
+      end
+
+      # Tear this runtime's isolate down for good. Each auxiliary window
+      # (`window.open` / a switched-into `target=_blank`) is its own Browser +
+      # V8Runtime + isolate; without this, closing the window reaped its
+      # background threads (Browser#dispose) but left the isolate ALIVE — the
+      # `@@live` at-exit registry holds a strong reference, so a bare GC never
+      # reclaimed it. Over a long suite those isolates (and their RSS)
+      # accumulated (measured: V8 isolate count 2 → 10, RSS ~2.7 → 6.6 GB across
+      # the Discourse suite). Idempotent; only ever called on teardown
+      # (Browser#dispose) — never on the per-test `reset_page` path, which
+      # reuses the isolate via `Context#reset`. The `ctx` getter stops rebuilding
+      # once `@disposed`, so a stray post-close call can't resurrect the isolate.
+      def dispose
+        return if @disposed
+        @disposed = true
+        dispose_frame_realms rescue nil
+        c, @ctx = @ctx, nil
+        dispose_ctx(c)
+      end
+
       # Per-call wall-clock cap (ms). Off by default. Opt in via
       # `CSIM_V8_CALL_TIMEOUT_MS=30000` for long-running suites where an
       # occasional JS-side infinite loop would otherwise stall the whole
       # run; the timeout converts the hang into a
-      # `RustyRacer::ScriptTerminatedError` on that one example. The
+      # `RustyRacer::ScriptTerminatedError` on that one example — whose
+      # `#message` / `#js_backtrace` (rusty >= 0.1.10) 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
       # isolate-global by design), and the isolate itself stays healthy
       # for subsequent calls — csim treats a terminated call as fatal to
@@ -599,17 +733,15 @@ 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) {
-          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id) }
+        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) {
+          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id, frame_name, frame_doc_origin, frame_location_origin, js_url_source) }
         })
         # 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
         # linger in @frame_realms and get re-drained on every poll tick.
         # Disposing a non-executing child realm mid-callback is safe.
         c.attach('__csim_disposeFrameRealm', ->(id) {
-          @realm_module_handles&.delete(id)
-          fr = frame_realms.delete(id)
-          fr.dispose rescue nil if fr
+          dispose_frame_realm(id)   # also revokes the realm's blob URLs
           nil
         })
       end
@@ -620,22 +752,46 @@ module Capybara
       # state, point it at its own URL with the top frame as parent/top, then
       # load its document (running its scripts in the realm). Tracked for
       # event-loop draining + teardown.
-      def create_frame_realm(parent_ctx, url, body, content_type, parent_id = 0)
-        realm = parent_ctx.create_context
-        # Re-evaling the snapshot source would redefine snapshot globals (e.g.
-        # the `scrollX` accessor) and throw — re-entrantly. Only eval the
-        # source on a bare no-snapshot dev ctx, where the realm boots empty.
-        # Host fns are replayed onto the realm by `Ctx#create_context`.
+      # Browsers cap nested browsing-context depth; with eager frame building a
+      # self-referential or pathologically nested iframe (`<iframe src=self>`)
+      # would otherwise build realms without bound and stall the settle loop.
+      # Depth is one more than the parent realm's (the main frame is depth 0).
+      MAX_FRAME_DEPTH = 16
+
+      def frame_realm_depths = (@frame_realm_depths ||= {})
+
+      # Bring a freshly-created realm context up to a runnable bridge, shared by the
+      # frame and window realm constructors. Re-evaling the snapshot source would
+      # redefine snapshot globals (e.g. the `scrollX` accessor) and throw, so only
+      # eval it on a bare no-snapshot dev ctx where the realm boots empty. The
+      # replayed `__csim_runScriptCached` / `__csim_evalEsmEntry` close over the MAIN
+      # ctx they were first attached to, so a realm script routing through them
+      # (leading-lexical, ≥64KB, or `type=module`) would run against the main
+      # 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
-        # The replayed `__csim_runScriptCached` / `__csim_runScriptEval` /
-        # `__csim_evalEsmEntry` close over the context they EXECUTE in (the
-        # main ctx) — left as-is, a frame script that routes through them
-        # (leading-lexical, ≥64KB, or `type=module`) would run against the
-        # PARENT realm's document. Rebind realm-executing variants on top.
         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)
+        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}")
+          return nil
+        end
+        realm = parent_ctx.create_context
+        # Record depth BEFORE loading the document: the frame's own scripts run
+        # during __csimLoadDocument below and may synchronously build NESTED frames
+        # (their create_frame_realm looks up this realm's depth as their parent's),
+        # so it must already be set or the nested depth undercounts and the cap
+        # never trips.
+        frame_realm_depths[realm.id]  = depth
+        frame_realm_parents[realm.id] = parent_id.to_i   # owning realm, for contentWindow-reached rebuilds
+        seed_realm_bridge(realm)
         # Wire `parent` / `top` to the realm that owns this iframe (its context
         # id passed from `__csimFrameWindow`), BEFORE the frame's scripts run —
         # `top` propagates up the chain (the main realm's `top` is itself). A
@@ -645,8 +801,22 @@ module Capybara
           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) {
-              globalThis.parent = __parentWin;
-              globalThis.top    = __parentWin.top || __parentWin;
+              // Expose `parent`/`top` as THIS realm's WindowProxy for them (not the
+              // raw parent global) so `e.source === parent` holds and a frame's
+              // `parent.postMessage(...)` attributes the sender. `top` resolves
+              // through the parent's own top (already a proxy if the parent is a
+              // frame), unwrapped to its raw global then re-proxied for this realm.
+              var __NS = globalThis.#{HOST_NAMESPACE_NAME};
+              var __pf = globalThis.__csimFrameWindowProxyFor;
+              if (__pf && __NS && typeof __NS.contextOf === 'function') {
+                var __topRaw = __parentWin.top || __parentWin;
+                if (__topRaw && __topRaw.__csimRawWindow) __topRaw = __topRaw.__csimRawWindow;
+                globalThis.parent = __pf(__NS.contextOf(__parentWin)) || __parentWin;
+                globalThis.top    = __pf(__NS.contextOf(__topRaw)) || __topRaw;
+              } else {
+                globalThis.parent = __parentWin;
+                globalThis.top    = __parentWin.top || __parentWin;
+              }
             }
           }
         JS
@@ -655,8 +825,42 @@ 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?
+        # 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?
+        # 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.
+        realm.call('__csimSetDocumentOrigin', frame_doc_origin.to_s) unless frame_doc_origin.nil?
+        # The frame's location.origin (opaque "null" for about:blank / srcdoc /
+        # javascript:); decoupled from the location string so navigation is intact.
+        realm.call('__csimSetLocationOrigin', frame_location_origin.to_s) unless frame_location_origin.nil?
         realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
+        # 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
+        # document built from it; any other result (incl. the common undefined)
+        # leaves the about:blank document, so only its side effects (e.g.
+        # `parent.foo()`) take effect. A throwing script is reported and left as a
+        # no-op rather than aborting the frame build.
+        unless js_url_source.nil?
+          begin
+            result = realm.eval(js_url_source.to_s)
+            realm.call('__csimLoadDocument', result, 'text/html') if result.is_a?(String)
+          rescue StandardError => e
+            @browser.log_console('warn', "javascript: URL frame threw: #{e.message}")
+          end
+        end
         frame_realms[realm.id] = realm
+        # Fire the nested document's window `load`. The frame's inline scripts ran
+        # during __csimLoadDocument and registered their `window.onload` (the usual
+        # `window.onload = () => parent.postMessage(...)` a frame reports back
+        # through); without firing it, an eagerly-built frame that the parent never
+        # touches would never run its load handler. Safe if no handler is set
+        # (dispatches to an empty listener list). Guarded so a frame whose load
+        # handler throws doesn't abort the build.
+        realm.call('__csimFireWindowLoad') rescue nil
         realm.id
       rescue StandardError => e
         @browser.log_console('warn', "frame realm load failed: #{e.message}")
@@ -671,6 +875,86 @@ module Capybara
         nil
       end
 
+      # Build a same-origin auxiliary WINDOW (window.open / open_new_window) as a
+      # realm in THIS isolate — like an iframe's frame realm, but top-level: `parent`
+      # === `top` === the window itself (the bridge default, so unlike
+      # create_frame_realm we don't wire them to a container), and `window.opener`
+      # points at the opener realm's WindowProxy. Tracked in `frame_realms` so
+      # realm_call / drainChildRealms / dispose_frame_realms cover it for free.
+      # Returns the new realm's context id; the opener-side `window.open` wraps it in
+      # 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)
+        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
+        # top-page path — top === self here, so neither default branch fits. Also give
+        # it the window-lifecycle surface a popup needs but a frame realm doesn't:
+        # `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)
+          globalThis.__csimIsWindowRealm = true;
+          globalThis.__csimWindowClosedFlag = false;
+          try {
+            Object.defineProperty(globalThis, 'closed', {
+              configurable: true,
+              get() { return !!globalThis.__csimWindowClosedFlag; }
+            });
+          } catch (_) {}
+          globalThis.close = function () { globalThis.__csimWindowClosedFlag = true; };
+        JS
+        # window.opener → a WindowProxy for the opener realm. opener_id is the opener's
+        # context id (0 = the main realm, a VALID opener); nil means "no opener", so the
+        # 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)
+            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?
+        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?
+        # Register the realm as alive BEFORE its document loads: its inline scripts run
+        # synchronously inside __csimLoadDocument and may post to a BroadcastChannel the
+        # opener listens on (a blob popup that posts then self.close()s). The delivery
+        # path gates on `frame_realm_alive?`, so the realm must already be tracked or its
+        # own load-time post is dropped. Mirrors create_frame_realm seeding its depth /
+        # parent maps before the load for the same reason.
+        frame_realms[realm.id]        = realm
+        frame_realm_parents[realm.id] = 0   # top-level (no parent frame)
+        # 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});")
+        # 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}
+        realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
+        realm.call('__csimFireWindowLoad') rescue nil
+        realm.id
+      rescue StandardError => e
+        @browser.log_console('warn', "window realm load failed: #{e.message}")
+        if realm
+          # The realm is registered (frame_realms / parents / __csimChildRealmIds)
+          # BEFORE the document loads, so a load-time throw must roll all of that back
+          # — otherwise frame_realm_alive? and drainChildRealms keep treating a
+          # disposed context as live. dispose_frame_realm unwinds the registries (and
+          # disposes if registered); the explicit dispose is the backstop for a throw
+          # that happened before registration.
+          dispose_frame_realm(realm.id)
+          realm.dispose rescue nil
+        end
+        nil
+      end
+
       # `target` is the context the module graph compiles + evaluates in,
       # `handles` its module-handle cache — the main ctx + `native_module_handles`
       # by default, or a frame realm + its realm-local cache (Module handles are
@@ -1034,6 +1318,12 @@ module Capybara
         # pending XHRs the moment the worker's queue empties. The settle
         # loop already polls `worker_pending?` for worker thread activity.
         c.attach('__setTimersActive', ->(_flag) { nil })
+        # `importScripts` runs a classic script at the worker's TOP-LEVEL script scope,
+        # so its top-level `const`/`let`/`class` (dispatcher.js's `const send`/`receive`)
+        # 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();')
         WorkerRuntime.new(
           eval_fn:           ->(s)     { c.eval(s.to_s) },

data/lib/capybara/simulated/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Simulated
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end