cataract 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67046f0d371d7b0b077971e8634ff4054e64fe23a55c80b1a9f80e3dee6d804b
-  data.tar.gz: 776865b7490e22c326c0bab93a3da32f088177817b3e237c68b66e233df39021
+  metadata.gz: 4f107809adb744598338be592626fc5ebbfdb81c2813957c7e5ed1652f37a607
+  data.tar.gz: 810a6aadbe0a8c2ce4eff7c307c17c9de354f1a3bc0d9509ae4e83f1d7e1c8b0
 SHA512:
-  metadata.gz: 21f5ccd9b4ed3e0831fa8723d02493b7b4a3582c359a3e3bae927e554d207422a0139592b23889d273ca1ed3a1888679c729d9ad0f4aa2bf4c90d18b2e16fe0c
-  data.tar.gz: f149256218337a47a1b27cd945857dd358199ceb47f70274c0c7db5cb3fa196d84a55281528c0f22d12da4bbbaff3b92c6e315210906a75aee2d304a9b91c275
+  metadata.gz: b7e85ed2f9ad0b9154e78c795bc0548ca1eaeb55f8f24b2b644852394a506173afb64042f55a3c02c13c21e1b539738695a83c8f774aaf0311bdda8f00da42b9
+  data.tar.gz: f6ea7361ad3d180aaf9e4faa72bf686906a0f81345df59f70856734e50f17b79d4dc20823d0fae520279767cd289fb8e42bbd619230f095d1d26f9ed95aa1094

data/.yardopts

@@ -0,0 +1,9 @@
+--output-dir docs
+--readme README.md
+--title 'Cataract - Fast CSS Parser'
+--exclude lib/cataract/pure\.rb
+--exclude lib/cataract/pure/
+lib/**/*.rb
+ext/**/*.c
+-
+docs/files/EXAMPLE.md

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.5.0] - 2026-07-09
+
+- Feature: `@supports (condition) { ... }` now preserves its condition and the rules it wraps through parse -> serialize, in both backends - previously the condition was discarded entirely and the wrapped rules were silently flattened into the surrounding document with no trace of ever being conditional.
+- Feature: `@container name (condition) { ... }` (container queries) now preserves its name, condition, and wrapped rules the same way - handles named, anonymous, and name-only forms, and nests correctly with `@media`/`@supports`/itself.
+- Feature: `@layer` (cascade layers) now preserves its name and wrapped rules, both in block form (`@layer name { ... }`, including anonymous and dotted/nested names like `framework.layout`) and statement form (`@layer a, b;`, which declares layer order with no wrapped rules at all - previously silently corrupted parsing of whatever rule came right after it).
+- Fix: `@media`/`@supports`/`@container`/`@scope`/`@layer` with no whitespace before a following `(` (e.g. minified `@supports(display:grid){...}`) no longer misparses the at-rule name, which silently corrupted the rest of the block. Present in both backends since `@media`/`@supports` shipped.
+- Feature: `@namespace` (default and prefixed, e.g. `@namespace svg url(http://www.w3.org/2000/svg);`) is now preserved through parse -> serialize, in both backends - previously it wasn't modelled at all. Namespaced selectors (`ns|E`, `*|E`, `|E`, and the attribute-selector equivalents) already parsed as opaque text, but their specificity was miscounted - a namespace prefix was counted as its own type selector instead of contributing nothing, e.g. `svg|rect` computed as specificity 2 instead of 1. Both are fixed now.
+
 ## [0.4.0] - 2026-07-08
 
 - Fix: `Declarations.new(some_string)` (standalone CSS declaration-block parsing) now works under the pure Ruby backend (`CATARACT_PURE=1`) - previously raised `NoMethodError`.

data/ext/cataract/cataract.c

@@ -9,6 +9,7 @@ VALUE cAtRule;
 VALUE cStylesheet;
 VALUE cImportStatement;
 VALUE cMediaQuery;
+VALUE cConditionalGroup;
 
 // Error class definitions (shared with main extension)
 VALUE eCataractError;
@@ -168,6 +169,13 @@ static void serialize_at_rule(VALUE result, VALUE at_rule) {
     VALUE selector = rb_struct_aref(at_rule, INT2FIX(AT_RULE_SELECTOR));
     VALUE content = rb_struct_aref(at_rule, INT2FIX(AT_RULE_CONTENT));
 
+    if (NIL_P(content)) {
+        // Statement form (e.g. `@layer a, b;`) - no block to wrap.
+        rb_str_append(result, selector);
+        rb_str_cat2(result, ";\n");
+        return;
+    }
+
     rb_str_append(result, selector);
     rb_str_cat2(result, " {\n");
 
@@ -277,6 +285,14 @@ static void serialize_at_rule_formatted(VALUE result, VALUE at_rule, const char
     VALUE selector = rb_struct_aref(at_rule, INT2FIX(AT_RULE_SELECTOR));
     VALUE content = rb_struct_aref(at_rule, INT2FIX(AT_RULE_CONTENT));
 
+    if (NIL_P(content)) {
+        // Statement form (e.g. `@layer a, b;`) - no block to wrap.
+        rb_str_cat2(result, indent);
+        rb_str_append(result, selector);
+        rb_str_cat2(result, ";\n");
+        return;
+    }
+
     rb_str_cat2(result, indent);
     rb_str_append(result, selector);
     rb_str_cat2(result, " {\n");
@@ -408,6 +424,77 @@ static VALUE build_rules_by_id(VALUE rules_array) {
     return rules_by_id;
 }
 
+// A rule's conditional-group wrapping chain, outermost first, found by
+// walking parent_id from its own conditional_group_id up to the root. Only
+// @supports currently populates conditional_group_id (see the parser), but
+// this walks whatever's there generically.
+static VALUE conditional_group_chain(VALUE conditional_groups, VALUE conditional_group_id) {
+    VALUE chain = rb_ary_new();
+    VALUE id = conditional_group_id;
+    while (!NIL_P(id)) {
+        VALUE group = rb_ary_entry(conditional_groups, FIX2INT(id));
+        if (NIL_P(group)) break;
+
+        rb_ary_unshift(chain, group);
+        id = rb_struct_aref(group, INT2FIX(CONDITIONAL_GROUP_PARENT_ID));
+    }
+    return chain;
+}
+
+// Reconcile the currently-open conditional-group blocks with the ones a
+// rule needs, like diffing two paths down a tree: close whatever's open
+// past where the chains diverge (innermost first), then open whatever the
+// target chain adds from that point on. Nested entirely inside whatever
+// media block is currently open (conditional groups don't affect media
+// context). Returns target_chain, for the caller to track as current.
+static VALUE sync_conditional_group_chain(VALUE result, VALUE current_chain, VALUE target_chain, const char *indent) {
+    long current_len = RARRAY_LEN(current_chain);
+    long target_len = RARRAY_LEN(target_chain);
+    long common = 0;
+    while (common < current_len && common < target_len) {
+        VALUE cur_id = rb_struct_aref(rb_ary_entry(current_chain, common), INT2FIX(CONDITIONAL_GROUP_ID));
+        VALUE tgt_id = rb_struct_aref(rb_ary_entry(target_chain, common), INT2FIX(CONDITIONAL_GROUP_ID));
+        if (!rb_equal(cur_id, tgt_id)) break;
+
+        common++;
+    }
+
+    for (long i = current_len - 1; i >= common; i--) {
+        rb_str_cat2(result, indent);
+        rb_str_cat2(result, "}\n");
+    }
+
+    for (long i = common; i < target_len; i++) {
+        VALUE group = rb_ary_entry(target_chain, i);
+        VALUE name = rb_struct_aref(group, INT2FIX(CONDITIONAL_GROUP_NAME));
+        VALUE condition = rb_struct_aref(group, INT2FIX(CONDITIONAL_GROUP_CONDITION));
+
+        rb_str_cat2(result, indent);
+        rb_str_cat2(result, "@");
+        rb_str_append(result, rb_sym2str(rb_struct_aref(group, INT2FIX(CONDITIONAL_GROUP_TYPE))));
+        if (!NIL_P(name) || !NIL_P(condition)) {
+            rb_str_cat2(result, " ");
+            if (!NIL_P(name)) {
+                rb_str_append(result, name);
+                if (!NIL_P(condition)) rb_str_cat2(result, " ");
+            }
+            if (!NIL_P(condition)) {
+                rb_str_append(result, condition);
+            }
+        }
+        rb_str_cat2(result, " {\n");
+    }
+
+    return target_chain;
+}
+
+static void close_conditional_groups(VALUE result, long count, const char *indent) {
+    for (long i = 0; i < count; i++) {
+        rb_str_cat2(result, indent);
+        rb_str_cat2(result, "}\n");
+    }
+}
+
 // Rule and AtRule don't share a member layout past their first few fields
 // (see the AT_RULE_* comment in cataract.h), so reading parent_rule_id or
 // media_query_id off a rule of unknown type needs to dispatch on which
@@ -425,6 +512,12 @@ static inline VALUE rule_media_query_id_of(VALUE rule) {
         : rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
 }
 
+static inline VALUE rule_conditional_group_id_of(VALUE rule) {
+    return rb_obj_is_kind_of(rule, cAtRule)
+        ? rb_struct_aref(rule, INT2FIX(AT_RULE_CONDITIONAL_GROUP_ID))
+        : rb_struct_aref(rule, INT2FIX(RULE_CONDITIONAL_GROUP_ID));
+}
+
 // Formatting options for stylesheet serialization
 // Avoids mode flags and if/else branches - all behavior controlled by struct values
 struct format_opts {
@@ -564,6 +657,7 @@ static VALUE serialize_stylesheet_with_grouping(
     VALUE media_query_lists,
     VALUE result,
     VALUE selector_lists,
+    VALUE conditional_groups,
     const struct format_opts *opts
 ) {
     long total_rules = RARRAY_LEN(rules_array);
@@ -589,6 +683,7 @@ static VALUE serialize_stylesheet_with_grouping(
     // Iterate through rules in insertion order, grouping consecutive media queries
     VALUE current_media = Qnil;
     int in_media_block = 0;
+    VALUE current_cg_chain = rb_ary_new();
 
     for (long i = 0; i < total_rules; i++) {
         VALUE rule = rb_ary_entry(rules_array, i);
@@ -606,10 +701,12 @@ static VALUE serialize_stylesheet_with_grouping(
             rule_media = rb_ary_entry(media_queries, FIX2INT(rule_media_query_id));
         }
         int is_first_rule = (i == 0);
+        VALUE rule_cg_chain = conditional_group_chain(conditional_groups, rule_conditional_group_id_of(rule));
 
         if (NIL_P(rule_media)) {
             // Not in any media query - close any open media block first
             if (in_media_block) {
+                current_cg_chain = sync_conditional_group_chain(result, current_cg_chain, rb_ary_new(), opts->media_indent);
                 rb_str_cat2(result, "}\n");
                 in_media_block = 0;
                 current_media = Qnil;
@@ -620,11 +717,15 @@ static VALUE serialize_stylesheet_with_grouping(
                 rb_str_cat2(result, "\n");
             }
 
-            serialize_rule_in_group(result, rule, rule_id, rule_media_query_id, &group_ctx, 0);
+            current_cg_chain = sync_conditional_group_chain(result, current_cg_chain, rule_cg_chain, "");
+
+            serialize_rule_in_group(result, rule, rule_id, rule_media_query_id, &group_ctx, RARRAY_LEN(current_cg_chain) > 0);
         } else {
             // This rule is in a media query
             // Check if media query changed from previous rule (compare MediaQuery objects by value)
             if (NIL_P(current_media) || !rb_equal(current_media, rule_media)) {
+                current_cg_chain = sync_conditional_group_chain(result, current_cg_chain, rb_ary_new(), opts->media_indent);
+
                 // Close previous media block if open
                 if (in_media_block) {
                     rb_str_cat2(result, "}\n");
@@ -648,19 +749,23 @@ static VALUE serialize_stylesheet_with_grouping(
                 in_media_block = 1;
             }
 
+            current_cg_chain = sync_conditional_group_chain(result, current_cg_chain, rule_cg_chain, opts->media_indent);
+
             serialize_rule_in_group(result, rule, rule_id, rule_media_query_id, &group_ctx, 1);
         }
     }
 
-    // Close final media block if still open
+    // Close final conditional-group and media blocks if still open
+    close_conditional_groups(result, RARRAY_LEN(current_cg_chain), in_media_block ? opts->media_indent : "");
     if (in_media_block) {
         rb_str_cat2(result, "}\n");
     }
 
-    // Guard hash objects we created and used throughout
+    // Guard hash/array objects we created and used throughout
     RB_GC_GUARD(mq_id_to_list_id);
     RB_GC_GUARD(rules_by_id);
     RB_GC_GUARD(processed_rule_ids);
+    RB_GC_GUARD(current_cg_chain);
     return result;
 }
 
@@ -1010,11 +1115,12 @@ static VALUE serialize_stylesheet_with_nesting(
 // this, differing only in which format_opts they select. Dispatches on has_nesting
 // to pick the selector-list-grouping serializer (no nesting - zero overhead) or the
 // parent/child lookahead serializer (has nesting).
-static VALUE stylesheet_serialize_impl(VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists, int formatted) {
+static VALUE stylesheet_serialize_impl(VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists, VALUE conditional_groups, int formatted) {
     Check_Type(rules_array, T_ARRAY);
     Check_Type(media_queries, T_ARRAY);
     if (!NIL_P(media_query_lists)) Check_Type(media_query_lists, T_HASH);
     if (!NIL_P(selector_lists)) Check_Type(selector_lists, T_HASH);
+    if (!NIL_P(conditional_groups)) Check_Type(conditional_groups, T_ARRAY);
 
     VALUE result = rb_str_new_cstr("");
 
@@ -1048,22 +1154,23 @@ static VALUE stylesheet_serialize_impl(VALUE rules_array, VALUE charset, VALUE h
 
     // Fast path: if no nesting, use the selector-list-grouping serializer (zero overhead)
     if (!RTEST(has_nesting)) {
-        return serialize_stylesheet_with_grouping(rules_array, media_queries, media_query_lists, result, selector_lists, &opts);
+        return serialize_stylesheet_with_grouping(rules_array, media_queries, media_query_lists, result, selector_lists, conditional_groups, &opts);
     }
 
     // Has nesting - use the parent/child lookahead serializer
     // TODO: Phase 2 - use selector_lists for grouping on the nesting path too
+    // TODO: conditional_groups (@supports etc.) aren't reconstructed on this path yet
     return serialize_stylesheet_with_nesting(rules_array, media_queries, media_query_lists, result, &opts);
 }
 
 // New stylesheet serialization entry point - checks for nesting and delegates
-static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists) {
-    return stylesheet_serialize_impl(rules_array, charset, has_nesting, selector_lists, media_queries, media_query_lists, 0);
+static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists, VALUE conditional_groups) {
+    return stylesheet_serialize_impl(rules_array, charset, has_nesting, selector_lists, media_queries, media_query_lists, conditional_groups, 0);
 }
 
 // Formatted version with indentation and newlines (with nesting support)
-static VALUE stylesheet_to_formatted_s(VALUE self, VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists) {
-    return stylesheet_serialize_impl(rules_array, charset, has_nesting, selector_lists, media_queries, media_query_lists, 1);
+static VALUE stylesheet_to_formatted_s(VALUE self, VALUE rules_array, VALUE charset, VALUE has_nesting, VALUE selector_lists, VALUE media_queries, VALUE media_query_lists, VALUE conditional_groups) {
+    return stylesheet_serialize_impl(rules_array, charset, has_nesting, selector_lists, media_queries, media_query_lists, conditional_groups, 1);
 }
 
 /*
@@ -1207,6 +1314,12 @@ void Init_native_extension(void) {
         rb_raise(rb_eLoadError, "Cataract::MediaQuery not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
     }
 
+    if (rb_const_defined(mCataract, rb_intern("ConditionalGroup"))) {
+        cConditionalGroup = rb_const_get(mCataract, rb_intern("ConditionalGroup"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::ConditionalGroup not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
+    }
+
     // Define Stylesheet class (Ruby will add instance methods like each_selector).
     // Declarations is left alone here - it's a plain Ruby class (declarations.rb)
     // with its own #to_s, not something this backend attaches methods to.
@@ -1219,8 +1332,8 @@ void Init_native_extension(void) {
     VALUE mNative = rb_define_module_under(mBackends, "Native");
 
     rb_define_module_function(mNative, "parse", parse_css_new, -1);
-    rb_define_module_function(mNative, "stylesheet_to_s", stylesheet_to_s, 6);
-    rb_define_module_function(mNative, "stylesheet_to_formatted_s", stylesheet_to_formatted_s, 6);
+    rb_define_module_function(mNative, "stylesheet_to_s", stylesheet_to_s, 7);
+    rb_define_module_function(mNative, "stylesheet_to_formatted_s", stylesheet_to_formatted_s, 7);
     rb_define_module_function(mNative, "parse_declarations", new_parse_declarations, 1);
     rb_define_module_function(mNative, "flatten", cataract_flatten, 1);
     rb_define_module_function(mNative, "calculate_specificity", calculate_specificity, 1);

data/ext/cataract/cataract.h

@@ -14,6 +14,7 @@ extern VALUE cAtRule;
 extern VALUE cStylesheet;
 extern VALUE cImportStatement;
 extern VALUE cMediaQuery;
+extern VALUE cConditionalGroup;
 
 // Error class references
 extern VALUE eCataractError;
@@ -25,7 +26,7 @@ extern VALUE eParseError;
 // Struct field indices
 // ============================================================================
 
-// Rule struct field indices (id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id, media_query_id)
+// Rule struct field indices (id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id, media_query_id, conditional_group_id)
 #define RULE_ID 0
 #define RULE_SELECTOR 1
 #define RULE_DECLARATIONS 2
@@ -34,6 +35,7 @@ extern VALUE eParseError;
 #define RULE_NESTING_STYLE 5
 #define RULE_SELECTOR_LIST_ID 6
 #define RULE_MEDIA_QUERY_ID 7
+#define RULE_CONDITIONAL_GROUP_ID 8
 
 // Nesting style constants
 #define NESTING_STYLE_IMPLICIT 0  // .parent { .child { } } - no &
@@ -45,13 +47,14 @@ extern VALUE eParseError;
 #define NO_PARENT_SELECTOR Qnil
 #define NO_PARENT_RULE_ID Qnil
 #define NO_MEDIA_QUERY_ID (-1)
+#define NO_CONDITIONAL_GROUP_ID (-1)
 
 // Declaration struct field indices (property, value, important)
 #define DECL_PROPERTY 0
 #define DECL_VALUE 1
 #define DECL_IMPORTANT 2
 
-// AtRule struct field indices (id, selector, content, specificity, media_query_id)
+// AtRule struct field indices (id, selector, content, specificity, media_query_id, conditional_group_id)
 // Matches Rule interface for duck-typing, but AtRule has fewer members - its
 // indices do NOT line up with Rule's past AT_RULE_SPECIFICITY (e.g. index 4
 // is media_query_id here but parent_rule_id on Rule), so never read a field
@@ -61,6 +64,14 @@ extern VALUE eParseError;
 #define AT_RULE_CONTENT 2
 #define AT_RULE_SPECIFICITY 3
 #define AT_RULE_MEDIA_QUERY_ID 4
+#define AT_RULE_CONDITIONAL_GROUP_ID 5
+
+// ConditionalGroup struct field indices (id, type, name, condition, parent_id)
+#define CONDITIONAL_GROUP_ID 0
+#define CONDITIONAL_GROUP_TYPE 1
+#define CONDITIONAL_GROUP_NAME 2
+#define CONDITIONAL_GROUP_CONDITION 3
+#define CONDITIONAL_GROUP_PARENT_ID 4
 
 // ============================================================================
 // Macros