dommy 0.13.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,246 +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
-
-      # `stack_frames` are the value's JS stack, when the tag that crossed
-      # carried one. Ruby cannot reach through a ref to read `.stack`, so an
-      # error-shaped value brings its frames with it (see host_runtime.js
-      # tagValue) and reporting uses them for the source position.
-      attr_reader :stack_frames
-
-      # The value's JS constructor name, when the tag carried one.
-      attr_reader :js_name
-
-      def initialize(ref, label = nil, stack_frames = nil, js_name = nil)
-        @ref = ref
-        @label = label
-        @stack_frames = stack_frames
-        @js_name = js_name
-      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
-
-      # `message` overrides the value's string form, for a caller that can say
-      # more about it than `to_s` can (a JS error's kind, say).
-      def initialize(value, message = nil)
-        @value = value
-        super(message || 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

@@ -70,7 +70,7 @@ module Dommy
       @error_log = Js::ErrorLog.new(strict: strict)
       @console = []
       @disposed = false
-      @pending_navigation = nil
+      @pending_navigations = []
       @runtime = nil
 
       @window = Dommy.parse(html)
@@ -104,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
@@ -128,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.
@@ -316,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)
@@ -343,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.
@@ -383,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)