makiri 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c178d50564ea8152e886817e6df19628c491eb7bb1213e06ab70f6ffe8665015
-  data.tar.gz: 55a69b4d93c40b130581cb078ffee01dc6355cec4843fdc0f86269d7d22a4390
+  metadata.gz: ece0ed1298dbb761fbaeecc7e497b20ee69766c988ef5e0c671e282a3a455de9
+  data.tar.gz: a909b7cbd715ad23e58f5c4f649298c6ca4472c9004423eb73930baadea205ec
 SHA512:
-  metadata.gz: c87c6c98a58fe500d60f7775c088c655d3938e22cf614ed57b84d395d15229bd4dfbf5e61909c86804132d90dfdb31d62278e36ed7399c66102590c13867ca36
-  data.tar.gz: 2da0687466e5c2faab9d0c95d8181e529acf68b30165c9357375edb10e5dff5cd45557e7186c133fdfaf40043f7d2c2f3ee1a49d945cacea4f46c1b56b195c2c
+  metadata.gz: 265f7671dd689039fb98a41513b45fa2b3dae542f9a99942832fe25e36c1b4e7430caf8c14f39c3832947819258a850cacca556ef278785356d616d5b132cd16
+  data.tar.gz: 7bed0126338689b1e5c2bbf47b60d9550352b471162f80b030cad11141158efbd7a293f48551be73bbdfe1ac9d24cab6c0074ff46ef5d01e2aa404888e147c0e

data/.github/workflows/security.yml

@@ -157,6 +157,55 @@ jobs:
   # poisoning on), catching intra-arena overflows that a plain ASan build cannot
   # see - the class the v3.0.0 :lexbor-contains overflow belonged to. Heavy
   # (full instrumented Lexbor rebuild), so nightly only.
+  # The randomised property checks (spec/invariants/). Cheap enough to gate a PR
+  # on, so they run on every push; the ASan pass is nightly because an
+  # instrumented build is slow.
+  invariants:
+    name: Invariant checks
+    runs-on: ubuntu-latest
+    if: github.event_name != 'schedule'
+    steps:
+      - name: Checkout (with vendored Lexbor submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Ensure cmake is available
+        uses: lukka/get-cmake@latest
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run the invariant checks
+        run: bundle exec rake invariants
+
+  invariants-sanitize:
+    name: Nightly invariant checks under ASan + UBSan
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Checkout (with vendored Lexbor submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Ensure cmake is available
+        uses: lukka/get-cmake@latest
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      # The text index hands out borrowed slices, so a stale one is a memory bug
+      # as much as a wrong answer - this is the pass that would see it.
+      - name: Run the invariant checks under sanitizers
+        run: bundle exec rake "invariants:sanitize"
+
   security-sanitize-lexbor:
     name: Nightly instrumented-Lexbor ASan suite
     runs-on: ubuntu-latest

data/.github/workflows/valgrind.yml

@@ -24,11 +24,16 @@ jobs:
   # (intra-arena overflows).  Runs on Linux because Valgrind is x86_64/amd64
   # Linux only.
   valgrind-memcheck:
-    name: Valgrind memcheck (Ruby ${{ matrix.ruby }})
+    name: Valgrind memcheck (Ruby ${{ matrix.ruby }}, shard ${{ matrix.shard }}/4)
     runs-on: ubuntu-latest
     timeout-minutes: 360
     env:
       BUNDLE_WITH: valgrind
+      # Shard the suite across the matrix below: 4 parallel jobs each memcheck a
+      # quarter of the spec files, so the whole suite finishes in ~1/4 the
+      # wall-clock with no loss of coverage (each shard is balanced by file size).
+      VALGRIND_SHARDS: "4"
+      VALGRIND_SHARD_INDEX: ${{ matrix.shard }}
       # These heavy jobs verify memory discipline (uninit values, intra-arena
       # overflows, use-after-move), not the property space - so the full
       # 300-iteration PBT sweep (already run by the normal CI matrix) is
@@ -37,10 +42,16 @@ jobs:
       # keeping the run tractable.
       PBT_COUNT: "15"
       CSS_PBT_COUNT: "15"
+      # --track-origins roughly doubles memcheck's runtime and only adds an origin
+      # backtrace to a finding (the finding itself is still reported without it).
+      # Drop it on the frequent post-merge push gate to halve its runtime; keep it
+      # for the thorough nightly / manual runs, where the backtrace aids triage.
+      VALGRIND_TRACK_ORIGINS: ${{ github.event_name == 'push' && 'no' || 'yes' }}
     strategy:
       fail-fast: false
       matrix:
         ruby: ["3.4"]
+        shard: [0, 1, 2, 3]   # keep in sync with VALGRIND_SHARDS above
 
     steps:
       - name: Checkout (with vendored Lexbor submodule)

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [0.9.0] - 2026-09-11
+
+### Added
+
+* `Node#attribute_by_qualified_name(name)` and
+  `Node#attribute_value_by_qualified_name(name)`: the attribute whose
+  **qualified** name is exactly `name` — its node, and its value — or nil.
+  `#[]` cannot answer this: it also finds a prefixed attribute by its local
+  name (`svg_a["href"]` returns `xlink:href`), and it lower-cases what it looks
+  up (`el["DATA-X"]` finds `data-x`). The new match is byte-exact.
+
+### Changed
+
+* **`Makiri::XML` follows the DOM namespace model.** A node's namespace URI is
+  decided once — by the parser, or by the context it is first inserted into —
+  and does not change afterwards; the serializer emits whatever xmlns
+  declarations the output needs:
+
+  - moving a node under an element that binds its prefix to a different URI
+    keeps `namespace_uri`, and the output declares the prefix at the moved node;
+  - inserting a node whose prefix is bound nowhere in the destination now
+    succeeds instead of raising;
+  - `import_node` keeps the namespace of what it copied;
+  - an element in no namespace stays in no namespace under a default namespace,
+    serialized as `xmlns=""`;
+  - `#to_xml` on a node below the root declares the prefixes its subtree uses,
+    so the output re-parses to the same namespaces standing alone.
+
+  Nodes from the factories (`create_element` and friends) still take their
+  namespace from the context they are first inserted into.
+
+* **Inserting a node from another document adopts it.** `add_child` / `before` /
+  `after` / `replace` bring the node over and remove it from the document it
+  came from, instead of copying it (`Makiri::XML`) or raising (`Makiri::HTML`).
+  A spliced fragment is left empty; a rejected insert leaves the source
+  document untouched.
+
+  The node handed back is a **different object** than the one passed in, so use
+  the return value afterwards rather than the argument. `Document#import_node`
+  is unchanged: it copies and leaves the source alone.
+
+* **XML serialization is capped at the nesting depth the parser accepts.**
+  `#to_xml` and `#canonicalize` raise `Makiri::Error` past it, rather than
+  emitting XML that Makiri could not read back. A deeper tree is still fine to
+  hold, walk and query.
+
+### Fixed
+
+* XPath axes from an **attribute** context node on the XML backend now follow
+  XPath 1.0 §2.2: `following-sibling` and `preceding-sibling` are empty, and
+  `following` / `preceding` exclude attribute nodes. They used to return the
+  element's later attributes.
+
+* A rejected insert no longer leaves part of the moved subtree carrying
+  namespace URIs resolved against the scope it was refused from.
+
+## [0.8.0] - 2026-07-12
+
+### Fixed
+
+* `Document#import_node` (DOM `importNode` / `adoptNode`) now imports an HTML
+  element whose name is a valid DOM name but not a well-formed XML QName (e.g.
+  `":good:times:"`, `"x<"`, `"0:a"`) instead of raising. Such an element is not
+  XML-serializable (`#to_xml` raises). An element carrying a similarly lenient
+  attribute name is still rejected.
+
 ## [0.7.0] - 2026-07-11
 
 ### Added

data/README.md

@@ -110,7 +110,9 @@ doc.css("feed > entry").map { |e| e.at_css("title").text }  # => ["Hello", "Worl
 
 # Serialize back to XML
 doc.to_xml                                 # => "<?xml version=\"1.0\"?>\n<feed ...>...</feed>\n"
-doc.at_xpath("//a:entry", ns).to_xml       # => "<entry><title>Hello</title></entry>" (no declaration)
+# A node below the root serializes self-contained: no XML declaration, but the
+# namespace declarations its subtree needs, so the output re-parses the same.
+doc.at_xpath("//a:entry", ns).to_xml       # => "<entry xmlns=\"http://www.w3.org/2005/Atom\"><title>Hello</title></entry>"
 doc.to_xml(pretty: true)                   # indented, element-only content
 
 # DOCTYPE is recognized but the DTD is not processed (no entities, no I/O):
@@ -138,8 +140,11 @@ doc.root.to_xml           # => "<feed xmlns:dc=\"urn:dc\"><post dc:k=\"v\">Bye</
 ```
 
 XML subtrees can be built with `Document#create_element` and related node factory methods,
-then inserted with `#add_child`, `#before`, `#after`, or `#replace`;
-namespaces are resolved at insertion time, and cross-document nodes are deep-copied.
+then inserted with `#add_child`, `#before`, `#after`, or `#replace`. A factory-built
+node takes its namespace from the context it is first inserted into; one that already
+has a namespace keeps it. A node from another document is **adopted** — brought over
+and removed from the document it came from — and the method returns the node now in
+the tree, which is a different object than the one passed in.
 
 `Document#import_node(node, deep = false)` brings a node into a document as a
 detached copy, and works **across representations**: importing a `Makiri::HTML`
@@ -240,6 +245,34 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
     (QNames), never PI targets. Nokogiri/libxml2 rejects it (`colons are forbidden
     from PI names`); Makiri follows the normative text. Only the reserved `xml`
     (any case) target is rejected.
+* A node's **namespace URI is its identity**, not something re-derived from the
+  declarations around it - the WHATWG DOM model, measured against Chrome 152
+  (`DOMParser` + `XMLSerializer`).
+  * Moving a node under an element that binds its prefix to a different URI does
+    **not** change `namespace_uri`; the serializer emits the declaration the
+    output needs (`<p:x xmlns:p="urn:a"/>`), and nothing when the destination
+    already agrees. libxml2 keeps the URI on an in-document move but does *not*
+    emit the declaration, so Nokogiri's tree and its own output disagree there.
+  * `#to_xml` on a node below the root is **self-contained**: it declares the
+    prefixes its subtree uses, so the output re-parses to the same namespaces
+    standing alone. Nokogiri omits them, and its subtree output does not
+    round-trip.
+  * Where one prefix would have to mean two things at once, the serializer
+    invents one (`ns1`, `ns2`, ...) rather than shadow the other, as browsers do.
+  * An element in **no** namespace stays that way under a default namespace,
+    serialized as `xmlns=""`.
+  * Nodes from the factories (`create_element` and friends) still take their
+    namespace from the context they are first inserted into, so a subtree can be
+    built detached and attached afterwards. Only later moves carry.
+* Inserting a node **from another document adopts it** (`add_child` / `before` /
+  `after` / `replace`): it is brought over and taken out of the document it came
+  from, as `appendChild` does in the DOM and in both Chrome and Nokogiri.
+  * Each arena owns its own nodes, so the node cannot be relinked across them: it
+    is copied here and removed there. The one visible difference from Nokogiri
+    and browsers is that the node handed back is a **different object** than the
+    one passed in - use the return value afterwards, not the argument.
+  * `Document#import_node` is the copy: it leaves the source alone, like DOM
+    `importNode`.
 * Otherwise the parsed tree is byte-identical to `Nokogiri::XML`'s (verified by
   the property-based differential), including namespaces, prolog/epilog comments
   and PIs, and adjacent-CDATA coalescing.
@@ -267,6 +300,21 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
 * Type selectors are ASCII case-insensitive (CSS-correct for HTML; `LI` matches `<li>`)
   * `Nokogiri::HTML5` is case-sensitive there.
 
+### Serialization
+
+* **Comment data is written literally**, as the WHATWG serialization algorithm
+  says and as browsers do: `comment.content = "a-->b"` serializes to
+  `<!--a-->b-->`, which re-parses as the comment `"a"` followed by text.
+  * `Nokogiri::HTML5` escapes it to `<!--a--&gt;b-->` instead. That does not
+    round-trip either - comments do not decode entities, so the data comes back
+    as `"a--&gt;b"`. Neither library round-trips this; Makiri matches Chrome.
+* The same applies to the children of `style` / `script` / `xmp` / `iframe` /
+  `noembed` / `noframes` / `plaintext`, which the algorithm also writes
+  literally. `noscript` is **escaped**, because Makiri parses it with scripting
+  disabled (its children are elements, not raw text) and escaping is what makes
+  that round-trip; `Nokogiri::HTML5` writes it literally and contradicts its own
+  parser there.
+
 ### Text input (mutation APIs)
 
 * Programmatic string arguments must be **valid UTF-8** (invalid bytes raise

data/Rakefile

@@ -88,7 +88,12 @@ begin
       "--error-limit=no",
       "--trace-children=yes",   # spec processes may fork
       "--undef-value-errors=yes", # the point of this job (ruby_memcheck defaults to =no)
-      "--track-origins=yes",    # report where an uninitialised value came from
+      # Origin tracking (where an uninitialised value came from) roughly DOUBLES
+      # memcheck's run time. It is a diagnostic aid, not a detection capability -
+      # memcheck still reports the uninitialised USE without it - so the frequent
+      # post-merge push gate turns it off (VALGRIND_TRACK_ORIGINS=no) to run in
+      # ~half the time, while the nightly / manual runs keep it on for the backtrace.
+      "--track-origins=#{ENV.fetch('VALGRIND_TRACK_ORIGINS', 'yes')}",
       "--leak-check=no",        # leaks are `rake leaks`' job, not this one
     ],
   )
@@ -96,7 +101,34 @@ begin
   namespace :spec do
     desc "Run the spec suite under Valgrind memcheck (ruby_memcheck; needs the " \
          ":valgrind bundler group and the valgrind binary)"
-    RubyMemcheck::RSpec::RakeTask.new(valgrind: :compile)
+    RubyMemcheck::RSpec::RakeTask.new(valgrind: :compile) do |t|
+      # Let spec_helper skip :slow examples (fail-closed limit tests whose sheer
+      # volume dominates memcheck without adding memory-safety coverage).
+      ENV["VALGRIND"] = "1"
+
+      # Optional sharding for CI wall-clock: with VALGRIND_SHARDS=N (>1) the spec
+      # files are partitioned into N groups and this run does only group
+      # VALGRIND_SHARD_INDEX, so N parallel matrix jobs cover the whole suite in
+      # ~1/N the time WITHOUT dropping any coverage. Files are packed
+      # largest-first onto the currently-lightest shard (greedy LPT by file size,
+      # a proxy for runtime), so the slowest shard - which sets wall-clock - is
+      # balanced rather than left to name order. Deterministic, so every shard
+      # computes the same partition and takes its own index. Default N=1 = the
+      # whole suite (local `rake spec:valgrind`).
+      shards = Integer(ENV.fetch("VALGRIND_SHARDS", "1"))
+      if shards > 1
+        index   = Integer(ENV.fetch("VALGRIND_SHARD_INDEX", "0"))
+        buckets = Array.new(shards) { { load: 0, files: [] } }
+        # sort by (size desc, name) so the packing is fully deterministic across
+        # shards regardless of Array#sort stability.
+        Dir["spec/**/*_spec.rb"].sort_by { |f| [-File.size(f), f] }.each do |f|
+          b = buckets.min_by { |x| x[:load] }
+          b[:files] << f
+          b[:load] += File.size(f)
+        end
+        t.pattern = buckets.fetch(index)[:files]
+      end
+    end
   end
 rescue LoadError
   # ruby_memcheck not installed (optional :valgrind group absent) - skip the task.
@@ -194,6 +226,63 @@ task :sanitize do
   sh(env, "#{FileUtils::RUBY} -S rspec")
 end
 
+# The randomised property checks in spec/invariants/. They are not *_spec.rb, so
+# `rake spec` skips them; they run here and nightly in CI. Each takes
+# [documents] [seed] [html|xml] and is deterministic, so a finding replays.
+INVARIANT_CHECKS = [
+  ["check_ns_reresolve.rb",       %w[]],
+  ["check_import_clone.rb",       %w[]],
+  ["check_tree_invariants.rb",    %w[html xml]],
+  ["check_index_staleness.rb",    %w[html xml]],
+  ["check_serialize_fixpoint.rb", %w[html xml]],
+  ["check_text_input.rb",         nil],           # takes no count
+].freeze
+
+# [[script, argv], ...] for a given document count.
+def invariant_runs(count)
+  INVARIANT_CHECKS.flat_map do |script, backends|
+    path = "spec/invariants/#{script}"
+    next [[path, []]] if backends.nil?
+    next [[path, [count.to_s]]] if backends.empty?
+
+    backends.map { |b| [path, [count.to_s, "20260911", b]] }
+  end
+end
+
+desc "Run the invariant checks (override the document count via INVARIANT_COUNT)"
+task invariants: :compile do
+  count = (ENV["INVARIANT_COUNT"] || 2000).to_i
+  invariant_runs(count).each do |script, argv|
+    sh "#{FileUtils::RUBY} -Ilib #{script} #{argv.join(' ')}"
+  end
+end
+
+desc "Run the invariant checks under AddressSanitizer + UBSan (the text index " \
+     "holds borrowed slices, so staleness there is a memory bug too)"
+task "invariants:sanitize" do
+  sanitize = ENV["MAKIRI_SANITIZE"] || "address,undefined"
+  sh({ "MAKIRI_SANITIZE" => sanitize }, "#{FileUtils::RUBY} -S rake clean compile")
+
+  env = {
+    "ASAN_OPTIONS"  => "detect_leaks=0:detect_container_overflow=0:" \
+                       "detect_odr_violation=0:abort_on_error=1:halt_on_error=1",
+    "UBSAN_OPTIONS" => "print_stacktrace=1:halt_on_error=1",
+  }
+  if sanitize.include?("address")
+    runtime = asan_runtime_path or
+      abort "invariants:sanitize: could not locate the ASan runtime for #{RbConfig::CONFIG['CC']}"
+    preload = RbConfig::CONFIG["target_os"] =~ /darwin/ ? "DYLD_INSERT_LIBRARIES" : "LD_PRELOAD"
+    env[preload] = runtime
+    puts "invariants:sanitize: preloading #{runtime} via #{preload}"
+  end
+
+  # Instrumented builds are slow; a smaller sweep still exercises every path.
+  count = (ENV["INVARIANT_COUNT"] || 500).to_i
+  invariant_runs(count).each do |script, argv|
+    sh(env, "#{FileUtils::RUBY} -Ilib #{script} #{argv.join(' ')}")
+  end
+end
+
 desc "Measure C coverage of OUR sources (clang source-based) over the spec suite. " \
      "Prints an llvm-cov region+branch report (excludes vendored Lexbor) and writes " \
      "a line-level detail file to tmp/coverage/show.txt."

data/ext/makiri/dom_adapter/cross_import.c

@@ -185,15 +185,37 @@ h2x_make(mkr_xml_doc_t *xdoc, lxb_dom_node_t *s, const char *pdef, uint32_t pdef
         size_t nl;
         const lxb_char_t *nm = lxb_dom_element_qualified_name(lxb_dom_interface_element(s), &nl);
         if (!MKR_FITS_U32(nl)) return MKR_XML_MUT_OOM;
+
+        /* The element's namespace URI (borrowed from the source doc's ns table). */
+        uint32_t eul;
+        const char *euri = mkr_html_ns_uri(s, &eul);
+
+        /* Strict first, so a valid QName stays XML-serializable. importNode/adoptNode
+         * never re-validate an existing node's name (DOM requires the source already
+         * be well-formed for its representation), so an HTML name that is a valid DOM
+         * element name but NOT a well-formed XML QName (":good:times:", "x<", "0:a")
+         * is taken VERBATIM as an unprefixed DOM-loose name (local == whole) rather
+         * than rejected - the same non-serializable escape hatch as
+         * create_loose_dom_element. HTML elements are always unprefixed. The namespace
+         * is passed DIRECTLY because ns resolution at link time skips loose names
+         * (resolve_node_ns), so a synthesized xmlns declaration would not reach it. */
         mkr_xml_node_t *el = NULL;
         mkr_xml_mut_status_t st = mkr_xml_new_element(xdoc, (const char *)nm, (uint32_t)nl, &el);
+        if (st == MKR_XML_MUT_BAD_NAME && nl > 0) {
+            mkr_xml_qname_t qn = {
+                (const char *)nm, (uint32_t)nl,   /* qname          */
+                (const char *)nm, 0,              /* prefix (none)  */
+                (const char *)nm, (uint32_t)nl,   /* local == qname */
+            };
+            st = mkr_xml_new_loose_dom_element(xdoc, &qn, euri, eul, &el);
+        }
         if (st != MKR_XML_MUT_OK) return st;
 
-        /* Declare the element's default namespace iff it differs from the inherited
-         * one, so this (unprefixed, like all HTML elements) element resolves to it.
-         * An element with no namespace under an inherited default undeclares (xmlns=""). */
-        uint32_t eul;
-        const char *euri = mkr_html_ns_uri(s, &eul);
+        /* Declare the default namespace iff it differs from the inherited one, so
+         * this (unprefixed, like all HTML elements) element and its children resolve
+         * to it. An element with no namespace under an inherited default undeclares
+         * (xmlns=""). For a loose element this only feeds child inheritance - its own
+         * ns_uri was already set directly above. */
         if (!mkr_uri_eq(euri, eul, pdef, pdef_len)) {
             st = h2x_declare_ns(xdoc, el, NULL, 0, euri, eul);
             if (st != MKR_XML_MUT_OK) return st;

data/ext/makiri/glue/glue.h

@@ -124,6 +124,7 @@ lxb_dom_node_t *mkr_run_fragment_parser(VALUE html, mkr_fragment_parse_fn parse,
  * Implemented in ruby_doc.c (next to the import machinery), bound in
  * mkr_init_node. */
 VALUE mkr_node_clone_node(int argc, VALUE *argv, VALUE self);
+lxb_dom_node_t *mkr_html_import_deep(lxb_dom_document_t *doc, lxb_dom_node_t *src);
 
 /* NodeSet bridge (glue/ruby_node_set.c). mkr_raw_node_t (above): callers cast
  * their typed node to it when pushing (forgetting the type is the safe, store

data/ext/makiri/glue/ruby_doc.c

@@ -339,6 +339,20 @@ mkr_run_fragment_parser(VALUE html, mkr_fragment_parse_fn parse, void *ctx)
     return root;
 }
 
+/* Deep-import +src+ into +doc+, <template> contents included - the copy step of
+ * adopting a node from another document (ruby_html_mutate.c). Raises rather than
+ * returning a partial node. */
+lxb_dom_node_t *
+mkr_html_import_deep(lxb_dom_document_t *doc, lxb_dom_node_t *src)
+{
+    lxb_dom_node_t *imp = lxb_dom_document_import_node(doc, src, true);
+    if (imp == NULL) {
+        rb_raise(mkr_eError, "failed to import node");
+    }
+    mkr_fixup_template_content(doc, src, imp);
+    return imp;
+}
+
 /* Node#clone_node(deep = false): a shallow (or deep, with deep truthy) copy of
  * this node, owned by the same document and detached from any parent - the DOM
  * cloneNode, whose `deep` defaults to false (a missing/nil/false argument =>

data/ext/makiri/glue/ruby_html_mutate.c

@@ -26,11 +26,13 @@ lxb_dom_attr_qualified_name_append(lexbor_hash_t *hash, const lxb_char_t *name,
  * DOM mutation (v0.2). Thin wrappers over Lexbor's insert/remove/create
  * functions, with the safety checks Lexbor itself omits:
  *
- *   - same-document: a node can only be inserted into its own document
- *     (cross-document moves would splice foreign-arena pointers);
  *   - no cycles: a node cannot become a descendant of itself;
  *   - attribute nodes are not tree children.
  *
+ * A node from another document is ADOPTED, as the DOM says appendChild does: it
+ * cannot be relinked across arenas, so it is copied here and released there
+ * (mkr_adopt_copy / mkr_adopt_release), and the verb hands back the copy.
+ *
  * We never destroy detached nodes: the document arena owns all node memory and
  * frees it wholesale, and live Ruby wrappers may still point at a removed node.
  * `remove`/`unlink` therefore only detach.
@@ -57,26 +59,81 @@ mkr_arg_node(VALUE v)
     return mkr_html_node_unwrap(v);
 }
 
-/* Validate that `incoming` may be placed relative to `ref` and detach it from
- * any current parent (move semantics). Raises on the unsafe cases. */
+/* Copy +node+ into +doc+, for a node that came from another document. Lexbor's
+ * arenas own their own nodes, so it cannot be relinked across them; the copy is
+ * this half of the DOM's adopt, and mkr_adopt_release is the other. */
+static lxb_dom_node_t *
+mkr_adopt_copy(lxb_dom_document_t *doc, lxb_dom_node_t *node)
+{
+    return mkr_html_import_deep(doc, node);
+}
+
+/* The other half: take +node+ out of the document it came from, so the whole
+ * thing reads as the move the DOM says appendChild performs.
+ *
+ * Called only AFTER the insert has gone through, so a refused one leaves the
+ * source document alone - the same ordering the XML backend uses. */
 static void
-mkr_prepare_insert(lxb_dom_node_t *ref, lxb_dom_node_t *incoming)
+mkr_adopt_release(lxb_dom_node_t *node)
+{
+    if (node->type == LXB_DOM_NODE_TYPE_DOCUMENT_FRAGMENT) {
+        /* A fragment contributes its children; the DOM leaves a spliced one
+         * empty, so empty the source rather than detaching it. */
+        lxb_dom_node_t *c;
+        while ((c = node->first_child) != NULL) lxb_dom_node_remove(c);
+    } else if (node->parent != NULL) {
+        lxb_dom_node_remove(node);
+    }
+}
+
+/* Validate that `rb_incoming` may be placed relative to `ref`, detach it from
+ * any current parent (move semantics), and return the node to actually insert.
+ *
+ * For a node from another document that is its copy (see mkr_adopt_copy), so
+ * the returned node is not always the one passed in and the caller must insert
+ * - and hand back - what this returns. *+adopt_from+ receives the argument in
+ * that case, for mkr_inserted_result to release once the insert has gone
+ * through; Qnil otherwise. Holding the Ruby VALUE, rather than the raw node,
+ * also keeps the source document reachable until then - the same protocol the
+ * XML backend uses (mkr_xml_incoming_node / mkr_xml_adopt_finish).
+ *
+ * Raises on the unsafe cases. */
+static lxb_dom_node_t *
+mkr_prepare_insert(lxb_dom_node_t *ref, VALUE rb_incoming, VALUE *adopt_from)
 {
+    lxb_dom_node_t *incoming = mkr_arg_node(rb_incoming);
+
+    *adopt_from = Qnil;
     if (incoming->type == LXB_DOM_NODE_TYPE_ATTRIBUTE) {
         rb_raise(mkr_eError, "an attribute node cannot be inserted into the tree");
     }
-    if (ref->owner_document != incoming->owner_document) {
-        rb_raise(mkr_eError, "cannot move a node between documents");
-    }
     /* incoming must not be an inclusive ancestor of ref. */
     for (lxb_dom_node_t *p = ref; p != NULL; p = p->parent) {
         if (p == incoming) {
             rb_raise(mkr_eError, "cannot insert a node into its own subtree");
         }
     }
+    if (ref->owner_document != incoming->owner_document) {
+        *adopt_from = rb_incoming;
+        return mkr_adopt_copy(ref->owner_document, incoming);
+    }
     if (incoming->parent != NULL) {
         lxb_dom_node_remove(incoming);
     }
+    return incoming;
+}
+
+/* The value an insertion verb hands back: its argument, or - when the node was
+ * adopted - the node now in the tree, which is a different object. Finishing the
+ * adoption here keeps the release after the insert, where it belongs. */
+static VALUE
+mkr_inserted_result(VALUE self, VALUE rb_arg, lxb_dom_node_t *inserted,
+                    VALUE adopt_from)
+{
+    if (NIL_P(adopt_from)) return rb_arg;
+
+    mkr_adopt_release(mkr_arg_node(adopt_from));
+    return mkr_wrap_html_node(inserted, mkr_node_document(self));
 }
 
 /* WHATWG doctype ordering at the document node (https://dom.spec.whatwg.org/#concept-node-ensure-pre-insertion-validity),
@@ -194,12 +251,12 @@ static VALUE
 mkr_node_add_child(VALUE self, VALUE rb_child)
 {
     lxb_dom_node_t *parent = mkr_node_unwrap_mutable(self);
-    lxb_dom_node_t *child  = mkr_arg_node(rb_child);
-    mkr_guard_doc_child_order(parent, NULL, NULL, child);   /* append: before == NULL */
-    mkr_prepare_insert(parent, child);
-    mkr_splice_or_insert(parent, child, lxb_dom_node_insert_child, 0);
+    mkr_guard_doc_child_order(parent, NULL, NULL, mkr_arg_node(rb_child));   /* append */
+    VALUE adopt_from;
+    lxb_dom_node_t *ins = mkr_prepare_insert(parent, rb_child, &adopt_from);
+    mkr_splice_or_insert(parent, ins, lxb_dom_node_insert_child, 0);
     mkr_invalidate_index(self);
-    return rb_child;
+    return mkr_inserted_result(self, rb_child, ins, adopt_from);
 }
 
 /* node << child -> node (chainable). */
@@ -214,30 +271,30 @@ static VALUE
 mkr_node_add_previous_sibling(VALUE self, VALUE rb_node)
 {
     lxb_dom_node_t *ref  = mkr_node_unwrap_mutable(self);
-    lxb_dom_node_t *node = mkr_arg_node(rb_node);
     if (ref->parent == NULL) {
         rb_raise(mkr_eError, "cannot add a sibling to a node with no parent");
     }
-    mkr_guard_doc_child_order(ref->parent, ref, NULL, node);   /* inserted before ref */
-    mkr_prepare_insert(ref, node);
-    mkr_splice_or_insert(ref, node, lxb_dom_node_insert_before, 0);
+    mkr_guard_doc_child_order(ref->parent, ref, NULL, mkr_arg_node(rb_node));
+    VALUE adopt_from;
+    lxb_dom_node_t *ins = mkr_prepare_insert(ref, rb_node, &adopt_from);
+    mkr_splice_or_insert(ref, ins, lxb_dom_node_insert_before, 0);
     mkr_invalidate_index(self);
-    return rb_node;
+    return mkr_inserted_result(self, rb_node, ins, adopt_from);
 }
 
 static VALUE
 mkr_node_add_next_sibling(VALUE self, VALUE rb_node)
 {
     lxb_dom_node_t *ref  = mkr_node_unwrap_mutable(self);
-    lxb_dom_node_t *node = mkr_arg_node(rb_node);
     if (ref->parent == NULL) {
         rb_raise(mkr_eError, "cannot add a sibling to a node with no parent");
     }
-    mkr_guard_doc_child_order(ref->parent, ref->next, NULL, node);   /* inserted after ref */
-    mkr_prepare_insert(ref, node);
-    mkr_splice_or_insert(ref, node, lxb_dom_node_insert_after, 1);
+    mkr_guard_doc_child_order(ref->parent, ref->next, NULL, mkr_arg_node(rb_node));
+    VALUE adopt_from;
+    lxb_dom_node_t *ins = mkr_prepare_insert(ref, rb_node, &adopt_from);
+    mkr_splice_or_insert(ref, ins, lxb_dom_node_insert_after, 1);
     mkr_invalidate_index(self);
-    return rb_node;
+    return mkr_inserted_result(self, rb_node, ins, adopt_from);
 }
 
 /* node.remove / node.unlink -> node. Detaches from the tree (still usable). */
@@ -260,16 +317,16 @@ static VALUE
 mkr_node_replace(VALUE self, VALUE rb_other)
 {
     lxb_dom_node_t *ref   = mkr_node_unwrap_mutable(self);
-    lxb_dom_node_t *other = mkr_arg_node(rb_other);
     if (ref->parent == NULL) {
         rb_raise(mkr_eError, "cannot replace a node with no parent");
     }
-    mkr_guard_doc_child_order(ref->parent, ref, ref, other);   /* other takes ref's slot */
-    mkr_prepare_insert(ref, other);
-    mkr_splice_or_insert(ref, other, lxb_dom_node_insert_before, 0);
+    mkr_guard_doc_child_order(ref->parent, ref, ref, mkr_arg_node(rb_other));
+    VALUE adopt_from;
+    lxb_dom_node_t *ins = mkr_prepare_insert(ref, rb_other, &adopt_from);
+    mkr_splice_or_insert(ref, ins, lxb_dom_node_insert_before, 0);
     lxb_dom_node_remove(ref);
     mkr_invalidate_index(self);
-    return rb_other;
+    return mkr_inserted_result(self, rb_other, ins, adopt_from);
 }
 
 /* ------------------------------------------------------------------ */