dommy 0.10.0 → 0.12.0

data/lib/dommy/document.rb

@@ -7,6 +7,7 @@ require_relative "internal/mutation_coordinator"
 require_relative "internal/shadow_root_registry"
 require_relative "internal/cookie_jar"
 require_relative "internal/node_traversal"
+require_relative "internal/node_adopter"
 require_relative "internal/observer_manager"
 require_relative "internal/template_content_registry"
 
@@ -25,6 +26,12 @@ module Dommy
   #    so it stays tree-DISCONNECTED per its detached nature.
   class DocumentType
     include Node
+    include Internal::LeafNode
+    # A node-backed doctype is an ordinary ChildNode of the document, so
+    # `before` / `after` / `replaceWith` go through the shared implementation —
+    # which runs the parent's ensure-pre-insertion-validity and the live-range
+    # insert steps, neither of which the old doctype-specific path did.
+    include Internal::ChildNode
 
     # Mixed into a node-backed doctype only, so a synthetic one does NOT respond
     # to `__dommy_backend_node__` — leaving the Node mixin's guards (which key off
@@ -59,6 +66,14 @@ module Dommy
       @document || @owner_document
     end
 
+    # A doctype answers `document` from either of two ivars (a synthetic one has
+    # only `@owner_document`), so an adopt has to move both.
+    def __internal_reseat__(backend_node, document)
+      super
+      @owner_document = document
+      nil
+    end
+
     def name
       @__node__ ? @__node__.name : @name
     end
@@ -93,26 +108,44 @@ module Dommy
     end
 
     def before(*nodes)
-      return nil unless @owner_document
+      return synthetic_insert(nodes, after: false) unless @__node__
 
-      @owner_document.__internal_insert_at_doctype__(nodes, after: false)
-      nil
+      child_node_before(nodes)
     end
 
     def after(*nodes)
-      return nil unless @owner_document
+      return synthetic_insert(nodes, after: true) unless @__node__
 
-      @owner_document.__internal_insert_at_doctype__(nodes, after: true)
-      nil
+      child_node_after(nodes)
     end
 
     def replace_with(*nodes)
+      unless @__node__
+        synthetic_insert(nodes, after: false)
+        remove
+        return nil
+      end
+
+      child_node_replace_with(nodes)
+    end
+
+    # A synthetic doctype — the fallback for a backend that cannot create a
+    # doctype node — is not in the tree at all, so WHATWG's ChildNode methods
+    # would return at step 2. Dommy has always inserted around the document
+    # element instead; that stays until the fallback goes away.
+    def synthetic_insert(nodes, after:)
       return nil unless @owner_document
 
-      @owner_document.__internal_insert_at_doctype__(nodes, after: false)
-      remove
+      @owner_document.__internal_insert_at_doctype__(nodes, after: after)
       nil
     end
+    private :synthetic_insert
+
+    # A doctype is connected when its tree is a document's; a synthetic one is
+    # never in a tree at all.
+    def is_connected?
+      get_root_node.is_a?(Dommy::Document)
+    end
 
     def __js_get__(key)
       case key
@@ -141,6 +174,8 @@ module Dommy
         NodeList.new
       when "firstChild", "lastChild"
         nil
+      when "isConnected"
+        is_connected?
       end
     end
 
@@ -161,12 +196,25 @@ module Dommy
         rescue StandardError
           nil
         end
-        return DocumentType.new(backend_node: node, document: @document) if node
+        if node
+          clone = DocumentType.new(backend_node: node, document: @document)
+          # Register the wrapper against its backend node, so inserting the clone
+          # into a tree and reading it back returns THIS object rather than a
+          # freshly built one (`doc.replaceChildren(dt); doc.firstChild === dt`).
+          @document.__internal_register_wrapper__(node, clone)
+          return clone
+        end
       end
       DocumentType.new(name, public_id, system_id, owner_document: @owner_document)
     end
 
     include Bridge::Methods
+    # WHATWG's own wording for a doctype parent.
+    def leaf_insertion_message
+      "a DocumentType may not have children"
+    end
+    private :leaf_insertion_message
+
     js_methods %w[isEqualNode isSameNode getRootNode hasChildNodes normalize compareDocumentPosition contains
       cloneNode appendChild insertBefore removeChild replaceChild before after replaceWith remove
       lookupNamespaceURI lookupPrefix isDefaultNamespace
@@ -194,16 +242,14 @@ module Dommy
         get_root_node(args[0])
       when "compareDocumentPosition"
         compare_document_position(args[0])
-      when "appendChild", "insertBefore", "replaceChild"
-        # Pre-insert / replace step 1 rejects a non-parent context node with
-        # HierarchyRequestError before the reference-child check.
-        raise Bridge::TypeError, "Argument is not a Node." unless args[0].is_a?(Dommy::Node)
-
-        raise DOMException::HierarchyRequestError, "a DocumentType may not have children"
+      when "appendChild"
+        append_child(args[0])
+      when "insertBefore"
+        insert_before(args[0], args[1])
+      when "replaceChild"
+        replace_child(args[0], args[1])
       when "removeChild"
-        raise Bridge::TypeError, "Argument is not a Node." unless args[0].is_a?(Dommy::Node)
-
-        raise DOMException::NotFoundError, "the node to be removed is not a child of this node"
+        remove_child(args[0])
       when "before"
         before(*args)
       when "after"
@@ -231,15 +277,23 @@ module Dommy
       @document = document
     end
 
+    # A name createDocumentType refuses. It is otherwise extremely permissive —
+    # "1foo", "@foo", "edi:%" and the empty string are all accepted — but a name
+    # carrying whitespace or ">" could not be serialized back as a doctype, and
+    # is an InvalidCharacterError.
+    UNSERIALIZABLE_DOCTYPE_NAME = /[\s>]/
+
     # A created DocumentType's node document is the implementation's document. When
     # the backend ships a doctype factory (the HTML backend) and accepts the name,
     # the result is a real, node-backed (but detached) DocumentType that can join
-    # the tree; otherwise it falls back to a synthetic one. (Qualified-name QName
-    # validation isn't enforced — createDocumentType is permissive, so the factory's
-    # stricter name check is bypassed via the synthetic fallback rather than
-    # raising; a couple of invalid-name WPT cases stay documented gaps.)
+    # the tree; otherwise it falls back to a synthetic one — the factory's own
+    # (stricter, XML-flavoured) name check is not the DOM rule.
     def create_document_type(qualified_name, public_id, system_id)
       qn = qualified_name.to_s
+      if qn.match?(UNSERIALIZABLE_DOCTYPE_NAME)
+        raise DOMException::InvalidCharacterError, "invalid doctype name: #{qn.inspect}"
+      end
+
       pub = public_id.to_s
       sys = system_id.to_s
       node =
@@ -248,7 +302,16 @@ module Dommy
         rescue ArgumentError
           nil
         end
-      node ? DocumentType.new(backend_node: node, document: @document) : DocumentType.new(qn, pub, sys, owner_document: @document)
+      return DocumentType.new(qn, pub, sys, owner_document: @document) unless node
+
+      # Seed the wrapper cache, or the doctype reached later through the tree
+      # (document.childNodes, document.doctype, a NodeIterator) would be a
+      # DIFFERENT DocumentType object than the one createDocumentType returned,
+      # and `===` / `isSameNode` on the two would be false. Every other
+      # create* goes through the cache; this one built its wrapper directly.
+      wrapper = DocumentType.new(backend_node: node, document: @document)
+      @document.__internal_register_wrapper__(node, wrapper)
+      wrapper
     end
 
     # `hasFeature()` is a no-op that always returns true (DOM Standard).
@@ -302,6 +365,7 @@ module Dommy
       return unless node
 
       root = doc.backend_doc.root
+      doc.__internal_ranges_will_insert__(doc.backend_doc, root, 1)
       root ? root.add_previous_sibling(node) : doc.backend_doc.add_child(node)
     end
 
@@ -349,24 +413,158 @@ module Dommy
     attr_reader :backend_doc
     attr_accessor :default_view
     # --- CSS cascade support (Internal::CSS) ---
-    # Monotonic counter bumped on every DOM mutation; the CSS layer
-    # invalidates its per-document style cache wholesale when it moves.
-    # The cache slot itself is owned by Internal::CSS::Cascade.
+    # Two invalidation epochs, split so a style-neutral mutation doesn't pay
+    # for a cascade rebuild (RuleIndex.build is a full rules x document query):
+    #
+    # `dom_generation` keys the selector-result caches (query caches, selector
+    # index). It moves on anything that can change what a selector matches:
+    # tree shape, attributes, focus/hover, checkedness, and text edits that
+    # flip a node between empty and non-empty (`:empty` is the matcher's only
+    # text-sensitive pseudo-class).
+    #
+    # `style_generation` keys the cascade caches (RuleIndex, computed styles,
+    # counters — the slot itself is owned by Internal::CSS::Cascade). It moves
+    # on the same events, EXCEPT that an attribute change only moves it when
+    # the built RuleIndex's selectors depend on that attribute, and a text
+    # edit only when it's inside a <style> or flips emptiness while a sheet
+    # uses `:empty`. The coordinator reports mutations through the
+    # `__internal_note_*` seams below, which decide what to bump.
     attr_accessor :__css_style_cache__
 
     def style_generation
       @style_generation || 0
     end
 
+    def dom_generation
+      @dom_generation || 0
+    end
+
+    # Moves only on childList mutations — the coarsest epoch. Keys memos
+    # whose value depends on the element population alone (which elements
+    # exist, in what order), like the document's <style>/<link> list: an
+    # attribute-triggered cascade rebuild can then skip re-walking for them.
+    def tree_generation
+      @tree_generation || 0
+    end
+
     def __internal_bump_style_generation__
       @style_generation = style_generation + 1
       nil
     end
 
+    def __internal_bump_dom_generation__
+      @dom_generation = dom_generation + 1
+      nil
+    end
+
+    # A childList mutation: tree shape feeds both selector matching and the
+    # rule -> element index, so everything is suspect.
+    def __internal_note_tree_mutation__
+      @tree_generation = tree_generation + 1
+      __internal_bump_dom_generation__
+      __internal_bump_style_generation__
+    end
+
+    # The document's <style> and <link> elements in document order (their
+    # relative order breaks cascade ties), memoized per tree_generation:
+    # only a childList mutation can change the list, so the cascade's
+    # attribute-triggered rebuilds reuse it without a document walk.
+    def __internal_style_sheet_elements__
+      if @__sheet_elements_gen != tree_generation
+        @__sheet_elements_gen = tree_generation
+        @__sheet_elements = query_selector_all("style, link").to_a
+      end
+      @__sheet_elements
+    end
+
+    # An attribute mutation: selector results are always suspect (any cached
+    # query could carry an attribute selector), but the cascade only when the
+    # indexed rules read this attribute — or when the attribute belongs to a
+    # <style>/<link>, whose media/disabled/rel gate whole sheets.
+    def __internal_note_attribute_mutation__(name, target_node)
+      __internal_bump_dom_generation__
+      __internal_bump_style_generation__ if __internal_style_affected_by_attribute__(name, target_node)
+    end
+
+    # A characterData mutation. Text participates in matching only through
+    # `:empty` (a text node counts iff its data is non-empty), so nothing is
+    # suspect unless the edit flips that emptiness — except text inside a
+    # <style>, which IS the stylesheet source.
+    def __internal_note_character_data_mutation__(target_node, old_value)
+      # Only a Text node's data participates in :empty; a comment/PI edit
+      # can't change any match. `target_node` is a backend node, so its data
+      # reads through the Nokogiri-compatible #content.
+      text = target_node.respond_to?(:node_type) && target_node.node_type == 3
+      flipped = text && (old_value.to_s.empty? != target_node.content.to_s.empty?)
+      __internal_bump_dom_generation__ if flipped
+      if __internal_inside_style_element__(target_node) ||
+         (flipped && __internal_style_text_sensitive__)
+        __internal_bump_style_generation__
+      end
+      nil
+    end
+
+    # Selector-observable state that lives outside the attribute space
+    # (focus, hover, checkedness…): both cache families are suspect.
+    def __internal_note_selector_state_change__
+      __internal_bump_dom_generation__
+      __internal_bump_style_generation__
+    end
+
+    # A form control's IDL value changed (typing, `input.value = …`, a form
+    # reset). No attribute mutates, yet the value is selector-observable
+    # through the validity / range / placeholder pseudo-classes, so the
+    # selector epoch always moves — a cached `querySelectorAll(":invalid")`
+    # would otherwise survive the very change that flipped it. The cascade
+    # follows only when a sheet actually uses one of those pseudo-classes.
+    def __internal_note_value_change__
+      __internal_bump_dom_generation__
+      __internal_bump_style_generation__ if __internal_style_value_sensitive__
+      nil
+    end
+
+    def __internal_style_value_sensitive__
+      index = @__css_style_cache__ && @__css_style_cache__[:index]
+      index ? index.value_sensitive? : true
+    end
+
+    def __internal_style_affected_by_attribute__(name, target_node)
+      owner = target_node.respond_to?(:name) ? target_node.name.to_s.downcase : nil
+      return true if owner == "style" || owner == "link"
+
+      index = @__css_style_cache__ && @__css_style_cache__[:index]
+      # No RuleIndex yet: the bump is nearly free (at most it drops the
+      # author_css?/counters memos), so stay conservative.
+      return true unless index
+
+      index.attribute_dependency?(name)
+    end
+
+    def __internal_style_text_sensitive__
+      index = @__css_style_cache__ && @__css_style_cache__[:index]
+      index ? index.text_sensitive? : true
+    end
+
+    def __internal_inside_style_element__(node)
+      # No <style> in the document -> a text edit can't be sheet source, so
+      # skip the ancestor walk. The sheet-element list is memoized per
+      # tree_generation (only childList changes it), so a text-editing loop
+      # between childList mutations answers this without re-walking.
+      return false unless __internal_style_sheet_elements__.any? { |el| el.local_name.to_s.casecmp?("style") }
+
+      current = node.respond_to?(:parent) ? node.parent : nil
+      while current
+        return true if current.respond_to?(:name) && current.name.to_s.downcase == "style"
+
+        current = current.respond_to?(:parent) ? current.parent : nil
+      end
+      false
+    end
+
     # A by-id/class/tag index of the backend element tree, memoized per DOM
     # generation, for SelectorMatcher's document-scoped fast path (or nil to tell
     # the caller to walk). Rebuilt lazily only after a mutation bumps
-    # style_generation, so it costs one tree walk per generation and pays off when
+    # dom_generation, so it costs one tree walk per generation and pays off when
     # several queries run before the next mutation.
     #
     # Adaptive bypass: if the index keeps getting invalidated after serving only a
@@ -379,7 +577,7 @@ module Dommy
     SELECTOR_INDEX_RETEST_GAP = 64 # generations to wait before re-testing a bypass
 
     def __internal_selector_index__
-      gen = style_generation
+      gen = dom_generation
       if @__sel_idx_gen != gen
         if @__sel_idx
           if @__sel_idx_served.to_i < SELECTOR_INDEX_MIN_REUSE
@@ -410,18 +608,18 @@ module Dommy
     # (element, selector) constantly between mutations; this memoizes the match
     # set, keyed by [scope object_id, kind, selector] and tagged with the DOM
     # generation, so a hit skips the whole combinator match. Capped, and a
-    # mutation (style_generation bump) makes every entry stale at once.
+    # mutation (dom_generation bump) makes every entry stale at once.
     SCOPED_QUERY_CACHE_CAP = 4096
 
     def __internal_scoped_query_get(key)
       entry = (@__scoped_query_cache ||= {})[key]
-      entry && entry[0] == style_generation ? entry[1] : nil
+      entry && entry[0] == dom_generation ? entry[1] : nil
     end
 
     def __internal_scoped_query_set(key, value)
       cache = (@__scoped_query_cache ||= {})
       cache.clear if cache.size >= SCOPED_QUERY_CACHE_CAP
-      cache[key] = [style_generation, value]
+      cache[key] = [dom_generation, value]
       value
     end
 
@@ -447,6 +645,17 @@ module Dommy
     # owns firing the element's load / error event. nil = such scripts are inert.
     attr_accessor :external_script_runner
 
+    # Installed by the browser when a JS runtime is present: re-runs the
+    # inline-handler scan so an `on*` attribute that arrived after boot (a cloned
+    # template, an innerHTML fragment) is compiled. nil without a runtime, which
+    # is also the fast path that keeps a JS-free document out of this entirely.
+    attr_accessor :inline_handler_wirer
+
+    def __internal_wire_inline_handlers__
+      @inline_handler_wirer&.call
+      nil
+    end
+
     def initialize(host = nil, backend_doc: nil, default_view: nil)
       @host = host
       @default_view = default_view
@@ -456,7 +665,12 @@ module Dommy
       @cookie_jar = Internal::CookieJar.new
       @template_content_registry = Internal::TemplateContentRegistry.new(self)
       @mutation_coordinator = Internal::MutationCoordinator.new(self, @observer_manager)
-      @node_iterators = []
+      # Weak, like @live_ranges: a NodeIterator is consulted by every removal for
+      # as long as its document holds it, and detach() is a no-op by definition,
+      # so a strong list would mean every iterator ever created keeps costing
+      # work — and keeps its referenceNode's whole detached subtree alive —
+      # forever. A browser collects an unreachable one and stops consulting it.
+      @node_iterators = ObjectSpace::WeakMap.new
       @backend_doc = backend_doc || Backend.parse("<!doctype html><html><head></head><body></body></html>")
       @content_type = "text/html"
       # The document is fully parsed before scripts run (no incremental network
@@ -504,9 +718,24 @@ module Dommy
       write_title(value.to_s)
     end
 
+    # A document is its own shadow-including root, so it is always connected
+    # (Element#is_connected? walks up to a document; the document itself is the
+    # base case).
+    def is_connected?
+      true
+    end
+
     def document_element
       # The document's root element — `<html>` for HTML, the actual root for XML.
-      wrap_node(@backend_doc.root)
+      # It is the document's first ELEMENT child, so a document that has none
+      # answers null: the backend's `root` falls back to the doctype once the
+      # element is gone (`document.removeChild(documentElement)`, or a
+      # replaceChild that swaps it for a comment), and head / body / title
+      # resolve through this.
+      root = @backend_doc.root
+      return nil unless root&.element?
+
+      wrap_node(root)
     end
 
     def head
@@ -691,8 +920,8 @@ module Dommy
 
     def __internal_set_active_element__(el)
       # Focus is selector-observable state (:focus / :focus-within rules), so
-      # a change invalidates computed styles.
-      __internal_bump_style_generation__ unless @active_element.equal?(el)
+      # a change invalidates cached query results and computed styles.
+      __internal_note_selector_state_change__ unless @active_element.equal?(el)
       @active_element = el
     end
 
@@ -713,7 +942,7 @@ module Dommy
       return if @hovered_element.equal?(el)
 
       @hovered_element = el
-      __internal_bump_style_generation__
+      __internal_note_selector_state_change__
       nil
     end
 
@@ -733,15 +962,7 @@ module Dommy
     # Ruby Proc, a JS-bridge callable, or an object with
     # `accept_node` / `acceptNode`.
     def create_tree_walker(root, what_to_show = NodeFilter::SHOW_ALL, filter = nil)
-      TreeWalker.new(require_node_root(root), what_to_show, filter)
-    end
-
-    # The `root` of a TreeWalker / NodeIterator is a non-nullable WebIDL `Node`:
-    # a null or non-Node argument is a TypeError before construction.
-    def require_node_root(root)
-      return root if root.is_a?(Dommy::Node)
-
-      raise Bridge::TypeError, "createTreeWalker/createNodeIterator root must be a Node"
+      TreeWalker.new(Internal::WebIDL.node!(root), what_to_show, filter)
     end
 
     # WebIDL `unsigned long whatToShow = 0xFFFFFFFF`: an omitted or `undefined`
@@ -767,97 +988,66 @@ module Dommy
     # wrapper is owned by `this`. Per spec, the source node is left
     # in place. `deep: true` copies the entire subtree.
     def import_node(node, deep = false)
+      # Step 1: "If node is a document or shadow root, throw a
+      # NotSupportedError." Neither has anywhere to go in another document.
+      if node.is_a?(Document) || node.is_a?(ShadowRoot)
+        raise DOMException::NotSupportedError, "a #{node.is_a?(Document) ? "document" : "shadow root"} cannot be imported"
+      end
+
+      # An Attr is a Node but not a backend-tree node: it is copied by rebuilding
+      # it here with the same qualified name, namespace, prefix and value, owned
+      # by no element (importNode never attaches the copy to anything).
+      return import_attribute(node) if node.is_a?(Attr)
       return nil unless node.respond_to?(:__dommy_backend_node__)
 
       # WebIDL `optional boolean deep = false`: a missing / undefined argument
       # is the default (false / shallow), not a truthy sentinel.
       deep = false if deep.nil? || deep.equal?(Bridge::UNDEFINED)
-      copy = clone_into_doc(node.__dommy_backend_node__, deep)
+      source_document = node.respond_to?(:document) ? node.document : self
+      copy = clone_into_doc(node.__dommy_backend_node__, deep, source_document)
       wrap_node(copy)
     end
 
-    # Move a node from another document into this one. The source
-    # node is detached from its previous owner and its ownerDocument
-    # becomes this. Returns the (possibly re-wrapped) node.
-    def adopt_node(node)
-      # WHATWG adopt: a Document can't be adopted into another document.
-      if node.is_a?(Dommy::Document)
-        raise DOMException::NotSupportedError, "A Document node cannot be adopted."
-      end
-      return nil unless node.respond_to?(:__dommy_backend_node__)
-
-      src = node.__dommy_backend_node__
-      src.unlink if src.parent
-
-      # Same document: just return the wrapper after the detach above.
-      return wrap_node(src) if src.document == @backend_doc
-
-      # Cross-document DocumentType: Makiri can't import a doctype node between
-      # arenas, so re-create it in this document's backend from its public
-      # name / publicId / systemId (as createDocument does), then reseat the
-      # caller's wrapper onto the new node so JS identity survives the move.
-      if node.is_a?(DocumentType)
-        adopted = begin
-          Backend.create_document_type(node.name, node.public_id, node.system_id, @backend_doc)
-        rescue StandardError
-          nil
-        end
-        return node unless adopted
-
-        src_doc_wrapper = node.instance_variable_get(:@document)
-        src_doc_wrapper.__internal_reset_wrapper__(src) if src_doc_wrapper.respond_to?(:__internal_reset_wrapper__)
-        node.instance_variable_set(:@document, self)
-        node.instance_variable_set(:@owner_document, self)
-        node.instance_variable_set(:@__node__, adopted)
-        @node_wrapper_cache.register(adopted, node)
-        return node
-      end
-
-      # Cross-document: hand the detached source to the backend, which
-      # returns the node now owned by this document — an imported copy for
-      # Makiri (a node can't move between arenas). Drop the stale source
-      # wrapper, then reseat the caller's Dommy wrapper onto the adopted
-      # node so `adopt_node(x).equal?(x)` stays true across documents.
-      src_doc_wrapper = node.instance_variable_get(:@document)
-      adopted = Backend.adopt(src, @backend_doc)
-
-      if src_doc_wrapper.respond_to?(:__internal_reset_wrapper__)
-        src_doc_wrapper.__internal_reset_wrapper__(src)
-      end
-      node.instance_variable_set(:@document, self)
-      node.instance_variable_set(:@__node__, adopted)
-      @node_wrapper_cache.register(adopted, node)
-
-      # A deep adopt imports a fresh copy of the whole subtree, so any live
-      # descendant wrapper (held by page script, e.g. an aria element reference)
-      # must be reseated onto its corresponding copy — otherwise it stays bound to
-      # the old document. Import preserves document order, so walk both subtrees in
-      # lockstep.
-      reseat_descendant_wrappers(src, adopted, src_doc_wrapper)
-      node
+    def import_attribute(attr)
+      Attr.new(
+        attr.name,
+        value: attr.value,
+        namespace_uri: attr.namespace_uri,
+        prefix: attr.prefix,
+        local_name: attr.local_name,
+        document: self
+      )
     end
 
-    # Move each live wrapper for a descendant of `src_root` onto the matching node
-    # in `dst_root` (the imported copy), pruning it from the source document.
-    def reseat_descendant_wrappers(src_root, dst_root, src_doc)
-      return unless src_doc.respond_to?(:__internal_peek_wrapper__)
-
-      src_nodes = collect_subtree_nodes(src_root)
-      dst_nodes = collect_subtree_nodes(dst_root)
-      return unless src_nodes.length == dst_nodes.length
+    # The registry holding this document's `<template>` content fragments. A
+    # cross-document clone or adopt has to read the SOURCE document's registry:
+    # template contents are not in the template's child list, so they are
+    # reachable only through the registry that owns them.
+    def __internal_template_registry__
+      @template_content_registry
+    end
 
-      src_nodes.zip(dst_nodes).each do |orig, copy|
-        next if orig.equal?(src_root) # the root wrapper is reseated by the caller
+    # Move a node from another document into this one. The source node is
+    # detached from its previous owner and its ownerDocument becomes this.
+    # Returns the (possibly re-bound) node.
+    #
+    # What "moving" costs depends on the backend — an import plus a walk to
+    # carry the live wrappers and template contents over, where a browser swaps
+    # a pointer — so the whole of it lives in Internal::NodeAdopter.
+    def adopt_node(node)
+      node_adopter.adopt(node)
+    end
 
-        wrapper = src_doc.__internal_peek_wrapper__(orig)
-        next unless wrapper
+    # Adopt a raw backend node with no wrapper of its own: a DocumentFragment's
+    # children, on a cross-document insert.
+    def __internal_adopt_backend_node__(node, source_document)
+      node_adopter.adopt_backend_node(node, source_document)
+    end
 
-        src_doc.__internal_reset_wrapper__(orig)
-        wrapper.instance_variable_set(:@document, self)
-        wrapper.instance_variable_set(:@__node__, copy)
-        @node_wrapper_cache.register(copy, wrapper)
-      end
+    def node_adopter
+      @node_adopter ||= Internal::NodeAdopter.new(self)
     end
+    private :node_adopter
 
     # HTML "cloning steps": a cloned node copies interface-specific live state
     # that the content attributes don't capture — an input's dirty value and
@@ -867,11 +1057,17 @@ module Dommy
     # lockstep and copy each live wrapper's cloning state onto its copy. `deep`
     # false processes only the root (a shallow clone has no children).
     def __internal_apply_cloning_steps__(src_root_bn, clone_root_bn, deep)
-      src_nodes = deep ? collect_subtree_nodes(src_root_bn) : [src_root_bn]
-      clone_nodes = deep ? collect_subtree_nodes(clone_root_bn) : [clone_root_bn]
+      src_nodes = deep ? Internal::NodeTraversal.subtree_nodes(src_root_bn) : [src_root_bn]
+      clone_nodes = deep ? Internal::NodeTraversal.subtree_nodes(clone_root_bn) : [clone_root_bn]
       return unless src_nodes.length == clone_nodes.length
 
       src_nodes.zip(clone_nodes).each do |orig, copy|
+        # HTML cloning steps for <template>: its content lives in an off-tree
+        # fragment the backend's subtree clone never reaches, so a deep clone has
+        # to copy it across explicitly (a shallow clone gets an empty template,
+        # per spec).
+        clone_template_content(orig, copy) if deep && @template_content_registry.has_content?(orig)
+
         wrapper = @node_wrapper_cache.peek(orig)
         next unless wrapper.respond_to?(:__cloning_state__)
 
@@ -882,32 +1078,27 @@ module Dommy
       end
     end
 
-    # A subtree's nodes in document (depth-first) order — the order Backend.adopt
-    # preserves — so a source node and its imported copy line up by index.
-    def collect_subtree_nodes(root)
-      nodes = [root]
-      root.children.each { |child| nodes.concat(collect_subtree_nodes(child)) } if root.respond_to?(:children)
-      nodes
-    end
-
     # Legacy `document.createEvent("EventName")` factory. Returns an
     # Event subclass instance whose init still has to be called
     # (`event.initEvent(type, bubbles, cancelable)`). Matches the
     # mapping happy-dom and linkedom use.
     def create_event(type_name)
       name = type_name.to_s
-      case name
-      when "Event", "Events", "HTMLEvents"
-        Event.new("")
-      when "CustomEvent"
-        CustomEvent.new("")
-      when "MouseEvent", "MouseEvents"
-        MouseEvent.new("")
-      when "KeyboardEvent", "KeyboardEvents"
-        KeyboardEvent.new("")
-      else
-        Event.new("")
-      end
+      event =
+        case name
+        when "CustomEvent"
+          CustomEvent.new("")
+        when "MouseEvent", "MouseEvents"
+          MouseEvent.new("")
+        when "KeyboardEvent", "KeyboardEvents"
+          KeyboardEvent.new("")
+        else
+          Event.new("")
+        end
+      # createEvent hands back an *uninitialized* event: it has no type yet and
+      # dispatching it before initEvent() is an InvalidStateError.
+      event.__internal_mark_uninitialized__
+      event
     end
 
     # Stubs for layout / focus / selection / execCommand APIs that
@@ -920,7 +1111,11 @@ module Dommy
 
     alias has_focus has_focus?
 
+    # A document without a browsing context (one built by DOMParser or
+    # createHTMLDocument) has no selection.
     def get_selection
+      return nil unless @default_view
+
       @__selection ||= Selection.new(self)
     end
 
@@ -962,7 +1157,7 @@ module Dommy
     # `document.createNodeIterator(root, whatToShow?, filter?)` —
     # flat depth-first iteration.
     def create_node_iterator(root, what_to_show = NodeFilter::SHOW_ALL, filter = nil)
-      root = require_node_root(root)
+      root = Internal::WebIDL.node!(root)
       iterator = NodeIterator.new(root, what_to_show, filter)
       # The "NodeIterator pre-removing steps" run for iterators whose root's node
       # document is the removed node's document. Track the iterator on the root's
@@ -979,12 +1174,16 @@ module Dommy
     def node_iterator_document(root)
       return root if root.is_a?(Dommy::Document)
 
-      doc = root.instance_variable_get(:@document)
+      doc = root.document if root.respond_to?(:document)
       doc.is_a?(Dommy::Document) ? doc : self
     end
 
     def __internal_track_node_iterator__(iterator)
-      @node_iterators << iterator
+      @node_iterators[iterator] = true
+    end
+
+    def node_iterators?
+      @node_iterators.size.positive?
     end
 
     # `document.doctype` — the node-backed DocumentType wrapping the parsed
@@ -1012,6 +1211,7 @@ module Dommy
     # from the counts, since replace-all removes them first. `exclude` (replace)
     # is a current child to disregard. Raises HierarchyRequestError on violation.
     def ensure_document_insertion_validity!(args, child_bn, ignore_existing: false, exclude: nil)
+      ensure_not_self_insertion!(args)
       elements = 0
       doctypes = 0
       has_text = false
@@ -1066,6 +1266,31 @@ module Dommy
       end
     end
 
+    # Document's answer to the ParentNode hook a ChildNode mutation
+    # (`before` / `after` / `replaceWith`) calls on its parent. A Document
+    # parent skips the ancestor rule (it is never a descendant of anything) and
+    # instead carries step 6: at most one element child, no Text child, and a
+    # doctype only ahead of the document element. `replacing` is the child a
+    # `replaceWith` stands in for, which WHATWG "replace" disregards when
+    # counting the existing children.
+    def __internal_ensure_insertion_validity__(args, ref_bn, replacing: nil)
+      ensure_document_insertion_validity!(args, ref_bn, exclude: replacing)
+    end
+
+    # WHATWG "ensure pre-insertion validity" step 2 for a Document parent: node
+    # must not be a host-including inclusive ancestor of the parent. A document
+    # is an inclusive ancestor of itself and nothing else can be an ancestor of
+    # one, so this reduces to "you cannot insert the document into itself".
+    #
+    # It is step 2, so it precedes step 3's NotFoundError on the reference
+    # child: `document.replaceChild(document, x)` is a HierarchyRequestError
+    # even when x is not a child of the document.
+    def ensure_not_self_insertion!(args)
+      return unless args.any? { |a| a.equal?(self) }
+
+      raise DOMException::HierarchyRequestError, "Cannot insert a node as a descendant of itself"
+    end
+
     # Whether any element child precedes `child_bn` in the document's child list.
     def element_before_child?(existing, child_bn)
       idx = child_bn && existing.index { |c| c == child_bn }
@@ -1088,26 +1313,147 @@ module Dommy
       ensure_document_insertion_validity!([node], nil)
       return node unless node.respond_to?(:__dommy_backend_node__)
 
-      # appendChild adopts a node from another document (per spec). Only needed on
-      # a backend that can't move a node across documents (Makiri).
-      if !Backend.moves_nodes_across_documents? && node.respond_to?(:document) && !node.document.equal?(self)
-        node = adopt_node(node)
-      end
-      @backend_doc.add_child(node.__dommy_backend_node__)
+      # An append has a null reference child, so insert step 5 shifts nothing.
+      nodes = document_insertion_nodes([node])
+      return node if nodes.empty?
+
+      nodes.each { |bn| @backend_doc.add_child(bn) }
+      notify_document_child_list(added: nodes)
       node
     end
 
+    # The Node / ParentNode mutation methods under their WHATWG names. The
+    # document's own child list has its own rules (at most one element, no Text,
+    # a doctype only ahead of the document element), so each forwards to the
+    # `document_*` implementation that carries them.
+    def insert_before(node, reference)
+      document_insert_before(node, reference)
+    end
+
+    def replace_child(new_child, old_child)
+      document_replace_child(new_child, old_child)
+    end
+
+    def remove_child(node)
+      document_remove_child(node)
+    end
+
+    def replace_children(*args)
+      document_replace_children(args)
+    end
+
+    def append(*args)
+      document_insert(args, prepend: false)
+    end
+
+    def prepend(*args)
+      document_insert(args, prepend: true)
+    end
+
+    # WHATWG ParentNode.moveBefore(node, child) with the DOCUMENT as the new
+    # parent. The move primitive's steps 5 and 6 bind only here: a Text node may
+    # not become a child of a document, and an Element may only be moved in when
+    # the document has no element child, the reference is not the doctype, and
+    # no doctype follows the reference.
+    #
+    # Spec: https://dom.spec.whatwg.org/#dom-parentnode-movebefore
+    def move_before(node, child = nil)
+      Internal::WebIDL.node!(node)
+      Internal::WebIDL.nullable_node!(child)
+      bn = move_backend_node(node)
+      ref_bn = move_backend_node(child)
+      ref_bn = ref_bn.next_sibling if ref_bn && bn && ref_bn == bn
+      ensure_document_move_validity!(node, bn, ref_bn)
+
+      old_parent = bn.parent
+      old_previous = bn.previous_sibling
+      old_next = bn.next_sibling
+      detach_node(bn, moving: true)                               # steps 10-11, 14
+      ref_bn = nil if ref_bn && ref_bn.parent != @backend_doc
+      __internal_ranges_will_insert__(@backend_doc, ref_bn, 1)    # step 16
+      new_previous = ref_bn ? ref_bn.previous_sibling : @backend_doc.children.to_a.last
+      ref_bn ? ref_bn.add_previous_sibling(bn) : @backend_doc.add_child(bn) # step 18
+      if old_parent
+        notify_child_list_mutation(
+          target_node: old_parent, added_nodes: [], removed_nodes: [bn],
+          previous_sibling: old_previous && wrap_node(old_previous),
+          next_sibling: old_next && wrap_node(old_next), moving: true
+        )
+      end
+      notify_document_child_list(added: [bn], previous_sibling: new_previous && wrap_node(new_previous),
+                                 next_sibling: ref_bn && wrap_node(ref_bn), moving: true)
+      __internal_notify_moved_subtree__(bn)                        # step 19.3, into a document
+      nil
+    end
+
+    # The backend node an argument to `moveBefore` stands for. A Dommy::Document
+    # has no `__dommy_backend_node__` of its own, but it is a node the algorithm
+    # has to see (step 2 rejects it, step 3 measures its parentage).
+    def move_backend_node(value)
+      return value.backend_doc if value.is_a?(Dommy::Document)
+      return nil unless value.respond_to?(:__dommy_backend_node__)
+
+      value.__dommy_backend_node__
+    end
+
+    # "Move" steps 1-6 with a document new parent.
+    def ensure_document_move_validity!(node, bn, ref_bn)
+      # Step 1 — the same root. A document is its own root, so this says the
+      # node must already be somewhere in this document.
+      root = bn
+      root = root.parent while root.respond_to?(:parent) && root.parent
+      # `==` and not `equal?`: a backend may hand back a fresh Ruby object for
+      # the same underlying node on every `parent` call.
+      unless bn && root == @backend_doc
+        raise DOMException::HierarchyRequestError,
+              "moveBefore requires the node and the new parent to share a root"
+      end
+
+      # Step 2 — a document is its own inclusive ancestor; nothing else can be
+      # an ancestor of one, so this reduces to "not the document itself".
+      ensure_not_self_insertion!([node])
+
+      # Step 3.
+      if ref_bn && ref_bn.parent != @backend_doc
+        raise DOMException::NotFoundError, "The reference child is not a child of this document."
+      end
+
+      # Step 4.
+      unless node.is_a?(Dommy::Element) || node.is_a?(Dommy::CharacterDataNode)
+        raise DOMException::HierarchyRequestError, "this node type cannot be moved"
+      end
+
+      # Step 5.
+      if node.is_a?(Dommy::CharacterDataNode) && node.node_type == 3
+        raise DOMException::HierarchyRequestError, "A Text node cannot be a child of a document."
+      end
+
+      return unless node.is_a?(Dommy::Element)
+
+      # Step 6. The counts are of the CURRENT children, so a document that
+      # already has a document element cannot take another element — not even
+      # by moving that same element to a different slot.
+      existing = @backend_doc.children.to_a
+      return unless existing.any? { |c| c.node_type == 1 } ||
+                    (ref_bn && ref_bn.node_type == 10) ||
+                    doctype_after_child?(existing, ref_bn)
+
+      raise DOMException::HierarchyRequestError, "An element cannot be moved here."
+    end
+
     # ParentNode / Node mutation on the document's direct children (the doctype
     # and the document element).
     def document_insert(args, prepend:)
       ref_bn = prepend ? @backend_doc.children.first : nil
       ensure_document_insertion_validity!(args, ref_bn)
-      nodes = args.filter_map { |a| adopted_backend_node(a) }
+      __internal_ranges_will_insert__(@backend_doc, ref_bn, document_insertion_count(args))
+      nodes = document_insertion_nodes(args)
       if prepend && (first = @backend_doc.children.first)
         nodes.reverse_each { |n| first.add_previous_sibling(n) }
       else
         nodes.each { |n| @backend_doc.add_child(n) }
       end
+      notify_document_child_list(added: nodes)
       nil
     end
 
@@ -1115,8 +1461,11 @@ module Dommy
       # replaceChildren removes the current children first, so the validity
       # checks ignore them (whatwg/dom#1045).
       ensure_document_insertion_validity!(args, nil, ignore_existing: true)
-      @backend_doc.children.each(&:unlink)
-      args.filter_map { |a| adopted_backend_node(a) }.each { |n| @backend_doc.add_child(n) }
+      removed = @backend_doc.children.to_a
+      removed.each { |child| detach_node(child) }
+      added = document_insertion_nodes(args)
+      added.each { |n| @backend_doc.add_child(n) }
+      notify_document_child_list(added: added, removed: removed)
       nil
     end
 
@@ -1126,15 +1475,15 @@ module Dommy
       bn = backend_node(node)
       raise DOMException::NotFoundError, "node is not a child of this document" unless bn && bn.parent == @backend_doc
 
-      run_node_iterator_pre_remove(bn)
-      bn.unlink
+      remove_node_with_notify(bn)
       node
     end
 
     def document_insert_before(node, ref)
-      # WHATWG pre-insert order: the reference child must be a child of the
-      # parent (step 3, NotFoundError) BEFORE the node-type / document-hierarchy
-      # checks (steps 4-6).
+      # WHATWG pre-insert order: step 2 (a cycle) first, THEN step 3 (the
+      # reference child must be a child of the parent, NotFoundError), and only
+      # then the node-type / document-hierarchy checks (steps 4-6).
+      ensure_not_self_insertion!([node])
       ref_present = !(ref.nil? || (defined?(Bridge::UNDEFINED) && ref.equal?(Bridge::UNDEFINED)))
       ref_bn = ref_present ? backend_node(ref) : nil
       if ref_present && !(ref_bn && ref_bn.parent == @backend_doc)
@@ -1142,19 +1491,31 @@ module Dommy
       end
 
       ensure_document_insertion_validity!([node], ref_bn)
-      bn = adopted_backend_node(node)
-      return node unless bn
+      # Insert step 6's insertion point, read BEFORE step 7's adopt moves
+      # anything: the reference child's previous sibling, or the document's last
+      # child when appending.
+      record_previous = document_insertion_previous_sibling(ref_bn)
+      record_next = ref_bn && wrap_node(ref_bn)
+      # Insert step 5 runs before step 7's adopt, so the count is taken while the
+      # node (or fragment) still sits wherever it is now.
+      __internal_ranges_will_insert__(@backend_doc, ref_bn, document_insertion_count([node]))
+      nodes = document_insertion_nodes([node])
+      return node if nodes.empty?
 
       ref_node = ref && backend_node(ref)
       if ref_node && ref_node.parent == @backend_doc
-        ref_node.add_previous_sibling(bn)
+        nodes.each { |bn| ref_node.add_previous_sibling(bn) }
       else
-        @backend_doc.add_child(bn)
+        nodes.each { |bn| @backend_doc.add_child(bn) }
       end
+      notify_document_child_list(added: nodes, previous_sibling: record_previous,
+                                 next_sibling: record_next)
       node
     end
 
     def document_replace_child(new_child, old_child)
+      # Step 2 (a cycle) precedes step 3 (the reference child's parentage).
+      ensure_not_self_insertion!([new_child])
       old_bn = backend_node(old_child)
       raise DOMException::NotFoundError, "node is not a child of this document" unless old_bn && old_bn.parent == @backend_doc
 
@@ -1162,18 +1523,51 @@ module Dommy
       # the document's existing element / doctype children.
       ensure_document_insertion_validity!([new_child], old_bn, exclude: old_bn)
 
-      # Remove old FIRST, then adopt the incoming node. A cross-document doctype
-      # is re-created in this backend, and Makiri's fail-closed guard refuses a
-      # second doctype — so the old one must be gone before the new is made.
       ref = old_bn.next
-      old_bn.unlink
-      if !Backend.moves_nodes_across_documents? && new_child.respond_to?(:document) && !new_child.document.equal?(self)
-        new_child = adopt_node(new_child)
-      end
-      new_bn = backend_node(new_child)
-      if new_bn
-        ref && ref.parent == @backend_doc ? ref.add_previous_sibling(new_bn) : @backend_doc.add_child(new_bn)
+      # Replace step 4's previousSibling: the old child's previous sibling,
+      # read before the adopt below removes anything.
+      record_previous = old_bn.previous && wrap_node(old_bn.previous)
+      record_next = ref && wrap_node(ref)
+      cross_document = !Backend.moves_nodes_across_documents? &&
+        new_child.respond_to?(:document) && !new_child.document.equal?(self)
+      fragment = new_child.is_a?(Dommy::Fragment)
+
+      # Same document: WHATWG replace adopts the incoming node — which removes
+      # it from whatever parent it has — BEFORE removing the child it replaces,
+      # so that old parent gets its removing steps and its childList record.
+      #
+      # Cross-document is deferred instead: a doctype has to be re-created in
+      # this backend, and Makiri's fail-closed guard refuses a second doctype,
+      # so the old one must be gone before the new one is made.
+      #
+      # A DocumentFragment has nothing to adopt at this point: what gets
+      # inserted is its children, and insert step 4 takes them out later, after
+      # step 7 has removed the child being replaced.
+      new_bn = adopted_backend_node(new_child) if !cross_document && !fragment
+      # Insert step 2's count, taken while the fragment still holds its children.
+      count = document_insertion_count([new_child])
+      detach_node(old_bn)
+      # Insert step 4: a fragment's children are REMOVED from it, which runs the
+      # live range and NodeIterator pre-remove steps and queues a childList
+      # record on the fragment. Then step 5 shifts the ranges on this document
+      # by the count. WHATWG "replace" removes the old child (step 7) before the
+      # insert (step 9), so step 5 measures `ref` in the tree the removal leaves.
+      nodes =
+        if fragment
+          document_insertion_nodes([new_child])
+        elsif cross_document
+          new_child = adopt_node(new_child)
+          bn = backend_node(new_child)
+          bn ? [bn] : []
+        else
+          new_bn ? [new_bn] : []
+        end
+      __internal_ranges_will_insert__(@backend_doc, ref && ref.parent == @backend_doc ? ref : nil, count)
+      nodes.each do |bn|
+        ref && ref.parent == @backend_doc ? ref.add_previous_sibling(bn) : @backend_doc.add_child(bn)
       end
+      notify_document_child_list(added: nodes, removed: [old_bn],
+                                 previous_sibling: record_previous, next_sibling: record_next)
       old_child
     end
 
@@ -1183,8 +1577,7 @@ module Dommy
       node = backend_node(doctype) || Backend.internal_subset(@backend_doc)
       return nil unless node
 
-      run_node_iterator_pre_remove(node)
-      node.unlink
+      remove_node_with_notify(node)
       nil
     end
 
@@ -1192,21 +1585,28 @@ module Dommy
     # (at the document start) or after it (just before the document element).
     def __internal_insert_at_doctype__(nodes, after:)
       bns = nodes.filter_map { |n| backend_node(n) }
+      anchor = after ? @backend_doc.root : @backend_doc.children.first
+      __internal_ranges_will_insert__(@backend_doc, anchor, bns.size)
       if after
-        root = @backend_doc.root
-        root ? bns.each { |n| root.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
+        anchor ? bns.each { |n| anchor.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
       else
-        first = @backend_doc.children.first
-        first ? bns.reverse_each { |n| first.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
+        anchor ? bns.reverse_each { |n| anchor.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
       end
       nil
     end
 
-    # `document.cloneNode(deep)` → a fresh Document over a (deep) copy of the
-    # Makiri tree, preserving the content type.
+    # `document.cloneNode(deep)` → a fresh Document of the same kind, keeping
+    # the content type. "Clone a single node" creates a document EMPTY, and a
+    # deep clone then copies the original's children into it — so nothing
+    # sprouts an html/head/body of its own, and a document with no children
+    # clones to one with no children.
     def clone_node(deep)
-      copy = deep ? Backend.clone_document(@backend_doc) : Backend.empty_document_like(@backend_doc)
-      Document.new(nil, backend_doc: copy).tap { |d| d.content_type = @content_type }
+      copy = Document.new(nil, backend_doc: Backend.empty_document_like(@backend_doc))
+      copy.content_type = @content_type
+      return copy unless deep
+
+      child_nodes.each { |child| copy.append_child(copy.import_node(child, true)) }
+      copy
     end
 
     def backend_node(node)
@@ -1219,13 +1619,55 @@ module Dommy
     # `append_child` does, otherwise a cross-document node's backend node comes
     # from a foreign arena and the insertion silently drops it on a backend that
     # can't move nodes across documents (Makiri).
+    # WHATWG pre-insert: adopt the node into this document, which removes it
+    # from whatever parent it has now. The backend would detach it implicitly on
+    # the next add_child, but silently — that is a storage operation, not a DOM
+    # removal, so route it through the shared remove primitive instead and let
+    # the old parent see its removing steps and its childList record.
+    # WHATWG "insert" steps 1 and 4 for the DOCUMENT's own child list. A
+    # DocumentFragment argument contributes its children, and they are removed
+    # from it first — with their removing steps, so a live range or NodeIterator
+    # inside them follows — before anything is linked here. Every other node is
+    # adopted, which removes it from its old parent.
+    #
+    # Document's insertion paths hand the backend the node they were given, and
+    # the backend splices a fragment's children in silently; without this the
+    # fragment's children would move with no removing steps at all.
+    def document_insertion_nodes(args)
+      args.flat_map do |arg|
+        if arg.is_a?(Dommy::Fragment)
+          source = arg.document
+          arg.extract_children.map do |n|
+            n.document == @backend_doc ? n : __internal_adopt_backend_node__(n, source)
+          end
+        else
+          bn = adopted_backend_node(arg)
+          bn ? [bn] : []
+        end
+      end
+    end
+
+    # How many nodes `args` will contribute, counted BEFORE any of them moves —
+    # insert step 5 needs the count while the fragment still holds its children.
+    def document_insertion_count(args)
+      args.sum do |arg|
+        if arg.is_a?(Dommy::Fragment) then arg.child_nodes.to_a.size
+        elsif arg.respond_to?(:__dommy_backend_node__) then 1
+        else 0
+        end
+      end
+    end
+
     def adopted_backend_node(node)
       return nil unless node.respond_to?(:__dommy_backend_node__)
 
       if !Backend.moves_nodes_across_documents? && node.respond_to?(:document) && !node.document.equal?(self)
-        node = adopt_node(node)
+        return adopt_node(node)&.__dommy_backend_node__
       end
-      node.__dommy_backend_node__
+
+      bn = node.__dommy_backend_node__
+      remove_node_with_notify(bn) if bn.parent
+      bn
     end
 
     # Delegate to CookieJar
@@ -1333,14 +1775,16 @@ module Dommy
       when "scrollingElement"
         wrap_node(@backend_doc.at_css("html"))
       when "documentElement"
-        # The document's root element — `<html>` for HTML, the actual root for XML.
-        wrap_node(@backend_doc.root)
+        document_element
       when "title"
         read_title
       when "cookie"
         cookie
       when "nodeType"
         9
+      when "isConnected"
+        # A document is its own shadow-including root, so it is always connected.
+        true
       when "nodeValue", "textContent"
         # A Document's nodeValue and textContent are null (not the concatenated
         # descendant text) per the DOM.
@@ -1524,7 +1968,7 @@ module Dommy
       adoptNode hasFocus getSelection elementFromPoint queryCommandSupported addEventListener
       removeEventListener dispatchEvent write writeln open close isEqualNode isSameNode appendChild
       hasChildNodes contains append prepend replaceChildren removeChild insertBefore replaceChild
-      cloneNode normalize compareDocumentPosition getRootNode
+      cloneNode normalize compareDocumentPosition getRootNode moveBefore
       lookupNamespaceURI lookupPrefix isDefaultNamespace
     ]
     def __js_call__(method, args)
@@ -1563,17 +2007,20 @@ module Dommy
         document_remove_child(args[0])
       when "insertBefore"
         raise Bridge::TypeError, "insertBefore requires 2 arguments." if args.length < 2
-        unless args[1].nil? || args[1].equal?(Bridge::UNDEFINED) || args[1].is_a?(Dommy::Node)
-          raise Bridge::TypeError, "The reference child is not a Node."
-        end
+        Internal::WebIDL.nullable_node!(args[1])
 
         document_insert_before(args[0], args[1])
       when "replaceChild"
         document_replace_child(args[0], args[1])
+      when "moveBefore"
+        raise Bridge::TypeError, "moveBefore requires 2 arguments." if args.length < 2
+
+        move_before(args[0], args[1])
+        Bridge::UNDEFINED
       when "cloneNode"
         clone_node(args[0])
       when "normalize"
-        nil # the document has no text children to merge
+        normalize
       when "writeln"
         write(*(args + ["\n"]))
       when "exitFullscreen"
@@ -1702,6 +2149,58 @@ module Dommy
       @node_wrapper_cache.wrap_cloned_element_ns(node, namespace, prefix, local, qualified_name)
     end
 
+    # The task scheduler this document's own tasks run on: its browsing context's
+    # when it has one, otherwise the one handed to it by whatever built it (a
+    # DOMParser document has no defaultView but still queues tasks on the window
+    # whose script created it).
+    attr_writer :task_scheduler
+
+    def __internal_scheduler__
+      (@default_view&.scheduler if @default_view.respond_to?(:scheduler)) || @task_scheduler
+    end
+
+    # The parser built the tree without any insertion or attribute steps
+    # running: give the elements that depend on them their due, once the
+    # document exists. Every details gets its insertion steps (the toggle event
+    # it owes, its exclusive accordion group settled), and every select has its
+    # list of options settled (a single-select the parser left with no, or
+    # several, selected options).
+    def __internal_run_parsed_insertion_steps__
+      return nil unless @backend_doc.respond_to?(:css)
+
+      elements = @backend_doc.css("details").filter_map { |node| wrap_node(node) }
+      HTMLDetailsElement.run_insertion_steps(elements) unless elements.empty?
+      @backend_doc.css("select").each { |node| wrap_node(node)&.__internal_settle_selectedness_once__ }
+      nil
+    end
+
+    # Bind an externally built wrapper to its backend node, so later traversals
+    # return the same Ruby object (JS identity) instead of building a new one.
+    def __internal_register_wrapper__(node, wrapper)
+      @node_wrapper_cache.register(node, wrapper)
+      wrapper
+    end
+
+    # The wrapper already cached for a backend node, or nil — never builds one.
+    def __internal_cached_wrapper__(node)
+      @node_wrapper_cache.cached_wrapper(node)
+    end
+
+    # Recorded when an element is created outside the HTML namespace or with a
+    # prefix. Deep cloning only has to carry that metadata across for a document
+    # that has some — which the overwhelming majority never do, so the ordinary
+    # `body.cloneNode(true)` keeps walking nothing.
+    def __internal_note_namespaced_element__(namespace, prefix)
+      return if namespace == Element::HTML_NAMESPACE && prefix.nil?
+
+      @namespaced_elements = true
+      nil
+    end
+
+    def __internal_namespaced_elements__?
+      @namespaced_elements == true
+    end
+
     # Clear the cached wrapper so the next `wrap_node` creates a new
     # one. Used by `customElements.define` to upgrade nodes that were
     # constructed before the registration landed.
@@ -1727,6 +2226,33 @@ module Dommy
       @shadow_registry.find_for_fragment(fragment_node)
     end
 
+    def __internal_shadow_root_for_host__(host_node)
+      @shadow_registry.find_for_host(host_node)
+    end
+
+    # Every element among `root`'s shadow-including inclusive descendants, as
+    # backend nodes, in shadow-including tree order: an element, then the shadow
+    # tree it hosts, then its children. The whole list, shadow trees included, is
+    # taken before the first element is yielded. Callbacks run synchronously here,
+    # and one that attaches a shadow root or inserts elements triggers those
+    # changes' own reactions; walking into them as well would run them twice.
+    def __internal_each_shadow_including_element__(root, &block)
+      shadow_including_elements(root).each(&block)
+      nil
+    end
+
+    def shadow_including_elements(root, list = [])
+      elements = root.respond_to?(:element?) && root.element? ? [root] : []
+      elements.concat(root.css("*").to_a) if root.respond_to?(:css)
+      elements.each do |element|
+        list << element
+        shadow = @shadow_registry.find_for_host(element)
+        shadow_including_elements(shadow.__dommy_backend_node__, list) if shadow
+      end
+      list
+    end
+    private :shadow_including_elements
+
     def __internal_shadow_root_containing__(node)
       @shadow_registry.find_enclosing(node)
     end
@@ -1754,6 +2280,12 @@ module Dommy
       @mutation_coordinator.notify_connected_subtree(nk)
     end
 
+    # The custom element reactions of a move (moveBefore), for a node that ended
+    # up connected.
+    def __internal_notify_moved_subtree__(nk)
+      @mutation_coordinator.notify_moved_subtree(nk)
+    end
+
     def __internal_notify_disconnected_subtree__(nk)
       @mutation_coordinator.notify_disconnected_subtree(nk)
     end
@@ -1770,22 +2302,114 @@ module Dommy
       @mutation_coordinator.unregister_observer(observer)
     end
 
+    # Queue the childList record for a mutation. The live-range insertion steps
+    # are NOT run here: WHATWG puts them at insert step 5, before the nodes are
+    # converted and linked, so every insertion site calls
+    # __internal_ranges_will_insert__ itself, at that point.
     def notify_child_list_mutation(
       target_node:,
       added_nodes:,
       removed_nodes:,
       previous_sibling: nil,
-      next_sibling: nil
+      next_sibling: nil,
+      moving: false
     )
       @mutation_coordinator.notify_child_list_mutation(
         target_node: target_node,
         added_nodes: added_nodes,
         removed_nodes: removed_nodes,
         previous_sibling: previous_sibling,
-        next_sibling: next_sibling
+        next_sibling: next_sibling,
+        moving: moving
+      )
+    end
+
+    # WHATWG "removing steps", run while `node` is STILL attached (they are all
+    # expressed in terms of the position it is about to vacate). Every path that
+    # takes a node out of its parent — an explicit removeChild, the implicit
+    # removal a move performs, replaceChildren, textContent=, fragment
+    # extraction — must go through here, or a live Range / NodeIterator anchored
+    # in the vacated position is left pointing at a detached node.
+    #
+    # A document with no live range and no NodeIterator has nothing to observe
+    # the vacated position, so the whole thing collapses to two predicate calls
+    # — this runs once per removed node, and a bulk replaceChildren /
+    # textContent= must not pay for machinery nobody is watching.
+    def pre_remove_node(node)
+      return nil if !node_iterators? && !live_ranges?
+      return nil unless node.parent
+
+      run_node_iterator_pre_remove(node)
+      __internal_ranges_will_remove__(node)
+      nil
+    end
+
+    # A childList mutation on the DOCUMENT's own child list (its doctype, the
+    # document element, a stray comment). Document-level mutation is observable
+    # like any other — `observe(document, {childList: true})` is legal — so it
+    # goes through the same pipeline rather than only nudging live ranges.
+    # Insert step 6 for a document parent: the reference child's previous
+    # sibling, or the document's last child when appending.
+    def document_insertion_previous_sibling(ref_bn)
+      node = ref_bn ? ref_bn.previous : @backend_doc.children.to_a.last
+      node && wrap_node(node)
+    end
+
+    def notify_document_child_list(added: [], removed: [], previous_sibling: nil, next_sibling: nil, moving: false)
+      notify_child_list_mutation(
+        target_node: @backend_doc,
+        added_nodes: added,
+        removed_nodes: removed,
+        previous_sibling: previous_sibling,
+        next_sibling: next_sibling,
+        moving: moving
       )
     end
 
+    # The single detach primitive: pre-removing steps, then unlink. Callers that
+    # batch several removals into one childList record (replaceChildren,
+    # textContent=, replaceChild) use this and queue the record themselves;
+    # `remove_node_with_notify` is this plus a per-node record.
+    #
+    # `moving:` marks the first half of the "move" primitive (moveBefore). A
+    # move takes the node out of its old parent's children only to put it
+    # straight back into the same shadow-including tree: it never leaves the
+    # document, so nothing that reacts to a removal from the document may run.
+    def detach_node(node, moving: false)
+      pre_remove_node(node)
+      add_transient_observers_for(node)
+      node.unlink
+      # A removal can take a shadow tree, and a selection range in it, out of
+      # the document without moving the range; the selection lets go of it.
+      @__selection&.__internal_node_removed__ unless moving
+      node
+    end
+
+    # WHATWG remove step 20: every subtree registration reachable from the old
+    # parent's inclusive ancestors gains a transient registered observer on the
+    # node being removed, so a subtree observer keeps seeing mutations inside
+    # the just-removed subtree until the next microtask checkpoint.
+    #
+    # The step is NOT guarded by suppressObservers (only step 21's record is),
+    # so it has to run here, in the removal primitive, rather than alongside the
+    # record. Replace all step 3, insert step 4 and replace step 7 all remove
+    # with observers suppressed.
+    def add_transient_observers_for(node)
+      return unless @observer_manager.any?
+
+      parent = node.parent
+      return unless parent
+
+      target = wrap_node(parent)
+      removed = wrap_node(node)
+      return unless target && removed
+
+      @observer_manager.observers_matching(target).each do |observer|
+        entry = observer.find_matching_entry(target)
+        observer.add_transient(removed, entry) if entry && entry[:subtree]
+      end
+    end
+
     # Unlink a backend node from its parent and queue a childList removal record
     # capturing the node's position (previous/next sibling) BEFORE the unlink, so
     # the record's previousSibling/nextSibling are correct (the coordinator can't
@@ -1796,8 +2420,7 @@ module Dommy
 
       prev_w = node.previous_sibling && wrap_node(node.previous_sibling)
       next_w = node.next_sibling && wrap_node(node.next_sibling)
-      run_node_iterator_pre_remove(node)
-      node.unlink
+      detach_node(node)
       notify_child_list_mutation(
         target_node: parent,
         added_nodes: [],
@@ -1807,14 +2430,198 @@ module Dommy
       )
     end
 
+    # --- Live ranges -------------------------------------------------
+    # Ranges are live: a DOM mutation moves their boundary points so they keep
+    # designating the same content. They are held weakly, so a range the caller
+    # drops is collected rather than pinned for the document's lifetime.
+
+    def __internal_register_range__(range)
+      @live_ranges ||= ObjectSpace::WeakMap.new
+      @live_ranges[range] = true
+      nil
+    end
+
+    def __internal_each_live_range__
+      return if @live_ranges.nil? || @live_ranges.size.zero?
+
+      @live_ranges.each_key { |range| yield range }
+    end
+
+    def live_ranges?
+      !@live_ranges.nil? && @live_ranges.size.positive?
+    end
+
+    # WHATWG "removing steps" for live ranges. Must run while `backend_node` is
+    # still attached, since the rules are expressed in terms of the position it
+    # is about to vacate.
+    def __internal_ranges_will_remove__(backend_node)
+      return unless live_ranges?
+
+      parent = backend_node.parent
+      return unless parent
+
+      removed = wrap_node(backend_node)
+      parent_wrapper = wrap_node(parent)
+      affected = live_ranges_where { |r| r.__internal_affected_by_removal__(removed, parent_wrapper) }
+      return if affected.empty?
+
+      index = child_index_of_wrapper(parent_wrapper, removed)
+      return unless index
+
+      affected.each { |r| r.__internal_apply_remove__(removed, parent_wrapper, index) }
+    end
+
+    # WHATWG "insert a node into a parent before a child", step 5 — the
+    # live-range offset shift.
+    #
+    # It runs BEFORE step 7 adopts each node (which removes it from wherever it
+    # is now), so `child`'s index, and every boundary it shifts, are measured
+    # against the tree as it stands before the insertion begins. Running it
+    # afterwards double-counts a boundary that one of those removals has just
+    # moved onto `parent`: `parent.insertBefore(second, first)` with a range
+    # inside `second` leaves that boundary at `(parent, 1)` per spec, but at
+    # `(parent, 2)` if the shift is applied after the move.
+    #
+    # Appending (a null `child`) shifts nothing: a boundary at the parent's end
+    # stays before the new nodes.
+    def __internal_ranges_will_insert__(parent_backend_node, ref_backend_node, count)
+      return if ref_backend_node.nil? || count.zero?
+      return unless live_ranges?
+
+      parent_wrapper = wrap_node(parent_backend_node)
+      return unless parent_wrapper.respond_to?(:child_nodes)
+
+      affected = live_ranges_where { |r| r.__internal_anchored_at__(parent_wrapper) }
+      return if affected.empty?
+
+      index = child_index_of_wrapper(parent_wrapper, wrap_node(ref_backend_node))
+      return unless index
+
+      affected.each { |r| r.__internal_apply_insert__(parent_wrapper, index, count) }
+    end
+
+    # WHATWG normalize() steps 6.1-6.4. `current` is a contiguous exclusive Text
+    # sibling whose data has just been appended to `node` at `length`; its own
+    # boundaries — and a parent-anchored boundary pointing AT it — follow the
+    # data into the merged node. Run for every merged sibling before any of them
+    # is removed, so the indices still describe the pre-removal tree.
+    def __internal_ranges_normalize_merge__(node, current, length)
+      return unless live_ranges?
+
+      merged_into = wrap_node(node)
+      current_wrapper = wrap_node(current)
+      parent = current.parent && wrap_node(current.parent)
+      index = parent && child_index_of_wrapper(parent, current_wrapper)
+      __internal_each_live_range__ do |range|
+        range.__internal_apply_normalize_merge__(merged_into, current_wrapper, length, parent, index)
+      end
+    end
+
+    # Node.normalize() on the document: every Text run in the tree.
+    def normalize
+      __internal_normalize__(@backend_doc)
+    end
+
+    # Node#normalize — merge each run of adjacent exclusive Text descendants
+    # into its first node (preserving that node's identity, so a JS reference
+    # to it survives) and drop empty Text nodes. Recurses the whole subtree,
+    # so it serves Element, DocumentFragment, ShadowRoot and the Document alike.
+    #
+    # A run is merged one sibling at a time: append the sibling's data to the
+    # survivor (a characterData record), hand its live range boundaries over,
+    # remove it (a childList record), then the next. Read literally, the spec
+    # concatenates every sibling's data first (steps 3-4, one "replace data")
+    # and removes them afterwards (step 7), which would queue ONE
+    # characterData record per run. Every shipping engine merges pairwise
+    # instead — Blink, WebCore and Gecko all answer [characterData, childList,
+    # characterData, childList, …] for a run of four text nodes, confirmed by
+    # running the same script in Chromium 141, WebKitGTK 2.52.6 and Firefox —
+    # and the WPT suite fixes only the childList side, so the records follow
+    # the engines. The tree and every live range boundary end up exactly where
+    # the spec's steps put them: a boundary in a later sibling (or on the
+    # parent, pointing at one) is shifted down by each earlier removal and
+    # then handed over at the survivor's length of that moment, which is the
+    # same offset the batch steps compute up front.
+    # https://github.com/takahashim/dommy/issues/24
+    def __internal_normalize__(root)
+      text_nodes = []
+      root.traverse { |node| text_nodes << node if node.respond_to?(:text?) && node.text? }
+
+      text_nodes.each do |node|
+        next unless node.parent # already removed as part of an earlier run
+
+        if node.content.to_s.empty?
+          remove_node_with_notify(node)
+          next
+        end
+
+        sib = node.next
+        while sib.respond_to?(:text?) && sib.text?
+          following = sib.next
+          data = sib.content.to_s
+          # The offset the sibling's data lands at inside the survivor — the
+          # length of what it already holds, measured before the append.
+          length = wrap_node(node).length
+          # An empty sibling has nothing to append: the engines skip the data
+          # step for it (Gecko checks the length, Blink and WebCore behave the
+          # same), so it is removed without a characterData record. Its range
+          # boundaries still move to the survivor's join.
+          unless data.empty?
+            old = node.content.to_s
+            node.content = old + data
+            notify_character_data_mutation(target_node: node, old_value: old)
+          end
+          # WHATWG normalize() step 6: the merged-away sibling hands its live
+          # range boundaries to the survivor at that offset BEFORE it is
+          # removed, or the plain removing steps would strand them on the
+          # parent.
+          __internal_ranges_normalize_merge__(node, sib, length)
+          remove_node_with_notify(sib)
+          sib = following
+        end
+      end
+
+      nil
+    end
+
+    def __internal_ranges_replaced_data__(node, offset, count, new_length)
+      return unless live_ranges?
+
+      __internal_each_live_range__ { |r| r.__internal_apply_replace_data__(node, offset, count, new_length) }
+    end
+
+    def __internal_ranges_split_text__(node, offset, new_node)
+      return unless live_ranges?
+
+      parent = node.parent_node
+      # Only the parent-anchored rule needs an index, so resolve one lazily.
+      index =
+        if parent && live_ranges_where { |r| r.__internal_anchored_at__(parent) }.any?
+          child_index_of_wrapper(parent, node)
+        end
+      __internal_each_live_range__ { |r| r.__internal_apply_split__(node, offset, new_node, parent, index) }
+    end
+
+    def live_ranges_where
+      out = []
+      __internal_each_live_range__ { |r| out << r if yield(r) }
+      out
+    end
+
+    def child_index_of_wrapper(parent_wrapper, child_wrapper)
+      return nil unless parent_wrapper.respond_to?(:child_nodes)
+
+      parent_wrapper.child_nodes.to_a.index { |c| c.equal?(child_wrapper) }
+    end
+
     # Run the "NodeIterator pre-removing steps" for every live iterator before
     # `backend_node` is detached, so referenceNode/pointerBeforeReferenceNode
     # stay valid. `backend_node` must still be attached (tree intact) here.
     def run_node_iterator_pre_remove(backend_node)
-      return if @node_iterators.empty?
+      return unless node_iterators?
 
       removed = wrap_node(backend_node)
-      @node_iterators.each { |iter| iter.pre_remove(removed) }
+      @node_iterators.each_key { |iter| iter.pre_remove(removed) }
     end
 
     def notify_attribute_mutation(target_node:, attribute_name:, old_value:, namespace: nil)
@@ -1895,41 +2702,106 @@ module Dommy
     # Build a Nokogiri copy of the given node inside our @backend_doc.
     # `deep: true` recurses into children. Used by importNode and
     # adoptNode for cross-document transfer.
-    def clone_into_doc(source, deep)
-      copy = if source.element?
-        new_el = Backend.create_element(source.name, @backend_doc)
-        Backend.attribute_nodes(source).each { |a| new_el[a.name] = a.value }
-        new_el
+    def clone_into_doc(source, deep, source_document = self)
+      copy = clone_single_node_into_doc(source, source_document)
+
+      if source.element? && source.name == "template"
+        # A <template>'s contents live in a separate content fragment, not its
+        # child list, so the generic deep pass over `children` misses them.
+        clone_template_content(source, copy, source_document) if deep
+      elsif deep && source.respond_to?(:children)
+        source.children.each do |child|
+          copy.add_child(clone_into_doc(child, true, source_document))
+        end
+      end
+
+      copy
+    end
+
+    # "Clone a single node" (§4.4): the copy implements the SAME interface as
+    # the original — a ProcessingInstruction clones to one, not to the comment
+    # its serialization looks like — and carries the same data. Elements are
+    # cloned by #clone_element_into_doc; children are the caller's business.
+    def clone_single_node_into_doc(source, source_document)
+      if source.element?
+        clone_element_into_doc(source, source_document)
+      elsif (cdata = Backend.cdata_class) && source.is_a?(cdata)
+        # CDATA is a Text subtype in the backend, so ask about it first.
+        Backend.create_cdata(source.content, @backend_doc)
       elsif source.text?
         Backend.create_text(source.content, @backend_doc)
       elsif source.is_a?(Backend.comment_class)
         Backend.create_comment(source.content, @backend_doc)
+      elsif source.is_a?(Backend.processing_instruction_class)
+        Backend.create_processing_instruction(source.target, source.content, @backend_doc)
       elsif source.is_a?(Backend.document_fragment_class)
         # A DocumentFragment clones to a fragment (its children are appended by
-        # the deep pass below), NOT to its first child — `importNode(<template>
+        # the deep pass), NOT to its first child — `importNode(<template>
         # .content, true)` must return a fragment so `.firstElementChild` works
         # (Vue/Alpine x-for clone template content this way). Built via the
         # document's own `fragment` (as TemplateContentRegistry does) rather than
         # `document_fragment_class.new`, so it works on backends whose fragment
         # class isn't directly instantiable (Makiri).
-        @backend_doc.fragment("")
+        Parser.fragment("", owner_doc: @backend_doc)
+      elsif (doctype = Backend.document_type_class) && source.is_a?(doctype)
+        wrapper = source_document.wrap_node(source)
+        Backend.create_document_type(wrapper.name, wrapper.public_id, wrapper.system_id, @backend_doc)
       else
-        # Fallback: serialize + reparse via fragment for unusual types.
-        fragment = Parser.fragment(source.to_html, owner_doc: @backend_doc)
-        fragment.children.first || Backend.create_text("", @backend_doc)
+        Backend.create_text("", @backend_doc)
       end
+    end
 
-      if source.element? && source.name == "template"
-        # A <template>'s contents live in a separate content fragment, not its
-        # child list, so the generic deep pass over `children` misses them.
-        clone_template_content(source, copy) if deep
-      elsif deep && source.respond_to?(:children)
-        source.children.each do |child|
-          copy.add_child(clone_into_doc(child, true))
+    # An element's copy keeps its namespace, its prefix and the exact spelling
+    # of its local name. None of that is on the backend node — the HTML backend
+    # tracks no namespace for an element script created, and createElementNS's
+    # case lives on the wrapper — so the original is read through its wrapper
+    # and the copy is given the same metadata.
+    def clone_element_into_doc(source, source_document)
+      wrapper = source_document.wrap_node(source)
+      namespace, prefix, local, qualified = clone_name_parts(wrapper, source)
+      copy = Backend.create_element_loose(qualified, prefix, local, namespace, @backend_doc) ||
+        Backend.create_element(source.name, @backend_doc)
+      copy_attributes_into(source, copy)
+      note_cloned_element_namespace(copy, namespace, prefix, local, qualified)
+      copy
+    end
+
+    # The four parts of the original's name — namespace, prefix, local name and
+    # qualified name. The wrapper's own metadata has them whenever there is
+    # anything to carry (createElementNS's case and prefix, an XML document's,
+    # the HTML parser's SVG names); otherwise the element is an unprefixed one
+    # whose namespace the backend knows.
+    def clone_name_parts(wrapper, source)
+      meta = wrapper.__internal_namespace_metadata__ if wrapper.respond_to?(:__internal_namespace_metadata__)
+      return meta if meta
+
+      local = wrapper ? wrapper.local_name.to_s : source.name
+      [wrapper&.namespace_uri, nil, local, local]
+    end
+
+    # "Clone a single node" step 2.1 clones the attributes one by one, so each
+    # keeps its own namespace and prefix — an `xml:b` must not flatten into an
+    # attribute whose local name is the qualified string "xml:b".
+    def copy_attributes_into(source, copy)
+      Backend.attribute_nodes(source).each do |attr|
+        info = Backend.attribute_ns_info(attr)
+        if info[:namespace_uri]
+          Backend.set_attribute_ns(copy, info[:namespace_uri], info[:prefix], info[:local_name],
+            info[:qualified_name], info[:value])
+        else
+          copy[info[:qualified_name]] = info[:value]
         end
       end
+      nil
+    end
 
-      copy
+    # Give the copy's wrapper the namespace metadata whenever the backend node
+    # alone would report something else (see #clone_element_into_doc).
+    def note_cloned_element_namespace(copy, namespace, prefix, local, qualified)
+      derived = Backend.namespace_of(copy)&.href || (html_document? ? Element::HTML_NAMESPACE : nil)
+      return if derived == namespace && prefix.nil? && local == copy.name
+
+      wrap_cloned_element_ns(copy, namespace, prefix, local, qualified)
     end
 
     # Clone a <template>'s content into a fragment registered as `copy`'s
@@ -1937,13 +2809,14 @@ module Dommy
     # keeps it in a native content fragment, Nokogiri keeps it as direct children
     # before migration and in the registry after — so source it from the registry
     # fragment when migrated, else from Backend.template_content_nodes.
-    def clone_template_content(source, copy)
-      src_frag = @template_content_registry.raw_fragment_for(source)
+    def clone_template_content(source, copy, source_document = self)
+      registry = source_document.__internal_template_registry__
+      src_frag = registry.raw_fragment_for(source)
       content_nodes = src_frag ? src_frag.children.to_a : Backend.template_content_nodes(source)
       return if content_nodes.empty?
 
-      frag = @backend_doc.fragment("")
-      content_nodes.each { |n| frag.add_child(clone_into_doc(n, true)) }
+      frag = Parser.fragment("", owner_doc: @backend_doc)
+      content_nodes.each { |n| frag.add_child(clone_into_doc(n, true, source_document)) }
       @template_content_registry.store(copy, frag)
     end
 
@@ -1968,7 +2841,7 @@ module Dommy
         head.add_child(title)
       end
 
-      title.children.each(&:unlink)
+      title.children.to_a.each { |child| detach_node(child) }
       title.add_child(Backend.create_text(value, @backend_doc))
     end