makiri 0.2.0 → 0.3.0

data/ext/makiri/glue/ruby_doc.c

@@ -1,6 +1,7 @@
 #include "glue.h"
 #include "../lexbor_compat/compat_internal.h" /* mkr_dom_preorder_next */
 #include "../core/mkr_core.h"
+#include "../xml/mkr_xml.h"   /* mkr_xml_doc_memsize for an XML-backed document */
 
 #include <lexbor/html/parser.h>
 #include <ruby/thread.h>
@@ -32,23 +33,47 @@ mkr_doc_free(void *ptr)
 static size_t
 mkr_doc_memsize(const void *ptr)
 {
-    /* The DOM arena size is not cheaply queryable; report the wrapper only. */
-    (void)ptr;
-    return sizeof(mkr_doc_data_t);
+    const mkr_doc_data_t *d = (const mkr_doc_data_t *)ptr;
+    size_t total = sizeof(mkr_doc_data_t);
+    /* The Lexbor (HTML) arena size is not cheaply queryable; report the wrapper
+     * only. The XML arena tracks its own byte total, so include it. */
+    if (d->parsed != NULL && mkr_parsed_kind(d->parsed) == MKR_DOC_XML) {
+        total += mkr_xml_doc_memsize(mkr_parsed_xml_doc(d->parsed));
+    }
+    return total;
 }
 
+/* Like nodes, HTML and XML Documents share the mkr_doc_data_t layout and GC
+ * functions but are wrapped under DISTINCT TypedData types (both deriving from
+ * the shared base mkr_doc_type), so mkr_html_doc_unwrap - which reinterprets the
+ * parsed document as a Lexbor lxb_html_document_t - RAISES TypeError on an XML
+ * Document via Ruby's type machinery, instead of relying on the (NDEBUG-erased)
+ * assert in mkr_parsed_html_doc. mkr_doc_type (base) is kept for the kind-agnostic
+ * accessors (mkr_doc_parsed, #errors) that legitimately accept either. */
 const rb_data_type_t mkr_doc_type = {
     "Makiri::Document",
     { mkr_doc_mark, mkr_doc_free, mkr_doc_memsize, },
     0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
 };
+static const rb_data_type_t mkr_html_doc_type = {
+    "Makiri::HTML::Document",
+    { mkr_doc_mark, mkr_doc_free, mkr_doc_memsize, },
+    &mkr_doc_type, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+static const rb_data_type_t mkr_xml_doc_type = {
+    "Makiri::XML::Document",
+    { mkr_doc_mark, mkr_doc_free, mkr_doc_memsize, },
+    &mkr_doc_type, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
 
 lxb_dom_document_t *
-mkr_doc_unwrap(VALUE rb_doc)
+mkr_html_doc_unwrap(VALUE rb_doc)
 {
     mkr_doc_data_t *d;
-    TypedData_Get_Struct(rb_doc, mkr_doc_data_t, &mkr_doc_type, d);
-    return (lxb_dom_document_t *)d->parsed->doc;
+    /* mkr_html_doc_type rejects an XML Document at the type boundary (its type
+     * chain does not include mkr_html_doc_type). */
+    TypedData_Get_Struct(rb_doc, mkr_doc_data_t, &mkr_html_doc_type, d);
+    return (lxb_dom_document_t *)mkr_parsed_html_doc(d->parsed);
 }
 
 mkr_parsed_t *
@@ -59,13 +84,19 @@ mkr_doc_parsed(VALUE rb_doc)
     return d->parsed;
 }
 
-/* Wrap an owned mkr_parsed_t as a Makiri::Document. GC takes ownership of
- * +parsed+ (freed in dfree). Used to back a standalone DocumentFragment. */
+/* Wrap an owned mkr_parsed_t as a Document. GC takes ownership of +parsed+
+ * (freed in dfree). The Ruby leaf class is chosen by kind: a Lexbor-backed
+ * handle becomes Makiri::Document (HTML), an arena-backed one
+ * Makiri::XML::Document (§2.3). Used to back a parsed document or a standalone
+ * DocumentFragment. */
 VALUE
 mkr_wrap_document(mkr_parsed_t *parsed)
 {
+    int is_xml = (mkr_parsed_kind(parsed) == MKR_DOC_XML);
+    VALUE klass = is_xml ? mkr_cXmlDocument : mkr_cHtmlDocument;
     mkr_doc_data_t *d;
-    VALUE obj = TypedData_Make_Struct(mkr_cDocument, mkr_doc_data_t, &mkr_doc_type, d);
+    VALUE obj = TypedData_Make_Struct(klass, mkr_doc_data_t,
+                                      is_xml ? &mkr_xml_doc_type : &mkr_html_doc_type, d);
     d->parsed = parsed;
     d->errors = rb_ary_new();
     return obj;
@@ -95,7 +126,7 @@ mkr_resolve_fragment_context(lxb_dom_document_t *doc, VALUE context,
     }
 
     if (rb_obj_is_kind_of(context, mkr_cNode)) {
-        lxb_dom_node_t *cn = mkr_node_unwrap(context);
+        lxb_dom_node_t *cn = mkr_html_node_unwrap(context);   /* reject an XML node before lxb use */
         if (cn->type != LXB_DOM_NODE_TYPE_ELEMENT) {
             rb_raise(rb_eArgError, "fragment context node must be an element");
         }
@@ -207,7 +238,39 @@ mkr_sanitize_html_input(VALUE html, const lxb_char_t **out, size_t *out_len,
     /* Browser-compatible decoding: invalid UTF-8 -> U+FFFD; valid input is used
      * in place (no copy, *owned == NULL). Returns -1 on OOM (nothing allocated)
      * so the caller can release its parser before raising. */
-    mkr_ruby_borrowed_bytes_t hv = mkr_ruby_bytes_view(html);
+    VALUE u8 = mkr_ruby_to_utf8(html); /* honour the input encoding (-> UTF-8) */
+    mkr_ruby_borrowed_bytes_t hv = mkr_ruby_bytes_view(u8);
+
+    if (u8 != html) {
+        /* Transcoded to UTF-8: a fresh String that nothing keeps alive past this
+         * return, so we must NOT borrow its bytes. It is already valid UTF-8, so
+         * copy it into an owned buffer (the caller frees *owned) - no sanitise. */
+        size_t n = (hv.len > 0) ? hv.len : 1;
+        char  *buf = mkr_reallocarray(NULL, n, 1);
+        if (buf == NULL) {
+            RB_GC_GUARD(hv.value);
+            return -1;
+        }
+        if (hv.len > 0) {
+            memcpy(buf, hv.ptr, hv.len);
+        }
+        *owned   = (lxb_char_t *)buf;
+        *out     = (const lxb_char_t *)buf;
+        *out_len = hv.len;
+        RB_GC_GUARD(hv.value);
+        return 0;
+    }
+
+    /* Not transcoded (UTF-8 / US-ASCII / binary): input Ruby already knows is
+     * valid UTF-8 is borrowed in place (the caller keeps `html` alive);
+     * otherwise sanitise as before. */
+    if (mkr_ruby_str_known_valid_utf8(html)) {
+        *owned   = NULL;
+        *out     = (const lxb_char_t *)hv.ptr;
+        *out_len = hv.len;
+        RB_GC_GUARD(hv.value);
+        return 0;
+    }
     lxb_char_t *clean = NULL;
     size_t      clean_len = 0;
     if (mkr_utf8_sanitize((const lxb_char_t *)hv.ptr, hv.len, &clean, &clean_len) != 0) {
@@ -249,7 +312,7 @@ mkr_import_fragment_children(lxb_dom_document_t *doc, lxb_dom_node_t *root,
 }
 
 /* Node#clone_node(deep = false): a shallow (or deep, with deep truthy) copy of
- * this node, owned by the same document and detached from any parent — the DOM
+ * this node, owned by the same document and detached from any parent - the DOM
  * cloneNode, whose `deep` defaults to false (a missing/nil/false argument =>
  * shallow). Built on the same import_node + <template>-content fixup the
  * fragment parser uses, so a deep-cloned <template> carries its contents (which
@@ -262,7 +325,7 @@ mkr_node_clone_node(int argc, VALUE *argv, VALUE self)
     rb_scan_args(argc, argv, "01", &deep_v);
     bool deep = RTEST(deep_v);
 
-    lxb_dom_node_t *node = mkr_node_unwrap(self);
+    lxb_dom_node_t *node = mkr_html_node_unwrap(self);
     lxb_dom_document_t *doc = node->owner_document;
 
     lxb_dom_node_t *clone = lxb_dom_document_import_node(doc, node, deep);
@@ -272,11 +335,11 @@ mkr_node_clone_node(int argc, VALUE *argv, VALUE self)
     if (deep) {
         mkr_fixup_template_content(doc, node, clone);
     }
-    return mkr_wrap_node(clone, mkr_node_document(self));
+    return mkr_wrap_html_node(clone, mkr_node_document(self));
 }
 
 /* Document#import_node(node, deep = false): a shallow (or deep, with deep
- * truthy) copy of +node+ owned by THIS document — the DOM importNode, whose
+ * truthy) copy of +node+ owned by THIS document - the DOM importNode, whose
  * `deep` defaults to false (a missing/nil/false argument => shallow). Unlike
  * Node#clone_node, the copy is owned by the receiver rather than the node's own
  * document, so it is the way to bring a node across documents (Makiri never
@@ -290,8 +353,8 @@ mkr_doc_import_node(int argc, VALUE *argv, VALUE self)
     rb_scan_args(argc, argv, "11", &node_v, &deep_v);
     bool deep = RTEST(deep_v);
 
-    lxb_dom_node_t   *src = mkr_node_unwrap(node_v);
-    lxb_dom_document_t *doc = mkr_doc_unwrap(self);
+    lxb_dom_node_t   *src = mkr_html_node_unwrap(node_v);   /* reject an XML node before lxb use */
+    lxb_dom_document_t *doc = mkr_html_doc_unwrap(self);
 
     lxb_dom_node_t *imp = lxb_dom_document_import_node(doc, src, deep);
     if (imp == NULL) {
@@ -300,7 +363,7 @@ mkr_doc_import_node(int argc, VALUE *argv, VALUE self)
     if (deep) {
         mkr_fixup_template_content(doc, src, imp);
     }
-    return mkr_wrap_node(imp, self);
+    return mkr_wrap_html_node(imp, self);
 }
 
 /* Parse +rb_html+ as a fragment in the given (tag id, namespace) context and
@@ -315,7 +378,7 @@ mkr_build_fragment_ctx(VALUE document, VALUE rb_html,
                        lxb_tag_id_t ctx_tag, lxb_ns_id_t ctx_ns)
 {
     VALUE html = rb_String(rb_html);
-    lxb_dom_document_t *doc = mkr_doc_unwrap(document);
+    lxb_dom_document_t *doc = mkr_html_doc_unwrap(document);
 
     lxb_dom_document_fragment_t *frag = lxb_dom_document_fragment_interface_create(doc);
     if (frag == NULL) {
@@ -349,7 +412,7 @@ mkr_build_fragment_ctx(VALUE document, VALUE rb_html,
 
     lxb_html_parser_destroy(parser);
     RB_GC_GUARD(html);
-    return mkr_wrap_node(frag_node, document);
+    return mkr_wrap_html_node(frag_node, document);
 }
 
 /* document.fragment(html, context: ...) -> DocumentFragment bound to this
@@ -363,7 +426,7 @@ mkr_doc_fragment(int argc, VALUE *argv, VALUE self)
                                 : rb_hash_aref(opts, ID2SYM(rb_intern("context")));
     lxb_tag_id_t tag;
     lxb_ns_id_t  ns;
-    mkr_resolve_fragment_context(mkr_doc_unwrap(self), context, &tag, &ns);
+    mkr_resolve_fragment_context(mkr_html_doc_unwrap(self), context, &tag, &ns);
     return mkr_build_fragment_ctx(self, html, tag, ns);
 }
 
@@ -379,14 +442,14 @@ mkr_frag_s_parse(int argc, VALUE *argv, VALUE klass)
                                 : rb_hash_aref(opts, ID2SYM(rb_intern("context")));
 
     static const lxb_char_t shell[] = "<html><body></body></html>";
-    mkr_parsed_t *parsed = mkr_parse_html(shell, sizeof(shell) - 1);
+    mkr_parsed_t *parsed = mkr_parse_html(shell, sizeof(shell) - 1, true);
     if (parsed == NULL) {
         rb_raise(mkr_eError, "failed to create fragment document");
     }
     VALUE document = mkr_wrap_document(parsed); /* GC now owns parsed */
     lxb_tag_id_t tag;
     lxb_ns_id_t  ns;
-    mkr_resolve_fragment_context(mkr_doc_unwrap(document), context, &tag, &ns);
+    mkr_resolve_fragment_context(mkr_html_doc_unwrap(document), context, &tag, &ns);
     return mkr_build_fragment_ctx(document, html, tag, ns);
 }
 
@@ -396,7 +459,7 @@ mkr_frag_s_parse(int argc, VALUE *argv, VALUE klass)
 static VALUE
 mkr_node_parse(VALUE self, VALUE rb_html)
 {
-    lxb_dom_node_t *node = mkr_node_unwrap(self);
+    lxb_dom_node_t *node = mkr_html_node_unwrap(self);
     if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
         rb_raise(rb_eArgError, "Node#parse requires an element context");
     }
@@ -415,6 +478,7 @@ mkr_node_parse(VALUE self, VALUE rb_html)
 typedef struct {
     const lxb_char_t *src;
     size_t            len;
+    bool              assume_valid;
     mkr_parsed_t     *result;
 } mkr_parse_nogvl_t;
 
@@ -425,7 +489,7 @@ static void *
 mkr_parse_nogvl(void *p)
 {
     mkr_parse_nogvl_t *a = (mkr_parse_nogvl_t *)p;
-    a->result = mkr_parse_html(a->src, a->len);
+    a->result = mkr_parse_html(a->src, a->len, a->assume_valid);
     return NULL;
 }
 
@@ -440,11 +504,16 @@ static VALUE
 mkr_doc_s_parse(VALUE klass, VALUE rb_source)
 {
     StringValue(rb_source);
+    /* Honour the input's encoding: UTF-8/US-ASCII/binary pass through (no
+     * degradation), anything else is transcoded to UTF-8 so its content is
+     * preserved rather than read as raw UTF-8 bytes. */
+    rb_source = mkr_ruby_to_utf8(rb_source);
 
     /* Allocate the wrapper first (with parsed == NULL) so that if parsing
-     * fails the GC-managed object frees cleanly. */
+     * fails the GC-managed object frees cleanly. This is the HTML parse entry
+     * (defined on Makiri::HTML::Document), so the result is always HTML. */
     mkr_doc_data_t *d;
-    VALUE obj = TypedData_Make_Struct(klass, mkr_doc_data_t, &mkr_doc_type, d);
+    VALUE obj = TypedData_Make_Struct(klass, mkr_doc_data_t, &mkr_html_doc_type, d);
     d->parsed = NULL;
     d->errors = rb_ary_new();
 
@@ -457,9 +526,14 @@ mkr_doc_s_parse(VALUE klass, VALUE rb_source)
     if (mkr_ruby_copy_bytes(rb_source, &source) != 0) {
         rb_raise(mkr_eError, "out of memory copying source");
     }
+    /* Read the coderange (no scan) before releasing the GVL; the copy is
+     * byte-identical, so a source Ruby already knows is valid UTF-8 lets the
+     * parse skip its sanitisation scan. */
+    bool assume_valid = mkr_ruby_str_known_valid_utf8(rb_source);
     RB_GC_GUARD(rb_source);
 
-    mkr_parse_nogvl_t args = { (const lxb_char_t *)source.ptr, source.len, NULL };
+    mkr_parse_nogvl_t args = { (const lxb_char_t *)source.ptr, source.len,
+                               assume_valid, NULL };
     rb_thread_call_without_gvl(mkr_parse_nogvl, &args, NULL, NULL);
     mkr_owned_bytes_clear(&source);
 
@@ -479,8 +553,8 @@ mkr_doc_s_parse(VALUE klass, VALUE rb_source)
 static VALUE
 mkr_doc_root(VALUE self)
 {
-    lxb_dom_document_t *doc = mkr_doc_unwrap(self);
-    return mkr_wrap_node(lxb_dom_document_root(doc), self);
+    lxb_dom_document_t *doc = mkr_html_doc_unwrap(self);
+    return mkr_wrap_html_node(lxb_dom_document_root(doc), self);
 }
 
 /* Get the document <title>, or "" if absent. */
@@ -489,7 +563,7 @@ mkr_doc_title(VALUE self)
 {
     size_t len = 0;
     const lxb_char_t *str =
-        lxb_html_document_title((lxb_html_document_t *)mkr_doc_unwrap(self), &len);
+        lxb_html_document_title((lxb_html_document_t *)mkr_html_doc_unwrap(self), &len);
     return (str == NULL) ? rb_utf8_str_new("", 0)
                          : rb_utf8_str_new((const char *)str, len);
 }
@@ -500,10 +574,10 @@ mkr_doc_title(VALUE self)
 static VALUE
 mkr_doc_internal_subset(VALUE self)
 {
-    lxb_dom_node_t *doc = (lxb_dom_node_t *)mkr_doc_unwrap(self);
+    lxb_dom_node_t *doc = (lxb_dom_node_t *)mkr_html_doc_unwrap(self);
     for (lxb_dom_node_t *c = doc->first_child; c != NULL; c = c->next) {
         if (c->type == LXB_DOM_NODE_TYPE_DOCUMENT_TYPE) {
-            return mkr_wrap_node(c, self);
+            return mkr_wrap_html_node(c, self);
         }
     }
     return Qnil;
@@ -515,7 +589,7 @@ mkr_doc_internal_subset(VALUE self)
 static VALUE
 mkr_doc_quirks_mode(VALUE self)
 {
-    return INT2NUM((int)mkr_doc_unwrap(self)->compat_mode);
+    return INT2NUM((int)mkr_html_doc_unwrap(self)->compat_mode);
 }
 
 /* Parse warnings. Reserved; currently always empty. */
@@ -530,18 +604,18 @@ mkr_doc_errors(VALUE self)
 void
 mkr_init_document(void)
 {
-    rb_define_singleton_method(mkr_cDocument, "_parse", mkr_doc_s_parse, 1);
-    rb_define_method(mkr_cDocument, "root",     mkr_doc_root,     0);
-    rb_define_method(mkr_cDocument, "title",    mkr_doc_title,    0);
-    rb_define_method(mkr_cDocument, "errors",   mkr_doc_errors,   0);
-    rb_define_method(mkr_cDocument, "internal_subset", mkr_doc_internal_subset, 0);
-    rb_define_method(mkr_cDocument, "quirks_mode", mkr_doc_quirks_mode, 0);
-    rb_define_method(mkr_cDocument, "fragment", mkr_doc_fragment, -1);
-    rb_define_method(mkr_cDocument, "import_node", mkr_doc_import_node, -1);
+    rb_define_singleton_method(mkr_cHtmlDocument, "_parse", mkr_doc_s_parse, 1);
+    rb_define_method(mkr_cHtmlDocument, "root",     mkr_doc_root,     0);
+    rb_define_method(mkr_cHtmlDocument, "title",    mkr_doc_title,    0);
+    rb_define_method(mkr_cHtmlDocument, "errors",   mkr_doc_errors,   0);
+    rb_define_method(mkr_cHtmlDocument, "internal_subset", mkr_doc_internal_subset, 0);
+    rb_define_method(mkr_cHtmlDocument, "quirks_mode", mkr_doc_quirks_mode, 0);
+    rb_define_method(mkr_cHtmlDocument, "fragment", mkr_doc_fragment, -1);
+    rb_define_method(mkr_cHtmlDocument, "import_node", mkr_doc_import_node, -1);
 
     rb_define_singleton_method(mkr_cDocumentFragment, "parse", mkr_frag_s_parse, -1);
 
     /* Node#parse(html): fragment-parse in this element's context (Nokogiri
      * compatible). Defined here, next to the fragment machinery it reuses. */
-    rb_define_method(mkr_cNode, "parse", mkr_node_parse, 1);
+    rb_define_method(mkr_mHtmlNodeMethods, "parse", mkr_node_parse, 1);
 }

data/ext/makiri/glue/ruby_html_css.c

@@ -0,0 +1,246 @@
+#include "glue.h"
+
+#include <lexbor/css/css.h>
+#include <lexbor/selectors/selectors.h>
+
+/*
+ * CSS selector queries, delegated to Lexbor's lxb_selectors engine.
+ *
+ *   Node#css(selector)    -> NodeSet (descendants matching, document order)
+ *   Node#at_css(selector) -> first matching descendant, or nil
+ *
+ * The Lexbor CSS engine (selector parser + its arena + the traversal engine) is
+ * built once and reused for every query. CSS evaluation always holds the GVL (it
+ * never releases it), so all queries are serialized and a single process-global
+ * engine is safe with no locking. Creating and tearing the engine down per call
+ * - four create/init/destroy triples - dominated a cheap query like
+ * at_css('#id') (the match is found almost immediately, so setup IS the cost);
+ * reusing it closes the gap to nokolexbor, which caches the same objects in
+ * thread-local storage. Between calls only the parsed selector list's arena is
+ * reset (lxb_css_memory_clean) and the parser is returned to its CLEAN stage
+ * (lxb_css_parser_clean) - both preserve the memory/selectors objects set once;
+ * the selectors parse-state is auto-cleaned by the parser and the traversal
+ * engine self-cleans after each find/match. A malformed selector raises
+ * Makiri::CSS::SyntaxError.
+ */
+
+/* Process-global CSS engine, created lazily and kept for the process lifetime
+ * (one small allocation). parser->memory / parser->selectors are set once so the
+ * parser reuses the same selector arena + parse state across calls. */
+static lxb_css_memory_t    *g_css_mem;
+static lxb_css_parser_t    *g_css_parser;
+static lxb_css_selectors_t *g_css_sel;
+static lxb_selectors_t     *g_selectors;
+static int                  g_css_ready;
+
+/* Build the shared engine on first use; raises Makiri::Error on init failure
+ * (leaving the globals unset, so a later call retries). */
+static void
+mkr_css_engine_init(void)
+{
+    if (g_css_ready) {
+        return;
+    }
+
+    lxb_css_memory_t    *mem       = lxb_css_memory_create();
+    lxb_css_parser_t    *parser    = lxb_css_parser_create();
+    lxb_css_selectors_t *css_sel   = lxb_css_selectors_create();
+    lxb_selectors_t     *selectors = lxb_selectors_create();
+
+    int ok = (mem != NULL && parser != NULL && css_sel != NULL && selectors != NULL)
+          && (lxb_css_memory_init(mem, 128) == LXB_STATUS_OK)
+          && (lxb_css_parser_init(parser, NULL) == LXB_STATUS_OK)
+          && (lxb_css_selectors_init(css_sel) == LXB_STATUS_OK)
+          && (lxb_selectors_init(selectors) == LXB_STATUS_OK);
+
+    if (!ok) {
+        if (selectors != NULL) lxb_selectors_destroy(selectors, true);
+        if (parser != NULL)    lxb_css_parser_destroy(parser, true);
+        if (mem != NULL)       lxb_css_memory_destroy(mem, true);
+        if (css_sel != NULL)   lxb_css_selectors_destroy(css_sel, true);
+        rb_raise(mkr_eError, "failed to initialise CSS selector engine");
+    }
+
+    lxb_css_parser_memory_set(parser, mem);
+    lxb_css_parser_selectors_set(parser, css_sel);
+
+    g_css_mem    = mem;
+    g_css_parser = parser;
+    g_css_sel    = css_sel;
+    g_selectors  = selectors;
+    g_css_ready  = 1;
+}
+
+typedef struct {
+    VALUE           set;
+    lxb_dom_node_t *root;       /* excluded from results: css is descendant-only */
+    size_t          count;
+    int             overflow;
+} mkr_css_ctx_t;
+
+static lxb_status_t
+mkr_css_find_cb(lxb_dom_node_t *node, lxb_css_selector_specificity_t spec,
+                void *ctx_)
+{
+    (void)spec;
+    mkr_css_ctx_t *c = (mkr_css_ctx_t *)ctx_;
+
+    if (node == c->root) {
+        return LXB_STATUS_OK; /* descendant-only, like Nokogiri's node.css */
+    }
+    if (c->count >= MKR_NODE_SET_MAX) {
+        c->overflow = 1;
+        return LXB_STATUS_STOP; /* fail closed without raising mid-traversal */
+    }
+
+    mkr_node_set_push(c->set, (mkr_raw_node_t *)node);
+    c->count++;
+    return LXB_STATUS_OK;
+}
+
+/* at_css: capture the first matching descendant and stop. Avoids materialising a
+ * NodeSet (and a Ruby #first dispatch) for the one node the caller wants. */
+typedef struct {
+    lxb_dom_node_t *root;       /* excluded: descendant-only */
+    lxb_dom_node_t *found;
+} mkr_css_first_ctx_t;
+
+static lxb_status_t
+mkr_css_first_cb(lxb_dom_node_t *node, lxb_css_selector_specificity_t spec,
+                 void *ctx_)
+{
+    (void)spec;
+    mkr_css_first_ctx_t *c = (mkr_css_first_ctx_t *)ctx_;
+
+    if (node == c->root) {
+        return LXB_STATUS_OK; /* descendant-only */
+    }
+    c->found = node;
+    return LXB_STATUS_STOP;
+}
+
+/* Callback for matches?: signals that the node matched the selector. */
+static lxb_status_t
+mkr_css_match_cb(lxb_dom_node_t *node, lxb_css_selector_specificity_t spec,
+                 void *ctx_)
+{
+    (void)node; (void)spec;
+    *(int *)ctx_ = 1;
+    return LXB_STATUS_STOP;
+}
+
+/* Parse +rb_selector+ with the shared engine, hand the parsed list to +run+
+ * (the actual find / match against +node+), then reset the engine for the next
+ * call. Raises Makiri::CSS::SyntaxError on a bad selector; any result-specific
+ * limits are checked by the caller after return. */
+static void
+mkr_with_compiled_selector(VALUE rb_selector, lxb_dom_node_t *node,
+                           lxb_status_t (*run)(lxb_selectors_t *, lxb_dom_node_t *,
+                                               lxb_css_selector_list_t *, void *),
+                           void *u)
+{
+    mkr_ruby_borrowed_text_t sv = mkr_ruby_verified_text(rb_selector, "CSS selector");
+
+    mkr_css_engine_init(); /* raises on init failure */
+
+    lxb_css_selector_list_t *list =
+        lxb_css_selectors_parse(g_css_parser, (const lxb_char_t *)sv.ptr, sv.len);
+
+    int syntax_error = (list == NULL || g_css_parser->status != LXB_STATUS_OK);
+    if (!syntax_error) {
+        (void)run(g_selectors, node, list, u);
+    }
+
+    /* Reset the shared engine for the next query: drop the parsed list's arena
+     * allocations and return the parser to its CLEAN stage. Both preserve the
+     * memory/selectors objects we set once; the traversal engine self-cleans
+     * after find/match. */
+    lxb_css_memory_clean(g_css_mem);
+    lxb_css_parser_clean(g_css_parser);
+
+    if (syntax_error) {
+        rb_raise(mkr_eCSSSyntaxError, "invalid CSS selector: %" PRIsVALUE, sv.value);
+    }
+    RB_GC_GUARD(sv.value);
+}
+
+/* find: collect descendants matching the selector (MATCH_FIRST dedups a node
+ * that matches several selectors in a comma list). */
+static lxb_status_t
+mkr_run_find(lxb_selectors_t *selectors, lxb_dom_node_t *root,
+             lxb_css_selector_list_t *list, void *u)
+{
+    lxb_selectors_opt_set(selectors, LXB_SELECTORS_OPT_MATCH_FIRST);
+    return lxb_selectors_find(selectors, root, list, mkr_css_find_cb, u);
+}
+
+/* find_first: stop at the first matching descendant (for at_css). */
+static lxb_status_t
+mkr_run_find_first(lxb_selectors_t *selectors, lxb_dom_node_t *root,
+                   lxb_css_selector_list_t *list, void *u)
+{
+    lxb_selectors_opt_set(selectors, LXB_SELECTORS_OPT_MATCH_FIRST);
+    return lxb_selectors_find(selectors, root, list, mkr_css_first_cb, u);
+}
+
+/* match_node: does THIS node match? */
+static lxb_status_t
+mkr_run_match(lxb_selectors_t *selectors, lxb_dom_node_t *node,
+              lxb_css_selector_list_t *list, void *u)
+{
+    return lxb_selectors_match_node(selectors, node, list, mkr_css_match_cb, u);
+}
+
+/* Node#css: collect every matching descendant into a NodeSet (document order).
+ * Raises Makiri::CSS::SyntaxError on a bad selector, Makiri::Error on an
+ * over-large result. */
+static VALUE
+mkr_node_css(VALUE self, VALUE rb_selector)
+{
+    lxb_dom_node_t *root = mkr_html_node_unwrap(self);
+    VALUE document = mkr_node_document(self);
+    VALUE set = mkr_node_set_new(document);
+
+    mkr_css_ctx_t ctx = { .set = set, .root = root, .count = 0, .overflow = 0 };
+    mkr_with_compiled_selector(rb_selector, root, mkr_run_find, &ctx);
+
+    if (ctx.overflow) {
+        rb_raise(mkr_eError, "CSS result set exceeded the node limit (%u)",
+                 MKR_NODE_SET_MAX);
+    }
+    return set;
+}
+
+/* Node#at_css: the first matching descendant, or nil. */
+static VALUE
+mkr_node_at_css(VALUE self, VALUE rb_selector)
+{
+    lxb_dom_node_t *root = mkr_html_node_unwrap(self);
+
+    mkr_css_first_ctx_t ctx = { .root = root, .found = NULL };
+    mkr_with_compiled_selector(rb_selector, root, mkr_run_find_first, &ctx);
+
+    return ctx.found != NULL
+        ? mkr_wrap_html_node(ctx.found, mkr_node_document(self))
+        : Qnil;
+}
+
+/* Node#matches?(selector): does THIS node match the CSS selector? (Like
+ * Nokogiri - tested against the node itself, not its descendants.) A malformed
+ * selector raises Makiri::CSS::SyntaxError. */
+static VALUE
+mkr_node_matches(VALUE self, VALUE rb_selector)
+{
+    lxb_dom_node_t *node = mkr_html_node_unwrap(self);
+    int matched = 0;
+    mkr_with_compiled_selector(rb_selector, node, mkr_run_match, &matched);
+    return matched ? Qtrue : Qfalse;
+}
+
+void
+mkr_init_css(void)
+{
+    rb_define_method(mkr_mHtmlNodeMethods, "css",     mkr_node_css,     1);
+    rb_define_method(mkr_mHtmlNodeMethods, "at_css",  mkr_node_at_css,  1);
+    rb_define_method(mkr_mHtmlNodeMethods, "matches?", mkr_node_matches, 1);
+}