leptris 1.9.174.5 → 1.9.174.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec76aed6663e2ae97d677c09e8b05486eb6e0543da0f92640a81a87d49c38565
-  data.tar.gz: bd881b0e87ff21939925f879abfced736f304a5396f675013a2bc8e2f220a89c
+  metadata.gz: 2b55134beeb4963b45dab45f2702b840c8db5e4f1c5e282622f5e4c4b5f55b1e
+  data.tar.gz: 92278400c3c9a6ff0450a151583a9edd383677b621d6c95bdbd5286d0ba0b8a1
 SHA512:
-  metadata.gz: f9f8f54bca5c16e6f1068a9988374ab2a852febc8f4f8695fa7cf0e5bb21fed700bf5b7a34b0732693d55f520000528ed35719dc2488fdf3afb3b6224d2dce9d
-  data.tar.gz: a883b80b556feaa34abc6544fe7b4c5f03d6da46597c6dc3170d1219ab66aa4018be3233f824ae6df551c50dc963974a35f72ea715037d596a26259bc8087d8a
+  metadata.gz: 3e476a9c2aaecd83069e118a4a7c1aa4ed141df2c853b238f4eb745b916be151ce46b0a5c29686f3d481d2bb816fe4c6f4744df7e76835bfe53ccc82c998134d
+  data.tar.gz: af8d33a0aaa87d762405979bcbc08be5af416e8dac2de924027eb900184df6740fcc4a8ef30e533becf131db08c2502a9dfc4a634b9678d9a87b5fa0513af212

data/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.174.7] - 2026-09-16
+
+### Changed
+
+- **Namespace-bound xpath on the compiled path (TODO.perf/29)**:
+  the ns branch rides the compiled-expression cache (the handle
+  is ns-independent) plus the cached ns set through
+  `XPath#eval_ns_ptrs`, then the eager materializer — measured
+  (load ~16): repeat ns-xpath 7.9µs → 3.1µs (2.5x).
+- **dup + element-child faces (TODO.perf/30)**: `Element#dup`
+  runs engine create + handle + element_copy + rooted wrap in
+  one C dispatch (the namespace-lift decision stays in Ruby) —
+  ns-bearing dup 37.0µs → 9.6µs (3.9x); `first/last_element_child`
+  answer in one C walk each (the FFI paths paid O(N) scans).
+
+## [1.9.174.6] - 2026-09-15
+
+### Changed
+
+- **C-yield traversal (TODO.perf/27)**: `traverse` and `visit`
+  no longer allocate an FFI::Function closure per call — the
+  ext's callbacks rb_yield directly, preserving post-order +
+  abort-at-self + stash-abort-raise (traverse) and the
+  (node, entering, depth) visit contract. Measured (load 34):
+  **traverse over 8k nodes 1663.5µs → 379.9µs (4.4x; 6.81x
+  Nokogiri); visit 2288.6µs → 545.4µs (4.2x)**.
+- **Address-based first-touch fills (TODO.perf/28)**:
+  text/comment/CDATA/PI content and `path` fill through address
+  faces (scope-eligible); the bulk attribute faces accept
+  scope-owned elements.
+
 ## [1.9.174.5] - 2026-09-15
 
 ### Changed

data/TODO.perf/27-c-yield-traversal.md

@@ -0,0 +1,38 @@
+# 27 — C-yield traversal (traverse/visit without the FFI::Function closure)
+
+Status: DONE (1.9.174.6)
+
+Node#traverse and #visit allocate an FFI::Function closure per
+call (~1µs) and dispatch every visited node back through the
+Ruby closure — the dominant per-node cost of whole-subtree
+iteration, paid even on small subtrees where the walk itself is
+microseconds.
+
+Bind both to C callbacks that rb_yield directly: the ext's
+traverse face keeps the abort-at-self post-order contract and
+the exception discipline (rb_protect in the callback stashes,
+aborts the walk, re-raises after — exactly the Ruby version's
+contract); visit keeps its (node, entering, depth) callback
+shape with the same stash-and-raise treatment. Node wrapping per
+visit rides the shared binding construction (identity cache +
+kind dispatch), and the walk state lives on the C stack — no
+globals, nested traversals safe.
+
+Gates: post-order sequence identical (receiver last); the
+subtree boundary holds (abort-at-self); block exceptions
+re-raise after the walk stops; enum_for forms unchanged; suite
+both modes.
+
+## Outcome (1.9.174.6)
+
+Native.traverse_binding / visit_binding: C callbacks that
+rb_yield directly (block forwarded explicitly — rb_yield needs
+it on the C entry's frame). traverse keeps post-order +
+abort-at-self + stash-abort-raise (rb_protect in the callback,
+walk state on the C stack — nested traversals independent);
+visit keeps (node, entering, depth) with the engine's
+(user, node, ...) callback order. Two bugs found by the suite:
+the visit callback's argument order (user first — the segfault
+spec caught it) and the block forwarding. Measured (load 34):
+traverse over 8k nodes 1663.5µs (FFI closure) -> 379.9µs
+(4.4x; 6.81x Nokogiri); visit 2288.6µs -> 545.4µs (4.2x).

data/TODO.perf/28-address-fills.md

@@ -0,0 +1,25 @@
+# 28 — Address-based first-touch fills for the remaining reads
+
+Status: DONE (1.9.174.6)
+
+The memoized content readers still fill through FFI marshaling on
+first touch — Text/Comment/CDATA/PI content, and Node#path
+(owned-string read + free) — and the bulk attribute faces exclude
+scope-owned elements though they touch no document state. Add the
+trivial address faces (fast_text/comment/cdata content, pi
+target/data, node path with the free protocol) and switch the
+fills to @addr_reads_fast (scope-eligible); the attributes bulk
+path follows.
+
+Gates: identical values for every kind (UTF-8, escapes, nils);
+scope-owned fills answer the same; path memo unchanged; suite
+both modes.
+
+## Outcome (1.9.174.6)
+
+fast_text/comment/cdata content, fast_pi_target/data (the
+read_pi_data strip preserved), and fast_path (owned-string copy
++ engine free) — every first-touch content fill now rides the
+address faces via @addr_reads_fast (scope-eligible), and the
+bulk attribute faces accept scope-owned elements (they touch no
+document state; the scope's version stamps the memo).

data/TODO.perf/29-ns-xpath-compiled.md

@@ -0,0 +1,23 @@
+# 29 — Namespace-bound xpath on the compiled + eager path
+
+Status: DONE (1.9.174.7)
+
+TODO.perf/15 excluded namespace-bound evaluations from the
+compiled-expression cache — they still pay the engine's string
+parse per call (~2-3µs) on top of an already-cached ns set. The
+engine has leptris_xpath_compiled_eval_ns; route the ns branch
+of xpath/at_xpath through the compiled cache (the handle is
+ns-independent — compile once) and the cached ns set, then let
+the eager materializer (TODO.perf/22) take the result.
+
+Gates: ns-bound results identical (prefix resolution, missing
+prefixes raising as today); the version-pinned path untouched;
+suite both modes.
+
+## Outcome (1.9.174.7)
+
+The ns branch of xpath/at_xpath rides the compiled-expression
+cache (the handle is ns-independent) + the cached ns set via
+XPath#eval_ns_ptrs (leptris_xpath_compiled_eval_ns); results
+flow into the eager materializer. Measured (load ~16): repeat
+ns-xpath 7.9µs -> 3.1µs (2.5x).

data/TODO.perf/30-copy-and-element-child-faces.md

@@ -0,0 +1,31 @@
+# 30 — dup one-dispatch + first/last element child faces
+
+Status: DONE (1.9.174.7)
+
+Node#dup runs create + FFI element_copy + root= (three dispatches
+plus the lift-guard walk) for an engine-copier op that is already
+2.3x — bind the whole copy: engine create + handle + element_copy
++ root wrap in one face. And the element-child readers pay O(N):
+first_element_child scans siblings with two FFI calls per
+non-element (text-heavy parents), last_element_children batches
+ALL children to keep one — one C walk each answers in a single
+dispatch.
+
+Gates: dup semantics (comment/PI children, namespaces — the
+copy_of seam contract #696/#721/#812); first/last on mixed
+content, empty elements, document receivers; suite both modes.
+
+## Outcome (1.9.174.7)
+
+Native.copy_binding_element: engine create + lifetime handle +
+document wrapper + element_copy + rooted+memo-seeded wrap in one
+dispatch; the namespace-lift decision stays in Ruby (skip_
+adoption_lift? + lift — the copy_of seam's #696/#721/#812
+semantics), and the return shape matches copy_of's contract (the
+copied root ELEMENT — my first version returned the document and
+the probe caught it). Native.first/last_element_child: one C
+walk each (the FFI scan paid two calls per skipped sibling; the
+batch fetch materialized every child to keep one). Measured
+(load ~16): ns-bearing element dup 37.0µs -> 9.6µs (3.9x);
+first_element_child over 1000 mixed children 98ns (memo-hit
+shape), last 3.2µs cold-walk.

data/ext/leptris/native/native.c

@@ -87,8 +87,20 @@ static node_str_fn f_comment_content, f_cdata_content, f_pi_target,
                    f_pi_data;
 typedef int (*set_str_fn)(void *, const char *);
 typedef int (*node_unlink_fn)(void *);
+typedef int (*traverse_cb_fn)(void *, void *);
+typedef int (*traverse_fn)(void *, int, traverse_cb_fn, void *);
+typedef void (*visit_cb_fn)(void *, void *, int, int);
+typedef void (*visit_fn)(void *, visit_cb_fn, void *);
+typedef void (*free_str_fn)(void *);
+typedef const char *(*node_xpath_fn)(void *);
+typedef void *(*elem_copy_fn)(void *, void *);
 static set_str_fn f_elem_set_name, f_elem_set_text, f_text_set_content;
 static node_unlink_fn f_node_unlink;
+static traverse_fn f_node_traverse;
+static visit_fn f_node_visit;
+static free_str_fn f_free_str;
+static node_xpath_fn f_node_xpath;
+static elem_copy_fn f_elem_copy;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -105,6 +117,10 @@ static VALUE c_use_after_free_error;
 static VALUE native_cache_of(VALUE document);
 static void resolve_binding_classes(void);
 static VALUE binding_cache_of(VALUE document);
+static VALUE binding_klass_for(int kind);
+static VALUE c_iteration_scope;
+static VALUE c_b_document, c_b_freed, c_ffi_pointer;
+static ID id_ptr_new, id_freed_new, id_alive;
 
 #define NT_ELEMENT 0
 
@@ -200,6 +216,11 @@ static void resolve_symbols(const char *lib_path)
     f_elem_set_text = (set_str_fn)lib_sym(h, "leptris_element_set_text");
     f_text_set_content = (set_str_fn)lib_sym(h, "leptris_text_node_set_content");
     f_node_unlink = (node_unlink_fn)lib_sym(h, "leptris_node_unlink");
+    f_node_traverse = (traverse_fn)lib_sym(h, "leptris_node_traverse");
+    f_node_visit = (visit_fn)lib_sym(h, "leptris_node_visit");
+    f_free_str = (free_str_fn)lib_sym(h, "leptris_free_string");
+    f_node_xpath = (node_xpath_fn)lib_sym(h, "leptris_node_get_xpath");
+    f_elem_copy = (elem_copy_fn)lib_sym(h, "leptris_element_copy");
     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 ||
@@ -211,6 +232,8 @@ static void resolve_symbols(const char *lib_path)
         !f_comment_content || !f_cdata_content || !f_pi_target ||
         !f_pi_data || !f_elem_set_name || !f_elem_set_text ||
         !f_text_set_content || !f_node_unlink ||
+        !f_node_traverse || !f_node_visit || !f_free_str ||
+        !f_node_xpath || !f_elem_copy ||
         !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 ||
@@ -707,6 +730,277 @@ static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
     return INT2FIX(st);
 }
 
+/* ---- C-yield traversal (TODO.perf/27) ----------------------------
+ * Same contracts as the Ruby FFI::Function versions without the
+ * per-call closure: traverse is post-order with abort-at-self
+ * (the receiver is the LAST node of its subtree in post-order,
+ * so stopping at self bounds the walk exactly) and
+ * stash-abort-raise exception discipline; visit passes (node,
+ * entering, depth). Walk state lives on the caller's C stack —
+ * nested traversals are independent. */
+struct trav_state {
+    VALUE document;
+    VALUE err;
+    void *self_ptr;
+    int for_visit;
+};
+
+static VALUE trav_yield_one(VALUE arg)
+{
+    return rb_yield(arg);
+}
+
+static int trav_cb(void *node_ptr, void *user)
+{
+    struct trav_state *st = user;
+    VALUE cache, key, node;
+    int kind, state;
+
+    if (st->err != Qnil)
+        return 1;
+    kind = f_node_type(node_ptr);
+    cache = binding_cache_of(st->document);
+    key = ULL2NUM((uint64_t)(uintptr_t)node_ptr);
+    node = rb_hash_aref(cache, key);
+    if (NIL_P(node)) {
+        node = rb_obj_alloc(binding_klass_for(kind));
+        rb_iv_set(node, "@c_address", key);
+        rb_iv_set(node, "@document", st->document);
+        rb_iv_set(node, "@parent", Qnil);
+        if (rb_obj_class(st->document) == c_iteration_scope) {
+            rb_iv_set(node, "@structure_memoizable", Qfalse);
+            rb_iv_set(node, "@native_fast", Qfalse);
+            rb_iv_set(node, "@pub_document", Qnil);
+        } else {
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
+            rb_iv_set(node, "@pub_document", st->document);
+        }
+        rb_iv_set(node, "@addr_reads_fast", Qtrue);
+        rb_iv_set(node, "@node_type", INT2FIX(kind));
+        rb_hash_aset(cache, key, node);
+    }
+    rb_protect(trav_yield_one, node, &state);
+    if (state) {
+        st->err = rb_errinfo();
+        return 1; /* abort the walk */
+    }
+    return node_ptr == st->self_ptr ? 1 : 0; /* abort-at-self */
+}
+
+static VALUE nf_traverse_binding(VALUE self, VALUE document,
+                                 VALUE addr)
+{
+    struct trav_state st;
+
+    (void)self;
+    resolve_binding_classes();
+    st.document = document;
+    st.err = Qnil;
+    st.self_ptr = (void *)(uintptr_t)NUM2ULL(addr);
+    st.for_visit = 0;
+    f_node_traverse(st.self_ptr, 1 /* TRAVERSE_POST_ORDER */,
+                    trav_cb, &st);
+    if (st.err != Qnil)
+        rb_exc_raise(st.err);
+    return Qnil;
+}
+
+struct visit_yield_args {
+    VALUE node, entering, depth;
+};
+
+static VALUE trav_yield_args(VALUE arg)
+{
+    struct visit_yield_args *a = (struct visit_yield_args *)arg;
+    return rb_yield_values(3, a->node, a->entering, a->depth);
+}
+
+/* Engine visit callback order is (user, node, entering, depth) —
+ * the Ruby closure's |_, node_ptr, entering, depth| mirrors it. */
+static void visit_cb(void *user, void *node_ptr, int entering,
+                     int depth)
+{
+    /* visit's engine signature cannot abort; exceptions are
+     * stashed and every later node is skipped — the raise
+     * happens after the walk, same observable outcome. */
+    struct trav_state *st = user;
+    struct visit_yield_args va;
+    VALUE cache, key, node;
+    int kind, state;
+
+    if (st->err != Qnil)
+        return;
+    kind = f_node_type(node_ptr);
+    cache = binding_cache_of(st->document);
+    key = ULL2NUM((uint64_t)(uintptr_t)node_ptr);
+    node = rb_hash_aref(cache, key);
+    if (NIL_P(node)) {
+        node = rb_obj_alloc(binding_klass_for(kind));
+        rb_iv_set(node, "@c_address", key);
+        rb_iv_set(node, "@document", st->document);
+        rb_iv_set(node, "@parent", Qnil);
+        if (rb_obj_class(st->document) == c_iteration_scope) {
+            rb_iv_set(node, "@structure_memoizable", Qfalse);
+            rb_iv_set(node, "@native_fast", Qfalse);
+            rb_iv_set(node, "@pub_document", Qnil);
+        } else {
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
+            rb_iv_set(node, "@pub_document", st->document);
+        }
+        rb_iv_set(node, "@addr_reads_fast", Qtrue);
+        rb_iv_set(node, "@node_type", INT2FIX(kind));
+        rb_hash_aset(cache, key, node);
+    }
+    va.node = node;
+    va.entering = entering ? Qtrue : Qfalse;
+    va.depth = INT2NUM(depth);
+    rb_protect(trav_yield_args, (VALUE)&va, &state);
+    if (state)
+        st->err = rb_errinfo();
+}
+
+static VALUE nf_visit_binding(VALUE self, VALUE document, VALUE addr)
+{
+    struct trav_state st;
+
+    (void)self;
+    resolve_binding_classes();
+    st.document = document;
+    st.err = Qnil;
+    st.self_ptr = (void *)(uintptr_t)NUM2ULL(addr);
+    st.for_visit = 1;
+    f_node_visit(st.self_ptr, visit_cb, &st);
+    if (st.err != Qnil)
+        rb_exc_raise(st.err);
+    return Qnil;
+}
+
+/* ---- Address-based fills (TODO.perf/28) -------------------------
+ * Pure reads of node-local data — no cache, no version — the
+ * same shapes the inner_html pass uses. */
+static VALUE nf_fast_text_content(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_text_content((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_fast_comment_content(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_comment_content((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_fast_cdata_content(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_cdata_content((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_fast_pi_target(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_pi_target((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_fast_pi_data(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_pi_data((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+/* Shared construction for address-walk faces (TODO.perf/30):
+ * cache lookup + kind-dispatched binding wrapper. */
+static VALUE wrap_addr_node(VALUE document, void *ptr)
+{
+    VALUE cache, key, node;
+    int kind;
+
+    kind = f_node_type(ptr);
+    cache = binding_cache_of(document);
+    key = ULL2NUM((uint64_t)(uintptr_t)ptr);
+    node = rb_hash_aref(cache, key);
+    if (NIL_P(node)) {
+        node = rb_obj_alloc(binding_klass_for(kind));
+        rb_iv_set(node, "@c_address", key);
+        rb_iv_set(node, "@document", document);
+        rb_iv_set(node, "@parent", Qnil);
+        if (rb_obj_class(document) == c_iteration_scope) {
+            rb_iv_set(node, "@structure_memoizable", Qfalse);
+            rb_iv_set(node, "@native_fast", Qfalse);
+            rb_iv_set(node, "@pub_document", Qnil);
+        } else {
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
+            rb_iv_set(node, "@pub_document", document);
+        }
+        rb_iv_set(node, "@addr_reads_fast", Qtrue);
+        rb_iv_set(node, "@node_type", INT2FIX(kind));
+        rb_hash_aset(cache, key, node);
+    }
+    return node;
+}
+
+/* First element child in one C walk (text-heavy parents paid two
+ * FFI calls per skipped sibling). */
+static VALUE nf_first_element_child(VALUE self, VALUE document,
+                                    VALUE addr)
+{
+    void *p;
+
+    (void)self;
+    resolve_binding_classes();
+    for (p = f_first_child((void *)(uintptr_t)NUM2ULL(addr));
+         p != NULL; p = f_next_sibling(p)) {
+        if (f_node_type(p) == NT_ELEMENT)
+            return wrap_addr_node(document, p);
+    }
+    return Qnil;
+}
+
+/* Last element child in one C walk (the batch fetch materialized
+ * every child to keep one). */
+static VALUE nf_last_element_child(VALUE self, VALUE document,
+                                   VALUE addr)
+{
+    void *p, *last = NULL;
+
+    (void)self;
+    resolve_binding_classes();
+    for (p = f_first_child((void *)(uintptr_t)NUM2ULL(addr));
+         p != NULL; p = f_next_sibling(p)) {
+        if (f_node_type(p) == NT_ELEMENT)
+            last = p;
+    }
+    return last ? wrap_addr_node(document, last) : Qnil;
+}
+
+/* Owned string: copy + free through the engine's seam (the
+ * read_owned_string protocol). */
+static VALUE nf_fast_path(VALUE self, VALUE addr)
+{
+    const char *s;
+    VALUE out;
+    (void)self;
+    s = f_node_xpath((void *)(uintptr_t)NUM2ULL(addr));
+    if (!s)
+        return Qnil;
+    out = rb_utf8_str_new_cstr(s);
+    f_free_str((void *)s);
+    return out;
+}
+
 /* C-bound insert family (TODO.perf/14): prepend / insert-after /
  * insert-before share append's gates + predicate + bump shape.
  * mode: 1 prepend, 2 after, 3 before (anchor = receiver). */
@@ -1003,6 +1297,8 @@ 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 binding_klass_for(int kind);
+static VALUE c_iteration_scope;
 
 static VALUE bulk_xpath_array(VALUE document, void *result);
 
@@ -1512,6 +1808,48 @@ static const rb_data_type_t dh_type = {
 static VALUE c_doc_handle;
 static ID id_iv_doc_handle, id_freed_new, id_alive;
 
+/* Node#dup in one dispatch (TODO.perf/30): engine create +
+ * lifetime handle + document wrapper + element_copy + the copy
+ * wrapped-and-rooted (memo-seeded). The namespace lift stays a
+ * Ruby decision (skip_adoption_lift? — the copy_of seam's
+ * semantics, #696/#721/#812). */
+static VALUE nf_copy_binding_element(VALUE self, VALUE document,
+                                     VALUE addr)
+{
+    void *doc, *copy;
+    VALUE new_doc, doc_addr, handle, freed, root;
+    struct doc_handle *h;
+
+    (void)self;
+    resolve_binding_classes();
+    doc = f_doc_create();
+    if (!doc)
+        return Qnil;
+    doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
+    new_doc = rb_obj_alloc(c_b_document);
+    rb_iv_set(new_doc, "@c_ptr",
+              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
+    rb_iv_set(new_doc, "@c_address", doc_addr);
+    freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
+    rb_iv_set(new_doc, "@freed", freed);
+    rb_iv_set(new_doc, "@readonly", Qfalse);
+    rb_iv_set(new_doc, "@version", INT2FIX(0));
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc;
+    rb_ivar_set(new_doc, id_iv_doc_handle, handle);
+
+    copy = f_elem_copy((void *)(uintptr_t)NUM2ULL(addr), doc);
+    if (!copy) {
+        h->doc = NULL; /* the handle releases the empty doc */
+        return Qnil;
+    }
+    root = wrap_addr_node(new_doc, copy);
+    rb_ivar_set(new_doc, rb_intern("@root"), root);
+    rb_ivar_set(new_doc, rb_intern("@root_version"), INT2FIX(0));
+    return new_doc;
+}
+
 static VALUE nf_doc_handle_attach(VALUE self, VALUE document)
 {
     struct doc_handle *h;
@@ -1711,6 +2049,28 @@ void Init_native(void)
                               nf_set_binding_text, 3);
     rb_define_module_function(m_native, "unlink_binding_node",
                               nf_unlink_binding_node, 2);
+    rb_define_module_function(m_native, "traverse_binding",
+                              nf_traverse_binding, 2);
+    rb_define_module_function(m_native, "visit_binding",
+                              nf_visit_binding, 2);
+    rb_define_module_function(m_native, "fast_text_content",
+                              nf_fast_text_content, 1);
+    rb_define_module_function(m_native, "fast_comment_content",
+                              nf_fast_comment_content, 1);
+    rb_define_module_function(m_native, "fast_cdata_content",
+                              nf_fast_cdata_content, 1);
+    rb_define_module_function(m_native, "fast_pi_target",
+                              nf_fast_pi_target, 1);
+    rb_define_module_function(m_native, "fast_pi_data",
+                              nf_fast_pi_data, 1);
+    rb_define_module_function(m_native, "fast_path",
+                              nf_fast_path, 1);
+    rb_define_module_function(m_native, "first_element_child",
+                              nf_first_element_child, 2);
+    rb_define_module_function(m_native, "last_element_child",
+                              nf_last_element_child, 2);
+    rb_define_module_function(m_native, "copy_binding_element",
+                              nf_copy_binding_element, 2);
     rb_define_module_function(m_native, "fast_inner_xml",
                               nf_fast_inner_xml, 1);
     rb_define_module_function(m_native, "doc_handle_attach",

data/lib/leptris/version.rb

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

data/lib/leptris/xml/cdata.rb

@@ -6,7 +6,11 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_cdata_node_get_content(c_ptr)
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_cdata_content(@c_address)
+             else
+               Leptris::XML::FFI.leptris_cdata_node_get_content(c_ptr)
+             end
     if @document
       @content = result
       @content_version = @document.version

data/lib/leptris/xml/comment.rb

@@ -6,7 +6,11 @@ class Leptris::XML::Comment < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_comment_node_get_content(c_ptr)
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_comment_content(@c_address)
+             else
+               Leptris::XML::FFI.leptris_comment_node_get_content(c_ptr)
+             end
     if @document
       @content = result
       @content_version = @document.version

data/lib/leptris/xml/element.rb

@@ -260,7 +260,9 @@ class Leptris::XML::Element < Leptris::XML::Node
     # 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)
-    if native_fast?
+    # TODO.perf/28: the bulk faces touch no document state —
+    # scope-eligible via @addr_reads_fast.
+    if @addr_reads_fast
       # TODO.perf/10: both memo faces in one C walk.
       result, values = Leptris::XML::Native.bulk_attr_faces(
         @c_address, self)
@@ -495,9 +497,21 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   # Deep copy in a NEW document via Document.copy_of (the single
   # copy seam — every child kind and namespace survives,
-  # #696/#721/#812).
+  # #696/#721/#812). TODO.perf/30: one C dispatch when the ext
+  # is loaded — the namespace-lift decision stays here.
   def dup
     ensure_alive!
+    if @addr_reads_fast
+      doc = Leptris::XML::Native.copy_binding_element(
+        @document, @c_address)
+      unless doc.nil?
+        copied = doc.root
+        unless Leptris::XML::Element.skip_adoption_lift?(copied)
+          Leptris::XML::Element.lift_namespaces_for_adoption(copied, {})
+        end
+        return copied
+      end
+    end
     Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup

data/lib/leptris/xml/node.rb

@@ -390,6 +390,17 @@ class Leptris::XML::Node
   def first_element_child
     return @first_element_child if memo_hit?(@first_element_child_version)
     ensure_alive!
+    # TODO.perf/30: one C walk (the FFI scan paid two calls per
+    # skipped non-element sibling).
+    if @addr_reads_fast
+      result = Leptris::XML::Native.first_element_child(
+        @document, @c_address)
+      if @document
+        @first_element_child = result
+        @first_element_child_version = @document.version
+      end
+      return result
+    end
     # Raw pointer scan: non-element siblings are typed with one C
     # call each — never wrapped, never cached — and the found
     # element carries the ELEMENT hint into the wrap.
@@ -413,8 +424,12 @@ class Leptris::XML::Node
   end
 
   def last_element_child
-    # Element receivers: the element-only batch fetches pointers
-    # without wrapping any text child; only the last is wrapped.
+    # TODO.perf/30: one C walk — the batch fetch materialized
+    # every child pointer to keep one.
+    if @addr_reads_fast
+      return Leptris::XML::Native.last_element_child(
+        @document, @c_address)
+    end
     if is_a?(Leptris::XML::Element)
       kids = Leptris::XML::FFI.fetch_element_children(c_ptr)
       return nil if kids.empty?
@@ -492,6 +507,13 @@ class Leptris::XML::Node
   def visit(&block)
     return enum_for(:visit) unless block
     ensure_alive!
+    # TODO.perf/27: the ext's callback rb_yields directly — no
+    # FFI::Function closure per call.
+    if @addr_reads_fast
+      Leptris::XML::Native.visit_binding(@document, @c_address,
+                                          &block)
+      return self
+    end
     document = @document
     visitor = ::FFI::Function.new(
       :void, [:pointer, :pointer, :int, :int], blocking: true) do |_, node_ptr, entering, depth|
@@ -524,9 +546,18 @@ class Leptris::XML::Node
   # exception and returns non-zero, aborting the C walk — without
   # it the FFI dispatch silently swallowed the exception and the
   # walk continued with partially processed data.
-  def traverse
-    return enum_for(:traverse) unless block_given?
+  def traverse(&block)
+    return enum_for(:traverse) unless block
     ensure_alive!
+    # TODO.perf/27: post-order + abort-at-self + stash-abort-raise
+    # all preserved in the C callback (walk state on its stack).
+    # The block forwards explicitly — rb_yield needs it on the C
+    # entry's own frame.
+    if @addr_reads_fast
+      Leptris::XML::Native.traverse_binding(@document, @c_address,
+                                             &block)
+      return self
+    end
     error = nil
     self_address = @c_address
     callback = ::FFI::Function.new(:int, [:pointer, :pointer], blocking: true) do |node_ptr, _|
@@ -547,8 +578,12 @@ class Leptris::XML::Node
   def path
     return @path if memo_hit?(@path_version)
     ensure_alive!
-    str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(c_ptr)
-    result = str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_path(@c_address)
+             else
+               str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(c_ptr)
+               str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
+             end
     if @document
       @path = result
       @path_version = @document.version
@@ -580,6 +615,23 @@ class Leptris::XML::Node
   # non-element kinds rebuild by value — #161).
   def dup
     ensure_alive!
+    # TODO.perf/30: elements copy in one C dispatch (engine
+    # create + handle + element_copy + rooted wrap). The
+    # namespace lift stays a Ruby decision — the copy_of seam's
+    # semantics (#696/#721/#812) run below when needed.
+    if element? && @addr_reads_fast
+      doc = Leptris::XML::Native.copy_binding_element(
+        @document, @c_address)
+      unless doc.nil?
+        # copy_of's contract returns the copied ROOT (the last
+        # expression of the root= assignment), not the document.
+        copied = doc.root
+        unless Leptris::XML::Element.skip_adoption_lift?(copied)
+          Leptris::XML::Element.lift_namespaces_for_adoption(copied, {})
+        end
+        return copied
+      end
+    end
     Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup

data/lib/leptris/xml/processing_instruction.rb

@@ -4,7 +4,11 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def name
     return @name if memo_hit?(@name_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_pi_node_get_target(c_ptr)
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_pi_target(@c_address)
+             else
+               Leptris::XML::FFI.leptris_pi_node_get_target(c_ptr)
+             end
     if @document
       @name = result
       @name_version = @document.version
@@ -16,8 +20,12 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.read_pi_data(
-      Leptris::XML::FFI.leptris_pi_node_get_data(c_ptr)).to_s
+    raw = if @addr_reads_fast
+            Leptris::XML::Native.fast_pi_data(@c_address)
+          else
+            Leptris::XML::FFI.leptris_pi_node_get_data(c_ptr)
+          end
+    result = Leptris::XML::FFI.read_pi_data(raw).to_s
     if @document
       @content = result
       @content_version = @document.version

data/lib/leptris/xml/searchable.rb

@@ -69,7 +69,16 @@ module Leptris::XML::Searchable
           doc_ptr, context_ptr, expr,
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
-        xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
       elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
         compiled.eval_ptrs(doc_ptr, context_ptr)
       else
@@ -105,7 +114,16 @@ module Leptris::XML::Searchable
           doc_ptr, context_ptr, expr,
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
-        xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
       elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
         compiled.eval_ptrs(doc_ptr, context_ptr)
       else

data/lib/leptris/xml/text.rb

@@ -6,7 +6,11 @@ class Leptris::XML::Text < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_text_node_get_content(c_ptr)
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_text_content(@c_address)
+             else
+               Leptris::XML::FFI.leptris_text_node_get_content(c_ptr)
+             end
     if @document
       @content = result
       @content_version = @document.version

data/lib/leptris/xml/xpath.rb

@@ -40,6 +40,14 @@ class Leptris::XML::XPath
       @handle, doc_ptr, context_ptr)
   end
 
+  # Namespace-bound evaluation against the compiled handle
+  # (TODO.perf/29): the handle is ns-independent — compile once,
+  # bind per call through the cached ns set.
+  def eval_ns_ptrs(doc_ptr, context_ptr, ns_set_ptr)
+    Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
+      @handle, doc_ptr, context_ptr, ns_set_ptr)
+  end
+
   def initialize(expression, handle, version_code = nil)
     @expression = expression
     @handle = handle

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.5
+  version: 1.9.174.7
 platform: ruby
 authors:
 - Ribose Inc.
@@ -95,6 +95,10 @@ files:
 - TODO.perf/24-immutable-read-lanes.md
 - TODO.perf/25-scope-owned-bulk-path.md
 - TODO.perf/26-post-mutation-memo-seeding.md
+- TODO.perf/27-c-yield-traversal.md
+- TODO.perf/28-address-fills.md
+- TODO.perf/29-ns-xpath-compiled.md
+- TODO.perf/30-copy-and-element-child-faces.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md