leptris 1.9.163.6 → 1.9.163.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed19c6383e8e83433ffcc99c8843337eb64ba48ac4f40349d5c5e0a537a31ab9
-  data.tar.gz: 3096440c8ba68d7eb54bfb2fd133098c795b025ec74389d09fd09cacd12f6311
+  metadata.gz: a191c85c5149a0f263ca7d7ee5f8ec63b58570f2f56ecd9c3cfc6333a974eff0
+  data.tar.gz: 7f126b1b774331af49faaea1b2dadffa7e8a170a47b917a9c3ea03d89377bbee
 SHA512:
-  metadata.gz: 5bef6e81be43ea7d536252201a4a59477d6c296a14ef186f9adb28fd304a13fb533218d46ac4d2245e55b724a62d13ab6d39088f82a750bbdfdb797c26c64c93
-  data.tar.gz: 9a61e4f09d0df6fc73479e1a25b83a146e77e28bae50b1d4dd82e5ed3b5f10be0e9b879e866d70f1207ac0abeda302d32f92c7b7efb4a27da8ee1958c6c63edd
+  metadata.gz: 47c7ae31a849c74b9dc651439de4b55d23a038098ed7b6dbfc8ff6ec2b740d45dfb39bb3ee42ac0b0d8a7ef467f03807e77c5cba70dfa5246a957f24c901726e
+  data.tar.gz: 8530bd56c3a373dd9bff555ed3fae96212db9792de187be21a002081be24e961601816016a3dc899482b61527424b818910cfeb85288156e95f5cd96fa7e4d8a

data/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.163.7] - 2026-09-15
+
+### Changed
+
+- **at_xpath single-result seam (TODO.perf/16)**: nodeset entry-0
+  materialization (identity cache, kind dispatch, attribute/text
+  value capture) plus the result free run as one C dispatch —
+  repeat `at_xpath` measured 3.7µs (pre-cache baseline) → ~1.3µs
+  across TODO.perf/15+16 (2.8x). Non-nodeset results keep the
+  exact Ruby scalar path.
+- **inner_html in one C pass (TODO.perf/18)**: the child chain,
+  per-kind serialization (elements through the engine's
+  serialize_into, text escaped with the binding's entity set,
+  CDATA/comments/PIs wrapped), and the buffer growth all in C —
+  byte-identical to the Ruby loop (spec-pinned per kind and past
+  the growth floor); ~160ns/child vs ~500-800ns/child.
+- **Precomputed fast-path flags (TODO.perf/17)**: `@native_fast`
+  at construction (Ruby and every C site) replaces the
+  `defined?`+`scope_owned?` method chain at every gate.
+  `Element#[]=` reads attribute names via StringValue+RSTRING_PTR
+  (values keep the embedded-NUL raise); the row measured
+  454ns → 236ns (~Nokogiri parity in the same run).
+
+### Added
+
+- `Native.at_xpath_first` / `Native.fast_inner_xml` module faces;
+  `materialize_xp_entry` shared by the bulk and single-result
+  paths.
+
 ## [1.9.163.6] - 2026-09-15
 
 ### Changed

data/TODO.perf/16-at-xpath-single-result-seam.md

@@ -0,0 +1,38 @@
+# 16 — C-bound at_xpath single-result seam
+
+Status: DONE (1.9.163.7)
+
+at_xpath is the hottest query shape (adapters picking one node),
+and its result path is five FFI calls per hit: result_type,
+get_node(0), node_kind(0), Node.wrap (pointer + construct), and
+result_free — plus the Ruby case dispatch between them. The bulk
+machinery from TODO.perf/03 already knows how to materialize a
+result entry as a binding wrapper in C (identity cache, kind
+dispatch, attribute/text value capture).
+
+Add Native.at_xpath_first(document, result_ptr): one C dispatch
+checks the result type; nodesets materialize entry 0 through the
+bulk machinery (get_nodes_ex with capacity 1 carries pointer +
+kind in one call), free the result handle, and return the binding
+node (or Qnil on empty); non-nodeset results return Qundef so the
+existing Ruby scalar path keeps its exact semantics. Searchable's
+wrap_xpath_first_result routes through the face when native is
+enabled.
+
+Gates: at_xpath parity for elements, attributes (ResultAttr name/
+value capture), text-kind results, empty results, and scalars;
+the result handle always freed exactly once.
+
+## Outcome (1.9.163.7)
+
+Native.at_xpath_first(document, result_ptr): one dispatch — type
+check, entry-0 materialization through the extracted
+materialize_xp_entry (shared with the TODO.perf/03 bulk loop:
+identity cache, kind dispatch, attribute/text value capture),
+result free. Non-nodeset results return the Native module object
+(Qundef must never cross into Ruby) and keep the exact Ruby
+scalar path. Measured: repeat at_xpath 3.7µs baseline -> 1.9µs
+(TODO.perf/15) -> ~1.3µs with the seam (2.8x total, load 8-30;
+the same-run Nokogiri comparison on this box is anomalous and not
+reported). Specs pin element identity, attribute capture, text
+kinds, nil misses, scalars, and xpath().first agreement.

data/TODO.perf/17-precomputed-fast-path-flags.md

@@ -0,0 +1,35 @@
+# 17 — Precomputed fast-path flags + set_attribute tightening
+
+Status: DONE (1.9.163.7)
+
+The native guards on hot paths are method chains:
+native_fast_children? resolves as defined?(NATIVE_FAST) plus
+scope_owned? (another method) — paid per mutation ([]=, add_child,
+the insert family) and per cold read fill. @structure_memoizable
+(TODO.perf/13) already carries "document-owned and alive" as an
+ivar; NATIVE_FAST availability is fixed at load time before any
+node exists, so the conjunction is construct-time constant.
+
+Add @native_fast to every wrapper construction (Ruby initialize
+and every C construction site): one ivar read replaces the chain
+at every gate. Fold in the set_attribute shaves: the C face reads
+attribute NAMES via StringValue+RSTRING_PTR (names cannot contain
+NULs — same rationale as nn_attribute); VALUES keep StringValueCStr
+so an embedded-NUL value still raises rather than truncating.
+
+Gates: suite green in both modes (the FFI fallback semantics must
+be unchanged for nodes constructed before a late native require —
+worst case they stay on the FFI path); set_attribute row improves.
+
+## Outcome (1.9.163.7)
+
+@native_fast computed once at construction (Ruby initialize and
+every C construction site — the bundle running implies the
+constant), replacing the defined?+scope_owned? method chain at
+every gate (native_fast?/native_fast_children? are ivar readers
+now). []= additionally reads attribute names via
+StringValue+RSTRING_PTR (values keep StringValueCStr — an
+embedded-NUL value still raises; spec-pinned). Measured (load
+17-31): binding []= 454ns mandate baseline -> 236ns (~2x on the
+row; 0.88x vs Nokogiri's 209ns in the same run — effectively
+parity).

data/TODO.perf/18-inner-html-one-c-pass.md

@@ -0,0 +1,32 @@
+# 18 — inner_html in one C pass
+
+Status: DONE (1.9.163.7)
+
+Element#inner_html walks children (bulk since TODO.perf/01) and
+then serializes EACH child from Ruby: element children get one
+ext dispatch each, text/comment/PI children are string-built in
+Ruby and joined. An N-child element pays N dispatches plus the
+case ladder plus the join.
+
+Bind the whole pass in C: iterate the child chain once, appending
+each child's serialization into one growable buffer — elements
+through leptris_element_serialize_into (the fast_serialize
+protocol), text nodes XML-escaped (& < > — the binding's
+escape_text set), CDATA wrapped raw, comments and PIs wrapped.
+One dispatch, one string mint, no Ruby per child.
+
+Gates: inner_html parity for every child kind (elements, text
+with entities, CDATA, comments, PIs, mixed), empty elements,
+large children past the 4096-byte stack probe (growth path).
+
+## Outcome (1.9.163.7)
+
+Native.fast_inner_xml: one pass over the child chain into a
+grow-only scratch — elements through leptris_element_serialize_into
+(needed-1 protocol, grow+retry past capacity), text escaped with
+the binding's entity set (& < > \r), CDATA raw-wrapped, comments
+and PIs wrapped (PI data leading-whitespace-stripped, read_pi_data
+parity). Byte-identical to the Ruby loop for every child kind and
+past the 4KB growth floor (specs). Measured (load 17-31): 30-child
+inner_html ~4.9µs (~160ns/child vs the loop's ~500-800ns/child
+estimate).

data/ext/leptris/native/native.c

@@ -76,6 +76,15 @@ static create_child_fn f_create_child;
 static append_child_fn f_append_child;
 static append_child_fn f_prepend_child, f_insert_after, f_insert_before;
 static set_attr_fn f_set_attr;
+typedef int (*xp_type_fn)(void *);
+typedef void (*xp_free_fn)(void *);
+typedef void *(*first_child_fn)(void *);
+typedef const char *(*node_str_fn)(void *);
+static xp_type_fn f_xp_type;
+static xp_free_fn f_xp_free;
+static first_child_fn f_first_child;
+static node_str_fn f_comment_content, f_cdata_content, f_pi_target,
+                   f_pi_data;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -176,6 +185,13 @@ static void resolve_symbols(const char *lib_path)
     f_insert_after = (append_child_fn)lib_sym(h, "leptris_element_insert_after");
     f_insert_before = (append_child_fn)lib_sym(h, "leptris_element_insert_before");
     f_set_attr = (set_attr_fn)lib_sym(h, "leptris_element_set_attribute");
+    f_xp_type = (xp_type_fn)lib_sym(h, "leptris_xpath_result_type");
+    f_xp_free = (xp_free_fn)lib_sym(h, "leptris_xpath_result_free");
+    f_first_child = (first_child_fn)lib_sym(h, "leptris_node_first_child");
+    f_comment_content = (node_str_fn)lib_sym(h, "leptris_comment_node_get_content");
+    f_cdata_content = (node_str_fn)lib_sym(h, "leptris_cdata_node_get_content");
+    f_pi_target = (node_str_fn)lib_sym(h, "leptris_pi_node_get_target");
+    f_pi_data = (node_str_fn)lib_sym(h, "leptris_pi_node_get_data");
     f_set_root = (set_root_fn)lib_sym(h, "leptris_document_set_root");
     f_doc_free = (doc_free_fn)lib_sym(h, "leptris_document_free");
     if (!f_elem_name || !f_text_content || !f_attr ||
@@ -183,6 +199,9 @@ static void resolve_symbols(const char *lib_path)
         !f_element_text || !f_doc_create || !f_elem_create || !f_text_create ||
         !f_create_child || !f_append_child || !f_prepend_child ||
         !f_insert_after || !f_insert_before || !f_set_attr || !f_set_root ||
+        !f_xp_type || !f_xp_free || !f_first_child ||
+        !f_comment_content || !f_cdata_content || !f_pi_target ||
+        !f_pi_data ||
         !f_doc_free ||
         !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
         !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
@@ -603,7 +622,11 @@ static VALUE nf_set_binding_attribute(VALUE self, VALUE document,
     node = (void *)(uintptr_t)NUM2ULL(addr);
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
-    st = f_set_attr(node, StringValueCStr(name), StringValueCStr(value));
+    /* Attribute names cannot contain NULs (StringValueCStr's
+     * memchr is a wasted scan); VALUES keep the scan so an
+     * embedded-NUL value raises rather than truncates. */
+    st = f_set_attr(node, RSTRING_PTR(StringValue(name)),
+                    StringValueCStr(value));
     return INT2FIX(st);
 }
 
@@ -853,6 +876,7 @@ static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
             rb_iv_set(node, "@document", document);
             rb_iv_set(node, "@parent", Qnil);
             rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
             rb_iv_set(node, "@node_type", INT2FIX(kinds[i]));
             rb_hash_aset(cache, key, node);
         }
@@ -885,6 +909,9 @@ static VALUE nf_bulk_element_children(VALUE self, VALUE document,
  * while the result handle is alive, identity-cache check/store
  * for elements. Returns the Ruby Array. */
 static VALUE m_native_sentinel; /* module object = fallback marker */
+static VALUE materialize_xp_entry(VALUE document, VALUE cache,
+                                  void *result, void *ptr, int kind,
+                                  int idx);
 
 static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
 {
@@ -912,76 +939,124 @@ static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
     cache = binding_cache_of(document);
     out = rb_ary_new2(count);
     for (i = 0; i < count; i++) {
-        VALUE node, key;
-        const char *s;
         if (buf[i] == NULL)
             continue;
-        key = ULL2NUM((uint64_t)(uintptr_t)buf[i]);
-        switch (kinds[i]) {
-        case 0: /* element */
+        rb_ary_push(out, materialize_xp_entry(document, cache, result,
+                                              buf[i], kinds[i], i));
+    }
+    ruby_xfree(buf);
+    ruby_xfree(kinds);
+    return out;
+}
+
+/* Materializes ONE result entry as a binding wrapper (or the
+ * module sentinel for the rare kinds the bulk path defers to
+ * Ruby). Shared by the bulk materializer (TODO.perf/03) and the
+ * at_xpath single-result seam (TODO.perf/16). */
+static VALUE materialize_xp_entry(VALUE document, VALUE cache,
+                                  void *result, void *ptr, int kind,
+                                  int idx)
+{
+    VALUE node, key;
+    const char *s;
+
+    key = ULL2NUM((uint64_t)(uintptr_t)ptr);
+    switch (kind) {
+    case 0: /* element */
+        node = rb_hash_aref(cache, key);
+        if (NIL_P(node)) {
+            VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
+            node = rb_obj_alloc(c_b_element);
+            rb_iv_set(node, "@c_ptr", p);
+            rb_iv_set(node, "@document", document);
+            rb_iv_set(node, "@parent", Qnil);
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
+            rb_iv_set(node, "@node_type", INT2FIX(0));
+            rb_hash_aset(cache, key, node);
+        }
+        return node;
+    case 1: /* synthetic attribute */
+        {
+            const char *name = f_xp_node_name(result, idx);
+            const char *value = f_xp_node_value(result, idx);
+            VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
+            node = rb_obj_alloc(c_b_result_attr);
+            rb_iv_set(node, "@c_ptr", p);
+            rb_iv_set(node, "@document", document);
+            rb_iv_set(node, "@attr_name",
+                      name ? rb_utf8_str_new_cstr(name) : Qnil);
+            rb_iv_set(node, "@attr_value",
+                      value ? rb_utf8_str_new_cstr(value) : Qnil);
+        }
+        return node;
+    case 2: /* text-kind: synthetic sequence carrier, or a real
+             * Text/CDATA node (XPath reports both as TEXT) —
+             * dispatch on the node's own type like Node.wrap. */
+        {
+            int nt = f_node_type(ptr);
+            if (nt == 8) { /* NODE_SYNTHETIC_TEXT */
+                s = f_xp_node_value(result, idx);
+                node = rb_obj_alloc(c_b_result_text);
+                rb_iv_set(node, "@c_ptr",
+                          rb_funcall(c_ffi_pointer, id_ptr_new, 1, key));
+                rb_iv_set(node, "@document", document);
+                rb_iv_set(node, "@value",
+                          s ? rb_utf8_str_new_cstr(s) : Qnil);
+                return node;
+            }
             node = rb_hash_aref(cache, key);
             if (NIL_P(node)) {
-                VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
-                node = rb_obj_alloc(c_b_element);
-                rb_iv_set(node, "@c_ptr", ptr);
+                VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
+                node = rb_obj_alloc(binding_klass_for(nt));
+                rb_iv_set(node, "@c_ptr", p);
                 rb_iv_set(node, "@document", document);
                 rb_iv_set(node, "@parent", Qnil);
                 rb_iv_set(node, "@structure_memoizable", Qtrue);
-                rb_iv_set(node, "@node_type", INT2FIX(0));
+                rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@node_type", INT2FIX(nt));
                 rb_hash_aset(cache, key, node);
             }
-            break;
-        case 1: /* synthetic attribute */
-            {
-                const char *name = f_xp_node_name(result, i);
-                const char *value = f_xp_node_value(result, i);
-                VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
-                node = rb_obj_alloc(c_b_result_attr);
-                rb_iv_set(node, "@c_ptr", ptr);
-                rb_iv_set(node, "@document", document);
-                rb_iv_set(node, "@attr_name",
-                          name ? rb_utf8_str_new_cstr(name) : Qnil);
-                rb_iv_set(node, "@attr_value",
-                          value ? rb_utf8_str_new_cstr(value) : Qnil);
-            }
-            break;
-        case 2: /* text-kind: synthetic sequence carrier, or a real
-                 * Text/CDATA node (XPath reports both as TEXT) —
-                 * dispatch on the node's own type like Node.wrap. */
-            {
-                int nt = f_node_type(buf[i]);
-                if (nt == 8) { /* NODE_SYNTHETIC_TEXT */
-                    s = f_xp_node_value(result, i);
-                    node = rb_obj_alloc(c_b_result_text);
-                    rb_iv_set(node, "@c_ptr",
-                              rb_funcall(c_ffi_pointer, id_ptr_new, 1, key));
-                    rb_iv_set(node, "@document", document);
-                    rb_iv_set(node, "@value",
-                              s ? rb_utf8_str_new_cstr(s) : Qnil);
-                } else {
-                    VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
-                    node = rb_hash_aref(cache, key);
-                    if (NIL_P(node)) {
-                        node = rb_obj_alloc(binding_klass_for(nt));
-                        rb_iv_set(node, "@c_ptr", ptr);
-                        rb_iv_set(node, "@document", document);
-                        rb_iv_set(node, "@parent", Qnil);
-                        rb_iv_set(node, "@structure_memoizable", Qtrue);
-                        rb_iv_set(node, "@node_type", INT2FIX(nt));
-                        rb_hash_aset(cache, key, node);
-                    }
-                }
-            }
-            break;
-        default: /* other: rare — signal Ruby fallback for this index */
-            rb_ary_push(out, m_native_sentinel);
-            continue;
         }
-        rb_ary_push(out, node);
+        return node;
+    default: /* other: rare — signal Ruby fallback for this entry */
+        return m_native_sentinel;
     }
-    ruby_xfree(buf);
-    ruby_xfree(kinds);
-    return out;
+}
+
+/* ---- at_xpath single-result seam (TODO.perf/16) ----------------
+ * One dispatch for the hottest query shape: type check, entry-0
+ * materialization through the bulk machinery, result free.
+ * Non-nodeset results return Qundef — the caller keeps the exact
+ * Ruby scalar path (and owns the free there). */
+static VALUE nf_at_xpath_first(VALUE self, VALUE document,
+                               VALUE result_ptr_val)
+{
+    void *result = (void *)(uintptr_t)NUM2ULL(result_ptr_val);
+    void *buf;
+    int kind;
+    size_t scount;
+    VALUE node;
+
+    (void)self;
+    resolve_binding_classes();
+    if (f_xp_type(result) != 0) /* XPATH_NODESET */
+        return m_native_sentinel; /* caller keeps the scalar path */
+    scount = f_xp_count(result);
+    if (scount == 0) {
+        f_xp_free(result);
+        return Qnil;
+    }
+    buf = NULL;
+    scount = f_xp_nodes_ex(result, &buf, &kind, 1);
+    if (scount == 0 || buf == NULL) {
+        f_xp_free(result);
+        return Qnil;
+    }
+    node = materialize_xp_entry(document, binding_cache_of(document),
+                                result, buf, kind, 0);
+    f_xp_free(result);
+    return node;
 }
 
 /* ---- Bulk attribute materialization (TODO.perf/10) ---------------
@@ -1027,6 +1102,7 @@ static VALUE nf_create_binding_element(VALUE self, VALUE document,
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);
+    rb_iv_set(node, "@native_fast", Qtrue);
     rb_iv_set(node, "@node_type", INT2FIX(0));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -1052,6 +1128,7 @@ static VALUE nf_create_binding_text(VALUE self, VALUE document,
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);
+    rb_iv_set(node, "@native_fast", Qtrue);
     rb_iv_set(node, "@node_type", INT2FIX(1));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -1163,6 +1240,117 @@ static VALUE nf_fast_element_xml(VALUE self, VALUE addr,
                           NUM2INT(indent), RTEST(decl) ? 1 : 0);
 }
 
+/* ---- inner_html in one C pass (TODO.perf/18) --------------------
+ * Serializes the receiver's children into one growable buffer:
+ * elements via leptris_element_serialize_into (the same opts the
+ * Ruby loop passed), text XML-escaped with the binding's entity
+ * set (& < > \r), CDATA/comments/PIs wrapped raw — byte-identical
+ * to Element#inner_html's per-child loop. */
+static char *inner_buf;
+static size_t inner_cap;
+
+static void inner_ensure(size_t need)
+{
+    if (need > inner_cap) {
+        inner_cap = need < 64 ? 64 : need;
+        inner_buf = ruby_xrealloc(inner_buf, inner_cap);
+    }
+}
+
+static size_t inner_append_raw(const char *s, size_t len, size_t at)
+{
+    inner_ensure(at + len + 1);
+    if (len)
+        memcpy(inner_buf + at, s, len);
+    return at + len;
+}
+
+static size_t inner_append_escaped(const char *s, size_t at)
+{
+    for (; s && *s; s++) {
+        const char *repl;
+        size_t rl;
+        switch (*s) {
+        case '&':  repl = "&amp;";  rl = 5; break;
+        case '<':  repl = "&lt;";   rl = 4; break;
+        case '>':  repl = "&gt;";   rl = 4; break;
+        case '\r': repl = "&#xD;"; rl = 5; break;
+        default:   repl = NULL;     rl = 0; break;
+        }
+        if (repl) {
+            at = inner_append_raw(repl, rl, at);
+        } else {
+            inner_ensure(at + 2);
+            inner_buf[at++] = *s;
+        }
+    }
+    return at;
+}
+
+static VALUE nf_fast_inner_xml(VALUE self, VALUE addr)
+{
+    void *node = (void *)(uintptr_t)NUM2ULL(addr);
+    void *child;
+    struct serialize_opts opts;
+    size_t at = 0, needed;
+
+    (void)self;
+    opts.indent = 0;
+    opts.xml_declaration = 1; /* matches element_xml_default */
+    opts.encoding = NULL;
+    inner_ensure(4096);
+    for (child = f_first_child(node); child != NULL;
+         child = f_next_sibling(child)) {
+        switch (f_node_type(child)) {
+        case 0: /* element */
+            needed = f_elem_serialize(child, inner_buf + at,
+                                      inner_cap - at, NULL, &opts);
+            if (needed > 0) {
+                if (needed > inner_cap - at) {
+                    inner_ensure(at + needed);
+                    needed = f_elem_serialize(child, inner_buf + at,
+                                              inner_cap - at, NULL, &opts);
+                }
+                at += needed - 1; /* size includes the NUL */
+            }
+            break;
+        case 1: /* text */
+            at = inner_append_escaped(f_text_content(child), at);
+            break;
+        case 2: /* comment */
+            at = inner_append_raw("<!--", 4, at);
+            at = inner_append_escaped(f_comment_content(child), at);
+            at = inner_append_raw("-->", 3, at);
+            break;
+        case 3: { /* CDATA */
+            const char *c = f_cdata_content(child);
+            at = inner_append_raw("<![CDATA[", 9, at);
+            at = inner_append_raw(c, c ? strlen(c) : 0, at);
+            at = inner_append_raw("]]>", 3, at);
+            break;
+        }
+        case 4: { /* PI — the binding strips leading whitespace from
+                   * the data before joining (read_pi_data parity). */
+            const char *data = f_pi_data(child);
+            while (data && (*data == ' ' || *data == '\t' ||
+                            *data == '\r' || *data == '\n'))
+                data++;
+            at = inner_append_raw("<?", 2, at);
+            at = inner_append_escaped(f_pi_target(child), at);
+            if (data && *data) {
+                at = inner_append_raw(" ", 1, at);
+                at = inner_append_escaped(data, at);
+            }
+            at = inner_append_raw("?>", 2, at);
+            break;
+        }
+        default:
+            break;
+        }
+    }
+    return rb_utf8_str_new(inner_buf, at);
+}
+
 /* ---- Adoption-lift predicate (TODO.perf/09, #204 ask 3) ---------
  * The #178/#208 namespace lift + pruning runs on EVERY attach and
  * costs several FFI round-trips even when provably a no-op. This
@@ -1394,6 +1582,10 @@ void Init_native(void)
                               nf_set_binding_attribute, 4);
     rb_define_module_function(m_native, "insert_binding_child",
                               nf_insert_binding_child, 4);
+    rb_define_module_function(m_native, "at_xpath_first",
+                              nf_at_xpath_first, 2);
+    rb_define_module_function(m_native, "fast_inner_xml",
+                              nf_fast_inner_xml, 1);
     rb_define_module_function(m_native, "doc_handle_attach",
                               nf_doc_handle_attach, 1);
     rb_define_module_function(m_native, "doc_handle_release",

data/lib/leptris/version.rb

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

data/lib/leptris/xml/element.rb

@@ -9,7 +9,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # rules ride the IterationScope seam — the ext fast path is for
   # document-owned trees.
   def native_fast?
-    defined?(Leptris::XML::NATIVE_FAST) && !scope_owned?
+    @native_fast
   end
 
   def name
@@ -609,6 +609,11 @@ class Leptris::XML::Element < Leptris::XML::Node
   # of #inner_text, which returns the unescaped text content.
   def inner_html
     ensure_alive!
+    # One C pass (TODO.perf/18): the child chain, per-kind
+    # serialization, and the escape set all in one dispatch —
+    # byte-identical to the Ruby loop below.
+    return Leptris::XML::Native.fast_inner_xml(@c_ptr.address) if
+      @native_fast
     children.map do |child|
       case child
       when Leptris::XML::Element

data/lib/leptris/xml/node.rb

@@ -27,6 +27,11 @@ class Leptris::XML::Node
     # keeps the memo-hit path free of method dispatch.
     @structure_memoizable =
       !document.nil? && !document.is_a?(Leptris::XML::IterationScope)
+    # NATIVE_FAST availability is fixed at load time before any
+    # node exists, so the conjunction with document-ownership is
+    # construct-time constant — the hot gates read one ivar.
+    @native_fast = @structure_memoizable &&
+                   defined?(Leptris::XML::NATIVE_FAST) ? true : false
     # wrap() already calls leptris_node_get_type for dispatch; reusing
     # the result makes every predicate and #type call FFI-free.
     @node_type = node_type
@@ -145,9 +150,9 @@ class Leptris::XML::Node
 
   # The ext bulk path applies to document-owned trees only:
   # scope-owned (iterparse) elements ride the IterationScope seam.
+  # Precomputed at construction (TODO.perf/17) — one ivar read.
   def native_fast_children?
-    defined?(Leptris::XML::NATIVE_FAST) &&
-      !@document.is_a?(Leptris::XML::IterationScope)
+    @native_fast
   end
 
   # Content-defined 64-bit Merkle digest of this subtree

data/lib/leptris/xml/searchable.rb

@@ -236,6 +236,14 @@ module Leptris::XML::Searchable
   # AutoPointer, one fewer FFI than xpath().first; scalars keep the
   # full-wrapper semantics.
   def self.wrap_xpath_first_result(document, result_ptr)
+    # C seam (TODO.perf/16): nodesets materialize entry 0, free
+    # the handle, and return in one dispatch. The module object
+    # back means non-nodeset — the scalar path below owns it.
+    if defined?(Leptris::XML::NATIVE_FAST)
+      first = Leptris::XML::Native.at_xpath_first(
+        document, result_ptr.address)
+      return first unless first.equal?(Leptris::XML::Native)
+    end
     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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.163.6
+  version: 1.9.163.7
 platform: ruby
 authors:
 - Ribose Inc.
@@ -84,6 +84,9 @@ files:
 - TODO.perf/13-structural-memos.md
 - TODO.perf/14-insert-family-c-bound.md
 - TODO.perf/15-compiled-expression-cache.md
+- TODO.perf/16-at-xpath-single-result-seam.md
+- TODO.perf/17-precomputed-fast-path-flags.md
+- TODO.perf/18-inner-html-one-c-pass.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md