dommy 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab840b2c863131b5f20d7be40f28028bec227fb490688b4b0f26157058c0ea68
-  data.tar.gz: a87acf4824167a08eae696de0ffe504cdf808d9085176e084b3e4f3d225e5c7a
+  metadata.gz: 52933caebd00a8d1b7dcfa14421116be45617e04d53ee6f8d8771c5fc5ccefdc
+  data.tar.gz: da2372f52dac931a6e7ad4316ec4cb15efb0effa799229eae7bde1435b8aa3c8
 SHA512:
-  metadata.gz: db29082c6b8b686eb762aa53f3ae213b40da69210732c99a53f15a1f18318a326fd6bcf4c65fcfa4abc27dc41bebff0b16164682b7d18e7fed7a44415a9bb7e6
-  data.tar.gz: 71669401a09832106ec301e0b2d4747fb7782b2ac2514fbf4cfbf625358695f0c498561cbd3efb565b7b2abbaf43b4b2068dbe5f1831523a74ec25dc2c2e1435
+  metadata.gz: e05358f558f5e84fe6da7e7f705dbdc5bdd178646ef71a3ee9311a9d05893320cda1c0e6ca3596aa05e7e389e9112e96c8d44b640b7dea55480066af40e65eb7
+  data.tar.gz: ac0dea6fecd2fe7624f71cdef6f9eab786be60a584a4307d0fcac66540002de7cc1cc52812a638bfc8bb35afb53dd836ed7ebb2b007fee8fabfd172e62e8850a

data/lib/dommy/attr.rb

@@ -22,9 +22,12 @@ module Dommy
       nil
     end
 
-    def initialize(name, owner: nil, value: "", namespace_uri: nil, prefix: nil, local_name: nil)
+    def initialize(name, owner: nil, value: "", namespace_uri: nil, prefix: nil, local_name: nil, document: nil)
       qname = name.to_s
       @owner = owner
+      # The node document (for baseURI/ownerDocument when detached from an
+      # element). Owned attrs derive it from their owner instead.
+      @document = document
       @detached_value = value.to_s
       if namespace_uri && !namespace_uri.to_s.empty?
         # Namespaced attributes preserve case and carry prefix / localName.
@@ -50,6 +53,22 @@ module Dommy
       @owner
     end
 
+    # Node.baseURI — the node document's base URL. Derived from the owner
+    # element when attached, else the document the attr was created in.
+    def base_uri
+      return @owner.base_uri if @owner.respond_to?(:base_uri)
+
+      @document&.base_uri
+    end
+
+    # Node.ownerDocument — the owner element's current document when attached (so
+    # it follows the element across adoptNode), else the creation document.
+    def owner_document
+      return @owner.document if @owner.respond_to?(:document)
+
+      @document
+    end
+
     def value
       if @owner
         if @namespace_uri
@@ -89,6 +108,8 @@ module Dommy
         value
       when "ownerElement"
         @owner
+      when "ownerDocument"
+        owner_document
       when "localName"
         @local_name
       when "namespaceURI"
@@ -97,6 +118,8 @@ module Dommy
         @prefix
       when "nodeType"
         2
+      when "baseURI"
+        base_uri
       when "specified"
         # Legacy/useless attribute — always true (WHATWG DOM).
         true
@@ -119,12 +142,20 @@ module Dommy
     include Bridge::Methods
     js_methods %w[cloneNode isSameNode getRootNode hasChildNodes normalize compareDocumentPosition
       appendChild insertBefore removeChild replaceChild
+      lookupNamespaceURI lookupPrefix isDefaultNamespace
       addEventListener removeEventListener dispatchEvent]
     def __js_call__(method, args)
       case method
+      when "lookupNamespaceURI"
+        lookup_namespace_uri(args[0])
+      when "lookupPrefix"
+        lookup_prefix(args[0])
+      when "isDefaultNamespace"
+        is_default_namespace(args[0])
       when "cloneNode"
         Attr.new(@name, owner: nil, value: value,
-                        namespace_uri: @namespace_uri, prefix: @prefix, local_name: @local_name)
+                        namespace_uri: @namespace_uri, prefix: @prefix, local_name: @local_name,
+                        document: @document || (@owner.respond_to?(:document) ? @owner.document : nil))
       when "isSameNode"
         is_same_node(args[0])
       when "getRootNode"
@@ -209,7 +240,9 @@ module Dommy
     end
 
     def get_named_item(name)
-      key = name.to_s.downcase
+      # getNamedItem / getAttribute lowercase the qualified name only for an HTML
+      # element in an HTML document; other elements match case-sensitively.
+      key = @element.__internal_normalize_attr_key__(name)
       node = Backend.attribute_nodes(@element.__dommy_backend_node__).find do |a|
         Backend.attribute_ns_info(a)[:qualified_name] == key
       end
@@ -221,7 +254,7 @@ module Dommy
     end
 
     def remove_named_item(name)
-      key = name.to_s.downcase
+      key = @element.__internal_normalize_attr_key__(name)
       node = Backend.attribute_nodes(@element.__dommy_backend_node__).find do |a|
         Backend.attribute_ns_info(a)[:qualified_name] == key
       end
@@ -329,12 +362,17 @@ module Dommy
       end
     end
 
-    # WebIDL "supported property names" for NamedNodeMap: the qualified name of
-    # each attribute, in order (the indexed names are reflected separately).
+    # WebIDL "supported property names" for NamedNodeMap: each attribute's
+    # qualified name, in order with duplicates omitted (the indexed names are
+    # reflected separately). For an HTML element in an HTML document, names
+    # containing an ASCII upper alpha are excluded (they can't be reached by the
+    # case-insensitive named getter).
     def __js_named_props__
-      Backend.attribute_nodes(@element.__dommy_backend_node__).map do |a|
+      names = Backend.attribute_nodes(@element.__dommy_backend_node__).map do |a|
         Backend.attribute_ns_info(a)[:qualified_name]
-      end
+      end.uniq
+      names.reject! { |n| n.match?(/[A-Z]/) } unless @element.__internal_case_sensitive_attribute_names__?
+      names
     end
 
     include Bridge::Methods

data/lib/dommy/backend/makiri_adapter.rb

@@ -21,6 +21,7 @@ module Dommy
       CDATASection = ::Makiri::CDATASection
       ProcessingInstruction = ::Makiri::ProcessingInstruction
       DocumentFragment = ::Makiri::DocumentFragment
+      DocumentType = ::Makiri::DocumentType
       Node = ::Makiri::Node
 
       # A minimal namespace wrapper exposing the same `href` API that Nokogiri's
@@ -168,6 +169,39 @@ module Dommy
         doc.create_element(name)
       end
 
+      # An XML-backed document rejects a qualified name that DOM allows (e.g.
+      # "f}oo" — an invalid char in the local part), so createElementNS uses
+      # Makiri's loose creator, which builds it verbatim (case/prefix preserved).
+      # nil for a non-XML backend → the caller uses the strict #create_element.
+      def create_element_loose(qualified_name, prefix, local, namespace, doc)
+        return nil unless doc.is_a?(::Makiri::XML::Document) && doc.respond_to?(:create_loose_dom_element)
+
+        doc.create_loose_dom_element(qualified_name, prefix, local, namespace)
+      end
+
+      # A detached DocumentType node owned by `doc`, for
+      # DOMImplementation.createDocumentType. Only the HTML backend ships the
+      # factory (`create_document_type`); nil signals the caller to fall back to a
+      # synthetic (non-tree) DocumentType. Raises ArgumentError for a name the
+      # factory rejects.
+      def create_document_type(name, public_id, system_id, doc)
+        return nil unless doc.respond_to?(:create_document_type)
+
+        doc.create_document_type(name.to_s, public_id.to_s, system_id.to_s)
+      end
+
+      # The parsed document's DocumentType node (`<!DOCTYPE …>`), or nil when the
+      # document declares none.
+      def internal_subset(doc)
+        doc.respond_to?(:internal_subset) ? doc.internal_subset : nil
+      end
+
+      # The backend class for a DocumentType node, so the wrapper routes it to
+      # Dommy::DocumentType (node-backed).
+      def document_type_class
+        ::Makiri::DocumentType
+      end
+
       def create_text(content, doc)
         doc.create_text_node(content)
       end

data/lib/dommy/backend.rb

@@ -130,6 +130,35 @@ module Dommy
         current.create_element(name, doc)
       end
 
+      # Create a namespaced element permitting a DOM-valid qualified name that a
+      # strict XML backend would reject (an internal invalid char like "f}oo"),
+      # preserving case/prefix. Returns nil when the backend has no loose path
+      # (fall back to #create_element); raises ArgumentError for a genuinely
+      # invalid name (the caller maps it to InvalidCharacterError).
+      def create_element_loose(qualified_name, prefix, local, namespace, doc)
+        current.create_element_loose(qualified_name, prefix, local, namespace, doc)
+      end
+
+      # A detached DocumentType node owned by `doc` (for
+      # DOMImplementation.createDocumentType). Returns nil when the backend has no
+      # doctype factory (the caller falls back to a synthetic DocumentType); raises
+      # ArgumentError for a name the factory rejects (the caller then also falls
+      # back, since createDocumentType is permissive).
+      def create_document_type(name, public_id, system_id, doc)
+        current.respond_to?(:create_document_type) ? current.create_document_type(name, public_id, system_id, doc) : nil
+      end
+
+      # The parsed document's DocumentType node, or nil when it declares none.
+      def internal_subset(doc)
+        current.respond_to?(:internal_subset) ? current.internal_subset(doc) : nil
+      end
+
+      # The backend class for a DocumentType node (nil if unsupported), so the
+      # wrapper cache can route it to Dommy::DocumentType.
+      def document_type_class
+        current.respond_to?(:document_type_class) ? current.document_type_class : nil
+      end
+
       def create_text(content, doc)
         current.create_text(content, doc)
       end

data/lib/dommy/blob.rb

@@ -21,19 +21,26 @@ module Dommy
     # Promises (they need a scheduler). A window-less Blob falls back to a
     # synchronous result, which `await` still handles.
     def initialize(parts = [], options = {}, window = nil)
+      # WebIDL: an omitted / `undefined` blobParts argument defaults to an empty
+      # sequence (`new Blob()` / `new Blob(undefined)` is a zero-length Blob), so
+      # it must not be coerced to the string "undefined".
+      parts = [] if parts.nil? || (defined?(Bridge::UNDEFINED) && parts.equal?(Bridge::UNDEFINED))
       parts = [parts] unless parts.is_a?(Array)
       @data = collect_bytes(parts)
       @size = @data.bytesize
-      raw_type = options["type"] || options[:type] || ""
-      @type = raw_type.to_s.downcase
+      raw_type = (options["type"] || options[:type] || "").to_s
+      # A type string with any code point outside U+0020..U+007E is discarded
+      # (→ ""); otherwise it is ASCII-lowercased (FileAPI "parse a MIME type"
+      # gate, applied to both the constructor and slice's contentType).
+      @type = raw_type.match?(/[^ -~]/) ? "" : raw_type.downcase
       @window = window
     end
 
     # Return a new Blob over a byte range of this one.
     # Negative indices are treated as offsets from the end (per spec).
     def slice(start = 0, last = @size, content_type = "")
-      s = clamp_index(start.to_i, @size)
-      e = clamp_index(last.to_i, @size)
+      s = clamp_index(clamp_long_long(start), @size)
+      e = clamp_index(clamp_long_long(last), @size)
       e = s if e < s
       Blob.new([@data.byteslice(s, e - s) || ""], {"type" => content_type.to_s}, @window)
     end
@@ -51,6 +58,13 @@ module Dommy
       Bridge::ArrayBuffer.new(@data.bytes)
     end
 
+    # Read the bytes as a Uint8Array (the spec return type). The DOM spec returns
+    # a Promise<Uint8Array>; Dommy is synchronous. `Bridge::Bytes` crosses the JS
+    # boundary as a Uint8Array (vs `ArrayBuffer` for #array_buffer).
+    def bytes
+      Bridge::Bytes.new(@data.bytes)
+    end
+
     # Raw binary bytes (Ruby ASCII-8BIT string). Used by FormData /
     # fetch when serializing multipart bodies.
     def __dommy_bytes__
@@ -71,17 +85,30 @@ module Dommy
     # Methods routed through __js_call__ (keep in sync with its when-arms).
     # File < Blob inherits these (it adds only properties).
     include Bridge::Methods
-    js_methods %w[slice text arrayBuffer]
+    js_methods %w[slice text arrayBuffer bytes]
     def __js_call__(method, args)
       case method
       when "slice"
-        slice(args[0] || 0, args[1] || @size, args[2] || "")
+        # An omitted / `undefined` start|end uses the default (0 / size); map
+        # UNDEFINED to nil so the `|| default` fallbacks apply (a bare UNDEFINED
+        # is truthy and has no #to_i). contentType is a plain DOMString: omitted
+        # / undefined → "" (default), but an explicit JS null coerces to "null".
+        a = args.map { |v| v.equal?(Bridge::UNDEFINED) ? nil : v }
+        ctype = if args.length < 3 || args[2].equal?(Bridge::UNDEFINED)
+          ""
+        else
+          args[2].nil? ? "null" : args[2].to_s
+        end
+        slice(a[0] || 0, a[1] || @size, ctype)
       when "text"
         # WHATWG: Blob.text() returns a Promise<string>.
         promise_or_value(text)
       when "arrayBuffer"
         # WHATWG: Blob.arrayBuffer() returns a Promise<ArrayBuffer>.
         promise_or_value(array_buffer)
+      when "bytes"
+        # WHATWG: Blob.bytes() returns a Promise<Uint8Array>.
+        promise_or_value(bytes)
       end
     end
 
@@ -115,6 +142,21 @@ module Dommy
       idx = length + idx if idx.negative?
       idx.clamp(0, length)
     end
+
+    # WebIDL `[Clamp] long long` conversion of a slice bound: a fractional value
+    # rounds to the nearest integer, ties to even (banker's rounding) — so
+    # `slice(1.5)` starts at 2 and `slice(3.5)` at 4, per the [Clamp] extended
+    # attribute on Blob.slice.
+    def clamp_long_long(value)
+      return value if value.is_a?(Integer)
+
+      f = value.to_f
+      return 0 if f.nan?
+
+      f.round(half: :even)
+    rescue StandardError
+      0
+    end
   end
 
   # `File` — Blob with a filename and an optional last-modified

data/lib/dommy/browser.rb

@@ -56,47 +56,45 @@ module Dommy
       end
     end
 
+    # Start a navigable session by fetching the initial document from
+    # `resources`, rather than passing literal HTML. Links / forms / location
+    # then perform real cross-document navigation (fetch → replace Window + JS
+    # realm), with the browser handle (history, resources, error log) surviving.
+    #   Dommy::Browser.visit("http://localhost/", resources: my_resources)
+    def self.visit(url, resources:, **opts)
+      browser = new("<!doctype html><html><head></head><body></body></html>",
+        url: "about:blank", resources: resources, navigable: true, **opts)
+      browser.visit(url, replace: true)
+      browser
+    end
+
     def initialize(html, url: "http://localhost/", resources: nil, execute_scripts: true, strict: true, settle: true,
-      wasm_memory_shim: false, backend: nil)
+      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 = []
       @console = []
       @acknowledged = 0
       @allow_errors = false
       @disposed = false
+      @pending_navigation = nil
+      @runtime = nil
 
       @window = Dommy.parse(html)
       @window.location.__internal_set_url__(url) if url
+      install_runtime(@window)
 
-      # 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)
-      @runtime.on_log { |log| @console << log }
-      @runtime.define_host_object("document", @window.document)
-      @runtime.install_window(@window)
-      @runtime.install_browser_globals
-      # Opt-in WPT scaffolding (common/sab.js derives SharedArrayBuffer through
-      # WebAssembly.Memory); off by default so real pages don't see the shim.
-      @runtime.install_wasm_memory_shim if wasm_memory_shim && @runtime.respond_to?(:install_wasm_memory_shim)
-      @window.globals["__fetch_handler__"] = Resources::FetchHandler.new(@resources) if @resources
-
-      if execute_scripts
-        doc = @window.document
-        # 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 })
-        end
-        Js::ScriptBoot.run_document_scripts(
-          @runtime, doc, resources: @resources, on_error: ->(e) { @js_errors << 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
+      if navigable
+        @fetcher = Navigation::Fetcher.new(@resources, same_origin: @same_origin)
+        @history = Navigation::JointHistory.new
+        @window.navigation_delegate = self
+        @history.push(current_url, window: @window, windex: @window.history.__internal_index__)
       end
       check_js_errors!
     end
@@ -106,6 +104,70 @@ module Dommy
     # Current document HTML (serialized).
     def html = @window.document.document_element&.outer_html
 
+    # The current document's URL (the address bar).
+    def current_url = @window.location.href
+
+    # The joint (tab) history of a navigable browser, or nil for a plain
+    # single-document browser.
+    attr_reader :history
+
+    # Programmatically navigate to `url` (a Ruby-initiated visit). Only
+    # meaningful for a navigable browser; performs the fetch + document swap
+    # immediately (there is no JS on the stack).
+    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}
+      flush_navigation!
+      self
+    end
+
+    # Reload the current document (re-fetch, replace the current history entry).
+    def reload
+      visit(current_url, replace: true)
+    end
+
+    # Move back / forward one entry in the joint history. A same-document target
+    # (the entry's window is still live) traverses in place (popstate); a
+    # document-boundary target is re-fetched (no bfcache — D2).
+    def back = traverse(-1)
+    def forward = traverse(1)
+
+    # --- NavigationDelegate port (see Dommy::Navigation) ---
+
+    # A cross-document navigation intent (link / form / location). Navigation is
+    # a task: rather than swap the Window + JS realm synchronously (which may run
+    # while the outgoing realm's JS is still on the stack — e.g. `location.href =`
+    # 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 = {
+        url: url, method: method, body: body, params: params, enctype: enctype,
+        headers: headers, replace: replace, source: source
+      }
+      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.
+    def traverse(delta)
+      return self unless @navigable
+
+      entry = delta.negative? ? @history.back : @history.forward
+      return self unless entry
+
+      if entry.window && entry.window.equal?(@window)
+        @window.history.__internal_go_to__(entry.windex)
+        @runtime.drain_microtasks
+        check_js_errors!
+      else
+        perform_navigation!({url: entry.url, method: "GET", source: :traverse}, rebind: true)
+      end
+      self
+    end
+
     # Evaluate an expression / statement body and return the decoded value.
     def evaluate(js)
       result = @runtime.evaluate(js)
@@ -125,6 +187,7 @@ module Dommy
     # `setTimeout(300)` — use `advance_time(300)` for debounce/throttle.
     def settle
       @runtime.settle
+      flush_navigation!
       check_js_errors!
       self
     end
@@ -133,6 +196,7 @@ module Dommy
     def advance_time(ms)
       @window.scheduler.advance_time(ms)
       @runtime.drain_microtasks
+      flush_navigation!
       check_js_errors!
       self
     end
@@ -142,25 +206,29 @@ module Dommy
     # land before the next line, then enforce strict mode.
     def after_interaction
       @runtime.drain_microtasks
+      flush_navigation!
       check_js_errors!
     end
 
     # Click a submit-capable button. The button's click event fires (JS may
     # handle / preventDefault it); if it is an un-prevented submit button, the
-    # form's `submit` event is dispatched too (a SPA's JS handles it). Real
-    # navigation on an un-prevented submit is a Session concern (out of scope).
+    # owning form's submission algorithm runs (a real SubmitEvent a SPA can
+    # intercept, then the delegate navigation). In a navigable browser that
+    # follows the submit for real; otherwise the delegate just records it.
     def click_button(locator)
       button = finder.find_button(locator)
-      prevented = Dommy::Interaction::EventSynthesis.click(button)
-      if !prevented && submit_button?(button) && (form = finder.form_for(button))
-        form.dispatch_event(Dommy::Event.new("submit", "bubbles" => true, "cancelable" => true))
-      end
+      # An un-prevented click runs the button's activation behavior — a submit
+      # button submits its owning form (real SubmitEvent + delegate navigation),
+      # so a navigable browser follows the submit for real.
+      Dommy::Interaction::EventSynthesis.click(button)
       after_interaction
       button
     end
 
     # Click a link, firing its click event so SPA JS (Turbo, React Router, …)
-    # can intercept. Real navigation on an un-prevented click is out of scope.
+    # can intercept. An un-prevented click runs the anchor's activation behavior
+    # (follow-the-hyperlink); in a navigable browser that navigates for real,
+    # otherwise the delegate records it.
     def click_link(locator)
       link = finder.find_link(locator)
       Dommy::Interaction::EventSynthesis.click(link)
@@ -190,6 +258,141 @@ module Dommy
 
     private
 
+    # Build a fresh JS realm for `window`, wire error/console/fetch/external-
+    # script seams, and boot its `<script>` tags. Disposes the previous realm
+    # first (a no-op on the initial load), so a navigation tears the outgoing
+    # realm — and with it every pending timer / microtask on the old Window's
+    # scheduler — down before the new page runs.
+    def install_runtime(window)
+      @runtime&.dispose
+      # 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)
+      runtime.on_log { |log| @console << log }
+      runtime.define_host_object("document", window.document)
+      runtime.install_window(window)
+      runtime.install_browser_globals
+      # Opt-in WPT scaffolding (common/sab.js derives SharedArrayBuffer through
+      # WebAssembly.Memory); off by default so real pages don't see the shim.
+      runtime.install_wasm_memory_shim if @wasm_memory_shim && runtime.respond_to?(:install_wasm_memory_shim)
+      window.globals["__fetch_handler__"] = Resources::FetchHandler.new(@resources) if @resources
+      @runtime = runtime
+      return unless @execute_scripts
+
+      doc = window.document
+      # 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 })
+      end
+      Js::ScriptBoot.run_document_scripts(
+        runtime, doc, resources: @resources, on_error: ->(e) { @js_errors << 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
+
+    # 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
+    # non-document response leaves the current page in place.
+    MAX_META_REFRESHES = 20
+
+    def perform_navigation!(nav, rebind: false, refresh_depth: 0)
+      response, final_url = @fetcher.request(
+        method: nav[:method] || "GET", url: nav[:url], params: nav[:params],
+        body: nav[:body], enctype: nav[:enctype], headers: nav[:headers] || {}
+      )
+      return unless response&.success? && document_response?(response)
+
+      # Fire the outgoing document's unload sequence while its realm is still
+      # alive, then surface any of its errors before the realm is torn down.
+      fire_unload(@window)
+      check_js_errors!
+
+      new_window = Dommy.parse(response.body)
+      new_window.location.__internal_set_url__(final_url)
+      new_window.navigation_delegate = self
+      @window = new_window
+      install_runtime(new_window)
+
+      windex = new_window.history.__internal_index__
+      if rebind || nav[:replace]
+        @history.rebind_current(url: final_url, window: new_window, windex: windex)
+      else
+        @history.push(final_url, window: new_window, windex: windex)
+      end
+
+      follow_meta_refresh!(refresh_depth)
+    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.
+    def follow_meta_refresh!(depth)
+      return if depth >= MAX_META_REFRESHES
+
+      target = meta_refresh_target(@window.document)
+      return unless target
+
+      perform_navigation!({url: target, method: "GET", source: :meta_refresh},
+        rebind: true, refresh_depth: depth + 1)
+    end
+
+    # The resolved URL a `<meta http-equiv="refresh" content="0; url=…">` points
+    # at, or nil when the document has none (or a refresh with no URL, which just
+    # reloads and is left alone to avoid a busy loop).
+    def meta_refresh_target(document)
+      document.query_selector_all("meta").each do |meta|
+        next unless meta.get_attribute("http-equiv").to_s.casecmp?("refresh")
+
+        _delay, separator, rest = meta.get_attribute("content").to_s.partition(";")
+        next if separator.empty?
+
+        url = rest.strip.sub(/\Aurl\s*=\s*/i, "").gsub(/\A["']|["']\z/, "").strip
+        return resolve_against_current(url) unless url.empty?
+      end
+      nil
+    end
+
+    def resolve_against_current(url)
+      URI.join(current_url, url).to_s
+    rescue URI::InvalidURIError
+      url
+    end
+
+    # Perform a pending navigation recorded by the delegate (JS-initiated
+    # location.href= / form submit / link click). Called at drain boundaries so
+    # the swap never runs with the outgoing realm's JS on the stack.
+    def flush_navigation!
+      return unless @navigable
+
+      nav = @pending_navigation
+      return unless nav
+
+      @pending_navigation = nil
+      perform_navigation!(nav)
+    end
+
+    def fire_unload(window)
+      window.dispatch_event(Dommy::Event.new("pagehide"))
+      window.dispatch_event(Dommy::Event.new("unload"))
+    end
+
+    # Only HTML/XML responses replace the document; other content types (a JSON
+    # API hit, an image) leave the current page. A response with no Content-Type
+    # is treated as a document (fixtures commonly omit it).
+    def document_response?(response)
+      headers = response.headers || {}
+      key = headers.keys.find { |k| k.to_s.casecmp?("content-type") }
+      content_type = key ? headers[key].to_s.downcase : ""
+      content_type.empty? || content_type.include?("html") || content_type.include?("xml")
+    end
+
     def unacknowledged = @js_errors[@acknowledged..] || []
 
     def submit_button?(button)

data/lib/dommy/callable_invoker.rb

@@ -22,12 +22,16 @@ module Dommy
 
     # 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).
-    def invoke_listener(listener, event)
+    # that order). A JS function listener's `this` must be the event's
+    # currentTarget (the node the listener is attached to), so pass it through
+    # when the bridge supports an explicit receiver.
+    def invoke_listener(listener, event, current_target = nil)
       if listener.respond_to?(:handle_event)
         listener.handle_event(event)
       elsif listener.respond_to?(:call) && !listener.is_a?(Module)
         listener.call(event)
+      elsif listener.respond_to?(:__js_call_with_this__)
+        listener.__js_call_with_this__([event], current_target)
       elsif listener.respond_to?(:__js_call__)
         listener.__js_call__("call", [event])
       end