dommy 0.7.0 → 0.8.0

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/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,7 +75,7 @@ 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

data/lib/dommy/crypto.rb

@@ -62,6 +62,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[randomUUID getRandomValues]
     def __js_call__(method, args)
       case method
       when "randomUUID"
@@ -99,7 +101,9 @@ module Dommy
         hasher = ALGORITHMS[name]
         raise ArgumentError, "unsupported algorithm: #{name}" unless hasher
 
-        hasher.call(coerce_bytes(data)).bytes
+        # WHATWG: digest() resolves to an ArrayBuffer — wrap so it crosses the
+        # JS boundary as a bare ArrayBuffer (not a plain Array).
+        Bridge::ArrayBuffer.new(hasher.call(coerce_bytes(data)).bytes)
       end
     end
 
@@ -230,6 +234,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[digest generateKey importKey sign verify encrypt decrypt]
     def __js_call__(method, args)
       case method
       when "digest"

data/lib/dommy/css.rb

@@ -125,6 +125,8 @@ module Dommy
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[insertRule deleteRule replaceSync replace]
     def __js_call__(method, args)
       case method
       when "insertRule"
@@ -196,6 +198,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[item]
     def __js_call__(method, args)
       case method
       when "item"
@@ -280,4 +284,46 @@ module Dommy
       nil
     end
   end
+
+  # `window.CSS` namespace object — `escape()` for safe selector building
+  # (used by Turbo and friends) and a `supports()` stub (no CSS engine).
+  class CSSNamespace
+    def __js_get__(_key) = nil
+    def __js_set__(_key, _value) = Bridge::UNHANDLED
+
+    include Bridge::Methods
+    js_methods %w[escape supports]
+    def __js_call__(method, args)
+      case method
+      when "escape"
+        self.class.escape(args[0])
+      when "supports"
+        false
+      end
+    end
+
+    # CSSOM `CSS.escape` — escape a string for use as an identifier in a
+    # selector. Follows the spec's char rules closely enough for selectors.
+    def self.escape(value)
+      str = value.to_s
+      out = +""
+      str.each_char.with_index do |ch, i|
+        code = ch.ord
+        if code.zero?
+          out << "\uFFFD"
+        elsif (code >= 0x01 && code <= 0x1F) || code == 0x7F ||
+              (i.zero? && code >= 0x30 && code <= 0x39) ||
+              (i == 1 && code >= 0x30 && code <= 0x39 && str[0] == "-")
+          out << "\\#{code.to_s(16)} "
+        elsif code >= 0x80 || code == 0x2D || code == 0x5F ||
+              (code >= 0x30 && code <= 0x39) ||
+              (code >= 0x41 && code <= 0x5A) || (code >= 0x61 && code <= 0x7A)
+          out << ch
+        else
+          out << "\\#{ch}"
+        end
+      end
+      out
+    end
+  end
 end

data/lib/dommy/custom_elements.rb

@@ -10,7 +10,21 @@ module Dommy
   #
   # Names must contain a hyphen per the HTML spec (e.g., `my-button`).
   class CustomElementRegistry
-    NAME_RE = /\A[a-z][a-z0-9-]*-[a-z0-9-]*\z/
+    # https://html.spec.whatwg.org/#valid-custom-element-name
+    # PCENChar — the characters allowed after the first (ASCII-lower) char: a
+    # superset of [-._0-9a-z] plus wide Unicode ranges. A valid name is
+    # `[a-z] PCENChar* - PCENChar*` (i.e. lower-alpha start + at least one "-").
+    PCEN = "\\-._0-9a-z\\u00B7\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u037D" \
+           "\\u037F-\\u1FFF\\u200C-\\u200D\\u203F-\\u2040\\u2070-\\u218F" \
+           "\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD\\u{10000}-\\u{EFFFF}"
+    NAME_RE = Regexp.new("\\A[a-z][#{PCEN}]*-[#{PCEN}]*\\z")
+
+    # Hyphenated names that the HTML spec reserves (SVG / MathML elements), so
+    # they are NOT valid custom element names even though they match NAME_RE.
+    RESERVED_NAMES = %w[
+      annotation-xml color-profile font-face font-face-src font-face-uri
+      font-face-format font-face-name missing-glyph
+    ].to_set.freeze
 
     def initialize(window)
       @window = window
@@ -23,7 +37,10 @@ module Dommy
     def define(name, klass, _options = nil)
       key = name.to_s
       unless key.match?(NAME_RE)
-        raise DOMException::SyntaxError, "name must be a hyphenated string, got #{name.inspect}"
+        raise DOMException::SyntaxError, "#{name.inspect} is not a valid custom element name"
+      end
+      if RESERVED_NAMES.include?(key)
+        raise DOMException::SyntaxError, "#{name.inspect} is a reserved element name"
       end
 
       raise DOMException::NotSupportedError, "#{key} already defined" if @definitions.key?(key)
@@ -83,6 +100,8 @@ module Dommy
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[define get whenDefined upgrade]
     def __js_call__(method, args)
       case method
       when "define"
@@ -108,7 +127,12 @@ module Dommy
     # new class and fire connectedCallback.
     def upgrade_existing(name)
       doc = @window.document
-      doc.nokogiri_doc.css(name).each do |nk|
+      # Match by tag name rather than interpolating `name` into a CSS selector:
+      # a spec-valid custom element name may contain "." (a CSS class selector
+      # char) or other metacharacters, which would corrupt the query.
+      doc.nokogiri_doc.css("*").each do |nk|
+        next unless nk.name == name
+
         doc.__internal_reset_wrapper__(nk)
         wrapped = doc.wrap_node(nk)
         doc.__internal_notify_connected__(wrapped) if wrapped

data/lib/dommy/data_transfer.rb

@@ -64,11 +64,15 @@ module Dommy
         @drop_effect = value.to_s
       when "effectAllowed"
         @effect_allowed = value.to_s
+      else
+        return Bridge::UNHANDLED
       end
 
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[getData setData clearData]
     def __js_call__(method, args)
       case method
       when "getData"