dommy-js-quickjs 0.1.0 → 0.10.0

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

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

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # Every environment variable this backend reads, in one place. They used to
+      # be read where they were needed — three files, three layers — so the only
+      # way to learn which knobs exist was to grep for `ENV`.
+      #
+      # Read at the point of use rather than memoized: a test (and dommynx)
+      # changes these between runtimes in the same process.
+      module Config
+        # The gem's default eval timeout is 100ms, which interrupts large
+        # synchronous bridge loops (every property crossing is a Ruby call).
+        DEFAULT_TIMEOUT_MSEC = 60_000
+
+        # The gem's default memory ceiling is 128 MB. A real-site SPA (note.com's
+        # Apollo/React bundle, hydration, the whole DOM mirrored as host proxies)
+        # blows past that and the VM hits out-of-memory, which poisons it. Give a
+        # browser-grade VM more headroom so heavy pages actually finish
+        # rendering; the OOM is also survivable (see Backend#poisoned?).
+        DEFAULT_MEMORY_LIMIT = 512 * 1024 * 1024
+
+        module_function
+
+        # The per-eval timeout, in ms. A single JS eval — a script, or one
+        # timer/rAF callback — is force-aborted (Quickjs::InterruptedError,
+        # caught and logged) after this long. It is ALSO the ceiling on how long
+        # QuickJS holds the thread in C: while it runs, a Ctrl-C (delivered as a
+        # deferred SIGINT) can't be serviced, so an interactive host (dommynx)
+        # sets a lower value so a heavy/runaway burst can't freeze the UI for the
+        # full library default.
+        def timeout_msec
+          env = ENV["DOMMY_JS_TIMEOUT_MSEC"].to_i
+          env.positive? ? env : DEFAULT_TIMEOUT_MSEC
+        end
+
+        # The VM's memory ceiling, in bytes. Overridable like the timeout, in MB
+        # for legibility: an out-of-memory poisons the VM and stops the page's
+        # JavaScript for good, so being able to lower it is how that path gets
+        # exercised deliberately (and to raise it for a heavier page than the
+        # default was sized for).
+        def memory_limit
+          mb = ENV["DOMMY_JS_MEMORY_LIMIT_MB"].to_i
+          mb.positive? ? mb * 1024 * 1024 : DEFAULT_MEMORY_LIMIT
+        end
+
+        # Whether to keep the gem's per-crossing Ruby `Timeout.timeout` (see
+        # Backend's SkipCrossingTimeout). Off by default: it costs ~4us on every
+        # DOM crossing, and QuickJS's own interrupt handler already bounds a
+        # runaway execution.
+        def crossing_timeout? = !ENV["DOMMY_JS_CROSSING_TIMEOUT"].to_s.empty?
+
+        # Whether to record the JS-side detail of a promise rejection, so a
+        # reason the engine could only stringify to "[object Object]" can still
+        # be diagnosed (see ErrorTranslator#enrich_rejection). Opt-in: it makes
+        # every rejection cross the bridge twice.
+        def track_rejections? = !ENV["DOMMY_JS_DEBUG_REJECTIONS"].to_s.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # Turns what the ENGINE raised into what the page (or the host) should see.
+      #
+      # QuickJS converts a JS throw into a Ruby exception before the host hears
+      # about it, which loses the thrown object, and a rejection reason the
+      # engine could only stringify arrives as "[object Object]". Each of those
+      # needs a different repair, and none of them is about running scripts or
+      # driving the loop, so they live here rather than in Runtime.
+      class ErrorTranslator
+        # An engine frame in a converted exception's backtrace (`at f
+        # (<code>:1:34)`). A host-raised one carries Ruby frames instead
+        # (`/…/lib/dommy/js/quickjs/backend.rb:82:in '…'`).
+        #
+        # Core has a stricter counterpart (Internal::ExceptionReport::STACK_FRAME)
+        # that PARSES a frame into file/line/column for ErrorEvent. This one only
+        # asks whether a frame came from JS at all, and stays here because the
+        # answer is engine-specific: what a frame looks like is QuickJS's
+        # business, and another backend's would differ.
+        JS_FRAME = /\A\s*at\s/
+        private_constant :JS_FRAME
+
+        def initialize(backend, bridge)
+          @backend = backend
+          @bridge = bridge
+        end
+
+        # Rebuild a script's thrown value as a real Error inside the realm.
+        #
+        # QuickJS raises a HOST exception when an evaluated script throws, so by
+        # the time we see it the JS value is gone: its message and frames survive
+        # as a Ruby exception, the object itself does not. Handing that husk to
+        # the page gives a handler an object with no `message` and no `stack`,
+        # which is worse than useless — reading either throws, so the handler
+        # dies before it can cancel the report.
+        #
+        # An equivalent Error is built in the realm instead, carrying the same
+        # name, message and frames. Everything a handler observes matches what it
+        # threw; what it cannot do is compare identity (`e.error === thrown`),
+        # since the original was freed before we were told about it. Preserving
+        # that needs the engine to hand the value over instead of converting it.
+        #
+        # Returns nil for anything that did not come from JS (a host bug) and for
+        # any failure to rebuild, so the caller falls back to what it caught.
+        def rebuild_error(error)
+          return nil unless error.is_a?(::Quickjs::RuntimeError)
+
+          # Deliberately NOT through an evaluate that drives the event loop: this
+          # runs while the page is still booting its scripts, and a due-now timer
+          # from an earlier script would fire before the next `<script>`, which
+          # no browser does. Calling the realm's helper (see js/error_rebuild.js)
+          # only builds the object and marshals it.
+          @bridge.decode(
+            @backend.call_js("__rbDommyRebuildError",
+              js_error_name(error), error.message.to_s, js_frames(error))
+          )
+        rescue ::StandardError
+          nil
+        end
+
+        # The JS half of a converted exception's backtrace, as the page's own
+        # `stack` string.
+        #
+        # Handing the host frames to the page would publish this gem's file paths
+        # to anything that reads `error.stack` — a page can log or upload it.
+        # Keep the JS frames, drop the rest, and let an all-host backtrace
+        # produce an empty stack rather than a plausible-looking lie about where
+        # the page failed.
+        def js_frames(error)
+          Array(error.backtrace).grep(JS_FRAME).join("\n")
+        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(error)
+          return error unless error.respond_to?(:message) && error.message.to_s.strip == "[object Object]"
+
+          detail = @bridge.take_rejection_detail
+          return error if detail.nil? || detail.to_s.empty?
+
+          enriched = ::Quickjs::RuntimeError.new(detail.to_s, "UnhandledRejection")
+          enriched.set_backtrace(error.backtrace) if error.backtrace
+          enriched
+        rescue ::StandardError
+          error
+        end
+
+        # Attach the timer's scheduling stack (where the page set the timer up)
+        # to the 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 with_timer_origin(error, timer)
+          frames = timer_origin(timer)
+          error.set_backtrace(frames) unless frames.empty?
+          error
+        rescue ::StandardError
+          error
+        end
+
+        private
+
+        # The JS constructor name behind a converted exception. quickjs.rb maps
+        # each standard error to its own subclass (`Quickjs::TypeError` for a JS
+        # `TypeError`), and uses the generic `RuntimeError` for a plain `Error`
+        # and for a thrown non-Error.
+        def js_error_name(error)
+          name = error.class.name.to_s.split("::").last.to_s
+          name == "RuntimeError" ? "Error" : name
+        end
+
+        # The scheduling stack for `timer`, as cleaned frame strings (or []). The
+        # origin Error lives JS-side (see js/timer_globals.js) until now;
+        # fetching it also clears it.
+        def 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # The WHATWG event loop over two queues that live in different places: the
+      # engine's promise-job queue (drained through the Backend) and Dommy's
+      # deterministic scheduler (the window's, driven by virtual time).
+      #
+      # The three entry points differ ONLY in how far they are willing to move
+      # the clock, so they share one pump and supply that policy as a block:
+      #
+      #   #drive_due_now   not at all — whatever is due at this instant
+      #   #settle          to the next animation frame, but not to a later timer
+      #   #run_until_idle  to the next due timer, repeatedly, until none is left
+      #
+      # Also the place where a dead VM stops the loop: an out-of-memory poisons
+      # the VM, and per the "browsing never crashes" contract the failure is
+      # reported once and then swallowed, rather than escaping into a host that
+      # is only asking for microtasks to be drained.
+      class EventLoop
+        # How many due-now turns #drive_due_now takes before giving up. The
+        # nested-timer 4ms clamp guarantees due-now work drains in finite turns.
+        DUE_NOW_TURNS = 64
+
+        # Bounds a runaway timer loop (a self-rescheduling setInterval, an rAF
+        # that always asks for another frame).
+        DEFAULT_MAX_ITERATIONS = 1000
+
+        # `scheduler` is asked for Dommy's scheduler each time the loop runs,
+        # rather than handed one at construction: a Runtime is built before its
+        # window exists, and the window is the scheduler's owner. Keeping it a
+        # question avoids a second copy of the window living here.
+        #
+        # `on_halt` is called with the exception the first time the VM is found
+        # poisoned, and never again.
+        def initialize(backend, scheduler:, &on_halt)
+          @backend = backend
+          @scheduler = scheduler
+          @on_halt = on_halt
+          @halted = false
+        end
+
+        # Drain the engine's microtask queue. The one operation every policy
+        # starts from, and the one a host can ask for on its own.
+        def drain_microtasks
+          @backend.drain_microtasks
+        rescue ::Quickjs::RuntimeError => e
+          # The checkpoint hit out-of-memory and poisoned the VM. 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_halted(e)
+        end
+
+        # Everything 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 caller's await to surface).
+        def drive_due_now
+          pump(DUE_NOW_TURNS) do |scheduler|
+            scheduler.advance_time(0)
+            scheduler.next_due_timer_at == scheduler.now_ms
+          end
+          nil
+        end
+
+        # The work that is READY now: microtasks, timers already due
+        # (`setTimeout(0)` chains), and pending `requestAnimationFrame`
+        # callbacks, reached by advancing to their frame boundary. Does NOT jump
+        # the clock to a not-yet-due `setTimeout(300)` — that needs an explicit
+        # `advance_time(300)`. The "let promises and animation frames resolve"
+        # entry point.
+        def settle(max_iterations: DEFAULT_MAX_ITERATIONS)
+          pump(max_iterations) do |scheduler|
+            before = scheduler.now_ms
+            scheduler.advance_time(0) # due-now timers + microtasks, no clock jump
+            # Not redundant with the pump's own drains: a timer that just ran may
+            # have queued the microtask that schedules the next animation frame,
+            # and the check below has to see it.
+            drain_microtasks
+
+            frame_at = scheduler.next_animation_frame_at
+            if frame_at && frame_at > scheduler.now_ms
+              scheduler.advance_time(frame_at - scheduler.now_ms) # advance to the frame, run rAF
+              next true
+            end
+
+            scheduler.now_ms != before # quiescent once the clock stops moving
+          end
+        end
+
+        # Quiescence: drain, advance to the next due timer, drain again, until no
+        # timer is pending. The deterministic "settle everything" a host uses
+        # after an eval — every queued microtask runs and every scheduled timer
+        # fires, in WHATWG order (microtasks before each timer).
+        def run_until_idle(max_iterations: DEFAULT_MAX_ITERATIONS)
+          pump(max_iterations) do |scheduler|
+            next_at = scheduler.next_due_timer_at
+            next false unless next_at
+
+            scheduler.advance_time(next_at - scheduler.now_ms)
+            true
+          end
+        end
+
+        # Record a halt if the VM is in fact dead, and say whether it was. The
+        # caller (a timer callback that raised) does not have to ask the backend
+        # itself: an out-of-memory there poisons the whole VM, not just that one
+        # callback.
+        def note_halted_if_poisoned(error)
+          return false unless @backend.poisoned?
+
+          note_halted(error)
+          true
+        end
+
+        private
+
+        # The VM is poisoned. Surface the failure ONCE (a repeated drain would
+        # otherwise report it every tick) so the host sees that the page's
+        # JavaScript stopped, then leave it to the no-op guards.
+        def note_halted(error)
+          return if @halted
+
+          @halted = true
+          @on_halt&.call(error)
+          nil
+        end
+
+        # Drain, then let the policy move the clock; stop when it reports there
+        # is nothing left to do, when there is no scheduler to drive, or when the
+        # iteration bound runs out.
+        def pump(max_iterations)
+          scheduler = @scheduler.call
+          max_iterations.times do
+            drain_microtasks
+            break unless scheduler
+            break unless yield(scheduler)
+
+            drain_microtasks
+          end
+          self
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/quickjs/js/browser_globals.js

@@ -0,0 +1,36 @@
+// The bare browser globals frameworks reach for, aliased onto the installed
+// window. This is what lets real frontend bundles (Turbo, …) run unmodified.
+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;
+// `frames` is the window itself, indexable by child-frame number
+// (`frames[0]` === the first <iframe>'s contentWindow).
+globalThis.frames = window;
+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) {}
+}

data/lib/dommy/js/quickjs/js/error_rebuild.js

@@ -0,0 +1,22 @@
+// Rebuild a thrown value as a real Error inside the realm.
+//
+// QuickJS raises a HOST exception when an evaluated script throws, so by the
+// time Ruby sees it the JS value is gone: its name, message and frames survive
+// as a Ruby exception, the object itself does not. The page is handed an
+// equivalent built here instead, so a handler reading `.message` / `.stack`
+// gets what it threw rather than an object with no properties.
+//
+// `name` is the constructor to use (`TypeError`, …), falling back to `Error`
+// for anything the realm does not define. `stack` is already filtered to the
+// frames that came from JS — the host's own are not the page's business.
+//
+// The result is tagged for the bridge here rather than at the call site, so
+// crossing back to Ruby carries the object rather than flattening it.
+globalThis.__rbDommyRebuildError = function (name, message, stack) {
+  var Ctor = globalThis[name];
+  var error = new (typeof Ctor === "function" ? Ctor : Error)(message);
+  if (stack) {
+    try { error.stack = stack; } catch (_) {}
+  }
+  return __rbHost.tag(error);
+};

data/lib/dommy/js/quickjs/js/intl_polyfill.js

@@ -0,0 +1,56 @@
+// 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.
+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;
+}