cataract 0.2.1 → 0.2.2

data/ext/cataract/css_parser.c

@@ -17,11 +17,14 @@
 typedef struct {
     VALUE rules_array;        // Array of Rule structs
     VALUE media_index;        // Hash: Symbol => Array of rule IDs
+    VALUE selector_lists;     // Hash: list_id => Array of rule IDs
     VALUE imports_array;      // Array of ImportStatement structs
     int rule_id_counter;      // Next rule ID (0-indexed)
+    int next_selector_list_id; // Next selector list ID (0-indexed)
     int media_query_count;    // Safety limit for media queries
     st_table *media_cache;    // Parse-time cache: string => parsed media types
     int has_nesting;          // Set to 1 if any nested rules are created
+    int selector_lists_enabled; // Parser option: track selector lists (1=enabled, 0=disabled)
     int depth;                // Current recursion depth (safety limit)
 } ParserContext;
 
@@ -499,9 +502,15 @@ static VALUE parse_declarations(const char *start, const char *end) {
                          val_len, MAX_PROPERTY_VALUE_LENGTH);
             }
 
-            // Create property string and lowercase it
-            VALUE property_raw = rb_usascii_str_new(prop_start, prop_len);
-            VALUE property = lowercase_property(property_raw);
+            // Create property string - use UTF-8 to support custom properties with Unicode
+            VALUE property = rb_utf8_str_new(prop_start, prop_len);
+            // Custom properties (--foo) are case-sensitive and can contain Unicode
+            // Regular properties are ASCII-only and case-insensitive
+            if (!(prop_len >= 2 && prop_start[0] == '-' && prop_start[1] == '-')) {
+                // Regular property: force ASCII encoding and lowercase
+                rb_enc_associate(property, rb_usascii_encoding());
+                property = lowercase_property(property);
+            }
             VALUE value = rb_utf8_str_new(val_start, val_len);
 
             // Create Declaration struct
@@ -691,7 +700,8 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
                 media_declarations,
                 Qnil,  // specificity
                 parent_rule_id,  // Link to parent for nested @media serialization
-                Qnil   // nesting_style (nil for @media nesting)
+                Qnil,  // nesting_style (nil for @media nesting)
+                Qnil   // selector_list_id
             );
 
             // Mark that we have nesting (only set once)
@@ -773,7 +783,8 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
                             nested_declarations,
                             Qnil,  // specificity
                             parent_rule_id,
-                            nesting_style
+                            nesting_style,
+                            Qnil   // selector_list_id
                         );
 
                         // Mark that we have nesting (only set once)
@@ -852,8 +863,15 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
                          val_len, MAX_PROPERTY_VALUE_LENGTH);
             }
 
-            VALUE property_raw = rb_usascii_str_new(prop_start, prop_len);
-            VALUE property = lowercase_property(property_raw);
+            // Create property string - use UTF-8 to support custom properties with Unicode
+            VALUE property = rb_utf8_str_new(prop_start, prop_len);
+            // Custom properties (--foo) are case-sensitive and can contain Unicode
+            // Regular properties are ASCII-only and case-insensitive
+            if (!(prop_len >= 2 && prop_start[0] == '-' && prop_start[1] == '-')) {
+                // Regular property: force ASCII encoding and lowercase
+                rb_enc_associate(property, rb_usascii_encoding());
+                property = lowercase_property(property);
+            }
             VALUE value = rb_utf8_str_new(val_start, val_len);
 
             VALUE decl = rb_struct_new(cDeclaration,
@@ -1158,10 +1176,14 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                 ParserContext nested_ctx = {
                     .rules_array = rb_ary_new(),
                     .media_index = rb_hash_new(),
+                    .selector_lists = rb_hash_new(),
+                    .imports_array = rb_ary_new(),
                     .rule_id_counter = 0,
+                    .next_selector_list_id = 0,
                     .media_query_count = 0,
                     .media_cache = NULL,
                     .has_nesting = 0,
+                    .selector_lists_enabled = ctx->selector_lists_enabled,
                     .depth = 0
                 };
                 parse_css_recursive(&nested_ctx, block_start, block_end, NO_PARENT_MEDIA, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID);
@@ -1283,6 +1305,28 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                     // Example: ".a, .b, .c { color: red; }" creates 3 separate rules
                     //           ^selector_start      ^sel_end
                     //              ^seg_start=seg (scanning for commas)
+
+                    // Count selectors for selector list tracking
+                    int selector_count = 1;
+                    if (ctx->selector_lists_enabled) {
+                        const char *count_ptr = selector_start;
+                        while (count_ptr < sel_end) {
+                            if (*count_ptr == ',') {
+                                selector_count++;
+                            }
+                            count_ptr++;
+                        }
+                    }
+
+                    // Create selector list if enabled and multiple selectors
+                    int list_id = -1;
+                    VALUE rule_ids_array = Qnil;
+                    if (ctx->selector_lists_enabled && selector_count > 1) {
+                        list_id = ctx->next_selector_list_id++;
+                        rule_ids_array = rb_ary_new();
+                        rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
+                    }
+
                     const char *seg_start = selector_start;
                     const char *seg = selector_start;
 
@@ -1322,16 +1366,45 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                                 // Get rule ID and increment
                                 int rule_id = ctx->rule_id_counter++;
 
+                                // Determine selector_list_id value
+                                VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
+
+                                // Deep copy declarations for selector lists to avoid shared state
+                                // (principle of least surprise - modifying one rule shouldn't affect others)
+                                VALUE rule_declarations;
+                                if (list_id >= 0) {
+                                    // Deep copy: both array and Declaration structs inside
+                                    long decl_count = RARRAY_LEN(declarations);
+                                    rule_declarations = rb_ary_new_capa(decl_count);
+                                    for (long k = 0; k < decl_count; k++) {
+                                        VALUE decl = rb_ary_entry(declarations, k);
+                                        VALUE new_decl = rb_struct_new(cDeclaration,
+                                            rb_struct_aref(decl, INT2FIX(DECL_PROPERTY)),
+                                            rb_struct_aref(decl, INT2FIX(DECL_VALUE)),
+                                            rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT))
+                                        );
+                                        rb_ary_push(rule_declarations, new_decl);
+                                    }
+                                } else {
+                                    rule_declarations = rb_ary_dup(declarations);
+                                }
+
                                 // Create Rule
                                 VALUE rule = rb_struct_new(cRule,
                                     INT2FIX(rule_id),
                                     resolved_selector,
-                                    rb_ary_dup(declarations),
+                                    rule_declarations,
                                     Qnil,  // specificity
                                     parent_id_val,
-                                    nesting_style_val
+                                    nesting_style_val,
+                                    selector_list_id_val
                                 );
 
+                                // Track rule in selector list if applicable
+                                if (list_id >= 0) {
+                                    rb_ary_push(rule_ids_array, INT2FIX(rule_id));
+                                }
+
                                 // Mark that we have nesting (only set once)
                                 if (!ctx->has_nesting && !NIL_P(parent_id_val)) {
                                     ctx->has_nesting = 1;
@@ -1358,6 +1431,28 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                     //   - .a .child with declarations [font: 14px]
                     //   - .b with declarations [color: red]
                     //   - .b .child with declarations [font: 14px]
+
+                    // Count selectors for selector list tracking
+                    int selector_count = 1;
+                    if (ctx->selector_lists_enabled) {
+                        const char *count_ptr = selector_start;
+                        while (count_ptr < sel_end) {
+                            if (*count_ptr == ',') {
+                                selector_count++;
+                            }
+                            count_ptr++;
+                        }
+                    }
+
+                    // Create selector list if enabled and multiple selectors
+                    int list_id = -1;
+                    VALUE rule_ids_array = Qnil;
+                    if (ctx->selector_lists_enabled && selector_count > 1) {
+                        list_id = ctx->next_selector_list_id++;
+                        rule_ids_array = rb_ary_new();
+                        rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
+                    }
+
                     const char *seg_start = selector_start;
                     const char *seg = selector_start;
 
@@ -1407,6 +1502,9 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                                                                              resolved_current, INT2FIX(current_rule_id), parent_media_sym);
                                 ctx->depth--;
 
+                                // Determine selector_list_id value
+                                VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
+
                                 // Create parent rule and replace placeholder
                                 // Always create the rule (even if empty) to avoid edge cases
                                 VALUE rule = rb_struct_new(cRule,
@@ -1415,9 +1513,15 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                                     parent_declarations,
                                     Qnil,  // specificity
                                     current_parent_id,
-                                    current_nesting_style
+                                    current_nesting_style,
+                                    selector_list_id_val
                                 );
 
+                                // Track rule in selector list if applicable
+                                if (list_id >= 0) {
+                                    rb_ary_push(rule_ids_array, INT2FIX(current_rule_id));
+                                }
+
                                 // Mark that we have nesting (only set once)
                                 if (!ctx->has_nesting && !NIL_P(current_parent_id)) {
                                     ctx->has_nesting = 1;
@@ -1473,12 +1577,17 @@ VALUE parse_media_types(VALUE self, VALUE media_query_sym) {
  * Main parse entry point
  * Returns: { rules: [...], media_index: {...}, charset: "..." | nil, last_rule_id: N }
  */
-VALUE parse_css_new_impl(VALUE css_string, int rule_id_offset) {
+VALUE parse_css_new_impl(VALUE css_string, VALUE parser_options, int rule_id_offset) {
     Check_Type(css_string, T_STRING);
+    Check_Type(parser_options, T_HASH);
 
     DEBUG_PRINTF("\n[PARSE_NEW] ========== NEW PARSE CALL ==========\n");
     DEBUG_PRINTF("[PARSE_NEW] Input CSS (first 100 chars): %.100s\n", RSTRING_PTR(css_string));
 
+    // Read parser options
+    VALUE selector_lists_opt = rb_hash_aref(parser_options, ID2SYM(rb_intern("selector_lists")));
+    int selector_lists_enabled = (NIL_P(selector_lists_opt) || RTEST(selector_lists_opt)) ? 1 : 0;
+
     const char *css = RSTRING_PTR(css_string);
     const char *pe = css + RSTRING_LEN(css_string);
     const char *p = css;
@@ -1513,11 +1622,14 @@ VALUE parse_css_new_impl(VALUE css_string, int rule_id_offset) {
     ParserContext ctx;
     ctx.rules_array = rb_ary_new();
     ctx.media_index = rb_hash_new();
+    ctx.selector_lists = rb_hash_new();
     ctx.imports_array = rb_ary_new();
     ctx.rule_id_counter = rule_id_offset;  // Start from offset
+    ctx.next_selector_list_id = 0;  // Start from 0
     ctx.media_query_count = 0;
     ctx.media_cache = NULL;  // Removed - no perf benefit
     ctx.has_nesting = 0;  // Will be set to 1 if any nested rules are created
+    ctx.selector_lists_enabled = selector_lists_enabled;
     ctx.depth = 0;  // Start at depth 0
 
     // Parse CSS (top-level, no parent context)
@@ -1528,6 +1640,7 @@ VALUE parse_css_new_impl(VALUE css_string, int rule_id_offset) {
     VALUE result = rb_hash_new();
     rb_hash_aset(result, ID2SYM(rb_intern("rules")), ctx.rules_array);
     rb_hash_aset(result, ID2SYM(rb_intern("_media_index")), ctx.media_index);
+    rb_hash_aset(result, ID2SYM(rb_intern("_selector_lists")), ctx.selector_lists);
     rb_hash_aset(result, ID2SYM(rb_intern("imports")), ctx.imports_array);
     rb_hash_aset(result, ID2SYM(rb_intern("charset")), charset);
     rb_hash_aset(result, ID2SYM(rb_intern("last_rule_id")), INT2FIX(ctx.rule_id_counter));
@@ -1536,6 +1649,7 @@ VALUE parse_css_new_impl(VALUE css_string, int rule_id_offset) {
     RB_GC_GUARD(charset);
     RB_GC_GUARD(ctx.rules_array);
     RB_GC_GUARD(ctx.media_index);
+    RB_GC_GUARD(ctx.selector_lists);
     RB_GC_GUARD(ctx.imports_array);
     RB_GC_GUARD(result);
 

data/ext/cataract/flatten.c

@@ -623,7 +623,7 @@ struct flatten_selectors_context {
 };
 
 // Forward declaration
-static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, VALUE selector);
+static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, VALUE selector, VALUE *out_selector_list_id);
 
 // Callback for rb_hash_foreach when merging selector groups
 static int flatten_selector_group_callback(VALUE selector, VALUE group_indices, VALUE arg) {
@@ -634,8 +634,9 @@ static int flatten_selector_group_callback(VALUE selector, VALUE group_indices,
                  ctx->selector_index, ctx->total_selectors,
                  RSTRING_PTR(selector), RARRAY_LEN(group_indices));
 
-    // Merge all rules in this selector group
-    VALUE merged_decls = flatten_rules_for_selector(ctx->rules_array, group_indices, selector);
+    // Merge all rules in this selector group and preserve selector_list_id if all rules share same ID
+    VALUE selector_list_id = Qnil;
+    VALUE merged_decls = flatten_rules_for_selector(ctx->rules_array, group_indices, selector, &selector_list_id);
 
     // Create new rule with this selector and merged declarations
     VALUE new_rule = rb_struct_new(cRule,
@@ -644,7 +645,8 @@ static int flatten_selector_group_callback(VALUE selector, VALUE group_indices,
         merged_decls,
         Qnil,  // specificity
         Qnil,  // parent_rule_id
-        Qnil   // nesting_style
+        Qnil,  // nesting_style
+        selector_list_id  // Preserve selector_list_id if all rules in group share same ID
     );
     rb_ary_push(ctx->merged_rules, new_rule);
 
@@ -657,15 +659,66 @@ static int flatten_selector_group_callback(VALUE selector, VALUE group_indices,
  * Takes an array of rule indices that all share the same selector,
  * expands shorthands, applies cascade rules, and recreates shorthands.
  *
+ * @param out_selector_list_id Output parameter: set to selector_list_id if all rules share same ID, else Qnil
  * Returns: Array of merged Declaration structs
  */
-static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, VALUE selector) {
+static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, VALUE selector, VALUE *out_selector_list_id) {
     long num_rules_in_group = RARRAY_LEN(rule_indices);
     VALUE properties_hash = rb_hash_new();
 
     DEBUG_PRINTF("    [flatten_rules_for_selector] Merging %ld rules for selector '%s'\n",
                  num_rules_in_group, RSTRING_PTR(selector));
 
+    // Extract selector_list_id from rules - preserve if all rules share same ID
+    VALUE first_selector_list_id = Qnil;
+    int all_same_selector_list_id = 1;
+
+    DEBUG_PRINTF("    Checking if rules share same selector_list_id...\n");
+
+    for (long g = 0; g < num_rules_in_group; g++) {
+        long rule_idx = FIX2LONG(rb_ary_entry(rule_indices, g));
+        VALUE rule = RARRAY_AREF(rules_array, rule_idx);
+
+        // Skip AtRule objects - they don't have selector_list_id
+        if (rb_obj_is_kind_of(rule, cAtRule)) {
+            continue;
+        }
+
+        VALUE selector_list_id = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR_LIST_ID));
+
+        if (NIL_P(selector_list_id)) {
+            DEBUG_PRINTF("      Rule %ld: has nil selector_list_id, can't preserve\n", g);
+            // If any rule has nil selector_list_id, can't preserve
+            all_same_selector_list_id = 0;
+            break;
+        }
+
+        if (g == 0 || NIL_P(first_selector_list_id)) {
+            first_selector_list_id = selector_list_id;
+            DEBUG_PRINTF("      Rule %ld: first selector_list_id=%ld\n", g, NUM2LONG(first_selector_list_id));
+        } else if (!rb_equal(first_selector_list_id, selector_list_id)) {
+            DEBUG_PRINTF("      Rule %ld: different selector_list_id=%ld (vs %ld), can't preserve\n",
+                         g, NUM2LONG(selector_list_id), NUM2LONG(first_selector_list_id));
+            // Different selector_list_ids - can't preserve
+            all_same_selector_list_id = 0;
+            break;
+        } else {
+            DEBUG_PRINTF("      Rule %ld: same selector_list_id=%ld\n", g, NUM2LONG(selector_list_id));
+        }
+    }
+
+    // Set output parameter: preserve selector_list_id only if all rules share same ID
+    if (out_selector_list_id) {
+        *out_selector_list_id = (all_same_selector_list_id && !NIL_P(first_selector_list_id)) ? first_selector_list_id : Qnil;
+#ifdef CATARACT_DEBUG
+        if (!NIL_P(*out_selector_list_id)) {
+            DEBUG_PRINTF("    -> Preserving selector_list_id=%ld for merged rule\n", NUM2LONG(*out_selector_list_id));
+        } else {
+            DEBUG_PRINTF("    -> NOT preserving selector_list_id (not all same)\n");
+        }
+#endif
+    }
+
     // Process each rule in this selector group
     for (long g = 0; g < num_rules_in_group; g++) {
         long rule_idx = FIX2LONG(rb_ary_entry(rule_indices, g));
@@ -1015,6 +1068,178 @@ static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, V
     return merged_decls;
 }
 
+/*
+ * Helper function: Check if two declaration arrays are equal
+ *
+ * Returns: true if declarations have same properties, values, and importance
+ */
+static int declarations_equal(VALUE decls1, VALUE decls2) {
+    long len1 = RARRAY_LEN(decls1);
+    long len2 = RARRAY_LEN(decls2);
+
+    DEBUG_PRINTF("      [declarations_equal] Comparing %ld vs %ld declarations\n", len1, len2);
+
+    if (len1 != len2) {
+        DEBUG_PRINTF("      -> Different lengths, NOT equal\n");
+        return 0;
+    }
+
+    // Compare each declaration (property, value, important must all match)
+    for (long i = 0; i < len1; i++) {
+        VALUE d1 = RARRAY_AREF(decls1, i);
+        VALUE d2 = RARRAY_AREF(decls2, i);
+
+        VALUE prop1 = rb_struct_aref(d1, INT2FIX(DECL_PROPERTY));
+        VALUE prop2 = rb_struct_aref(d2, INT2FIX(DECL_PROPERTY));
+        VALUE val1 = rb_struct_aref(d1, INT2FIX(DECL_VALUE));
+        VALUE val2 = rb_struct_aref(d2, INT2FIX(DECL_VALUE));
+        VALUE imp1 = rb_struct_aref(d1, INT2FIX(DECL_IMPORTANT));
+        VALUE imp2 = rb_struct_aref(d2, INT2FIX(DECL_IMPORTANT));
+
+        if (!rb_equal(prop1, prop2) || !rb_equal(val1, val2) || (RTEST(imp1) != RTEST(imp2))) {
+            DEBUG_PRINTF("      -> Decl %ld differs: %s:%s%s vs %s:%s%s\n",
+                         i,
+                         RSTRING_PTR(prop1), RSTRING_PTR(val1), RTEST(imp1) ? "!" : "",
+                         RSTRING_PTR(prop2), RSTRING_PTR(val2), RTEST(imp2) ? "!" : "");
+            // Protect VALUEs from GC after rb_equal() calls and before RSTRING_PTR usage above
+            RB_GC_GUARD(prop1);
+            RB_GC_GUARD(val1);
+            RB_GC_GUARD(prop2);
+            RB_GC_GUARD(val2);
+            return 0;
+        }
+    }
+
+    DEBUG_PRINTF("      -> All declarations match, equal\n");
+    return 1;
+}
+
+/*
+ * Update selector lists to remove diverged rules
+ *
+ * After flattening/cascade, rules that were in the same selector list may have
+ * different declarations. This function builds the selector_lists hash with only
+ * rules that still match, and clears selector_list_id for diverged rules.
+ *
+ * @param merged_rules Array of flattened rules (with new IDs assigned)
+ * @param selector_lists Empty hash to populate with list_id => Array of rule IDs
+ */
+static void update_selector_lists_for_divergence(VALUE merged_rules, VALUE selector_lists) {
+    DEBUG_PRINTF("\n=== update_selector_lists_for_divergence ===\n");
+
+    // Group merged rules by selector_list_id (skip rules with no list)
+    // NOTE: Using manual iteration instead of group_by to avoid Ruby method calls
+    VALUE rules_by_list = rb_hash_new();
+
+    long num_rules = RARRAY_LEN(merged_rules);
+    DEBUG_PRINTF("  Total merged rules: %ld\n", num_rules);
+
+    for (long i = 0; i < num_rules; i++) {
+        VALUE rule = RARRAY_AREF(merged_rules, i);
+
+        // Skip AtRule objects
+        if (rb_obj_is_kind_of(rule, cAtRule)) {
+            continue;
+        }
+
+        VALUE selector_list_id = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR_LIST_ID));
+#ifdef CATARACT_DEBUG
+        VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
+#endif
+
+        if (NIL_P(selector_list_id)) {
+            DEBUG_PRINTF("  Rule %ld (%s): no selector_list_id\n", i, RSTRING_PTR(selector));
+            continue;
+        }
+
+        DEBUG_PRINTF("  Rule %ld (%s): selector_list_id=%ld\n",
+                     i, RSTRING_PTR(selector), NUM2LONG(selector_list_id));
+
+        VALUE group = rb_hash_aref(rules_by_list, selector_list_id);
+        if (NIL_P(group)) {
+            group = rb_ary_new();
+            rb_hash_aset(rules_by_list, selector_list_id, group);
+            DEBUG_PRINTF("    -> Created new group for list_id=%ld\n", NUM2LONG(selector_list_id));
+        }
+        rb_ary_push(group, rule);
+    }
+
+    // For each selector list, check if declarations still match
+    VALUE list_ids = rb_funcall(rules_by_list, rb_intern("keys"), 0);
+    long num_lists = RARRAY_LEN(list_ids);
+    DEBUG_PRINTF("  Found %ld selector list groups to check\n", num_lists);
+
+    for (long i = 0; i < num_lists; i++) {
+        VALUE list_id = RARRAY_AREF(list_ids, i);
+        VALUE rules_in_list = rb_hash_aref(rules_by_list, list_id);
+        long num_in_list = RARRAY_LEN(rules_in_list);
+
+        DEBUG_PRINTF("\n  Checking list_id=%ld: %ld rules\n", NUM2LONG(list_id), num_in_list);
+
+        // Skip if only one rule in list (nothing to compare)
+        if (num_in_list <= 1) {
+            DEBUG_PRINTF("    -> Only 1 rule, skipping\n");
+            continue;
+        }
+
+        // Get first rule as reference
+        VALUE reference_rule = RARRAY_AREF(rules_in_list, 0);
+        VALUE reference_decls = rb_struct_aref(reference_rule, INT2FIX(RULE_DECLARATIONS));
+#ifdef CATARACT_DEBUG
+        VALUE reference_selector = rb_struct_aref(reference_rule, INT2FIX(RULE_SELECTOR));
+        DEBUG_PRINTF("    Reference rule: selector=%s, %ld declarations\n",
+                     RSTRING_PTR(reference_selector), RARRAY_LEN(reference_decls));
+#endif
+
+        // Find rules that still match (have identical declarations)
+        VALUE matching_rules = rb_ary_new();
+        rb_ary_push(matching_rules, reference_rule);
+
+        for (long j = 1; j < num_in_list; j++) {
+            VALUE rule = RARRAY_AREF(rules_in_list, j);
+            VALUE decls = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
+#ifdef CATARACT_DEBUG
+            VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
+            DEBUG_PRINTF("    Comparing rule %ld (selector=%s):\n", j, RSTRING_PTR(selector));
+#endif
+
+            if (declarations_equal(reference_decls, decls)) {
+                DEBUG_PRINTF("      -> MATCHES reference, keeping in list\n");
+                rb_ary_push(matching_rules, rule);
+            } else {
+                DEBUG_PRINTF("      -> DIVERGED from reference, clearing selector_list_id\n");
+                // Clear selector_list_id for diverged rule
+                rb_struct_aset(rule, INT2FIX(RULE_SELECTOR_LIST_ID), Qnil);
+            }
+        }
+
+        // Only keep the selector list if at least 2 rules still match
+        long num_matching = RARRAY_LEN(matching_rules);
+        DEBUG_PRINTF("    Result: %ld/%ld rules still match\n", num_matching, num_in_list);
+
+        if (num_matching >= 2) {
+            // Build selector_lists hash with NEW rule IDs
+            VALUE rule_ids = rb_ary_new_capa(num_matching);
+            for (long j = 0; j < num_matching; j++) {
+                VALUE rule = RARRAY_AREF(matching_rules, j);
+                VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
+                rb_ary_push(rule_ids, rule_id);
+            }
+            rb_hash_aset(selector_lists, list_id, rule_ids);
+            DEBUG_PRINTF("    -> Keeping selector list with %ld rules\n", num_matching);
+        } else {
+            DEBUG_PRINTF("    -> Only 1 rule left, clearing selector_list_id for it too\n");
+            // Clear selector_list_id for the last remaining rule too
+            for (long j = 0; j < num_matching; j++) {
+                VALUE rule = RARRAY_AREF(matching_rules, j);
+                rb_struct_aset(rule, INT2FIX(RULE_SELECTOR_LIST_ID), Qnil);
+            }
+        }
+    }
+
+    DEBUG_PRINTF("\n=== End divergence tracking: %ld selector lists preserved ===\n\n", RHASH_SIZE(selector_lists));
+}
+
 // Flatten CSS rules by applying cascade rules
 // Input: Stylesheet object or CSS string
 // Output: Stylesheet with flattened declarations (cascade applied)
@@ -1025,7 +1250,8 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
     // Most calls pass Stylesheet (common case), String is rare
     if (TYPE(input) == T_STRING) {
         // Parse CSS string first
-        VALUE parsed = parse_css_new(self, input);
+        VALUE argv[1] = { input };
+        VALUE parsed = parse_css_new(1, argv, self);
         rules_array = rb_hash_aref(parsed, ID2SYM(rb_intern("rules")));
     } else if (rb_obj_is_kind_of(input, cStylesheet)) {
         // Extract @rules from Stylesheet (common case)
@@ -1214,10 +1440,8 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
         VALUE passthrough_sheet = rb_class_new_instance(0, NULL, cStylesheet);
         rb_ivar_set(passthrough_sheet, id_ivar_rules, passthrough_rules);
 
-        // Set empty @media_index
+        // Set empty @media_index (no media rules after flatten)
         VALUE media_idx = rb_hash_new();
-        VALUE all_ids = rb_ary_new();
-        rb_hash_aset(media_idx, ID2SYM(id_all), all_ids);
         rb_ivar_set(passthrough_sheet, id_ivar_media_index, media_idx);
 
         return passthrough_sheet;
@@ -1258,15 +1482,45 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
 
         rb_ivar_set(merged_sheet, id_ivar_rules, merged_rules);
 
-        // Set @media_index with :all pointing to all rule IDs
-        VALUE media_idx = rb_hash_new();
-        VALUE all_ids = rb_ary_new();
-        for (int i = 0; i < rule_id_counter; i++) {
-            rb_ary_push(all_ids, INT2FIX(i));
+        // Handle selector list divergence: remove rules from selector lists if declarations no longer match
+        // This makes selector_list_id authoritative - if set, declarations MUST be identical
+        // Only process if selector_lists is enabled in the stylesheet's parser options
+        VALUE selector_lists = rb_hash_new();
+        int selector_lists_enabled = 0;
+
+        if (rb_obj_is_kind_of(input, cStylesheet)) {
+            VALUE parser_options = rb_ivar_get(input, rb_intern("@parser_options"));
+
+            if (!NIL_P(parser_options)) {
+                VALUE enabled_val = rb_hash_aref(parser_options, ID2SYM(rb_intern("selector_lists")));
+                selector_lists_enabled = RTEST(enabled_val);
+
+                if (selector_lists_enabled) {
+                    update_selector_lists_for_divergence(merged_rules, selector_lists);
+                } else {
+                    // Clear all selector_list_ids when feature is disabled
+                    for (long i = 0; i < rule_id_counter; i++) {
+                        VALUE rule = RARRAY_AREF(merged_rules, i);
+                        if (!rb_obj_is_kind_of(rule, cAtRule)) {
+                            rb_struct_aset(rule, INT2FIX(RULE_SELECTOR_LIST_ID), Qnil);
+                        }
+                    }
+                }
+            } else {
+                // Default behavior when parser_options is nil: assume enabled
+                update_selector_lists_for_divergence(merged_rules, selector_lists);
+            }
         }
-        rb_hash_aset(media_idx, ID2SYM(id_all), all_ids);
+
+        // Set @media_index to empty hash (no media rules after flatten)
+        // NOTE: Setting to empty hash instead of { all: [ids] } to match pure Ruby behavior
+        // and avoid wrapping output in @media all during serialization
+        VALUE media_idx = rb_hash_new();
         rb_ivar_set(merged_sheet, id_ivar_media_index, media_idx);
 
+        // Set @_selector_lists with divergence tracking
+        rb_ivar_set(merged_sheet, rb_intern("@_selector_lists"), selector_lists);
+
         return merged_sheet;
     }
 
@@ -1731,7 +1985,8 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
         merged_declarations,      // declarations
         Qnil,                     // specificity (not applicable)
         Qnil,                     // parent_rule_id (not nested)
-        Qnil                      // nesting_style (not nested)
+        Qnil,                     // nesting_style (not nested)
+        Qnil                      // selector_list_id
     );
 
     // Set @rules array with single merged rule (use cached ID)

data/lib/cataract/declaration.rb

@@ -15,4 +15,23 @@ module Cataract
   # @attr [String] value CSS property value
   # @attr [Boolean] important Whether the declaration has !important
   Declaration = Struct.new(:property, :value, :important) unless const_defined?(:Declaration)
+
+  class Declaration
+    # Check if this declaration is a custom property (CSS variable).
+    #
+    # Custom properties are properties that start with the "--" prefix.
+    #
+    # @return [Boolean] true if property is a custom property
+    #
+    # @example Custom property
+    #   decl = Cataract::Declaration.new('--color', 'red', false)
+    #   decl.custom_property? #=> true
+    #
+    # @example Regular property
+    #   decl = Cataract::Declaration.new('color', 'red', false)
+    #   decl.custom_property? #=> false
+    def custom_property?
+      property.start_with?('--')
+    end
+  end
 end