dommy-js-quickjs 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17fc429b996f9fb344e581d754fa51c5a0e27d559caca8709fdd1dd6bcbd8516
-  data.tar.gz: de228d74c5b14116c3eae917154823c00f0cd3c5f3c81a89d4b33d1c89c6b44b
+  metadata.gz: 582867f4a71527529224d5ecf3348461ff69e4b76518f5c8f0f9dc85c5704270
+  data.tar.gz: b183f4631ea255d7844b8b2f20cc68214863d3639eaa559e3cdc3f44e1ec04a0
 SHA512:
-  metadata.gz: a4340bfcd9e6c084ee9441bafc176752bb97601814d460fd39cac699553faf52c972d08f844011a957c90b0df7b4c83b609df618f10d9545a58e4d22bb314f0e
-  data.tar.gz: 628bb3957b81036927500ee813d6b0410bc936ac378e35efc27990f8cc59c6d5ed4eb9b18bd9e1baed781bb813a7d09d864c1bf74e40d50b03cac588e0d5ec3a
+  metadata.gz: 0b185321865a0e45d9b880bbc8e25ef7936c8fb570e0b9a1a60ea21bd70af68efc8dfa5dd1f82a4d8214a237f8174eb1d6a5997a67db82a5bd6d92e8e2df7a70
+  data.tar.gz: 3fe107306181b587a96a1dac23bcd73f08f2f9484c9f61a105449508d6a9438cf2dfa76f8bdd8c997f5b511784c45e09e0dca7ab3546b28985b86118a7e26f4c

data/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake

data/CHANGELOG.md

@@ -1,6 +1,89 @@
 # Changelog
 
+## 0.9.0 — 2026-06-22
+
+The first substantial release since `0.1.0`. The version jumps to `0.9.0` to
+line up with the rest of the Dommy monorepo (`dommy`, `dommy-rack`,
+`capybara-dommy`). The headline change is architectural: the engine-agnostic
+host layer and bridge now live in `dommy` core, leaving this gem as the QuickJS
+backend that plugs into it. On top of that foundation sits real ESM and
+JavaScript-framework support, an event-loop-aware runtime, and a large WHATWG /
+WPT conformance pass.
+
+Requires `dommy >= 0.9.0` and `quickjs ~> 0.18.0`.
+
+### Added
+
+#### Browser & page lifecycle
+- `Dommy::Browser`, a lightweight test browser that boots a page, runs its
+  scripts through a shared `ScriptBoot`, and exposes interaction verbs with a
+  conservative `settle` step
+- `Browser.open` settles after boot by default (opt out / tune with the
+  `settle:` option)
+- QuickJS is wired into Dommy page loads
+- `SessionRuntime`, a JS host for the dommy-rack `Session`
+
+#### ES Modules
+- Full ESM support: `importmap`, the module loader, and `type=module` boot
+- Inline modules' `import.meta.url` is pinned to the clean page URL
+- External `<script src>` inserted into the DOM defers correctly rather than
+  running synchronously during append
+
+#### JavaScript frameworks
+- Host and conformance coverage for **Stimulus** (with a ported QUnit suite),
+  **React 18** (JSX, SSR, hydration), and **Vue 3** (global-scope script loading
+  with tolerant handles)
+- Integration suites for **Alpine**, **htmx**, **Solid**, and **Lit**
+
+#### Event loop, timers & promises
+- `evaluate` / `await` are event-loop-aware and settle task-resolved results
+- The scheduler's microtask-checkpoint hook is wired up so host-side microtasks
+  interleave with JS promises in FIFO order
+- A throwing JS timer callback is isolated so it can no longer crash the host; a
+  runaway (force-killed) callback is recorded rather than fatal, and a throwing
+  callback is traced back to its scheduling site
+- Ported the official **Promises/A+** suite against the host `PromiseValue`
+
+#### Engine surface
+- Polyfilled `Intl` and stubbed `WebAssembly` (the engine ships neither)
+- More bare browser globals (`Image`, `Audio`, `Option`, `console`, `Object`, …)
+  are aliased onto the global scope as the native globals
+- The per-eval timeout is configurable via `DOMMY_JS_TIMEOUT_MSEC`
+- Bridge crossing counts are exposed; opaque unhandled rejections are enriched
+
+#### WPT / WHATWG conformance
+- A resource-driven WPT runner plus a large vendored corpus: DOM nodes /
+  traversal / ranges / collections, URL & URLSearchParams, Encoding, Selectors,
+  CSS (syntax, variables, color, CSSOM), WAI-ARIA roles, and accessible-name
+  (accname). The heavy thousands-of-subtests files are gated behind `WPT_HEAVY`.
+
+### Changed
+
+- **Pluggable runtime (breaking):** the engine-agnostic bridge and host layer
+  (`Browser` + the Js port) moved into `dommy` core; the JS runtime is now
+  pluggable and `Browser` is decoupled from QuickJS. This gem registers QuickJS
+  as a backend. Bridge wire-protocol tags are centralized and `JSValue` unified.
+- **Bridge contract (breaking):** defensive `Dommy::Bridge` guards were dropped
+  in favor of requiring the backend contract; `dommy >= 0.9.0` is now required.
+- Proxy identity and expando lifetime are preserved across crossings so reactive
+  frameworks observe stable object identity; a `NodeList` crosses as a `NodeList`
+  (not a plain array); `DOMException` subclasses cross as the single
+  `DOMException` interface (`constructor === DOMException`).
+- Callback exceptions propagate across the bridge; `NodeFilter` objects cross as
+  live references.
+
+### Fixed
+
+- Survive a VM out-of-memory instead of crashing the browser
+- Work around a QuickJS `for-of`-with-`yield`-in-iterable codegen bug
+- Report a present-but-undefined IDL attribute via the `in` operator
+- Scrub lone surrogates in dehydrated object keys
+
+### Performance
+
+- Skip the per-crossing Ruby `Timeout` (≈40% faster DOM crossings)
+- Bytecode-cache the host runtime and external scripts
+
 ## 0.1.0
 
 initial release.
-

data/README.md

@@ -7,15 +7,21 @@ JavaScript executes in an embedded QuickJS VM (via the
 [`quickjs`](https://github.com/hmsk/quickjs.rb) gem). Dommy DOM nodes are bridged
 to JS as objects whose property/method access routes into Dommy's
 `__js_get__` / `__js_set__` / `__js_call__` / `__js_new__` ABI, so JS drives a
-real Dommy document. The QuickJS-specific code is isolated in a small `Backend`;
-the rest of the bridge is engine-agnostic.
+real Dommy document. This gem provides the QuickJS `Backend`; the
+engine-agnostic bridge it plugs into (the `HostBridge` marshalling core and the
+JS-side runtime) lives in the [`dommy`](https://github.com/takahashim/dommy) gem,
+so other engines can reuse it.
 
 The bridge presents a **spec-shaped JS DOM**, not bare proxies: `instanceof`,
 prototype chains, `Object.prototype.toString` brands, constructable interfaces
 (`new Event(...)`), custom elements (`class extends HTMLElement`), live
 collections, and expandos all work — enough that the real
-[`@hotwired/turbo`](https://github.com/hotwired/turbo) bundle loads and drives
-the DOM (turbo-stream + turbo-frame; see `test/dommy/js/test_turbo_integration.rb`).
+[`@hotwired/turbo`](https://github.com/hotwired/turbo) and
+[`@hotwired/stimulus`](https://github.com/hotwired/stimulus) bundles load and
+drive the DOM (turbo-stream + turbo-frame; Stimulus controllers, targets,
+values, classes, actions, and outlets — see
+`test/dommy/js/test_turbo_integration.rb` and
+`test/dommy/js/test_stimulus_integration.rb`).
 
 ## Installation
 
@@ -123,9 +129,9 @@ require "dommy/js/quickjs/capybara"
   Selenium-style `done()` / real-time waits are not supported.
 - **`fetch` is stub-based** via Dommy's `__fetchy_stub__` (a `{ url => entry }` map);
   there is no real network.
-- **Event listeners must be functions** — `addEventListener("...", fn)` works
-  (closures intact; `removeEventListener` with the same function detaches it), but
-  the `{ handleEvent }` object form is not.
+- **Event listeners** — both forms work: a function (`addEventListener("...", fn)`,
+  closures intact) and the EventListener *object* form (`{ handleEvent }`, used by
+  Stimulus). `removeEventListener` detaches by the same function/object identity.
 - **Expandos are scoped to elements**, and the JS callback table is not evicted, so
   a very long-lived VM can grow unbounded.
 - **DOM coverage is Dommy's.** A JS method/property works only where Dommy exposes
@@ -137,14 +143,30 @@ require "dommy/js/quickjs/capybara"
 Run `bin/setup` to install dependencies, then `rake test`. `bin/console` opens an
 interactive prompt.
 
-The real-framework integration test (`test_turbo_integration.rb`) is skipped
-unless the Turbo bundle is vendored at `test/fixtures/turbo.umd.js`:
+The real-framework integration tests are skipped unless their bundle is
+vendored under `test/fixtures/`:
 
 ```bash
 curl -sL https://unpkg.com/@hotwired/turbo@8/dist/turbo.es2017-umd.js \
   -o test/fixtures/turbo.umd.js
+curl -sL https://unpkg.com/@hotwired/stimulus@3/dist/stimulus.umd.js \
+  -o test/fixtures/stimulus.umd.js
 ```
 
+### Conformance suites
+
+Two tasks run real third-party test corpora against the bridge and report a
+pass rate — the lens that pins how faithfully the bridge hosts the platform:
+
+```bash
+rake wpt:conformance[filter]        # Web Platform Tests (vendored under test/fixtures/wpt)
+rake stimulus:conformance[filter]   # @hotwired/stimulus's own QUnit suite
+```
+
+The Stimulus suite is vendored as a single bundle (`test/fixtures/
+stimulus-tests.umd.js`) run through a small QUnit shim; each test runs in its
+own fresh VM. Regenerate the bundle with `script/build_stimulus_tests.sh`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome at https://github.com/takahashim/dommy-js-quickjs.

data/Rakefile

@@ -3,9 +3,30 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+# The OOM-resilience test forces a real QuickJS out-of-memory. Whether an OOM
+# poisons the VM (vs. unwinding as a recoverable JS exception) depends on the
+# allocator's state, which other JS-heavy tests in the same process perturb — so
+# it runs in its own process to stay deterministic.
+OOM_TEST = "test/dommy/js/test_oom_resilience.rb"
 
-task default: :test
+Minitest::TestTask.create(:test) do |t|
+  t.test_globs = FileList["test/**/test_*.rb"].exclude(OOM_TEST)
+end
+
+Minitest::TestTask.create(:test_oom) do |t|
+  t.test_globs = [OOM_TEST]
+end
+
+namespace :test do
+  desc "Run the full test suite including the heavy (thousands-of-subtests) WPT files"
+  task :all do
+    ENV["WPT_HEAVY"] = "1"
+    Rake::Task["test"].invoke
+    Rake::Task["test_oom"].invoke
+  end
+end
+
+task default: %i[test test_oom]
 
 namespace :wpt do
   desc "Run the vendored WPT corpus against the bridge and report a conformance rate"
@@ -47,3 +68,50 @@ namespace :wpt do
          "#{file_ok} files fully green#{blocked.empty? ? "" : ", #{blocked.size} errored"}"
   end
 end
+
+namespace :stimulus do
+  desc "Run @hotwired/stimulus's QUnit suite against the bridge and report a conformance rate"
+  task :conformance, [:filter] do |_t, args|
+    $LOAD_PATH.unshift File.expand_path("test", __dir__)
+    require "test_helper"
+    require "support/stimulus_conformance"
+
+    runner = Dommy::Js::StimulusConformance
+    unless runner.available?
+      abort "Stimulus suite not vendored. Build it: script/build_stimulus_tests.sh"
+    end
+
+    manifest = runner.manifest
+    manifest = manifest.select { |t| t["module"].match?(/#{args[:filter]}/i) } if args[:filter]
+
+    # Run each test in its own VM, grouping the printed output by module.
+    by_module = Hash.new { |h, k| h[k] = [] }
+    failures = []
+    manifest.each do |t|
+      r = runner.run_test(t["module"], t["name"])
+      by_module[t["module"]] << r
+    rescue => e
+      puts "  ✗ #{t["module"]} :: #{t["name"]}  (errored: #{e.class}: #{e.message[0, 70]})"
+    end
+
+    total_pass = total_runnable = total = 0
+    by_module.each do |mod, results|
+      pass = results.count(&:pass?)
+      runnable = results.count(&:runnable?)
+      total_pass += pass
+      total_runnable += runnable
+      total += results.size
+      flag = runnable.positive? && pass == runnable ? "✓" : " "
+      printf("  %s %-42s %3d/%-3d\n", flag, mod, pass, runnable)
+      results.reject { |r| r.pass? || r.skip? || r.todo? }.each do |r|
+        failures << r
+        puts "        #{r.to_s[0, 120]}"
+      end
+    end
+
+    pct = total_runnable.zero? ? 0 : (100.0 * total_pass / total_runnable).round(1)
+    puts
+    puts "Stimulus conformance: #{total_pass}/#{total_runnable} runnable tests (#{pct}%) " \
+         "across #{by_module.size} modules; #{total - total_runnable} skipped/todo, #{failures.size} failing"
+  end
+end

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

@@ -1,23 +1,136 @@
 # 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
       # Binds HostBridge's abstract backend contract to the `quickjs` gem.
+      #
+      # Value-representation conformance: host_runtime.js now tags a top-level JS
+      # `undefined` itself (`dehydrateTop` -> `{__rb_undefined:true}`) at the
+      # JS->Ruby crossings, so the protocol no longer relies on the backend to
+      # marshal a bare `undefined` to a sentinel — keeping it engine-neutral.
+      # The `quickjs` gem happens to also deliver a bare `undefined` as the Ruby
+      # symbol `:undefined`, which HostBridge#unwrap still accepts as a defensive
+      # fallback (e.g. the `evaluate`/`tag` return path, which dehydrates without
+      # 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
+
         def initialize(**vm_opts)
-          vm_opts = {timeout_msec: DEFAULT_TIMEOUT_MSEC}.merge(vm_opts)
+          vm_opts = {timeout_msec: self.class.default_timeout_msec, memory_limit: DEFAULT_MEMORY_LIMIT}.merge(vm_opts)
           @vm = ::Quickjs::VM.new(**vm_opts)
         end
 
+        # True once the VM can no longer run JS safely: it hit out-of-memory (the
+        # gem flags it "poisoned" — further eval may segfault) or was disposed.
+        # Callers stop driving a poisoned VM (the page's JS is dead) instead of
+        # letting the error crash the whole browser — browsing survives a page
+        # whose JS ran out of memory, showing whatever rendered before it died.
+        def poisoned?
+          (@vm.respond_to?(:memory_poisoned?) && @vm.memory_poisoned?) ||
+            (@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
+
+        # 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
+        # than re-parsing the source per VM (the large host runtime / vendored
+        # 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
+        # #run_bundle (host_runtime.js, observable_runtime.js). Kept separate
+        # from ScriptCache (user-facing external scripts) so the two concerns
+        # don't share a count/namespace.
+        @bundle_cache = {}
+        @bundle_mutex = Mutex.new
+
+        def self.compiled_bundle(cache_key, source)
+          @bundle_mutex.synchronize { @bundle_cache[cache_key] ||= compile(source, filename: cache_key.to_s) }
+        end
+
+        # 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
+
+        # Run a source bundle that is identical across VMs (the bridge's host
+        # runtime, the Observable polyfill): compile it to bytecode once per
+        # process — keyed by `cache_key` — and run that on this VM. Lets the
+        # engine-agnostic bridge reuse big bundles without knowing about
+        # bytecode; the compile-once optimization stays here in the engine layer.
+        def run_bundle(cache_key, source)
+          run_compiled(self.class.compiled_bundle(cache_key, source))
         end
 
         # Async eval: the gem awaits the top-level result and drains the
@@ -26,15 +139,39 @@ module Dommy
           @vm.eval_code(js, async: true)
         end
 
+        # Install the ESM module resolver: a callable `(specifier, importer) ->
+        # source String | { code:, as: } | nil` the engine consults for every
+        # static/dynamic `import`. nil clears it (engine default loader).
+        def module_loader=(callable)
+          @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: "")
+        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?
+
           @vm.drain_jobs!
         end
 

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "capybara/dommy"
+require "dommy/rack"
 require_relative "../quickjs"
 
 module Dommy
@@ -10,14 +11,25 @@ module Dommy
       # Capybara::Dommy::Driver (via install_capybara! below), so execute_script /
       # evaluate_script run against the current Dommy document through a QuickJS
       # Runtime. Without this require, capybara-dommy stays JS-free (its default).
+      #
+      # The realm-per-document machinery lives in SessionRuntime (shared with
+      # Dommy::Rack::Session's `javascript: true`); the driver wires it to the
+      # session and the Capybara polling loop, and wraps results as Capybara
+      # nodes.
       module CapybaraDriver
+        def rack_session
+          session = super
+          dommy_js_attach(session)
+          session
+        end
+
         def execute_script(script, *_args)
-          dommy_js_runtime.execute(script)
+          dommy_js_host.execute(script)
           nil
         end
 
         def evaluate_script(script, *_args)
-          decode_for_capybara(dommy_js_runtime.evaluate(script))
+          decode_for_capybara(dommy_js_host.evaluate(script))
         end
 
         # No real async loop; evaluate synchronously. Sufficient for scripts
@@ -28,19 +40,20 @@ module Dommy
 
         private
 
-        # One Runtime per document. Rebuilt when navigation swaps the document
-        # so JS always sees the current page (and the old VM is released).
-        def dommy_js_runtime
-          doc = document
-          unless defined?(@dommy_js_doc) && @dommy_js_doc.equal?(doc)
-            @dommy_js_runtime&.dispose
-            @dommy_js_runtime = Runtime.new
-            @dommy_js_runtime.define_host_object("document", doc)
-            view = doc.default_view
-            @dommy_js_runtime.install_window(view) if view
-            @dommy_js_doc = doc
-          end
-          @dommy_js_runtime
+        # 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.
+        def dommy_js_attach(session)
+          return if defined?(@dommy_js_session) && @dommy_js_session.equal?(session)
+
+          @dommy_js_session = session
+          @dommy_js_host = ::Dommy::Rack::SessionRuntime.new(session) { document }
+          self.time_pump = -> { @dommy_js_host.pump }
+        end
+
+        def dommy_js_host
+          rack_session # ensures the host is attached for the current session
+          @dommy_js_host
         end
 
         # Map an evaluate() result to what Capybara expects:
@@ -48,10 +61,11 @@ module Dommy
         #   - 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; a browser
-        #                          likewise returns non-serializable values as null)
+        #                          Window have no Capybara representation)
         #   - primitive/Hash    -> as-is
         def decode_for_capybara(value)
+          return nil if value.equal?(::Dommy::Bridge::UNDEFINED)
+
           case value
           when Array
             value.map { |element| decode_for_capybara(element) }

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Wires QuickJS as the JS runtime for `Dommy::Rack::Session.new(app,
+# javascript: true)`. Requiring this file (directly, or lazily by the session
+# when javascript is requested) registers the :quickjs backend and points the
+# session's runtime factory at the realm manager.
+#
+# The realm manager (Dommy::Rack::SessionRuntime) lives in dommy-rack and is
+# backend-agnostic; this gem only supplies the QuickJS engine.
+require "dommy/rack"
+require_relative "../quickjs"
+
+Dommy::Rack::Session.javascript_runtime_factory = lambda do |session|
+  Dommy::Rack::SessionRuntime.new(session)
+end