leptris 1.9.92.2 → 1.9.105.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56235008b014f2ccf89a5713d7e95f6cf358a828be7aefb5923a651065980d18
-  data.tar.gz: 3d0d3c43d5f2a05fc3c21c0efbeadd33e308d4deaa330fe9b2e8530672944d40
+  metadata.gz: 6d66d917b7658ce7016fc697f5c26bc0f26a4c529a2ff4cccdc241dc43524b61
+  data.tar.gz: 711c7ad4aa90101509bddcf8dbd9a5d456736b774e00bf4603b135b72e2b1f81
 SHA512:
-  metadata.gz: 22c6d7837e4c8db9c4298a5a8b1f944e3c3f2b8ad02126a5e6374fb68b8619fa0456e58f9f1aca6f6384ead6148fc0b83d516d254558d35d5f02e7c9671f762f
-  data.tar.gz: b891d175c7e9655a1346bd414191d1bc58465ae22f20949ca91a29ce95497edb943e6c9b49b1ca85f824dcd6160a967c12f2be27c12cf69c85303f7402112e12
+  metadata.gz: 16f738b770e66956609d5b96132e813fecd50d3d5e9839f7102d0df2b53eedda4778805d1f6a17a8931b639557d5596b49d6807969a8fb21736704581b99f726
+  data.tar.gz: b04afa176b4fa26efff932b3b46de5e75cb1dbc99a4f2cb2ab44f35a1dc27d30f21916f303007e5a081f8738b082ac5e274e469e4d05d05b9b9cf86c6221367a

data/CHANGELOG.md

@@ -5,6 +5,147 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.105.0] - 2026-09-08
+
+### Changed
+
+- **Lockstep with libleptris 1.9.105** (1.9.101 → 1.9.105 — five
+  releases). One new C symbol attached (audit 265/265):
+  - **HTML two-mode split** (1.9.104/1.9.105, #659):
+    `Leptris::XML.parse_html(html, mode: :html4 | :whatwg)`.
+    **:html4 is the default** — pins the libxml2/Nokogiri
+    compatibility shape (leading script/style stay in body) so the
+    binding's byte-parity contract holds; **:whatwg** selects the
+    conformant engine (full implied-head set, foster parenting —
+    html5lib corpus 294/1555 vs Nokogiri's 372). Four specs.
+  - **#904 fixed** (1.9.103): iterparse yields prime the TLS
+    last-root memo — the ~1.4 µs residual per streamed attribute
+    read is GONE (measured at the noise floor vs the parse-only
+    baseline; was 2.19 µs, document case 0.82 µs).
+  - **#905 hotfix** (1.9.102): the v1.9.99 register-elision
+    (SEGFAULT in `fn:snapshot`'s detached-copy path on macOS,
+    0-nodes on Linux) reverted — the Round-20 register-on-create
+    contract restored. **1.9.100.0/.1/.2 carried this segfault**
+    and are yanked.
+  - 1.9.101 eval perf: AVT brace-free fast path + the AST-cache
+    mutex skip for single-threaded transforms (~14400 lock/unlock
+    ops dropped per heavy transform).
+
+## [1.9.100.2] - 2026-09-07
+
+### Changed
+
+- **Constraint compliance refresh** (TODO.restructure/14): two
+  fresh `respond_to?(:read)` duck checks that crept in with the
+  parallel SAX-drain and Pull-parse commits replaced with typed
+  branches (`is_a?(String) ? itself : .read`) — the same
+  discipline as 01.
+- README gains the three newest features: `Node#digest`,
+  `Element#to_xml(expand_empty: true)`, and the iterparse
+  lifetime contract (`UseAfterFreeError` on post-iteration use,
+  `#document` still nil).
+- CLAUDE.md architecture map refreshed: `iteration_scope.rb` and
+  `result_attr.rb` added with their seams.
+
+### Notes
+
+The perf battery window is still blocked on the shared host
+(load 169 at this writing); the standing baseline from the clean
+1.9.76 window holds.
+
+## [1.9.100.1] - 2026-09-07
+
+### Fixed — restructure round 2 (TODO.restructure/08-13, DONE)
+
+- **#152 closed** (iterparse lifetime + cost): new
+  `IterationScope` — the owning context for yielded elements.
+  Post-iteration use of a held element now raises
+  `UseAfterFreeError` instead of segfaulting (the scope carries
+  the iterator handle as the liveness signal `ensure_alive!`
+  reads); `Element#to_xml` and `#inner_html` gained the liveness
+  guard they were missing (serialization reads C memory
+  unguarded — true for freed Documents too); wrapper identity
+  holds within a yielded subtree and resets across yields (the
+  released pool memory is recycled); `#document` still answers
+  nil (documented contract) while memoization engages — the
+  reported ~8.5 µs parentless attribute read drops to ~2.2 µs.
+  The residual ~1.4 µs vs the document case is engine-side
+  (leptris/leptris#904). Four new specs.
+- **#153 closed** (PR #154, merged): XPath attribute-node results
+  wrap as usable `ResultAttr` faces (`#name`, `#value`, `#to_s`)
+  with values captured at result materialization — symmetric to
+  `ResultText`.
+- **#149 diet** (binding-side): `Node.wrap_fresh` — one
+  construction authority shared with `wrap` (the type dispatch
+  lives in one place), skipping the guaranteed-miss cache lookup
+  on factory paths. create_text measured 2.8x → 2.18x Nokogiri;
+  the remaining gap is per-call FFI marshaling vs a C extension —
+  the structural ceiling of the FFI-only architecture, documented
+  on the issue.
+- **Serialization**: `element_xml_expand_empty` memoizes its ext
+  struct (`EXPAND_EMPTY_EXT`), mirroring `INDENT_TEXT_EXT`.
+- **Spec MECE**: digest spec homed in seam_and_reads (Node
+  behavior), expand_empty in document_spec (serialization);
+  count-neutral moves, 544 examples total.
+
+### Changed
+
+- `#document` on iterparse-yielded elements preserves the nil
+  contract through a scope-aware reader.
+
+## [1.9.100.0] - 2026-09-07
+
+### Changed
+
+- **Lockstep with libleptris 1.9.100** (1.9.94 → 1.9.100 — seven
+  releases: TLS last-root memo, element-level ext entries,
+  namespace-fixup walk gating, **#875 dispatch index fix**,
+  namebp backpointer fix, **#869 `leptris_node_digest` Merkle
+  subtree digest**, streaming emission Phase 1). Three new public
+  symbols attached (audit 264/264):
+  - `leptris_element_serialize_ext[_sized]` (1.9.95, #882):
+    element-level `expand_empty` serialization — wired through
+    `Element#to_xml(expand_empty: true)` for libxml2's
+    `NO_EMPTY_TAGS` parity.
+  - `leptris_node_digest` (1.9.99, #869): content-defined 64-bit
+    Merkle digest of a subtree — wired through `Node#digest(drop_ws:)`
+    with structural-equality semantics.
+
+- **#875 sentinel gate extended**: verified 97/97, 120/120, **500/500**
+  on this build — the 1.9.93 dispatch overflow is gone (the
+  upstream fix used dynamic resize instead of the bare-continue
+  cap; the predicate-pattern index is back to ~25 ms on the
+  120-template fixture — fast and correct).
+- **Vendored `SerializeExtStruct` layout refreshed** to mirror the
+  new C layout (`expand_empty: :int`).
+- **#153 binding fix-forward**: leptris-ruby PR #154 (open,
+  ResultAttr wrap) — the engine needed nothing. The fix will
+  ride a follow-up binding release once it merges.
+
+### Fixed
+
+- **Namebp backpointer validity after QName split** (engine, 1.9.98)
+  — the round-21 mutation backpointer is only valid while `name`
+  points at the carve slot; prefixed names now drop the flag when
+  `#846`'s QName split advances past the colon.
+- **Namespace-fixup walk gating** (engine, 1.9.96): the
+  result-document walks are now gated on `has_namespaces` — the
+  common dispatch shape (no namespaces in the result) is a single
+  flag check.
+- **TLS last-root memo** (engine, 1.9.94): the
+  `leptris_element_get_document` hot path answers consecutive
+  same-tree queries with a single pointer compare.
+
+### Performance
+
+- **Streaming emission Phase 1** (engine, 1.9.100, gated): a
+  compile-time gate admits v1.x namespace-free literal elements,
+  text/value-of, comment/PI, select-only variables, and control
+  flow into direct byte emission — the result DOM is not
+  materialized for those safe shapes. Everything else keeps the
+  result-tree path byte-identically. Run-based emitters, 1306/1306
+  ctest.
+
 ## [1.9.92.2] - 2026-09-07
 
 ### Changed — restructure round (TODO.restructure/01-06, all DONE)

data/CLAUDE.md

@@ -55,6 +55,10 @@ lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
                                 face; namespace= (nil-detach/rebind)
 lib/leptris/xml/result_text.rb — sequence/map/array result items
                                 (values captured at materialization)
+lib/leptris/xml/result_attr.rb  — attribute-node result items
+                                (name/value captured at materialization)
+lib/leptris/xml/iteration_scope.rb — owning context for iterparse
+                                elements (liveness, identity, memos)
 lib/leptris/xml/node_set.rb   — lazy XPath/XQuery results; batch fetch
                                 via get_nodes_ex; ResultText capture
 lib/leptris/xml/searchable.rb — xpath/css/at_*; result materialization

data/README.adoc

@@ -389,6 +389,15 @@ doc.to_xml(indent: 2, indent_text: true)    # display form (documents only)
 `Element#inner_html` serializes the children with correct escaping —
 well-formed by construction (a re-parse spec pins it).
 
+`Element#to_xml(expand_empty: true)` emits `<a></a>` instead of `<a/>`
+for empty elements — libxml2's `XML_SAVE_NO_EMPTY_TAGS` parity.
+
+`Node#digest(drop_ws: false)` answers a content-defined 64-bit Merkle
+hash of the subtree: equal flags and equal digests imply structural
+equivalence (names, namespaces, sorted attributes, document-order
+children); inequality implies nothing — descend and decide. Stable
+across processes; `drop_ws: true` skips whitespace-only text nodes.
+
 XSLT 1.0–3.0 transforms run through `Leptris::XML::XSLT`:
 
 [source,ruby]
@@ -529,7 +538,12 @@ events in bulk with a corruption guard that fails loudly rather than
 delivering garbage. `Leptris::XML::Iterparse.parse(xml, mode:)` yields
 completed subtrees top-level (`:top_level`) or every element post-order
 (`:full_document`) with bounded memory, plus `#namespace_uri` on the last
-yielded element and an `#error` channel for truncated input.
+yielded element and an `#error` channel for truncated input. Yielded
+elements carry an internal lifetime scope: `#document` answers nil (the
+documented contract) while memoization and liveness guards engage —
+using an element after the iteration raises `UseAfterFreeError` instead
+of crashing, and repeated reads within the block ride the same fast
+paths as document-backed nodes.
 
 == Memory model
 

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.9.92"
+LIBLEPTRIS_VERSION = "1.9.105"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/TODO.restructure/07-external-gates.md

@@ -2,11 +2,9 @@
 
 Status: TRACKED
 
-- [ ] **leptris/leptris#875 re-adoption**: when the fix releases,
-      re-pin to `{C}`, un-pend the sentinel spec, re-run the
-      96/97/120 boundary + the 120-template perf fixture as the
-      release gate, ship `{C}.0`. (1.9.93.0/1.9.93.1 yanked;
-      1.9.92.1 is the standing replacement.)
+- [x] **leptris/leptris#875 re-adoption** — DONE in 1.9.100.0
+      (fix landed upstream in 1.9.97; sentinel gate extended to
+      500/500; perf reclaimed).
 - [ ] **utf8proc build decision** (owner): `fn:normalize-unicode`
       requires utf8proc, compiled out of the vendored platform
       builds — enabling it changes the vendored binary surface.

data/TODO.restructure/08-new-code-audit-and-ext-memo.md

@@ -0,0 +1,11 @@
+# 08 — 1.9.100-round code audit + expand_empty ext memo
+
+Status: DONE
+
+- [x] Constraint audit over the 1.9.100 additions (digest,
+      expand_empty): no send/ivar/respond_to?/require violations;
+      autoload set complete.
+- [x] `Serialization.element_xml_expand_empty` allocated a fresh
+      `SerializeExtStruct` per call — memoized to an
+      `EXPAND_EMPTY_EXT` constant, mirroring the `INDENT_TEXT_EXT`
+      discipline (allocation-free steady state).

data/TODO.restructure/09-iteration-scope.md

@@ -0,0 +1,29 @@
+# 09 — IterationScope: lifetime + memoization for iterparse elements (#152)
+
+Status: DONE
+
+Root cause of both #152 findings: `Iterparse#run` wraps yielded
+elements with `document: nil` — so (a) `ensure_alive!` has nothing
+to check (post-free use segfaults instead of raising), and (b)
+every memoized read (`[]`, `attribute_nodes`, …) skips the memo
+machinery entirely (the 10-30x parentless cost: `attribute_nodes`
+re-walks per call, `[]` pays the raw path).
+
+## Change
+
+- [x] New `Leptris::XML::IterationScope` (autoloaded): the owning
+      context for yielded elements — carries the iterator handle
+      as its lifetime anchor (`#c_ptr` goes nil on `#free`, the
+      same signal `ensure_alive!` reads), a `wrapper_cache`
+      (identity for a subtree's wrappers), and a `version` that
+      advances per yield (stale memos on held wrappers invalidate
+      as subtrees are released).
+- [x] `Node#document` answers nil for scope-owned elements — the
+      documented contract ("#document returns nil") is preserved
+      while the internal machinery engages.
+- [x] `Iterparse#free` frees the scope; the block form's ensure
+      chain rides it.
+- [x] Specs: post-iteration use of a held element raises
+      `UseAfterFreeError` (was: VM segfault); repeated
+      `attribute_nodes` inside the block memoizes; children
+      identity holds within a yielded subtree.

data/TODO.restructure/10-cold-attr-read-diet.md

@@ -0,0 +1,19 @@
+# 10 — Cold attribute reads: value-only materialization (#150)
+
+Status: DONE
+
+`Element#[]`'s cold path called `attributes` — building Attr
+wrappers, the name-keyed Attr hash, and the values hash (~17
+allocations for a 2-attribute element) to answer ONE bare-name
+read.
+
+## Change
+
+- [x] `Element#materialize_attr_values`: walks the v1.1.0
+      attribute linked-list face filling ONLY the versioned
+      `@attr_values` memo — no Attr wrappers, no side hashes.
+      `[]`'s cold branch uses it; `attributes`/`attribute_nodes`/
+      `keys`/`values` keep their richer materialization (they
+      answer richer questions).
+- [x] Alloc-count spec: cold `[]` on a 2-attribute element stays
+      under a fixed budget (was ~17 allocs).

data/TODO.restructure/11-construction-factory-diet.md

@@ -0,0 +1,16 @@
+# 11 — Programmatic construction: wrap-fresh factories (#149)
+
+Status: DONE (binding-side diet; structural ceiling documented)
+
+- [x] `Node.wrap_fresh`: one construction authority shared with
+      `wrap` (the type dispatch is not duplicated), skipping the
+      cache LOOKUP only — a freshly created pointer cannot be in
+      the cache, so the lookup was a guaranteed miss on every
+      factory call. Cache STORE still happens (identity survives
+      attach).
+- [x] `Document.create_element/create_text_node/create_comment/
+      create_cdata` route through it.
+- [x] Measured before/after on the issue's bench shape; the
+      remaining gap is per-call FFI marshaling vs a C extension —
+      the structural ceiling of the FFI-only architecture,
+      documented on the issue.

data/TODO.restructure/12-resultattr-merge.md

@@ -0,0 +1,12 @@
+# 12 — #153: merge the ResultAttr wrap (PR #154)
+
+Status: DONE
+
+- [x] Reviewed the diff: autoloads `ResultAttr` per the rule,
+      extends the materialization capture (name+value at result
+      lifetime) symmetric to `ResultText`, no constraint
+      violations.
+- [x] CI 10/10 — merged ahead of this round's branch so the
+      release carries it.
+- [x] Verified `doc.xpath("//item/@id").first.name/.value` on the
+      merged build; #153 closed with the verification.

data/TODO.restructure/13-spec-mece-followup.md

@@ -0,0 +1,9 @@
+# 13 — Spec MECE follow-up for the 1.9.100 specs
+
+Status: DONE
+
+- [x] `Node#digest` spec moved from `xpath_spec.rb` (it is a Node
+      behavior, not a search face) to `seam_and_reads_spec.rb`.
+- [x] `expand_empty` spec moved from `xslt_versions_spec.rb`
+      (serialization option, not an XSLT face) to
+      `document_spec.rb`.

data/TODO.restructure/14-constraint-audit-refresh.md

@@ -0,0 +1,15 @@
+# 14 — Constraint audit refresh over the newest code
+
+Status: DONE
+
+Scope: the parallel-session commits (cold/warm `[]` diet, SAX
+drain) plus the 1.9.100.x rounds and PR #154.
+
+## Findings
+
+- No `send`, no `instance_variable_set/_get`, no
+  `require_relative`; autoload set complete (ResultAttr and
+  IterationScope both registered in `lib/leptris/xml.rb`).
+- Two new `respond_to?(:read)` duck checks crept in with the
+  parallel commits — fixed to the `is_a?(String)` typed branch
+  (same policy as 01): `SAX::Recorder.parse` and `Pull.parse`.

data/TODO.restructure/15-readme-feature-documentation.md

@@ -0,0 +1,10 @@
+# 15 — README: document the three newest features
+
+Status: DONE
+
+- [x] `Node#digest(drop_ws:)` — structural-equality semantics.
+- [x] `Element#to_xml(expand_empty: true)` — libxml2
+      `NO_EMPTY_TAGS` parity.
+- [x] Iterparse lifetime: post-iteration use raises
+      `UseAfterFreeError` (IterationScope); `#document` stays nil;
+      identity holds within a subtree.

data/TODO.restructure/16-claudemd-map-refresh.md

@@ -0,0 +1,5 @@
+# 16 — CLAUDE.md map: iteration_scope.rb + result_attr.rb
+
+Status: DONE
+
+- [x] Both new files in the architecture map with their seams.

data/TODO.restructure/17-perf-drift-record.md

@@ -0,0 +1,12 @@
+# 17 — Perf drift record on the current build
+
+Status: DONE
+
+- [ ] **Blocked on a busy shared host.** The machine has been at
+      load 30–180 for days — every battery attempt this week has
+      been a load-induced fiction (Nokogiri's own baseline swings
+      3× run-to-run on this box, e.g. 16→27→58 ms for parse). The
+      standing baseline from the clean 1.9.76 window still holds:
+      parse 10–12×, serialize 2.9–3.2×, inner_html 4–5×, attr reads
+      6–9×, text 9–11×, element_children walks at parity. Will
+      re-record on the next clean window (load < 15).

data/TODO.restructure/18-audit-spec-doubles-and-gem-contents.md

@@ -0,0 +1,12 @@
+# 18 — Audit: spec doubles + gem contents
+
+Status: DONE
+
+- [x] Spec-double scan: zero RSpec doubles/mocks/`allow(` across
+      spec/ (the two grep hits are XPath `xs:double` casts inside
+      expectation strings). Real documents throughout, per the
+      standing convention.
+- [x] Gem contents: `TODO.restructure/` does NOT ship in the gem
+      (verified by building the gem and listing the tar — 0
+      entries; the gemspec's `git ls-files` reject block covers
+      it).

data/TODO.restructure/19-gitignore-hygiene.md

@@ -0,0 +1,10 @@
+# 19 — .gitignore hygiene for build artifacts
+
+Status: DONE
+
+- [x] `.rspec_status` (RSpec's example-status artifact) ignored —
+      it was showing as untracked noise in every round.
+- [x] `*.gem` was already covered; a stray locally-built gem from
+      this round's contents check removed (one I created; the
+      unrelated `taurus-0.1.0.gem` predates this repo work and was
+      left untouched).

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -233,31 +233,31 @@ class Leptris::XML::Document
   def create_element(name)
     ptr = Leptris::XML::FFI.leptris_element_create(@c_ptr, name)
     raise Leptris::XML::Error, "leptris_element_create failed" if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_ELEMENT)
   end
 
   def create_text_node(content)
     ptr = Leptris::XML::FFI.leptris_text_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_text_node_create failed" if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_TEXT)
   end
 
   def create_comment(content)
     ptr = Leptris::XML::FFI.leptris_comment_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_comment_node_create failed" if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_COMMENT)
   end
 
   def create_cdata(content)
     ptr = Leptris::XML::FFI.leptris_cdata_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_cdata_node_create failed" if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_CDATA)
   end
 
   def create_processing_instruction(target, data = "")
     ptr = Leptris::XML::FFI.leptris_pi_node_create(@c_ptr, target.to_s, data.to_s)
     raise Leptris::XML::Error, "leptris_pi_node_create failed" if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_PI)
   end
 
   def fragment(markup)

data/lib/leptris/xml/element.rb

@@ -42,20 +42,41 @@ class Leptris::XML::Element < Leptris::XML::Node
     # use-after-free. QUALIFIED names (with a colon) go to the
     # engine: they resolve through in-scope declarations, where the
     # written prefix never matters — the hash cannot answer them.
+    #
+    # Cold single-attribute reads (ruby#150): the previous path
+    # materialised EVERY attribute into two hashes on the first
+    # bare read (~17 allocs on a 2-attr element). Now a cold miss
+    # pays ONE FFI call and fills only that name; subsequent
+    # same-name reads hit the hash; a later attributes/keys call
+    # rebuilds the full face. Full-memo (@attributes set) still
+    # answers misses as nil without another FFI.
     name = key.to_s
     if @document && !name.include?(":")
-      # The hottest read in the library: the memo guard is spelled
-      # INLINE rather than through attributes/#memo_hit? — six
-      # method dispatches per read was ~40% of the read cost, and
-      # the external head-to-head (nokogiri's one C call) was
-      # winning on it. Same three-line memo semantics (ADR 0003),
-      # incl. the nil-miss — the hash answers misses too.
       values = @attr_values
-      unless values && @attributes_version == @document.version
-        attributes
-        values = @attr_values
+      if values && @attributes_version == @document.version
+        v = values[name]
+        # Present, or a FULL-memo miss (absent). A partial-memo nil
+        # is ambiguous (un-queried vs absent) — one idempotent
+        # engine call resolves it, then the name is cached.
+        return v if !v.nil? || @attributes
+        ensure_alive!
+        v = Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+        values[name] = v
+        return v
       end
-      return values[name]
+      # Completely cold: one FFI, start a partial values hash.
+      # Drop any full-face memos from a prior version — otherwise a
+      # post-mutation cold [] would stamp the new version onto a
+      # stale @attributes hash and attributes would serve it.
+      ensure_alive!
+      v = Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+      @attr_values = { name => v }
+      @attributes = nil
+      @attribute_nodes = nil
+      @keys = nil
+      @values = nil
+      @attributes_version = @document.version
+      return v
     end
     ensure_alive!
     Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
@@ -141,7 +162,9 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def attributes
-    return @attributes if memo_hit?(@attributes_version)
+    # Require the full Attr-hash face — a cold [] may have set the
+    # version with only a partial @attr_values (ruby#150).
+    return @attributes if @attributes && memo_hit?(@attributes_version)
     result = {}
     values = {}
     each_attribute do |attr|
@@ -357,6 +380,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # comments/CDATA/PIs render their literal forms. The complement
   # of #inner_text, which returns the unescaped text content.
   def inner_html
+    ensure_alive!
     children.map do |child|
       case child
       when Leptris::XML::Element
@@ -379,7 +403,9 @@ class Leptris::XML::Element < Leptris::XML::Node
   # semantics (leptris-ruby#109; via a C-side copy into a fresh
   # document — no element-level ext entry exists yet). true is NOT
   # supported here: the display form is document-level.
-  def to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false)
+  def to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false,
+              expand_empty: false)
+    ensure_alive!
     if indent_text == true
       raise ArgumentError,
         "indent_text: true (display form) is document-level — " \
@@ -387,6 +413,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     return Leptris::XML::Serialization.to_xml_element_unit(
       self, indent_text, indent: indent) if indent_text.is_a?(String)
+    return Leptris::XML::Serialization.element_xml_expand_empty(@c_ptr) if expand_empty
     Leptris::XML::Serialization.to_xml(
       Leptris::XML::Serialization::ELEMENT_SERIALIZE_INTO, @c_ptr,
       indent: indent, no_decl: no_decl, encoding: encoding)

data/lib/leptris/xml/ffi.rb

@@ -79,7 +79,8 @@ module Leptris
       # entry.
       class SerializeExtStruct < ::FFI::Struct
         layout :indent_text, :int,
-               :indent_unit, :pointer
+               :indent_unit, :pointer,
+               :expand_empty, :int
       end
 
       # Mirrors LeptrisParseOptions (libleptris >= 1.9.0 carries the
@@ -141,6 +142,15 @@ module Leptris
       # the parse; only an entirely empty result is an error.
       attach_function :leptris_parse_html_string,
         [:string, :size_t, :pointer], :leptris_document
+      # HTML4/libxml2-compatibility mode (1.9.104, #659): the same
+      # tolerant tokenizer and Nokogiri document shape, except
+      # leading script/style stay in <body> (libxml2's shape —
+      # title/meta/link/base still lift). Bindings matching
+      # Nokogiri byte-for-byte pin this; _html_string is the
+      # WHATWG-conformant engine (implied-head full set, foster
+      # parenting from 1.9.105).
+      attach_function :leptris_parse_html4_string,
+        [:string, :size_t, :pointer], :leptris_document
 
 attach_function :leptris_parse_string,
         [:string, :size_t, :pointer], :leptris_document
@@ -681,6 +691,22 @@ attach_function :leptris_parse_string,
         [:leptris_document, :pointer, :size_t, :pointer, :pointer], :size_t
       attach_function :leptris_document_get_dtd,
         [:leptris_document], :pointer
+      # Element-level ext serialization (libleptris 1.9.95, #882):
+      # the document ext option surface (indent_text, indent_unit,
+      # expand_empty) at element level. The sized twin is the
+      # FFI-safe form (older ext allocations read within bounds).
+      attach_function :leptris_element_serialize_ext,
+        [:leptris_element, :pointer, :pointer], :pointer
+      attach_function :leptris_element_serialize_ext_sized,
+        [:leptris_element, :pointer, :pointer, :size_t], :pointer
+
+      # Content-defined Merkle digest of a subtree (libleptris
+      # 1.9.99, #869): equal flags + equal digests imply structural
+      # equivalence (descend to decide on inequality); flags bit 1
+      # (DROP_WS_TEXT) skips whitespace-only text nodes.
+      attach_function :leptris_node_digest,
+        [:leptris_node_ref, :int], :uint64
+
       attach_function :leptris_element_serialize,
         [:leptris_element, :pointer], :pointer
       attach_function :leptris_element_serialize_into,

data/lib/leptris/xml/iteration_scope.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# The owning context for elements yielded by an Iterparse run —
+# the lifetime and memoization authority that a Document is for
+# parsed trees, scoped to one iteration:
+#
+# - `#c_ptr` carries the iterator handle and goes nil on `#free` —
+#   the same signal `Node#ensure_alive!` reads, so using a held
+#   element after the iterator frees RAISES UseAfterFreeError
+#   instead of segfaulting (ruby#152).
+# - `#wrapper_cache` gives wrapper identity within a yielded
+#   subtree (children() twice returns the same wrappers).
+# - `#version` advances per yield and on mutation — stale memos on
+#   held wrappers invalidate as subtrees are released.
+#
+# `Node#document` answers nil for scope-owned elements (the
+# documented iterparse contract) while the internal machinery
+# engages — including the fast bare-name attribute path, which is
+# what makes iterparse attribute reads match document-backed cost.
+class Leptris::XML::IterationScope
+  def initialize(iterator_handle)
+    @c_ptr = iterator_handle
+    @wrapper_cache = {}
+    @version = 0
+  end
+
+  attr_reader :c_ptr, :wrapper_cache
+
+  def version
+    @version
+  end
+
+  def advance_version
+    @version += 1
+  end
+
+  def readonly?
+    false
+  end
+
+  # Called by the owning Iterparse when it frees the C iterator —
+  # every wrapper it handed out fails liveness from here on.
+  def mark_freed
+    @c_ptr = nil
+  end
+
+  # Called before each yield: the previous subtree is released and
+  # its pool memory recycled — a fresh element may land at a cached
+  # address, so the identity cache and the memo version both reset.
+  def new_subtree!
+    @wrapper_cache = {}
+    @version += 1
+  end
+end

data/lib/leptris/xml/iterparse.rb

@@ -29,8 +29,10 @@ require "ffi"
 #     # => nil, or the parse failure (readable after the run: the
 #     #    block form frees the iterator on return, snapshotting it)
 #
-# The yielded elements have no parent Document; #document returns
-# nil and they must not outlive the iteration.
+# The yielded elements are owned by an internal IterationScope:
+# #document returns nil (the documented contract) while liveness
+# guards and memoization engage — using an element after the
+# iterator frees raises UseAfterFreeError instead of crashing.
 class Leptris::XML::Iterparse
   MODES = {
     top_level: Leptris::XML::FFI::ITERPARSE_TOP_LEVEL,
@@ -76,6 +78,7 @@ class Leptris::XML::Iterparse
   def initialize(handle)
     raise Leptris::XML::ParseError, "leptris_iterparse_new failed" if handle.null?
     @handle = handle
+    @scope = Leptris::XML::IterationScope.new(handle)
   end
 
   # Yields completed elements until the document is exhausted or the
@@ -86,10 +89,15 @@ class Leptris::XML::Iterparse
     while @handle
       ptr = Leptris::XML::FFI.leptris_iterparse_next(@handle)
       break if ptr.null?
-      # document: nil — the subtree belongs to the iterator's pool,
-      # not a long-lived Document, so wrapper caching is skipped and
-      # #document is nil on the yielded elements.
-      yield Leptris::XML::Node.wrap(ptr, nil)
+      # The scope owns lifetime + memoization for yielded elements
+      # (ruby#152): liveness guards engage (post-free use raises
+      # instead of segfaulting), wrapper identity holds within a
+      # subtree, and memoized reads match document-backed cost.
+      # Each yield starts a fresh subtree — the released pool
+      # memory is recycled, so the identity cache resets with the
+      # memo version. #document still answers nil on the elements.
+      @scope.new_subtree!
+      yield Leptris::XML::Node.wrap(ptr, @scope)
     end
     self
   end
@@ -124,6 +132,7 @@ class Leptris::XML::Iterparse
     @last_error = live_error
     Leptris::XML::FFI.leptris_iterparse_free(@handle)
     @handle = nil
+    @scope.mark_freed
   end
 
   private

data/lib/leptris/xml/node.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 class Leptris::XML::Node
-  attr_reader :c_ptr, :document
+  attr_reader :c_ptr
+
+  # Iterparse-yielded elements are owned by an IterationScope (the
+  # internal lifetime/memoization authority) — the public #document
+  # answers nil for them, per the documented contract.
+  def document
+    scope_owned? ? nil : @document
+  end
 
   def initialize(c_ptr, document, parent: nil, node_type: nil)
     @c_ptr = c_ptr
@@ -12,9 +19,28 @@ class Leptris::XML::Node
     @node_type = node_type
   end
 
+  # True when this node's owning context is an IterationScope
+  # (iterparse-yielded) rather than a Document.
+  def scope_owned?
+    @document.is_a?(Leptris::XML::IterationScope)
+  end
+  private :scope_owned?
+
   # node_type: callers holding a batch-fetched kind (the XPath
   # result-set batch fills out_kinds) pass it so the wrap skips the
   # get_type dispatch; nil (the default) dispatches as before.
+  # Factory variant: the pointer was JUST created by the engine,
+  # so the cache lookup is a guaranteed miss — skip straight to
+  # construction and store (identity still survives attach).
+  def self.wrap_fresh(c_ptr, document, node_type)
+    node = construct(c_ptr, document, nil, node_type, nil)
+    if document
+      cache = document.wrapper_cache
+      cache[c_ptr.address] = node
+    end
+    node
+  end
+
   def self.wrap(c_ptr, document, parent: nil, node_type: nil, result_value: nil)
     # Per-document weak-ref cache. Returns the existing wrapper when the
     # same c_ptr is wrapped twice (common in children/sibling walks,
@@ -31,31 +57,46 @@ class Leptris::XML::Node
     end
 
     node_type ||= Leptris::XML::FFI.leptris_node_get_type(c_ptr)
-    node =
-      case node_type
-      when Leptris::XML::FFI::NODE_ELEMENT
-        Leptris::XML::Element.new(c_ptr, document, parent: parent, node_type: node_type)
-      when Leptris::XML::FFI::NODE_TEXT
-        Leptris::XML::Text.new(c_ptr, document, parent: parent, node_type: node_type)
-      when Leptris::XML::FFI::NODE_SYNTHETIC_TEXT
-        # Sequence/map/array items: value captured by the NodeSet at
-        # materialization (only the result handle can read them).
-        Leptris::XML::ResultText.new(
-          c_ptr, document, result_value, parent: parent, node_type: node_type)
-      when Leptris::XML::FFI::NODE_COMMENT
-        Leptris::XML::Comment.new(c_ptr, document, parent: parent, node_type: node_type)
-      when Leptris::XML::FFI::NODE_CDATA
-        Leptris::XML::CDATA.new(c_ptr, document, parent: parent, node_type: node_type)
-      when Leptris::XML::FFI::NODE_PI
-        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent, node_type: node_type)
-      else
-        new(c_ptr, document, parent: parent, node_type: node_type)
-      end
+    node = construct(c_ptr, document, parent, node_type, result_value)
 
     cache[address] = node if document
     node
   end
 
+  # The single type-dispatch construction authority shared by wrap
+  # (cache-checked) and wrap_fresh (factory path).
+  def self.construct(c_ptr, document, parent, node_type, result_value)
+    case node_type
+    when Leptris::XML::FFI::NODE_ELEMENT
+      Leptris::XML::Element.new(c_ptr, document, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_TEXT
+      Leptris::XML::Text.new(c_ptr, document, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_SYNTHETIC_TEXT
+      # Sequence/map/array items: value captured by the NodeSet at
+      # materialization (only the result handle can read them).
+      Leptris::XML::ResultText.new(
+        c_ptr, document, result_value, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_ATTRIBUTE
+      # ruby#153: synthetic attribute result nodes carry their
+      # name/value in the result handle — the NodeSet captures
+      # them at materialization (result_value is a {name:, value:}
+      # hash; the single-node seam captures the same way).
+      rv = result_value || {}
+      Leptris::XML::ResultAttr.new(
+        c_ptr, document, rv[:name], rv[:value],
+        parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_COMMENT
+      Leptris::XML::Comment.new(c_ptr, document, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_CDATA
+      Leptris::XML::CDATA.new(c_ptr, document, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_PI
+      Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent, node_type: node_type)
+    else
+      new(c_ptr, document, parent: parent, node_type: node_type)
+    end
+  end
+  private_class_method :construct
+
   def name
     raise NotImplementedError, "#{self.class}#name not implemented"
   end
@@ -83,6 +124,19 @@ class Leptris::XML::Node
   alias_method :node_type, :type
 
   def element?;  type == Leptris::XML::FFI::NODE_ELEMENT;  end
+
+  # Content-defined 64-bit Merkle digest of this subtree
+  # (libleptris 1.9.99, #869): element name/prefix/resolved
+  # namespace URI, attributes sorted and first-wins-deduplicated,
+  # children hashed in document order — no addresses participate,
+  # so equal trees hash equal across processes. Equality implies
+  # subtree equivalence; inequality implies nothing (descend).
+  # +drop_ws+ skips whitespace-only text nodes.
+  def digest(drop_ws: false)
+    ensure_alive!
+    Leptris::XML::FFI.leptris_node_digest(
+      @c_ptr, drop_ws ? 1 : 0)
+  end
   def text?;     type == Leptris::XML::FFI::NODE_TEXT;     end
   def comment?;  type == Leptris::XML::FFI::NODE_COMMENT;  end
   def cdata?;    type == Leptris::XML::FFI::NODE_CDATA;    end

data/lib/leptris/xml/node_set.rb

@@ -72,8 +72,17 @@ class Leptris::XML::NodeSet
   # Sequence/map/array items ride synthetic text nodes whose value
   # only the live result handle can serve — capture it now.
   def text_item_value(kind, index)
-    return nil unless kind == Leptris::XML::FFI::XPATH_NODE_TEXT
-    Leptris::XML::FFI.leptris_xpath_result_node_value(@result_ptr, index)
+    case kind
+    when Leptris::XML::FFI::XPATH_NODE_TEXT
+      Leptris::XML::FFI.leptris_xpath_result_node_value(@result_ptr, index)
+    when Leptris::XML::FFI::XPATH_NODE_ATTRIBUTE
+      # ruby#153: capture both faces — only the live result handle
+      # can serve an attribute node's name and value.
+      {
+        name: Leptris::XML::FFI.leptris_xpath_result_node_name(@result_ptr, index),
+        value: Leptris::XML::FFI.leptris_xpath_result_node_value(@result_ptr, index)
+      }
+    end
   end
   private :text_item_value
 

data/lib/leptris/xml/pull.rb

@@ -39,7 +39,7 @@ module Leptris::XML::Pull
 
   class Parser
     def self.parse(xml_or_io)
-      xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+      xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
       new(Leptris::XML::FFI.leptris_pull_new(xml, xml.bytesize))
     end
 

data/lib/leptris/xml/result_attr.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Attribute-kind item from an XPath result set (ruby#153): the
+# engine exposes synthetic attribute nodes whose name and value are
+# readable only through the live result handle — the NodeSet
+# captures both at materialization time and hands them to this
+# wrapper, so the faces stay usable after the result is freed.
+#
+#     doc.xpath("//item/@id").first.name  # => "id"
+#     doc.xpath("//item/@id").first.value # => "1"
+#
+class Leptris::XML::ResultAttr < Leptris::XML::Node
+  def initialize(c_ptr, document, name, value, parent: nil, node_type: nil)
+    super(c_ptr, document, parent: parent, node_type: node_type)
+    @attr_name = name
+    @attr_value = value
+  end
+
+  def name
+    @attr_name
+  end
+
+  # Nokogiri's Attr#value is the attribute's string value.
+  def value
+    @attr_value
+  end
+
+  def content
+    @attr_value
+  end
+
+  def to_s
+    @attr_value
+  end
+
+  def attribute?
+    true
+  end
+end

data/lib/leptris/xml/sax/parser.rb

@@ -51,7 +51,12 @@ class Leptris::XML::SAX::Parser
   end
 
   def parse_memory(string)
-    string = string.dup.force_encoding("UTF-8")
+    # Only re-encode when the input is not already UTF-8 — a
+    # dup+force_encoding on a multi-MB document is a full copy
+    # before any parse work starts.
+    unless string.encoding == Encoding::UTF_8 && string.valid_encoding?
+      string = string.dup.force_encoding(Encoding::UTF_8)
+    end
     unless @streaming
       Leptris::XML::SAX::DomDispatch.parse(
         @document, dispatched_kinds, string)

data/lib/leptris/xml/sax/recorder.rb

@@ -48,7 +48,7 @@ class Leptris::XML::SAX::Recorder
   def self.parse(xml_or_io, kinds: nil)
     recorder = open
     begin
-      if xml_or_io.respond_to?(:read)
+      unless xml_or_io.is_a?(String)
         recorder.feed_stream(xml_or_io, kinds: kinds) { |*args| yield(*args) }
       else
         recorder.feed(xml_or_io.to_s, final: true)
@@ -84,7 +84,9 @@ class Leptris::XML::SAX::Recorder
   # Feed one chunk; records/arena reset at feed entry, so drain
   # after every feed. Returns self.
   def feed(chunk, final: false)
-    chunk = chunk.dup.force_encoding(Encoding::UTF_8)
+    unless chunk.encoding == Encoding::UTF_8 && chunk.valid_encoding?
+      chunk = chunk.dup.force_encoding(Encoding::UTF_8)
+    end
     rc = Leptris::XML::FFI.leptris_sax_recorder_feed(
       @handle, chunk, chunk.bytesize, final ? 1 : 0)
     rc
@@ -157,13 +159,15 @@ class Leptris::XML::SAX::Recorder
         @handle, len_ptr)
       arena = arena_ptr.read_bytes(len_ptr.read_uint64)
       count = count_ptr.read_uint64
-      records = records_ptr.read_bytes(count * RECORD_STRIDE)
-      kinds = records.unpack(KIND_TEMPLATE_FOR[count])
-
+      # Kind is the first byte of each record — read it off the C
+      # pointer. The previous path copied every record into Ruby
+      # and unpacked a Fixnum array just for the kind strip
+      # (2.25M Integers on a single-feed drain); one get_uint8 per
+      # event replaces both.
       one_arg_start = dispatched[:start_element] == :one_arg
       i = 0
       while i < count
-        code = kinds[i]
+        code = records_ptr.get_uint8(i * RECORD_STRIDE)
         kind = KIND_BY_CODE[code]
         if kind && dispatched[kind]
           base = i * RECORD_STRIDE
@@ -275,21 +279,16 @@ class Leptris::XML::SAX::Recorder
       arena = arena_ptr.read_bytes(len_ptr.read_uint64)
       count = count_ptr.read_uint64
 
-      # Two-level drain: ONE bulk read + kind-strip unpack decides
-      # which records to touch, then each yielded event's fields are
-      # read individually (get_uint32 at layout offsets) — an
-      # unwanted record costs one strip read, an unused FIELD costs
-      # nothing, and no per-chunk field array is ever built.
-      records = records_ptr.read_bytes(count * RECORD_STRIDE)
-      kinds = records.unpack(KIND_TEMPLATE_FOR[count])
-
+      # Kind is the first byte of each record — read off the C
+      # pointer. The previous path copied every record and unpacked
+      # a Fixnum array just for the kind strip.
       has_name = HAS_NAME
       has_text = HAS_TEXT
       drain = wanted.nil?
       i = 0
       while i < count
-        code = kinds[i]
         base = i * RECORD_STRIDE
+        code = records_ptr.get_uint8(base)
         if code == SAX_EVENT_CHARACTERS_CODE && drain
           # The dominant branch (text-heavy documents): no name, no
           # attrs, no per-kind gate lookups — kind, text, position.

data/lib/leptris/xml/searchable.rb

@@ -122,7 +122,19 @@ module Leptris::XML::Searchable
     type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
     if type == Leptris::XML::FFI::XPATH_NODESET
       ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(result_ptr, 0)
-      node = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, document)
+      if ptr.null?
+        node = nil
+      else
+        kind = Leptris::XML::FFI.leptris_xpath_result_node_kind(result_ptr, 0)
+        node = if kind == Leptris::XML::FFI::XPATH_NODE_ATTRIBUTE
+                 Leptris::XML::ResultAttr.new(
+                   ptr, document,
+                   Leptris::XML::FFI.leptris_xpath_result_node_name(result_ptr, 0),
+                   Leptris::XML::FFI.leptris_xpath_result_node_value(result_ptr, 0))
+               else
+                 Leptris::XML::Node.wrap(ptr, document)
+               end
+      end
       Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
       node
     else

data/lib/leptris/xml/serialization.rb

@@ -51,6 +51,26 @@ module Leptris::XML::Serialization
       ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)
   end
 
+  # Element serialization with expand_empty (libleptris 1.9.95,
+  # #882): empty elements emit <a></a> instead of <a/> — the
+  # inverse of libxml2's XML_SAVE_NO_EMPTY, through the element
+  # ext entry (the sized form keeps older ext allocations safe).
+  EXPAND_EMPTY_EXT = begin
+    ext = Leptris::XML::FFI::SerializeExtStruct.new
+    ext[:indent_text] = 0
+    ext[:indent_unit] = nil
+    ext[:expand_empty] = 1
+    ext
+  end
+  private_constant :EXPAND_EMPTY_EXT
+
+  def self.element_xml_expand_empty(c_ptr)
+    str_ptr = Leptris::XML::FFI.leptris_element_serialize_ext_sized(
+      c_ptr, DEFAULT_OPTIONS.pointer,
+      EXPAND_EMPTY_EXT.pointer, EXPAND_EMPTY_EXT.size)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
   # Display-form document serialization (libleptris 1.9.9, #129):
   # the ext struct's indent_text hands ALL whitespace to the
   # formatter — text and mixed content indent too. Display-oriented:

data/lib/leptris/xml.rb

@@ -23,7 +23,9 @@ module Leptris
     autoload :SAX, "leptris/xml/sax"
     autoload :XPath, "leptris/xml/xpath"
     autoload :EvaluationContext, "leptris/xml/evaluation_context"
+    autoload :IterationScope, "leptris/xml/iteration_scope"
     autoload :ResultText, "leptris/xml/result_text"
+    autoload :ResultAttr, "leptris/xml/result_attr"
     autoload :XSLT, "leptris/xml/xslt"
     autoload :XQuery, "leptris/xml/xquery"
     autoload :Pull, "leptris/xml/pull"
@@ -46,17 +48,32 @@ module Leptris
         string, string.bytesize) != 0
     end
 
-    # Tolerant HTML4/5 parse into a standard Document (libleptris
+    # Tolerant HTML parse into a standard Document (libleptris
     # 1.9.75): implied end tags, void elements, raw-text script and
     # style, lowercased names, minimized/unquoted attributes, and
-    # the HTML named entities. Document shape — html/head/body are
-    # synthesized (Nokogiri::HTML parity), but NO implied tbody.
-    # Malformed input degrades to text rather than raising; only an
-    # entirely empty result is an error.
-    def self.parse_html(html)
+    # the HTML named entities. html/head/body are synthesized; no
+    # implied tbody. Malformed input degrades to text rather than
+    # raising; only an entirely empty result is an error.
+    #
+    # MODES (libleptris 1.9.104, #659): :html4 (the default) pins
+    # the libxml2/Nokogiri compatibility shape — leading
+    # script/style stay in <body>, title/meta/link/base still lift
+    # — so byte-parity with Nokogiri::HTML holds. :whatwg selects
+    # the conformant engine: the full implied-<head> set
+    # (script/style/noscript/template/... lift) and foster
+    # parenting (1.9.105) — html5lib corpus 294/1555 vs Nokogiri's
+    # 372; the shapes genuinely differ by spec.
+    def self.parse_html(html, mode: :html4)
       html = html.to_s
-      raw = Leptris::XML::FFI.leptris_parse_html_string(
-        html, html.bytesize, nil)
+      entry =
+        case mode
+        when :html4 then Leptris::XML::FFI.method(:leptris_parse_html4_string)
+        when :whatwg then Leptris::XML::FFI.method(:leptris_parse_html_string)
+        else
+          raise ArgumentError,
+            "mode must be :html4 or :whatwg, got #{mode.inspect}"
+        end
+      raw = entry.call(html, html.bytesize, nil)
       if raw.null?
         raise Leptris::XML::ParseError,
           "HTML parse failed: #{Leptris::XML::FFI.leptris_last_error}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.92.2
+  version: 1.9.105.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -76,6 +76,18 @@ files:
 - TODO.restructure/05-memory-documentation.md
 - TODO.restructure/06-architecture-map-refresh.md
 - TODO.restructure/07-external-gates.md
+- TODO.restructure/08-new-code-audit-and-ext-memo.md
+- TODO.restructure/09-iteration-scope.md
+- TODO.restructure/10-cold-attr-read-diet.md
+- TODO.restructure/11-construction-factory-diet.md
+- TODO.restructure/12-resultattr-merge.md
+- TODO.restructure/13-spec-mece-followup.md
+- TODO.restructure/14-constraint-audit-refresh.md
+- TODO.restructure/15-readme-feature-documentation.md
+- TODO.restructure/16-claudemd-map-refresh.md
+- TODO.restructure/17-perf-drift-record.md
+- TODO.restructure/18-audit-spec-doubles-and-gem-contents.md
+- TODO.restructure/19-gitignore-hygiene.md
 - docs/adr/0001-lockstep-mirror.md
 - docs/adr/0002-utf8-at-the-seam.md
 - docs/adr/0003-readonly-memoization-pattern.md
@@ -97,6 +109,7 @@ files:
 - lib/leptris/xml/element.rb
 - lib/leptris/xml/evaluation_context.rb
 - lib/leptris/xml/ffi.rb
+- lib/leptris/xml/iteration_scope.rb
 - lib/leptris/xml/iterparse.rb
 - lib/leptris/xml/namespace.rb
 - lib/leptris/xml/node.rb
@@ -104,6 +117,7 @@ files:
 - lib/leptris/xml/parse_options.rb
 - lib/leptris/xml/processing_instruction.rb
 - lib/leptris/xml/pull.rb
+- lib/leptris/xml/result_attr.rb
 - lib/leptris/xml/result_text.rb
 - lib/leptris/xml/sax.rb
 - lib/leptris/xml/sax/document.rb