dommy 0.6.0 → 0.8.0

data/lib/dommy/backend/nokolexbor_adapter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "nokolexbor"
+
+module Dommy
+  module Backend
+    # Nokolexbor (Lexbor-based) backend. 3-7× faster CSS selectors,
+    # 6× faster HTML5 parsing. HTML-only — XML namespaces are not
+    # tracked, so SVG detection falls back to ancestor walking.
+    module Nokolexbor
+      # Class references for `is_a?` / type-checking.
+      Element = ::Nokolexbor::Element
+      Document = ::Nokolexbor::Document
+      Text = ::Nokolexbor::Text
+      Comment = ::Nokolexbor::Comment
+      DocumentFragment = ::Nokolexbor::DocumentFragment
+      Node = ::Nokolexbor::Node
+
+      # Fake "namespace" wrapper returned for nodes inside <svg> subtrees.
+      # Provides the same `href` API that Nokogiri's Namespace object has,
+      # so calling code can treat them uniformly.
+      SvgNamespace = Struct.new(:href) do
+        def initialize
+          super("http://www.w3.org/2000/svg")
+        end
+      end
+
+      SVG_NAMESPACE = SvgNamespace.new.freeze
+
+      module_function
+
+      def parse(html)
+        ::Nokolexbor.parse(html.to_s)
+      end
+
+      def fragment(html, owner_doc:)
+        ::Nokolexbor::DocumentFragment.parse(html.to_s)
+      end
+
+      def create_element(name, doc)
+        ::Nokolexbor::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokolexbor::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        # Nokolexbor's argument order is (content, doc).
+        ::Nokolexbor::Comment.new(content, doc)
+      end
+
+      # Nokolexbor doesn't track XML namespaces. We synthesize one for
+      # SVG by walking ancestors — necessary so `element_class_for`
+      # routes SVG tags to their specialized classes.
+      def namespace_of(node)
+        return nil unless node.respond_to?(:name)
+
+        in_svg_subtree?(node) ? SVG_NAMESPACE : nil
+      end
+
+      def add_namespace_definition(_node, _prefix, _href)
+        # No-op: Nokolexbor doesn't support XML namespaces.
+      end
+
+      # ----- Namespaced attributes (degraded) -----
+      # Nokolexbor has no namespace model, so *AttributeNS collapses to the
+      # qualified name in the null namespace. Fine for HTML (all attributes are
+      # null-namespace); foreign-content (SVG/MathML) fidelity is lost.
+
+      def get_attribute_ns(node, _namespace, local_name)
+        node[local_name.to_s]
+      end
+
+      def has_attribute_ns?(node, _namespace, local_name)
+        node.key?(local_name.to_s)
+      end
+
+      def set_attribute_ns(node, _namespace, _prefix, _local_name, qualified_name, value)
+        node[qualified_name] = value.to_s
+        value.to_s
+      end
+
+      def remove_attribute_ns(node, _namespace, local_name)
+        node.remove_attribute(local_name.to_s) if node.key?(local_name.to_s)
+        nil
+      end
+
+      def attribute_ns_info(attr_node)
+        {
+          namespace_uri: nil,
+          prefix: nil,
+          local_name: attr_node.name,
+          qualified_name: attr_node.name,
+          value: attr_node.value,
+        }
+      end
+
+      def attribute_nodes(node)
+        node.attribute_nodes
+      end
+
+      # Internal helper — visible to allow testing.
+      def in_svg_subtree?(node)
+        return true if node.name.to_s.downcase == "svg"
+
+        current = node.parent
+        while current
+          return true if current.respond_to?(:name) && current.name.to_s.downcase == "svg"
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/dommy/backend.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `Dommy::Backend` — pluggable HTML parser abstraction. Lets Dommy
+  # work with either Nokogiri (mature, full namespace support) or
+  # Nokolexbor (faster, HTML5-only). Internally, all DOM library
+  # code goes through this facade rather than referencing the parser
+  # directly.
+  #
+  # Defaults to Nokogiri if available, else Nokolexbor.
+  #
+  # Switching backends:
+  #
+  #   require "dommy"
+  #   Dommy::Backend.use(:nokolexbor)
+  #
+  # Or set directly:
+  #
+  #   Dommy::Backend.current = Dommy::Backend::Nokolexbor
+  #
+  # All adapters must implement the same interface — see
+  # `Backend::Nokogiri` for the canonical reference.
+  module Backend
+    class BackendNotAvailable < StandardError
+    end
+
+    class << self
+      def current
+        @current ||= detect_default
+      end
+
+      attr_writer :current
+
+      def use(name)
+        @current = case name.to_sym
+        when :nokogiri
+          require_relative "backend/nokogiri_adapter"
+          Nokogiri
+        when :nokolexbor
+          require_relative "backend/nokolexbor_adapter"
+          Nokolexbor
+        else
+          raise ArgumentError, "Unknown backend: #{name.inspect}. Use :nokogiri or :nokolexbor."
+        end
+      end
+
+      # Delegate calls so internal code can use `Backend.parse(...)`.
+      def parse(html)
+        current.parse(html)
+      end
+
+      # Parse XML input into an XML document. Backends without a real XML parser
+      # (HTML-only, e.g. Nokolexbor) fall back to the HTML parser.
+      def parse_xml(xml)
+        current.respond_to?(:parse_xml) ? current.parse_xml(xml) : current.parse(xml)
+      end
+
+      def fragment(html, owner_doc:)
+        current.fragment(html, owner_doc: owner_doc)
+      end
+
+      def create_element(name, doc)
+        current.create_element(name, doc)
+      end
+
+      def create_text(content, doc)
+        current.create_text(content, doc)
+      end
+
+      def create_comment(content, doc)
+        current.create_comment(content, doc)
+      end
+
+      # CDATA section node (XML documents). Backends without CDATA fall back to a
+      # text node.
+      def create_cdata(content, doc)
+        current.respond_to?(:create_cdata) ? current.create_cdata(content, doc) : current.create_text(content, doc)
+      end
+
+      def cdata_class
+        current.respond_to?(:cdata_class) ? current.cdata_class : nil
+      end
+
+      def namespace_of(node)
+        current.namespace_of(node)
+      end
+
+      def add_namespace_definition(node, prefix, href)
+        current.add_namespace_definition(node, prefix, href)
+      end
+
+      # Namespaced attribute access (DOM *AttributeNS). `namespace` is an href
+      # String or nil. Nokolexbor degrades to qualified-name (null-namespace).
+      def get_attribute_ns(node, namespace, local_name)
+        current.get_attribute_ns(node, namespace, local_name)
+      end
+
+      def set_attribute_ns(node, namespace, prefix, local_name, qualified_name, value)
+        current.set_attribute_ns(node, namespace, prefix, local_name, qualified_name, value)
+      end
+
+      def remove_attribute_ns(node, namespace, local_name)
+        current.remove_attribute_ns(node, namespace, local_name)
+      end
+
+      def has_attribute_ns?(node, namespace, local_name)
+        current.has_attribute_ns?(node, namespace, local_name)
+      end
+
+      # Reads a backend attribute node into {namespace_uri:, prefix:,
+      # local_name:, qualified_name:, value:} (namespace-aware).
+      def attribute_ns_info(attr_node)
+        current.attribute_ns_info(attr_node)
+      end
+
+      # The element's attribute nodes (each readable via attribute_ns_info).
+      # The single choke point so DOM code doesn't touch parser internals.
+      def attribute_nodes(node)
+        current.attribute_nodes(node)
+      end
+
+      # Type constants — proxy through to the current backend so
+      # `node.is_a?(Backend::Element)` resolves dynamically.
+      def element_class
+        current::Element
+      end
+
+      def document_class
+        current::Document
+      end
+
+      def text_class
+        current::Text
+      end
+
+      def comment_class
+        current::Comment
+      end
+
+      def document_fragment_class
+        current::DocumentFragment
+      end
+
+      def node_class
+        current::Node
+      end
+
+      private
+
+      def detect_default
+        try_nokogiri ||
+          try_nokolexbor ||
+          raise(BackendNotAvailable, "Dommy requires either 'nokogiri' or 'nokolexbor' gem to be installed.")
+      end
+
+      def try_nokogiri
+        require "nokogiri"
+
+        require_relative "backend/nokogiri_adapter"
+        Nokogiri
+      rescue LoadError
+        nil
+      end
+
+      def try_nokolexbor
+        require "nokolexbor"
+
+        require_relative "backend/nokolexbor_adapter"
+        Nokolexbor
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/blob.rb

@@ -17,12 +17,16 @@ module Dommy
     #   - anything else: coerced via to_s
     #
     # `options["type"]` sets the MIME type (lowercased per spec).
-    def initialize(parts = [], options = {})
+    # `window` (optional) lets the JS-facing `text()`/`arrayBuffer()` return real
+    # 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)
       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
+      @window = window
     end
 
     # Return a new Blob over a byte range of this one.
@@ -31,7 +35,7 @@ module Dommy
       s = clamp_index(start.to_i, @size)
       e = clamp_index(last.to_i, @size)
       e = s if e < s
-      Blob.new([@data.byteslice(s, e - s) || ""], "type" => content_type.to_s)
+      Blob.new([@data.byteslice(s, e - s) || ""], {"type" => content_type.to_s}, @window)
     end
 
     # Read the bytes as UTF-8 text. The DOM spec returns a Promise,
@@ -40,15 +44,16 @@ module Dommy
       @data.dup.force_encoding(Encoding::UTF_8)
     end
 
-    # Read the bytes as an Array<Integer>. The DOM spec returns a
-    # Promise<ArrayBuffer>; Dommy is synchronous.
+    # Read the bytes as a real ArrayBuffer (the spec return type, wrapped so it
+    # crosses the JS boundary as a bare ArrayBuffer rather than an Array/typed
+    # array). The DOM spec returns a Promise<ArrayBuffer>; Dommy is synchronous.
     def array_buffer
-      @data.bytes
+      Bridge::ArrayBuffer.new(@data.bytes)
     end
 
     # Raw binary bytes (Ruby ASCII-8BIT string). Used by FormData /
     # fetch when serializing multipart bodies.
-    def __bytes__
+    def __dommy_bytes__
       @data
     end
 
@@ -61,25 +66,37 @@ module Dommy
       end
     end
 
+    # 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]
     def __js_call__(method, args)
       case method
       when "slice"
         slice(args[0] || 0, args[1] || @size, args[2] || "")
       when "text"
-        text
+        # WHATWG: Blob.text() returns a Promise<string>.
+        promise_or_value(text)
       when "arrayBuffer"
-        array_buffer
+        # WHATWG: Blob.arrayBuffer() returns a Promise<ArrayBuffer>.
+        promise_or_value(array_buffer)
       end
     end
 
     private
 
+    # Wrap a consumed value in a resolved Promise when a window is available;
+    # otherwise return it directly (a window-less Blob — `await` copes either way).
+    def promise_or_value(value)
+      @window ? PromiseValue.resolve(@window, value) : value
+    end
+
     def collect_bytes(parts)
       buf = String.new(encoding: Encoding::ASCII_8BIT)
       parts.each do |part|
         case part
         when Blob
-          buf << part.__bytes__
+          buf << part.__dommy_bytes__
         when String
           buf << part.dup.force_encoding(Encoding::ASCII_8BIT)
         when Array
@@ -106,8 +123,8 @@ module Dommy
   class File < Blob
     attr_reader :name, :last_modified
 
-    def initialize(parts, name, options = {})
-      super(parts, options)
+    def initialize(parts, name, options = {}, window = nil)
+      super(parts, options, window)
       @name = name.to_s
       raw_lm = options["lastModified"] || options[:lastModified]
       @last_modified = (raw_lm || (Time.now.to_f * 1000)).to_i
@@ -172,6 +189,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[item]
     def __js_call__(method, args)
       case method
       when "item"

data/lib/dommy/bridge/constructor_registry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # Maps JS global constructor names (e.g. "Event", "URL", "XMLHttpRequest")
+    # to their `Bridge::Constructor` instances. Window builds one and routes
+    # `__js_get__` name lookups through it, instead of carrying one ivar plus
+    # one `when` arm per constructor.
+    class ConstructorRegistry
+      def initialize(map)
+        @map = map.freeze
+      end
+
+      def [](name)
+        @map[name]
+      end
+
+      def key?(name)
+        @map.key?(name)
+      end
+
+      # The set of constructor names, e.g. for host-side enumeration / tests.
+      def names
+        @map.keys
+      end
+    end
+  end
+end

data/lib/dommy/bridge/methods.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # Declares, in one line, the set of JS-callable method names a bridge class
+    # routes through `__js_call__` (as opposed to data properties read via
+    # `__js_get__`). The QuickJS host reads `__js_method_names__` once per
+    # interface to decide which property names to expose as callable functions.
+    #
+    #   class Blob
+    #     include Bridge::Methods
+    #     js_methods %w[slice text arrayBuffer]
+    #     def __js_call__(method, args) = ...
+    #   end
+    #
+    # Subclasses compose automatically: a subclass's own `js_methods` are merged
+    # with its ancestors' (ancestors first), so `__js_call__ ... else super`
+    # chains stay in sync with the exposed names without a manual `super + own`.
+    #
+    # The per-class `JS_METHOD_NAMES` constant holds the class's OWN names; the
+    # suite asserts it matches the class's own `__js_call__` `when` arms — see
+    # test/test_js_call_dispatch_invariant.rb.
+    module Methods
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # `extend` is per-singleton, so a subclass of an includer would not
+        # inherit `js_methods`. Re-extend each subclass as it is defined.
+        def inherited(subclass)
+          super
+          subclass.extend(ClassMethods)
+        end
+
+        def js_methods(names)
+          own = names.map(&:to_s).freeze
+          const_set(:JS_METHOD_NAMES, own) unless const_defined?(:JS_METHOD_NAMES, false)
+
+          # Capture the ancestor's __js_method_names__ as a real method (if any)
+          # at definition time. We can't use `super` here: classes like
+          # StyleDeclaration define `method_missing`, so `super` would fall
+          # through to it and return a CSS-property String instead of raising.
+          parent =
+            if superclass.method_defined?(:__js_method_names__)
+              superclass.instance_method(:__js_method_names__)
+            end
+
+          define_method(:__js_method_names__) do
+            base = parent ? parent.bind(self).call : []
+            (base + own).uniq.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dommy/bridge.rb

@@ -18,6 +18,97 @@ module Dommy
   #     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
+
+    # 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
@@ -83,6 +174,12 @@ module Dommy
         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`

data/lib/dommy/callable_invoker.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Dommy
+  # Invokes a callback that may be a JS-bridged object (responds to `__js_call__`)
+  # or a plain Ruby callable (responds to `call`). Centralizes the dispatch used
+  # by promises, the scheduler, and streams so the JS/Ruby fork lives in one place.
+  module CallableInvoker
+    module_function
+
+    # Invoke `callback` with `args`. A JS-bridged callable goes through
+    # `__js_call__("call", args)`; a Ruby callable through `call(*args)`. A nil
+    # or non-callable callback is a no-op (returns nil).
+    def invoke(callback, *args)
+      return if callback.nil?
+
+      if callback.respond_to?(:__js_call__)
+        callback.__js_call__("call", args)
+      elsif callback.respond_to?(:call)
+        callback.call(*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).
+    def invoke_listener(listener, event)
+      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__)
+        listener.__js_call__("call", [event])
+      end
+    end
+  end
+end

data/lib/dommy/compression_streams.rb

@@ -31,9 +31,9 @@ module Dommy
           "close" => proc do
             compressed = compressor.call(@buffer)
             controller.enqueue(compressed)
-            @readable.__close__
+            @readable.__internal_close__
           end,
-          "abort" => proc { |r| @readable.__error__(r) }
+          "abort" => proc { |r| @readable.__internal_error__(r) }
         }
       )
     end
@@ -98,9 +98,9 @@ module Dommy
           "close" => proc do
             plain = decompressor.call(@buffer)
             controller.enqueue(plain)
-            @readable.__close__
+            @readable.__internal_close__
           end,
-          "abort" => proc { |r| @readable.__error__(r) }
+          "abort" => proc { |r| @readable.__internal_error__(r) }
         }
       )
     end

data/lib/dommy/cookie_store.rb

@@ -60,6 +60,8 @@ module Dommy
       PromiseValue.resolve(@window, nil)
     end
 
+    include Bridge::Methods
+    js_methods %w[get getAll set delete addEventListener removeEventListener dispatchEvent]
     def __js_call__(method, args)
       case method
       when "get"
@@ -73,13 +75,13 @@ module Dommy
       when "addEventListener"
         add_event_listener(args[0], args[1], args[2])
       when "removeEventListener"
-        remove_event_listener(args[0], args[1])
+        remove_event_listener(args[0], args[1], args[2])
       when "dispatchEvent"
         dispatch_event(args[0])
       end
     end
 
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end