makiri 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f88832bca79aadf7ea686b37739a5b600d9ff4a2075f28e9d59a885a66afab80
-  data.tar.gz: 6f835ef9f2bee6318e9ef5ff179dac48b7e99b2f019fb85f86c67eb94fced1e9
+  metadata.gz: b0cf63c9d861e721a52064dccc929db0a8f823d485f69854f07d90b805913db0
+  data.tar.gz: 989e0d0b1430b202147cd4f0fec411d0377114f34ae380217b683b6b63d031e6
 SHA512:
-  metadata.gz: 4171815b57b086979c4638b44cd9316562e7293b16c40302a62e78b7a93c30f0a1e0dd4f09764574fe20c5b6e948699dee64dad6d45136e582da22b4ac5fc74d
-  data.tar.gz: ee5dda37c9dc8722d7313b96981312b0d1b1599dde764eeb108ba8397655586cfd793d6ce1a3f9473ae0cfc0e542d6e50f87c93dc355d9237432de00d088bb29
+  metadata.gz: 13598e1f45341c8fed3924da8bbe913cf55ef5c1b9256193db18ae3cf2bb9ae0f4816370d8ca569139b33e7194aced65656c1314989b882ea612a44e3750e84b
+  data.tar.gz: 71c9da99e6f26fb8a034efba1d0642b37cdcd3ddf212c6f977ad3c868b104162ca86f0c721606024286a06c858326508e41c8624687c03fa3d7a205461926faf

data/.github/workflows/release.yml

@@ -196,17 +196,22 @@ jobs:
             $pre --verify-tag || \
           gh release upload "${GITHUB_REF_NAME}" dist/*.gem --repo "${GITHUB_REPOSITORY}" --clobber
 
-  # --- optional: publish to RubyGems (manual, opt-in, never on a tag push) ----
-  # Auth is RubyGems Trusted Publishing (OIDC): no stored API key, short-lived
-  # token, MFA-compatible. Configure a matching Trusted Publisher on RubyGems.org
-  # for this gem: owner=takahashim, repo=makiri, workflow=release.yml, and set its
-  # Environment to "rubygems" (matching `environment:` below).
+  # --- publish to RubyGems, behind the `rubygems` environment approval gate ---
+  # Held until the `rubygems` environment's Required-reviewers rule is approved,
+  # so a tag push releases on GitHub immediately but the RubyGems push waits.
+  #
+  # Auth is RubyGems Trusted Publishing (OIDC): no stored API key. Configure a
+  # matching Trusted Publisher on RubyGems.org (owner=takahashim, repo=makiri,
+  # workflow=release.yml, Environment=rubygems) so the token is only accepted
+  # through this gated environment.
   publish:
     name: Publish to RubyGems
     needs: [source-gem, native-gem]
-    if: github.event_name == 'workflow_dispatch' && inputs.publish_to_rubygems
+    if: >-
+      startsWith(github.ref, 'refs/tags/') ||
+      (github.event_name == 'workflow_dispatch' && inputs.publish_to_rubygems)
     runs-on: ubuntu-latest
-    environment: rubygems   # add a Required-reviewers protection rule for an approval gate
+    environment: rubygems
     permissions:
       contents: read
       id-token: write       # OIDC identity token for Trusted Publishing

data/CHANGELOG.md

@@ -7,28 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-06
+
+### Added
+
+* **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`),
+    duplicate attributes rejected, XML 1.0 only; verified against the W3C XML
+    Conformance Test Suite.
+  * Encoding autodetected (BOM / `<?xml encoding?>`); a contradicting String
+    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.
+  * 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.
+  * Prolog/epilog comments & PIs kept on the document node; adjacent same-type
+    character data coalesced - byte-identical to Nokogiri (property-based diff).
+  * `#to_xml` / `#to_s` (`pretty:` / `indent:` / `encoding:`) and `#canonicalize`
+    (Inclusive C14N 1.0, byte-identical to libxml2); buffers fail closed.
+  * Unsupported surface raises `NotImplementedError`: `#css` / `#at_css` and HTML
+    serialization.
+  * Tree mutation - fully fail-closed, detach-never-destroy:
+    * in-place: `#[]=` / `#delete`, `#content=`, `#name=`, `#remove` / `#unlink`;
+    * factories: `Document#create_{element,text_node,comment,cdata,processing_instruction}`
+      (+ Nokogiri-style `.new` constructors);
+    * insertion: `#add_child` / `<<`, `#before` / `#after`, `#replace` - namespaces
+      resolved at the insertion point; a cross-document insert deep-copies;
+    * fragments: `XML::DocumentFragment.parse` / `XML::Document#fragment`;
+    * from scratch: `XML::Document.new` + `#root=`.
+* `XML::Element#element_children` and `Node#clone_node` for XML nodes (also enabling
+  `Node#dup` / `#clone`); a clone keeps name case, namespace and the CDATA type.
+* `Node` includes `Enumerable` over its child nodes (`each` / `map` / `select` / ...).
+* `Node#<=>` + `Comparable` - sort by document position (`nil` across documents or
+  for attributes).
+* `NodeSet.new(document_or_node, list = [])` - foreign / cross-representation nodes
+  are rejected.
+* `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`.
+
+### Changed
+
+* CSS queries reuse one shared Lexbor engine (GVL-safe) and `at_css` wraps the match
+  directly: `at_css('#id')` ~5x faster than nokolexbor (was ~1.16x slower).
+* HTML serialization pre-reserves its buffer - `to_html` now at parity with nokolexbor.
+* Node-class names are the WHATWG DOM interface names (`CDATASection`, `Attr`,
+  `DocumentType`, ...), with the Nokogiri spellings (`CDATA`, `DTD`) kept as aliases;
+  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
+  transcoded to UTF-8 instead of mangled.
+* Parsing skips its UTF-8 validation scan when the String's coderange already proves
+  it valid.
+* Faster HTML parse/serialize: `memchr` line table + validate-only UTF-8 scan (~7%),
+  and a single-copy serializer buffer (~1.2-1.3x).
+
+### Fixed
+
+* **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
+    process;
+  * `NodeSet#|` / `+` / `&` / `-` across different documents raise `Makiri::Error`
+    (was a silent mis-wrap);
+  * HTML-only APIs (`import_node`, `add_child` / `before` / `after` / `replace`,
+    `fragment(context:)`) reject an XML node argument (was a segfault).
+* The bundle exported the entire vendored Lexbor symbol table (~1700 `lxb_*`); now
+  only `Init_makiri` is exported, so loading alongside another Lexbor gem (e.g.
+  nokolexbor) no longer segfaults. (Precompiled gems: rebuild required.)
+
 ## [0.2.0] - 2026-06-04
 
 ### Added
 
-* `Element#tag_name` (DOM `tagName`) — the qualified name uppercased for an
+* `Element#tag_name` (DOM `tagName`) - the qualified name uppercased for an
   HTML element in an HTML document (`"DIV"`), keeping the original case for
   SVG/MathML; `nil` for non-elements. Complements `#name`, which stays the
   lowercase qualified name.
-* `ProcessingInstruction#target` (DOM `target`) — a PI's target name; `nil` for
+* `ProcessingInstruction#target` (DOM `target`) - a PI's target name; `nil` for
   other node kinds. Its data is read via `#content`/`#text`.
 * `Document#create_processing_instruction(target, data)` (DOM
   `createProcessingInstruction`) and `Document#create_document_fragment` (DOM
-  `createDocumentFragment`, an empty fragment to build up programmatically —
+  `createDocumentFragment`, an empty fragment to build up programmatically -
   unlike `#fragment` / `DocumentFragment.parse`, which parse HTML). Both produce
   a detached node owned by the document; PI creation fails closed when the data
   contains the `?>` terminator (matching the DOM constraint). (DOM
   `createCDATASection` is intentionally not provided: per WHATWG DOM it throws on
   an HTML document, which is the only kind Makiri produces.)
-* `Node#{namespace_uri, prefix, local_name}` — the WHATWG DOM per-node
+* `Node#{namespace_uri, prefix, local_name}` - the WHATWG DOM per-node
   namespace accessors on `Element` and `Attribute` (`nil` on other node kinds).
   `namespace_uri` resolves an element's namespace from its node (so an HTML
-  element is the XHTML namespace `http://www.w3.org/1999/xhtml`, not `nil` — the
+  element is the XHTML namespace `http://www.w3.org/1999/xhtml`, not `nil` - the
   DOM-faithful value browsers and `namespace-uri()` return; SVG/MathML get their
   own URI), and agrees byte-for-byte with the `namespace-uri()` XPath function.
   For attributes it is `nil` unless prefixed, where it returns the parser-assigned
@@ -36,21 +114,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   segment of the qualified name (`nil` for the usual unprefixed HTML5 case), and
   `local_name` is the name without that prefix. Previously a node's namespace was
   reachable only through XPath (`namespace-uri()`/`local-name()`).
-* `Node#clone_node(deep = false)` — a copy of the node, owned by the same
+* `Node#clone_node(deep = false)` - a copy of the node, owned by the same
   document and detached from any parent (the DOM `cloneNode`, whose `deep`
-  defaults to `false` — a missing/`nil`/`false` argument is a shallow clone; a
+  defaults to `false` - a missing/`nil`/`false` argument is a shallow clone; a
   truthy one copies the subtree). Built on the same `import_node` +
   `<template>`-content fixup the fragment parser uses, so a deep-cloned
   `<template>` keeps its contents. Fails closed: a failed import raises rather
   than returning a partial node.
-* `Document#import_node(node, deep = false)` — a copy of `node` owned by the
+* `Document#import_node(node, deep = false)` - a copy of `node` owned by the
   receiver document (the DOM `importNode`, whose `deep` likewise defaults to
   `false`). Unlike `Node#clone_node`, the copy is owned by the target rather
   than the node's own document, so it is the way to bring a node across
   documents (Makiri never moves a node between arenas); the source is left
   untouched. Same import + `<template>`-content fixup as `clone_node`, and fails
   closed on a failed import.
-* `Node#pointer_id` — the underlying `lxb_dom_node_t` pointer as an Integer,
+* `Node#pointer_id` - the underlying `lxb_dom_node_t` pointer as an Integer,
   matching `Nokogiri::XML::Node#pointer_id`. Shares the value `#hash`/`#eql?`
   are built on, so it is a stable, Nokogiri-compatible identity key for
   consumers (e.g. wrapper caches) that key nodes by pointer. Stable for a
@@ -73,19 +151,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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
+selectors for Ruby - built on vendored [Lexbor](https://lexbor.com/) with **no
 libxml2 / libxslt dependency at any layer**.
 
 ### Added
 
 **Parsing & DOM**
 
-* `Makiri::HTML` / `Makiri.parse` — HTML5 parsing via vendored, unpatched Lexbor,
+* `Makiri::HTML` / `Makiri.parse` - HTML5 parsing via vendored, unpatched Lexbor,
   with browser-compatible UTF-8 decoding (invalid bytes → U+FFFD; parsing never
   fails on bad bytes). Read-only navigation and attribute/text readers across
   `Document`, `Element`, `Attribute`, `Text`, `CData`, `Comment`,
   `ProcessingInstruction`, `DocumentType`, and `DocumentFragment`.
-* `Node#line` — 1-based source line of an element, reconstructed from the
+* `Node#line` - 1-based source line of an element, reconstructed from the
   tokenizer without patching Lexbor (nil when the location is unknown).
 * `Element#attribute_nodes` and `Attribute#{name,value,parent,element}`, backed
   by a lazily-built attribute→owner index in the Lexbor compat layer.
@@ -138,7 +216,7 @@ libxml2 / libxslt dependency at any layer**.
 * UTF-8 text-input contract: HTML and fragment parsing are lenient (invalid
   bytes → U+FFFD, never reject), while strings passed to the XPath / CSS /
   DOM-mutation APIs must be valid UTF-8 with no NUL byte, otherwise they raise
-  `Makiri::Error` — never silently truncated, repaired, or reinterpreted.
+  `Makiri::Error` - never silently truncated, repaired, or reinterpreted.
 * Thread-safe by construction: parsing releases the GVL (concurrent parse scales
   ~2× on 8 cores), while XPath evaluation holds the GVL so sharing a document or
   context across threads cannot corrupt memory. Fail-closed string caps and
@@ -161,6 +239,7 @@ libxml2 / libxslt dependency at any layer**.
   domxpath, CSS differential vs `Nokogiri::HTML5`). GitHub Actions CI across
   Ruby 3.2–4.0 × Ubuntu/macOS plus a sanitizer job.
 
-[Unreleased]: https://github.com/takahashim/makiri/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/takahashim/makiri/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/takahashim/makiri/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/takahashim/makiri/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/takahashim/makiri/releases/tag/v0.1.0

data/README.md

@@ -1,7 +1,8 @@
 # Makiri
 
-Standards-oriented HTML5 parsing, CSS selector querying, and XPath 1.0
-querying for Ruby, powered by Lexbor and a native XPath engine.
+Standards-oriented HTML5/XML parsing, CSS selector querying, XPath 1.0 querying,
+and a native XML 1.0 reader/editor for Ruby, powered by Lexbor and a native XPath
+engine - with no libxml2 dependency.
 
 > [!WARNING]
 > Status: early release. APIs and behavior may change before v1.0.
@@ -20,6 +21,12 @@ XPath 1.0 evaluation in its own native engine, with no libxml2 dependency.
 * Native XPath 1.0 engine
   * XPath is parsed and evaluated by Makiri's own engine, written from scratch.
   * Makiri does not depend on libxml2 for parsing, DOM representation, or XPath evaluation.
+* Native XML 1.0 reader + in-place editor (`Makiri::XML`)
+  * A strict, non-validating, fail-closed parser with its own node arena (not
+    Lexbor's HTML DOM), queried through the same native XPath engine, with
+    in-place tree edits (attributes, content, rename, remove).
+  * Conformance is held by the W3C XML Conformance Test Suite, an XPath
+    differential, and property-based testing vs Nokogiri (see below).
 * Bounded, fail-closed execution
   * XPath evaluation is bounded by per-evaluation limits on work, memory, and recursion.
   * Ownership and borrowing are kept explicit across layers, with owned/borrowed
@@ -46,7 +53,7 @@ HTML
 doc.css("a").map { |a| a["href"] }      # => ["/a", "/b"]
 doc.at_css("p.lead").text               # => "Hello"
 
-# XPath 1.0 (native engine — no libxml2)
+# XPath 1.0 (native engine - no libxml2)
 doc.xpath("//a").length                 # => 2
 doc.xpath("count(//a)")                 # => 2.0
 doc.at_xpath('//*[@id="main"]/p').text  # => "Hello"
@@ -72,16 +79,158 @@ ctx.register_variable("cls", "lead")
 ctx.evaluate('//p[@class=$cls]').first.text   # => "Hello"
 ```
 
+### XML (with in-place editing)
+
+`Makiri::XML(source)` parses **XML 1.0** with a native, strict,
+well-formedness-checking parser (no libxml2) and queries it through the same
+native XPath 1.0 engine. `source` is a String or any object responding to
+`#read` (an `IO` / `File` / `StringIO`); read a non-UTF-8 file in binary mode
+(`File.binread`) so its encoding is autodetected. Element-name case and namespaces are preserved. It is
+**fail-closed**: malformed input, a duplicate attribute, or a
+non-`1.0` version declaration raises `Makiri::XML::SyntaxError`, and operations
+XML does not support raise `NotImplementedError` rather than returning a wrong
+result. The tree supports in-place edits and building new subtrees (see below).
+A `<!DOCTYPE ...>` is recognized but its **DTD is not processed** (no
+entity/element declarations are loaded, no external subset is fetched) - so a
+DTD-defined entity reference stays an undefined-entity error and **XXE /
+billion-laughs are structurally impossible**. The doctype's name and identifiers
+are still readable:
+
+```ruby
+doc = Makiri::XML(<<~XML)
+  <feed xmlns="http://www.w3.org/2005/Atom">
+    <entry><title>Hello</title></entry>
+    <entry><title>World</title></entry>
+  </feed>
+XML
+
+# Namespace matching is strict, so a default namespace needs a registered prefix.
+ns = { "a" => "http://www.w3.org/2005/Atom" }
+doc.xpath("//entry").length                    # => 0  (default namespace)
+doc.xpath("//a:entry", ns).length              # => 2
+doc.at_xpath("//a:entry/a:title", ns).text     # => "Hello"
+
+# Or reuse a context (caches registrations + compiled expressions):
+ctx = Makiri::XPathContext.new(doc.root)
+ctx.register_namespace("a", "http://www.w3.org/2005/Atom")
+ctx.evaluate("//a:entry").length               # => 2
+
+el = doc.at_xpath("//a:entry", ns)
+el.local_name                                  # => "entry"
+el.namespace_uri                               # => "http://www.w3.org/2005/Atom"
+
+doc.css("entry")     # raises NotImplementedError (use #xpath)
+
+# Serialize back to XML
+doc.to_xml                                 # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<feed ...>...</feed>\n"
+doc.at_xpath("//a:entry", ns).to_xml       # => "<entry><title>Hello</title></entry>" (no declaration)
+doc.to_xml(pretty: true)                   # indented, element-only content
+
+# DOCTYPE is recognized but the DTD is not processed (no entities, no I/O):
+dtd = Makiri::XML(%(<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "x.dtd"><html/>))
+        .internal_subset
+dtd.name         # => "html"
+dtd.external_id  # => "-//W3C//DTD XHTML 1.0//EN"  (alias: #public_id)
+dtd.system_id    # => "x.dtd"
+```
+
+Comments and processing instructions in the prolog/epilog are document-node
+children (reachable via `//comment()` / `//processing-instruction()` and
+`#children`), and adjacent CDATA is coalesced - matching libxml2 and the XPath
+data model. `#to_xml` / `#to_s` serialize the tree back to XML (`pretty: true`,
+or `indent: n`, for indented element-only content; `encoding: "Shift_JIS"` to
+transcode, with a hex character reference for anything the encoding can't hold);
+a `Document#to_xml` adds the declaration and the DOCTYPE. `#canonicalize` emits
+Inclusive Canonical XML 1.0 (for XML signatures; `comments: true` to keep
+comments), byte-identical to libxml2. CSS is intentionally unavailable for XML
+(Lexbor's selector engine lower-cases names, which breaks XML case/namespace
+matching) - use XPath.
+
+The tree supports in-place mutation - every edit validates its input (names as
+XML 1.0 QNames, values as XML Char) so the tree stays serializable to
+well-formed XML, and a removed node is detached, never freed, so a live wrapper
+that aliases it stays usable:
+
+```ruby
+doc = Makiri::XML(%(<feed xmlns:dc="urn:dc"><entry id="1">Hi</entry><draft/></feed>))
+e   = doc.at_xpath("//entry")
+
+e["id"]   = "9"            # add or replace an attribute (value escaped on output)
+e["dc:k"] = "v"           # a prefixed name resolves against the in-scope xmlns
+e.content = "Bye"         # replace an element's children with text
+e.name    = "post"        # rename in place (identity + namespace re-resolved)
+e.delete("id")            # remove an attribute
+doc.at_xpath("//draft").remove
+
+doc.root.to_xml           # => "<feed xmlns:dc=\"urn:dc\"><post dc:k=\"v\">Bye</post></feed>"
+```
+
+New subtrees can be built too - `Document#create_element` (and
+`#create_text_node` / `#create_comment` / `#create_cdata` /
+`#create_processing_instruction`) make detached nodes, and `#add_child` / `<<`,
+`#add_previous_sibling` / `#before`, `#add_next_sibling` / `#after`, `#replace`
+link them. A node's namespace is resolved against its position **at insertion**
+(a prefixed name binds to the in-scope `xmlns`, an unprefixed element to the
+default namespace), so the same tree results whether you set names before or
+after attaching; an unbound prefix in the live tree fails closed. A node from
+another document is **deep-copied** into the target (the source is untouched):
+
+```ruby
+doc   = Makiri::XML(%(<feed xmlns="urn:a" xmlns:dc="urn:dc"/>))
+entry = doc.create_element("entry")
+entry["dc:id"] = "42"                       # prefixed attr resolves on insertion
+entry.add_child(doc.create_element("title", "Hello"))
+doc.root.add_child(entry)
+
+doc.to_xml   # => "...<entry dc:id=\"42\"><title>Hello</title></entry>..."
+```
+
+Supported edits: `#[]=`, `#delete` / `#remove_attribute`, `#content=`, `#name=`,
+`#remove` / `#unlink`, the factories above, and `#add_child` / `<<` /
+`#before` / `#after` / `#replace`. Insertion takes a `Makiri::XML` node or a
+`DocumentFragment` (its children are spliced in); a fragment is parsed by
+`Document#fragment(str)` (bound to the document) or `DocumentFragment.parse(str)`
+(standalone). A raw string handed straight to `#add_child` is **not** accepted -
+parse it into a fragment first. A whole document can also be built from scratch
+with `XML::Document.new` + `#root=` and the factories.
+
+The character encoding is autodetected (XML 1.0 Appendix F): a byte-order mark or
+the `<?xml encoding="..."?>` declaration selects it, so raw bytes (`File.binread`)
+in UTF-16, Shift_JIS, etc. parse correctly and a leading BOM is stripped. A
+concrete String encoding stays authoritative - a BOM or declaration that
+contradicts it is a fatal error, not a silent mis-decode.
+
+Parsing is DoS-bounded by a single arena memory ceiling (default 256 MiB,
+counting node structs and text), which fits every standard document. Raise it
+per parse for an unusually large one:
+
+```ruby
+Makiri::XML(huge_xml, max_bytes: 512 * 1024 * 1024)   # also Makiri::XML::Document.parse(..., max_bytes:)
+```
+
+Conformance is held by a regression net: the **W3C XML Conformance Test Suite**
+(`rake conformance:xmlconf`, 100% of the in-scope non-validating XML-1.0 tests),
+an XPath 1.0 differential vs Nokogiri/libxml2 (`rake conformance:xpath_xml`), and
+property-based testing that requires Makiri's tree to be byte-identical to
+Nokogiri's over generated documents (`rake conformance:xml_pbt`).
+
 ## Non-goals (v1.0)
 
-* XML parsing (HTML only).
+* Passing a raw markup string straight to an insertion method
+  (`node.add_child("<x/>")`); parse it into a fragment first
+  (`Document#fragment` / `DocumentFragment.parse`). (Building XML from scratch
+  (`XML::Document.new` + `#root=`), the node factories - `Document#create_element`
+  etc. - fragments, node insertion (`#add_child` / `#before` / `#after` /
+  `#replace`), and `#to_xml` serialization ARE supported.)
 * XSLT, DTD / Schema / RelaxNG validation, XPointer, XInclude.
 * Streaming / SAX parsing.
 * Drop-in replacement for every Nokogiri method. Makiri covers the common
   HTML-scraping and manipulation surface. Deliberately not provided:
-  - XML/XHTML serialization variants (`to_xml`, `to_xhtml`, `write_xml_to`)
+  - XHTML serialization variants (`to_xhtml`, `write_xml_to`); `#to_xml` is supported
   - XML/DTD construction (`create_internal_subset`, `external_subset`)
-  - namespace introspection beyond `namespace-uri()` (`namespace_definitions`, `add_namespace`, `collect_namespaces`)
+  - namespace *mutation* (`add_namespace_definition`); read introspection
+    (`#namespace`, `#namespace_definitions`, `#namespaces`, `#collect_namespaces`)
+    is supported on `Makiri::XML` nodes
   - Nokogiri internals (`decorate`, `slop!`, `validate`).
 
 ## Differences from Nokogiri
@@ -103,9 +252,26 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
 * `namespace-uri()` of an HTML element returns the XHTML URI (DOM-correct, as browsers report)
   * `Nokogiri::HTML5` returns `""`.
 
+### XML
+
+* `Makiri::XML` is **XML 1.0 only and non-validating**.
+  * A `version="1.1"` declaration is rejected; Nokogiri parses XML 1.1.
+  * The DTD is recognized but not processed: DTD-defined entities are not
+    expanded and DTD default attributes are not applied (Nokogiri/libxml2 can do
+    both). External entities/subsets are never fetched (no I/O).
+  * 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.)
+* 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.
+
 ### CSS
 
-* jQuery/Nokogiri CSS extensions are not supported (`:contains`, `:gt`, `:lt`, `:eq`, `:first`, …)
+* jQuery/Nokogiri CSS extensions are not supported (`:contains`, `:gt`, `:lt`, `:eq`, `:first`, ...)
   * Makiri uses Lexbor's standards-only selector engine.
     Use XPath (`xpath("//p[contains(., 'x')]")`) or Enumerable (`css('li')[1]`).
     Standard Level-4 selectors (`:is` / `:where` / `:has`) are supported; some of which Nokogiri rejects.

data/Rakefile

@@ -7,6 +7,24 @@ require "shellwords"
 
 GEMSPEC = Gem::Specification.load("makiri.gemspec")
 
+# Replace bundler/gem_tasks' `release` (which builds a source-only gem and
+# `gem push`es it from the dev machine) with a tag push: it hands the build,
+# GitHub Release, and the approval-gated RubyGems publish off to CI
+# (.github/workflows/release.yml). Nothing is pushed to RubyGems locally.
+Rake::Task["release"].clear
+desc "Tag v#{GEMSPEC.version} and push it; CI builds, releases, and publishes"
+task release: %w[release:guard_clean release:source_control_push] do
+  puts <<~MSG
+
+    Pushed tag v#{GEMSPEC.version}. GitHub Actions (release.yml) will now:
+      1. build the source gem + precompiled native gems,
+      2. create the GitHub Release and attach them, then
+      3. publish to RubyGems via OIDC - after the `rubygems` environment approval.
+    Approve the pending deployment in the Actions run to publish; nothing is
+    pushed to RubyGems from this machine.
+  MSG
+end
+
 Rake::ExtensionTask.new("makiri", GEMSPEC) do |ext|
   ext.lib_dir       = "lib/makiri"
   ext.ext_dir       = "ext/makiri"
@@ -26,7 +44,7 @@ end
 
 # `rake clean` (from rake-compiler) removes the ext build dir under tmp/,
 # including the generated Makefile. The next `rake compile` re-runs extconf,
-# so newly-added .c files are picked up — without this, a stale Makefile omits
+# so newly-added .c files are picked up - without this, a stale Makefile omits
 # new sources and macOS's -undefined dynamic_lookup turns the missing symbols
 # into runtime NULL calls. The vendored Lexbor build is deliberately NOT wiped
 # here (it is slow to rebuild and rarely changes); use `rake clean:lexbor` for
@@ -63,6 +81,17 @@ def asan_runtime_path
   nil
 end
 
+# The compiled extension, and whether it carries sanitizer instrumentation, so
+# `fuzz:sanitize SKIP_BUILD=1` can refuse to run a plain (non-ASan) build.
+def ext_bundle_path
+  Dir["lib/makiri/makiri.{bundle,so}"].first
+end
+
+def ext_sanitized?
+  bundle = ext_bundle_path or return false
+  !(`nm "#{bundle}" 2>/dev/null` =~ /asan|ubsan/i).nil?
+end
+
 desc "Build the extension with sanitizers (MAKIRI_SANITIZE, default " \
      "address,undefined) and run the spec suite under them"
 task :sanitize do
@@ -92,6 +121,16 @@ task fuzz: :compile do
   sh "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{ENV['FUZZ_ARGS']}"
 end
 
+desc "Fuzz the XML parser (hostile/mutated documents; override via FUZZ_ARGS)"
+task "fuzz:xml": :compile do
+  sh "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb --target xml #{ENV['FUZZ_ARGS']}"
+end
+
+desc "Fuzz the XML mutation surface (random edit sequences + invariants; override via FUZZ_ARGS)"
+task "fuzz:mutate": :compile do
+  sh "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb --target mutate #{ENV['FUZZ_ARGS']}"
+end
+
 desc "Run the performance benchmark (Makiri vs Nokogiri reference)"
 task bench: :compile do
   # Run outside the bundle so the bench-only gems (nokogiri, benchmark-ips)
@@ -101,6 +140,13 @@ task bench: :compile do
   end
 end
 
+desc "Run the XML reader benchmark (Makiri::XML vs Nokogiri::XML reference)"
+task "bench:xml" => :compile do
+  Bundler.with_unbundled_env do
+    sh "#{FileUtils::RUBY} -Ilib bench/bench_xml.rb"
+  end
+end
+
 namespace :conformance do
   desc "WHATWG HTML5 parsing conformance: run html5lib-tests through Makiri"
   task html5: :compile do
@@ -116,6 +162,28 @@ namespace :conformance do
     end
   end
 
+  desc "XML XPath 1.0 differential conformance: Makiri::XML vs Nokogiri::XML"
+  task xpath_xml: :compile do
+    Bundler.with_unbundled_env do
+      sh "#{FileUtils::RUBY} -Ilib spec/conformance/xml_xpath_diff.rb #{ENV['XPATH_ARGS']}"
+    end
+  end
+
+  desc "W3C XML Conformance Test Suite: well-formedness through Makiri::XML"
+  task xmlconf: :compile do
+    # Nokogiri (bench-only) parses the manifests, so run outside the bundle.
+    Bundler.with_unbundled_env do
+      sh "#{FileUtils::RUBY} -Ilib spec/conformance/xmlconf_runner.rb #{ENV['XMLCONF_ARGS']}"
+    end
+  end
+
+  desc "Property-based XML differential: generated documents, Makiri vs Nokogiri tree"
+  task xml_pbt: :compile do
+    Bundler.with_unbundled_env do
+      sh "#{FileUtils::RUBY} -Ilib spec/conformance/xml_pbt_diff.rb #{ENV['PBT_ARGS']}"
+    end
+  end
+
   desc "CSS Selectors differential conformance vs Nokogiri::HTML5"
   task css: :compile do
     Bundler.with_unbundled_env do
@@ -124,14 +192,31 @@ namespace :conformance do
   end
 end
 
-desc "Run all conformance suites (html5lib-tests + XPath & CSS differentials)"
-task conformance: %w[conformance:html5 conformance:xpath conformance:css]
+desc "Run all conformance suites"
+task conformance: %w[conformance:html5 conformance:xpath conformance:css conformance:xmlconf conformance:xpath_xml]
 
 namespace :fuzz do
-  desc "Run the fuzzer under AddressSanitizer (rebuilds the ext; --isolated)"
+  # Run the fuzzer under the sanitizer. Toggles (all via env):
+  #   FAST=1        run the surfaces NON-isolated (one process, no fork-per-query).
+  #                 Far higher throughput; ASan still aborts on a memory error
+  #                 (halt_on_error). The default (isolated) is the complete net:
+  #                 it also survives + attributes a genuine segfault and catches a
+  #                 hang via the per-query timeout, at much lower throughput.
+  #   SKIP_BUILD=1  reuse the current build instead of rebuilding (refuses to run
+  #                 if it is not a sanitizer build, so you never fuzz a plain ext).
+  #   FUZZ_TIME=N   seconds per surface (default 90).
+  #   FUZZ_ARGS=... run a single custom invocation instead of the three surfaces.
+  desc "Run the fuzzer under AddressSanitizer (FAST=1 non-isolated, SKIP_BUILD=1 reuse build)"
   task :sanitize do
     sanitize = ENV["MAKIRI_SANITIZE"] || "address,undefined"
-    sh({ "MAKIRI_SANITIZE" => sanitize }, "#{FileUtils::RUBY} -S rake clean compile")
+    if %w[1 true yes].include?(ENV["SKIP_BUILD"].to_s.downcase)
+      ext_sanitized? or
+        abort "fuzz:sanitize: SKIP_BUILD set but lib/makiri is not a sanitizer build; " \
+              "drop SKIP_BUILD to rebuild with MAKIRI_SANITIZE"
+      puts "fuzz:sanitize: reusing the existing sanitizer build (SKIP_BUILD)"
+    else
+      sh({ "MAKIRI_SANITIZE" => sanitize }, "#{FileUtils::RUBY} -S rake clean compile")
+    end
 
     env = {
       "ASAN_OPTIONS"  => "detect_leaks=0:detect_container_overflow=0:" \
@@ -144,7 +229,18 @@ namespace :fuzz do
       preload = RbConfig::CONFIG["target_os"] =~ /darwin/ ? "DYLD_INSERT_LIBRARIES" : "LD_PRELOAD"
       env[preload] = runtime
     end
-    args = ENV["FUZZ_ARGS"] || "--isolated --time 120"
-    sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{args}")
+
+    if ENV["FUZZ_ARGS"]
+      sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{ENV['FUZZ_ARGS']}")
+    else
+      iso  = %w[1 true yes].include?(ENV["FAST"].to_s.downcase) ? "" : "--isolated"
+      secs = ENV["FUZZ_TIME"] || "90"
+      # Cover every surface under the sanitizer: the query engine (XPath/CSS over
+      # parsed fixtures), the XML parser (hostile documents), and the XML mutation
+      # surface (random edit sequences + invariants).
+      ["", "--target xml", "--target mutate"].each do |surface|
+        sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{surface} #{iso} --time #{secs}".squeeze(" ").strip)
+      end
+    end
   end
 end

data/ext/makiri/bridge/bridge.h

@@ -46,6 +46,34 @@ mkr_ruby_borrowed_bytes_t mkr_ruby_bytes_view(VALUE in);
  * for an empty input), suitable for use while the GVL is released. */
 int mkr_ruby_copy_bytes(VALUE in, mkr_owned_bytes_t *out);
 
+/* Return a UTF-8 Ruby String for `str`, honouring its declared encoding: UTF-8 /
+ * US-ASCII / ASCII-8BIT are returned unchanged (the parser handles their bytes
+ * directly); any other encoding is transcoded to UTF-8 (invalid/undef -> U+FFFD)
+ * so its content is preserved rather than read as raw UTF-8. The UTF-8 common
+ * case is a single encoding comparison. */
+VALUE mkr_ruby_to_utf8(VALUE str);
+
+/* STRICT decode for XML (§2.1): like mkr_ruby_to_utf8 it honours the String's
+ * declared encoding (UTF-8 / US-ASCII / ASCII-8BIT pass through; any other
+ * encoding is transcoded to UTF-8) - but FAIL-CLOSED, never lenient: a non-UTF-8
+ * byte that can't be converted, invalid UTF-8, or an embedded NUL all raise
+ * Makiri::XML::SyntaxError (no U+FFFD replacement). Returns a validated,
+ * UTF-8-tagged Ruby String. (The HTML replace path mkr_ruby_to_utf8 itself is
+ * NOT reused for the conversion - only its encoding-judgment rule is shared.)
+ *
+ * +max_bytes+ bounds the decoded UTF-8 length: an input that already exceeds the
+ * parser's arena byte budget is rejected here with Makiri::XML::LimitExceeded,
+ * before the validation copy and the caller's GVL-release copy (so a hostile
+ * oversized document is not copied twice for a doomed parse). 0 disables the
+ * check (decode-only callers that build no arena). */
+VALUE mkr_xml_decode_input(VALUE str, size_t max_bytes);
+
+/* True if `str` is *already known* to be valid UTF-8 - pure ASCII, or valid in
+ * the UTF-8 encoding - from its cached coderange, WITHOUT forcing a scan. Lets
+ * the parse skip mkr_utf8_sanitize's validation pass for input Ruby has already
+ * classified (an unknown/broken coderange returns false: sanitize handles it). */
+bool mkr_ruby_str_known_valid_utf8(VALUE str);
+
 /* Validate a Ruby String for use as an XPath engine string: valid UTF-8,
  * no interior NUL, and at most +max_bytes+. Returns NULL on success and fills
  * +out+; otherwise returns a static reason string. +sv+ must be a String. */