leptris 1.6.0 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f24417196438a9a1aef17c3e1f648b7d85048659268a332341c36663a4a16a
-  data.tar.gz: 542fa2497b09a734f2cd65ca3eb398c90d24841bc4ed70577e7ed177e323f521
+  metadata.gz: 6cb4c2a8d3cb9da6f2c79fd03dc85b0f55f1a590b15a18ffedabd63177332f8e
+  data.tar.gz: df6b3611943af4f69c30d2a1650c86276fd89b7261f4d8da9dd43d6421b17de3
 SHA512:
-  metadata.gz: d46d2a265f3c07326fda5e152f338373772b9f804f5c5c7d8174dcb78dff3f10e5a875972b5635ab94e2309001552e85f0a45c26e14687c713d8647cdd32815c
-  data.tar.gz: a7ae147afbd49cf1afe4eebfd6f9e2ba4dea2e682a2da7cbd3e7b892aaf5bc3150eeffca6bdecd840a166499d17eefd6debf4f4df3e0fe59d34cdfe0613da84f
+  metadata.gz: 82fde4f6f7d6645c1eafe9d130f532437fb28703ab27aa6753d9afc2ad53f2eabb6e852bf8338b8e8c1e551225fd2548045430f93b2063cd31adf7c2e6132e2e
+  data.tar.gz: 726699586511ef79fdc5c51e4a102e49329c480bd66d39089c2dd0201c0d96117127f6a5cbb9a90051a115e0c130877c957e6342b124fb1a18211104a8bad591

data/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.2] - 2026-08-24
+
+Lockstep with libleptris 1.6.2 (fix releases, no public API changes).
+
+### Changed
+
+- CI/build pin libleptris v1.6.2, carrying the serializer fix for
+  mixed-content indentation (upstream #534 — never indent inside
+  mixed-content elements).
+
+## [1.6.1] - 2026-08-24
+
+### Added
+
+- **Readonly mode**: `Leptris::XML.parse(xml, readonly: true)` /
+  `Document#readonly!` (one-way). Mutations raise
+  `Leptris::XML::ReadOnlyError`; read paths memoize aggressively
+  (names, content, children NodeSets, attribute hashes) since they can
+  never go stale; the C document is frozen (advisory upstream).
+  Detached factories (`create_element` etc.) remain usable.
+  Purpose: steady-state read performance for the dominant
+  parse-query-serialize workload — see Changed.
+
+### Changed
+
+- Micro-optimizations targeting the small-document gap versus C
+  extension bindings:
+  - node type is memoized from `Node.wrap`'s dispatch call — every
+    predicate and `#type` is now FFI-free
+  - the default serialize options struct is built once and reused
+  - `Document.parse` skips the per-parse status MemoryPointer (the C
+    out-param is nullable; failure detail comes from the thread-local
+    last error)
+  - `Element#name` memoizes (invalidated by `name=`)
+
 ## [1.6.0] - 2026-08-24
 
 Lockstep with libleptris 1.6.0 — the moxml-adapter blockers fixed:
@@ -26,6 +61,41 @@ release: pull (StAX) API, bounded iterparse, compiled XPath
 expressions, per-parse options, truthful serialization encoding
 declarations. Binding-side adoption of the new APIs follows.
 
+## [1.6.2] - 2026-08-24
+
+Lockstep with libleptris 1.6.2 (fix releases, no public API changes).
+
+### Changed
+
+- CI/build pin libleptris v1.6.2, carrying the serializer fix for
+  mixed-content indentation (upstream #534 — never indent inside
+  mixed-content elements).
+
+## [1.6.1] - 2026-08-24
+
+### Added
+
+- **Readonly mode**: `Leptris::XML.parse(xml, readonly: true)` /
+  `Document#readonly!` (one-way). Mutations raise
+  `Leptris::XML::ReadOnlyError`; read paths memoize aggressively
+  (names, content, children NodeSets, attribute hashes) since they can
+  never go stale; the C document is frozen (advisory upstream).
+  Detached factories (`create_element` etc.) remain usable.
+  Purpose: steady-state read performance for the dominant
+  parse-query-serialize workload — see Changed.
+
+### Changed
+
+- Micro-optimizations targeting the small-document gap versus C
+  extension bindings:
+  - node type is memoized from `Node.wrap`'s dispatch call — every
+    predicate and `#type` is now FFI-free
+  - the default serialize options struct is built once and reused
+  - `Document.parse` skips the per-parse status MemoryPointer (the C
+    out-param is nullable; failure detail comes from the thread-local
+    last error)
+  - `Element#name` memoizes (invalidated by `name=`)
+
 ## [1.6.0] - 2026-08-24
 
 Lockstep with libleptris 1.6.0 (v1.4/v1.5 were fix releases with no

data/CLAUDE.md

@@ -4,101 +4,90 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-`leptris-ruby` is a Ruby gem that wraps the native C library `libleptris` (built via CMake) via the `ffi` gem. It exposes an XML parser with complete XPath 1.0 support and a CLI. Target users want Nokogiri-like ergonomics with native speed.
-
-- Native dep: `libleptris` shared library, built by `ext/leptris/extconf.rb` (CMake) and copied to `lib/libleptris.{dylib,so,dll}`.
-- Ruby entry point: `lib/leptris.rb` (uses `require_relative` — see "Conventions" below).
-- CLI: `bin/leptris` (Thor-based), defined in `lib/leptris/cli.rb`.
+`leptris-ruby` is the official Ruby binding for `libleptris`
+(https://github.com/leptris/leptris), a pure-C99 XML 1.0 parser with a
+W3C-conformant XPath 1.0 engine (438/438 on the W3C suite), full SAX,
+pull parsing, and C14N. The binding is **FFI-based** (no C extension,
+no compilation at install) and ships **precompiled platform gems**
+with the shared library vendored inside: x86_64/aarch64-linux (glibc
+and musl), x86_64/arm64-darwin, x64-mingw32/ucrt, aarch64-mingw-ucrt,
+plus the pure-Ruby fallback gem.
+
+Version lockstep: the gem's major.minor tracks the C library
+(`libleptris 1.6.x` <-> `leptris 1.6.x`). A C release means one PR
+carrying version.rb + the Rakefile `LIBLEPTRIS_VERSION` pin + the
+CHANGELOG entry, then the release workflow.
 
 ## Commands
 
 ```bash
-# Build the C library and install it into lib/ for FFI to load
-bundle exec rake compile            # runs ext/leptris/extconf.rb (CMake)
-
-# Run the full test suite (builds first)
-bundle exec rake test               # = spec, depends on :compile
-
-# Run RSpec directly (skips build dependency)
-bundle exec rspec                   # full suite
-bundle exec rspec spec/leptris/document_spec.rb    # one file
-bundle exec rspec spec/leptris/document_spec.rb:42 # one example by line
-
-# Lint
-bundle exec rubocop
-
-# Clean build artifacts (lib/libleptris.*, ext/leptris/build, Makefile, tmp, pkg)
-bundle exec rake clean
+bundle exec rake compile   # build libleptris (pinned tarball) into lib/
+bundle exec rspec          # full suite (uses the vendored library)
+bundle exec rspec spec/xml/xpath_spec.rb:42   # one example
+bundle exec rake gem:native:arm64-darwin      # platform gem
 ```
 
-CI (`.github/workflows/test.yml`) runs `bundle exec rspec` + `bundle exec rubocop` on Ubuntu + macOS across Ruby 3.0–3.3.
+`LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec rspec` runs
+against an arbitrary build (e.g. a libleptris checkout under test).
+
+## Architecture
 
-## Architecture: current state (v1.1.0)
+The C DOM is the single source of truth; Ruby objects are thin FFI
+handles. One Ruby method = one FFI call wherever possible.
 
 ```
-User Ruby code
-    ↓
-Leptris.parse / Leptris.parse_file                  (lib/leptris.rb)
-    ↓ FFI call (leptris_parse) — one-shot tree copy
-C document → FFI::Bridge.document_from_ptr        (lib/leptris/ffi/bridge.rb)
-    ↓ recursive hydration
-Ruby Document → Element → Node → NodeSet          (lib/leptris/{document,element,node,node_set}.rb)
+lib/leptris.rb                — Leptris::VERSION
+lib/leptris/xml.rb            — autoload registry, error classes,
+                                Leptris::XML.parse / parse_file
+lib/leptris/xml/ffi.rb        — every public C declaration + seam
+                                helpers (check_status, read_owned_string,
+                                status_message)
+lib/leptris/xml/document.rb   — the only C-memory owner (finalizer);
+                                factories, PI accessors, exslt, last_error
+lib/leptris/xml/node.rb       — Node.wrap: the ONLY wrapper constructor
+                                (identity cache + type dispatch)
+lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
+                                face; namespace/mutation surface
+lib/leptris/xml/node_set.rb   — lazy XPath results; batch fetch via
+                                get_nodes_ex
+lib/leptris/xml/searchable.rb — xpath/css/at_*; namespace-bound path
+lib/leptris/xml/xpath.rb      — compiled expressions (parse once,
+                                eval many)
+lib/leptris/xml/sax/          — callback SAX
+lib/leptris/xml/pull.rb       — StAX-style pull parsing
+lib/leptris/xml/iterparse.rb  — bounded-memory element iteration
+lib/leptris/xml/serialization.rb — serialize/c14n (Document + Element
+                                one-liners over this module)
+lib/leptris/xml/c_string_array.rb — NULL-terminated char** adapter
+lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
 ```
 
-Key directories:
-
-- `lib/leptris.rb` — top-level module, `parse`, `parse_file`, `xpath_evaluate`, error classes (`ParseError`, `XPathError`, `EvaluationError`).
-- `lib/leptris/ffi/` — FFI plumbing: `library.rb` (bindings), `types.rb` (constants), `memory.rb` (AutoPointer wrappers), `errors.rb` (thread-local error check), `bridge.rb` (C ptr → Ruby object).
-- `lib/leptris/{document,element,node,node_set}.rb` — pure-Ruby tree model (full hydration on parse).
-- `lib/leptris/xpath/` — pure-Ruby XPath engine (lexer, parser, compiler, VM). XPath DOES NOT go through C currently; `lib/leptris.rb#xpath_evaluate` calls `FFI.leptris_xpath_eval` only as a wrapper, but the result materialization in `FFI::Bridge` recursively re-walks via the Ruby tree.
-- `lib/leptris/adapter*` — third-party format adapters.
-- `spec/leptris/` — 250+ RSpec examples covering parser, XPath, namespaces, errors, ox-compatibility.
-- `ext/leptris/` — CMake-based build of `libleptris` (sources come from the separate `leptris/leptris` repo at build time).
-
-## Architecture: planned rewrite (see `TODO.impl/`)
-
-The five files under `TODO.impl/` describe a planned rewrite that has NOT been implemented yet. Read them before touching the Ruby/COM layer. Summary:
-
-1. **`01-architecture.md`** — Rewrite `leptris-ruby` as a **thin FFI wrapper** around libleptris v0.4.2 with a **Nokogiri-compatible API**. Current code does a one-shot C→Ruby tree copy and runs XPath in Ruby; planned code keeps the C DOM as the single source of truth (Ruby objects = handles wrapping opaque pointers), so every Ruby method = one FFI call and XPath/SAX go through the C engine.
-
-2. **`02-ffi-declarations.md`** — Complete FFI attachment: every public function in libleptris v0.4.2 (document lifecycle, node access, element queries/mutation, creation, text/comment/CDATA/PI access, XPath + variable set, SAX, serialization, `leptris_free_string`). Opaque typedefs: `document`, `element`, `node_ref`, `xpath_result`, `sax_parser`, `attribute`. Structs: `SAXHandler`, `SerializeOptions`. Constants for status codes, node types, XPath result types.
-
-3. **`03-document-node-element-nodeset.md`** — Target file layout:
-   ```
-   lib/leptris.rb
-   lib/leptris/xml.rb
-   lib/leptris/xml/{ffi,document,node,element,text,comment,cdata,
-                   processing_instruction,attr,node_set,searchable,
-                   parse_options}.rb
-   ```
-   `Node.wrap(ptr, doc)` dispatches on the C node type. Document is the only memory-owning object; Node/Element/Text/Comment/CDATA/PI/Attr are non-owning handles valid until `Document#free`.
-
-4. **`04-sax-parser.md`** — `Leptris::XML::SAX::{Parser, Document}` wrapping `leptris_sax_parse` / `leptris_sax_parser_feed`. FFI::Function callbacks for each event; `start_element` walks the NULL-terminated `const char**` attribute array. Streaming via incremental `feed`.
-
-5. **`05-serialize-c14n-memory-specs-css.md`** — `SerializeOptions` struct for `leptris_serialize_document`; `Document#canonicalize` (modes `C14N_1_0`, `C14N_1_1`, `C14N_EXCLUSIVE`); `UseAfterFreeError` guard; minimal CSS-to-XPath converter (`.class`, `#id`, `[attr]`, `[attr=val]`, `:first-child`, `:last-child`); spec layout under `spec/xml/{parse,document,node,element,node_set,xpath,sax,serialize,c14n,memory}_spec.rb`.
-
-### Memory ownership rules (planned)
-
-| Ruby class | Owns C memory? | Free function |
-|---|---|---|
-| `Document` | YES | `leptris_document_free` |
-| `Node`/`Element`/text/CDATA/PI/Attr | NO (borrowed) | freed transitively by Document |
-| `NodeSet` (XPath result) | YES | `leptris_xpath_result_free` |
-| SAX handler closures | callback lifetime | `leptris_sax_parser_free` |
-
-GC safety net: `ObjectSpace.define_finalizer` capturing the **raw pointer value**, not the Ruby wrapper. Finalizers must not double-free after explicit `#free`.
-
-## Reference material
-
-- Nokogiri source (`~/src/external/nokogiri/`) — `lib/nokogiri/xml/{node,node_set,document,searchable}.rb` are the API shape targets.
-- libleptris public headers (`src/include/leptris/{types,leptris}.h`, `src/include/leptris/{dom,xpath,sax}/*.h`) — the single source of truth for FFI declarations. Target tag: `v0.4.2`.
-- `docs/FFI_ARCHITECTURE.md` — describes the v0.5.0 FFI design (AutoPointer, two-pointer strategy for XPath). The planned rewrite supersedes some of this (no recursive hydration, no two-pointer — the Document pointer alone suffices because Node objects stay as C handles).
-- `docs/BUILD.md` — CMake build reference for libleptris itself.
-
-## Conventions (project-specific)
-
-- **Autoload, not require_relative.** TODO 3 is explicit: `lib/leptris.rb` → `autoload :XML, 'leptris/xml'`; `lib/leptris/xml.rb` → `autoload :Document, 'leptris/xml/document'`. Autoload entries live in the **immediate parent namespace's file** (create that file if missing). The current `lib/leptris.rb` uses `require_relative` — when implementing TODO 3, do not retrofit require_relative into the new layout.
-- **No `instance_variable_set`/`_get` cross-object.** TODO 3 is explicit. The current `lib/leptris.rb` and `lib/leptris/ffi/bridge.rb` use `instance_variable_get(:@_c_ptr)` heavily — that pattern is debt to migrate, not a model to copy. In the rewrite, expose `c_ptr`/`document` as public `attr_reader`s and access via those.
-- **No `respond_to?` type checks.** Use `is_a?`. The current `lib/leptris.rb#xpath_evaluate` checks `context_node != doc` to disambiguate — fine. Don't add `respond_to?(:c_ptr)` style checks.
-- **No doubles in specs.** The existing `spec/leptris/` specs use real model instances (XML strings → `Leptris.parse` → real `Document`/`Element`/`NodeSet`). Keep it that way.
-- **Forward compatibility:** Keep `Leptris.parse` / `Leptris.parse_file` as the existing top-level API during the rewrite. The new `Leptris::XML.parse` may coexist.
+### Ownership and seams
+
+- `Document` owns C memory (explicit `#free` or GC finalizer; wrapper
+  cache is a strong Hash cleared on free). Every other class is a
+  borrowed handle valid while its Document lives.
+- All wrapper construction goes through `Node.wrap` — wrapper
+  identity (`doc.root.equal?(doc.root)`) is guaranteed by the
+  per-document cache.
+- Status checks go through `FFI.check_status`; C `char*` returns go
+  through `FFI.read_owned_string`; array wire format (both
+  directions) goes through `CStringArray`. Never hand-roll these.
+- The release workflow's publish loop is idempotent (already-published
+  gems are skipped).
+
+## Conventions
+
+- Autoload only — no `require_relative` inside `lib/`.
+- No `instance_variable_set`/`_get` across objects; no `respond_to?`
+  type checks; specs use real documents, never doubles.
+- New C surface: attach in `ffi.rb`, sugar where it earns its keep,
+  specs against a locally built library, CHANGELOG, lockstep release.
+- All changes via PRs; no AI attribution; `git add` explicit paths.
+
+## Reference
+
+- libleptris public headers (`src/include/leptris/*.h`) are the
+  contract; when symbols change, bump lockstep and audit
+  attached-vs-exported (`nm -gU` on a fresh build).
+- Upstream issues worth tracking live at leptris/leptris.

data/README.adoc

@@ -136,6 +136,25 @@ doc.root.traverse do |node|
 end
 ----
 
+== Readonly mode
+
+For the dominant parse-query-serialize workload, parse with
+`readonly: true` (or call `Document#readonly!`, one-way):
+
+[source,ruby]
+----
+doc = Leptris::XML.parse(xml, readonly: true)
+doc.root.children.first["id"]        # reads are memoized
+doc.root.name                        # plain ivar after first call
+doc.root << doc.create_element("x")  # raises ReadOnlyError
+----
+
+Reads (`name`, `content`, `children`, `attributes`) memoize
+aggressively — they cannot go stale because mutation is forbidden.
+Every mutator raises `Leptris::XML::ReadOnlyError`. Detached factories
+(`create_element` and friends) still work: building a *new* tree
+against a readonly document is legal; mutating the frozen one is not.
+
 == Searching: XPath and CSS
 
 `Document` and `Element` (via `Leptris::XML::Searchable`) support:
@@ -376,11 +395,66 @@ Notable differences:
 
 == Performance
 
-On the benchmark suite in `benchmark/leptris_vs_nokogiri.rb` (Ruby 3.3,
-libleptris v0.13+, macOS arm64), Leptris matches or beats Nokogiri on
-parse, XPath, serialize, and full-tree traverse for the small and
-medium documents that dominate real-world XML workloads. Run the
-benchmark locally for numbers on your hardware:
+Measured with metanorma/serialbench (Ruby 3.4.8, leptris 1.6.0,
+libleptris 1.6.0, macOS arm64) — Leptris vs the full field:
+
+[cols="2,1,1,1,1",options="header"]
+|===
+|Operation |Leptris |Ox |Nokogiri |vs Ox
+
+|parse medium (300 KB)
+|0.97 ms
+|3.00 ms
+|8.57 ms
+|3.1x faster
+
+|parse large (4.4 MB)
+|13.51 ms
+|77.06 ms
+|104.22 ms
+|5.7x faster
+
+|generate medium
+|1.75 ms
+|14.19 ms
+|23.93 ms
+|8.1x faster
+
+|generate large
+|74.57 ms
+|80.91 ms
+|117.16 ms
+|1.1x faster
+
+|streaming medium
+|0.73 ms
+|103.82 ms
+|43.74 ms
+|142x faster
+
+|streaming large
+|8.52 ms
+|204.14 ms
+|239.14 ms
+|24x faster
+
+|Ruby allocations (medium)
+|0.01 MB
+|18.43 MB
+|39.05 MB
+|~1800x less
+|===
+
+Leptris takes first place on every XML operation above small-document
+size, including against Ox (the C-extension speed champion). On
+small-document micro-operations (sub-5 µs), C extensions hold an
+inherent edge per call; Leptris's readonly mode closes the
+steady-state gap by memoizing reads behind an immutability guarantee.
+
+For XPath-heavy workloads, `Leptris::XML::XPath.compile` evaluates a
+parsed expression repeatedly without re-parsing.
+
+Run the local benchmark for numbers on your hardware:
 
 [source,shell]
 ----
@@ -392,7 +466,7 @@ bundle exec ruby benchmark/leptris_vs_nokogiri.rb
 [source,shell]
 ----
 bundle install                       # install Ruby deps
-bundle exec rspec                    # full test suite (176 specs)
+bundle exec rspec                    # full test suite (229 specs)
 bundle exec rspec spec/xml/xpath_spec.rb:42   # one example by line
 bundle exec rubocop                  # lint
 ----

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.6.0"
+LIBLEPTRIS_VERSION = "1.6.2"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/benchmark/README.md

@@ -1,168 +1,12 @@
-# leptris-ruby vs Nokogiri — Ruby-level benchmarks
+# leptris vs the field
 
-Compares `Leptris::XML` (FFI → libleptris v0.12.0) against `Nokogiri::XML`
-(C extension → libxml2) on the operations that matter for typical use.
+The authoritative cross-library numbers live in the README's
+Performance section (measured with metanorma/serialbench).
 
-Run with:
+This local benchmark compares against Nokogiri only:
 
-```
-bundle exec ruby -Ilib benchmark/leptris_vs_nokogiri.rb
-```
+    LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec ruby benchmark/leptris_vs_nokogiri.rb
 
-## Latest run (M1, libleptris v0.12.0, Nokogiri 1.19.4)
-
-All libleptris upstream issues closed (#166–#262, 21 issues total).
-v0.12.0 ships the [#262](https://github.com/leptris/leptris/issues/262) proposals:
-batch XPath result accessor (`leptris_xpath_result_get_nodes`) and per-node
-`binding_wrapper` field. The Ruby binding uses the batch accessor in
-`NodeSet#each`; the `binding_wrapper` is left for the libleptris team's
-other bindings (Python ctypes, etc.) — the Ruby binding's per-Document
-`ObjectSpace::WeakMap` cache is faster (no FFI call per cache lookup).
-
-Median of 3 runs (run-to-run variance is significant on cold starts and
-shared-runner workloads; the trend is stable):
-
-| Operation | Leptris | Nokogiri | Leptris / Nokogiri | Winner |
-|---|---:|---:|---:|---|
-| Parse small (431 B) | ~6 µs | ~14 µs | **~2×** | Leptris (variable) |
-| Parse medium (12 KB) | ~32 µs | ~200 µs | **~6×** | Leptris |
-| XPath `count(//book)` | ~1.5 µs | ~9 µs | **~6×** | Leptris |
-| XPath `//book` (100-node nodeset) | ~4 µs | ~13 µs | **~5×** | Leptris |
-| XPath `//book[@id='50']` (1 match) | ~6 µs | ~80 µs | **~10×** | Leptris |
-| XPath `//book[price > 50]` | ~80 µs | ~100 µs | **~1.3×** | Leptris |
-| XPath `//author \| //title` (union) | ~14 µs | ~25 µs | **~3×** | Leptris |
-| Tree traversal | ~900 µs | ~500 µs | 0.55× | Nokogiri (1.8× faster) |
-| Serialize | ~28 µs | ~85 µs | **~3×** | Leptris |
-
-**Leptris beats Nokogiri on 8 of 9 operations.** Only tree traversal still
-loses, by ~1.8×.
-
-### Why tree traversal still loses
-
-`Node#traverse` visits every node and materializes each one via
-`Node.wrap`. The per-Document `ObjectSpace::WeakMap` cache helps on
-repeated traversals of the same doc but not on a single one. Each
-visited node pays:
-- 1 FFI call to `leptris_node_first_child` / `_next_sibling`
-- 1 FFI call to `leptris_node_get_type` (for wrap dispatch)
-- 1 Ruby object allocation (cache miss)
-
-Nokogiri's libxml2 C extension handles traversal in C and only crosses
-into Ruby when the user's block is called. No per-node FFI.
-
-The libleptris `binding_wrapper` field shipped in v0.12.0 doesn't help
-here in the Ruby binding — Ruby FFI still needs an FFI call to read
-`binding_wrapper`. The Ruby-side `WeakMap` cache avoids that FFI call
-on cache hits. So the binding's existing cache is already optimal for
-Ruby; the `binding_wrapper` field is more useful for bindings that
-don't have a native GC hook (Python ctypes, Go cgo, Rust bindgen).
-
-## What changed from earlier runs
-
-### v0.11.0 → v0.11.2 (binding-side)
-
-- **Lazy NodeSet** — `NodeSet.from_result` keeps the
-  `LeptrisXPathResult*` alive (via `FFI::AutoPointer`) and materializes
-  `self[i]` on demand. Eager materialization was the #1 cost.
-- **Per-Document wrapper cache** — `ObjectSpace::WeakMap` keyed on c_ptr
-  address. Eliminates re-allocation on repeated access to the same node.
-
-### v0.11.4 (libleptris-side)
-
-- **`leptris_xpath_result_get_nodes`** — batch accessor. The Ruby binding
-  now uses this in `NodeSet#each` to fetch all node pointers in one FFI
-  call instead of N calls.
-
-### v0.12.0 (libleptris-side)
-
-- **`binding_wrapper` field on `LeptrisNode`** — present in the C struct
-  but not used by the Ruby binding (see "Why tree traversal still loses"
-  above). Useful for non-Ruby bindings.
-- **`#261` fix** — `benchmark-ips` on 38 KB docs no longer segfaults.
-  All upstream issues closed.
-
-### Before/after the binding + libleptris v0.12.0 optimizations
-
-| Operation | v0.11.0 (eager) | v0.12.0 (lazy + batch) | Speedup |
-|---|---:|---:|---:|
-| XPath `//book` (100 nodes) | 87.77 µs (0.15×) | ~4 µs (5×) | **22×** |
-| XPath union (200 nodes) | 188.40 µs (0.14×) | ~14 µs (3×) | **13×** |
-| XPath complex | 126.88 µs (0.67×) | ~80 µs (1.3×) | 1.6× |
-| Tree traversal | 1203 µs (0.50×) | ~900 µs (0.55×) | 1.3× |
-
-## What this means for the v0.1.0 release
-
-- Leptris is the right choice for almost every Nokogiri workload on
-  small-to-medium docs (≤20 KB): 2–10× faster than Nokogiri.
-- Tree-traversal-heavy workloads (single-pass DOM scraping where you
-  touch every node once) are 1.8× slower than Nokogiri. Acceptable
-  for v0.1.0; the binding could ship a "fast traverse" path later that
-  skips wrapping for read-only blocks.
-- All known libleptris bugs are fixed. No upstream blockers.
-
-## Analysis
-
-### Where Leptris wins
-
-**Parse (1.69×–6.90×)** — libleptris's single-pass direct parser (the only
-parser since v0.11.0, after flat + legacy were deleted) is dramatically
-faster than libxml2's parser. The gap widens with document size.
-
-**XPath returning scalars (4.56×)** — `count()`, `boolean()`, `string()`,
-`number()` queries skip NodeSet materialization entirely. libleptris's XPath
-bytecode VM evaluates these in a single C call, no Ruby objects allocated
-per match.
-
-**XPath predicate match (13.01×)** — when the predicate narrows to a small
-result set (single match in this test), Leptris is much faster than
-Nokogiri/libxml2.
-
-**Serialize (2.84×)** — single C call into `leptris_document_serialize`,
-no Ruby traversal.
-
-### Where Nokogiri wins
-
-**Nodeset-returning XPath (0.13×–0.16×)** — when a query returns a 100-node
-NodeSet, Leptris materializes every node eagerly (100× `Node.wrap` calls,
-each dispatching on `leptris_node_get_type`). Nokogiri caches wrappers
-lazily.
-
-**Tree traversal (0.49×)** — same root cause. `Node#traverse` creates a
-new wrapper per visited node via `Node.wrap`; Nokogiri reuses cached
-wrappers.
-
-### Optimization opportunities (Ruby-side, no libleptris work needed)
-
-1. **Lazy NodeSet materialization.** Currently `NodeSet.from_result`
-   iterates the C result and calls `Node.wrap` for each entry on
-   construction. Switch to lazy: keep the `LeptrisXPathResult*` alive,
-   materialize `self[i]` on demand. Frees the eager 100× wrap.
-2. **Node wrapper cache.** Weak-ref map keyed on the c_ptr address.
-   `Node.wrap(ptr)` checks the cache first; only creates a new wrapper
-   if none exists. Matches Nokogiri's behavior.
-3. **Specialized traverse path.** For pure-traversal use cases (no
-   per-node mutation), skip the wrapper and call FFI directly. Lower
-   overhead but less idiomatic.
-
-### Blockers
-
-**Parse-loop segfault on >20 KB docs with explicit `Document#free`
-(libleptris #256).** The v0.11.1 fix addressed one stale-thread-local
-path but not the parse+free cycle path. Long-running services and batch
-processors parsing medium/large XML cannot rely on the standard Ruby
-"let GC handle document lifetime" pattern OR the explicit `Document#free`
-pattern. Tracked upstream; workaround: cap doc size or avoid tight loops.
-
-**DOCTYPE PUBLIC/SYSTEM not exposed (libleptris #253).** Unrelated to
-benchmarks but blocks 4 Ruby specs. Low impact on perf-sensitive workloads.
-
-## What this means for the v0.1.0 release
-
-- For **parse-heavy / XPath-aggregate / serialize** workloads on small-to-
-  medium docs (≤20 KB): Leptris is clearly the right choice. 1.7-7× faster
-  than Nokogiri.
-- For **heavy nodeset manipulation** (scraping, large DOM traversal):
-  Nokogiri is faster today. The Ruby-side optimizations above would close
-  most of the gap.
-- For **long-running services on medium/large docs**: blocked by #256
-  until libleptris ships a complete fix.
+For the full-field race (Ox, Nokogiri, Oga, REXML, Leptris), use
+https://github.com/metanorma/serialbench — leptris's adapter ships
+there under `lib/serialbench/serializers/xml/leptris_serializer.rb`.

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.6.0"
+  VERSION = "1.6.2"
 end

data/lib/leptris/xml/cdata.rb

@@ -8,6 +8,7 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_cdata_node_set_content(@c_ptr, new_content.to_s))
     new_content

data/lib/leptris/xml/comment.rb

@@ -8,6 +8,7 @@ class Leptris::XML::Comment < Leptris::XML::Node
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_comment_node_set_content(@c_ptr, new_content.to_s))
     new_content