dommy 0.13.0 → 0.15.0

data/lib/dommy/backend.rb

@@ -1,297 +1,362 @@
 # frozen_string_literal: true
 
+require "makiri"
+
 module Dommy
-  # `Dommy::Backend` — pluggable HTML parser abstraction. Lets Dommy
-  # work with Makiri (Lexbor-based, HTML5-only). Internally, all DOM library
-  # code goes through this facade rather than referencing the parser
-  # directly.
-  #
-  # Defaults to Makiri.
-  #
-  # Switching backends:
-  #
-  #   require "dommy"
-  #   Dommy::Backend.use(:makiri)
-  #
-  # Or set directly:
+  # `Dommy::Backend` — what the DOM asks of Makiri, the Lexbor-based parser
+  # that holds every tree. All DOM library code comes through here rather
+  # than reading Makiri's API directly, so what Dommy relies on of it is in
+  # one place: the node classes, the creators, the namespaced attribute
+  # model, and the few normalizations (an empty namespace is none).
   #
-  #   Dommy::Backend.current = Dommy::Backend::Makiri
-  #
-  # All adapters must implement the same interface — see
-  # `Backend::Makiri` for the canonical reference.
+  # Makiri splits its document model into `Makiri::HTML::Document`
+  # (case-folding, html/head/body) and `Makiri::XML::Document`
+  # (case-preserving, namespaces, CDATA); both share the `Makiri::Document` /
+  # `Makiri::Node` bases used here for `is_a?` checks. HTML parses go through
+  # HTML::Document; `new Document()` / createDocument go through XML::Document.
   module Backend
-    class BackendNotAvailable < StandardError
-    end
-
     class << self
-      def current
-        @current ||= detect_default
-      end
+      # The node classes (the shared bases, so both HTML and XML node
+      # subclasses match), so the wrapper cache can route each node.
+      def element_class = ::Makiri::Element
 
-      attr_writer :current
+      def document_class = ::Makiri::Document
 
-      def use(name)
-        @current = case name.to_sym
-        when :makiri
-          require_relative "backend/makiri_adapter"
-          Makiri
-        else
-          raise ArgumentError, "Unknown backend: #{name.inspect}. Use :makiri."
-        end
-      end
+      def text_class = ::Makiri::Text
+
+      def comment_class = ::Makiri::Comment
+
+      # A Text subtype, matched before Text.
+      def cdata_class = ::Makiri::CDATASection
+
+      def processing_instruction_class = ::Makiri::ProcessingInstruction
+
+      def document_fragment_class = ::Makiri::DocumentFragment
+
+      def document_type_class = ::Makiri::DocumentType
 
-      # Stable per-document identity key for a backend node, used to cache DOM
-      # wrappers and key per-node side tables. Makiri mints a fresh wrapper per traversal
-      # but never frees nodes (arena-owned), so it keys on the stable node pointer.
+      def node_class = ::Makiri::Node
+
+      # What Makiri raises for markup that is not well-formed XML (an XML
+      # document's fragment parse included).
+      def xml_syntax_error_class = ::Makiri::XML::SyntaxError
+
+      # Stable per-document identity key for a backend node, used to key
+      # per-node side tables. pointer_id is the underlying lxb_dom_node_t
+      # pointer: Makiri detaches but never frees nodes — the document arena
+      # owns them — so a live node's pointer is never recycled; a freed
+      # document's may be, so a table keyed by it is a document's own.
       def identity_key(node)
-        current.identity_key(node)
+        node.pointer_id
       end
 
       # Deep (or shallow) copy of an element/node, detached and owned by the
-      # same document — the backing for DOM cloneNode.
+      # same document — the backing for DOM cloneNode. Makiri clones natively
+      # (import_node + template fixup), preserving the node's namespace and
+      # attributes and carrying <template> contents.
       def clone_node(node, deep:)
-        current.clone_node(node, deep: deep)
+        node.clone_node(deep)
       end
 
-      # A fresh, empty HTML-backed document.
+      # A fresh, empty HTML-backed document — no children, no-quirks. The
+      # backing for a shallow clone of an HTML document.
       def empty_document
-        current.empty_document
+        ::Makiri::HTML::Document.new
       end
 
-      # A fresh, empty XML-backed document — for `new Document()` / createDocument,
-      # which the DOM defines as XML documents (case-preserving, real CDATA
-      # nodeType, namespaces).
+      # A fresh, empty XML-backed document — the backing for `new Document()` /
+      # createDocument, which the DOM defines as XML documents. An XML backing
+      # gives them case preservation, real CDATA nodes (nodeType 4) and
+      # namespace tracking. Makiri's cross-kind `import_node` translates
+      # between the HTML and XML node representations, so a node created here
+      # can still be adopted into the main HTML tree (and vice versa).
       def empty_xml_document
-        current.empty_xml_document
+        ::Makiri::XML::Document.new
       end
 
-      # An empty backing document matching `doc`'s kind (HTML stays HTML, XML stays
-      # XML) — for a shallow document clone, whose result keeps the source flavor.
+      # Whether the HTML parser left `doc` in quirks mode (not limited-quirks,
+      # which matches no-quirks everywhere Dommy asks). An XML document is
+      # never in it.
+      def quirks_mode?(doc)
+        doc.respond_to?(:quirks_mode?) && doc.quirks_mode?
+      end
+
+      # An empty backing document matching `doc`'s kind (HTML stays HTML, XML
+      # stays XML) — for a shallow document clone, whose result keeps the
+      # source flavor.
       def empty_document_like(doc)
-        current.empty_document_like(doc)
+        doc.is_a?(::Makiri::XML::Document) ? empty_xml_document : empty_document
       end
 
       # Bring `node` (already detached from its old tree) into `target_doc`,
-      # returning the backend node now owned by `target_doc`. Makiri can't move a node
-      # between arenas, so it imports a copy — callers must reseat any wrapper
-      # onto the returned node.
+      # returning the backend node now owned by `target_doc`. Lexbor's arenas
+      # can't move a node between documents, so adoption imports a detached
+      # copy — callers must reseat any wrapper onto the returned node.
+      #
+      # Gap absorption: Lexbor's HTML serializer has no CDATA case (it errors
+      # on a CDATA node) and Lexbor is a pinned upstream submodule, so Makiri's
+      # cross-kind import_node fails closed when bringing an XML CDATASection
+      # into an HTML document. Rather than let that surface as an error,
+      # degrade the node to a text node carrying the same data — the data a
+      # spec-faithful HTML serializer emits anyway (CDATASection is a Text
+      # subtype). The caller reseats the Dommy CDATASection wrapper onto this
+      # node, so `nodeType` stays 4 at the DOM level; only the backing node
+      # (and thus serialization) is text. An XML target keeps a real CDATA
+      # node. This handles a directly adopted CDATA node (a CDATA descendant
+      # inside an adopted element subtree is rare, untested, and still fails
+      # closed in the backend).
       def adopt(node, target_doc)
-        current.adopt(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
-      # therefore crashing — adoption on backends that don't need it.
-      def moves_nodes_across_documents?
-        current.respond_to?(:moves_nodes_across_documents?) ? current.moves_nodes_across_documents? : true
-      end
+        if node.is_a?(::Makiri::CDATASection) && !target_doc.is_a?(::Makiri::XML::Document)
+          return target_doc.create_text_node(node.text)
+        end
 
-      # CSS query that honors Dommy's custom pseudo-classes
-      # (`:disabled`/`:enabled`/`:checked`/`:scope`). Each backend applies its
-      # own mechanism (Lexbor native pseudos plus a
-      # `:scope` rewrite). `scope_node` binds `:scope` to that element.
-      def select_all(node, selector, scope_node: nil)
-        current.select_all(node, selector, scope_node: scope_node)
+        target_doc.import_node(node, true)
       end
 
-      def select_first(node, selector, scope_node: nil)
-        current.select_first(node, selector, scope_node: scope_node)
+      # 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)
+        target_doc.import_node(node, false)
       end
 
-      # Delegate calls so internal code can use `Backend.parse(...)`.
       def parse(html)
-        current.parse(html)
+        ::Makiri::HTML::Document.parse(html.to_s)
       end
 
-      # Parse XML input into an XML document.
-      # fall back to the HTML parser.
+      # XML parse (DOMParser `text/xml` / `application/xml`): a real XML
+      # document, so element/attribute case is preserved, namespaces are
+      # tracked, and CDATA round-trips.
       def parse_xml(xml)
-        current.parse_xml(xml)
+        ::Makiri::XML::Document.parse(xml.to_s)
       end
 
       def fragment(html, owner_doc:)
-        current.fragment(html, owner_doc: owner_doc)
-      end
-
-      # Make `node` the sole document element of `doc` (used by
-      # DOMImplementation.createDocument). Lexbor-backed documents are seeded with an <html> shell
-      # that must be cleared first.
-      def set_document_root(doc, node)
-        current.set_document_root(doc, node)
-      end
-
-      def create_element(name, doc)
-        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).
+        ::Makiri::DocumentFragment.parse(html.to_s)
+      end
+
+      # The DOM's createElement: an element whose local name is `local_name`
+      # as written, colons included (`foo:` and `f::oo` are valid local names,
+      # not prefixed ones), in `namespace` — the HTML namespace in an HTML or
+      # XHTML document, nil in any other. An XML document's own creator parses
+      # a QName, so its element is built from the parts. An HTML-backed one —
+      # which a document typed as XHTML or XML after an HTML parse also is —
+      # makes it by createElementNS, which keeps the name's case and the
+      # namespace given; that splits a name at its colon, and refuses `xmlns`
+      # outside the XMLNS namespace, as createElementNS must — so a name with
+      # a colon, or `xmlns`, takes the HTML document's creator, which keeps
+      # the name as written but folds it into the HTML namespace in lower case.
+      def create_element(local_name, namespace, doc)
+        return doc.create_loose_dom_element(local_name, nil, local_name, namespace) unless doc.is_a?(::Makiri::HTML::Document)
+        return doc.create_element(local_name) if local_name.include?(":") || local_name == "xmlns"
+
+        doc.create_element_ns(namespace, local_name)
+      end
+
+      # The DOM's createElementNS, in an HTML or an XML document alike: the
+      # element is in `namespace` (nil for none) with `qualified_name` as
+      # written — an SVG `feGaussianBlur` keeps its case, a prefixed name its
+      # prefix. Makiri checks the name as the DOM does, so a name the caller
+      # has validated is never refused; it raises ArgumentError for one it
+      # would not have passed.
+      def create_element_ns(namespace, qualified_name, doc)
+        doc.create_element_ns(namespace, qualified_name.to_s)
+      end
+
+      # A detached DocumentType node owned by `doc`, HTML or XML (for
+      # DOMImplementation.createDocumentType). Makiri takes any name the DOM
+      # does but the empty one, which Lexbor reads as no name, and raises
+      # ArgumentError for it; the caller then falls back to a synthetic
+      # (non-tree) DocumentType, 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
+        doc.create_document_type(name.to_s, public_id.to_s, system_id.to_s)
       end
 
-      # The parsed document's DocumentType node, or nil when it declares none.
+      # The parsed document's DocumentType node (`<!DOCTYPE …>`), or nil when
+      # the document 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
+        doc.internal_subset
       end
 
       def create_text(content, doc)
-        current.create_text(content, doc)
+        doc.create_text_node(content)
       end
 
       def create_comment(content, doc)
-        current.create_comment(content, doc)
+        doc.create_comment(content)
       end
 
-      # CDATA section node (XML documents). Backends without CDATA fall back to a
-      # text node.
+      # CDATASection (nodeType 4). A genuine XML document — including a
+      # `new Document()` / createDocument document, XML-backed (see
+      # #empty_xml_document) — mints a real CDATA node and the XML serializer
+      # emits `<![CDATA[…]]>`. `Document#create_cdata_section` rejects HTML
+      # documents up front (NotSupportedError, per spec), so the text-node
+      # fallback below is a defensive guard for an HTML document that still
+      # slips through (Lexbor's HTML serializer raises on a native CDATA node,
+      # so a text node keeps serialization safe).
       def create_cdata(content, doc)
-        current.respond_to?(:create_cdata) ? current.create_cdata(content, doc) : current.create_text(content, doc)
+        if doc.is_a?(::Makiri::XML::Document)
+          doc.create_cdata(content)
+        else
+          doc.create_text_node(content)
+        end
       end
 
-      def cdata_class
-        current.respond_to?(:cdata_class) ? current.cdata_class : nil
+      # ProcessingInstruction node (`<?target data?>`). Both Makiri document
+      # families mint a real PI node and serialize it, so PIs — unlike CDATA —
+      # need no HTML-document fallback.
+      def create_processing_instruction(target, data, doc)
+        doc.create_processing_instruction(target, data)
       end
 
-      # ProcessingInstruction node (`<?target data?>`). Supported by every
-      # backend Dommy ships (both Makiri document families), so — unlike CDATA —
-      # there is no text-node fallback.
-      def create_processing_instruction(target, data, doc)
-        current.create_processing_instruction(target, data, doc)
+      # DOM "child text content": the data of `node`'s Text (and CDATA
+      # section) children, in order — no deeper descendant's.
+      def child_text_content(node)
+        node.children.select { |c| c.text? || c.cdata? }.map(&:content).join
       end
 
-      def processing_instruction_class
-        current.processing_instruction_class
+      # The element's own namespace URI as the DOM reports it (Lexbor's HTML /
+      # SVG / MathML, an XML document's own), nil for none — Makiri answers
+      # nil, never "", for a node without one, parsed or created.
+      def namespace_uri(node)
+        node.namespace_uri
       end
 
-      def namespace_of(node)
-        current.namespace_of(node)
+      # The element's own namespace prefix as the DOM reports it, nil for none.
+      def prefix(node)
+        node.prefix
       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)
+      # Makiri'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)
+        node.respond_to?(:content_fragment) ? node.content_fragment : nil
       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)
+      # ----- Namespaced attributes -----
+      # Lexbor tracks the attribute's own namespace: set_attribute_ns records
+      # it (splitting prefix/local), and the attr node reports
+      # namespace_uri/prefix/local_name. So *AttributeNS matches on
+      # (namespace, local name) faithfully, and Makiri finds an attribute by
+      # that pair natively. `namespace` is an href String or nil throughout,
+      # and Makiri takes "" as none, as the DOM does.
+
+      def get_attribute_ns(node, namespace, local_name)
+        node.attribute_value_ns(namespace, local_name.to_s)
       end
 
-      def add_namespace_definition(node, prefix, href)
-        current.add_namespace_definition(node, prefix, href)
+      def has_attribute_ns?(node, namespace, local_name)
+        !attr_by_ns(node, namespace, local_name).nil?
       end
 
-      # Namespaced attribute access (DOM *AttributeNS). `namespace` is an href
-      # String or nil.
-      def get_attribute_ns(node, namespace, local_name)
-        current.get_attribute_ns(node, namespace, local_name)
+      # The attribute node in `namespace` with `local_name`, or nil — what
+      # getAttributeNodeNS and the NS removals find.
+      def attr_by_ns(node, namespace, local_name)
+        node.attribute_node_ns(namespace, local_name.to_s)
       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)
+      def set_attribute_ns(node, namespace, prefix, _local_name, qualified_name, value)
+        none = namespace.to_s.empty?
+        note_namespaced_unprefixed_attribute if prefix.to_s.empty? && !none
+        name = qualified_name.to_s
+        value = value.to_s
+        node.set_attribute_ns(namespace, name, value) unless none && set_null_namespace_attribute(node, name, value)
+        value
       end
 
-      def remove_attribute_ns(node, namespace, local_name)
-        current.remove_attribute_ns(node, namespace, local_name)
+      # Whether an attribute in a namespace but with no prefix has ever been
+      # made (setAttributeNS("urn:x", "id")). That is the only way an
+      # attribute whose qualified name is a plain `id` or `class` can be in a
+      # namespace — a parser's are either prefixed or, `xmlns` aside, in none —
+      # so until one is made, no element need be asked whether it has one
+      # (Element#namespaced_unprefixed_attribute?, which gates the JS bridge's
+      # attribute snapshot). Process-wide, as an attribute moves between
+      # documents with its node; it only ever decides how fast an answer comes.
+      def note_namespaced_unprefixed_attribute
+        @namespaced_unprefixed_attribute = true
       end
 
-      def has_attribute_ns?(node, namespace, local_name)
-        current.has_attribute_ns?(node, namespace, local_name)
+      def namespaced_unprefixed_attribute?
+        @namespaced_unprefixed_attribute == true
+      end
+
+      # Remove by (namespace, local name) — removing by qualified name is
+      # ambiguous once same-name/different-namespace attributes coexist.
+      def remove_attribute_ns(node, namespace, local_name)
+        node.remove_attribute_ns(namespace, local_name.to_s)
+        nil
       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)
+        {
+          namespace_uri: attr_node.namespace_uri,
+          prefix: attr_node.prefix,
+          local_name: attr_node.local_name,
+          qualified_name: attr_node.name,
+          value: attr_node.value,
+        }
       end
 
       # The attribute node whose QUALIFIED name is `qualified_name`, or nil.
       #
       # WHATWG's by-name family ("get an attribute by name", `setAttribute`,
-      # `removeAttribute`) matches on the qualified name. A lookup by local name
-      # confuses `b` with a prefixed `xml:b`, so those paths must come through
-      # here rather than through `node[name]`.
+      # `removeAttribute`) matches on the qualified name. A lookup by local
+      # name confuses `b` with a prefixed `xml:b`, so those paths must come
+      # through here rather than through `node[name]`. Makiri scans natively.
       def attr_by_qualified_name(node, qualified_name)
-        current.attr_by_qualified_name(node, qualified_name)
+        node.attribute_by_qualified_name(qualified_name.to_s)
       end
 
-      # That attribute's VALUE, or nil when there is no such attribute. The same
-      # match without an attribute node in hand, for the two readers that only
-      # ever wanted the value — `getAttribute` and `hasAttribute` — which run on
-      # every CSS match and every reflected IDL attribute.
+      # That attribute's VALUE, or nil when there is no such attribute. The
+      # same match without an attribute node in hand, for the two readers that
+      # only ever wanted the value — `getAttribute` and `hasAttribute` — which
+      # run on every CSS match and every reflected IDL attribute.
       def attr_value_by_qualified_name(node, qualified_name)
-        current.attr_value_by_qualified_name(node, qualified_name)
+        node.attribute_value_by_qualified_name(qualified_name.to_s)
+      end
+
+      # The value of `node`'s attribute named `local_name` in no namespace, or
+      # nil — what a selector's `[att]` and HTML's id, class and name read, on
+      # the hottest path in the library. One native read, which finds the
+      # attribute by namespace and local name, so a namespaced one that shares
+      # the name (setAttributeNS("u", "att"), a parsed `xmlns`) is not it.
+      def no_namespace_attribute_value(node, local_name)
+        node.attribute_value_ns(nil, local_name)
       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
+        node.attribute_nodes
       end
 
       private
 
-      def detect_default
-        try_makiri ||
-          raise(BackendNotAvailable, "Dommy requires either 'makiri' gem to be installed.")
-      end
-
-      def try_makiri
-        require "makiri"
-
-        require_relative "backend/makiri_adapter"
-        Makiri
-      rescue LoadError
-        nil
+      # 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 `set_loose_dom_attribute`, the DOM's setAttribute, for the
+      # setAttribute-only names, which set_attribute_ns refuses: a plain
+      # attribute in no namespace (never a namespace declaration) whose local
+      # name is the whole name, colon included, lower-cased only on an
+      # HTML-namespace element of an HTML document. 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.
+      def set_null_namespace_attribute(node, name, value)
+        return false unless set_attribute_only_name?(name)
+
+        node.set_loose_dom_attribute(name, value)
+        true
       end
     end
   end

data/lib/dommy/blob.rb

@@ -36,6 +36,13 @@ module Dommy
       @window = window
     end
 
+    # A File of the same bytes and type named `name`, as FormData's "create an
+    # entry" makes of a Blob it is given (named "blob") or of a File given a
+    # filename.
+    def __internal_file_named__(name)
+      File.new([@data], name, {"type" => @type}, @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 = "")

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