leptris 1.9.201.4 → 1.9.204.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 230f192458c26ad52475b9ef659644858d264777896cc197482205ac32972a01
-  data.tar.gz: 2013be07ce60da7b35b5564b6d18b3905dd7809d08acabb2780211323a6f6781
+  metadata.gz: 0facebf2d44046c5a2c7ddaca5fdc8d2b5aea2b92017f6f1de8844122ec0eda4
+  data.tar.gz: f0f09d7786bd551d6f7077e1112e499ad25d6236a379d10607f59aeb2ddef02e
 SHA512:
-  metadata.gz: 979d1f1a2e9d5815a6502c1990e171ff6e0e1df90751121bf96eacab517f7510b0eb30efca09e848fb3ab4c27e33fba4f2fbcf3f977811a786b766a23fa58545
-  data.tar.gz: 3df36dfd59e33291acad1ad240541d12d2f1fb0cd7a4e4590ff1bf7569e30ce6b639fbbc6aaffc469bf49716dc914c9d5ef42dafada61da49c0f408711ed2949
+  metadata.gz: cbb0f3100ba9c705da214daafe066dcdbd973e41abb08d04e4b6db69a18091976b0083e223c9e888829fc46e5b6c4fe49ddf7d3defa380e62631fdc2d3897f7b
+  data.tar.gz: e11a0141773522b79b5ddc5217aa706b1ef01517e8981924842e0f1b7d272499601b3723d6df23c2741dea1e5e5733818a8b743a67af19b63be0f4ce9a554c10

data/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.204.0] - 2026-09-19
+
+### Added — document-level mutation completed: #1229 (the 1.9.204 surface)
+
+- **`Document#clear_declaration`** — un-sets the XML declaration
+  (clears version/encoding and the standalone marker); the
+  document serializes exactly as if the input had none.
+  Idempotent; returns self.
+- **`Document#remove_doctype`** — un-sets the DOCTYPE; it leaves
+  the child chain and the serializer's view while the DocType
+  stays pool-owned and readable (`doc.doctype.name` et al.) until
+  `#free`. Returns true when removed, false when the document had
+  none. Rounds out the write-half next to `#set_doctype` /
+  `doc.doctype` (the read/create faces wired earlier).
+- Completes upstream leptris/leptris#1229 and, with it, the
+  leptris-ruby#275 umbrella (PI removal 1.9.9, declaration clear +
+  DOCTYPE unset 1.9.204). Spec battery in
+  `document_construction_spec.rb`.
+- Engine adoption: 1.9.203 (`leptris_dtd_parse` honors the
+  NULL-on-error contract, upstream #1211) and 1.9.204 (html.h
+  subsystem header, one-shot name fast paths, one-call buffer-mode
+  pull feeds). #1229's two exports are wired as the
+  `Document#clear_declaration` / `#remove_doctype` faces; the
+  other two 1.9.204 exports attach for lockstep parity
+  (`leptris_sax_parser_set_one_shot` — the binding's one-shot SAX
+  entry is one-shot by construction and pull's memory source sets
+  it engine-side; `leptris_alloc_buffer` — engine-heap allocation
+  for callback-owned buffers like the DTD PE loader, released via
+  the already-bound `leptris_free_string`). Audit 333/333.
+
+### Fixed — portability (audit:symbols + POWER vendor mapping)
+
+- `nm -gU` → `nm -g`: GNU binutils nm (Debian bookworm 2.40)
+  accepts `-U` but then ignores the file operand entirely
+  (`nm: 'a.out': No such file`, empty export list, guaranteed
+  false drift). Undefined externals print two columns, so the
+  existing `split[2]` + `compact` already skips them on every nm
+  flavor. The engine build itself succeeded on ppc64le this round
+  — #1196's LTO crash did not reproduce.
+- `vendor_platforms_for` normalizes RbConfig's `powerpc64le` to
+  the gem-tier spelling `ppc64le`: the JVM-host rebuild ("java" →
+  host cpu-os) matched no tier on POWER hosts, so JRuby/
+  TruffleRuby there missed their vendored binary. Surfaced by the
+  ppc64le qemu leg (ffi_spec:223) once the audit fix let the suite
+  run; the spec now asserts JVM ≡ host tier.
+
+### Not fixed despite upstream closes
+
+- **Iterparse attribute reads: all-nil runs on ubuntu-latest Ruby
+  3.4 CI legs** — filed upstream as leptris/leptris#1242
+  (leptris-ruby#279 tracks the investigation). Six strikes; the
+  last three were consecutive reruns of one job, suggesting
+  per-machine determinism. Unreproducible across ~75k local reads
+  on darwin/arm64 (native + FFI, GC.stress) and x86_64 linux
+  (qemu; native + FFI; threaded and not). The leg sets
+  `LEPTRIS_SKIP_1242=1` to quarantine exactly that one spec on
+  that one leg until the engine ships the fix; every other leg
+  keeps the full guard.
+
+- **#1220 reopened with the 1.9.203 repro**: HTML-document
+  mutations are still lost on serialization (the exact original
+  repro stands; node reads back mutated, serializer sees the old
+  tree). Tracking continues upstream.
+- **#1197 reopened with fresh 1.9.203 evidence**: the s390x qemu
+  leg failed 442/742 with the identical `malformed input`
+  signature at ASCII offsets; the reopen quotes the close
+  comment's own terms. (1.9.204's notes carry no BE fix; the leg
+  stays experimental until the engine ships one.)
+
 ## [1.9.201.3] - 2026-09-19
 
 ### Added — the HTML facade (Nokogiri-shaped entry points)

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.201"
+LIBLEPTRIS_VERSION = "1.9.204"
 # Vendored alongside libleptris for fn:normalize-unicode (TODO
 # .restructure/20): built per platform with a RELOCATABLE @rpath
 # install name, loaded by ffi.rb before libleptris so the
@@ -326,7 +326,13 @@ namespace :audit do
     unless lib
       abort "audit:symbols: vendored library not found — run rake compile"
     end
-    exported = `nm -gU #{lib}`
+    # Plain -g, not -U: GNU binutils nm (Debian bookworm 2.40)
+    # accepts -U but then ignores the file operand entirely
+    # ("nm: 'a.out': No such file", empty export list, guaranteed
+    # false drift — the ppc64le leg). Undefined externals print two
+    # columns (type, name), so split[2] is nil for them and the
+    # compact below already drops them on every nm flavor.
+    exported = `nm -g #{lib}`
       .lines.map { |l| l.split[2] }.compact
       .map { |n| n.sub(/\A_/, "") }
       .select { |n| n.start_with?("leptris_") }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -635,6 +635,31 @@ class Leptris::XML::Document
     Leptris::XML::DocType.new(dt, self)
   end
 
+  # Un-set the XML declaration (libleptris 1.9.204, upstream
+  # #1229): the document stops being declaration-bearing and
+  # serialization emits none — exactly as if the input had none.
+  # Clears version/encoding and the standalone marker. Idempotent.
+  # Returns self.
+  def clear_declaration
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_clear_declaration(c_ptr))
+    @version += 1
+    self
+  end
+
+  # Un-set the document's DOCTYPE (libleptris 1.9.204, upstream
+  # #1229). The DocType stays pool-owned and readable via #doctype
+  # until #free; it leaves the child chain and the serializer's
+  # view. Returns true when removed, false when the document had
+  # none.
+  def remove_doctype
+    rc = Leptris::XML::FFI.leptris_document_remove_doctype(c_ptr)
+    return false if rc == Leptris::XML::FFI::LEPTRIS_ERROR_NOT_FOUND
+    Leptris::XML::FFI.check_status(rc)
+    @version += 1
+    true
+  end
+
   # Append a document-level comment (epilog position, after the
   # root element) — the add_pi twin (libleptris 1.9.160, #1032;
   # parsed document-level comments round-tripped since 1.9.3/#578,

data/lib/leptris/xml/dtd.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris::XML
+  # DTD validation (the libleptris 1.9.202-exported surface, the
+  # leptris validate --dtd CLI's library face): parse an internal
+  # subset, optionally merge an external subset (the application
+  # owns I/O — read the resource named by the DOCTYPE system id
+  # and hand the bytes over), then validate any number of documents.
+  # The RelaxNG shape: parse once, validate many; errors carry
+  # message/element/line/column.
+  #
+  #     dtd = Leptris::XML::DTD.parse(<<~DTD)
+  #       <!ELEMENT book (title, author+)>
+  #       <!ATTLIST book id ID #REQUIRED>
+  #     DTD
+  #     dtd.valid?(doc)
+  #     dtd.validate(doc)  # => [{message:, element:, line:, column:}]
+  #
+  module DTD
+    module_function
+
+    def parse(dtd_content)
+      DTDHandle.parse(dtd_content)
+    end
+
+    # The document's own internal subset (from its DOCTYPE), as a
+    # validatable handle: document-owned, never freed by the caller.
+    # Extend it with an external subset via #merge_external_subset.
+    def from_document(document)
+      DTDHandle.wrap_owned(
+        Leptris::XML::FFI.leptris_document_get_dtd(document.c_ptr))
+    end
+
+    # One struct-free convenience: validate +first_error. Returns
+    # nil when valid.
+    def first_error(document, dtd_content)
+      DTDHandle.parse(dtd_content).first_error(document)
+    end
+
+    class DTDHandle
+      def self.parse(dtd_content)
+        content = dtd_content.to_s
+        raw = Leptris::XML::FFI.leptris_dtd_parse(
+          content, content.bytesize)
+        if raw.null?
+          raise Leptris::XML::Error,
+            "DTD parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+        end
+        new(OwnedHandle.new(raw))
+      end
+
+      def self.wrap_owned(ptr)
+        new(nil, ptr)
+      end
+
+      class OwnedHandle < ::FFI::AutoPointer
+        def self.release(ptr)
+          Leptris::XML::FFI.leptris_dtd_free(ptr)
+        end
+      end
+
+      def initialize(owned, doc_owned_ptr = nil)
+        @owned = owned
+        @ptr = doc_owned_ptr || owned
+      end
+
+      def c_ptr
+        @ptr
+      end
+
+      # Merge an external subset (the application reads the resource;
+      # the library never does I/O). First declaration of a name wins,
+      # so the internal subset is never overridden.
+      def merge_external_subset(content)
+        c = content.to_s
+        rc = Leptris::XML::FFI.leptris_dtd_parse_external_subset(
+          c_ptr, c, c.bytesize)
+        raise Leptris::XML::Error, "external subset merge failed" if rc.negative?
+        self
+      end
+
+      def valid?(document)
+        validate(document).empty?
+      end
+
+      # [{ message:, element:, line:, column: }] — empty when valid.
+      def validate(document)
+        err = Leptris::XML::FFI::DTDErrorStruct.new
+        rc = Leptris::XML::FFI.leptris_dtd_validate(
+          document.c_ptr, c_ptr, err)
+        return [] if rc == 1
+        return [{ message: "internal validation error" }] if rc.negative?
+        message = err[:message]
+        return [{ message: "validation failed" }] if message.nil?
+        [{
+          message: message,
+          element: err[:element_name],
+          line: err[:line],
+          column: err[:column],
+        }]
+      ensure
+        Leptris::XML::FFI.leptris_dtd_error_free(err) unless rc == 1
+      end
+
+      # nil when valid — the single-error convenience.
+      def first_error(document)
+        validate(document).first
+      end
+    end
+  end
+end

data/lib/leptris/xml/ffi.rb

@@ -26,6 +26,9 @@ module Leptris
           end
           cpu = RbConfig::CONFIG["host_cpu"].to_s
           cpu = "aarch64" if cpu.empty?
+          # RbConfig says "powerpc64le"; the gem/vendor tier is
+          # "ppc64le-linux" (the gem platform spelling).
+          cpu = "ppc64le" if cpu == "powerpc64le"
           os = host_os =~ /darwin/ ? "darwin" : "linux"
           ruby_platform = "#{cpu}-#{os}"
         end
@@ -118,6 +121,7 @@ module Leptris
       typedef :pointer, :leptris_node_ref
       typedef :pointer, :leptris_attribute
       typedef :pointer, :leptris_doctype
+      typedef :pointer, :leptris_dtd
       typedef :pointer, :leptris_xpath_result
       typedef :pointer, :leptris_xpath_ns_set
       typedef :pointer, :leptris_xpath_compiled
@@ -381,6 +385,12 @@ attach_function :leptris_parse_string,
         [:leptris_document, :int], :leptris_status
       attach_function :leptris_document_set_doctype,
         [:leptris_document, :string, :string, :string], :leptris_doctype
+      # The #1229 remove-half (libleptris 1.9.204): un-set the
+      # declaration; un-set the DOCTYPE (NOT_FOUND when none set).
+      attach_function :leptris_document_clear_declaration,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_remove_doctype,
+        [:leptris_document], :leptris_status
       attach_function :leptris_document_append_pi,
         [:leptris_document, :string, :string], :leptris_node_ref
       attach_function :leptris_document_remove_child,
@@ -849,6 +859,14 @@ attach_function :leptris_parse_string,
         [:leptris_sax_parser], :void
       attach_function :leptris_sax_parser_set_streaming,
         [:leptris_sax_parser, :int], :int
+      # One-shot input hint (libleptris 1.9.204): whole document in
+      # a single feed(), alive for the parser's lifetime — enables
+      # in-place scans. The binding's one-shot entry
+      # (leptris_sax_parse) is one-shot by construction; the engine
+      # sets this itself for pull's memory source. Attach-only
+      # until a chunked-feed face wants to opt in.
+      attach_function :leptris_sax_parser_set_one_shot,
+        [:leptris_sax_parser, :int], :void
 
       # Pull parsing (v1.6.0): StAX-style cursor over a document.
       attach_function :leptris_pull_new,
@@ -1024,6 +1042,30 @@ attach_function :leptris_parse_string,
       attach_function :leptris_str_has_nonstandard_entity,
         [:string, :size_t], :int
 
+      # DTD validation (exported 1.9.202; the surface existed
+      # since the CLI work): parse an internal subset, merge an
+      # external subset (application-owned I/O), validate a
+      # document. Errors carry message/element/line/column.
+      class DTDErrorStruct < ::FFI::Struct
+        layout :message, :string,
+               :element_name, :string,
+               :line, :int,
+               :column, :int
+      end
+      attach_function :leptris_dtd_parse,
+        [:string, :size_t], :pointer
+      # leptris_document_get_dtd attached above with the readers
+      attach_function :leptris_dtd_parse_external_subset,
+        [:pointer, :string, :size_t], :int
+      attach_function :leptris_dtd_set_pe_loader,
+        [:pointer, :pointer, :pointer], :void
+      attach_function :leptris_dtd_validate,
+        [:leptris_document, :pointer, :pointer], :int
+      attach_function :leptris_dtd_free,
+        [:pointer], :void
+      attach_function :leptris_dtd_error_free,
+        [:pointer], :void
+
       attach_function :leptris_rng_parse,
         [:string, :size_t, :pointer], :leptris_relaxng
       attach_function :leptris_rng_parse_file,
@@ -1100,6 +1142,11 @@ attach_function :leptris_parse_string,
         [:leptris_doctype], :string
 
       attach_function :leptris_free_string, [:pointer], :void
+      # Engine-heap allocation (libleptris 1.9.204): buffers handed
+      # to engine callbacks (the DTD PE loader) so the engine frees
+      # through its matching deallocation path. Release with
+      # leptris_free_string when NOT consumed by the engine.
+      attach_function :leptris_alloc_buffer, [:size_t], :pointer
       attach_function :leptris_explicit_cleanup, [], :void
       attach_function :leptris_set_memory_management_functions,
         [:pointer, :pointer], :void

data/lib/leptris/xml.rb

@@ -34,6 +34,7 @@ module Leptris
     autoload :XSLT, "leptris/xml/xslt"
     autoload :XQuery, "leptris/xml/xquery"
     autoload :RelaxNG, "leptris/xml/relaxng"
+    autoload :DTD, "leptris/xml/dtd"
     autoload :Pull, "leptris/xml/pull"
     autoload :Iterparse, "leptris/xml/iterparse"
 

data/vendor-src/libleptris/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [1.9.204] - 2026-09-19
+
+### Added
+
+- leptris/html.h subsystem header; one-shot name fast paths (slice 1); document HTML parsing (api+perf)
+
+### Performance
+
+- buffer-mode pull feeds in ONE call (slice-1 prerequisite) (sax)
+
+
+
+## [1.9.203] - 2026-09-19
+
+### Fixed
+
+- leptris_dtd_parse honors the NULL-on-error contract (#1211) (dtd)
+
+
+
+## [1.9.202] - 2026-09-18
+
+### Fixed
+
+- export the DTD validation surface; gate unmarked public declarations (api)
+
+
+
 ## [1.9.201] - 2026-09-18
 
 <!-- Edit this section with the actual release notes. -->

data/vendor-src/libleptris/CLAUDE.md

@@ -69,7 +69,7 @@ Core (src/leptris/)    →  DOM, parser, XPath engine, SAX, DTD, encoding, memor
 - `xinclude/` — built and shipping. `parse="text"` with `xi:fallback` works end-to-end. `parse="xml"` and xpointer are TODO 92.
 
 ### Public API surface (`src/include/leptris/`)
-The public contract. Don't break ABI without a major bump. Headers split by subsystem: `dom/{document,element,serialize}.h`, `xpath/xpath.h`, `sax/sax.h`, plus `types.h`, `error.h`, `dtd.h` at the top level. All handles are opaque typedefs (`LeptrisDocument`, `LeptrisElement`, `LeptrisNodeRef`, …); callers never see struct definitions.
+The public contract. Don't break ABI without a major bump. Headers split by subsystem: `dom/{document,element,serialize}.h`, `xpath/xpath.h`, `sax/sax.h`, `html.h`, plus `types.h`, `error.h`, `dtd.h` at the top level. All handles are opaque typedefs (`LeptrisDocument`, `LeptrisElement`, `LeptrisNodeRef`, …); callers never see struct definitions.
 
 ### Memory model
 - Pool allocator is the dominant allocation path — node creation should go through `leptris_node_create_pooled`.

data/vendor-src/libleptris/CMakeLists.txt

@@ -3,7 +3,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(leptris
-    VERSION 1.9.201
+    VERSION 1.9.204
     DESCRIPTION "Fast XML parser and XPath evaluator in pure C"
     LANGUAGES C CXX
 )

data/vendor-src/libleptris/README.adoc

@@ -320,6 +320,32 @@ if (r) {
 Supported: all 13 axes, all 27 functions, all 15 operators, full
 predicate syntax.  See <<api,xpath-coverage>> for details.
 
+==== HTML parsing (WHATWG + libxml2-compat)
+
+HTML is a first-class input — two tolerant parsers, both declared in
+`leptris/html.h`:
+
+[source,c]
+----
+LeptrisStatus st;
+/* WHATWG-conformant tree construction (html5lib corpus green). */
+LeptrisDocument doc =
+    leptris_parse_html_string("<p>Hello <b>world", 18, &st);
+
+/* Nokogiri byte-for-byte shape: no synthesized <html>/<head>/<body>,
+ * no implied <tbody>, leading script/style content stays in <body>. */
+LeptrisDocument frag =
+    leptris_parse_html4_string("<p>Hello <b>world", 18, &st);
+----
+
+Both handle implied end tags (`p`/`li`/`td`/`tr`/`th`/`dt`/`dd`/
+`option`/...), void elements, raw-text `script`/`style`, minimized
+and unquoted attribute values, case-insensitive tag/attribute names,
+and the HTML named-entity table.  Malformed input never fails the
+parse — it degrades to text; the result serializes and queries
+(XPath/XSLT) like any XML document.  Memory contract identical to
+`leptris_parse_string`.
+
 ==== Parsing models: DOM, SAX, StAX, iterparse
 
 One engine, four consumption models. Pick by how you want to pay:

data/vendor-src/libleptris/TODO.max-perf/2-3-oneshot-tokenizer-design.md

@@ -0,0 +1,98 @@
+# Levers 2+3 — compiled-dispatch + zero-copy one-shot emission (design)
+
+Status: DESIGNED (2026-09-19). Implementation slices below.
+Owners: engine repo. Bench: `benchmarks/sax/bench_iterparse.c` (#1195).
+
+## Problem
+
+The pull/iterparse path costs 4.4x the compact DOM parse over the
+same bytes (10KB medium: pull 54.7us vs DOM one-shot 12.3us).
+Root cause (measured, #1178): every event string is copied twice —
+
+1. streaming.c copies names/text/attrs into per-frame storage
+   (scratch arena + inline name bufs), because a streaming feed()
+   chunk may be freed once the call returns;
+2. pull.c's cb_* strdups them again into queue events, freed at the
+   next _next.
+
+A falsified attempt (per-call arena staging in _next) ADDED a third
+copy layer and measured slower (54.7 -> 67.6us) — churn-shaving the
+wrong layer cannot win; the copies must not happen at all.
+
+## Insight
+
+One-shot parses (leptris_sax_parse / leptris_pull_new over an
+in-memory buffer) have no interruption: the input buffer is
+immutable (#1125), caller-owned, and alive for the whole iteration
+(the pull API already documents input-lifetime for buffer mode).
+Names and attribute names cannot contain entity references (XML
+names are name-chars only), so in one-shot mode they are always
+contiguous slices of the input — borrowable with zero copies.
+
+Only entity-expanded payloads (attribute values, text with &...;)
+must materialize; the common case has none.
+
+## Design
+
+### Slice events (one-shot only)
+
+```
+typedef struct {
+    const char* ptr;   /* points INTO the input buffer */
+    size_t      len;
+} LeptrisSlice;
+
+typedef struct {
+    LeptrisPullEventType type;
+    LeptrisSlice name;         /* element / PI target          */
+    LeptrisSlice text;         /* ONLY if no entities: borrowed */
+    char*        text_owned;   /* materialized when entities    */
+    LeptrisSlice attr_flat[];  /* name,value pairs, names always
+                                  borrowed; values borrowed when
+                                  entity-free, else owned       */
+} OneShotEvent;
+```
+
+Rule: a payload is borrowed iff the engine can prove (single scan,
+memchr '&') that its span contains no '&'. One memchr per payload
+replaces one malloc+memcpy+free — and '&' is absent from the vast
+majority of real payloads.
+
+### Compiled dispatch (lever 2)
+
+The streaming machine's per-state if-chains (peek '<', '/', '!',
+name-start, ws...) become a 256-entry class table + a state-indexed
+goto/switch jump table:
+
+- class LUT: 4 bits (WS, NAME_START, NAME_CHAR, SPECIAL masks) —
+  one load classifies each byte (the #1177 LUT result generalized);
+- state dispatch: `switch (state)` compiled to a jump table by the
+  compiler once states are a dense enum — keep cases small and
+  branchless-friendly (the hot tokenizer states are ~20).
+
+The SAME token loop serves both modes: streaming keeps frames/carry
+(one_shot=0); one-shot mode (one_shot=1) skips carry and frame
+copies, emits slices, and materializes only entity spans.
+
+### Consumer adaptation
+
+pull.c gains a one-shot queue variant: cb_* check parser->one_shot
+and enqueue slice events (no strdup); queue_reset_event frees only
+owned pointers. Batch staging (#589) copies out of slices on
+demand — the existing stage chain unchanged.
+
+## Slices
+
+1. **Slice events + one-shot flag** in streaming.c; pull one-shot
+   queue. Acceptance: bench_iterparse full-doc 0.47us/event ->
+   <=0.15us/event; no test changes (contracts identical).
+2. **Class LUT + dense-state dispatch** in the tokenizer loop.
+   Acceptance: bench_sax +5% minimum; no behavioral delta.
+3. **memchr fast paths** for text/attr-value spans feeding the
+   borrow check. Acceptance: entity-free docs near-memcpy speed.
+
+## Non-goals
+
+- No API changes; event lifetime contracts unchanged.
+- Streaming feed() semantics untouched (frames/carry stay).
+- No new allocation strategies in pull.c (the falsified lesson).

data/vendor-src/libleptris/cli/commands/validate.c

@@ -77,8 +77,10 @@ static void print_element_text(LeptrisElement e) {
         fputs(t, stdout);
         return;
     }
-    for (LeptrisNodeRef c = leptris_element_first_child_any(e); c;
-         c = leptris_element_next_sibling_any(c)) {
+    for (LeptrisNodeRef c = (LeptrisNodeRef)leptris_element_first_child_any(e);
+         c;
+         c = (LeptrisNodeRef)leptris_element_next_sibling_any(
+                 (LeptrisElement)c)) {
         const char* txt = leptris_text_node_get_content(c);
         if (txt) fputs(txt, stdout);
     }

data/vendor-src/libleptris/docs/guide/parsing.md

@@ -303,6 +303,36 @@ void find_by_attribute(LeptrisElement parent,
 }
 ```
 
+## Parsing HTML
+
+HTML is a first-class input: the WHATWG-conformant tolerant parser
+(`leptris_parse_html_string`) plus a libxml2/Nokogiri-compatibility
+mode (`leptris_parse_html4_string`), both declared in
+`leptris/html.h`:
+
+```c
+#include "leptris/html.h"
+
+LeptrisStatus st = LEPTRIS_OK;
+LeptrisDocument doc =
+    leptris_parse_html_string("<p>Hello <b>world", 18, &st);
+/* Implied end tags, void elements, raw-text <script>/<style>,
+ * minimized + unquoted attribute values, case-insensitive names and
+ * the HTML named-entity table are all handled. Malformed input
+ * never fails the parse — it degrades to text. The result
+ * serializes and queries (XPath/XSLT) like any XML document. */
+```
+
+Choose the mode by contract:
+
+| Function | Mode | Shape |
+|----------|------|-------|
+| `leptris_parse_html_string` | WHATWG | full html5lib-conformant tree construction |
+| `leptris_parse_html4_string` | libxml2/Nokogiri | fragment shape: no synthesized `<html>/<head>/<body>`, no implied `<tbody>`; leading `<script>/<style>` content stays in `<body>` |
+
+Memory: identical to XML — `leptris_document_free` releases
+everything; input must be valid UTF-8.
+
 ## Performance Tips
 
 1. **Use in-place parsing** for string data when possible

data/vendor-src/libleptris/scripts/check_export_surface.py

@@ -31,6 +31,22 @@ def declared_public_symbols(root: Path):
     return names
 
 
+def unmarked_public_declarations(root: Path):
+    """Public-header leptris_* function declarations WITHOUT
+    LEPTRIS_API: they link fine into the static lib (the CLI works)
+    but never export for FFI consumers — the dtd.h class caught by
+    the ruby binding (#1183)."""
+    pat = re.compile(
+        r"^(?!LEPTRIS_API|static|typedef|struct|#|//|\*|/\*)(?:const\s+|unsigned\s+|struct\s+)*"
+        r"[A-Za-z_][\w\s\*]*?\b(leptris_[a-z_0-9]+)\s*\(",
+        flags=re.M,
+    )
+    found = set()
+    for h in (root / "src" / "include").rglob("*.h"):
+        for m in pat.finditer(h.read_text()):
+            found.add(m.group(1))
+    return found
+
 def exported_symbols(lib: Path):
     out = subprocess.run(
         ["nm", "-gU", str(lib)], capture_output=True, text=True, check=True
@@ -65,11 +81,15 @@ def main():
     undeclared = sorted(exported - declared)
     missing = sorted(declared - exported)
 
+    unmarked = sorted(unmarked_public_declarations(root) - declared)
+
     failures = []
     for n in undeclared:
         failures.append(f"UNDECLARED EXPORT {n}: exported but absent from src/include/")
     for n in missing:
         failures.append(f"MISSING EXPORT   {n}: declared public but not exported")
+    for n in unmarked:
+        failures.append(f"UNMARKED PUBLIC  {n}: declared in a public header without LEPTRIS_API")
 
     if failures:
         print("EXPORT SURFACE DRIFT:")