makiri 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8998ec8f7ae9b6e9f31fb3b880f50a53602e2cdea51b42faa33613638e2ceedc
-  data.tar.gz: df9c18e5917eb79e2b0311a65c70e1b648e40c62fd1b14ecec1d64b4394f3930
+  metadata.gz: ece0ed1298dbb761fbaeecc7e497b20ee69766c988ef5e0c671e282a3a455de9
+  data.tar.gz: a909b7cbd715ad23e58f5c4f649298c6ca4472c9004423eb73930baadea205ec
 SHA512:
-  metadata.gz: 5bd1a20a81195609e360ffc71108cef27a62803a387526dfdb38cf7cbf0ae6bde69e48815717ba1d236300c2aedd376589b4799c610a883ebf088d8a37e0f3ce
-  data.tar.gz: 1104a702f5348a2e52705c81153af1baaad12bcc3a649e5e863d5e8a6c98da3566ede4efa8cb0f0b8d091b0ba3ee9abef0c67dcf83ddae33d48706999df9cd74
+  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/CHANGELOG.md

@@ -1,5 +1,61 @@
 # 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

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

@@ -226,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/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);
 }
 
 /* ------------------------------------------------------------------ */

data/ext/makiri/glue/ruby_html_node.c

@@ -8,6 +8,8 @@
 
 #include <lexbor/ns/ns.h>   /* lxb_ns_by_id, LXB_NS__UNDEF (namespaceURI) */
 
+#include "../core/mkr_span.h"   /* mkr_bytes_eq */
+
 /* ------------------------------------------------------------------ */
 /* wrap / unwrap                                                      */
 /* ------------------------------------------------------------------ */
@@ -720,6 +722,81 @@ mkr_node_attribute_nodes(VALUE self)
     return set;
 }
 
+/* element.attribute_by_qualified_name(name) -> the Attr node whose QUALIFIED
+ * name is exactly `name`, or nil. Nil for non-elements.
+ *
+ * `#[]` / `#key?` cannot answer this: they go through Lexbor's attribute-name
+ * hash, which is keyed by LOCAL name (lxb_dom_element_attr_by_name), so on an
+ * element carrying a prefixed attribute - `<a xlink:href>` in an inline <svg>,
+ * say - `el["href"]` hands that attribute back. The DOM's by-name family
+ * (getAttribute, setAttribute, removeAttribute) is defined on the qualified
+ * name, where `getAttribute("href")` there is null, and needs the exact match.
+ *
+ * The match is also BYTE-EXACT, where `#[]` lower-cases what it looks up
+ * (`el["DATA-X"]` finds `data-x`). getAttribute's ASCII-lowercasing applies only
+ * to an HTML element in an HTML document, so the caller does that step.
+ *
+ * The scan is the element's own attribute list (elements carry a handful), and
+ * compares the same string #name reports for an Attr. */
+static VALUE
+mkr_node_attribute_by_qualified_name(VALUE self, VALUE rb_name)
+{
+    lxb_dom_node_t *node = mkr_html_node_unwrap(self);
+    if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
+        return Qnil;
+    }
+
+    mkr_ruby_borrowed_text_t nv = mkr_ruby_verified_text(rb_name, "attribute name");
+    VALUE out = Qnil;
+    lxb_dom_attr_t *attr =
+        lxb_dom_element_first_attribute(lxb_dom_interface_element(node));
+    while (attr != NULL) {
+        size_t len = 0;
+        const lxb_char_t *qname = lxb_dom_attr_qualified_name(attr, &len);
+        if (mkr_bytes_eq(qname, len, nv.ptr, nv.len)) {
+            out = mkr_wrap_html_node(lxb_dom_interface_node(attr),
+                                     mkr_node_document(self));
+            break;
+        }
+        attr = lxb_dom_element_next_attribute(attr);
+    }
+    RB_GC_GUARD(nv.value);
+    return out;
+}
+
+/* element.attribute_value_by_qualified_name(name) -> the value String of that
+ * attribute, or nil. The same match as #attribute_by_qualified_name, without
+ * wrapping an Attr node: this is the shape a DOM `getAttribute` / `hasAttribute`
+ * wants, and those run often enough for the wrapper to show up. An empty value
+ * answers "", which is how `hasAttribute` tells it from an absent attribute. */
+static VALUE
+mkr_node_attribute_value_by_qualified_name(VALUE self, VALUE rb_name)
+{
+    lxb_dom_node_t *node = mkr_html_node_unwrap(self);
+    if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
+        return Qnil;
+    }
+
+    mkr_ruby_borrowed_text_t nv = mkr_ruby_verified_text(rb_name, "attribute name");
+    VALUE out = Qnil;
+    lxb_dom_attr_t *attr =
+        lxb_dom_element_first_attribute(lxb_dom_interface_element(node));
+    while (attr != NULL) {
+        size_t len = 0;
+        const lxb_char_t *qname = lxb_dom_attr_qualified_name(attr, &len);
+        if (mkr_bytes_eq(qname, len, nv.ptr, nv.len)) {
+            size_t vlen = 0;
+            const lxb_char_t *val = lxb_dom_attr_value(attr, &vlen);
+            out = mkr_ruby_str_from_borrowed(
+                mkr_borrowed_text((const char *)val, vlen));
+            break;
+        }
+        attr = lxb_dom_element_next_attribute(attr);
+    }
+    RB_GC_GUARD(nv.value);
+    return out;
+}
+
 /* attr.value -> the attribute's value String. For non-attribute nodes, falls
  * back to text content (matching the loose Nokogiri-ish meaning of #value). */
 static VALUE
@@ -862,6 +939,10 @@ mkr_init_node(void)
     rb_define_method(mkr_mHtmlNodeMethods, "keys",   mkr_node_keys,    0);
     rb_define_method(mkr_mHtmlNodeMethods, "values", mkr_node_values,  0);
     rb_define_method(mkr_mHtmlNodeMethods, "attribute_nodes", mkr_node_attribute_nodes, 0);
+    rb_define_method(mkr_mHtmlNodeMethods, "attribute_by_qualified_name",
+                     mkr_node_attribute_by_qualified_name, 1);
+    rb_define_method(mkr_mHtmlNodeMethods, "attribute_value_by_qualified_name",
+                     mkr_node_attribute_value_by_qualified_name, 1);
     rb_define_method(mkr_mHtmlNodeMethods, "value",  mkr_node_value,   0);
     rb_define_method(mkr_mHtmlNodeMethods, "line",   mkr_node_line,    0);