dommy 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce9aec097da24f1f6a44792f44615605a1405483b6c6c5183031757d11a0853
-  data.tar.gz: cf7c0e05839c313763590fcdb4d134459f5b1fe91ed1b479f819b18181cf1058
+  metadata.gz: ccbe61a606e042968621f7fa81588634f2cdae566d96cef137bfefdfb6d38dd6
+  data.tar.gz: 4358d9b68082608b7e78971be2d2818fb35200b17bec1819ce21a520b3552d7c
 SHA512:
-  metadata.gz: 0db6e083fb62dd609fd719264a4d35e6bcadd6b97ce8515d08a8a8a53028e1f3f870224ef40ca33240688ddaf782d41e09d261c079c145144fe7b47b83288ef6
-  data.tar.gz: d33e89e420bf0f93c2e478c93dd9241643ee47c40efa40927ff77714f20b92af561330b2cbedcaa287951cd07aab4ecfb899e24371fe8d6e2b20f289f6973b53
+  metadata.gz: a8c9a3b7bbfacb6f58440cbfec8884cc79c8690beda03225b229ca935f1b6d1ce0778c83a9253f2996198e46c8d8b85f9df53ccedb1ffa4e942a5b9841c051e4
+  data.tar.gz: f428a160a4c2f0180e7fa01f8cb1e6ec31dc9855f2bd7b43f1be6abd7a752a6b93926c1e57791a1c8b51a22e62631c997c4fbe8b55ea38fed5748f62cc874033

data/README.md

@@ -1,7 +1,7 @@
 # Dommy
 
-A pure-Ruby DOM polyfill on top of [Nokogiri::HTML5](https://nokogiri.org/) — a Ruby-side analogue to happy-dom / jsdom.
-Dommy exposes browser-like DOM semantics (events, MutationObserver, Custom Elements, Shadow DOM, File API, timers, Storage) so view / component / request specs can verify DOM structure and behavior without spinning up a real browser.
+Dommy is a pure Ruby DOM polyfill built on [Nokogiri::HTML5](https://nokogiri.org/), inspired by happy-dom and jsdom.
+It gives Ruby tests a browser style DOM with events, MutationObserver, Custom Elements, Shadow DOM, the File API, timers, and Storage, without requiring a real browser.
 
 ## Quick start
 
@@ -74,22 +74,24 @@ input.validation_message    #=> "Please fill out this field."
 ### File API (Blob / File / FormData / DataTransfer)
 
 ```ruby
+win = Dommy.parse("<form><input type='file' name='attachment'></form>")
 file = Dommy::File.new(["pdf body"], "doc.pdf", "type" => "application/pdf")
 
 # Seed a file input for tests
-input = dom.query_selector("input[type='file']")
-input.__set_files__([file])
+input = win.document.query_selector("input[type='file']")
+input.__driver_set_files__([file])
 
 # FormData picks it up
-fd = Dommy::FormData.new(dom.query_selector("form"))
+fd = Dommy::FormData.new(win.document.query_selector("form"))
 fd.entries.to_a   #=> [["attachment", #<Dommy::File doc.pdf>]]
 
 # Drag-and-drop simulation
 dt = Dommy::DataTransfer.new(files: [file])
 ev = Dommy::DragEvent.new("drop", "dataTransfer" => dt, "bubbles" => true)
-dropzone.dispatch_event(ev)
+win.document.body.dispatch_event(ev)
 
 # Blob URLs
+blob = Dommy::Blob.new(["blob body"], "type" => "text/plain")
 url = Dommy::URL.create_object_url(blob)   # "blob:dommy/..."
 ```
 
@@ -102,7 +104,7 @@ response = win.__js_call__("fetch", ["/api"]).await
 ```
 
 > [!WARNING]
-> Most Dommy accessors (`Blob#text`, `Response#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is for the JS-bridged async surface.
+> Most Dommy accessors (`Blob#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is only for the JS-bridged async surface (e.g., `fetch()`, `window.__js_call__`). Methods like `Response#text()` are Promise-returning and require `.await`.
 
 ## Test helpers
 
@@ -176,8 +178,7 @@ Supported Capybara-style options: `text:` / `exact:` / `count:` (Integer or Rang
 Implemented:
 
 - Core DOM (Document, Element, Text/Comment/Fragment, NodeList, Attr)
-- 26 specialized HTMLElement subclasses
-- SVG: SVGElement base + ~63 specialized subclasses covering shapes, gradients, marker / mask, the full set of standard filter primitives (Gaussian blur, offset, blend, color matrix, flood, composite, merge, component transfer, tile, morphology, image, drop shadow, turbulence, displacement map, convolve matrix, diffuse / specular lighting + light sources), `<a>` / `<textPath>` / `<view>` / `<switch>` / `<metadata>`, and SMIL animation (`<animate>` / `<animateTransform>` / `<animateMotion>` / `<set>` / `<mpath>` / `<discard>`) — with case-sensitive attribute round-trip
+- Specialized HTML and SVG element classes
 - events with composedPath / AbortSignal
 - MutationObserver (childList / attributes / characterData / subtree)
 - Custom Elements lifecycle
@@ -185,47 +186,38 @@ Implemented:
 - form validation
 - Scheduler (timers + microtasks with `advance_time`)
 - Promise
-- Location / History / URL (WHATWG-leaning parsing with whitespace/tab/newline stripping, percent-encoding of unsafe path chars, `\` → `/` conversion for special schemes, `./` and `../` resolution, IPv4 number forms normalization, ws/wss default port stripping, Punycode hostname encoding, full UTS #46 IDNA with RFC 5893 Bidi and RFC 5892 ContextJ/ContextO)
+- Location / History / URL
 - Storage
-- fetch (stub) / XMLHttpRequest (stub-driven, sync + async, shares the `__fetchy_stub__` fixture map)
-- WebSocket / EventSource — test seams (`__simulate_open__` / `__simulate_message__` / `__simulate_close__`) drive the streams
-- MessageChannel / MessagePort / BroadcastChannel — in-process pub/sub with `structuredClone`-on-transfer
-- FileReader (`readAsText` / `readAsDataURL` / `readAsArrayBuffer` / `readAsBinaryString`)
-- Notification (permission settable via `Notification.__set_permission__`)
-- Geolocation (mock position via `navigator.geolocation.__set_position__`)
-- `window.matchMedia` returning a `MediaQueryList` (`__set_matches__` flips and fires `change`)
-- `requestIdleCallback` / `cancelIdleCallback` (modelled on scheduler), `structuredClone` global
-- `crypto.subtle.digest` (SHA-1/256/384/512), HMAC sign/verify/import/generateKey, and AES-GCM encrypt/decrypt (128/256-bit with additionalData and tagLength options)
-- Streams API (`ReadableStream` / `WritableStream` / `TransformStream` + `TextEncoderStream` / `TextDecoderStream`)
-- `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw via Ruby `Zlib`)
-- Worker (inline-emulated — same-process message round-trip; tests register handlers via `worker.__on_message__`)
-- Performance User Timing (`performance.mark` / `measure` / `getEntriesByName`)
-- `cookieStore` (async Cookie Store API, backed by the same jar `document.cookie` uses)
-- Navigator extras: `share` / `vibrate` / `wakeLock.request` / `getBattery` / `locks` (Web Locks) / `storage.estimate` / `persist` / `persisted` (StorageManager)
-- Layout-adjacent stubs: `element.scrollIntoView` / `scrollTo` / scroll & client / offset metrics (return 0), `getComputedStyle` (inline style passthrough)
-- Popover API (`showPopover` / `hidePopover` / `togglePopover` with `beforetoggle` / `toggle` events)
-- Fullscreen API (`element.requestFullscreen` / `document.exitFullscreen` / `fullscreenchange`)
-- `URLPattern` (pattern matching for URL components — protocol, username, password, hostname, port, pathname, search, hash — with named capture groups and modifiers: `:id`, `*`, `:version+`, `:version?`)
-- `document.startViewTransition` (View Transitions API stub)
+- fetch / XMLHttpRequest stubs
+- WebSocket / EventSource / MessageChannel / BroadcastChannel test doubles
+- FileReader / Notification / Geolocation / `matchMedia`
+- `requestIdleCallback`, `structuredClone`, `URLPattern`
+- Web Crypto, Streams, Compression Streams, Worker
+- `performance`, `cookieStore`, Navigator extras
+- Popover API, Fullscreen API, View Transitions API stub
 - Navigator / Clipboard
 - TreeWalker / NodeIterator / NodeFilter
 - File API (Blob / File / FileList / FormData / DataTransfer)
-- Web Crypto (`crypto.randomUUID`, `getRandomValues`) / TextEncoder / TextDecoder
-- IntersectionObserver / ResizeObserver / PerformanceObserver (test-driven `__trigger__`)
+- IntersectionObserver / ResizeObserver / PerformanceObserver (test-driven `__test_trigger__`)
 - Range / Selection (DOM-level only, no layout)
-- Web Animations API (Animation / KeyframeEffect; lifecycle via scheduler, finished/ready Promises)
+- Web Animations API (Animation / KeyframeEffect)
 - Extended events: Touch / Clipboard / Composition / Wheel / Focus / BeforeUnload / Input / Pointer / Progress / Drag
 
+For implementation notes and tradeoffs, see [design.md](./design.md).
+
 > [!IMPORTANT]
 > Out of scope:
 >
-> - requires a layout / CSS engine or media subsystems: real `getBoundingClientRect` / scroll metrics
-> - CSS scoping (`:host`, `::slotted`, computed styles)
+> - layout and CSS-engine behavior
 > - JS evaluation
 > - Canvas / WebGL / media playback
-> - layout-dependent Range / Selection geometry (`getBoundingClientRect` returns zero rects)
-> - SVG-specific value types (SVGAnimatedLength, SVGTransform, SVGMatrix)
-> - Web Animations: no actual value interpolation — `Animation` is a state machine (`idle` / `running` / `paused` / `finished`) for testing lifecycle and event wiring
+> - layout-dependent Range / Selection geometry
+> - SVG-specific value types
+> - animation value interpolation
+
+## Method naming conventions
+
+See [docs/development.md](./docs/development.md) for method-naming conventions and internal protocols.
 
 ## Running the tests
 

data/lib/dommy/animation.rb

@@ -244,7 +244,7 @@ module Dommy
     end
 
     # Event bubbling stops at Animation — it isn't part of the DOM tree.
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end
 

data/lib/dommy/attr.rb

@@ -28,7 +28,7 @@ module Dommy
 
     def value
       if @owner
-        @owner.__node__[@name].to_s
+        @owner.__dommy_backend_node__[@name].to_s
       else
         @detached_value
       end
@@ -72,6 +72,12 @@ module Dommy
       nil
     end
 
+    # Methods routed through __js_call__ (keep in sync with its when-arms).
+    JS_METHOD_NAMES = %w[cloneNode].freeze
+    def __js_method_names__
+      JS_METHOD_NAMES
+    end
+
     def __js_call__(method, _args)
       case method
       when "cloneNode"
@@ -81,13 +87,13 @@ module Dommy
 
     # Internal: called by Element when the attr is being transferred
     # to (or detached from) an Element.
-    def __attach__(element)
+    def __internal_attach__(element)
       @owner = element
       @detached_value = ""
       nil
     end
 
-    def __detach__
+    def __internal_detach__
       cached = value
       @owner = nil
       @detached_value = cached
@@ -109,19 +115,19 @@ module Dommy
     end
 
     def length
-      @element.__node__.attribute_nodes.size
+      @element.__dommy_backend_node__.attribute_nodes.size
     end
 
     alias size length
 
     def item(index)
-      name = @element.__node__.attribute_nodes[index.to_i]&.name
+      name = @element.__dommy_backend_node__.attribute_nodes[index.to_i]&.name
       name && Attr.new(name, owner: @element)
     end
 
     def get_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
+      return nil unless @element.__dommy_backend_node__.key?(key)
 
       Attr.new(key, owner: @element)
     end
@@ -131,22 +137,22 @@ module Dommy
 
       key = attr.name
       val = attr.value
-      attr.__attach__(@element)
+      attr.__internal_attach__(@element)
       @element.set_attribute(key, val)
       attr
     end
 
     def remove_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
+      return nil unless @element.__dommy_backend_node__.key?(key)
 
-      attr = Attr.new(key, owner: nil, value: @element.__node__[key].to_s)
+      attr = Attr.new(key, owner: nil, value: @element.__dommy_backend_node__[key].to_s)
       @element.remove_attribute(key)
       attr
     end
 
     def each(&blk)
-      @element.__node__.attribute_nodes.each do |a|
+      @element.__dommy_backend_node__.attribute_nodes.each do |a|
         yield Attr.new(a.name, owner: @element)
       end
     end
@@ -175,6 +181,12 @@ module Dommy
       end
     end
 
+    # Methods routed through __js_call__ (keep in sync with its when-arms).
+    JS_METHOD_NAMES = %w[item getNamedItem setNamedItem removeNamedItem].freeze
+    def __js_method_names__
+      JS_METHOD_NAMES
+    end
+
     def __js_call__(method, args)
       case method
       when "item"
@@ -194,7 +206,7 @@ module Dommy
     end
 
     def respond_to_missing?(name, include_private = false)
-      @element.__node__.key?(name.to_s.downcase) || super
+      @element.__dommy_backend_node__.key?(name.to_s.downcase) || super
     end
   end
 end

data/lib/dommy/backend/nokogiri_adapter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Dommy
+  module Backend
+    # Nokogiri (libxml2-based) backend. Mature, full XML namespace
+    # support. Default backend.
+    module Nokogiri
+      # Class references for `is_a?` / type-checking from Dommy internals.
+      Element = ::Nokogiri::XML::Element
+      Document = ::Nokogiri::XML::Document
+      Text = ::Nokogiri::XML::Text
+      Comment = ::Nokogiri::XML::Comment
+      DocumentFragment = ::Nokogiri::XML::DocumentFragment
+      Node = ::Nokogiri::XML::Node
+
+      module_function
+
+      def parse(html)
+        ::Nokogiri::HTML5(html.to_s, max_errors: 0)
+      end
+
+      def fragment(html, owner_doc:)
+        # owner_doc is unused by Nokogiri — the fragment carries its
+        # own document. The Parser layer copies nodes into the target.
+        ::Nokogiri::HTML5.fragment(html.to_s, max_errors: 0)
+      end
+
+      def create_element(name, doc)
+        ::Nokogiri::XML::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokogiri::XML::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        ::Nokogiri::XML::Comment.new(doc, content)
+      end
+
+      def namespace_of(node)
+        node.namespace
+      end
+
+      def add_namespace_definition(node, prefix, href)
+        node.add_namespace_definition(prefix, href)
+      end
+    end
+  end
+end

data/lib/dommy/backend/nokolexbor_adapter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "nokolexbor"
+
+module Dommy
+  module Backend
+    # Nokolexbor (Lexbor-based) backend. 3-7× faster CSS selectors,
+    # 6× faster HTML5 parsing. HTML-only — XML namespaces are not
+    # tracked, so SVG detection falls back to ancestor walking.
+    module Nokolexbor
+      # Class references for `is_a?` / type-checking.
+      Element = ::Nokolexbor::Element
+      Document = ::Nokolexbor::Document
+      Text = ::Nokolexbor::Text
+      Comment = ::Nokolexbor::Comment
+      DocumentFragment = ::Nokolexbor::DocumentFragment
+      Node = ::Nokolexbor::Node
+
+      # Fake "namespace" wrapper returned for nodes inside <svg> subtrees.
+      # Provides the same `href` API that Nokogiri's Namespace object has,
+      # so calling code can treat them uniformly.
+      SvgNamespace = Struct.new(:href) do
+        def initialize
+          super("http://www.w3.org/2000/svg")
+        end
+      end
+
+      SVG_NAMESPACE = SvgNamespace.new.freeze
+
+      module_function
+
+      def parse(html)
+        ::Nokolexbor.parse(html.to_s)
+      end
+
+      def fragment(html, owner_doc:)
+        ::Nokolexbor::DocumentFragment.parse(html.to_s)
+      end
+
+      def create_element(name, doc)
+        ::Nokolexbor::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokolexbor::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        # Nokolexbor's argument order is (content, doc).
+        ::Nokolexbor::Comment.new(content, doc)
+      end
+
+      # Nokolexbor doesn't track XML namespaces. We synthesize one for
+      # SVG by walking ancestors — necessary so `element_class_for`
+      # routes SVG tags to their specialized classes.
+      def namespace_of(node)
+        return nil unless node.respond_to?(:name)
+
+        in_svg_subtree?(node) ? SVG_NAMESPACE : nil
+      end
+
+      def add_namespace_definition(_node, _prefix, _href)
+        # No-op: Nokolexbor doesn't support XML namespaces.
+      end
+
+      # Internal helper — visible to allow testing.
+      def in_svg_subtree?(node)
+        return true if node.name.to_s.downcase == "svg"
+
+        current = node.parent
+        while current
+          return true if current.respond_to?(:name) && current.name.to_s.downcase == "svg"
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/dommy/backend.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `Dommy::Backend` — pluggable HTML parser abstraction. Lets Dommy
+  # work with either Nokogiri (mature, full namespace support) or
+  # Nokolexbor (faster, HTML5-only). Internally, all DOM library
+  # code goes through this facade rather than referencing the parser
+  # directly.
+  #
+  # Defaults to Nokogiri if available, else Nokolexbor.
+  #
+  # Switching backends:
+  #
+  #   require "dommy"
+  #   Dommy::Backend.use(:nokolexbor)
+  #
+  # Or set directly:
+  #
+  #   Dommy::Backend.current = Dommy::Backend::Nokolexbor
+  #
+  # All adapters must implement the same interface — see
+  # `Backend::Nokogiri` for the canonical reference.
+  module Backend
+    class BackendNotAvailable < StandardError
+    end
+
+    class << self
+      def current
+        @current ||= detect_default
+      end
+
+      attr_writer :current
+
+      def use(name)
+        @current = case name.to_sym
+        when :nokogiri
+          require_relative "backend/nokogiri_adapter"
+          Nokogiri
+        when :nokolexbor
+          require_relative "backend/nokolexbor_adapter"
+          Nokolexbor
+        else
+          raise ArgumentError, "Unknown backend: #{name.inspect}. Use :nokogiri or :nokolexbor."
+        end
+      end
+
+      # Delegate calls so internal code can use `Backend.parse(...)`.
+      def parse(html)
+        current.parse(html)
+      end
+
+      def fragment(html, owner_doc:)
+        current.fragment(html, owner_doc: owner_doc)
+      end
+
+      def create_element(name, doc)
+        current.create_element(name, doc)
+      end
+
+      def create_text(content, doc)
+        current.create_text(content, doc)
+      end
+
+      def create_comment(content, doc)
+        current.create_comment(content, doc)
+      end
+
+      def namespace_of(node)
+        current.namespace_of(node)
+      end
+
+      def add_namespace_definition(node, prefix, href)
+        current.add_namespace_definition(node, prefix, href)
+      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
+      end
+
+      private
+
+      def detect_default
+        try_nokogiri ||
+          try_nokolexbor ||
+          raise(BackendNotAvailable, "Dommy requires either 'nokogiri' or 'nokolexbor' gem to be installed.")
+      end
+
+      def try_nokogiri
+        require "nokogiri"
+
+        require_relative "backend/nokogiri_adapter"
+        Nokogiri
+      rescue LoadError
+        nil
+      end
+
+      def try_nokolexbor
+        require "nokolexbor"
+
+        require_relative "backend/nokolexbor_adapter"
+        Nokolexbor
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/blob.rb

@@ -48,7 +48,7 @@ module Dommy
 
     # Raw binary bytes (Ruby ASCII-8BIT string). Used by FormData /
     # fetch when serializing multipart bodies.
-    def __bytes__
+    def __dommy_bytes__
       @data
     end
 
@@ -79,7 +79,7 @@ module Dommy
       parts.each do |part|
         case part
         when Blob
-          buf << part.__bytes__
+          buf << part.__dommy_bytes__
         when String
           buf << part.dup.force_encoding(Encoding::ASCII_8BIT)
         when Array

data/lib/dommy/compression_streams.rb

@@ -31,9 +31,9 @@ module Dommy
           "close" => proc do
             compressed = compressor.call(@buffer)
             controller.enqueue(compressed)
-            @readable.__close__
+            @readable.__internal_close__
           end,
-          "abort" => proc { |r| @readable.__error__(r) }
+          "abort" => proc { |r| @readable.__internal_error__(r) }
         }
       )
     end
@@ -98,9 +98,9 @@ module Dommy
           "close" => proc do
             plain = decompressor.call(@buffer)
             controller.enqueue(plain)
-            @readable.__close__
+            @readable.__internal_close__
           end,
-          "abort" => proc { |r| @readable.__error__(r) }
+          "abort" => proc { |r| @readable.__internal_error__(r) }
         }
       )
     end

data/lib/dommy/cookie_store.rb

@@ -79,7 +79,7 @@ module Dommy
       end
     end
 
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end
 

data/lib/dommy/crypto.rb

@@ -182,7 +182,7 @@ module Dommy
         raise ArgumentError, "HMAC key required" unless key.is_a?(CryptoKey) && key.algorithm_name == "HMAC"
         raise ArgumentError, "key.usages must include 'sign'" unless key.usages.include?("sign")
 
-        OpenSSL::HMAC.digest(openssl_digest_name(key.hash_name), key.__bytes__, coerce_bytes(data)).bytes
+        OpenSSL::HMAC.digest(openssl_digest_name(key.hash_name), key.__dommy_bytes__, coerce_bytes(data)).bytes
       end
     end
 
@@ -192,7 +192,7 @@ module Dommy
         raise ArgumentError, "HMAC key required" unless key.is_a?(CryptoKey) && key.algorithm_name == "HMAC"
         raise ArgumentError, "key.usages must include 'verify'" unless key.usages.include?("verify")
 
-        expected = OpenSSL::HMAC.digest(openssl_digest_name(key.hash_name), key.__bytes__, coerce_bytes(data))
+        expected = OpenSSL::HMAC.digest(openssl_digest_name(key.hash_name), key.__dommy_bytes__, coerce_bytes(data))
         sig_bytes = coerce_bytes(signature)
         if expected.bytesize == sig_bytes.bytesize
           OpenSSL.fixed_length_secure_compare(expected, sig_bytes)
@@ -327,7 +327,7 @@ module Dommy
     end
 
     def build_gcm_cipher(direction, algorithm, key)
-      raw_key = key.is_a?(CryptoKey) ? key.__bytes__ : coerce_bytes(key)
+      raw_key = key.is_a?(CryptoKey) ? key.__dommy_bytes__ : coerce_bytes(key)
       raise ArgumentError, "AES-GCM key must be 16/24/32 bytes" unless [16, 24, 32].include?(raw_key.bytesize)
 
       iv = algorithm.is_a?(Hash) ? (algorithm["iv"] || algorithm[:iv]) : nil
@@ -359,9 +359,9 @@ module Dommy
   end
 
   # `CryptoKey` — opaque key handle returned by SubtleCrypto.
-  # `extractable: false` keys reject export attempts; the
-  # `__bytes__` accessor stays internal-only (`__double_underscore__`
-  # convention) so production code paths can't read the raw bytes.
+  # `extractable: false` keys reject export attempts; the raw bytes are
+  # reachable only through the `__dommy_bytes__` ecosystem accessor, never
+  # the public (Web-mirroring) API.
   class CryptoKey
     attr_reader :type, :algorithm_name, :hash_name, :usages, :extractable
 
@@ -374,8 +374,9 @@ module Dommy
       @usages = usages.map(&:to_s).freeze
     end
 
-    # Test / internal seam — production callers should not reach in.
-    def __bytes__
+    # Low-level ecosystem accessor (see __dommy_ convention) — the public
+    # Web API never exposes raw key bytes.
+    def __dommy_bytes__
       @bytes
     end
 

data/lib/dommy/css.rb

@@ -63,7 +63,7 @@ module Dommy
       idx = index.nil? ? @css_rules.length : index.to_i
       raise DOMException::IndexSizeError, "out of range" if idx < 0 || idx > @css_rules.length
 
-      @css_rules.__insert__(idx, CSSRule.new(rule_text.to_s, self))
+      @css_rules.__internal_insert__(idx, CSSRule.new(rule_text.to_s, self))
       idx
     end
 
@@ -71,17 +71,17 @@ module Dommy
       idx = index.to_i
       raise DOMException::IndexSizeError, "out of range" if idx < 0 || idx >= @css_rules.length
 
-      @css_rules.__delete_at__(idx)
+      @css_rules.__internal_delete_at__(idx)
       nil
     end
 
     # `replaceSync(text)` — replace all rules with a single rule blob
     # (no parsing — we keep it as one opaque entry).
     def replace_sync(text)
-      @css_rules.__clear__
+      @css_rules.__internal_clear__
       return nil if text.to_s.empty?
 
-      @css_rules.__insert__(0, CSSRule.new(text.to_s, self))
+      @css_rules.__internal_insert__(0, CSSRule.new(text.to_s, self))
       nil
     end
 
@@ -173,15 +173,15 @@ module Dommy
       @rules.dup
     end
 
-    def __insert__(index, rule)
+    def __internal_insert__(index, rule)
       @rules.insert(index, rule)
     end
 
-    def __delete_at__(index)
+    def __internal_delete_at__(index)
       @rules.delete_at(index)
     end
 
-    def __clear__
+    def __internal_clear__
       @rules.clear
     end