dommy-js-quickjs 0.9.0 → 0.10.0

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

@@ -9,18 +9,29 @@ module Dommy
       #   rt.define_host_object("document", win.document)
       #   rt.evaluate('document.querySelector("h1").textContent')  #=> "..."
       #
-      # Wires the QuickJS Backend to the engine-agnostic HostBridge, seeded with
-      # the Dommy method manifest.
+      # Implements the Dommy::Js::Runtime port (see that module for the contract)
+      # by wiring four collaborators together and delegating to them:
+      #
+      #   Backend             the `quickjs` gem — eval, compile, the VM's state
+      #   HostBridge          the engine-agnostic JS<->Ruby DOM bridge (core)
+      #   BrowserEnvironment  the globals and polyfills a page expects to find
+      #   EventLoop           microtasks + Dommy's scheduler, as one loop
+      #   ErrorTranslator     an engine exception, as what the page should see
+      #
+      # What stays here is the port itself: script evaluation, and the wiring
+      # that decides which collaborator answers a host's call.
       class Runtime
         def initialize(**vm_opts)
           @backend = Backend.new(**vm_opts)
           @bridge = Dommy::Js::HostBridge.new(@backend)
+          @environment = BrowserEnvironment.new(@backend)
+          @errors = ErrorTranslator.new(@backend, @bridge)
+          @environment.install_error_rebuilder
+          @loop = EventLoop.new(@backend, scheduler: -> { @window&.scheduler }) do |error|
+            @callback_error_listener&.call(error)
+          end
           @callback_error_listener = nil
-          @js_halted = false
-          # Opt-in diagnostics: the engine stringifies a non-Error rejection reason
-          # to "[object Object]". Install a JS-side recorder so on_unhandled_rejection
-          # can surface the real cause (DOMMY_JS_DEBUG_REJECTIONS=1).
-          @track_rejections = !ENV["DOMMY_JS_DEBUG_REJECTIONS"].to_s.empty?
+          @track_rejections = Config.track_rejections?
           # Install the JS-side Promise rejection recorder (HostBridge registers
           # the __rb_record_rejection_detail sink it pushes to). The detail then
           # backfills the engine's detail-less report in #enrich_rejection.
@@ -31,74 +42,18 @@ module Dommy
           @bridge.define_host_object(name, obj)
         end
 
-        # Inject the Dommy window and alias the bare browser timer globals to it,
-        # so `setTimeout(fn, ms)` routes into Dommy's deterministic scheduler.
-        # Drive callbacks with `win.scheduler.advance_time(ms)`. `window.setTimeout`
-        # already works via the Window manifest; this also wires the unqualified
-        # globals browsers expose.
+        # Inject the Dommy window: seed it as the JS global, give the bridge the
+        # realm it belongs to, route rejections and runaway callbacks back here,
+        # and alias the bare timer globals onto it (so `setTimeout(fn, ms)` runs
+        # through Dommy's deterministic scheduler — drive it with
+        # `win.scheduler.advance_time(ms)`).
         def install_window(win)
           @window = win
           define_host_object("window", win)
           @bridge.window = win
-          # A runaway timer/rAF callback (busy loop) is force-killed by the gem's
-          # eval timeout, surfacing as a Quickjs::InterruptedError out of the host
-          # call. Route it through the scheduler's error hook so it is recorded as
-          # a js_error and dropped, not propagated as a fatal crash (browsing must
-          # never crash). Genuine host bugs (any other error) still propagate.
-          if win.respond_to?(:scheduler) && win.scheduler
-            win.scheduler.timer_error_handler = method(:handle_timer_error)
-            # The other half of a WHATWG microtask checkpoint: the engine's
-            # promise-job queue. Wiring this lets the scheduler drain microtasks
-            # after EACH task (not once per batch of due timers), as the event
-            # loop processing model requires.
-            win.scheduler.microtask_checkpoint = method(:drain_microtasks)
-          end
-          @backend.eval(<<~JS)
-            // Remember where each timer was scheduled, so a throwing callback can
-            // be traced back to the code that set it up. This matters most for
-            // minified SPA bundles, where the thrown value is often a bare `null`
-            // with no stack of its own — the only locatable stack is the
-            // scheduling site. The origin Error is kept JS-side and only
-            // stringified if the callback actually throws (see
-            // __rbFetchTimerOrigin + handle_timer_error); a successful callback
-            // forgets its origin and the map is size-capped, so this stays cheap.
-            globalThis.__rbTimerOrigins = new Map();
-            const __rbDefer = (schedule, fn, delay) => {
-              if (typeof fn !== "function") return schedule(fn, delay);
-              const origin = new Error();
-              let id;
-              const wrapped = function () {
-                const result = fn.apply(this, arguments);
-                __rbTimerOrigins.delete(id); // ran cleanly — no need to keep it
-                return result;
-              };
-              id = schedule(wrapped, delay);
-              __rbTimerOrigins.set(id, origin);
-              if (__rbTimerOrigins.size > 4096) __rbTimerOrigins.delete(__rbTimerOrigins.keys().next().value);
-              return id;
-            };
-            globalThis.__rbFetchTimerOrigin = (id) => {
-              const origin = __rbTimerOrigins.get(id);
-              if (!origin) return "";
-              __rbTimerOrigins.delete(id);
-              return origin.stack || "";
-            };
-            globalThis.setTimeout = (fn, delay) => __rbDefer((f, d) => window.setTimeout(f, d), fn, delay);
-            globalThis.clearTimeout = (id) => window.clearTimeout(id);
-            globalThis.setInterval = (fn, delay) => __rbDefer((f, d) => window.setInterval(f, d), fn, delay);
-            globalThis.clearInterval = (id) => window.clearInterval(id);
-            globalThis.requestAnimationFrame = (fn) => __rbDefer((f) => window.requestAnimationFrame(f), fn);
-            globalThis.cancelAnimationFrame = (id) => window.cancelAnimationFrame(id);
-            // queueMicrotask must share the engine's promise-job (microtask)
-            // queue so its callbacks are FIFO-ordered with Promise reactions
-            // (the WHATWG single-microtask-queue model). Routing through the
-            // Ruby scheduler instead would drain on a separate pass, reordering
-            // it after all native promise jobs.
-            globalThis.queueMicrotask = (fn) => {
-              if (typeof fn !== "function") throw new TypeError("queueMicrotask requires a function");
-              Promise.resolve().then(() => { fn(); });
-            };
-          JS
+          install_promise_rejection_hook
+          wire_scheduler(win)
+          @environment.install_timers
           win
         end
 
@@ -109,14 +64,34 @@ module Dommy
           @bridge.expose_constructors_on(window_obj)
         end
 
+        # Wire the bare browser globals frameworks reach for, aliased onto the
+        # installed window: self / location / history / navigator / storages /
+        # CSS / fetch / addEventListener / .... Call after install_window. This
+        # is what lets real frontend bundles (Turbo, …) run unmodified.
+        def install_browser_globals
+          @environment.install_globals
+          self
+        end
+
+        # WPT-only scaffolding, part of the port's optional surface: the
+        # harness's common/sab.js derives the SharedArrayBuffer constructor from
+        # `new WebAssembly.Memory({shared:true}).buffer.constructor`. That is
+        # what the WebAssembly stub's Memory already yields, so this is the same
+        # install — named separately because a host asks for it explicitly, and a
+        # no-op when #install_browser_globals already ran.
+        def install_wasm_memory_shim
+          @environment.install_wasm_stub
+          self
+        end
+
+        # --- Running scripts ---
+
         # Run a script for side effects (no return value). Wrapped in an IIFE so
         # statements are allowed and the completion value is voided — otherwise a
         # trailing Promise expression would trip the gem's "unawaited Promise"
         # guard. Drains microtasks so queued .then work lands before returning.
         def execute(js)
-          @backend.eval("(function () {\n#{js}\n})();")
-          drain_microtasks
-          nil
+          in_page_turn { @backend.eval("(function () {\n#{js}\n})();") }
         end
 
         # Load a script the way a browser <script> does: in GLOBAL scope, so its
@@ -125,18 +100,16 @@ module Dommy
         # `var Vue = (function(){…})({})`, which an IIFE wrapper (execute) would
         # trap in function scope. Drains microtasks afterward.
         def load_script(js)
-          @backend.eval(js)
-          drain_microtasks
-          nil
+          in_page_turn { @backend.eval(discard_completion_value(js)) }
         end
 
         # Like #load_script, but compiles the source to bytecode once per
         # `cache_key` (an external script's URL) and reuses it across VMs —
         # avoiding a re-parse of large vendored bundles on every page load.
         def load_script_cached(js, cache_key:)
-          @backend.run_compiled(ScriptCache.compiled(cache_key, js))
-          drain_microtasks
-          nil
+          in_page_turn do
+            @backend.run_compiled(ScriptCache.compiled(cache_key, discard_completion_value(js)))
+          end
         end
 
         # Install the ESM module resolver (see Backend#module_loader=). A
@@ -145,79 +118,43 @@ module Dommy
           @backend.module_loader = callable
         end
 
-        # Evaluate an inline `<script type="module">` body as an ES module (run
-        # for side effects). Bare specifiers / absolute paths in its imports
-        # resolve through the module loader. Drains microtasks afterward.
-        def load_module(source)
-          @backend.import_module(source)
-          drain_microtasks
-          nil
-        end
-
         # Evaluate an external module by URL (the loader fetches it); its
-        # relative imports resolve against that URL. Drains microtasks.
+        # relative imports resolve against that URL. An inline module arrives
+        # here too, seeded under a page URL by ScriptBoot so `import.meta.url`
+        # resolves. Drains microtasks.
         def load_module_url(url)
-          @backend.import_module_url(url)
-          drain_microtasks
-          nil
+          in_page_turn { @backend.import_module_url(url) }
         end
 
         # Evaluate JS and return its value, with DOM nodes decoded to Dommy
         # objects (rather than the empty Hash a raw proxy becomes crossing to
         # Ruby). Accepts either an expression (`document.title`) or a statement
-        # body that uses `return` (`const x = ...; return x;`): the expression
-        # form is tried first and, on a syntax error, retried as an async
-        # function body. Syntax errors are compile-time so the failed first
-        # attempt runs nothing. The result is awaited, so a Promise resolves
-        # before returning.
+        # body that uses `return` (`const x = ...; return x;`), run as an async
+        # function body. Which one it is gets decided by compiling, not by
+        # running and retrying (see #expression?). The result is awaited, so a
+        # Promise resolves before returning.
         def evaluate(js)
-          evaluate_settled("(#{js.strip.sub(/;\s*\z/, "")})")
-        rescue ::Quickjs::SyntaxError
-          evaluate_settled("(async () => {\n#{js}\n})()")
+          bump_dom_epoch
+          evaluate_settled(expression?(js) ? parenthesized(js) : "(async () => {\n#{js}\n})()")
         end
 
-        # Evaluate `expr` to its awaited value, driving the event loop so a result
-        # that depends on a TASK (a fetch's setTimeout(0) delivery, a setTimeout)
-        # settles first. The gem's top-level await (js_std_await) only drains the
-        # engine's job queue, never Dommy's scheduler — so awaiting a task-resolved
-        # promise directly deadlocks in C. Instead: store the result, run the
-        # event loop over everything due NOW (microtask checkpoint + due tasks and
-        # the tasks they chain), then await the now-settled promise (which returns
-        # immediately and still surfaces a rejection as a Ruby raise, as before).
-        def evaluate_settled(expr)
-          # `void 0` keeps the completion value off the promise, so the eval
-          # doesn't trip the gem's "unawaited Promise at top-level" guard.
-          @backend.eval("globalThis.__rbEvalP = Promise.resolve(#{expr}); void 0;")
-          drive_due_now
-          @bridge.decode(eval_tagged("await globalThis.__rbEvalP"))
+        # Optional Runtime API: run a script with Ruby arguments as its
+        # `arguments`. DOM objects cross as JS proxies (the same wire the bridge
+        # uses for any Ruby->JS value), so `arguments[0].scrollIntoView()` works.
+        # The wire payload is JSON spliced into the source and rehydrated
+        # in-realm (`__rbHost.rehydrateArgs`), then spread into the script.
+        def execute_with_args(js, args)
+          wire = encode_args(args)
+          in_page_turn { @backend.eval("(function () {\n#{with_arguments_js(js, wire)}\n})();") }
         end
 
-        # Run the event loop over the work ready at the current virtual time —
-        # the microtask checkpoint plus every due task and anything it queues at
-        # the same instant — WITHOUT advancing the clock to a future timer (a
-        # result waiting on a real delay is left for the await to surface). The
-        # nested-timer 4ms clamp guarantees due-now work drains in finite turns.
-        def drive_due_now
-          sched = @window&.scheduler
-          return drain_microtasks unless sched
-
-          64.times do
-            sched.advance_time(0)
-            break unless sched.next_due_timer_at == sched.now_ms
-          end
-          nil
-        end
-
-        def drain_microtasks
-          @backend.drain_microtasks
-        rescue ::Quickjs::RuntimeError => e
-          # The microtask checkpoint hit out-of-memory and poisoned the VM. Per
-          # the "browsing never crashes" contract, don't let it escape the event
-          # loop: record it once (so it shows in js_errors / the activity log) and
-          # then no-op — the page's JS is dead, but the browser stays alive.
-          raise unless @backend.poisoned?
-
-          note_js_halted(e)
+        # Args-aware evaluate. Like #evaluate, the script is an expression
+        # (`arguments[0].value`, the form Capybara's evaluate_script passes) or a
+        # body that uses `return`; the decoded result is awaited.
+        def evaluate_with_args(js, args)
+          bump_dom_epoch
+          body = expression?(js) ? "return #{parenthesized(js)};" : js
+          evaluate_settled("(async function () {\n#{with_arguments_js(body, encode_args(args))}\n})()")
         end
 
         # Drive the document lifecycle: set `document.readyState` and fire the
@@ -234,96 +171,69 @@ module Dommy
           self
         end
 
-        # Handle-oriented JS access for a wasm guest (see WasmBridge). Memoized
-        # so the guest's `__rbWasmInvoke` dispatcher (installed via #on_invoke)
-        # stays registered for the VM's lifetime.
-        def wasm_bridge
-          @wasm_bridge ||= WasmBridge.new(@backend)
-        end
+        # --- Driving the event loop (see EventLoop for what each one means) ---
 
-        # Drive the event loop to quiescence: drain the native microtask queue,
-        # then advance the deterministic scheduler to its next due timer and drain
-        # again, repeating until no timer is pending. This is the single
-        # deterministic "settle everything" entry point a host uses after an eval
-        # (mirroring a `drain_async!`): every queued microtask runs and every
-        # scheduled timer fires, in WHATWG order (microtasks before each timer).
-        # `max_iterations` bounds runaway timer loops (e.g. a self-rescheduling
-        # setInterval).
-        def run_until_idle(max_iterations: 1000)
-          sched = @window&.scheduler
-          max_iterations.times do
-            drain_microtasks
-            break unless sched
-
-            next_at = sched.next_due_timer_at
-            break unless next_at
-
-            sched.advance_time(next_at - sched.now_ms)
-            drain_microtasks
-          end
+        def drain_microtasks = @loop.drain_microtasks
+
+        def settle(max_iterations: EventLoop::DEFAULT_MAX_ITERATIONS)
+          @loop.settle(max_iterations: max_iterations)
           self
         end
 
-        # Settle the work that is READY at the current virtual time: drain
-        # microtasks, run timers already due now (`setTimeout(0)` chains), and
-        # flush pending `requestAnimationFrame` callbacks by advancing to their
-        # frame boundary — but do NOT jump the clock to a not-yet-due
-        # `setTimeout(300)` (that needs an explicit `advance_time(300)`). This is
-        # the "let promises and animation frames resolve" entry point; `bound`
-        # caps a self-rescheduling rAF loop.
-        def settle(max_iterations: 1000)
-          sched = @window&.scheduler
-          max_iterations.times do
-            drain_microtasks
-            break unless sched
-
-            before = sched.now_ms
-            sched.advance_time(0) # run due-now timers + microtasks, no clock jump
-            drain_microtasks
-
-            raf_at = sched.next_animation_frame_at
-            if raf_at && raf_at > sched.now_ms
-              sched.advance_time(raf_at - sched.now_ms) # advance to the frame, run rAF
-              drain_microtasks
-              next
-            end
-
-            break if sched.now_ms == before
-          end
+        def run_until_idle(max_iterations: EventLoop::DEFAULT_MAX_ITERATIONS)
+          @loop.run_until_idle(max_iterations: max_iterations)
           self
         end
 
+        # --- Errors ---
+
+        # An engine exception for a script's throw, rebuilt as a real Error
+        # inside the realm so `event.error` is something the page can read.
+        # Optional in the port contract; returns nil when it cannot be done.
+        def rebuild_error(error) = @errors.rebuild_error(error)
+
         # Surface otherwise-swallowed JS promise rejections (see Backend).
+        # Goes quiet once the JS hook is installed: both would fire for the same
+        # rejection, and the hook carries strictly more.
+        #
+        # Goes quiet, too, on an engine that reports a rejection before a
+        # handler could attach (Backend.premature_rejection_reports?): there
+        # every `.catch` and `try { await … } catch` would surface as an
+        # unhandled rejection and fail a strict host on correct code. Reporting
+        # none is the lesser loss — a rejection the page truly leaves unhandled
+        # goes unreported until the engine is fixed.
         def on_unhandled_rejection(&block)
-          if @track_rejections
-            @backend.on_unhandled_rejection { |err| block.call(enrich_rejection(err)) }
-          else
-            @backend.on_unhandled_rejection(&block)
+          # Decided when a rejection actually arrives, not now: a host registers
+          # this before #install_window, which is where the hook goes in.
+          relay = lambda do |error|
+            next if js_rejection_hook?
+            next self.class.warn_premature_rejection_reports if Backend.premature_rejection_reports?
+
+            block.call(@track_rejections ? @errors.enrich_rejection(error) : error)
           end
+          @backend.on_unhandled_rejection(&relay)
           self
         end
 
-        # In rejection-debug mode, replace the engine's detail-less "[object
-        # Object]" message (a non-Error reason the engine could only toString)
-        # with the rich detail recorded JS-side at rejection time, paired by
-        # recency. A no-op for errors that already carry a real message.
-        def enrich_rejection(err)
-          return err unless err.respond_to?(:message) && err.message.to_s.strip == "[object Object]"
-
-          detail = @bridge.take_rejection_detail
-          return err if detail.nil? || detail.to_s.empty?
+        # Said once per process, on the first rejection left unreported.
+        def self.warn_premature_rejection_reports
+          return if @warned_premature_rejection_reports
 
-          enriched = ::Quickjs::RuntimeError.new(detail.to_s, "UnhandledRejection")
-          enriched.set_backtrace(err.backtrace) if err.backtrace
-          enriched
-        rescue StandardError
-          err
+          @warned_premature_rejection_reports = true
+          warn "dommy-js-quickjs: this quickjs (#{::Quickjs::VERSION}) reports a promise rejection before " \
+               "a handler can attach, so unhandled rejections are not reported. A quickjs with " \
+               "hmsk/quickjs.rb#141 (unhandled-rejection timing) reports them."
+          nil
         end
 
+        # Whether rejections arrive through the JS hook. A host that also relays
+        # #on_unhandled_rejection would otherwise report each rejection twice.
+        def js_rejection_hook? = !!@js_rejection_hook
+
         # Observe a timer/rAF callback that was force-killed by the execution
         # timeout (a runaway busy loop). The host records it as a js_error; the
         # offending timer is already dropped by the scheduler so it cannot
-        # re-stall. Optional in the Runtime contract (guard with respond_to?).
+        # re-stall. Optional in the port contract (guard with respond_to?).
         def on_callback_error(&block)
           @callback_error_listener = block
           self
@@ -335,133 +245,13 @@ module Dommy
           self
         end
 
-        # Wire the bare browser globals frameworks reach for, aliased onto the
-        # installed window: self / location / history / navigator / storages /
-        # CSS / fetch / addEventListener / .... Call after install_window. This
-        # is what lets real frontend bundles (Turbo, …) run unmodified.
-        def install_browser_globals
-          alias_browser_globals
-          install_intl_polyfill
-          install_wasm_stub
-          mirror_builtins_on_window
-          self
-        end
+        # --- Introspection and teardown ---
 
-        # This QuickJS build has no WebAssembly, so a bare `WebAssembly.foo`
-        # reference throws `'WebAssembly' is not defined` (nuxt.com via Shiki,
-        # many bundlers' feature probes). Define a stub: compile/instantiate
-        # reject and validate() returns false, so WASM-loading code takes its
-        # JS fallback instead of crashing. `Memory` honors `{shared:true}` (a
-        # SharedArrayBuffer) so WPT's common/sab.js keeps working.
-        def install_wasm_stub
-          @backend.eval(WASM_STUB_JS)
-          self
-        end
-
-        WASM_STUB_JS = <<~'JS'
-          if (typeof globalThis.WebAssembly === "undefined") {
-            var unsupported = function () { return Promise.reject(new Error("WebAssembly is not supported")); };
-            var throwUnsupported = function () { throw new Error("WebAssembly is not supported"); };
-            globalThis.WebAssembly = {
-              instantiate: unsupported, instantiateStreaming: unsupported,
-              compile: unsupported, compileStreaming: unsupported,
-              validate: function () { return false; },
-              Module: throwUnsupported, Instance: throwUnsupported,
-              Memory: function (opts) {
-                var bytes = ((opts && opts.initial) || 0) * 65536;
-                this.buffer = (opts && opts.shared && typeof SharedArrayBuffer === "function")
-                  ? new SharedArrayBuffer(bytes) : new ArrayBuffer(bytes);
-              },
-              Table: function () {}, Global: function () {},
-              CompileError: Error, LinkError: Error, RuntimeError: Error,
-            };
-          }
-        JS
-
-        # This QuickJS build ships without ICU, so `Intl` is undefined and any
-        # page touching `Intl.NumberFormat` / `DateTimeFormat` / … throws
-        # `'Intl' is not defined` (nuxt.com, i18n libraries, …). Install a small
-        # locale-naive polyfill: it formats reasonably (grouped numbers, ISO-ish
-        # dates) so pages run instead of crashing, without pulling in full ICU.
-        def install_intl_polyfill
-          @backend.eval(INTL_POLYFILL_JS)
-          self
-        end
-
-        INTL_POLYFILL_JS = <<~'JS'
-          if (typeof globalThis.Intl === "undefined") {
-            var I = {};
-            var group = function (s) {
-              var p = String(s).split(".");
-              p[0] = p[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-              return p.join(".");
-            };
-            function NumberFormat(l, o) { this.o = o || {}; }
-            NumberFormat.prototype.format = function (n) {
-              n = Number(n); var o = this.o;
-              if (o.style === "percent") n *= 100;
-              var max = o.maximumFractionDigits;
-              if (max == null && o.style === "currency") max = 2;
-              var s = group(max == null ? String(n) : n.toFixed(max));
-              if (o.style === "percent") s += "%";
-              if (o.style === "currency" && o.currency) s = o.currency + " " + s;
-              return s;
-            };
-            NumberFormat.prototype.formatToParts = function (n) { return [{ type: "literal", value: this.format(n) }]; };
-            NumberFormat.prototype.resolvedOptions = function () { return Object.assign({ locale: "en", numberingSystem: "latn", style: "decimal" }, this.o); };
-            function DateTimeFormat(l, o) { this.o = o || {}; }
-            DateTimeFormat.prototype.format = function (d) {
-              d = d == null ? new Date() : new Date(d);
-              if (isNaN(d.getTime())) return "";
-              try { return d.toLocaleString(); } catch (e) { return d.toString(); }
-            };
-            DateTimeFormat.prototype.formatToParts = function (d) { return [{ type: "literal", value: this.format(d) }]; };
-            DateTimeFormat.prototype.formatRange = function (a, b) { return this.format(a) + " – " + this.format(b); };
-            DateTimeFormat.prototype.resolvedOptions = function () { return Object.assign({ locale: "en", calendar: "gregory", numberingSystem: "latn", timeZone: "UTC" }, this.o); };
-            function Collator(l, o) { this.o = o || {}; }
-            Collator.prototype.compare = function (a, b) { a = String(a); b = String(b); return a < b ? -1 : a > b ? 1 : 0; };
-            Collator.prototype.resolvedOptions = function () { return Object.assign({ locale: "en" }, this.o); };
-            function PluralRules(l, o) { this.o = o || {}; }
-            PluralRules.prototype.select = function (n) { return Number(n) === 1 ? "one" : "other"; };
-            PluralRules.prototype.resolvedOptions = function () { return Object.assign({ locale: "en", type: "cardinal" }, this.o); };
-            function RelativeTimeFormat(l, o) { this.o = o || {}; }
-            RelativeTimeFormat.prototype.format = function (v, u) { return v + " " + u + (Math.abs(v) === 1 ? "" : "s"); };
-            RelativeTimeFormat.prototype.formatToParts = function (v, u) { return [{ type: "literal", value: this.format(v, u) }]; };
-            RelativeTimeFormat.prototype.resolvedOptions = function () { return Object.assign({ locale: "en", numeric: "always", style: "long" }, this.o); };
-            function ListFormat(l, o) { this.o = o || {}; }
-            ListFormat.prototype.format = function (a) { return Array.from(a || []).join(", "); };
-            ListFormat.prototype.formatToParts = function (a) { return [{ type: "element", value: this.format(a) }]; };
-            ListFormat.prototype.resolvedOptions = function () { return Object.assign({ locale: "en", type: "conjunction", style: "long" }, this.o); };
-            I.NumberFormat = NumberFormat; I.DateTimeFormat = DateTimeFormat; I.Collator = Collator;
-            I.PluralRules = PluralRules; I.RelativeTimeFormat = RelativeTimeFormat; I.ListFormat = ListFormat;
-            ["NumberFormat", "DateTimeFormat", "Collator", "PluralRules", "RelativeTimeFormat", "ListFormat"].forEach(function (k) {
-              I[k].supportedLocalesOf = function (locs) { return Array.isArray(locs) ? locs.slice() : locs ? [locs] : []; };
-            });
-            I.getCanonicalLocales = function (locs) { return Array.isArray(locs) ? locs.slice() : locs ? [String(locs)] : []; };
-            globalThis.Intl = I;
-          }
-        JS
-
-        # WPT-only scaffolding: a minimal `WebAssembly.Memory` whose `.buffer`
-        # is a SharedArrayBuffer. The engine ships a real SharedArrayBuffer but
-        # no WebAssembly, and WPT's `common/sab.js` derives the SAB constructor
-        # from `new WebAssembly.Memory({shared:true}).buffer.constructor`. This
-        # is test-harness-only (real pages never need it), so it is opt-in and
-        # NOT part of #install_browser_globals.
-        def install_wasm_memory_shim
-          @backend.eval(<<~JS)
-            if (typeof globalThis.WebAssembly === "undefined" && typeof globalThis.SharedArrayBuffer === "function") {
-              globalThis.WebAssembly = {
-                Memory: function (opts) {
-                  const bytes = ((opts && opts.initial) || 0) * 65536;
-                  this.buffer = (opts && opts.shared)
-                    ? new SharedArrayBuffer(bytes)
-                    : new ArrayBuffer(bytes);
-                },
-              };
-            }
-          JS
-          self
+        # Handle-oriented JS access for a wasm guest (see WasmBridge). Memoized
+        # so the guest's `__rbWasmInvoke` dispatcher (installed via #on_invoke)
+        # stays registered for the VM's lifetime.
+        def wasm_bridge
+          @wasm_bridge ||= WasmBridge.new(@backend)
         end
 
         # Run JS GC then drain, so FinalizationRegistry cleanup callbacks fire and
@@ -472,26 +262,54 @@ module Dommy
         end
 
         # Live handle count (introspection for lifetime tests).
-        def registered_count
-          @bridge.registered_count
-        end
+        def registered_count = @bridge.registered_count
 
         # Snapshot bridge crossing counts when DOMMY_JS_BRIDGE_PROFILE=1.
-        def bridge_crossing_counts(limit: nil)
-          @bridge.crossing_counts(limit: limit)
-        end
+        def bridge_crossing_counts(limit: nil) = @bridge.crossing_counts(limit: limit)
 
         def reset_bridge_crossing_counts
           @bridge.reset_crossing_counts
           self
         end
 
-        def dispose
-          @backend.dispose
-        end
+        def dispose = @backend.dispose
 
         private
 
+        # A runaway timer/rAF callback (busy loop) is force-killed by the gem's
+        # eval timeout, surfacing as a Quickjs::InterruptedError out of the host
+        # call. Route it through the scheduler's error hook so it is recorded as
+        # a js_error and dropped, not propagated as a fatal crash (browsing must
+        # never crash). Genuine host bugs (any other error) still propagate.
+        #
+        # The microtask checkpoint is the other half of the wiring: draining
+        # after EACH task (not once per batch of due timers) is what the event
+        # loop processing model requires.
+        def wire_scheduler(win)
+          return unless win.respond_to?(:scheduler) && win.scheduler
+
+          win.scheduler.timer_error_handler = method(:handle_timer_error)
+          win.scheduler.microtask_checkpoint = method(:drain_microtasks)
+        end
+
+        # Hand rejections to the JS hook rather than to a Ruby callback, when the
+        # engine has one. It is called with the promise and the reason as the
+        # values the page threw, which is the whole point: an exception the
+        # engine already converted has lost both, and the page ends up with an
+        # object it cannot read. The hook also reports the other half of HTML's
+        # tracking, `rejectionhandled`, which a Ruby callback never sees.
+        #
+        # No-op on an engine without it; #on_unhandled_rejection then stays the
+        # route, with the losses that implies.
+        def install_promise_rejection_hook
+          return unless @backend.respond_to?(:promise_rejection_hook=)
+
+          @backend.promise_rejection_hook = "__rbHost.onPromiseRejection"
+          @js_rejection_hook = true
+        rescue ::StandardError
+          @js_rejection_hook = false
+        end
+
         # Scheduler hook: a timer/rAF callback raised. A JS-execution error —
         # the callback threw (Quickjs::RuntimeError) or was force-killed for
         # running too long (Quickjs::InterruptedError < RuntimeError) — must not
@@ -505,113 +323,96 @@ module Dommy
           # An out-of-memory in a timer callback poisons the whole VM: the page's
           # JS is dead from here on, so flag it (and report once) — not just this
           # one callback.
-          note_js_halted(error) if @backend.poisoned?
-          @callback_error_listener&.call(enrich_callback_error(error, timer))
+          @loop.note_halted_if_poisoned(error)
+          @callback_error_listener&.call(@errors.with_timer_origin(error, timer))
           true
         end
 
-        # The VM hit out-of-memory and is poisoned. Surface the failure ONCE (a
-        # repeated drain would otherwise report it every tick) so the user sees
-        # that the page's JavaScript stopped, then leave it to the no-op guards.
-        def note_js_halted(error)
-          return if @js_halted
+        # A classic script's completion value is discarded by a browser, but the
+        # gem converts whatever the eval returned and REFUSES a pending Promise
+        # ("An unawaited Promise was returned to the top-level"). A script whose
+        # last statement is an assignment of one — `window.p = new Promise(…);`,
+        # which is how a page publishes a promise for a later script to await —
+        # therefore reached the page as an uncaught error, and a testharness page
+        # that saw it reported no results at all.
+        #
+        # #execute solves this by wrapping in an IIFE, which #load_script cannot
+        # do: its declarations have to land in global scope. Append a statement
+        # that evaluates to undefined instead. The leading newline is what keeps
+        # it out of a trailing line comment, and no declaration moves scope.
+        def discard_completion_value(js) = "#{js}\n;void 0;"
+
+        # One turn of handing the page something to run. Ruby may have mutated the
+        # DOM since JS last ran, so the bridge's attribute snapshots are
+        # invalidated first; then the work runs; then queued `.then` work lands
+        # before the caller gets control back.
+        #
+        # Every entry point that gives the page code goes through here, so a new
+        # one cannot forget either half. Forgetting the first would be the quiet
+        # kind of bug: the page reads attribute values that are no longer true,
+        # and nothing raises.
+        def in_page_turn
+          bump_dom_epoch
+          yield
+          drain_microtasks
+          nil
+        end
 
-          @js_halted = true
-          @callback_error_listener&.call(error)
+        # Ruby -> JS entry: Ruby code (test drivers, script boot) may have
+        # mutated the DOM since JS last ran, so invalidate the bridge's
+        # attribute snapshots (see host_runtime.js). A no-op before the host
+        # runtime is installed.
+        def bump_dom_epoch
+          @backend.eval("globalThis.__rbHost && globalThis.__rbHost.bumpDomEpoch();")
           nil
         end
 
-        # Attach the timer's scheduling stack (where the page set the timer up) to
-        # the recorded error, so a callback that throws a stackless value — a bare
-        # `null`, common in minified bundles — is still traceable to the code that
-        # scheduled it. The error's class (and message, the dedup key) is kept;
-        # only its backtrace is replaced with the JS frames, which the diagnostics
-        # UI reads in place of the host scheduler internals. A no-op when no origin
-        # was captured (a timer not created through the instrumented globals, or a
-        # unit test driving the scheduler directly).
-        def enrich_callback_error(error, timer)
-          frames = fetch_timer_origin(timer)
-          error.set_backtrace(frames) unless frames.empty?
-          error
-        rescue StandardError
-          error
-        end
-
-        # The scheduling stack for `timer`, as cleaned frame strings (or []). The
-        # origin Error lives JS-side until now; fetching it also clears it.
-        def fetch_timer_origin(timer)
-          return [] unless timer.respond_to?(:id)
-
-          stack = @backend.call_js("__rbFetchTimerOrigin", timer.id).to_s
-          # Drop the shim's own frame (the `new Error()` in __rbDefer) so the top
-          # frame is the page code that called setTimeout/setInterval.
-          stack.split("\n").map(&:strip).reject(&:empty?)
-               .reject { |line| line.include?("__rbDefer") }
-        rescue StandardError
-          []
-        end
-
-        # Alias the bare browser globals frameworks reach for onto the installed
-        # window (self/parent/top/location/history/navigator/storages/CSS/fetch/
-        # event methods). This is what lets real frontend bundles run unmodified.
-        def alias_browser_globals
-          @backend.eval(<<~JS)
-            globalThis.self = globalThis;
-            // Top-level window: parent/top are the window itself (spec), so
-            // frame-walking loops terminate instead of dereferencing undefined.
-            globalThis.parent = globalThis;
-            globalThis.top = globalThis;
-            globalThis.location = window.location;
-            globalThis.history = window.history;
-            globalThis.navigator = window.navigator;
-            globalThis.sessionStorage = window.sessionStorage;
-            globalThis.localStorage = window.localStorage;
-            globalThis.CSS = window.CSS;
-            globalThis.getComputedStyle = (...args) => window.getComputedStyle(...args);
-            globalThis.matchMedia = (...args) => window.matchMedia(...args);
-            globalThis.fetch = (...args) => window.fetch(...args);
-            globalThis.addEventListener = (...args) => window.addEventListener(...args);
-            globalThis.removeEventListener = (...args) => window.removeEventListener(...args);
-            globalThis.dispatchEvent = (event) => window.dispatchEvent(event);
-
-            // More bare globals frameworks read directly (e.g. performance.now(),
-            // crypto, screen). Objects/values are aliased by reference; methods are
-            // wrapped so `this` binds to the window. All already exist on window.
-            for (const __n of ["performance", "crypto", "screen", "visualViewport",
-                               "indexedDB", "caches", "devicePixelRatio",
-                               "innerWidth", "innerHeight", "scrollX", "scrollY", "pageXOffset"]) {
-              try { globalThis[__n] = window[__n]; } catch (__e) {}
-            }
-            for (const __m of ["scrollTo", "scrollBy", "requestIdleCallback", "cancelIdleCallback",
-                               "getSelection", "structuredClone", "reportError", "btoa", "atob",
-                               "alert", "confirm", "prompt", "open", "postMessage"]) {
-              try { globalThis[__m] = (...args) => window[__m](...args); } catch (__e) {}
-            }
-          JS
-        end
-
-        # The window IS the global object, so JS built-in constructors and
-        # namespaces are also `window` properties (`window.String`,
-        # `window.Number`, …). Mirror them as own props on the window proxy so
-        # code that reads constructors off `window` (e.g. the WPT reflection
-        # harness's `window[type]` casts) resolves them.
-        def mirror_builtins_on_window
-          @backend.eval(<<~JS)
-            for (const __n of [
-              "String", "Boolean", "Number", "BigInt", "Symbol", "Object", "Array",
-              "Function", "Date", "RegExp", "Promise", "Map", "Set", "WeakMap",
-              "WeakSet", "Math", "JSON", "Reflect", "Proxy", "Error", "TypeError",
-              "RangeError", "SyntaxError", "Infinity", "NaN", "undefined",
-              "parseInt", "parseFloat", "isNaN", "isFinite", "globalThis",
-            ]) {
-              try { window[__n] = globalThis[__n]; } catch (__e) {}
-            }
-          JS
+        # Evaluate `expr` to its awaited value, driving the event loop so a result
+        # that depends on a TASK (a fetch's setTimeout(0) delivery, a setTimeout)
+        # settles first. The gem's top-level await (js_std_await) only drains the
+        # engine's job queue, never Dommy's scheduler — so awaiting a task-resolved
+        # promise directly deadlocks in C. Instead: store the result, run the
+        # event loop over everything due NOW (microtask checkpoint + due tasks and
+        # the tasks they chain), then await the now-settled promise (which returns
+        # immediately and still surfaces a rejection as a Ruby raise, as before).
+        def evaluate_settled(expr)
+          # `void 0` keeps the completion value off the promise, so the eval
+          # doesn't trip the gem's "unawaited Promise at top-level" guard.
+          @backend.eval("globalThis.__rbEvalP = Promise.resolve(#{expr}); void 0;")
+          @loop.drive_due_now
+          @bridge.decode(eval_tagged("await globalThis.__rbEvalP"))
         end
 
         def eval_tagged(inner_expr)
           @backend.eval_awaited("__rbHost.tag(#{inner_expr});")
         end
+
+        # Whether `js` is a single expression, found by compiling it — nothing
+        # runs. Running it and retrying as a body on SyntaxError could not tell
+        # a parse error from one the script throws (`JSON.parse("{")`), and the
+        # retry then ran the script's side effects a second time.
+        def expression?(js)
+          Backend.compile(parenthesized(js))
+          true
+        rescue ::Quickjs::SyntaxError
+          false
+        end
+
+        # `js` as a parenthesized expression, a trailing `;` dropped. The
+        # newlines keep a trailing line comment from swallowing the `)`.
+        def parenthesized(js) = "(\n#{js.strip.sub(/;\s*\z/, "")}\n)"
+
+        # Script arguments as the bridge's JSON wire payload.
+        def encode_args(args) = JSON.generate(@bridge.encode(Array(args)))
+
+        # A script body wrapped so `arguments` are the wire payload rehydrated
+        # in-realm (DOM handles become JS proxies). The payload is spliced into
+        # the source as a JSON literal and held in a function-local `var`, so
+        # nested calls can't collide and there is no global to clean up.
+        def with_arguments_js(js, wire_json)
+          "var __rbScriptArgs = __rbHost.rehydrateArgs(#{wire_json});\n" \
+            "return (function () {\n#{js}\n}).apply(this, __rbScriptArgs);"
+        end
       end
     end
   end