dommy-js-quickjs 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 582867f4a71527529224d5ecf3348461ff69e4b76518f5c8f0f9dc85c5704270
-  data.tar.gz: b183f4631ea255d7844b8b2f20cc68214863d3639eaa559e3cdc3f44e1ec04a0
+  metadata.gz: 56e600a474810ea778587cf249cbb7c200d9947c28270449837550971e5674de
+  data.tar.gz: ff9e6cf37ed37fb89f148163e38ee6fdd63e8bd5fc1e81669f8538eebc84d3ea
 SHA512:
-  metadata.gz: 0b185321865a0e45d9b880bbc8e25ef7936c8fb570e0b9a1a60ea21bd70af68efc8dfa5dd1f82a4d8214a237f8174eb1d6a5997a67db82a5bd6d92e8e2df7a70
-  data.tar.gz: 3fe107306181b587a96a1dac23bcd73f08f2f9484c9f61a105449508d6a9438cf2dfa76f8bdd8c997f5b511784c45e09e0dca7ab3546b28985b86118a7e26f4c
+  metadata.gz: ffa632c98fe6c8bedba9bc8e189cda13a1c9baef1c4bd0224fa1f7f9ffd31bdcaad8bcb84ffdbdf2b2436ec3a29bb68d0d8ceaa7879602f5cc45d8edbc1633ba
+  data.tar.gz: 22272e499d364204ecba6edb91cb6c01953d72d46990652b3f14907e2141686e8bbc8d94de3d5125e2f96b21e9e1a34b8d5c887c41af3dbe8cd693e33a2370bd

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.10.0 — 2026-10-01
+
+Requires `dommy >= 0.14.0, < 0.15` and `quickjs ~> 0.21.0`.
+
+### Added
+
+- Rejections are handed to a JS hook (`promise_rejection_hook=`) when the engine has one, so the promise and the reason cross as the values the page threw rather than an exception the engine already converted. That is what makes `event.reason`, `event.promise` and `rejectionhandled` work at all. `on_unhandled_rejection` goes quiet while the hook is installed, since both would report the same rejection.
+- `Runtime#rebuild_error` builds a real `Error` inside the realm from an exception QuickJS raised for a script's throw, so `event.error` reaches the page with the name, message and stack it threw instead of an object with no properties. The engine discards the JS value when it converts the throw, so the rebuilt error matches on everything observable except identity.
+- `rake capybara:compliance` runs Capybara's driver compliance suite against capybara-dommy with JavaScript on (`spec/capybara_compliance_spec.rb`). It is not part of `rake test`: it still fails in places (120 of 1413 examples today — asynchronous alerts, waiting on `current_path`, `attach_file`'s change events).
+
+### Changed
+
+- Requires `dommy >= 0.14.0, < 0.15` (was `>= 0.9.0`). 0.14.0 moved the wire tags from `Dommy::Js` to `Dommy::Bridge`, which the wasm bridge now reads, and 0.13.0 is the release carrying the JS error-report API this gem's suite drives (`Window#__internal_on_unhandled_error__`, `Browser#error_log`, `Dommy::JsError`). The upper bound is new: dommy's 0.x minors change the bridge contract, as 0.14.0 did — 0.9.0, which had none, breaks against it.
+- Requires `quickjs ~> 0.21.0` (was `~> 0.18.0`). Until both fixes are released upstream, the Gemfile pins [takahashim/quickjs.rb#feat/rejection-js-hook](https://github.com/takahashim/quickjs.rb/tree/feat/rejection-js-hook). It carries the JS rejection hook above, and sits on upstream's main with the checkpoint-timing fix ([hmsk/quickjs.rb#141](https://github.com/hmsk/quickjs.rb/pull/141), merged but not yet released) that reports an unhandled rejection at the end of the microtask checkpoint as HTML requires, rather than the moment a promise rejects. Without the latter, `Promise.reject(x).catch(...)` and `try { await rejecting() } catch {}` are both misreported as unhandled — correct code that a strict host then fails a test on. CI also runs the suite on the released 0.21.0 (`gemfiles/quickjs-released.gemfile`), which is what a RubyGems install gets.
+- `SourceGuard` is gone. It rewrote a `for...of` whose iterable contains a `yield` and retried, working around a QuickJS codegen bug ("stack underflow") that broke real SPA bundles. The QuickJS that 0.21 vendors compiles the construct, and the gemspec requires `~> 0.21.0`, so nothing could reach the retry — and nothing could test it either. Revert the removal if the bug ever comes back.
+- The gem's per-crossing `Timeout.timeout` is skipped by prepending to `::Quickjs`'s singleton rather than redefining `_with_timeout` outright, so the original stays reachable and the patch is visible in `ancestors`.
+- The last JavaScript built as a Ruby string moved into `js/error_rebuild.js`: rebuilding a thrown Error in the realm now calls a helper installed once per VM instead of evaluating freshly interpolated source on every reported error.
+- Every Backend entry point that runs something in the VM is guarded against a poisoned one, not just three of the six. After an out-of-memory an inline script quietly did nothing while an external (bytecode) script and `#evaluate` raised "VM is poisoned" from a different place each time; all of them now no-op, which is the "browsing never crashes" contract the guarded three already followed.
+- `DOMMY_JS_MEMORY_LIMIT_MB` sets the VM's memory ceiling, as `DOMMY_JS_TIMEOUT_MSEC` does the per-eval timeout. Lowering it is how the out-of-memory path gets exercised deliberately.
+- The realm's JavaScript (the Intl polyfill, the WebAssembly stub, the aliased browser globals, the mirrored built-ins, the timer instrumentation) moved out of Ruby heredocs into `.js` files under `lib/dommy/js/quickjs/js/`, installed by a new `BrowserEnvironment` through `Backend#run_bundle` — so each payload is compiled once per process rather than reparsed for every VM.
+- `Runtime` delegates to `EventLoop` (the microtask queue and Dommy's scheduler as one loop, with the three drivers sharing a pump), `ErrorTranslator` (an engine exception as what the page should see) and `Config` (every `DOMMY_JS_*` variable). Its public surface is now the Runtime port plus what hosts call; `evaluate_settled`, `bump_dom_epoch` and the other internals are private.
+- `Runtime#load_module` and `Backend#import_module` are gone, unused: an inline `<script type="module">` reaches the engine through `load_module_url`.
+- `install_wasm_memory_shim` installs the same WebAssembly stub as `install_browser_globals` rather than a second, near-identical one.
+- The vendored WPT tree is pinned to a single upstream revision (`test/fixtures/wpt/UPSTREAM_REVISION`) and refreshed with `script/vendor_wpt.sh`, rather than growing file by file from whatever upstream was that day. Refreshing to `2f7c700` moved 24 files; `url-constructor.any.js` is green again, since upstream now expects an undecodable A-label like `https://xn--/` to parse.
+- The gem ships `lib/`, `sig/`, the README, the changelog and the license, and nothing else. It used to take everything git tracks bar a few paths, which by now meant the maintainers' design notes, the WPT comparison scripts, the Capybara compliance spec and the CI workflow.
+
+### Fixed
+
+- On the released quickjs (0.21.0), a promise rejection a handler catches no longer fails a strict `Dommy::Browser`. That engine reports a rejection the moment it happens, before a `.catch` or `try { await … } catch` attached later in the same microtask checkpoint can handle it, so correct code came out as an unhandled rejection. When the engine behaves that way — probed once per process, since a fixed engine still says 0.21.0 — `on_unhandled_rejection` reports nothing and says so once with a warning; a rejection the page truly leaves unhandled then goes unreported, to the host and to the page alike — `unhandledrejection` and `window.onunhandledrejection` do not fire. A quickjs with [hmsk/quickjs.rb#141](https://github.com/hmsk/quickjs.rb/pull/141) reports them as before.
+- A classic script whose completion value is a pending Promise — `window.p = new Promise(...)` as its last statement, the idiom for publishing one a later script awaits — no longer reaches the page as an uncaught error. The gem refuses to convert such a value, and the resulting host exception was reported at the window; a testharness page that saw it reported no results at all. `#load_script` and `#load_script_cached` now discard the completion value, which `#execute` already did by wrapping in an IIFE.
+- `Runtime#rebuild_error` no longer copies a host exception's Ruby backtrace into the rebuilt Error's `stack`, which published this gem's file paths to any page that reads it. Engine frames are kept, everything else dropped, and a backtrace with no JS frames leaves the stack empty rather than naming a place the page did not fail.
+
 ## 0.9.0 — 2026-06-22
 
 The first substantial release since `0.1.0`. The version jumps to `0.9.0` to

data/README.md

@@ -110,6 +110,13 @@ The pieces it relies on are public Runtime API:
 - `Runtime#on_unhandled_rejection { |err| }` — surface promise rejections that
   reach the microtask queue with no handler. Frameworks swallow these; `err.backtrace`
   carries the JS stack, which is the difference between blind and one-shot debugging.
+  The released quickjs (0.21.0) reports a rejection before a handler attached in
+  the same microtask checkpoint can catch it, so `.catch` and `try { await … }
+  catch` would look unhandled; on such an engine nothing is reported here (a
+  warning says so once), so a strict `Dommy::Browser` does not fail on
+  rejections and the page's `unhandledrejection` event (and
+  `window.onunhandledrejection`) never fires. A quickjs with
+  [hmsk/quickjs.rb#141](https://github.com/hmsk/quickjs.rb/pull/141) reports them.
 - `Runtime#on_log { |log| }` — observe `console.*` (`log.severity` / `log.to_s`).
 
 ### Capybara

data/lib/dommy/js/quickjs/backend.rb

@@ -1,31 +1,38 @@
 # frozen_string_literal: true
 
 require "quickjs"
-require_relative "source_guard"
-
-# Performance: the quickjs gem wraps EVERY host-function call — every JS->Ruby
-# DOM crossing (__rb_host_get / _call / _set, …) — in `Timeout.timeout` to bound
-# a runaway Ruby callback. That costs ~4us per crossing (≈40% of a DOM property
-# read: 9.8us -> 5.1us with it removed), and a DOM-heavy SPA (React/Apollo) makes
-# MILLIONS of crossings while hydrating — tens of seconds of pure Timeout
-# overhead, the dominant cost behind a slow page.
-#
-# It is redundant here: QuickJS's own C interrupt handler still force-aborts a
-# runaway JS execution at the eval timeout (that mechanism is independent of this
-# Ruby wrapper), and Dommy's host functions are bounded DOM operations that never
-# hang. So skip the per-crossing Ruby Timeout. Set DOMMY_JS_CROSSING_TIMEOUT=1 to
-# keep the gem's original behavior (re-enabling the Ruby-callback-hang guard).
-if ::Quickjs.respond_to?(:_with_timeout) && ENV["DOMMY_JS_CROSSING_TIMEOUT"].to_s.empty?
-  module Quickjs
-    def self._with_timeout(_msec, proc, args)
-      proc.call(*args)
-    end
-  end
-end
 
 module Dommy
   module Js
     module Quickjs
+      # Skips the per-crossing Ruby `Timeout.timeout` the quickjs gem wraps EVERY
+      # host-function call in — every JS->Ruby DOM crossing (__rb_host_get /
+      # _call / _set, …). That costs ~4us per crossing (≈40% of a DOM property
+      # read: 9.8us -> 5.1us without it), and a DOM-heavy SPA (React/Apollo)
+      # makes MILLIONS of them while hydrating — tens of seconds of pure Timeout
+      # overhead, the dominant cost behind a slow page.
+      #
+      # It is redundant here: QuickJS's own C interrupt handler still
+      # force-aborts a runaway JS execution at the eval timeout (independent of
+      # this Ruby wrapper), and Dommy's host functions are bounded DOM
+      # operations that never hang. DOMMY_JS_CROSSING_TIMEOUT=1 keeps the gem's
+      # behavior, re-enabling the Ruby-callback-hang guard.
+      #
+      # Prepended to `::Quickjs`'s singleton rather than redefining the method:
+      # the gem's own implementation stays in the ancestor chain (reachable with
+      # `super`, visible in `::Quickjs.singleton_class.ancestors`), so the patch
+      # can be seen and undone. Redefining it outright left no way to tell the
+      # method had been replaced.
+      module SkipCrossingTimeout
+        def _with_timeout(_msec, proc, args)
+          proc.call(*args)
+        end
+      end
+
+      if ::Quickjs.respond_to?(:_with_timeout) && !Config.crossing_timeout?
+        ::Quickjs.singleton_class.prepend(SkipCrossingTimeout)
+      end
+
       # Binds HostBridge's abstract backend contract to the `quickjs` gem.
       #
       # Value-representation conformance: host_runtime.js now tags a top-level JS
@@ -38,31 +45,44 @@ module Dommy
       # the top-level tag); either way it maps to Dommy::Bridge::UNDEFINED. No
       # normalization is needed here.
       class Backend
-        # The gem's default eval timeout is 100ms, which interrupts large
-        # synchronous bridge loops (every property crossing is a Ruby call).
-        DEFAULT_TIMEOUT_MSEC = 60_000
-
-        # The per-eval timeout, in ms. A single JS eval — a script, or one
-        # timer/rAF callback — is force-aborted (Quickjs::InterruptedError, caught
-        # and logged) after this long. It is ALSO the ceiling on how long QuickJS
-        # holds the thread in C: while it runs, a Ctrl-C (delivered as a deferred
-        # SIGINT) can't be serviced, so an interactive host (dommynx) sets a lower
-        # value via DOMMY_JS_TIMEOUT_MSEC so a heavy/runaway burst can't freeze the
-        # UI for the full library default.
-        def self.default_timeout_msec
-          env = ENV["DOMMY_JS_TIMEOUT_MSEC"].to_i
-          env.positive? ? env : DEFAULT_TIMEOUT_MSEC
-        end
-
-        # The gem's default memory ceiling is 128 MB. A real-site SPA (note.com's
-        # Apollo/React bundle, hydration, the whole DOM mirrored as host proxies)
-        # blows past that and the VM hits out-of-memory, which poisons it. Give a
-        # browser-grade VM more headroom so heavy pages actually finish rendering;
-        # the OOM is also now survivable (see #poisoned?), not a crash.
-        DEFAULT_MEMORY_LIMIT = 512 * 1024 * 1024
-
+        # Whether this quickjs reports a promise rejection the moment it
+        # happens, before a handler attached later in the same microtask
+        # checkpoint gets the chance — the released quickjs (0.21.0) does, so
+        # `Promise.reject(x).catch(f)` and `try { await p } catch {}` both
+        # come out as unhandled. HTML reports at the end of the checkpoint
+        # (hmsk/quickjs.rb#141, merged upstream but unreleased).
+        #
+        # Decided by behavior, not by version — a git checkout of the fixed
+        # engine still says 0.21.0 — on a throwaway VM, once per process.
+        def self.premature_rejection_reports?
+          return @premature_rejection_reports if defined?(@premature_rejection_reports)
+
+          @premature_rejection_reports = probe_premature_rejection_reports
+        end
+
+        def self.probe_premature_rejection_reports
+          vm = ::Quickjs::VM.new
+          reported = false
+          vm.on_unhandled_rejection { |_error| reported = true }
+          vm.eval_code(<<~JS, async: false)
+            Promise.reject(1).catch(function () {});
+            (async function () { try { await Promise.reject(2); } catch (e) {} })();
+            0
+          JS
+          vm.drain_jobs!
+          reported
+        rescue ::StandardError
+          # A probe that cannot run says nothing either way; keep reporting.
+          false
+        ensure
+          vm&.dispose!
+        end
+        private_class_method :probe_premature_rejection_reports
+
+        # Timeout and memory ceiling both differ from the gem's defaults, for
+        # reasons Config documents.
         def initialize(**vm_opts)
-          vm_opts = {timeout_msec: self.class.default_timeout_msec, memory_limit: DEFAULT_MEMORY_LIMIT}.merge(vm_opts)
+          vm_opts = {timeout_msec: Config.timeout_msec, memory_limit: Config.memory_limit}.merge(vm_opts)
           @vm = ::Quickjs::VM.new(**vm_opts)
         end
 
@@ -76,20 +96,15 @@ module Dommy
             (@vm.respond_to?(:disposed?) && @vm.disposed?)
         end
 
-        def eval(js)
-          return if poisoned?
-
-          @vm.eval_code(js, async: false)
-        rescue ::Quickjs::RuntimeError => e
-          # A QuickJS codegen bug rejects `for-of` with a `yield` in the iterable
-          # ("stack underflow") — rewrite that construct and retry once.
-          raise unless SourceGuard.relevant_error?(e)
-
-          guarded = SourceGuard.fix_for_of_yield(js)
-          raise if guarded.equal?(js) || guarded == js
-
-          @vm.eval_code(guarded, async: false)
-        end
+        # Every entry point that RUNS something in the VM goes through #guarded,
+        # so a dead VM answers the same way whichever one a host reached for. It
+        # used to guard three of the six: an inline script quietly did nothing
+        # after an out-of-memory while an external (bytecode) one and #evaluate
+        # raised "VM is poisoned" from a different place each time.
+        #
+        # Registering a host function or a listener is not guarded: none of them
+        # runs JS, and they all happen while the VM is still alive.
+        def eval(js) = guarded { @vm.eval_code(js, async: false) }
 
         # Compile JS source to reusable bytecode (parsed once, via a throwaway
         # VM). Run it on any number of fresh VMs with #run_compiled — far cheaper
@@ -97,14 +112,6 @@ module Dommy
         # bundles are identical across VMs).
         def self.compile(source, filename: "<compiled>")
           ::Quickjs.compile(source, filename: filename)
-        rescue ::Quickjs::RuntimeError => e
-          # See #eval: work around the for-of/yield-in-iterable codegen bug.
-          raise unless SourceGuard.relevant_error?(e)
-
-          guarded = SourceGuard.fix_for_of_yield(source)
-          raise if guarded.equal?(source) || guarded == source
-
-          ::Quickjs.compile(guarded, filename: filename)
         end
 
         # Process-global cache for the engine-internal runtime bundles run via
@@ -120,9 +127,7 @@ module Dommy
 
         # Execute precompiled bytecode (a Quickjs::Runnable) on this VM in global
         # scope — equivalent to #eval of its source, without the parse cost.
-        def run_compiled(runnable)
-          runnable.run(on: @vm)
-        end
+        def run_compiled(runnable) = guarded { runnable.run(on: @vm) }
 
         # Run a source bundle that is identical across VMs (the bridge's host
         # runtime, the Observable polyfill): compile it to bytecode once per
@@ -135,9 +140,7 @@ module Dommy
 
         # Async eval: the gem awaits the top-level result and drains the
         # microtask queue, so JS `await`/Promises resolve before returning.
-        def eval_awaited(js)
-          @vm.eval_code(js, async: true)
-        end
+        def eval_awaited(js) = guarded { @vm.eval_code(js, async: true) }
 
         # Install the ESM module resolver: a callable `(specifier, importer) ->
         # source String | { code:, as: } | nil` the engine consults for every
@@ -146,34 +149,20 @@ module Dommy
           @vm.module_loader = callable
         end
 
-        # Evaluate `source` as an ES module (its `import`s resolved through the
-        # module loader). `* as` with no globalization runs it for side effects.
-        def import_module(source)
-          @vm.import("* as __dommy_mod", from: source, code_to_expose: "")
-        end
-
         # Evaluate the module at `url` (resolved + fetched by the module loader).
         # The importer of its relative imports is `url`, so they resolve
         # correctly — unlike an inline module's synthetic filename.
         def import_module_url(url)
-          @vm.import("* as __dommy_mod", filename: url, code_to_expose: "")
+          guarded { @vm.import("* as __dommy_mod", filename: url, code_to_expose: "") }
         end
 
         def define_host_function(name, &block)
           @vm.define_function(name, &block)
         end
 
-        def call_js(path, *args)
-          return if poisoned?
-
-          @vm.call(path, *args)
-        end
-
-        def drain_microtasks
-          return if poisoned?
+        def call_js(path, *args) = guarded { @vm.call(path, *args) }
 
-          @vm.drain_jobs!
-        end
+        def drain_microtasks = guarded { @vm.drain_jobs! }
 
         # Register a handler for promise rejections that reach the microtask
         # queue with no `.catch` — frameworks (Turbo, …) often swallow these,
@@ -182,19 +171,37 @@ module Dommy
           @vm.on_unhandled_rejection(&block)
         end
 
+        # Point the engine's promise-rejection hook at a JS function, named by an
+        # expression evaluated once in global scope. Only defined when the engine
+        # supports it, so callers can feature-detect with respond_to?.
+        if ::Quickjs::VM.method_defined?(:promise_rejection_hook=)
+          def promise_rejection_hook=(expression)
+            @vm.promise_rejection_hook = expression
+          end
+        end
+
         # Register a handler for console.(log|info|debug|warn|error). The block
         # receives a log object (#severity / #to_s / #raw).
         def on_log(&block)
           @vm.on_log(&block)
         end
 
-        def run_gc
-          @vm.gc!
-        end
+        def run_gc = guarded { @vm.gc! }
 
         def dispose
           @vm.dispose!
         end
+
+        private
+
+        # Run `block` unless the VM is dead, in which case the answer is nil —
+        # the "browsing never crashes" contract: the page's JS has stopped, and
+        # the host has already been told once (see EventLoop#note_halted).
+        def guarded
+          return if poisoned?
+
+          yield
+        end
       end
     end
   end

data/lib/dommy/js/quickjs/browser_environment.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # What this QuickJS build is missing before a page can run in it: the bare
+      # browser globals aliased onto the window, the timer globals routed into
+      # Dommy's scheduler, and stand-ins for the two things the build omits
+      # (Intl, WebAssembly).
+      #
+      # Separate from Runtime because it changes for its own reasons — a page
+      # reaching for a global nobody aliased yet — which has nothing to do with
+      # how the event loop is driven or how an engine exception becomes the
+      # page's error.
+      #
+      # Each payload is a .js file next door rather than a Ruby heredoc, the way
+      # the core bridge keeps host_runtime.js: it stays readable as JavaScript,
+      # and #run_bundle compiles it to bytecode ONCE per process instead of
+      # reparsing it for every VM.
+      class BrowserEnvironment
+        JS_DIR = ::File.join(__dir__, "js")
+        private_constant :JS_DIR
+
+        # Read at load time and frozen: the files never change at runtime, and a
+        # per-VM read would undo the point of caching the compile.
+        def self.payload(name)
+          ::File.read(::File.join(JS_DIR, name)).freeze
+        end
+        private_class_method :payload
+
+        TIMER_GLOBALS_JS = payload("timer_globals.js")
+        BROWSER_GLOBALS_JS = payload("browser_globals.js")
+        WINDOW_BUILTINS_JS = payload("window_builtins.js")
+        INTL_POLYFILL_JS = payload("intl_polyfill.js")
+        WASM_STUB_JS = payload("wasm_stub.js")
+        ERROR_REBUILD_JS = payload("error_rebuild.js")
+
+        # Nothing outside installs a payload by hand; the methods below are the
+        # way in.
+        private_constant :TIMER_GLOBALS_JS, :BROWSER_GLOBALS_JS, :WINDOW_BUILTINS_JS,
+          :INTL_POLYFILL_JS, :WASM_STUB_JS, :ERROR_REBUILD_JS
+
+        def initialize(backend)
+          @backend = backend
+        end
+
+        # The helper ErrorTranslator calls to rebuild a thrown Error inside the
+        # realm. Installed with the runtime rather than with the page globals:
+        # an engine exception can reach a host that never asked for a browser.
+        def install_error_rebuilder
+          run("error_rebuild.js", ERROR_REBUILD_JS)
+        end
+
+        # setTimeout / setInterval / requestAnimationFrame / queueMicrotask, as
+        # bare globals routed through the window (so they reach Dommy's
+        # deterministic scheduler), plus the scheduling-site capture a throwing
+        # callback is traced back through. Needs the window installed first.
+        def install_timers
+          run("timer_globals.js", TIMER_GLOBALS_JS)
+        end
+
+        # Everything a real frontend bundle expects to find on its own: the
+        # aliased window globals, then the two polyfills, then the built-ins
+        # mirrored onto the window. Order matters only in that the window must
+        # already be installed.
+        def install_globals
+          run("browser_globals.js", BROWSER_GLOBALS_JS)
+          run("intl_polyfill.js", INTL_POLYFILL_JS)
+          install_wasm_stub
+          run("window_builtins.js", WINDOW_BUILTINS_JS)
+          self
+        end
+
+        # The WebAssembly stand-in on its own. Idempotent: the payload defines
+        # nothing when `WebAssembly` already exists, so a host that asks for it
+        # explicitly (the WPT harness wants the SharedArrayBuffer that
+        # `Memory({shared:true})` yields) gets the same object install_globals
+        # would have built.
+        def install_wasm_stub
+          run("wasm_stub.js", WASM_STUB_JS)
+          self
+        end
+
+        private
+
+        def run(cache_key, source)
+          @backend.run_bundle(cache_key, source)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/quickjs/capybara.rb

@@ -7,6 +7,9 @@ require_relative "../quickjs"
 module Dommy
   module Js
     module Quickjs
+      # evaluate_async_script's callback was not called within the wait budget.
+      class ScriptTimeoutError < Error; end
+
       # Opt-in Capybara integration. Requiring this file enables JS execution on
       # Capybara::Dommy::Driver (via install_capybara! below), so execute_script /
       # evaluate_script run against the current Dommy document through a QuickJS
@@ -17,29 +20,92 @@ module Dommy
       # session and the Capybara polling loop, and wraps results as Capybara
       # nodes.
       module CapybaraDriver
+        # The in-realm slot an async script's callback reports to. Each call
+        # installs a fresh state object, so a late callback from an earlier call
+        # writes into its own, now-orphaned one.
+        ASYNC_SCRIPT_STATE = "__rbAsyncScriptState"
+
         def rack_session
           session = super
           dommy_js_attach(session)
           session
         end
 
-        def execute_script(script, *_args)
-          dommy_js_host.execute(script)
+        def execute_script(script, *args)
+          host = dommy_js_host
+          if args.empty?
+            host.execute(script)
+          else
+            host.execute_with_args(script, capybara_script_args(args))
+          end
           nil
         end
 
-        def evaluate_script(script, *_args)
-          decode_for_capybara(dommy_js_host.evaluate(script))
+        def evaluate_script(script, *args)
+          host = dommy_js_host
+          value = args.empty? ? host.evaluate(script) : host.evaluate_with_args(script, capybara_script_args(args))
+          decode_for_capybara(value)
         end
 
-        # No real async loop; evaluate synchronously. Sufficient for scripts
-        # that resolve immediately (the common Capybara case).
+        # WebDriver's executeAsyncScript: the script gets a callback as its last
+        # argument, and its result is whatever that callback is called with.
+        # Virtual time is pumped until it is, for at most
+        # Capybara.default_max_wait_time of VIRTUAL time — so a timer the script
+        # waits on fires, while the budget stays deterministic.
         def evaluate_async_script(script, *args)
-          evaluate_script(script, *args)
+          host = dommy_js_host
+          host.execute_with_args(<<~JS, capybara_script_args(args))
+            var state = { settled: false, value: undefined };
+            globalThis.#{ASYNC_SCRIPT_STATE} = state;
+            var args = Array.prototype.slice.call(arguments);
+            args.push(function (value) {
+              if (state.settled) return;
+              state.settled = true;
+              state.value = value;
+            });
+            (function () {
+            #{script}
+            }).apply(this, args);
+          JS
+          await_async_script(host)
+          decode_for_capybara(host.evaluate("globalThis.#{ASYNC_SCRIPT_STATE}.value"))
         end
 
         private
 
+        def await_async_script(host)
+          budget_ms = ::Capybara.default_max_wait_time * 1000
+          pumps = (budget_ms / ::Dommy::Rack::SessionRuntime::PUMP_SLICE_MS).ceil
+          settled = "(globalThis.#{ASYNC_SCRIPT_STATE} || {}).settled === true"
+          pumps.times do
+            return if host.evaluate(settled)
+
+            host.pump
+          end
+          return if host.evaluate(settled)
+
+          raise ScriptTimeoutError,
+                "evaluate_async_script did not call its callback within #{budget_ms.round}ms of virtual time"
+        end
+
+        # A Capybara node argument becomes the Dommy element it wraps (so it
+        # crosses to JS as a proxy), at any depth inside arrays and hashes.
+        # Capybara::Session unwraps only top-level elements, so a nested
+        # Capybara::Node::Element is unwrapped here too.
+        def capybara_script_args(args)
+          args.map { |arg| capybara_script_arg(arg) }
+        end
+
+        def capybara_script_arg(arg)
+          case arg
+          when ::Capybara::Node::Element then capybara_script_arg(arg.base)
+          when ::Capybara::Dommy::Node then arg.native
+          when Array then capybara_script_args(arg)
+          when Hash then arg.transform_values { |value| capybara_script_arg(value) }
+          else arg
+          end
+        end
+
         # Bind a SessionRuntime to the session (rebuilt when reset!/app_host
         # swaps the session). The driver's frame-aware `document` is the realm
         # target, and Capybara's retry loop pumps virtual time via time_pump.
@@ -51,8 +117,12 @@ module Dommy
           self.time_pump = -> { @dommy_js_host.pump }
         end
 
+        # The JS host bound to the CURRENT session. Reading `rack_session` is what
+        # (re)binds one, because the attach lives in that override — so this is a
+        # fetch with a deliberate side effect, not a plain reader. Capybara swaps
+        # the session on reset! / app_host, and the host has to follow.
         def dommy_js_host
-          rack_session # ensures the host is attached for the current session
+          rack_session
           @dommy_js_host
         end
 
@@ -60,23 +130,35 @@ module Dommy
         #   - Array            -> recurse (so element collections wrap per item)
         #   - JS undefined      -> nil
         #   - Dommy::Element    -> Capybara::Dommy::Node (covers HTML/SVG subclasses)
-        #   - other bridge obj  -> nil (Document/Text/Comment/Fragment/NodeList/
-        #                          Window have no Capybara representation)
+        #   - other host object -> nil (Document/Text/Comment/Fragment/NodeList/
+        #                          Window/Blob/FormData have no Capybara
+        #                          representation)
         #   - primitive/Hash    -> as-is
         def decode_for_capybara(value)
-          return nil if value.equal?(::Dommy::Bridge::UNDEFINED)
+          return nil if js_undefined?(value)
 
           case value
-          when Array
-            value.map { |element| decode_for_capybara(element) }
-          when ::Quickjs::Value::UNDEFINED
-            nil
-          when ::Dommy::Element
-            ::Capybara::Dommy::Node.new(self, value)
-          else
-            value.respond_to?(:__js_get__) ? nil : value
+          when Array then value.map { |element| decode_for_capybara(element) }
+          when ::Dommy::Element then ::Capybara::Dommy::Node.new(self, value)
+          else host_object?(value) ? nil : value
           end
         end
+
+        # JS `undefined` arrives as either the engine-neutral sentinel the bridge
+        # decodes to, or — on the paths that skip that decode — the gem's own.
+        def js_undefined?(value)
+          value.equal?(::Dommy::Bridge::UNDEFINED) || value.equal?(::Quickjs::Value::UNDEFINED)
+        end
+
+        # Whether `value` is a Dommy object the page can read properties off
+        # (`__js_get__` is what the bridge calls to do that). Everything that
+        # answers to it is a DOM-side object, and the ones Capybara can represent
+        # were already taken by the branches above — so what is left has no
+        # representation and becomes nil rather than leaking a host object into a
+        # Capybara assertion.
+        def host_object?(value)
+          value.respond_to?(:__js_get__)
+        end
       end
 
       # Idempotently prepend JS-execution support onto Capybara::Dommy::Driver.