makiri 0.10.0.rc1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 222e16ff55d6b0a91b495ec3f0a3919b3de5633afa5ec7a5363475f6c097a111
-  data.tar.gz: 35d5eacf1d006ef49d9fb1b31c3728e7693c6db175d041f78987084196a74a62
+  metadata.gz: b6163794fb07f39d4476e91a5d9db367d82b02888e167bc41435bb12de32de49
+  data.tar.gz: 4c075f42cbdf69b39b9783e3ad66bd09acb48f380447e8e80a47402dcdd427e5
 SHA512:
-  metadata.gz: 7f3fb141cb5ec35926f15f63f90cb5076f7d3faebc548ccd850014b526ddb2c8efab00f87424918fef73ecaf0f8edbf78646e4c00ce8d0b47882d38658be9748
-  data.tar.gz: 849a3a1a2f0d8da33b7da177f40c57bff74fdcc1039d800b0c132645d70c011d7f41cc601dd2add2380049f250549462d19a097baf8fd2fd68ff33fee8c8a961
+  metadata.gz: d6f1d154116c49d5b42e57e08d584781af42c2d0a02a6d3a1d6073659437cd7b0920a30a42451fedc70b173de242c9738a34ea4fd8d582dd3d199094bbfe10ab
+  data.tar.gz: 7278778cf2e98166e03ef79364ef9a4b0feec3b410949c2e4889f82f899594da8ba492ac00a6d75de2ee7a553430e5dc69a9af52a41292ab86249af830dea7fe

data/CHANGELOG.md

@@ -1,34 +1,142 @@
 # Changelog
 
+## [0.10.0] - 2026-09-22
+
+### Fixed
+
+* A frozen node now raises `FrozenError` when it is the ARGUMENT of a tree
+  mutation, not only the receiver: `b.add_child(a)` relinks `a` exactly as
+  `a.remove` does. Both `Makiri::XML` and `Makiri::HTML`. A fragment argument
+  splices its children, which have no wrapper of their own to check.
+* A `Makiri::XML` mutation that exceeds the document's own `max_bytes` /
+  `max_nodes` now raises `Makiri::XML::LimitExceeded` instead of reporting the
+  refusal as out of memory.
+* Inserting a `DocumentFragment` is all or nothing on `add_child`, `before` and
+  `after`, as it already was on `replace`: a child the rules refuse no longer
+  leaves the earlier ones linked in a document the caller was told had not
+  changed.
+* A rejected `Makiri::XML::Document#fragment` no longer charges the document for
+  the nodes it discarded. 100k rejected fragments grew a `<r/>` document to
+  77 MB; it is now 516 bytes.
+* A failed `Makiri::XML` parse reports the FIRST failure for all four kinds
+  (`syntax` was sticky while `limit` and `unsupported` overwrote each other).
+* `Makiri::XML#to_xml`'s serializer allocates fallibly again, so running out of
+  memory raises instead of aborting the process.
+* `:lexbor-contains()` now rejects an argument the bundled CSS parser does not
+  take, the way any unknown pseudo-class is rejected: `Makiri::CSS::SyntaxError`
+  from `#css` / `#at_css` / `#matches?`, and a `:bad_style` rule from
+  `Makiri::Lexbor::CSS.parse_stylesheet`. Well-formed uses are unchanged.
+
+### Performance
+
+* `Makiri::XML#to_xml` plans namespaces from a binding stack instead of
+  re-walking each ancestor's attribute list, which cost O(depth^2 x attributes).
+  403 KB of nested prefixed attributes took 4.88s and now takes 0.001s. A
+  crafted document fails closed with `Makiri::Error` ("namespace planning
+  exceeded its step budget") rather than running on.
+* Setting an attribute on a `Makiri::XML` element walks the attribute list once
+  instead of twice (4096 attributes: 47ms -> 27ms).
+
+## [0.10.0.rc2] - 2026-09-20
+
+### Added
+
+* `XPathContext.new` now registers namespace bindings passed via
+  `prefix: uri` (previously ignored).
+* `#css`, `#at_css`, and `#matches?` accept `(selector, namespaces = nil)`
+  on HTML documents for consistency with XML.
+* Standardized error message format for rejected CSS selectors across XML
+  and HTML: `"<reason>: <selector>"`.
+* Unified argument handling for `#xpath` and `#at_xpath` between HTML and XML.
+  * HTML supports per-query namespace bindings and keyword prefixes
+    (e.g., `s: uri`).
+  * XML supports custom-function handlers.
+* XML nodes now support HTML-style node readers and aliases
+  (`#first_element_child`, `#next_element`, `#tag_name`, `#attr`,
+  `#node_name`, etc.).
+
+### Changed
+
+* Updated vendored Lexbor to `v3.0.0-66`.
+* Parsed `<?php ... ?>` tags in HTML input as `ProcessingInstruction` nodes
+  instead of comments, adhering to the HTML Standard.
+* Vendored Lexbor updated from `v3.0.0-25` to `v3.0.0-66` (`05b5d37`), for an
+  out-of-bounds write in `lxb_dom_character_data_replace` reachable through
+  `#content=`, UTF-16 surrogate rejection, exact `meta` charset matching and
+  buffer-capacity fixes. (v3.0.1 is not usable: it lacks the two CSS-selector
+  fixes Makiri upstreamed.)
+* `<?php ... ?>` in HTML input is now a `ProcessingInstruction` node rather
+  than a Comment, serializes as `<?target data?>`, and `<?` at end of input is
+  ignored - the HTML Standard's processing-instruction tokens, which Lexbor now
+  implements. `Nokogiri::HTML5` still answers with a comment.
+* `Makiri::XML#matches?` tests the node locally via tree walking instead of
+  performing a full-document search.
+* `Makiri::XML::Namespace` is now an immutable `Data` object defined in Ruby.
+* `XML::Node#value` returns its text content (or attribute value for
+  attributes), aligning with HTML node behavior.
+* XPath over HTML now handles element/attribute names case-insensitively
+  and properly handles `xmlns` attributes according to browser specs.
+* `Makiri::XML` checks the internal DTD subset for well-formedness and
+  raises `Makiri::XML::SyntaxError` if unsupported constructs (e.g., attribute
+  defaults, entity references) would alter the document tree.
+* Documents with `version="1.x"` are now accepted and parsed as XML 1.0.
+* Processing instruction (PI) targets containing colons (e.g., `<?a:b?>`)
+  are now rejected per Namespaces in XML specs.
+
+### Fixed
+
+* `Makiri::XML::DocumentType#prefix` now returns `nil` instead of
+  the PUBLIC ID.
+* `Makiri::XML#last_element_child` now correctly returns an `Element`
+  instead of arbitrary child nodes (like comments or text).
+* `Element#local_name` and `local-name()` in XPath preserve camelCase
+  for SVG/MathML elements (e.g., `foreignObject`).
+* `inner_html=` and `outer_html=` are now atomic operations to prevent
+  leaving the DOM in a corrupted state on failure.
+* XPath over HTML assigns empty/correct namespaces to attributes instead of
+  inheriting from their parent element.
+* Corrected `lang()` evaluation to check the nearest language attribute
+  hierarchically.
+* Fixed `namespace_matching: :lax` on XML to be strict, aligning with
+  `Nokogiri::XML` / `libxml2` behavior.
+* Moving an HTML node to another document now correctly removes it
+  from the source document's indexes.
+* Prevented XPath custom handlers from creating new nodes on the document
+  being evaluated.
+* Fixed CSS universal selectors (`p|*`, `|*`) on XML to respect namespace
+  boundaries.
+* CSS column combinator (`a || b`) on XML now raises
+  `Makiri::CSS::SyntaxError` instead of being misparsed as descendant selector.
+
 ## [0.10.0.rc1] - 2026-09-19
 
 ### Changed
 
-* **The native extension is rewritten in Rust.** The C glue, the XPath engine,
+* The native extension is rewritten in Rust. The C glue, the XPath engine,
   the XML reader and the CSS lowering are now one Rust crate; the only C left is
   the vendored Lexbor, still unpatched. The Ruby API is unchanged, and answers
   were checked against the C build's recorded output as well as the existing
   differential suites against Nokogiri.
 
-  * **Installing from source needs a Rust toolchain.** `cargo` (stable) and
+  * Installing from source needs a Rust toolchain. `cargo` (stable) and
     libclang are required alongside CMake, and `rb_sys` becomes a runtime
     dependency of the source gem, because its `extconf.rb` runs at install time.
     The precompiled platform gems need none of this and do not depend on
     `rb_sys`.
-  * **Faster.** Makiri now beats both Nokogiri and nokolexbor on every
+  * Faster. Makiri now beats both Nokogiri and nokolexbor on every
     `rake bench` row, parse included - previously ~1.25x slower than nokolexbor.
     Source locations are stamped on the first `#line` or mutation rather than
     during every parse, and the vendored Lexbor is built with link-time
     optimization where the linker supports it (macOS; Linux with clang,
     llvm-ar and lld; not Windows).
-  * **An internal failure is an exception, not a crash.** It used to end the
+  * An internal failure is an exception, not a crash. It used to end the
     host process with SIGABRT. Now it unwinds on the thread that ran the call:
     `ensure` blocks run and the process keeps working. On entry points that
     handle input (parse, XPath, CSS, serialization, text) it is the new
-    **`Makiri::InternalError`**, which descends from `Exception`, not
+    `Makiri::InternalError`, which descends from `Exception`, not
     `StandardError`, so a bare `rescue => e` does not swallow it; elsewhere it
     is Ruby's `fatal`.
-  * **An XPath handler may not modify the document being evaluated.** Every
+  * An XPath handler may not modify the document being evaluated. Every
     mutator on that document raises `Makiri::Error` while an evaluation with a
     handler runs, because the evaluator holds names and values from it for the
     whole walk.
@@ -46,14 +154,14 @@
 
 * `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.
+  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
+* `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:
@@ -71,24 +179,24 @@
   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` /
+* 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 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.**
+* 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 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.
@@ -294,7 +402,7 @@
 
 ### Added
 
-* **Native XML 1.0 reader + in-place editor** - `Makiri::XML::Document.parse(source)`
+* Native XML 1.0 reader + in-place editor - `Makiri::XML::Document.parse(source)`
   / `Makiri::XML(source)`. No libxml2: a strict, fail-closed parser builds its own
   node arena (case- and namespace-preserving), queried by the native XPath engine.
   * Strict & secure: fail-closed decode (bad UTF-8 / NUL -> `XML::SyntaxError`),
@@ -304,9 +412,9 @@
     encoding is a fatal error, not a silent mis-decode.
   * DoS-bounded by a single arena byte ceiling (default 256 MiB; raise per parse
     with `max_bytes:`).
-  * `<!DOCTYPE>` recognized but **not processed** (`#internal_subset` ->
-    `XML::DocumentType`); zero entity/DTD I/O, so **XXE and billion-laughs are
-    structurally impossible**. Kept off the tree, as in libxml2.
+  * `<!DOCTYPE>` recognized but not processed (`#internal_subset` ->
+    `XML::DocumentType`); zero entity/DTD I/O, so XXE and billion-laughs are
+    structurally impossible. Kept off the tree, as in libxml2.
   * Read API mirrors Nokogiri: `#xpath` / `#at_xpath` (`{prefix => uri}`),
     name/namespace readers, `#text`, `#[]`, traversal, and namespace introspection
     (`Makiri::XML::Namespace`); `XPathContext` works over XML nodes too.
@@ -334,7 +442,7 @@
 * `NodeSet#[]` accepts a `Range` or `start, length` (like `Array#[]`).
 * `Node` / `NodeSet` / `Document` `#dup` / `#clone` now return real independent
   copies (`#dup(0)` shallow; `#clone(freeze:)` honoured).
-* A **frozen node is genuinely immutable** - every mutator raises `FrozenError`.
+* A frozen node is genuinely immutable - every mutator raises `FrozenError`.
 
 ### Changed
 
@@ -346,7 +454,7 @@
   added `Node#cdata?`.
 * Text-index range table uses `uint32` bounds (24 -> 16 B/entry; ~27% less retained
   index, byte-identical text).
-* Parsing **honours the input String's encoding** - Shift_JIS / EUC-JP / ... are now
+* Parsing honours the input String's encoding - Shift_JIS / EUC-JP / ... are now
   transcoded to UTF-8 instead of mangled.
 * Parsing skips its UTF-8 validation scan when the String's coderange already proves
   it valid.
@@ -355,7 +463,7 @@
 
 ### Fixed
 
-* **Hardened the HTML/XML representation boundary.** HTML (Lexbor) and XML (arena)
+* Hardened the HTML/XML representation boundary. HTML (Lexbor) and XML (arena)
   nodes are now distinct TypedData types, so the wrong representation raises
   `TypeError` instead of corrupting memory:
   * `Node#==` / `XPathContext#node=` with an XML `Document` no longer aborts the
@@ -434,12 +542,12 @@
 ## [0.1.0] - 2026-06-02
 
 First public release. An HTML5 parser, a native XPath 1.0 query engine, and CSS
-selectors for Ruby - built on vendored [Lexbor](https://lexbor.com/) with **no
-libxml2 / libxslt dependency at any layer**.
+selectors for Ruby - built on vendored [Lexbor](https://lexbor.com/) with no
+libxml2 / libxslt dependency at any layer.
 
 ### Added
 
-**Parsing & DOM**
+Parsing & DOM
 
 * `Makiri::HTML` / `Makiri.parse` - HTML5 parsing via vendored, unpatched Lexbor,
   with browser-compatible UTF-8 decoding (invalid bytes → U+FFFD; parsing never
@@ -454,7 +562,7 @@ libxml2 / libxslt dependency at any layer**.
   quirks_mode,internal_subset,errors}` and `Makiri::DocumentType#{public_id,
   system_id,external_id}`.
 
-**XPath**
+XPath
 
 * Native XPath 1.0 query engine (no libxml2/libxslt): `Node#{xpath,at_xpath}`
   and `Makiri::XPathContext` (`evaluate`, namespace/variable binding, custom
@@ -462,7 +570,7 @@ libxml2 / libxslt dependency at any layer**.
   built-in functions with spec-faithful semantics (XML NCNames including
   non-ASCII, node-set vs node-set comparisons per §3.4, document order per §5.1,
   Unicode-aware `translate`/`substring`).
-* Namespace matching is **strict by default** (HTML5/WHATWG-faithful, like
+* Namespace matching is strict by default (HTML5/WHATWG-faithful, like
   browsers' `document.evaluate` and `Nokogiri::HTML5`); pass
   `namespace_matching: :lax` for the namespace-agnostic, `Nokogiri::HTML`-style
   match.
@@ -470,12 +578,12 @@ libxml2 / libxslt dependency at any layer**.
   (operation / recursion-depth / node-set / string-byte caps) that raise
   `Makiri::XPath::LimitExceeded` on overrun.
 
-**CSS**
+CSS
 
 * `Node#{css,at_css,matches?}` via Lexbor's selector engine (descendant-only,
   document order). Malformed selectors raise `Makiri::CSS::SyntaxError`.
 
-**Mutation & serialization**
+Mutation & serialization
 
 * DOM mutation: `add_child`/`<<`, `add_previous_sibling`/`before`,
   `add_next_sibling`/`after`, `remove`/`unlink`, `replace`; attribute `[]=` and
@@ -494,7 +602,7 @@ libxml2 / libxslt dependency at any layer**.
   `NodeSet#{|,+,&,-,css,xpath,search,at,last,remove}`, and `Element.new` /
   `Text.new`.
 
-**Safety & concurrency**
+Safety & concurrency
 
 * UTF-8 text-input contract: HTML and fragment parsing are lenient (invalid
   bytes → U+FFFD, never reject), while strings passed to the XPath / CSS /
@@ -505,7 +613,7 @@ libxml2 / libxslt dependency at any layer**.
   context across threads cannot corrupt memory. Fail-closed string caps and
   iterative (non-recursive) tree walks resist stack-exhaustion DoS.
 
-**Performance** (`rake bench`, vs Nokogiri/libxml2)
+Performance (`rake bench`, vs Nokogiri/libxml2)
 
 * Meets or beats Nokogiri on every benchmarked operation: parse ~3×, css ~12×,
   at_css ~1000×, serialize ~4×, `//tag` ~3.4×, `[@attr='v']` predicate ~1.5×,
@@ -513,7 +621,7 @@ libxml2 / libxslt dependency at any layer**.
   a document element index (for `//tag`), a direct-attribute predicate fast
   path, and a hashed per-evaluate string-value cache.
 
-**Tooling**
+Tooling
 
 * Vendored Lexbor as a git submodule (pinned v3.0.0, applied without patches).
   Build hardening flags; AddressSanitizer+UBSan build (`rake sanitize`);

data/NOKOGIRI_DIFFERENCES.md

@@ -0,0 +1,177 @@
+# Differences from Nokogiri
+
+Makiri targets a Nokogiri-compatible API, but a few behaviours differ. Where
+they do, Makiri usually follows the web platform - the WHATWG standards and
+what browsers do - rather than libxml2. Detailed, test-backed notes live in
+`spec/conformance/README.md`.
+
+## XPath
+
+* The `namespace::` axis is not implemented
+  * It raises `Makiri::Error` rather than returning a silently-empty result.
+  * Nokogiri (libxml2) supports it (for `<svg>` in HTML it yields the `xml` and `svg` namespace nodes).
+    For an element's namespace use `namespace-uri()` / `local-name()`, which are implemented.
+* Unprefixed name tests are namespace-strict by default (HTML5/WHATWG-faithful, like browsers' `document.evaluate` and `Nokogiri::HTML5`)
+  * `//div` matches, but foreign elements need a registered prefix (`//svg:path`).
+    Pass `namespace_matching: :lax` to `Node#xpath` / `XPathContext.new` for the
+    namespace-agnostic match where `//path` finds an SVG element (the
+    `Nokogiri::HTML`/libxml2-HTML4 behaviour). Lax means "as Nokogiri does", so
+    on an XML document it changes nothing: `Nokogiri::XML` is namespace-strict too.
+* `namespace-uri()` of an HTML element returns the XHTML URI (DOM-correct, as browsers report)
+  * `Nokogiri::HTML5` returns `""`.
+* Name tests fold ASCII case on HTML elements, like browsers (WPT `domxpath`).
+  The HTML Standard's XPath section does not ask for this - it only sets the
+  default element namespace - so here Makiri follows the browsers over the text.
+  * `//DiV` matches `<div>` and `//div[@Id]` its `id`; SVG / MathML names compare
+    exactly (`//*[@refX]`, not `@refx`). Only ASCII folds: `Ø` still differs from `ø`.
+    This holds in `namespace_matching: :lax` too.
+  * `Nokogiri::HTML5` is case-sensitive there.
+* A foreign element's namespace declarations are not attributes
+  * `<svg xmlns="...">` has no `@xmlns` for `//*[@xmlns]` or `@*`, as in browsers
+    and in XPath's data model. An `xmlns` on an HTML element is an ordinary
+    attribute and stays visible.
+
+## XML
+
+* `Makiri::XML` is XML 1.0 (Fifth Edition) only and non-validating.
+  * A `version="1.x"` document is read as XML 1.0, as §2.8 says a 1.0 processor
+    does; a construct only XML 1.1 allows still fails.
+  * The internal DTD subset is checked but never applied. §5.1 requires even
+    a non-validating parser to apply its attribute defaults and entities, so a
+    document whose DTD would change the tree is refused
+    (`Makiri::XML::SyntaxError`, "unsupported DTD construct") rather than parsed
+    without them: an attribute default (`"d"` or `#FIXED "d"`), a non-CDATA
+    attribute type (`ID`, `NMTOKEN`, an enumeration, ... - they normalize the
+    value), a parameter-entity reference, or a reference to an entity the DTD
+    declares. Declarations that change nothing (`<!ELEMENT>`, `CDATA #IMPLIED` /
+    `#REQUIRED`, unused entity declarations, notations) are accepted.
+    Nokogiri/libxml2 by default parses such documents and leaves the defaults and
+    entities out (its `DTDATTR` / `NOENT` options apply them).
+  * External entities and the external subset are never fetched (no I/O), as
+    §5.1 allows a non-validating parser.
+  * Mutation supports in-place edits, the node factories, fragments
+    (`Document#fragment` / `DocumentFragment.parse`), node insertion, and building
+    a document from scratch (`XML::Document.new` + `#root=`); only handing a raw
+    markup string straight to `#add_child` is unsupported (parse it into a fragment
+    first). (`#to_xml` serialization is supported; HTML serialization - `to_html`
+    / `inner_html` / `outer_html` - is not.)
+* A processing-instruction target with a colon can be created but not written.
+  * The parser rejects `<?a:b ...?>`, as Nokogiri does: Namespaces in XML §7
+    requires every Name other than element and attribute names to be an NCName.
+  * `create_processing_instruction("a:b", ...)` succeeds, as DOM
+    `createProcessingInstruction` does, but `#to_xml` / `#canonicalize` then raise,
+    as DOM Parsing's well-formed serializer does. Nokogiri writes `<?a:b ...?>`.
+* `#freeze` on a node is ENFORCED: a frozen node's mutators raise `FrozenError`,
+  and so does passing a frozen node as the argument of an insertion, which
+  relinks it. Nokogiri reports `frozen?` but every mutator still mutates. The
+  check reaches the nodes the caller named; a fragment argument splices its
+  children, and those cannot be checked, because frozen-ness is a property of a
+  Ruby object and the arena keeps no map from a node back to its wrapper.
+
+* 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.
+
+## HTML parsing
+
+* `<?php ... ?>` in HTML input is a **ProcessingInstruction** node; `#to_html`
+  writes it back as `<?php ... ?>`, and `<?` at end of input is ignored.
+  * The HTML Standard added processing-instruction tokens and tree-construction
+    rules for them; Makiri follows them through Lexbor. `Nokogiri::HTML5` (gumbo)
+    still produces the older bogus comment (`<!--?php ... ?-->`), and
+    `Nokogiri::HTML` (libxml2) its own comment.
+
+## CSS
+
+* Most jQuery/Nokogiri CSS extensions are not supported (`:gt`, `:lt`, `:eq`, `:first`, ...)
+  * Makiri uses Lexbor's selector engine, which is standards-based apart from one
+    text-containment extension. Use XPath (`xpath("//p[contains(., 'x')]")`) or
+    Enumerable (`css('li')[1]`) for the rest.
+    Standard Level-4 selectors (`:is` / `:where` / `:has`) are supported; some of which Nokogiri rejects.
+  * `:lexbor-contains("text")` is supported (on both HTML and XML) - Lexbor's
+    spelling of the jQuery `:contains()` substring filter, matching an element
+    whose text contains the string; append ` i` (`:lexbor-contains("text" i)`)
+    for an ASCII case-insensitive match. (Nokogiri's name `:contains` is not an
+    alias.) Like Lexbor's matcher, it tests the element's immediate child text
+    nodes (not the deep string-value), so HTML and XML agree; on XML it lowers
+    to XPath `child::text()[contains(., "text")]`.
+* Untyped `:*-of-type` (`:first-of-type`, `:nth-of-type(an+b)`, ... with no type
+  selector) is supported and correct on both HTML and XML - the "type" is the
+  element's own expanded name.
+  * Nokogiri (XML and HTML5) mistranslates these to first-/only-child
+    (`//*[position()=1]` / `//*[last()=1]`), so it under-matches; Makiri matches
+    Lexbor's HTML matcher.
+* HTML CSS takes a `{prefix => uri}` Hash (`css(selector, ns)`) but does not
+  resolve prefixes against it: Lexbor's matcher matches a prefixed type selector
+  loosely, so `svg|path`, `|path` and `path` all find the SVG element whatever
+  is bound. `Nokogiri::HTML5` honours the binding (a wrong URI finds nothing).
+  * The Hash is accepted and unused rather than refused, so the `css(selector,
+    ns)` a caller writes for both representations works. Use `#xpath`, where a
+    prefix IS resolved against the bindings, when the namespace matters.
+  * `Makiri::XML` resolves CSS prefixes properly - it lowers the selector to the
+    XPath engine, which registers the bindings.
+* `#matches?` answers for a DETACHED node (`document.create_element("p")
+  .matches?("p")` is true, on both representations). Nokogiri raises
+  `NoMethodError` there - it implements `#matches?` as a search from
+  `ancestors.last`, which a detached node does not have.
+* * 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
+  `Makiri::Error`, never silently repaired - unlike HTML *parsing*, which decodes
+  leniently to U+FFFD).
+* An embedded NUL (U+0000) is accepted in HTML data-family content -
+  text/comment node content (`create_text_node`, `create_comment`, `content=`)
+  and attribute values (`[]=`, `set_attribute_ns`) - and stored/read back
+  verbatim, matching the WHATWG DOM / browsers (`document.createTextNode("\0")`).
+  It is still rejected in names, tag names, namespaces, PI target/data, CSS
+  selectors, and XPath expressions/variable names (a NUL there raises).
+  * On re-parse, the HTML tokenizer replaces a U+0000 in text/attributes with
+    U+FFFD (WHATWG), so a serialized-then-reparsed round-trip is not byte-identical.
+  * `Makiri::XML` rejects NUL everywhere: XML 1.0 has no legal U+0000 character,
+    so admitting it would produce non-well-formed XML.