dommy 0.9.0 → 0.11.0

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,148 @@ 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
+      doc = window.document
+      # An `on*` attribute that arrived after boot (a cloned template, an
+      # innerHTML fragment) is compiled on first dispatch, which replays the scan.
+      # 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 })
+      end
+      return unless @execute_scripts
+
+      # 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,14 +22,26 @@ 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.
+    # `args:` overrides the single-event argument list — the special error
+    # event handler (`window.onerror`) is called with (message, filename,
+    # lineno, colno, error) instead of the event. An EventListener object's
+    # handleEvent always receives the event.
+    def invoke_listener(listener, event, current_target = nil, args: nil)
+      args ||= [event]
       if listener.respond_to?(:handle_event)
         listener.handle_event(event)
       elsif listener.respond_to?(:call) && !listener.is_a?(Module)
-        listener.call(event)
+        listener.call(*args)
+      elsif listener.respond_to?(:__js_invoke__)
+        # A JS function listener: `this` is the currentTarget, and a thrown value
+        # surfaces (as a ThrowValue) so the dispatch reports it as a window
+        # `error` event instead of swallowing it.
+        listener.__js_invoke__(args, this: current_target, raising: true)
       elsif listener.respond_to?(:__js_call__)
-        listener.__js_call__("call", [event])
+        listener.__js_call__("call", args)
       end
     end
   end

data/lib/dommy/css.rb

@@ -18,7 +18,9 @@ module Dommy
   class CSSStyleSheet
     attr_reader :owner_node, :css_rules
 
-    def initialize(owner_node:, href: nil, media: nil, title: nil, type: "text/css", source_text: nil)
+    # A stylesheet constructed by `new CSSStyleSheet()` has no owner node.
+    # Element-owned sheets still pass their <style> / <link> node explicitly.
+    def initialize(owner_node: nil, href: nil, media: nil, title: nil, type: "text/css", source_text: nil)
       @owner_node = owner_node
       @href = href
       @media = media
@@ -291,21 +293,27 @@ module Dommy
     end
 
     def get_property_value(name)
-      entry = @props[name.to_s]
+      entry = @props[property_key(name)]
       entry ? entry[:value] : ""
     end
 
     def get_property_priority(name)
-      entry = @props[name.to_s]
+      entry = @props[property_key(name)]
       entry ? entry[:priority] : ""
     end
 
     def set_property(name, value, priority = nil)
-      key = name.to_s
+      key = property_key(name)
       if value.nil? || value.to_s.empty?
+        # CSSOM step 3 — an empty value removes the declaration, and it runs
+        # before the priority check, so the priority is irrelevant here.
         @props.delete(key)
       else
-        important = priority.to_s.downcase == "important" ? "important" : ""
+        # CSSOM step 4 — an invalid priority abandons the call, leaving the
+        # declaration block exactly as it was.
+        important = Internal::CssPriority.normalize(priority)
+        return nil if important.nil?
+
         @props[key] = {value: value.to_s, priority: important}
       end
       flush!
@@ -313,7 +321,7 @@ module Dommy
     end
 
     def remove_property(name)
-      removed = @props.delete(name.to_s)
+      removed = @props.delete(property_key(name))
       flush!
       removed ? removed[:value] : ""
     end
@@ -403,6 +411,13 @@ module Dommy
 
     private
 
+    # CSSOM normalizes every property name it is handed (see
+    # Internal::CSS::Parser.property_name); `css_name` below is the separate
+    # camelCase / snake_case → kebab conversion for the IDL accessors.
+    def property_key(name)
+      Internal::CSS::Parser.property_name(name)
+    end
+
     def css_name(name)
       str = name.to_s
       return str if str.start_with?("--")
@@ -414,8 +429,8 @@ module Dommy
     # reusing the cascade's declaration parser (same normalization the cascade
     # sees) so reads agree with computed style.
     def parse(body_text)
-      Internal::CSS::Parser.parse_declarations(body_text.to_s).each_with_object({}) do |decl, out|
-        out[decl.name] = {value: decl.value, priority: decl.important ? "important" : ""}
+      Internal::CSS::Parser.parse_block(body_text).transform_values do |decl|
+        {value: decl.value, priority: decl.important ? "important" : ""}
       end
     end
 
@@ -458,8 +473,16 @@ module Dommy
       @parent_style_sheet = parent_style_sheet
     end
 
+    # CSSOM serializes a style rule as its selector plus its declaration block,
+    # so the text is rebuilt from the parsed declarations rather than echoed
+    # back: `#foo { color: red }` reads as `#foo { color: red; }`, and a block
+    # whose contents are not declarations at all serializes empty. An at-rule
+    # keeps its text as given.
     def css_text
-      @css_text
+      return @css_text unless style_rule?
+
+      declarations = style&.css_text.to_s
+      declarations.empty? ? "#{selector_text} { }" : "#{selector_text} { #{declarations} }"
     end
 
     def css_text=(v)
@@ -553,7 +576,7 @@ module Dommy
 
     def __js_get__(key)
       case key
-      when "cssText" then @css_text
+      when "cssText" then css_text
       when "type" then type
       when "selectorText" then selector_text
       when "style" then style

data/lib/dommy/custom_elements.rb

@@ -34,6 +34,15 @@ module Dommy
       @pending_promises = {}
     end
 
+    # Whether `name` is a valid custom element name. Also consulted by
+    # `element_class_for`: an unrecognized HTML-namespace name that is valid here
+    # is an *undefined custom element* (interface HTMLElement), not an unknown
+    # element (HTMLUnknownElement).
+    def self.valid_name?(name)
+      key = name.to_s
+      key.match?(NAME_RE) && !RESERVED_NAMES.include?(key)
+    end
+
     def define(name, klass, _options = nil)
       key = name.to_s
       unless key.match?(NAME_RE)
@@ -90,7 +99,13 @@ module Dommy
         # Force re-wrap by clearing the document's cached wrapper.
         @window.document.__internal_reset_wrapper__(nk)
         wrapped = @window.document.wrap_node(nk)
-        @window.document.__internal_notify_connected__(wrapped) if wrapped
+        next unless wrapped
+
+        replay_observed_attributes(wrapped)
+        # connectedCallback is enqueued only for an element that is actually in
+        # a document tree — `customElements.upgrade()` on a detached subtree
+        # upgrades it without connecting it.
+        @window.document.__internal_notify_connected__(wrapped) if wrapped.is_connected?
       end
 
       nil
@@ -135,7 +150,32 @@ module Dommy
 
         doc.__internal_reset_wrapper__(nk)
         wrapped = doc.wrap_node(nk)
-        doc.__internal_notify_connected__(wrapped) if wrapped
+        next unless wrapped
+
+        replay_observed_attributes(wrapped)
+        doc.__internal_notify_connected__(wrapped)
+      end
+    end
+
+    # "Upgrade an element" step 6: the element's *existing* attributes are
+    # replayed through attributeChangedCallback (oldValue null) before
+    # connectedCallback, so a definition registered after the markup was parsed
+    # still sees the attributes that were already there.
+    def replay_observed_attributes(element)
+      klass = element.class
+      return unless klass.respond_to?(:observed_attributes)
+
+      observed = Array(klass.observed_attributes).map { |a| a.to_s.downcase }
+      return if observed.empty?
+
+      element.get_attribute_names.each do |name|
+        next unless observed.include?(name.to_s.downcase)
+
+        # Routed through the coordinator so the callback's arity handling (the
+        # optional 4th namespace argument) stays in one place.
+        @window.document.__internal_notify_attribute_changed__(
+          element, name, nil, element.get_attribute(name)
+        )
       end
     end