dommy 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64a22d9ba17102a03881baedbda66b5236b8c4499140d779e4c4acba86583241
-  data.tar.gz: e111a114c5a7ae9485a3e99af339e70a59dce6b9a83a837639ac6564873a8d4e
+  metadata.gz: d623f452622acb0d99a40af340aefc6dfc86a4c466277097132e0a3dcff5b741
+  data.tar.gz: 38ea700cb1a482696ca8253b5bbf8901c5f34f564ed760c57dae1e0d0abf9f92
 SHA512:
-  metadata.gz: 67c651bd499d2cd0d6cf1fb862b11a9f0f6b68ba1814abe40732b990e5b66b9b5f0494fd33cb989e4b7a5f64faa3a8a152e8979231f4c082f32187999188030a
-  data.tar.gz: e7e8ee9194687b9fe6be28646e9f80d32631f3cf78e5b9fefbab5fd913b9a1d6116ab819bae3a54030f2fefc6e4fa8e478c8ab2667cc086e009c5ebb1a7c9481
+  metadata.gz: b94eb7cece5d3753d03a0e763f7b0a8ddf7cf38360cd3841f195e9616b9caa2f24ac286bf897866f762694a2f48a5292ba01abd69c6a9213f59d8703e32c9509
+  data.tar.gz: f6cd5abc39c423a6d5f621a2c6209df9e622c7ee9ec3c805d3e2730ace518de1efe8614d4a91b48748e2515f37917bb607c9f89719f9ef0168f9028e55b8aca5

data/lib/dommy/backend/makiri_adapter.rb

@@ -23,12 +23,7 @@ module Dommy
       DocumentFragment = ::Makiri::DocumentFragment
       DocumentType = ::Makiri::DocumentType
       Node = ::Makiri::Node
-
-      # A minimal namespace wrapper exposing the same `href` API that Nokogiri's
-      # Namespace object has, so calling code treats both backends uniformly.
-      Namespace = Struct.new(:href)
-
-      HTML_NAMESPACE_URI = "http://www.w3.org/1999/xhtml"
+      XMLSyntaxError = ::Makiri::XML::SyntaxError
 
       # Throwaway attribute used to bind `:scope` to a context element — Lexbor
       # has no `:scope`, so a scoped query temporarily marks the element and
@@ -98,6 +93,10 @@ module Dommy
         target_doc.import_node(node, true)
       end
 
+      def import_element(node, target_doc)
+        target_doc.import_node(node, false)
+      end
+
       # Lexbor arenas can't move a node between documents — a foreign node must be
       # imported (see #adopt) before insertion.
       def moves_nodes_across_documents?
@@ -162,11 +161,22 @@ module Dommy
       # 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)
+        return nil unless doc.is_a?(::Makiri::XML::Document)
 
         doc.create_loose_dom_element(qualified_name, prefix, local, namespace)
       end
 
+      # createElementNS in an HTML document. Makiri builds the element in its
+      # own namespace, so the backend node is what the parser would have made:
+      # an SVG `feGaussianBlur` keeps its case and `[viewBox]` reads its
+      # attribute case-sensitively. nil for an XML document → the caller uses
+      # #create_element.
+      def create_element_ns(namespace, qualified_name, doc)
+        return nil unless doc.is_a?(::Makiri::HTML::Document)
+
+        doc.create_element_ns(presence(namespace), qualified_name.to_s)
+      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
@@ -231,20 +241,10 @@ module Dommy
         ::Makiri::ProcessingInstruction
       end
 
-      # Makiri 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.
-      # The element's namespace, from Lexbor's own namespace tracking (HTML /
-      # SVG / MathML). nil for the HTML namespace, so Element#namespace_uri
-      # falls back to its HTML default (and the wrapper is allocated only for
-      # genuine foreign content).
-      def namespace_of(node)
-        return nil unless node.respond_to?(:namespace_uri)
-
-        uri = node.namespace_uri
-        return nil if uri.nil? || uri.empty? || uri == HTML_NAMESPACE_URI
-
-        Namespace.new(uri)
+      # The element's namespace as the backend tracks it (Lexbor's HTML / SVG /
+      # MathML, an XML document's own), nil for none.
+      def namespace_uri(node)
+        presence(node.respond_to?(:namespace_uri) ? node.namespace_uri : nil)
       end
 
       # Bind a *prefixed* element's namespace so the prefix resolves. An XML
@@ -264,11 +264,13 @@ module Dommy
 
         node["xmlns:#{prefix}"] = href.to_s
         nil
-      rescue ArgumentError
+      rescue ArgumentError, ::Makiri::Error
         # DOM validates a qualified name against the Name production, which
         # admits prefixes an XML backend cannot spell as an `xmlns:` attribute
-        # ("0:a", ";:a"). The element is still valid — its prefix and namespace
-        # live on the wrapper — so the declaration is simply not written.
+        # ("0:a", ";:a" — ArgumentError), and binds prefixes Namespaces in XML
+        # forbids declaring ("f" to the XML namespace, anything to the XMLNS
+        # one — Makiri::Error). The element is still valid — its prefix and
+        # namespace live on the wrapper — so the declaration is simply not written.
         nil
       end
 
@@ -279,9 +281,8 @@ module Dommy
 
       # Lexbor keeps <template> contents in a separate content fragment rather
       # than the normal child chain.
-      def template_content_nodes(node)
-        cf = node.respond_to?(:content_fragment) ? node.content_fragment : nil
-        cf ? cf.children.to_a : []
+      def template_contents(node)
+        node.respond_to?(:content_fragment) ? node.content_fragment : nil
       end
 
       # ----- Namespaced attributes -----
@@ -299,8 +300,41 @@ module Dommy
       end
 
       def set_attribute_ns(node, namespace, _prefix, _local_name, qualified_name, value)
-        node.set_attribute_ns(presence(namespace), qualified_name.to_s, value.to_s)
-        value.to_s
+        ns = presence(namespace)
+        name = qualified_name.to_s
+        value = value.to_s
+        node.set_attribute_ns(ns, name, value) unless ns.nil? && set_null_namespace_attribute(node, name, value)
+        value
+      end
+
+      # A null-namespace name that only the DOM's `setAttribute` can make: one
+      # whose local name holds a colon ("xlink:href", "v-on:click") or is
+      # "xmlns". Makiri checks set_attribute_ns as the DOM's setAttributeNS
+      # does, which refuses these (a prefix needs a namespace).
+      def set_attribute_only_name?(name)
+        name == "xmlns" || name.include?(":")
+      end
+
+      # Makiri's own `setAttribute` for the setAttribute-only names, which
+      # set_attribute_ns refuses. true when it made the attribute; false leaves
+      # every other name to set_attribute_ns, which matches an existing
+      # attribute by (namespace, local name) rather than by qualified name:
+      # `setAttributeNS("u", "a")` then a null-namespace "a" are two attributes.
+      #
+      # - An XML document: set_loose_dom_attribute, a plain attribute (never a
+      #   namespace declaration) under the name as given.
+      # - An HTML document: `[]=`. It lower-cases only on an HTML-namespace
+      #   element, as setAttribute does, and makes the colon part of the local
+      #   name.
+      def set_null_namespace_attribute(node, name, value)
+        return false unless set_attribute_only_name?(name)
+
+        if node.respond_to?(:set_loose_dom_attribute)
+          node.set_loose_dom_attribute(name, value)
+        else
+          node[name] = value
+        end
+        true
       end
 
       def remove_attribute_ns(node, namespace, local_name)

data/lib/dommy/backend.rb

@@ -79,6 +79,12 @@ module Dommy
         current.adopt(node, target_doc)
       end
 
+      # A copy of the element `node` alone, owned by `target_doc`: its name and
+      # attributes exactly as the backend holds them.
+      def import_element(node, target_doc)
+        current.import_element(node, target_doc)
+      end
+
       # Whether the backend can move a node between documents in place or must adopt a copy first
       # (Lexbor's arenas can't move a node, so inserting a foreign node requires importing
       # it). Lets callers skip a needless — and on an empty target, root-less and
@@ -134,6 +140,20 @@ module Dommy
         current.create_element_loose(qualified_name, prefix, local, namespace, doc)
       end
 
+      # The element's own namespace URI as the DOM reports it: nil for no
+      # namespace.
+      def namespace_uri(node)
+        current.namespace_uri(node)
+      end
+
+      # Create an element in `namespace` in an HTML document, so the backend
+      # node carries the namespace and the name's case itself. Returns nil for
+      # an XML document (fall back to #create_element); raises ArgumentError
+      # for an invalid name (the caller maps it to InvalidCharacterError).
+      def create_element_ns(namespace, qualified_name, doc)
+        current.create_element_ns(namespace, qualified_name, 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
@@ -183,21 +203,18 @@ module Dommy
         current.processing_instruction_class
       end
 
-      def namespace_of(node)
-        current.namespace_of(node)
-      end
-
       # The element's in-scope namespace declarations (each responds to
       # `prefix`/`href`). Empty on backends without an XML namespace model.
       def namespace_definitions(node)
         current.namespace_definitions(node)
       end
 
-      # The content child nodes of a `<template>` element. HTML5 parsers model
-      # template contents differently — Lexbor/Makiri in a separate content fragment — so reading them goes
-      # through the backend. Used by the template-content registry's migration.
-      def template_content_nodes(node)
-        current.template_content_nodes(node)
+      # The backend's own fragment holding a `<template>` element's contents
+      # (Lexbor keeps them off the child list), the same one every time; nil
+      # for a node that has none — any node of an XML document, whose contents
+      # the template-content registry keeps instead.
+      def template_contents(node)
+        current.template_contents(node)
       end
 
       def add_namespace_definition(node, prefix, href)
@@ -262,6 +279,12 @@ module Dommy
         current::Document
       end
 
+      # What the backend raises for markup that is not well-formed XML (an XML
+      # document's fragment parse included).
+      def xml_syntax_error_class
+        current::XMLSyntaxError
+      end
+
       def text_class
         current::Text
       end

data/lib/dommy/bridge/constructor.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # A JS constructor function as Ruby sees it: `new X(...)` plus the static
+    # methods hanging off it, and the table Window looks names up in. The
+    # registry maps to these, so they share a file.
+
+    # Block-as-constructor adapter — invoking `__js_new__(args)`
+    # calls the wrapped block with `args` and returns whatever the
+    # block produces. Used by Window to wire up `new Event(init)`,
+    # `new CustomEvent(init)`, etc. without hand-rolling a class
+    # for each constructor.
+    class Constructor
+      def initialize(&block)
+        @block = block
+        @class_methods = {}
+      end
+
+      def __js_new__(args)
+        @block.call(args)
+      end
+
+      # Register a class-level method (e.g. `URL.createObjectURL`)
+      # that JS bridges resolve via `__js_call__` on the constructor
+      # itself. Returns self for chaining.
+      def define_class_method(name, &block)
+        @class_methods[name.to_s] = block
+        self
+      end
+
+      # A name outside the registered statics is not a method of this
+      # constructor, and answering nil would make `URL.notAThing()` read as a
+      # call that returned null rather than one that should not have compiled.
+      def __js_call__(method, args)
+        handler = @class_methods[method.to_s]
+        raise TypeError, "#{method} is not a function" unless handler
+
+        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
+
+    # 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/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # The exceptions a spec mandates the JS side see as something other than a
+    # DOMException — a real TypeError, a real RangeError, or an arbitrary thrown
+    # value. Each is kept distinct from Ruby's own so a host maps only the
+    # deliberate ones and never masks a genuine Ruby bug.
+
+    # Raised by a host method that must throw an ARBITRARY value back to JS —
+    # not a DOMException/Error, but e.g. `signal.throwIfAborted()` throwing the
+    # exact abort reason (a string, number, or opaque JSValue). The bridge
+    # re-throws the wrapped value verbatim (identity preserved). Subclasses
+    # RuntimeError (with the value's string form as the message) so standalone
+    # CRuby callers still see a normal `raise`-able error.
+    class ThrowValue < RuntimeError
+      attr_reader :value
+
+      # `message` overrides the value's string form, for a caller that can say
+      # more about it than `to_s` can (a JS error's kind, say).
+      def initialize(value, message = nil)
+        @value = value
+        super(message || value.to_s)
+      end
+    end
+
+    # A 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
+  end
+end

data/lib/dommy/bridge/methods.rb

@@ -34,24 +34,31 @@ module Dommy
         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
+          @own_js_methods = names.map(&:to_s).freeze
+          @js_method_names = nil # a declaration after a first read must win
+          const_set(:JS_METHOD_NAMES, @own_js_methods) unless const_defined?(:JS_METHOD_NAMES, false)
+          @own_js_methods
+        end
 
-          define_method(:__js_method_names__) do
-            base = parent ? parent.bind(self).call : []
-            (base + own).uniq.freeze
+        # The class's names plus its ancestors', ancestors first. Composed on
+        # the CLASS, which is where the answer belongs: a per-instance method
+        # could not use `super` to reach the ancestor's copy, because a class
+        # like StyleDeclaration answers `method_missing` for any name and would
+        # hand back a CSS property string instead. Walking `superclass` has no
+        # such problem.
+        def js_method_names
+          @js_method_names ||= begin
+            inherited_names = superclass.respond_to?(:js_method_names) ? superclass.js_method_names : []
+            (inherited_names + own_js_methods).uniq.freeze
           end
         end
+
+        def own_js_methods = @own_js_methods || []
       end
+
+      # The bridge ABI reads this per interface to decide which property names
+      # are callable functions.
+      def __js_method_names__ = self.class.js_method_names
     end
   end
 end

data/lib/dommy/bridge/sentinels.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # The three values that are not values: what the protocol says when a
+    # property is missing, undefined, or not ours to handle. Every host has to
+    # tell these apart, which is why they are Bridge's.
+
+    # Sentinel returned by `__js_set__` when a key is not a known DOM property
+    # (so the JS host can keep it as a JS-side expando, preserving identity)
+    # rather than silently dropping it.
+    UNHANDLED = :__js_unhandled__
+
+    # Sentinel for the JS `undefined` value, used in both directions:
+    #   - a `__js_call__` returns it for a void (undefined-returning) op, so the
+    #     host marshals JS `undefined` rather than the `null` a bare Ruby `nil`
+    #     would (e.g. DOMTokenList add/remove return undefined);
+    #   - a top-level JS `undefined` *argument* arrives as it (whereas JS `null`
+    #     arrives as `nil`), so WebIDL-style dispatch can tell an omitted optional
+    #     argument from an explicit null.
+    # Its `to_s` is "undefined" so a DOMString coercion of a stray undefined is
+    # still spec-faithful.
+    UNDEFINED = Object.new
+    def UNDEFINED.to_s = "undefined"
+    def UNDEFINED.inspect = "#<Dommy::Bridge::UNDEFINED>"
+    UNDEFINED.freeze
+
+    # The sentinel a `__js_get__` returns for a GENUINELY-ABSENT property (a key
+    # the object does not have), as distinct from a present property whose value
+    # is `nil`/JS null or `UNDEFINED`/JS undefined. It marshals to JS `undefined`
+    # for the value, but the proxy reports `("x" in obj) === false` for it — so
+    # feature detection like `isUndefined(window.Vue)` AND `"Vue" in window` are
+    # both correct. (UNDEFINED means present-but-undefined → reported present.)
+    ABSENT = Object.new
+    def ABSENT.to_s = "undefined"
+    def ABSENT.inspect = "#<Dommy::Bridge::ABSENT>"
+    ABSENT.freeze
+  end
+end

data/lib/dommy/bridge/values.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Bridge
+    # The Ruby shapes a JS value takes while it is on this side: an opaque
+    # reference, and the two byte buffers that cross as a typed array or a bare
+    # ArrayBuffer.
+
+    # An opaque handle to a JS-side value that Ruby only stores and hands back
+    # (an AbortSignal's reason, a CustomEvent's detail). A non-plain JS object
+    # (Error, class instance, …) crosses as one of these instead of being
+    # flattened to a Hash, so it round-trips with IDENTITY preserved. `to_s`
+    # exposes the captured JS string form for the rare Ruby consumer that needs
+    # text (e.g. building a message).
+    class JSValue
+      attr_reader :ref
+
+      # `stack_frames` are the value's JS stack, when the tag that crossed
+      # carried one. Ruby cannot reach through a ref to read `.stack`, so an
+      # error-shaped value brings its frames with it (see host_runtime.js
+      # tagValue) and reporting uses them for the source position.
+      attr_reader :stack_frames
+
+      # The value's JS constructor name, when the tag carried one.
+      attr_reader :js_name
+
+      def initialize(ref, label = nil, stack_frames = nil, js_name = nil)
+        @ref = ref
+        @label = label
+        @stack_frames = stack_frames
+        @js_name = js_name
+      end
+
+      def to_s = (@label || "[object]").to_s
+      def inspect = "#<Dommy::Bridge::JSValue #{to_s}>"
+    end
+
+    # 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(coerce(bytes))
+      end
+
+      alias bytes to_a
+      def pack_bytes = pack("C*")
+
+      private
+
+      # A String is the packed form — what #pack_bytes produces — so it unpacks
+      # rather than going through Array(), which would wrap it and take `to_i`
+      # of the whole thing: `Bytes.new("abc")` used to be one zero byte, with no
+      # complaint, which is the shape of a round trip gone wrong.
+      def coerce(bytes)
+        return bytes.b.unpack("C*") if bytes.is_a?(::String)
+
+        Array(bytes).map do |byte|
+          raise ArgumentError, "not a byte: #{byte.inspect}" unless byte.respond_to?(:to_int)
+
+          byte.to_int & 0xFF
+        end
+      end
+    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
+  end
+end

data/lib/dommy/{js → bridge}/wire_tags.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 module Dommy
-  module Js
-    # The wire protocol shared by every Ruby<->JS marshaller in this gem: the
-    # tagged-Hash shapes that cross the boundary (a handle, a callback, an opaque
-    # JS ref, a byte buffer, a tagged exception, …). Both Ruby marshallers —
-    # HostBridge#wrap/#unwrap (the Proxy bridge) and WasmBridge#pack/#unpack (the
-    # wasm guest bridge) — build and match these keys, so keeping them as one set
-    # of constants prevents the two sides from drifting apart.
+  module Bridge
+    # The wire protocol: the tagged-Hash shapes that cross the boundary (a
+    # handle, a callback, an opaque JS ref, a byte buffer, a tagged exception,
+    # …). Every marshaller builds and matches these keys — Js::Marshaller for
+    # the Proxy bridge, WasmBridge#pack/#unpack for the wasm guest — so one set
+    # of constants keeps them from drifting apart.
     #
-    # The JS half (host_runtime.js: dehydrate/rehydrate/wasmTag/wasmDeref) mirrors
-    # the SAME string literals. When changing a tag here, update host_runtime.js
-    # in lockstep — these constants are the canonical names; the JS literals are
-    # the mirror.
+    # It is Bridge's rather than Js's for exactly that reason: a tag is true of
+    # any host, not of the one we ship. A backend gem reads these to speak the
+    # protocol without depending on our engine.
+    #
+    # The JS half (host_runtime.js: dehydrate/rehydrate/wasmTag/wasmDeref)
+    # mirrors the SAME string literals. When changing a tag here, update
+    # host_runtime.js in lockstep — these constants are the canonical names; the
+    # JS literals are the mirror.
     module WireTags
       # A bridged Ruby object, referenced by its HandleTable id (becomes an ES
       # Proxy on the JS side).