dommy-js-quickjs 0.1.0 → 0.10.0

data/lib/dommy/js/quickjs/js/timer_globals.js

@@ -0,0 +1,46 @@
+// The bare timer globals a browser exposes, routed into Dommy's deterministic
+// scheduler through the window (`window.setTimeout` already works via the
+// Window manifest; these are the unqualified ones).
+//
+// 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 + Runtime#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(); });
+};

data/lib/dommy/js/quickjs/js/wasm_stub.js

@@ -0,0 +1,26 @@
+// 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}` with a SharedArrayBuffer, which the engine
+// does ship. That is also what WPT's common/sab.js needs: it derives the SAB
+// constructor from `new WebAssembly.Memory({shared:true}).buffer.constructor`.
+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,
+  };
+}

data/lib/dommy/js/quickjs/js/window_builtins.js

@@ -0,0 +1,14 @@
+// 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.
+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) {}
+}

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

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

@@ -9,44 +9,51 @@ 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
+          @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.
+          @backend.call_js("__rbHost.installRejectionTracker") if @track_rejections
         end
 
         def define_host_object(name, obj)
           @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
-          @backend.eval(<<~JS)
-            globalThis.setTimeout = (fn, delay) => window.setTimeout(fn, delay);
-            globalThis.clearTimeout = (id) => window.clearTimeout(id);
-            globalThis.setInterval = (fn, delay) => window.setInterval(fn, delay);
-            globalThis.clearInterval = (id) => window.clearInterval(id);
-            globalThis.requestAnimationFrame = (fn) => window.requestAnimationFrame(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
 
@@ -57,67 +64,178 @@ 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
+        # top-level `var` / `function` / `let` declarations become globals. UMD /
+        # "global" bundles rely on this — e.g. Vue's global build is literally
+        # `var Vue = (function(){…})({})`, which an IIFE wrapper (execute) would
+        # trap in function scope. Drains microtasks afterward.
+        def load_script(js)
+          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:)
+          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
+        # callable `(specifier, importer) -> source | {code:, as:} | nil`.
+        def module_loader=(callable)
+          @backend.module_loader = callable
+        end
+
+        # Evaluate an external module by URL (the loader fetches it); its
+        # 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)
+          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)
-          @bridge.decode(eval_tagged("await (#{js.strip.sub(/;\s*\z/, "")})"))
-        rescue ::Quickjs::SyntaxError
-          @bridge.decode(eval_tagged("await (async () => {\n#{js}\n})()"))
+          bump_dom_epoch
+          evaluate_settled(expression?(js) ? parenthesized(js) : "(async () => {\n#{js}\n})()")
         end
 
-        def drain_microtasks
-          @backend.drain_microtasks
+        # 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
 
-        # 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)
+        # 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 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
+        # Drive the document lifecycle: set `document.readyState` and fire the
+        # milestone events (`readystatechange`, then `DOMContentLoaded` on
+        # "interactive" / `load` on "complete"), then drain microtasks so the
+        # listeners settle. Lets a host replay the real load sequence so code
+        # that waits on document readiness (framework startup, `ready` handlers)
+        # runs the deferred path. The document defaults to "complete", so call
+        # `set_document_ready_state("loading")` BEFORE loading such code to
+        # exercise the waiting path.
+        def set_document_ready_state(state)
+          @window&.document&.__internal_set_ready_state__(state)
+          drain_microtasks
+          self
+        end
+
+        # --- Driving the event loop (see EventLoop for what each one means) ---
+
+        def drain_microtasks = @loop.drain_microtasks
+
+        def settle(max_iterations: EventLoop::DEFAULT_MAX_ITERATIONS)
+          @loop.settle(max_iterations: max_iterations)
+          self
+        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)
-          @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
+
+        # Said once per process, on the first rejection left unreported.
+        def self.warn_premature_rejection_reports
+          return if @warned_premature_rejection_reports
+
+          @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 port contract (guard with respond_to?).
+        def on_callback_error(&block)
+          @callback_error_listener = block
           self
         end
 
@@ -127,60 +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
-          @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.fetch = (...args) => window.fetch(...args);
-            globalThis.addEventListener = (...args) => window.addEventListener(...args);
-            globalThis.removeEventListener = (...args) => window.removeEventListener(...args);
-            globalThis.dispatchEvent = (event) => window.dispatchEvent(event);
-            // 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.
-            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) {}
-            }
-            // Minimal WebAssembly.Memory: the engine provides a real
-            // SharedArrayBuffer but no WebAssembly, and WPT's `common/sab.js`
-            // derives the SAB constructor from
-            // `new WebAssembly.Memory({shared:true}).buffer.constructor`. A
-            // Memory whose `.buffer` is a SharedArrayBuffer is enough to let
-            // those tests (encodeInto, TextDecoder copy, …) exercise shared
-            // buffers with the real codec logic.
-            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
+        # --- Introspection and teardown ---
+
+        # 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
@@ -191,19 +262,157 @@ 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)
 
-        def dispose
-          @backend.dispose
+        def reset_bridge_crossing_counts
+          @bridge.reset_crossing_counts
+          self
         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
+        # escape its dispatch (WHATWG: a timer callback's exception is reported,
+        # the event loop keeps running). Record it and return truthy so the
+        # scheduler drops the timer and browsing continues. A non-JS error is a
+        # genuine host bug: return falsy so it propagates.
+        def handle_timer_error(error, timer)
+          return false unless error.is_a?(::Quickjs::RuntimeError)
+
+          # 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.
+          @loop.note_halted_if_poisoned(error)
+          @callback_error_listener&.call(@errors.with_timer_origin(error, timer))
+          true
+        end
+
+        # 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
+
+        # 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
+
+        # 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