makiri 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48c6dfd55ed565531aea117967aee1f4b8f3405ff0e36ca8766ffa729a1ee27e
-  data.tar.gz: 1866e9eb174ea0a6428a8f1c81f65ed8756d61c2429de935876d60547a4bc6bd
+  metadata.gz: baaa765e2bd6208137962299994628a55a36ab68e29f9de9921e686679c69bf2
+  data.tar.gz: cd74ab123b1f8384d7aa14c448f1f12ee78371335061b60728c06424ccc5973b
 SHA512:
-  metadata.gz: f847d9d772a2865bcd6e3f9b1626f0b67e4215d14d844b529bd194e9d287aa288cc2a555156799f842ac68fcc13405e1cfff317a506c2476b87eb24646f17c46
-  data.tar.gz: ee1fe65b9055dc2a9c11cdbbd789544ef72ef1bd2c8fa731ab0eab2f97173125ab3f96637da903d33df76dfa80e221dd0e11abeaa446f5683e1428cc7f6552af
+  metadata.gz: 9ce8aa721e0e6848e2f7015f924f510599064f309c590181abef990e9b81121a1675aade8917515fdc35577bb65bb5edcf0d72ce4582df686eb0156d461d5e7b
+  data.tar.gz: 692a2a400e1be9ecc12fcd67cf317f5d7e51eef38c2846f25ab3bc23dd6626acdf02d860309e4444bf1b2b646461e8a32934804ebc8d1cc3f9a8593d729a79d8

data/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [0.14.0] - 2026-10-04
+
+### Added
+
+* `Document#attribute_version` (HTML and XML): an Integer that increases
+  whenever an attribute is added, removed or set (to the same value too),
+  including through an Attr node's `content=` or `remove`. Child-list and
+  text edits leave it as it is, so it can key a cache of attributes.
+* `Makiri::XML::Document#create_element_ns(namespace_uri, qualified_name)`,
+  like the HTML Document's and the DOM's `createElementNS`. The element keeps
+  its namespace wherever it is inserted; a name that is not an XML QName
+  (`f}oo`) makes an element that `to_xml` refuses.
+* `Makiri::HTML::Document.new`: an empty HTML document in no-quirks mode.
+* `Makiri::HTML::Document#quirks_mode?` and `#compat_mode` (`"BackCompat"` /
+  `"CSS1Compat"`, like the DOM's `compatMode`).
+* HTML `Attr#remove` / `#unlink` remove the attribute from its element, as on
+  XML. They raised "use delete(name) to remove an attribute".
+
+### Changed
+
+* `tree_version` counts child-list changes only. A Text, Comment, CDATA or
+  PI node's `content=` no longer moves it, and an HTML Attr node's
+  `content=` moves `attribute_version` instead.
+* `tree_version` and `attribute_version` are documented as cache keys: an
+  unchanged version means nothing it covers changed, while a changed one may
+  be conservative (an edit refused part-way can still move it).
+* `namespace_uri` and `prefix` are documented as `nil`, never `""`, when
+  there is no namespace or prefix, in HTML and XML.
+* `Document#dup` copies the tree node by node instead of re-parsing its
+  serialization. An HTML copy keeps a tree with no `<html>` root as it is and
+  keeps the quirks mode, and `Node#line` on it is `nil`. An XML copy keeps
+  every name and namespace as written (a re-parse invented `ns1:` prefixes),
+  copies data XML cannot write, and keeps the original's `max_bytes`.
+* XML `create_processing_instruction` accepts the target `xml` (in any case),
+  as the DOM does; `to_xml` and `canonicalize` refuse a tree holding one.
+* HTML `create_processing_instruction` raises `ArgumentError`, as XML does,
+  for data containing `?>`. It raised `Makiri::Error`.
+* A refused XML insertion names the DOM rule it breaks, in the same words as
+  HTML. It said "invalid placement".
+
+### Fixed
+
+* An Attr's `content=` and `remove` raise `FrozenError` when the element
+  that owns it is frozen, in HTML and XML.
+* XML `Attr#content=` sets the attribute's value. It raised "operation
+  unsupported".
+* HTML `title=` and `meta_encoding=` do nothing on a document with no
+  `<head>`, as the DOM's title setter does. They inserted the element directly
+  under the root element.
+* HTML `Document#root` and CSS `:root` return the document element, or `nil`.
+  Without an `<html>` element they returned the first child of any kind, such
+  as a comment, and `title=` raised on such a document.
+* An edit refused for its arguments - a frozen or non-node argument to an
+  HTML insertion, an invalid name given to XML `[]=`, `set_attribute_ns` or
+  `set_loose_dom_attribute`, a refused HTML `Attr#remove` - no longer moves a
+  version.
+* An XML copy that runs out of the document's byte budget (`import_node`,
+  `clone_node`, an insertion from another document) gives back what it used.
+  The document could not be edited any more after one.
+* Importing HTML into an XML document stores each namespace URI once instead
+  of once per element, which used up the byte budget faster.
+* An HTML Attr imported on its own from another HTML document keeps its
+  namespace URI as written. It was lower-cased.
+* `to_xml` and `canonicalize` write an element in the XML namespace as
+  `xml:local`. They wrote a declaration that does not parse. An element in
+  the XMLNS namespace is refused with `Makiri::Error`.
+* XML XPath: a prefixed attribute on a detached element, whose namespace is
+  not decided yet, no longer matches an unprefixed name test.
+* XML: references are read by one grammar everywhere. The internal subset
+  accepted a character reference to a character XML does not allow
+  (`<!ENTITY x "&#0;">`), and a malformed reference next to an entity
+  reference was reported as an unsupported DTD construct instead of as
+  malformed XML.
+
 ## [0.13.0] - 2026-10-03
 
 ### Added

data/README.md

@@ -184,6 +184,12 @@ and unusually large documents can raise it with `max_bytes:`.
 Makiri::XML(huge_xml, max_bytes: 512 * 1024 * 1024)   # also Makiri::XML::Document.parse(..., max_bytes:)
 ```
 
+The limit covers the document's whole life, not only the parse: nodes and
+values made by editing it count too, and a replaced value or a removed node
+keeps its bytes until the document is gone. A document edited for a long time
+can be compacted with `dup`, which copies only what is in it now, under the
+same limit.
+
 ### Node identity
 
 Navigating to the same node always gives the same Ruby object, for as long as

data/ext/makiri/rust/build.rs

@@ -193,7 +193,6 @@ fn main() {
         .allowlist_function("lexbor_hash_insert")
         .allowlist_var("lexbor_hash_search_raw")
         .allowlist_var("lexbor_hash_insert_raw")
-        .allowlist_function("lxb_dom_document_root")
         .allowlist_type("lxb_html_token_t")
         .allowlist_type("lxb_html_token_type_t")
         // The token-type FLAGS are in `enum lxb_html_token_type` - no trailing
@@ -283,6 +282,7 @@ fn main() {
         .allowlist_function("lxb_dom_document_type_create")
         .allowlist_function("lxb_dom_document_import_node")
         .allowlist_function("lexbor_str_init")
+        .allowlist_function("lxb_html_document_create")
         .allowlist_function("lxb_html_document_destroy")
         // The document title reader, generated rather than hand-declared like
         // the rest of this list.
@@ -416,12 +416,6 @@ const UNDECLARED_EXPORTS: &[(&str, &str, &str, &str)] = &[
         "lxb_dom_element_t *element, const lxb_char_t *prefix, size_t prefix_len, \
          const lxb_char_t *lname, size_t lname_len",
     ),
-    (
-        "lexbor/ns/ns.c",
-        "LXB_API const lxb_ns_data_t *",
-        "lxb_ns_append",
-        "lexbor_hash_t *hash, const lxb_char_t *link, size_t length",
-    ),
 ];
 
 fn check_undeclared_exports(include: &std::path::Path) {

data/ext/makiri/rust/src/bridge/doc.rs

@@ -34,8 +34,8 @@ use crate::bridge::xml::xml_node_document;
 use crate::bridge::xml::{xml_mut_result, xml_node_unwrap};
 use crate::lexbor::adapter::cross_import::cross_xml_to_html;
 use crate::lexbor::adapter::html::{RawDoc, RawNode};
-use crate::lexbor::adapter::post_parse::{parse_html, HtmlParseError};
-use crate::lexbor::adapter::tree_guard::{DepthLimit, MAX_SELECT_OPTIONS};
+use crate::lexbor::adapter::post_parse::{empty_html_document, parse_html, HtmlParseError};
+use crate::lexbor::adapter::tree_guard::{DepthLimit, GuardStop, MAX_SELECT_OPTIONS};
 
 /* ------------------------------------------------------------------ *
  * parsing                                                            *
@@ -49,13 +49,24 @@ pub fn select_options_error() -> Error {
     ))
 }
 
+/// The error for a parse the guard refused (`GuardStop`), for a document and
+/// a fragment alike: the one place that maps a stop to its exception.
+pub fn guard_error(stop: GuardStop, limit: DepthLimit) -> Error {
+    match stop {
+        GuardStop::TooDeep => tree_depth_error(limit),
+        GuardStop::TooManyOptions => select_options_error(),
+    }
+}
+
 /// The error for a parse the tree-depth limit refused: `Makiri::Error`, naming
 /// the limit, for a document and a fragment alike.
 pub fn tree_depth_error(limit: DepthLimit) -> Error {
     match limit.max_depth() {
         Some(n) => makiri_error(format!("document tree depth limit exceeded ({n})")),
-        /* Unreachable: an unlimited parse is never refused for depth. */
-        None => makiri_error("document tree depth limit exceeded"),
+        /* An unlimited parse is never refused for depth. */
+        None => crate::bridge::ruby::internal_error(
+            "a parse with no tree-depth limit was refused for depth",
+        ),
     }
 }
 
@@ -91,8 +102,7 @@ pub fn parse_document(source: Value, limit: DepthLimit) -> Result<Value, Error>
     drop(owned);
 
     let parsed = result.map_err(|e| match e {
-        HtmlParseError::TooDeep => tree_depth_error(limit),
-        HtmlParseError::TooManyOptions => select_options_error(),
+        HtmlParseError::Guard(stop) => guard_error(stop, limit),
         HtmlParseError::Failed => makiri_error("failed to parse HTML document"),
     })?;
     /* The GC learns the arena's size in `install`; `owned` is already gone, so
@@ -100,12 +110,24 @@ pub fn parse_document(source: Value, limit: DepthLimit) -> Result<Value, Error>
     Ok(shell.install_html(parsed))
 }
 
+/// An empty HTML document - no children - in `compat_mode` (Lexbor's
+/// numbering): `Makiri::HTML::Document.new` (no-quirks) and the copy
+/// `Document#dup` fills.
+pub fn new_empty_document(compat_mode: u32) -> Result<Value, Error> {
+    /* The wrapper first, while nothing needs freeing - see DocumentShell. */
+    let shell = DocumentShell::new(DocKind::Html);
+    let parsed = empty_html_document(compat_mode)
+        .map_err(|_| makiri_error("failed to create HTML document"))?;
+    Ok(shell.install_html(parsed))
+}
+
 /* ------------------------------------------------------------------ *
  * read-only accessors                                                *
  * ------------------------------------------------------------------ */
 
-/// `Document#root`: the root Element node, or nil (unreachable today - the HTML
-/// parser inserts html/head/body even for empty input).
+/// `Document#root`: the root Element node, or nil - for `Document.new`, or once
+/// the root is removed (the HTML parser inserts html/head/body even for empty
+/// input).
 pub fn document_root(rb_doc: Value) -> Result<Option<Value>, Error> {
     let Some(root) = html_doc(&rb_doc).as_node().document_root() else {
         return Ok(None);

data/ext/makiri/rust/src/bridge/dom_error.rs

@@ -0,0 +1,47 @@
+//! The errors the DOM's insertion rules raise, worded once for HTML and XML.
+//!
+//! Both representations keep a refusal's reason as a
+//! [`PreInsertError`](crate::dom_rules::PreInsertError) all the way here, so
+//! the same broken rule reads the same in either - XML used to fold every rule
+//! but two into one sentence.
+
+#![forbid(unsafe_code)]
+
+use crate::bridge::ruby::makiri_error;
+use crate::dom_rules::{Hierarchy as H, PreInsertError, Violation};
+use magnus::Error;
+
+/// The `Makiri::Error` an insertion `e` refused raises.
+pub fn pre_insert_error(e: PreInsertError) -> Error {
+    makiri_error(message(e))
+}
+
+fn message(e: PreInsertError) -> &'static str {
+    match e {
+        PreInsertError::NoParent { replacing: true } => "cannot replace a node with no parent",
+        PreInsertError::NoParent { replacing: false } => {
+            "cannot add a sibling to a node with no parent"
+        }
+        /* Unreachable through either representation's insertion, which takes
+         * the reference child from the parent it names; worded all the same. */
+        PreInsertError::Rule(Violation::NotFound) => {
+            "the reference node is not a child of the parent"
+        }
+        PreInsertError::Rule(Violation::HierarchyRequest(h)) => match h {
+            H::ParentNotContainer => {
+                "only a document, a document fragment or an element can have children"
+            }
+            H::Ancestor => "cannot insert a node into its own subtree",
+            H::AttributeNode => "an attribute node cannot be inserted into the tree",
+            H::DocumentNode => "a document node cannot be inserted into the tree",
+            H::UnsupportedNode => "this kind of node cannot be inserted into the tree",
+            H::DoctypeParent => "a doctype node can only be a child of the document",
+            H::DuplicateDoctype => "the document already has a doctype",
+            H::DoctypeAfterElement | H::ElementBeforeDoctype => {
+                "a doctype must precede the document element"
+            }
+            H::SecondDocumentElement => "the document already has a root element",
+            H::TextUnderDocument => "text cannot be a child of the document",
+        },
+    }
+}

data/ext/makiri/rust/src/bridge/fragment.rs

@@ -28,8 +28,7 @@ use crate::lexbor::fragment::{FragmentContext, FragmentError, TransientFragment}
 /// A fragment-parse failure as `Makiri::Error`.
 fn fragment_error(e: FragmentError, limit: DepthLimit) -> Error {
     match e {
-        FragmentError::TooDeep => crate::bridge::doc::tree_depth_error(limit),
-        FragmentError::TooManyOptions => crate::bridge::doc::select_options_error(),
+        FragmentError::Guard(stop) => crate::bridge::doc::guard_error(stop, limit),
         _ => makiri_error(e.message()),
     }
 }

data/ext/makiri/rust/src/bridge/gvl.rs

@@ -107,8 +107,7 @@ pub fn without_gvl<F: FnOnce() -> R + Send, R>(f: F) -> Result<R, magnus::Error>
         }
         if slot.f.is_none() {
             /* It ran and neither answered nor panicked - which `run` cannot do. */
-            return Err(magnus::Error::new(
-                crate::init::EXC_INTERNAL_ERROR.exception(),
+            return Err(crate::bridge::ruby::internal_error(
                 "the GVL-released body ran without a result",
             ));
         }

data/ext/makiri/rust/src/bridge/html.rs

@@ -17,8 +17,7 @@ use crate::init::{
     CLASS_HTML_PROCESSING_INSTRUCTION, CLASS_HTML_TEXT, CLASS_XML_DOCUMENT,
 };
 use crate::lexbor::adapter::html::{
-    ForeignNode, HtmlNode, HtmlNodeKey, HtmlNodeMut, Insertion, NodeType, Place, PreInsertError,
-    RawDoc, RawNode,
+    ForeignNode, HtmlNode, HtmlNodeKey, HtmlNodeMut, Insertion, NodeType, Place, RawDoc, RawNode,
 };
 use crate::lexbor::fragment::import_with_fixup;
 
@@ -282,7 +281,8 @@ pub(in crate::bridge) fn with_html_node<R>(
 
 /// The receiver cleared for an edit - not frozen, its document not under
 /// evaluation - and the PROOF of it: [`edit`] is the only way to build one and
-/// [`HtmlEdit::node`] the only way to spend it. The XML side's `Editing`.
+/// [`HtmlEdit::node`] (or its attribute and data twins) the only way to spend
+/// it, ONCE - they take `self`. The XML side's `Editing`, spent the same way.
 ///
 /// The checks and the index drop are two steps on purpose. The checks come
 /// first, so a frozen receiver is reported before a bad argument. The drop
@@ -298,12 +298,26 @@ pub struct HtmlEdit<'a> {
 /// before [`HtmlEdit::node`].
 pub fn edit(this: &HtmlSelf) -> Result<HtmlEdit<'_>, Error> {
     crate::bridge::ruby::check_frozen(this.value)?;
+    check_attr_owner_frozen(this)?;
     ensure_document_mutable(this.document)?;
     /* Before any argument is converted: see `account_growth`. */
     crate::bridge::wrapper::account_growth(this.document);
     Ok(HtmlEdit { this })
 }
 
+/// An Attr receiver's edit changes its OWNER's attribute list, so a frozen
+/// owner refuses it as it refuses `delete` - checked with the receiver's own
+/// frozen flag, before and after the arguments are converted.
+fn check_attr_owner_frozen(this: &HtmlSelf) -> Result<(), Error> {
+    let node = this.node();
+    match (node.node_type(), node.parent()) {
+        (NodeType::Attribute, Some(owner)) => {
+            crate::bridge::wrapper::check_node_frozen(this.document, RawNode::from(owner))
+        }
+        _ => Ok(()),
+    }
+}
+
 impl<'a> HtmlEdit<'a> {
     /// The receiver's node, read-only, for a check that no argument can
     /// change (its node type).
@@ -325,25 +339,34 @@ impl<'a> HtmlEdit<'a> {
     /// to engine calls and checks that call no Ruby (`insert` reads its
     /// argument's node and frozen flag there, and nothing more).
     ///
-    /// It counts as a change to a child list ([`bump_tree_version`]); an
-    /// attribute edit takes [`HtmlEdit::node_for_attributes`] instead.
+    /// It counts as a change to a child list ([`record_edit`]); an
+    /// attribute edit takes [`HtmlEdit::node_for_attributes`] instead, and a
+    /// character-data edit [`HtmlEdit::node_for_data`].
     pub fn node(self) -> Result<HtmlNodeMut<'a>, Error> {
-        self.mutable(true)
+        self.mutable(EditKind::ChildList)
     }
 
-    /// [`HtmlEdit::node`] for an edit of the element's ATTRIBUTES only, which
-    /// changes no child list and so leaves the tree version alone.
+    /// [`HtmlEdit::node`] for an edit of ATTRIBUTES only - an element's, or an
+    /// Attr node's value - which changes no child list: it counts towards the
+    /// attribute version ([`record_edit`]) instead of the tree
+    /// version.
     pub fn node_for_attributes(self) -> Result<HtmlNodeMut<'a>, Error> {
-        self.mutable(false)
+        self.mutable(EditKind::Attributes)
     }
 
-    fn mutable(self, structural: bool) -> Result<HtmlNodeMut<'a>, Error> {
+    /// [`HtmlEdit::node`] for an edit of a Text, Comment, CDATA or PI node's
+    /// DATA, which changes no child list and no attribute: no version counts
+    /// it (see [`EditKind::CharacterData`]).
+    pub fn node_for_data(self) -> Result<HtmlNodeMut<'a>, Error> {
+        self.mutable(EditKind::CharacterData)
+    }
+
+    fn mutable(self, kind: EditKind) -> Result<HtmlNodeMut<'a>, Error> {
         crate::bridge::ruby::check_frozen(self.this.value)?;
+        check_attr_owner_frozen(self.this)?;
         ensure_document_mutable(self.this.document)?;
         invalidate_indexes(self.this.document);
-        if structural {
-            bump_tree_version(self.this.document);
-        }
+        record_edit(self.this.document, kind);
         // SAFETY: the receiver is not frozen and no XPath evaluation is
         // reading its document - both checked just now.
         Ok(unsafe { HtmlNodeMut::assume_mutable(self.this.raw().as_node()) })
@@ -379,16 +402,16 @@ fn adopt_copy<'d>(doc: RawDoc, node: HtmlNode<'_>) -> Result<HtmlNode<'d>, Error
 /// document's indexes, which still list it. A structural change to a document
 /// invalidates ITS indexes; this is one, made from another document's method.
 fn adopt_release(src: Value) -> Result<(), Error> {
+    /* Invalidated and recorded before the release (`record_edit`); the node
+     * borrow below is taken after, as dropping the indexes borrows too. */
+    let src_doc = keepalive_document(src)?;
+    invalidate_indexes(src_doc);
+    record_edit(src_doc, EditKind::ChildList);
     with_arg_node(src, |node| {
         /* SAFETY: the source document was cleared for editing by
          * `take_incoming` before anything was copied out of it. */
         release_from_tree(unsafe { HtmlNodeMut::assume_mutable(node) });
-    })?;
-    /* After the borrow `with_arg_node` held: dropping them borrows again. */
-    let src_doc = keepalive_document(src)?;
-    invalidate_indexes(src_doc);
-    bump_tree_version(src_doc);
-    Ok(())
+    })
 }
 
 fn release_from_tree(node: HtmlNodeMut<'_>) {
@@ -412,7 +435,7 @@ fn release_from_tree(node: HtmlNodeMut<'_>) {
 /// [`Insertion::check`], the shared `crate::dom_rules`); after that only the adoption copy can fail, and it
 /// too runs before a link is touched.
 pub fn insert(this: &HtmlSelf, rb_incoming: Value, place: Place) -> Result<Value, Error> {
-    let target = edit(this)?.node()?;
+    let edit = edit(this)?;
     let (key, incoming_doc) = html_node_key(rb_incoming)?;
     /* The argument is relinked too - `place` changes its parent and siblings, and
      * an adoption removes it from its own document - so a frozen argument is a
@@ -422,6 +445,12 @@ pub fn insert(this: &HtmlSelf, rb_incoming: Value, place: Place) -> Result<Value
      * checked, because frozenness lives on the Ruby object and there is no map
      * from a node back to its wrapper. */
     crate::bridge::ruby::check_frozen(rb_incoming)?;
+    /* An adoption changes the argument's own document too (see
+     * `take_incoming`, which checks again). Refused here as well, so every
+     * refusal about the argument comes before `node` records the edit, as the
+     * XML side's does. */
+    ensure_document_mutable(incoming_doc)?;
+    let target = edit.node()?;
     /* The argument, resolved against its own Document, for the checks, the
      * copy or move, and the placing - none of which runs Ruby or wraps a
      * node. Releasing an adopted original and wrapping its copy borrow a
@@ -429,7 +458,7 @@ pub fn insert(this: &HtmlSelf, rb_incoming: Value, place: Place) -> Result<Value
     let (placed, adopted) = with_html_node(incoming_doc, key, |incoming| {
         Insertion::new(target.node(), place, incoming)
             .and_then(|i| i.check())
-            .map_err(|e| refused(e, place))?;
+            .map_err(crate::bridge::dom_error::pre_insert_error)?;
         let (node, adopted) = take_incoming(target, incoming_doc, incoming)?;
         target.place(node, place);
         Ok::<_, Error>((RawNode::from(node.node()), adopted))
@@ -441,38 +470,6 @@ pub fn insert(this: &HtmlSelf, rb_incoming: Value, place: Place) -> Result<Value
     wrap_html_node(placed, this.document)
 }
 
-/// A refused insertion, worded. The one place these messages live.
-fn refused(e: PreInsertError, place: Place) -> Error {
-    use crate::dom_rules::{Hierarchy as H, Violation};
-    makiri_error(match e {
-        PreInsertError::NoParent if place == Place::Replace => {
-            "cannot replace a node with no parent"
-        }
-        PreInsertError::NoParent => "cannot add a sibling to a node with no parent",
-        /* Unreachable through `Insertion::new`, which takes the reference child
-         * from the parent it names; worded all the same. */
-        PreInsertError::Rule(Violation::NotFound) => {
-            "the reference node is not a child of the parent"
-        }
-        PreInsertError::Rule(Violation::HierarchyRequest(h)) => match h {
-            H::ParentNotContainer => {
-                "only a document, a document fragment or an element can have children"
-            }
-            H::Ancestor => "cannot insert a node into its own subtree",
-            H::AttributeNode => "an attribute node cannot be inserted into the tree",
-            H::DocumentNode => "a document node cannot be inserted into the tree",
-            H::UnsupportedNode => "this kind of node cannot be inserted into the tree",
-            H::DoctypeParent => "a doctype node can only be a child of the document",
-            H::DuplicateDoctype => "the document already has a doctype",
-            H::DoctypeAfterElement | H::ElementBeforeDoctype => {
-                "a doctype must precede the document element"
-            }
-            H::SecondDocumentElement => "the document already has a root element",
-            H::TextUnderDocument => "text cannot be a child of the document",
-        },
-    })
-}
-
 /// The node to put in the tree for `incoming`: itself, taken out of where it
 /// was, or - from another document - a copy made in `target`'s, with `true`
 /// for "release the original once the copy is in" (see [`adopt_release`]).

data/ext/makiri/rust/src/bridge/mod.rs

@@ -59,6 +59,9 @@ pub mod node_set;
 #[cfg(feature = "lexbor")]
 pub mod node_wrap;
 
+/// The errors the DOM's insertion rules raise, for HTML and XML alike.
+pub mod dom_error;
+
 /// The Ruby <-> XPath engine seam: which backend a query runs on, and
 /// building the engine context for a Ruby node or document.
 #[cfg(feature = "lexbor")]

data/ext/makiri/rust/src/bridge/ruby.rs

@@ -33,6 +33,13 @@ pub fn makiri_error(msg: impl Into<std::borrow::Cow<'static, str>>) -> Error {
     Error::new(error_class(), msg)
 }
 
+/// A `Makiri::InternalError` carrying `msg`: a broken invariant of Makiri
+/// itself, which a bare `rescue` (StandardError) passes through - see
+/// [`entry`].
+pub fn internal_error(msg: impl Into<std::borrow::Cow<'static, str>>) -> Error {
+    Error::new(crate::init::EXC_INTERNAL_ERROR.exception(), msg)
+}
+
 /// Is `v` an instance of the class in `klass`? `false` before `Init_makiri`,
 /// when no class of ours exists for it to be an instance of.
 #[inline]
@@ -280,8 +287,7 @@ pub fn bool_value(v: VALUE) -> Option<bool> {
 pub fn entry<T>(f: impl FnOnce() -> Result<T, Error>) -> Result<T, Error> {
     match std::panic::catch_unwind(core::panic::AssertUnwindSafe(f)) {
         Ok(out) => out,
-        Err(payload) => Err(Error::new(
-            crate::init::EXC_INTERNAL_ERROR.exception(),
+        Err(payload) => Err(internal_error(
             crate::caught::message(payload.as_ref()).to_owned(),
         )),
     }

data/ext/makiri/rust/src/bridge/string.rs

@@ -541,22 +541,46 @@ pub struct Encoding(*mut rb_sys::rb_encoding);
 
 impl Encoding {
     /// The encoding `str` is tagged with.
-    fn of(str: RString) -> Encoding {
+    pub(super) fn of(str: RString) -> Encoding {
         // SAFETY: a live String, by type; reading its tag runs no Ruby.
         Encoding(unsafe { rb_sys::rb_enc_get(str.as_raw()) })
     }
 
-    fn utf8() -> Encoding {
+    pub(super) fn utf8() -> Encoding {
         // SAFETY: Ruby's immutable global encoding.
         Encoding(unsafe { rb_sys::rb_utf8_encoding() })
     }
 
-    fn is_usascii(self) -> bool {
+    /// The encoding Ruby knows by `name`, or None for a name it does not
+    /// know - not an error. MAY AUTOLOAD the encoding, a Ruby allocation and so
+    /// a GC point: call it with no borrow of a String's bytes held.
+    ///
+    /// `rb_enc_find` wants a C string and the name is bytes, so the NUL is
+    /// added here. A name too long to fit, or holding a NUL, is not one Ruby
+    /// knows, so it reads as None rather than being truncated at the NUL.
+    pub(super) fn find(name: &[u8]) -> Option<Encoding> {
+        let mut buf = [0u8; 64];
+        if name.is_empty() || name.len() >= buf.len() || name.contains(&0) {
+            return None;
+        }
+        buf[..name.len()].copy_from_slice(name);
+        let c = core::ffi::CStr::from_bytes_with_nul(&buf[..name.len() + 1]).ok()?;
+        // SAFETY: a NUL-terminated name; the lookup raises nothing.
+        let enc = unsafe { rb_sys::rb_enc_find(c.as_ptr()) };
+        (!enc.is_null()).then_some(Encoding(enc))
+    }
+
+    /// The raw encoding, for a C call in the bridge that takes one.
+    pub(super) fn as_raw(self) -> *mut rb_sys::rb_encoding {
+        self.0
+    }
+
+    pub(super) fn is_usascii(self) -> bool {
         // SAFETY: Ruby's immutable global encoding.
         self.0 == unsafe { rb_sys::rb_usascii_encoding() }
     }
 
-    fn is_ascii8bit(self) -> bool {
+    pub(super) fn is_ascii8bit(self) -> bool {
         // SAFETY: Ruby's immutable global encoding.
         self.0 == unsafe { rb_sys::rb_ascii8bit_encoding() }
     }
@@ -573,10 +597,12 @@ impl Encoding {
         !self.is_utf8_compatible()
     }
 
-    /// Whether HTML input in this encoding is parsed as it is: UTF-8, US-ASCII,
-    /// or ASCII-8BIT - deliberately raw bytes, which the parser decodes
-    /// leniently. Anything else is transcoded to UTF-8 first.
-    fn parses_as_is(self) -> bool {
+    /// Whether input in this encoding is read as UTF-8 bytes with no
+    /// transcode: UTF-8, US-ASCII, or ASCII-8BIT - deliberately raw bytes.
+    /// Anything else is transcoded to UTF-8 first. How the bytes are then
+    /// checked is each reader's own: HTML repairs invalid UTF-8 to U+FFFD
+    /// (`ruby_to_utf8`), XML refuses it (`xml_decode`).
+    pub(super) fn reads_as_utf8_bytes(self) -> bool {
         self.is_utf8_compatible() || self.is_ascii8bit()
     }
 
@@ -631,7 +657,7 @@ pub fn to_encoding(v: Value) -> Result<Encoding, Error> {
 /// [`ruby_to_utf8_value`]. Called bare, that raise would `longjmp` over the
 /// Rust frames above it.
 unsafe fn ruby_to_utf8(str: RString) -> VALUE {
-    if Encoding::of(str).parses_as_is() {
+    if Encoding::of(str).reads_as_utf8_bytes() {
         return str.as_raw();
     }
     const REPLACE: c_int = rb_sys::ruby_econv_flag_type::RUBY_ECONV_INVALID_REPLACE as c_int
@@ -652,7 +678,7 @@ pub fn ruby_to_utf8_value(s: RString) -> Result<RString, Error> {
     let raw = protect(|| unsafe { ruby_to_utf8(s) })?;
     // SAFETY: `rb_str_encode` returns a live value; checked to be a String.
     RString::from_value(unsafe { crate::bridge::ruby::value(raw) })
-        .ok_or_else(|| makiri_error("transcoding returned a non-String"))
+        .ok_or_else(|| crate::bridge::ruby::internal_error("transcoding returned a non-String"))
 }
 
 /// A Ruby String as HTML parser input, under the text-input contract: its