dommy-js-quickjs 0.1.0 → 0.9.0

data/lib/dommy/js/dom_interfaces.rb

@@ -1,139 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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

data/lib/dommy/js/host_bridge.rb

@@ -1,400 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Dommy
-  module Js
-    # Engine-agnostic core of the JS<->Ruby DOM bridge. Given a `backend` that
-    # can evaluate JS, register Ruby host functions, and call back into JS,
-    # HostBridge exposes a Ruby object to the JS side as an ES Proxy whose
-    # property/method access routes into the bridge ABI:
-    #   __js_get__(name) / __js_set__(name, value) / __js_call__(method, args)
-    #
-    # Nothing here is QuickJS-specific; this layer is intended to move into a
-    # future `dommy-js` gem with QuickJS/wasm backends plugged in underneath.
-    #
-    # Two collaborators keep the marshalling core free of DOM specifics:
-    #   DomInterfaces       — interface name/chain derivation (instanceof support)
-    #   ConstructorRegistry — `new Event(...)` style reverse construction
-    #
-    # Backend contract:
-    #   backend.eval(js)                         -> evaluate top-level JS
-    #   backend.define_host_function(name) { }   -> expose a Ruby block as a JS global
-    #   backend.call_js(path, *args)             -> invoke a JS global function by path
-    #
-    # The host object must implement __js_get__/__js_set__/__js_call__, and the
-    # bridge needs to know which names are methods (callable via __js_call__)
-    # vs. properties (read via __js_get__) — see #method_names.
-    class HostBridge
-      # JS half of the bridge (globalThis.__rbHost). Read from a companion file
-      # so it stays lintable/highlightable rather than buried in a heredoc.
-      # ::File — inside module Dommy, bare `File` resolves to Dommy::File (the
-      # File API class), not Ruby's file class.
-      HOST_RUNTIME_JS = ::File.read(::File.join(__dir__, "host_runtime.js")).freeze
-      # The WICG Observable polyfill (Observable/Subscriber + EventTarget.when),
-      # evaluated after the DOM interface prototypes are seeded.
-      OBSERVABLE_RUNTIME_JS = ::File.read(::File.join(__dir__, "observable_runtime.js")).freeze
-
-      def initialize(backend)
-        @backend = backend
-        @handles = HandleTable.new
-        @callback_objects = {}
-        @constructors = ConstructorRegistry.new
-        @custom_elements = CustomElements.new(self)
-        @microtask_procs = {}
-        @microtask_seq = 0
-        install!
-      end
-
-      # Bind a Ruby object to a JS global of the given name.
-      def define_host_object(name, obj)
-        handle = @handles.register(obj)
-        @backend.eval("globalThis[#{name.to_s.to_json}] = __rbHost.makeProxy(#{handle}); undefined;")
-        obj
-      end
-
-      # Bind the window the bridge draws on for JS constructors (new Event(...))
-      # and custom element registration. Called by Runtime#install_window — kept
-      # distinct from define_host_object so the generic binder has no hidden
-      # side effects.
-      def window=(win)
-        @constructors.source = win
-        @custom_elements.window = win
-        # Now that constructors are resolvable, expose their static methods
-        # (URL.createObjectURL, …) on the seeded interface globals, and expose
-        # the constructors themselves on the window proxy (window.Node,
-        # document.defaultView.DOMException, …).
-        @backend.call_js("__rbHost.attachStatics")
-        @backend.call_js("__rbHost.exposeConstructorsOnWindow")
-        # Route Dommy's host-side microtasks (MutationObserver delivery, …) onto
-        # the engine's native promise-job queue, so they interleave FIFO with JS
-        # `await`/Promise reactions instead of draining on a separate pass (which
-        # would deliver e.g. MutationObserver records only after `await
-        # Promise.resolve()`, batching several mutations into one callback).
-        if win.respond_to?(:scheduler) && win.scheduler.respond_to?(:native_microtask_scheduler=)
-          win.scheduler.native_microtask_scheduler = ->(callback) { schedule_native_microtask(callback) }
-        end
-      end
-
-      # Enqueue a Ruby callback as a NATIVE microtask (a resolved-promise job), so
-      # it runs in FIFO order with the engine's other promise jobs.
-      def schedule_native_microtask(callback)
-        id = (@microtask_seq += 1)
-        @microtask_procs[id] = callback
-        @backend.call_js("__rbHost.scheduleMicrotask", id)
-        nil
-      end
-
-      # Expose the seeded interface constructors (Element, Node, DOMException, …)
-      # on a secondary window object — an iframe's contentWindow — so cross-window
-      # `instanceof subWin.Element` and `subDoc.defaultView.DOMException` resolve
-      # to the same constructors the top window uses. Idempotent per window.
-      def expose_constructors_on(window_obj)
-        handle = @handles.register(window_obj)
-        # Retain the proxy in a JS-side registry: the constructors are defined as
-        # own properties on the proxy's target, so the proxy must stay alive (and
-        # keep its handle) — otherwise GC releases it and a later
-        # `iframe.contentWindow` rebuilds a fresh, constructor-less proxy.
-        @backend.eval(<<~JS)
-          (globalThis.__rbSubWindows ||= []).push(__rbHost.makeProxy(#{handle}));
-          __rbHost.exposeConstructorsOnWindow(globalThis.__rbSubWindows.at(-1));
-        JS
-        window_obj
-      end
-
-      # Invoke a JS custom element lifecycle callback (connectedCallback etc.) for
-      # a Dommy node. Called by the bridged custom element class (see CustomElements).
-      def invoke_lifecycle(node, callback, args)
-        handle = @handles.register(node)
-        unwrap(@backend.call_js("__rbHost.invokeLifecycle", handle, callback, wrap(Array(args))))
-      end
-
-      # Invoke a retained live JS function by id (used by HostCallback). The JS
-      # side returns a `dehydrate`d (tagged) value, so unwrap it back to Ruby:
-      # a callback that returns e.g. a Promise proxy must come back as the live
-      # PromiseValue, otherwise Dommy can't adopt it (breaking
-      # `fetch().then(r => r.json()).then(…)` chains).
-      def invoke_callback(id, args, this_arg = nil)
-        unwrap(@backend.call_js("__rbHost.invokeCallback", id, wrap(Array(args)), wrap(this_arg)))
-      end
-
-      # Turn a JS-side tagged value (produced by __rbHost.tag) back into Ruby:
-      # tagged handles become the original Ruby DOM objects. Used for return
-      # values that may contain DOM nodes (e.g. evaluate_script).
-      def decode(tagged)
-        unwrap(tagged)
-      end
-
-      # Number of live handle entries. Introspection for lifetime tests.
-      def registered_count
-        @handles.size
-      end
-
-      private
-
-      def install!
-        @backend.define_host_function("__rb_host_get") do |handle, prop|
-          dom_guard do
-            obj = host(handle)
-            wrap(obj.respond_to?(:__js_get__) ? obj.__js_get__(prop) : nil)
-          end
-        end
-        @backend.define_host_function("__rb_host_set") do |handle, prop, value|
-          # Returns whether Dommy handled the write as a DOM property. When it
-          # didn't (or the object has no __js_set__), the JS side keeps the value
-          # as an expando (preserving object/instance field identity). Wrapped in
-          # dom_guard so a throwing setter (e.g. `documentElement.outerHTML = …` →
-          # NoModificationAllowedError) crosses as a tagged exception the JS set
-          # trap re-throws, rather than escaping as a raw Ruby error.
-          dom_guard do
-            obj = host(handle)
-            obj.respond_to?(:__js_set__) ? dommy_handled?(obj.__js_set__(prop, unwrap(value))) : false
-          end
-        end
-        @backend.define_host_function("__rb_host_call") do |handle, method, args|
-          dom_guard do
-            obj = host(handle)
-            obj.respond_to?(:__js_call__) ? wrap(obj.__js_call__(method, unwrap(args))) : nil
-          end
-        end
-        # 2d: one call returns everything makeProxy needs — interface name +
-        # chain, method names, and the custom element tag (if any).
-        @backend.define_host_function("__rb_host_describe") do |handle|
-          obj = host(handle)
-          info = DomInterfaces.info(obj)
-          info["methods"] = method_names(obj)
-          # Mark JS-defined custom elements so makeProxy upgrades them on crossing.
-          info["ce"] = obj.__js_custom_element_name__ if obj.respond_to?(:__js_custom_element_name__)
-          info
-        end
-        @backend.define_host_function("__rb_release_handle") do |handle|
-          @handles.release(handle)
-          nil
-        end
-        # Run a Ruby microtask previously registered by schedule_native_microtask,
-        # invoked from the resolved-promise job scheduleMicrotask queued.
-        @backend.define_host_function("__rb_run_microtask") do |id|
-          callback = @microtask_procs.delete(id)
-          callback&.call
-          nil
-        end
-        # WebIDL "supported property names" for a legacy platform object (a live
-        # array-like/maplike collection): the current ordered named-property
-        # keys. Queried per ownKeys / getOwnPropertyDescriptor so it tracks DOM
-        # mutations. Nil when the object has no named getter.
-        @backend.define_host_function("__rb_named_props") do |handle|
-          obj = host(handle)
-          obj.respond_to?(:__js_named_props__) ? Array(obj.__js_named_props__).map(&:to_s) : nil
-        end
-        # Named deleter (`delete el.dataset.foo`): true when the object handled
-        # the delete, false/UNHANDLED when the JS side should fall back to its
-        # own (expando) delete.
-        @backend.define_host_function("__rb_host_delete") do |handle, prop|
-          dom_guard do
-            obj = host(handle)
-            obj.respond_to?(:__js_delete__) ? dommy_handled?(obj.__js_delete__(prop)) : false
-          end
-        end
-        # `new Event(...)` / `new DOMException(...)` from a bare interface
-        # constructor — resolve the named constructor and build. Returns nil when
-        # the interface isn't constructable, so the JS side throws.
-        @backend.define_host_function("__rb_construct") do |name, args|
-          dom_guard do
-            ctor = @constructors.resolve(name)
-            ctor ? wrap(ctor.__js_new__(unwrap(args))) : nil
-          end
-        end
-        # Static/class methods on an interface constructor (URL.createObjectURL,
-        # URL.parse, …): names to expose, and the dispatch.
-        @backend.define_host_function("__rb_static_names") do |name|
-          ctor = @constructors.resolve(name)
-          ctor.respond_to?(:__js_class_method_names__) ? ctor.__js_class_method_names__ : []
-        end
-        @backend.define_host_function("__rb_static_call") do |name, method, args|
-          dom_guard do
-            ctor = @constructors.resolve(name)
-            ctor.respond_to?(:__js_call__) ? wrap(ctor.__js_call__(method, unwrap(args))) : nil
-          end
-        end
-        # 1d: customElements.define(name, JSClass) wires a Dommy custom element.
-        @backend.define_host_function("__rb_define_custom_element") do |name, observed|
-          @custom_elements.define(name, Array(observed))
-          nil
-        end
-        # 1d: customElements.upgrade(root) — delegate to Dommy's registry.
-        @backend.define_host_function("__rb_upgrade_custom_elements") do |handle|
-          @custom_elements.upgrade(host(handle))
-          nil
-        end
-        @backend.eval(HOST_RUNTIME_JS)
-        # Seed base interface prototypes from the single Ruby-side hierarchy.
-        @backend.eval("__rbHost.seedInterfaces(#{JSON.generate(DomInterfaces::BASE_CHAINS)});")
-        # Observable depends on EventTarget.prototype existing (seeded above).
-        @backend.eval(OBSERVABLE_RUNTIME_JS)
-      end
-
-      def host(handle)
-        @handles.fetch(handle)
-      end
-
-      # Run a host-function body, converting a raised Dommy::DOMException into a
-      # tagged marker that the JS side (rehydrate) re-throws as a real
-      # DOMException (name + legacy code, `instanceof DOMException`). Otherwise
-      # the quickjs gem flattens it to a plain Error — no name/code — which
-      # breaks `assert_throws_dom` and every DOM error contract (removeChild
-      # NotFoundError, classList SyntaxError/InvalidCharacterError, …).
-      def dom_guard
-        yield
-      rescue Dommy::Bridge::ThrowValue => e
-        # A host method threw an arbitrary value (e.g. throwIfAborted's reason);
-        # re-throw it verbatim JS-side, identity preserved.
-        {"__rb_throw__" => wrap(e.value)}
-      rescue Dommy::DOMException => e
-        {"__rb_exception__" => {"name" => e.name, "message" => e.message, "code" => e.code}}
-      rescue Dommy::Bridge::TypeError => e
-        # A deliberate, spec-mandated JS TypeError (e.g. `new URL(bad)`). Tagged
-        # so rehydrate rethrows a real `TypeError` — `assert_throws_js(TypeError,
-        # …)` checks `instanceof TypeError`, which a DOMException/Error fails.
-        {"__rb_exception__" => {"name" => "TypeError", "message" => e.message, "js_native" => true}}
-      rescue Dommy::Bridge::RangeError => e
-        # A spec-mandated JS RangeError (e.g. `new Response(b, {status: 42})`).
-        {"__rb_exception__" => {"name" => "RangeError", "message" => e.message, "js_native" => true}}
-      end
-
-      # Ruby -> JS: tag bridge-able objects so the JS side can proxy them.
-      # Recurses Array and Hash so nested DOM nodes are tagged too (symmetric
-      # with #unwrap).
-      def wrap(value)
-        # A `__js_call__` may return the UNDEFINED sentinel for a void op; marshal
-        # it so the JS side yields `undefined` rather than `null`.
-        if defined?(Dommy::Bridge::UNDEFINED) && value.equal?(Dommy::Bridge::UNDEFINED)
-          return {"__rb_undefined" => true}
-        end
-        # A byte buffer tagged ArrayBuffer crosses back as a bare ArrayBuffer
-        # (checked before Bytes, since ArrayBuffer < Bytes).
-        if defined?(Dommy::Bridge::ArrayBuffer) && value.is_a?(Dommy::Bridge::ArrayBuffer)
-          return {"__rb_arraybuffer" => value.to_a}
-        end
-        # A byte buffer crosses back as a JS Uint8Array.
-        if defined?(Dommy::Bridge::Bytes) && value.is_a?(Dommy::Bridge::Bytes)
-          return {"__rb_bytes" => value.to_a}
-        end
-        # An opaque JS value returns as its original JS object (identity kept).
-        if defined?(Dommy::Bridge::JSValue) && value.is_a?(Dommy::Bridge::JSValue)
-          return {"__rb_js_ref" => value.ref}
-        end
-
-        case value
-        when Array
-          value.map { |element| wrap(element) }
-        when Hash
-          value.transform_values { |element| wrap(element) }
-        when HostCallback
-          # A JS function that crossed into Ruby returns as the same live JS
-          # function (not a proxy), so callbacks nested in objects round-trip.
-          {"__rb_callback" => value.id}
-        else
-          if bridgeable?(value)
-            {"__rb_handle" => @handles.register(value)}
-          else
-            value
-          end
-        end
-      end
-
-      # A value crosses as a proxy if it implements any of the bridge ABI — not
-      # only __js_get__: method-only objects (observers) and constructors expose
-      # __js_call__ / __js_new__ without properties.
-      def bridgeable?(value)
-        value.respond_to?(:__js_get__) ||
-          value.respond_to?(:__js_call__) ||
-          value.respond_to?(:__js_new__)
-      end
-
-      # JS -> Ruby: rebuild tagged handles / callbacks into Ruby objects.
-      def unwrap(value)
-        case value
-        when Array
-          value.map { |element| unwrap(element) }
-        when Hash
-          if value.key?("__rb_handle")
-            host(value["__rb_handle"])
-          elsif value.key?("__rb_callback")
-            id = value["__rb_callback"]
-            @callback_objects[id] ||= HostCallback.new(self, id)
-          elsif value.key?("__rb_js_ref")
-            # An opaque JS value (a non-plain object Ruby just stores and returns,
-            # e.g. an abort reason) — kept as a handle so it round-trips with
-            # identity rather than being flattened to a Hash.
-            if defined?(Dommy::Bridge::JSValue)
-              Dommy::Bridge::JSValue.new(value["__rb_js_ref"], value["__rb_js_label"])
-            else
-              value
-            end
-          elsif value.key?("__rb_undefined")
-            # A top-level JS `undefined` argument — distinct from JS null (nil).
-            defined?(Dommy::Bridge::UNDEFINED) ? Dommy::Bridge::UNDEFINED : nil
-          elsif value.key?("__rb_bytes")
-            # A JS ArrayBuffer / TypedArray argument arrives as a byte buffer.
-            defined?(Dommy::Bridge::Bytes) ? Dommy::Bridge::Bytes.new(value["__rb_bytes"]) : value["__rb_bytes"]
-          else
-            value.transform_values { |element| unwrap(element) }
-          end
-        when :undefined
-          # A raw JS `undefined` (e.g. a property-set value, which crosses via
-          # `dehydrate` rather than the tagged `dehydrateArgs`) reaches Ruby as
-          # the gem's `:undefined` symbol. Normalize it to the same sentinel a
-          # tagged top-level undefined produces, so setters can distinguish it
-          # from `null` (e.g. `el.ariaLabel = undefined` removes the attribute).
-          defined?(Dommy::Bridge::UNDEFINED) ? Dommy::Bridge::UNDEFINED : nil
-        else
-          value
-        end
-      end
-
-      # Which property names should be treated as callable methods. The ABI
-      # keeps properties (__js_get__) and methods (__js_call__) in disjoint
-      # namespaces, so the proxy asks the object to self-describe via the bridge
-      # ABI method __js_method_names__. method_defined? (not respond_to?) avoids
-      # classes whose respond_to_missing? answers true for arbitrary names (e.g.
-      # StyleDeclaration's CSS-property accessors).
-      def method_names(obj)
-        return [] unless obj.class.method_defined?(:__js_method_names__)
-
-        Array(obj.__js_method_names__).map(&:to_s)
-      end
-
-      # Did Dommy treat a __js_set__ as a real DOM property? A returned UNHANDLED
-      # sentinel means "no" (the JS side then keeps it as an expando). Tolerant of
-      # older Dommy without the sentinel (treats everything as handled).
-      def dommy_handled?(result)
-        !(defined?(Dommy::Bridge::UNHANDLED) && result == Dommy::Bridge::UNHANDLED)
-      end
-    end
-
-    # An event listener backed by a live JS function. Implements only the bridge
-    # ABI (__js_call__) — not #call/#handle_event — so Dommy's invoke_listener
-    # routes through the __js_call__("call", [event]) branch.
-    class HostCallback
-      attr_reader :id
-
-      def initialize(bridge, id)
-        @bridge = bridge
-        @id = id
-      end
-
-      def __js_call__(method, args)
-        return nil unless method == "call"
-
-        @bridge.invoke_callback(@id, args)
-      end
-
-      # Invoke with an explicit `this` receiver — e.g. a MutationObserver
-      # callback whose `this` must be the observer, or an event listener whose
-      # `this` is the currentTarget.
-      def __js_call_with_this__(args, this_arg)
-        @bridge.invoke_callback(@id, args, this_arg)
-      end
-    end
-  end
-end