dommy-js-quickjs 0.1.0

data/lib/dommy/js/constructor_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Resolves a JS constructor by interface name for reverse construction
+    # (`new Event(...)`, `new DOMException(...)`). The window object is the
+    # source for most constructors — it exposes them via __js_get__ — while a
+    # few not on the window are provided directly. Engine-agnostic.
+    class ConstructorRegistry
+      # The window whose __js_get__ exposes Event/CustomEvent/MouseEvent/… .
+      attr_writer :source
+
+      def initialize
+        @source = nil
+      end
+
+      # An object responding to __js_new__ for `name`, or nil if `name` isn't
+      # constructable (the bridge then makes the JS side throw).
+      def resolve(name)
+        if @source.respond_to?(:__js_get__)
+          ctor = @source.__js_get__(name)
+          return ctor if ctor.respond_to?(:__js_new__)
+        end
+        extra(name)
+      end
+
+      private
+
+      # Constructors the window doesn't expose.
+      def extra(name)
+        case name
+        when "DOMException"
+          return unless defined?(Dommy::DOMException)
+
+          Dommy::Bridge::Constructor.new { |args| Dommy::DOMException.new(args[0], args[1] || "Error") }
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/custom_elements.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Bridges JS-defined custom elements to Dommy's custom element pipeline.
+    # `customElements.define(name, JSClass)` on the JS side calls in here, which
+    # registers a Dommy::HTMLElement subclass for `name` whose lifecycle
+    # reactions (connected/disconnected/adopted/attributeChanged) route back to
+    # the JS instance through the bridge. The JS class's constructor itself runs
+    # on the JS side via the construction-stack upgrade in host_runtime.js.
+    class CustomElements
+      attr_writer :window
+
+      def initialize(bridge)
+        @bridge = bridge
+        @window = nil
+      end
+
+      def define(name, observed)
+        return unless @window.respond_to?(:custom_elements)
+
+        @window.custom_elements.define(name, build_class(name, observed))
+        nil
+      end
+
+      # customElements.upgrade(root): delegate to Dommy's registry so a subtree
+      # attached without firing reactions gets its registered elements upgraded.
+      def upgrade(root)
+        return unless @window.respond_to?(:custom_elements)
+
+        @window.custom_elements.upgrade(root)
+        nil
+      end
+
+      private
+
+      # A Dommy custom element class that forwards each reaction to the JS
+      # instance. `__js_custom_element_name__` marks the node so the bridge tells
+      # the JS side to upgrade it on first crossing (see HostBridge interface info).
+      def build_class(name, observed)
+        bridge = @bridge
+        Class.new(Dommy::HTMLElement) do
+          define_singleton_method(:observed_attributes) { observed }
+          define_method(:__js_custom_element_name__) { name }
+          define_method(:connected_callback) { bridge.invoke_lifecycle(self, "connectedCallback", []) }
+          define_method(:disconnected_callback) { bridge.invoke_lifecycle(self, "disconnectedCallback", []) }
+          define_method(:adopted_callback) { bridge.invoke_lifecycle(self, "adoptedCallback", []) }
+          define_method(:attribute_changed_callback) do |attr, old_value, new_value|
+            bridge.invoke_lifecycle(self, "attributeChangedCallback", [attr, old_value, new_value])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/dom_interfaces.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Derives WebIDL interface metadata for a Dommy DOM object: the most-derived
+    # interface name and the single-inheritance chain up to the root
+    # (EventTarget for nodes). This mirrors the JS prototype chain the bridge
+    # builds so `instanceof` / Object.prototype.toString resolve correctly.
+    #
+    # Engine-agnostic, and the single home for DOM interface hierarchy knowledge:
+    # BASE_CHAINS (seeded eagerly on the JS side) must stay consistent with what
+    # #chain_for derives from real objects.
+    module DomInterfaces
+      # Dommy class basename -> WebIDL interface name, where they diverge.
+      # Anything not listed uses the class basename verbatim (HTMLDivElement, …).
+      NAME_OVERRIDES = {
+        "TextNode" => "Text",
+        "CommentNode" => "Comment",
+        "CharacterDataNode" => "CharacterData",
+        "Fragment" => "DocumentFragment",
+        "ClassList" => "DOMTokenList",
+        "DatasetMap" => "DOMStringMap",
+        "StyleDeclaration" => "CSSStyleDeclaration",
+        "LiveNodeList" => "NodeList",
+        "StandaloneEventTarget" => "EventTarget"
+      }.freeze
+
+      # Concrete HTML element interfaces. A browser exposes every one of these as
+      # a global constructor whether or not an instance exists, so a framework's
+      # bare `instanceof HTMLInputElement` feature check resolves regardless of
+      # page content (idiomorph, Turbo's morph engine, probes `instanceof
+      # HTMLInputElement`/`HTMLTextAreaElement` during focus restoration even when
+      # the page has no such element). Each is a direct HTMLElement subclass
+      # except the two media leaves, appended with their chains below. Mirrors the
+      # `class HTMLxxxElement < HTMLElement` set in the dommy gem's html_elements.
+      HTML_LEAF_INTERFACES = %w[
+        HTMLAnchorElement HTMLAreaElement HTMLBaseElement HTMLBodyElement
+        HTMLBRElement HTMLButtonElement HTMLDataElement HTMLDetailsElement
+        HTMLDialogElement HTMLDivElement HTMLEmbedElement HTMLFieldsetElement
+        HTMLFormElement HTMLHeadElement HTMLHeadingElement HTMLHRElement
+        HTMLHtmlElement HTMLIFrameElement HTMLImageElement HTMLInputElement
+        HTMLLabelElement HTMLLegendElement HTMLLIElement HTMLLinkElement
+        HTMLMapElement HTMLMetaElement HTMLMeterElement HTMLModElement
+        HTMLObjectElement HTMLOListElement HTMLOptGroupElement HTMLOptionElement
+        HTMLOutputElement HTMLParagraphElement HTMLPictureElement HTMLPreElement
+        HTMLProgressElement HTMLQuoteElement HTMLScriptElement HTMLSelectElement
+        HTMLSlotElement HTMLSourceElement HTMLSpanElement HTMLStyleElement
+        HTMLTableCaptionElement HTMLTableCellElement HTMLTableElement
+        HTMLTableRowElement HTMLTableSectionElement HTMLTemplateElement
+        HTMLTextAreaElement HTMLTimeElement HTMLTitleElement HTMLTrackElement
+        HTMLUListElement
+      ].freeze
+
+      # Base interface chains seeded eagerly on the JS side so `instanceof Node`
+      # / `typeof HTMLElement` resolve before an instance of that exact type has
+      # crossed. Concrete leaves (HTMLButtonElement, …) are built lazily from
+      # #chain_for when an instance crosses. Keep consistent with #chain_for.
+      BASE_CHAINS = [
+        %w[Node EventTarget],
+        %w[Element Node EventTarget],
+        %w[HTMLElement Element Node EventTarget],
+        %w[SVGElement Element Node EventTarget],
+        %w[CharacterData Node EventTarget],
+        %w[Text CharacterData Node EventTarget],
+        %w[Comment CharacterData Node EventTarget],
+        %w[Document Node EventTarget],
+        %w[DocumentFragment Node EventTarget],
+        %w[DocumentType Node EventTarget],
+        %w[Attr Node EventTarget],
+        %w[Event],
+        %w[CustomEvent Event],
+        %w[MessageEvent Event],
+        %w[PopStateEvent Event],
+        %w[CloseEvent Event],
+        %w[MouseEvent Event],
+        %w[KeyboardEvent Event],
+        %w[DOMException],
+        # Window-exposed constructors that frameworks call bare (new X(...)).
+        # Seeding them creates the global; construction routes to the window.
+        %w[MutationObserver], %w[IntersectionObserver], %w[ResizeObserver],
+        %w[PerformanceObserver], %w[AbortController], %w[AbortSignal EventTarget],
+        %w[FormData], %w[URL], %w[URLSearchParams], %w[Headers], %w[Request], %w[Response],
+        %w[Blob], %w[File], %w[FileList], %w[FileReader], %w[XMLHttpRequest],
+        %w[TextEncoder], %w[TextDecoder], %w[DOMParser], %w[XMLSerializer],
+        %w[MessageChannel], %w[BroadcastChannel], %w[WebSocket], %w[EventSource],
+        %w[Notification], %w[Worker], %w[DataTransfer],
+        %w[ReadableStream], %w[WritableStream], %w[TransformStream],
+        %w[Range],
+        # Collection interfaces, seeded so `result instanceof NodeList` /
+        # `instanceof HTMLCollection` resolve (querySelectorAll, children, …).
+        %w[NodeList], %w[HTMLCollection],
+        # Traversal: NodeFilter exposes only [Constant]s (NodeFilter.SHOW_ELEMENT,
+        # .FILTER_ACCEPT, …); TreeWalker/NodeIterator are instances.
+        %w[NodeFilter], %w[TreeWalker], %w[NodeIterator],
+        # Concrete HTML element interfaces (see HTML_LEAF_INTERFACES) + the media
+        # subtree, so bare `instanceof HTMLInputElement` always resolves.
+        *HTML_LEAF_INTERFACES.map { |n| [n, "HTMLElement", "Element", "Node", "EventTarget"] },
+        %w[HTMLMediaElement HTMLElement Element Node EventTarget],
+        %w[HTMLAudioElement HTMLMediaElement HTMLElement Element Node EventTarget],
+        %w[HTMLVideoElement HTMLMediaElement HTMLElement Element Node EventTarget]
+      ].freeze
+
+      module_function
+
+      # { "name" => most-derived interface, "chain" => [...] } for a host object.
+      def info(obj)
+        chain = chain_for(obj)
+        {"name" => chain.first, "chain" => chain}
+      end
+
+      # Walk the Dommy class superclass chain (HTMLDivElement < HTMLElement <
+      # Element), then append the module-provided base interfaces (Node ->
+      # EventTarget) for nodes, since Dommy models Node as a mixin rather than a
+      # superclass. Stops at the first foreign superclass (Object, or
+      # StandardError for DOMException) so non-DOM ancestors stay out.
+      def chain_for(obj)
+        names = []
+        klass = obj.class
+        while klass && klass.name&.start_with?("Dommy::")
+          name = name_for(klass)
+          names << name if name && !names.include?(name)
+          klass = klass.superclass
+        end
+        if defined?(Dommy::Node) && obj.is_a?(Dommy::Node)
+          names << "Node" unless names.include?("Node")
+          names << "EventTarget" unless names.include?("EventTarget")
+        end
+        names
+      end
+
+      def name_for(klass)
+        base = klass.name&.split("::")&.last
+        return nil unless base
+
+        NAME_OVERRIDES.fetch(base, base)
+      end
+    end
+  end
+end

data/lib/dommy/js/handle_table.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Maps JS-facing integer handles to live Ruby objects. Engine-agnostic.
+    #
+    # Handles are monotonic — never reused — so a handle can never refer to two
+    # different objects over the table's lifetime. That invariant is what makes
+    # GC-driven #release race-free: a finalizer releasing handle N can't clobber
+    # a different object that happened to get the same id.
+    #
+    # The same Ruby object reuses its handle while still registered (keyed by
+    # object_id), so it maps to a single JS proxy (stable identity). A registry
+    # entry also keeps the object reachable while JS holds a proxy for it.
+    class HandleTable
+      def initialize
+        @by_handle = {}      # handle (Integer) -> object
+        @handle_by_oid = {}  # object_id -> handle (for identity reuse)
+        @next_handle = 0
+      end
+
+      def register(obj)
+        oid = obj.object_id
+        existing = @handle_by_oid[oid]
+        return existing if existing && @by_handle[existing].equal?(obj)
+
+        handle = (@next_handle += 1)
+        @by_handle[handle] = obj
+        @handle_by_oid[oid] = handle
+        handle
+      end
+
+      def fetch(handle)
+        @by_handle.fetch(handle.to_i)
+      end
+
+      # Forget a handle (called when its JS proxy is garbage-collected). Only
+      # trims the mapping; the object itself lives on via its other references.
+      def release(handle)
+        obj = @by_handle.delete(handle.to_i)
+        return unless obj
+
+        oid = obj.object_id
+        @handle_by_oid.delete(oid) if @handle_by_oid[oid] == handle.to_i
+      end
+
+      def size
+        @by_handle.size
+      end
+    end
+  end
+end