dommy-js-quickjs 0.1.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17fc429b996f9fb344e581d754fa51c5a0e27d559caca8709fdd1dd6bcbd8516
-  data.tar.gz: de228d74c5b14116c3eae917154823c00f0cd3c5f3c81a89d4b33d1c89c6b44b
+  metadata.gz: 56e600a474810ea778587cf249cbb7c200d9947c28270449837550971e5674de
+  data.tar.gz: ff9e6cf37ed37fb89f148163e38ee6fdd63e8bd5fc1e81669f8538eebc84d3ea
 SHA512:
-  metadata.gz: a4340bfcd9e6c084ee9441bafc176752bb97601814d460fd39cac699553faf52c972d08f844011a957c90b0df7b4c83b609df618f10d9545a58e4d22bb314f0e
-  data.tar.gz: 628bb3957b81036927500ee813d6b0410bc936ac378e35efc27990f8cc59c6d5ed4eb9b18bd9e1baed781bb813a7d09d864c1bf74e40d50b03cac588e0d5ec3a
+  metadata.gz: ffa632c98fe6c8bedba9bc8e189cda13a1c9baef1c4bd0224fa1f7f9ffd31bdcaad8bcb84ffdbdf2b2436ec3a29bb68d0d8ceaa7879602f5cc45d8edbc1633ba
+  data.tar.gz: 22272e499d364204ecba6edb91cb6c01953d72d46990652b3f14907e2141686e8bbc8d94de3d5125e2f96b21e9e1a34b8d5c887c41af3dbe8cd693e33a2370bd

data/CHANGELOG.md

@@ -1,6 +1,121 @@
 # 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
+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
 
@@ -104,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
@@ -123,9 +136,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 +150,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/lib/dommy/js/quickjs/backend.rb

@@ -5,38 +5,164 @@ require "quickjs"
 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
+      # `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
+        # 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: DEFAULT_TIMEOUT_MSEC}.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
 
-        def eval(js)
-          @vm.eval_code(js, async: false)
+        # 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
+
+        # 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
+        # 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)
+        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) = 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
+        # 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
         # microtask queue, so JS `await`/Promises resolve before returning.
-        def eval_awaited(js)
-          @vm.eval_code(js, async: true)
+        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
+        # static/dynamic `import`. nil clears it (engine default loader).
+        def module_loader=(callable)
+          @vm.module_loader = callable
+        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)
+          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)
-          @vm.call(path, *args)
-        end
+        def call_js(path, *args) = guarded { @vm.call(path, *args) }
 
-        def drain_microtasks
-          @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,
@@ -45,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