dommy 0.8.0 → 0.9.0

data/lib/dommy/js/runtime.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # The Runtime port: the contract a JS engine must satisfy to drive a Dommy
+    # DOM. `Dommy::Browser` and `Dommy::Js::ScriptBoot` depend on this interface,
+    # never on a concrete engine — so a backend (QuickJS today, others later) is
+    # a pluggable implementation registered through `Dommy::Js.register_runtime`.
+    #
+    # This module is documentation + a conformance check, not a base class:
+    # engines satisfy it by duck typing (no inheritance), and `conforms?` /
+    # `assert_conformance!` verify the surface so a partial backend fails fast
+    # with a clear message instead of an obscure NoMethodError mid-boot.
+    #
+    # The contract, as the host layer uses it:
+    #
+    #   Lifecycle / wiring
+    #     install_window(window)        seed the realm's window globals + DOM
+    #     install_browser_globals       CSS / fetch / addEventListener / ...
+    #     define_host_object(name, obj) expose a Ruby object under a JS global
+    #     on_unhandled_rejection { |e } observe uncaught promise rejections
+    #     on_log { |entry| }            observe console.* output
+    #     dispose                       tear down the realm
+    #
+    #   Script boot (driven by ScriptBoot)
+    #     set_document_ready_state(s)   replay loading/interactive/complete
+    #     module_loader = callable      install the ESM resolver Proc
+    #     load_script(js)               run a classic inline script
+    #     load_script_cached(js, cache_key:)  run external script, cache bytecode
+    #     load_module_url(url)          run an ES module by URL
+    #
+    #   Driving / settling
+    #     execute(js)                   run for side effects
+    #     evaluate(js)                  run and decode the result
+    #     settle                        drain microtasks + due-now timers + rAF
+    #     drain_microtasks              drain the microtask queue only
+    #
+    # Optional (a backend may omit these; callers must guard with respond_to?):
+    #     install_wasm_memory_shim      opt-in WPT SharedArrayBuffer scaffolding
+    module Runtime
+      # The methods every conforming runtime must respond to.
+      REQUIRED_METHODS = %i[
+        install_window install_browser_globals define_host_object
+        on_unhandled_rejection on_log dispose
+        set_document_ready_state module_loader= load_script load_script_cached load_module_url
+        execute evaluate settle drain_microtasks
+      ].freeze
+
+      # Methods a backend may implement but is not required to.
+      #   on_callback_error { |e } observe a timer/rAF callback the engine
+      #                            force-killed (runaway loop); recorded, not fatal
+      OPTIONAL_METHODS = %i[install_wasm_memory_shim on_callback_error].freeze
+
+      module_function
+
+      # The required methods `obj` does not respond to (empty when conforming).
+      def missing_methods(obj)
+        REQUIRED_METHODS.reject { |m| obj.respond_to?(m) }
+      end
+
+      def conforms?(obj) = missing_methods(obj).empty?
+
+      # Raise unless `obj` satisfies the contract, naming what is missing.
+      def assert_conformance!(obj)
+        missing = missing_methods(obj)
+        return obj if missing.empty?
+
+        raise ArgumentError,
+          "#{obj.class} is not a conforming Dommy::Js::Runtime " \
+          "(missing: #{missing.join(", ")})"
+      end
+    end
+
+    # Registry of JS runtime backends, keyed by name. A backend gem registers a
+    # factory on load (e.g. dommy-js-quickjs registers :quickjs); the host layer
+    # builds runtimes through `build_runtime` instead of naming a concrete class.
+    @runtime_factories = {}
+    @default_runtime = nil
+
+    class << self
+      # The name of the backend `build_runtime` uses when none is given. Set by
+      # the first backend to register (and overridable by the host).
+      attr_accessor :default_runtime
+
+      # Register a runtime factory under `name`. The factory receives the keyword
+      # options passed to `build_runtime` and must return an object satisfying
+      # the Runtime contract. The first registration becomes the default.
+      def register_runtime(name, &factory)
+        raise ArgumentError, "a factory block is required" unless factory
+
+        @runtime_factories[name.to_sym] = factory
+        @default_runtime ||= name.to_sym
+        name.to_sym
+      end
+
+      def runtime_registered?(name) = @runtime_factories.key?(name.to_sym)
+
+      def registered_runtimes = @runtime_factories.keys
+
+      # Build a runtime from the named backend (or the default), passing `opts`
+      # to its factory. Verifies the result conforms before handing it back.
+      def build_runtime(name = nil, **opts)
+        name = (name || @default_runtime)&.to_sym
+        factory = @runtime_factories[name]
+        unless factory
+          raise ArgumentError,
+            "unknown JS runtime backend #{name.inspect} " \
+            "(registered: #{registered_runtimes.inspect})"
+        end
+
+        Runtime.assert_conformance!(factory.call(**opts))
+      end
+    end
+  end
+end

data/lib/dommy/js/script_boot.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Boot a parsed document's `<script>` tags like a browser: run them in two
+    # passes that mirror the HTML spec, set `document.currentScript` around each,
+    # and replay the readyState lifecycle so ready-gated startup code (Stimulus /
+    # Turbo / jQuery ready) takes the real path.
+    #
+    #   loading -> parser-blocking classic scripts (document order)
+    #           -> deferred scripts: modules + classic `defer` (document order)
+    #           -> interactive (DOMContentLoaded)
+    #           -> complete (load)
+    #
+    # The two passes matter: a `<script type="module">` is *deferred* — it must
+    # run after the parser-inserted classic scripts even when it appears earlier
+    # in the document (e.g. a Nuxt entry module placed above the inline
+    # `window.__NUXT__ = {...}` bootstrap it depends on). Running everything in
+    # one document-order pass would execute the module against half-initialized
+    # globals. A failed fetch or a throwing script is isolated; `on_error` is
+    # notified (the Browser collects it for strict mode, the Capybara adapter
+    # ignores it) so the rest of the page still loads. Shared by `Dommy::Browser`
+    # and the Capybara driver so script boot lives in one place.
+    #
+    # The module is the stable entry point; the work lives on ScriptBooter, a
+    # short-lived instance that holds the runtime / document / resources /
+    # on_error collaborators so they aren't threaded through every step.
+    module ScriptBoot
+      module_function
+
+      def run_document_scripts(runtime, document, resources: nil, on_error: nil, on_script: nil)
+        ScriptBooter.new(runtime, document, resources: resources, on_error: on_error, on_script: on_script).run
+      end
+
+      # Fetch + execute a single `<script src>` that was dynamically inserted into
+      # an already-booted document (webpack/Vite on-demand chunk loading), then
+      # fire its load / error event so the loader's promise settles.
+      def run_external_script(runtime, document, element, src, resources: nil, on_error: nil)
+        ScriptBooter.new(runtime, document, resources: resources, on_error: on_error).run_inserted_external(element, src)
+      end
+    end
+
+    # One document's script-boot run. Instantiated per boot by ScriptBoot; the
+    # collaborators are ivars so the per-script steps take only what varies.
+    class ScriptBooter
+      def initialize(runtime, document, resources: nil, on_error: nil, on_script: nil)
+        @runtime = runtime
+        @document = document
+        @resources = resources
+        @on_error = on_error
+        @on_script = on_script
+        @loader = nil
+      end
+
+      def run
+        @runtime.set_document_ready_state("loading")
+        @loader = install_module_loader
+        scripts = @document.scripts.to_a
+        # Pass 1: parser-blocking classic scripts, in document order.
+        scripts.each { |element| run_one(element) unless deferred?(element) }
+        # Pass 2: deferred scripts (modules + classic `defer`), in document order.
+        scripts.each { |element| run_one(element) if deferred?(element) }
+        @runtime.set_document_ready_state("interactive")
+        @runtime.set_document_ready_state("complete")
+      end
+
+      # Fetch + run a dynamically-inserted external script, then fire `load` (or
+      # `error` if the fetch failed / it threw) so a loader awaiting the script
+      # element's onload resolves. The src was already taken from the element by
+      # the mutation coordinator, so this does not re-consume pending state.
+      def run_inserted_external(element, src)
+        ran = false
+        if @resources && (url = resolve_url(src)) && (response = @resources.get(url)) && response.success?
+          with_current_script(element) { @runtime.load_script_cached(response.body, cache_key: url) }
+          ran = true
+        end
+        dispatch_script_event(element, ran ? "load" : "error")
+      rescue StandardError => e
+        @on_error&.call(e)
+        dispatch_script_event(element, "error")
+      end
+
+      private
+
+      # Fire the script's load/error event ASYNCHRONOUSLY (a microtask), like a
+      # real browser. Code commonly does `head.appendChild(s); s.onload = …`
+      # (handlers set AFTER insertion), so a synchronous dispatch — during the
+      # appendChild — would fire before any handler is attached and be missed,
+      # hanging a loader that awaits onload (e.g. note.com's gtag plugin, which
+      # blocked Nuxt hydration). Deferring to a microtask lets the handler attach
+      # first.
+      def dispatch_script_event(element, type)
+        return unless element.respond_to?(:dispatch_event)
+
+        fire = proc { element.dispatch_event(Dommy::Event.new(type)) rescue nil }
+        scheduler = (@document.default_view&.scheduler if @document.respond_to?(:default_view))
+        scheduler ? scheduler.queue_microtask(fire) : fire.call
+      end
+
+      # Whether the element runs in the deferred pass rather than at its parse
+      # position. Module scripts are always deferred; a classic script is
+      # deferred only with a `src` and the `defer` attribute (inline classic
+      # scripts ignore `defer`). `async` opts out of deferral — it runs as soon
+      # as it is available, which in this synchronous model is the first pass.
+      def deferred?(element)
+        return false if element.async
+
+        module_script?(element) || (external?(element) && element.defer)
+      end
+
+      def module_script?(element) = element.type.to_s.strip.downcase == "module"
+      def external?(element) = !element.src.to_s.empty?
+
+      # Wire the ESM resolver before any module runs: parse the page's first
+      # <script type="importmap">, then resolve bare specifiers through it and
+      # fetch module sources through `resources`. Returns the loader so inline
+      # modules can be seeded under a document URL.
+      def install_module_loader
+        loader = ModuleLoader.new(@resources, parse_import_map, base_url: document_base)
+        # The engine requires a Proc specifically.
+        @runtime.module_loader = ->(specifier, importer) { loader.call(specifier, importer) }
+        loader
+      end
+
+      def parse_import_map
+        el = @document.scripts.find { |s| s.type.to_s.strip.downcase == "importmap" }
+        ImportMap.parse(el ? el.text : "")
+      end
+
+      # Run one <script> element and, only when it actually had pending work,
+      # notify `on_script` (element, error) — success with nil, failure with the
+      # raised error (alongside the existing `on_error`). Skipped/non-classic
+      # elements (no pending body/src/module) are not reported.
+      def run_one(element)
+        @on_script.call(element, nil) if run_pending(element) && @on_script
+      rescue StandardError => e
+        @on_error&.call(e)
+        @on_script&.call(element, e)
+      end
+
+      # Execute the element's pending inline body / external src / module, and
+      # return whether any of them matched (so run_one knows a script ran).
+      def run_pending(element)
+        if (body = element.__internal_take_pending_script__)
+          with_current_script(element) { @runtime.load_script(body) }
+        elsif (src = element.__internal_take_pending_src__)
+          run_external(element, src)
+        elsif (mod = element.__internal_take_pending_module__)
+          run_module(mod)
+        else
+          return false
+        end
+        true
+      end
+
+      # An ES module script. `currentScript` is null for modules (spec), so it
+      # is not set. An inline body is seeded under the document URL (so its
+      # relative imports resolve against the page) and pinned to the page's
+      # `import.meta.url`: the engine derives import.meta.url from the module's
+      # unique cache key, which carries a `#dommy-inline-N` fragment for a
+      # second inline module, so we set `import.meta.url` (writable) to the
+      # clean page URL up front. An external module loads by its own URL.
+      def run_module(mod)
+        kind, value = mod
+        if kind == :inline
+          base = inline_base
+          # No newline, so the original body's line numbers are preserved.
+          body = "import.meta.url = #{base.to_json}; #{value}"
+          @runtime.load_module_url(@loader.seed_inline(base, body))
+        elsif (url = resolve_url(value))
+          @runtime.load_module_url(url)
+        end
+      end
+
+      # The page URL an inline module is identified by (its import.meta.url and
+      # the base for its relative imports).
+      def inline_base
+        base = document_base
+        base.empty? ? "about:blank" : base
+      end
+
+      def run_external(element, src)
+        return unless @resources
+
+        url = resolve_url(src)
+        return unless url
+
+        response = @resources.get(url)
+        return unless response&.success?
+
+        # Cache the compiled bytecode by URL: vendored bundles re-parse on
+        # every fresh VM otherwise.
+        with_current_script(element) { @runtime.load_script_cached(response.body, cache_key: url) }
+      end
+
+      # Resolve a script's `src` against the document's base URL, which is the
+      # realm's own location (correct for frames too).
+      def resolve_url(src)
+        ::URI.join(document_base, src).to_s
+      rescue ::URI::InvalidURIError
+        nil
+      end
+
+      # The document's effective base URL string: its `<base>`-derived base
+      # URI, falling back to the realm's own location. Empty string when
+      # neither is set (callers decide their own fallback).
+      def document_base
+        base = @document.base_uri
+        base = @document.url if base.to_s.empty?
+        base.to_s
+      end
+
+      def with_current_script(element)
+        @document.__internal_set_current_script__(element)
+        yield
+      ensure
+        @document.__internal_set_current_script__(nil)
+      end
+    end
+  end
+end

data/lib/dommy/js/wire_tags.rb

@@ -0,0 +1,62 @@
+# 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.
+    #
+    # 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).
+      HANDLE = "__rb_handle"
+      # The host object's WebIDL interface name, carried alongside its handle so
+      # makeProxy can reuse a cached per-interface descriptor (prototype chain +
+      # method set) instead of a `__rb_host_describe` round trip per new proxy —
+      # the dominant overhead when JS traverses/builds many nodes.
+      INTERFACE = "__rb_if"
+      # The custom-element tag of a handle whose node is a registered custom
+      # element (so makeProxy upgrades it), carried per-instance since it is the
+      # one part of a describe that is NOT per-interface.
+      CUSTOM_ELEMENT = "__rb_ce"
+      # A live JS function that crossed into Ruby, referenced by callback id.
+      CALLBACK = "__rb_callback"
+      # An opaque JS value referenced by its id in the JS-side `jsRefs` table
+      # (shared by the Proxy and wasm bridges). See Dommy::Bridge::JSValue.
+      JS_REF = "__rb_js_ref"
+      # A human-readable label captured alongside a JS ref (for #to_s/#inspect).
+      JS_LABEL = "__rb_js_label"
+      # Marks a JS ref that implements the EventListener interface (handleEvent).
+      HANDLE_EVENT = "__rb_handle_event"
+      # Marks a JS ref that implements the NodeFilter interface (acceptNode).
+      ACCEPT_NODE = "__rb_accept_node"
+      # The JS `undefined` value (distinct from null / Ruby nil).
+      UNDEFINED = "__rb_undefined"
+      # A genuinely-absent property: marshals to JS `undefined` as a value, but the
+      # proxy reports it MISSING for the `in` operator (distinct from UNDEFINED,
+      # which is present-but-undefined). See Dommy::Bridge::ABSENT.
+      ABSENT = "__rb_absent"
+      # A byte buffer crossing as a JS Uint8Array.
+      BYTES = "__rb_bytes"
+      # A byte buffer crossing as a bare JS ArrayBuffer.
+      ARRAY_BUFFER = "__rb_arraybuffer"
+      # A host-raised DOMException/TypeError/RangeError, re-thrown JS-side.
+      EXCEPTION = "__rb_exception__"
+      # A host-created native JS error (TypeError/RangeError) crossing as a VALUE
+      # — not thrown — so e.g. a promise rejected with it has a reason that is a
+      # real `instanceof TypeError`. Rehydrates to the error object itself.
+      ERROR_VALUE = "__rb_error_value"
+      # An arbitrary host-thrown value, re-thrown JS-side verbatim.
+      THROW = "__rb_throw__"
+      # A callback whose JS invocation threw (the thrown value is carried here).
+      CALLBACK_THREW = "__rb_cb_threw__"
+    end
+  end
+end

data/lib/dommy/location.rb

@@ -35,6 +35,8 @@ module Dommy
         URI(@origin).scheme ? "#{URI(@origin).scheme}:" : ""
       when "port"
         (URI(@origin).port || 80).to_s
+      else
+        Bridge::ABSENT
       end
     end
 

data/lib/dommy/media_query_list.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "internal/css/media_query"
+
 module Dommy
   # `MediaQueryList` — what `window.matchMedia(query)` returns.
   #
-  # Dommy has no layout / viewport, so `matches` is `false` by default.
-  # Tests drive media query changes via `__test_set_matches__(bool)`, which
-  # flips the boolean and fires a `change` event — exactly the surface
+  # `matches` evaluates the query against the window's media environment
+  # (viewport 1280x720 by default; see Window#resize_to). When the
+  # environment changes, the window notifies every list it handed out and a
+  # `change` event fires for those whose result flipped.
+  #
+  # `__test_set_matches__(bool)` remains as a test seam: it forces the
+  # match state (overriding evaluation) and fires `change` — the surface
   # libraries like Material-UI / Bootstrap / @testing-library consult.
   #
   # Spec: https://drafts.csswg.org/cssom-view/#mediaquerylist
@@ -17,12 +23,16 @@ module Dommy
     def initialize(window, query)
       @window = window
       @media = query.to_s
-      @matches = false
+      @forced = nil
       @onchange = nil
+      @last_matches = evaluate
+      window.__internal_register_media_query_list__(self) if window.respond_to?(:__internal_register_media_query_list__)
     end
 
     def matches
-      @matches
+      return @forced unless @forced.nil?
+
+      @last_matches = evaluate
     end
 
     alias matches? matches
@@ -40,13 +50,26 @@ module Dommy
 
     alias removeListener remove_listener
 
-    # Test seam: flip the match state and dispatch a `change` event so
-    # subscribers re-render.
+    # Test seam: force the match state (evaluation is bypassed from then
+    # on) and dispatch a `change` event so subscribers re-render.
     def __test_set_matches__(value)
-      return if @matches == !!value
+      return if matches == !!value
 
-      @matches = !!value
-      dispatch_event(MediaQueryListEvent.new("change", "matches" => @matches, "media" => @media))
+      @forced = !!value
+      dispatch_change(@forced)
+      nil
+    end
+
+    # Called by the window when the media environment changed (resize etc.).
+    # Fires `change` when the evaluated result flipped; a forced value wins.
+    def __internal_environment_changed__
+      return unless @forced.nil?
+
+      current = evaluate
+      return if current == @last_matches
+
+      @last_matches = current
+      dispatch_change(current)
       nil
     end
 
@@ -55,9 +78,11 @@ module Dommy
       when "media"
         @media
       when "matches"
-        @matches
+        matches
       when "onchange"
         @onchange
+      else
+        Bridge::ABSENT
       end
     end
 
@@ -75,13 +100,14 @@ module Dommy
     end
 
     include Bridge::Methods
+    # `matches` is a read-only attribute (boolean), exposed through __js_get__ —
+    # not a method. Listing it here would shadow the getter with a callable, so
+    # `mql.matches` would evaluate to a function instead of the boolean.
     js_methods %w[
-      matches addListener removeListener addEventListener removeEventListener dispatchEvent
+      addListener removeListener addEventListener removeEventListener dispatchEvent
     ]
     def __js_call__(method, args)
       case method
-      when "matches"
-        @matches
       when "addListener"
         add_listener(args[0])
       when "removeListener"
@@ -98,6 +124,16 @@ module Dommy
     def __internal_event_parent__
       nil
     end
+
+    private
+
+    def evaluate
+      Internal::CSS::MediaQuery.match?(@media, @window.media_environment)
+    end
+
+    def dispatch_change(matches)
+      dispatch_event(MediaQueryListEvent.new("change", "matches" => matches, "media" => @media))
+    end
   end
 
   # `MediaQueryListEvent` — the `change` event payload.

data/lib/dommy/message_channel.rb

@@ -2,8 +2,11 @@
 
 module Dommy
   # `MessageChannel` — creates a pair of `MessagePort`s connected to
-  # each other. `port1.postMessage(x)` queues a microtask that fires
-  # a `message` event on `port2`, and vice versa.
+  # each other. `port1.postMessage(x)` queues a TASK (the "post message" task
+  # source, not a microtask) that fires a `message` event on `port2`, and vice
+  # versa — so the message is delivered in a later event-loop turn, after the
+  # current task's microtask checkpoint. React's scheduler relies on this to
+  # yield as a macrotask.
   #
   # Spec: https://html.spec.whatwg.org/multipage/web-messaging.html
   class MessageChannel
@@ -22,6 +25,8 @@ module Dommy
         @port1
       when "port2"
         @port2
+      else
+        Bridge::ABSENT
       end
     end
   end
@@ -47,7 +52,10 @@ module Dommy
       port = @entangled
       return unless port
 
-      @window.scheduler.queue_microtask(
+      # The "post message" task source — a task, NOT a microtask, so delivery
+      # happens in a later event-loop turn (after the current task's microtask
+      # checkpoint), matching browsers.
+      @window.scheduler.set_timeout(
         proc do
           evt = MessageEvent.new("message", "data" => Dommy.structured_clone(data))
           if port.__internal_started?
@@ -55,7 +63,8 @@ module Dommy
           else
             port.__internal_enqueue__(evt)
           end
-        end
+        end,
+        0
       )
 
       nil
@@ -88,6 +97,8 @@ module Dommy
       case key
       when "onmessage"
         @onmessage
+      else
+        Bridge::ABSENT
       end
     end
 
@@ -209,10 +220,13 @@ module Dommy
       peers = @@registries[@window][@name].reject { |p| p.equal?(self) || p.closed? }
       cloned = Dommy.structured_clone(data)
       peers.each do |peer|
-        @window.scheduler.queue_microtask(
+        # A task (post message task source), not a microtask — delivered in a
+        # later turn like a real BroadcastChannel.
+        @window.scheduler.set_timeout(
           proc do
             peer.dispatch_event(MessageEvent.new("message", "data" => cloned))
-          end
+          end,
+          0
         )
       end
 
@@ -239,6 +253,8 @@ module Dommy
         @name
       when "onmessage"
         @onmessage
+      else
+        Bridge::ABSENT
       end
     end
 

data/lib/dommy/minitest/assertions.rb

@@ -79,6 +79,21 @@ module Dommy
         refute_includes(actual_classes, class_name.to_s, msg)
       end
 
+      # Assert the scope contains an element with computed ARIA role `role`
+      # (+ optional accessible name / level). Walks the accessibility tree, so
+      # aria-hidden / invisible elements are excluded.
+      def assert_dom_has_role(scope, role, name: nil, level: nil, count: nil, exact: false, msg: nil)
+        matched = dom_roles_for(scope, role, name: name, level: level, exact: exact)
+        msg ||= "expected to find role #{role.to_s.inspect}#{role_clause(name, level, count)}, found #{matched.size}"
+        assert(Internal::DomMatching.count_matches?(matched.size, count), msg)
+      end
+
+      def refute_dom_has_role(scope, role, name: nil, level: nil, count: nil, exact: false, msg: nil)
+        matched = dom_roles_for(scope, role, name: name, level: level, exact: exact)
+        msg ||= "expected NOT to find role #{role.to_s.inspect}#{role_clause(name, level, nil)}, found #{matched.size}"
+        refute(Internal::DomMatching.count_matches?(matched.size, count), msg)
+      end
+
       def assert_dom_html_equal(scope, expected_html, msg: nil)
         scope = Internal::ScopeResolution.resolve(scope)
         actual_n = Internal::DomMatching.normalize_html(Internal::DomMatching.html_of(scope))
@@ -100,6 +115,18 @@ module Dommy
       def dom_text_of(scope)
         Internal::DomMatching.text_of(Internal::ScopeResolution.resolve(scope))
       end
+
+      def dom_roles_for(scope, role, name:, level:, exact:)
+        Interaction::RoleQuery.match(Internal::ScopeResolution.resolve(scope), role: role, name: name, level: level, exact: exact)
+      end
+
+      def role_clause(name, level, count)
+        clause = +""
+        clause << " named #{name.inspect}" if name
+        clause << " at level #{level}" if level
+        clause << " (count: #{count.inspect})" if count
+        clause
+      end
     end
   end
 end