dommy 0.12.0 → 0.14.0

data/lib/dommy/bridge.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
 module Dommy
-  # `Dommy::Bridge` — adapter classes for JS-style bridges (wasm
-  # embedders that route DOM method calls and constructor `new` ops
-  # through the `__js_get__` / `__js_set__` / `__js_call__` /
-  # `__js_new__` protocol).
+  # `Dommy::Bridge` — the protocol every JS host speaks to Dommy, and the
+  # vocabulary the DOM answers it in.
   #
-  # CRuby users writing happy-dom-style tests can ignore everything
-  # in this namespace; it's only relevant when integrating Dommy
-  # with an external runtime (such as an mruby-on-wasm host) that
-  # constructs callbacks / events / promises via the bridge view.
+  # THE RULE, because it has drifted before: what is true of ANY host belongs
+  # here; what is true of the host we happen to ship belongs in `Dommy::Js`.
+  # So the sentinels, the value types that cross the boundary, the exceptions
+  # a spec mandates and the wire tags are Bridge's, while the engine ABI, the
+  # marshaller that reads those tags and the QuickJS-facing runtime are Js's.
+  #
+  # This namespace is NOT optional or embedder-only, whatever an older version
+  # of this comment claimed: `Bridge::UNDEFINED` and `Bridge::Methods` are
+  # spoken by most of the DOM classes in this gem. A backend gem (dommy-js-
+  # quickjs, a future wasm one) depends on Bridge; nothing in the DOM depends
+  # on Js.
   #
   # The protocol contract:
   #   - `__js_get__(name)` reads a JS-style property by string name
@@ -17,233 +22,13 @@ module Dommy
   #   - `__js_call__(method, args)` invokes a method with positional
   #     args (Array)
   #   - `__js_new__(args)` invokes the value as a JS constructor
-  module Bridge
-    # Sentinel returned by `__js_set__` when a key is not a known DOM property
-    # (so the JS host can keep it as a JS-side expando, preserving identity)
-    # rather than silently dropping it.
-    UNHANDLED = :__js_unhandled__
-
-    # Sentinel for the JS `undefined` value, used in both directions:
-    #   - a `__js_call__` returns it for a void (undefined-returning) op, so the
-    #     host marshals JS `undefined` rather than the `null` a bare Ruby `nil`
-    #     would (e.g. DOMTokenList add/remove return undefined);
-    #   - a top-level JS `undefined` *argument* arrives as it (whereas JS `null`
-    #     arrives as `nil`), so WebIDL-style dispatch can tell an omitted optional
-    #     argument from an explicit null.
-    # Its `to_s` is "undefined" so a DOMString coercion of a stray undefined is
-    # still spec-faithful.
-    UNDEFINED = Object.new
-    def UNDEFINED.to_s = "undefined"
-    def UNDEFINED.inspect = "#<Dommy::Bridge::UNDEFINED>"
-    UNDEFINED.freeze
-
-    # The sentinel a `__js_get__` returns for a GENUINELY-ABSENT property (a key
-    # the object does not have), as distinct from a present property whose value
-    # is `nil`/JS null or `UNDEFINED`/JS undefined. It marshals to JS `undefined`
-    # for the value, but the proxy reports `("x" in obj) === false` for it — so
-    # feature detection like `isUndefined(window.Vue)` AND `"Vue" in window` are
-    # both correct. (UNDEFINED means present-but-undefined → reported present.)
-    ABSENT = Object.new
-    def ABSENT.to_s = "undefined"
-    def ABSENT.inspect = "#<Dommy::Bridge::ABSENT>"
-    ABSENT.freeze
-
-    # An opaque handle to a JS-side value that Ruby only stores and hands back
-    # (an AbortSignal's reason, a CustomEvent's detail). A non-plain JS object
-    # (Error, class instance, …) crosses as one of these instead of being
-    # flattened to a Hash, so it round-trips with IDENTITY preserved. `to_s`
-    # exposes the captured JS string form for the rare Ruby consumer that needs
-    # text (e.g. building a message).
-    class JSValue
-      attr_reader :ref
-
-      def initialize(ref, label = nil)
-        @ref = ref
-        @label = label
-      end
-
-      def to_s = (@label || "[object]").to_s
-      def inspect = "#<Dommy::Bridge::JSValue #{to_s}>"
-    end
-
-    # Raised by a host method that must throw an ARBITRARY value back to JS —
-    # not a DOMException/Error, but e.g. `signal.throwIfAborted()` throwing the
-    # exact abort reason (a string, number, or opaque JSValue). The bridge
-    # re-throws the wrapped value verbatim (identity preserved). Subclasses
-    # RuntimeError (with the value's string form as the message) so standalone
-    # CRuby callers still see a normal `raise`-able error.
-    class ThrowValue < RuntimeError
-      attr_reader :value
-
-      def initialize(value)
-        @value = value
-        super(value.to_s)
-      end
-    end
-
-    # A byte buffer that crosses the JS boundary as a `Uint8Array` (rather than a
-    # plain Array). Wrap a host method's byte-array result in this so JS sees a
-    # real typed array — e.g. `TextEncoder#encode`, `Blob#arrayBuffer`. The
-    # reverse direction (a JS ArrayBuffer/TypedArray argument) arrives as a
-    # `Bytes` too. It subclasses Array so plain-Array callers (and `== [..]`
-    # comparisons) keep working; only the bridge treats it specially.
-    class Bytes < ::Array
-      def initialize(bytes = [])
-        super()
-        concat(Array(bytes).map { |b| b.to_i & 0xFF })
-      end
-
-      alias bytes to_a
-      def pack_bytes = pack("C*")
-    end
-
-    # Like `Bytes`, but crosses the JS boundary as a bare `ArrayBuffer` rather
-    # than a `Uint8Array` view. Use this for the spec methods whose return type
-    # is `ArrayBuffer` — `Response`/`Blob`/`FileReader`/`XMLHttpRequest`'s
-    # `arrayBuffer`. Subclasses `Bytes` so Ruby-level `== [..]` comparisons still
-    # hold; only the bridge distinguishes it (and must check it before `Bytes`).
-    class ArrayBuffer < Bytes
-    end
-
-    # A Ruby-side signal that the JS boundary should surface a JS `TypeError`
-    # (not a `DOMException`). Some WebIDL operations — notably the `URL`
-    # constructor and its `href` setter — throw `TypeError` on failure rather
-    # than a DOMException; raising this lets a host bridge rethrow the correct
-    # JS error type, while Ruby callers can still rescue it like any other
-    # error. Kept distinct from Ruby's built-in `::TypeError` so a host can map
-    # only deliberate, spec-mandated TypeErrors (and not mask genuine Ruby type
-    # bugs) across the boundary.
-    class TypeError < ::StandardError; end
-
-    # Like `Bridge::TypeError`, but for spec-mandated `RangeError`s (e.g. the
-    # `Response` constructor rejecting a status outside 200–599). A host bridge
-    # rethrows a real JS `RangeError`; kept distinct from Ruby's `::RangeError`.
-    class RangeError < ::StandardError; end
-
-    # Wraps an external callback handle (registered in a host-side
-    # callback table) so the JS bridge can resolve / invoke it. The
-    # external host that creates these is responsible for honoring
-    # `invoke_callback(callback_id, args)`.
-    #
-    # The `__callback_id__` key on this object exposes the integer
-    # id to JS-side code that needs to round-trip it (e.g. for
-    # release / introspection).
-    class Callback
-      ID_KEY = "__callback_id__"
-
-      def initialize(host, callback_id)
-        @host = host
-        @callback_id = callback_id
-        @props = {}
-      end
-
-      def __js_get__(key)
-        if key == ID_KEY
-          @props.fetch(key, @callback_id)
-        else
-          @props[key]
-        end
-      end
-
-      def __js_set__(key, value)
-        @props[key] = value
-        nil
-      end
-
-      def __js_call__(method, args)
-        case method
-        when "call"
-          @host.invoke_callback(@callback_id, args)
-        end
-      end
-    end
-
-    # Block-as-constructor adapter — invoking `__js_new__(args)`
-    # calls the wrapped block with `args` and returns whatever the
-    # block produces. Used by Window to wire up `new Event(init)`,
-    # `new CustomEvent(init)`, etc. without hand-rolling a class
-    # for each constructor.
-    class Constructor
-      def initialize(&block)
-        @block = block
-        @class_methods = {}
-      end
-
-      def __js_new__(args)
-        @block.call(args)
-      end
-
-      # Register a class-level method (e.g. `URL.createObjectURL`)
-      # that JS bridges resolve via `__js_call__` on the constructor
-      # itself. Returns self for chaining.
-      def define_class_method(name, &block)
-        @class_methods[name.to_s] = block
-        self
-      end
-
-      def __js_call__(method, args)
-        handler = @class_methods[method.to_s]
-        handler&.call(args)
-      end
-
-      # Names of the registered class-level (static) methods, so a JS host can
-      # expose them on the constructor function (e.g. `URL.createObjectURL`).
-      def __js_class_method_names__
-        @class_methods.keys
-      end
-    end
-
-    # `JS.global[:Promise]` view. Implements the `resolve` / `reject`
-    # class methods plus `new Promise(executor)` via `__js_new__`.
-    class PromiseConstructor
-      def initialize(window)
-        @window = window
-      end
-
-      def __js_call__(method, args)
-        case method
-        when "resolve"
-          PromiseValue.resolve(@window, args[0])
-        when "reject"
-          PromiseValue.reject(@window, args[0])
-        end
-      end
-
-      # `new Promise(executor)` — runs executor synchronously with
-      # (resolve, reject) callbacks.
-      def __js_new__(args)
-        executor = args[0]
-        promise = PromiseValue.new(@window)
-        resolve = PromiseSettler.new(promise, fulfilled: true)
-        reject = PromiseSettler.new(promise, fulfilled: false)
-        if executor.respond_to?(:__js_call__)
-          executor.__js_call__("call", [resolve, reject])
-        elsif executor.respond_to?(:call)
-          executor.call(resolve, reject)
-        end
-
-        promise
-      end
-    end
-
-    # Adapter so a Ruby-side executor can deliver resolve/reject
-    # through the same `__js_call__("call", args)` interface that
-    # the scheduler and JS bridge use for callbacks.
-    class PromiseSettler
-      def initialize(promise, fulfilled:)
-        @promise = promise
-        @fulfilled = fulfilled
-      end
-
-      def __js_call__(_method, args)
-        if @fulfilled
-          @promise.fulfill(args[0])
-        else
-          @promise.reject(args[0])
-        end
-
-        nil
-      end
-    end
-  end
+  #
+  # The pieces are one file each, by what they are — see the requires below.
+  module Bridge; end
 end
+
+require_relative "bridge/sentinels"
+require_relative "bridge/values"
+require_relative "bridge/errors"
+require_relative "bridge/constructor"
+require_relative "bridge/wire_tags"

data/lib/dommy/browser.rb

@@ -23,24 +23,14 @@ module Dommy
     # settle before the next line.
     include Dommy::Interaction::Driver
 
-    # Raised in strict mode when JS errors were collected and not acknowledged.
-    class JsError < StandardError
-      attr_reader :causes
+    attr_reader :window, :runtime, :console
 
-      def initialize(causes)
-        @causes = causes
-        super(build_message(causes))
-      end
-
-      private
-
-      def build_message(causes)
-        lines = causes.map { |e| "  #{e.class}: #{e.message}" }
-        "#{causes.length} uncaught JS error(s):\n#{lines.join("\n")}"
-      end
-    end
+    # The ledger of errors the page left unhandled (`Dommy::Js::ErrorLog`);
+    # shared with the other hosts so strict mode behaves the same everywhere.
+    attr_reader :error_log
 
-    attr_reader :window, :runtime, :js_errors, :console
+    # The errors themselves, as a browser console's scrollback.
+    def js_errors = @error_log.errors
 
     # Build a browser and (unless `execute_scripts: false`) boot its scripts. In
     # block form the browser is yielded and disposed afterward, returning the
@@ -72,18 +62,15 @@ module Dommy
       wasm_memory_shim: false, backend: nil, navigable: false, same_origin: false)
       @resources = resources
       @same_origin = same_origin
-      @strict = strict
       @backend = backend
       @execute_scripts = execute_scripts
       @settle_after_boot = settle
       @wasm_memory_shim = wasm_memory_shim
       @navigable = navigable
-      @js_errors = []
+      @error_log = Js::ErrorLog.new(strict: strict)
       @console = []
-      @acknowledged = 0
-      @allow_errors = false
       @disposed = false
-      @pending_navigation = nil
+      @pending_navigations = []
       @runtime = nil
 
       @window = Dommy.parse(html)
@@ -117,7 +104,7 @@ module Dommy
     def visit(url, replace: false)
       raise "browser is not navigable (use Browser.visit or navigable: true)" unless @navigable
 
-      @pending_navigation = {url: url.to_s, method: "GET", source: :visit, replace: replace}
+      @pending_navigations << {url: url.to_s, method: "GET", source: :visit, replace: replace}
       flush_navigation!
       self
     end
@@ -141,14 +128,61 @@ module Dommy
     # inside a script), record it and perform the fetch + swap at the next drain
     # boundary (settle / after_interaction / advance_time). Ruby-initiated visits
     # flush immediately since no JS is on the stack.
-    def navigate(url:, source:, method: "GET", body: nil, params: nil, enctype: nil, headers: {}, replace: false)
-      @pending_navigation = {
+    def navigate(url:, source:, method: "GET", body: nil, params: nil, enctype: nil, target: nil, headers: {}, replace: false)
+      # A target that names an iframe in this document navigates that nested
+      # browsing context. It can be performed now — it does not replace the top
+      # realm — with only the frame's `load` deferred to a microtask, so a
+      # listener installed right after `form.submit()` is registered first.
+      frame = @navigable ? resolve_target_frame(target) : nil
+      if frame
+        navigate_frame(frame,
+          {method: method, url: url, params: params, body: body, enctype: enctype, headers: headers},
+          resolve_against_current(url.to_s))
+        @window.scheduler.queue_microtask(proc { frame.dispatch_event(Dommy::Event.new("load")) })
+        return nil
+      end
+
+      @pending_navigations << {
         url: url, method: method, body: body, params: params, enctype: enctype,
-        headers: headers, replace: replace, source: source
+        target: target, headers: headers, replace: replace, source: source
       }
       nil
     end
 
+    # A navigation delegate for an embedder-managed nested browsing context (an
+    # iframe whose content document the host injected). A navigation from inside
+    # that document loads into the frame itself.
+    class FrameNavigationDelegate
+      def initialize(browser, frame)
+        @browser = browser
+        @frame = frame
+      end
+
+      def navigate(url:, source:, method: "GET", body: nil, params: nil, enctype: nil, target: nil, headers: {}, replace: false)
+        @browser.__internal_load_frame__(@frame,
+          {url: url, method: method, body: body, params: params, enctype: enctype, headers: headers})
+      end
+
+      def traverse(_delta) = nil
+    end
+
+    def frame_navigation_delegate(frame) = FrameNavigationDelegate.new(self, frame)
+
+    # Load `nav` into `frame`, resolving the URL against the frame's own document,
+    # then fire the frame's `load`. Public (an `__internal_` seam) so a host that
+    # injected the frame's content document can wire it as that frame's delegate.
+    def __internal_load_frame__(frame, nav)
+      base = frame.content_window&.location&.__js_get__("href").to_s
+      resolved = begin
+        URI.join(base, nav[:url].to_s).to_s
+      rescue URI::InvalidURIError, ArgumentError
+        nav[:url].to_s
+      end
+      navigate_frame(frame, nav, resolved)
+      frame.dispatch_event(Dommy::Event.new("load"))
+      nil
+    end
+
     # A cross-document history traversal. Ruby-initiated (back / forward), so it
     # runs immediately: a same-document target (its window is still live)
     # traverses in place (popstate); a document-boundary target is re-fetched.
@@ -238,22 +272,19 @@ module Dommy
 
     # Suppress strict-mode failure for JS errors raised inside the block (they
     # stay collected in #js_errors for inspection). For tests that expect errors.
-    def allow_js_errors
-      prev = @allow_errors
-      @allow_errors = true
-      yield
-    ensure
-      @allow_errors = prev
-      @acknowledged = @js_errors.length
+    def allow_js_errors(&block)
+      @error_log.allow(&block)
     end
 
+    # Tear the realm down, then fail on anything the page left unhandled and
+    # nobody has reported. Disposing first means the failure cannot leave a live
+    # VM behind.
     def dispose
       return if @disposed
 
       @disposed = true
-      pending = unacknowledged
       @runtime&.dispose
-      raise JsError, pending if @strict && !pending.empty?
+      @error_log.check!(context: current_url)
     end
 
     private
@@ -268,8 +299,19 @@ module Dommy
       # The JS engine is pluggable: `@backend` selects a registered runtime
       # (nil → the configured default, QuickJS when dommy-js-quickjs is loaded).
       runtime = Js.build_runtime(@backend)
-      runtime.on_unhandled_rejection { |err| @js_errors << err }
-      runtime.on_callback_error { |err| @js_errors << err } if runtime.respond_to?(:on_callback_error)
+      # Every uncaught error the page produces goes through the window's
+      # "report an exception" / "notify about rejected promises" funnel, and only
+      # what the page left unhandled lands here. A page that installs its own
+      # `window.onerror` / `unhandledrejection` handler and cancels the event
+      # suppresses the failure, exactly as it would in a browser.
+      window.__internal_on_unhandled_error__ { |err| @error_log.record(err) }
+      # A rejection the page handled after we reported it is retracted, so it
+      # stops failing anything (WHATWG `rejectionhandled`).
+      window.__internal_on_rejection_handled__ { |record| @error_log.retract(record) }
+      runtime.on_unhandled_rejection { |err| report_rejection(window, err) }
+      if runtime.respond_to?(:on_callback_error)
+        runtime.on_callback_error { |err| Internal::ExceptionReport.report_at(window, err) }
+      end
       runtime.on_log { |log| @console << log }
       runtime.define_host_object("document", window.document)
       runtime.install_window(window)
@@ -285,24 +327,35 @@ module Dommy
       # Installed whenever a runtime is attached — an embedder that drives script
       # boot itself (`execute_scripts: false`) still needs inline handlers wired.
       doc.inline_handler_wirer = lambda do
-        Js::ScriptBoot.wire_inline_handlers(runtime, on_error: ->(e) { @js_errors << e })
+        Js::ScriptBoot.wire_inline_handlers(runtime, on_error: ->(e) { @error_log.record(e) })
       end
       return unless @execute_scripts
 
+      # `on_error:` here is only the windowless fallback — a booted document has
+      # a window, so a throwing script reports through it (see ScriptBoot).
+
       # Dynamically-inserted `<script src>` (webpack/Vite on-demand chunks)
       # fetch + run through the same resources adapter, after boot.
       doc.external_script_runner = lambda do |element, src|
         Js::ScriptBoot.run_external_script(runtime, doc, element, src,
-          resources: @resources, on_error: ->(e) { @js_errors << e })
+          resources: @resources, on_error: ->(e) { @error_log.record(e) })
       end
       Js::ScriptBoot.run_document_scripts(
-        runtime, doc, resources: @resources, on_error: ->(e) { @js_errors << e }
+        runtime, doc, resources: @resources, on_error: ->(e) { @error_log.record(e) }
       )
       # Leave the page in a ready state: run on-load promises, due-now timers,
       # and rAF (not future timers). `settle: false` observes it mid-flight.
       runtime.settle if @settle_after_boot
     end
 
+    # Route an unhandled promise rejection through the page's own
+    # `unhandledrejection` handling first. The engine decides WHEN a rejection
+    # counts as unhandled (see Window#__internal_report_rejection__).
+    def report_rejection(window, error)
+      value = Internal::ExceptionReport.error_value(error)
+      window.__internal_report_rejection__(value, host_error: error)
+    end
+
     # Perform a recorded navigation: fetch the target (following redirects),
     # fire the old document's unload, then replace the Window + JS realm with the
     # freshly parsed document and update the joint history. A network miss or a
@@ -310,8 +363,16 @@ module Dommy
     MAX_META_REFRESHES = 20
 
     def perform_navigation!(nav, rebind: false, refresh_depth: 0)
+      # A form's action is a document-relative URL; resolve it against the
+      # current address (links already arrive resolved via Location).
+      resolved = resolve_against_current(nav[:url].to_s)
+      # A `target` naming an iframe in this document navigates that nested
+      # browsing context instead of replacing the top-level page.
+      frame = resolve_target_frame(nav[:target])
+      return navigate_frame(frame, nav, resolved) if frame
+
       response, final_url = @fetcher.request(
-        method: nav[:method] || "GET", url: nav[:url], params: nav[:params],
+        method: nav[:method] || "GET", url: resolved, params: nav[:params],
         body: nav[:body], enctype: nav[:enctype], headers: nav[:headers] || {}
       )
       return unless response&.success? && document_response?(response)
@@ -337,6 +398,53 @@ module Dommy
       follow_meta_refresh!(refresh_depth)
     end
 
+    # The reserved browsing-context keywords; anything else names an iframe.
+    RESERVED_TARGETS = %w[_self _top _parent _blank].freeze
+
+    # The iframe a `target` names in the current document, or nil when the
+    # target is empty / a reserved keyword / names no frame (then the navigation
+    # is top-level, the only context Dommy models).
+    def resolve_target_frame(target)
+      name = target.to_s
+      return nil if name.empty? || RESERVED_TARGETS.include?(name.downcase)
+
+      @window.document.query_selector_all("iframe").find do |frame|
+        frame.get_attribute("name").to_s == name
+      end
+    end
+
+    # Load a navigation into a nested browsing context (a named iframe): fetch
+    # it, install the response document as the frame's content, and fire the
+    # frame's `load`. The top-level window and joint history are left alone.
+    def navigate_frame(frame, nav, resolved_url)
+      response, final_url = @fetcher.request(
+        method: nav[:method] || "GET", url: resolved_url, params: nav[:params],
+        body: nav[:body], enctype: nav[:enctype], headers: nav[:headers] || {}
+      )
+      return unless response&.success?
+
+      sub_window = frame_document_for(response)
+      sub_window.location.__internal_set_url__(final_url)
+      # A navigation from inside the loaded frame also stays in that frame.
+      sub_window.navigation_delegate = frame_navigation_delegate(frame)
+      # A nested realm needs the seeded constructors to run the response's
+      # scripts; a runtime that cannot expose them simply runs without them.
+      @runtime.expose_constructors_on(sub_window) if @runtime.respond_to?(:expose_constructors_on)
+      frame.__internal_set_content_document__(sub_window.document)
+      nil
+    end
+
+    # The document a frame shows for a response: HTML/XML is parsed as-is; a
+    # non-document response (e.g. text/plain from an echo endpoint) is displayed
+    # as text, so the frame gets a document whose body holds it.
+    def frame_document_for(response)
+      return Dommy.parse(response.body) if document_response?(response)
+
+      win = Dommy.parse("<!doctype html><html><head></head><body></body></html>")
+      win.document.body.text_content = response.body.to_s.dup.force_encoding(Encoding::UTF_8)
+      win
+    end
+
     # If the freshly loaded document asks for an immediate `<meta http-equiv=
     # refresh>`, follow it (as a replace, like a redirect), capped so a page that
     # refreshes to itself can't loop forever.
@@ -377,12 +485,11 @@ module Dommy
     # the swap never runs with the outgoing realm's JS on the stack.
     def flush_navigation!
       return unless @navigable
+      return if @pending_navigations.empty?
 
-      nav = @pending_navigation
-      return unless nav
-
-      @pending_navigation = nil
-      perform_navigation!(nav)
+      navs = @pending_navigations
+      @pending_navigations = []
+      navs.each { |nav| perform_navigation!(nav) }
     end
 
     def fire_unload(window)
@@ -400,8 +507,6 @@ module Dommy
       content_type.empty? || content_type.include?("html") || content_type.include?("xml")
     end
 
-    def unacknowledged = @js_errors[@acknowledged..] || []
-
     def submit_button?(button)
       if button.tag_name == "BUTTON"
         button.type == "submit"
@@ -410,18 +515,10 @@ module Dommy
       end
     end
 
-    # In strict mode, fail on any JS error collected since the last
-    # acknowledgement. Marks all current errors acknowledged so each is reported
-    # at most once.
+    # In strict mode, fail on anything the page left unhandled since the last
+    # checkpoint. The ledger drains itself, so each error is reported once.
     def check_js_errors!
-      return if @allow_errors
-      return unless @strict
-
-      pending = unacknowledged
-      return if pending.empty?
-
-      @acknowledged = @js_errors.length
-      raise JsError, pending
+      @error_log.check!(context: current_url)
     end
   end
 end

data/lib/dommy/callable_invoker.rb

@@ -20,6 +20,22 @@ module Dommy
       end
     end
 
+    # Invoke `callback` so a JS throw SURFACES as a Ruby exception instead of
+    # being swallowed by the bridge. WHATWG requires a task's exception to be
+    # reported at the global ("report an exception") rather than silently
+    # dropped, so the entry points that own a task — a timer / rAF callback —
+    # invoke this form and report whatever comes out. The plain `invoke` keeps
+    # the swallowing behavior for callers that handle their own errors.
+    def invoke_raising(callback, *args)
+      return if callback.nil?
+
+      if callback.respond_to?(:__js_invoke__)
+        callback.__js_invoke__(args, raising: true)
+      else
+        invoke(callback, *args)
+      end
+    end
+
     # Invoke a DOM event listener per the EventTarget rule: an object with
     # `handle_event`, else a Ruby callable, else a JS-bridged callable (tried in
     # that order). A JS function listener's `this` must be the event's