cataract 0.2.5 → 0.4.0

data/ext/cataract/cataract.c

@@ -131,8 +131,10 @@ VALUE parse_css_new(int argc, VALUE *argv, VALUE self) {
  * @param charset [String, nil] Optional @charset value
  * @return [String] CSS string
  */
-// Helper to serialize a single rule's declarations
-static void serialize_declarations(VALUE result, VALUE declarations) {
+// Helper to serialize a rule's declarations - indent == NULL means compact
+// (semicolon+space separated, single line); non-NULL means one declaration
+// per line, prefixed with indent.
+static void serialize_declarations(VALUE result, VALUE declarations, const char *indent) {
     long decl_len = RARRAY_LEN(declarations);
     for (long j = 0; j < decl_len; j++) {
         VALUE decl = rb_ary_entry(declarations, j);
@@ -140,6 +142,7 @@ static void serialize_declarations(VALUE result, VALUE declarations) {
         VALUE value = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
         VALUE important = rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT));
 
+        if (indent) rb_str_cat2(result, indent);
         rb_str_append(result, property);
         rb_str_cat2(result, ": ");
         rb_str_append(result, value);
@@ -148,34 +151,15 @@ static void serialize_declarations(VALUE result, VALUE declarations) {
             rb_str_cat2(result, " !important");
         }
 
-        rb_str_cat2(result, ";");
-
-        // Add space after semicolon except for last declaration
-        if (j < decl_len - 1) {
-            rb_str_cat2(result, " ");
-        }
-    }
-}
-
-// Formatted version - each declaration on its own line with indentation
-static void serialize_declarations_formatted(VALUE result, VALUE declarations, const char *indent) {
-    long decl_len = RARRAY_LEN(declarations);
-    for (long j = 0; j < decl_len; j++) {
-        VALUE decl = rb_ary_entry(declarations, j);
-        VALUE property = rb_struct_aref(decl, INT2FIX(DECL_PROPERTY));
-        VALUE value = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
-        VALUE important = rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT));
-
-        rb_str_cat2(result, indent);
-        rb_str_append(result, property);
-        rb_str_cat2(result, ": ");
-        rb_str_append(result, value);
-
-        if (RTEST(important)) {
-            rb_str_cat2(result, " !important");
+        if (indent) {
+            rb_str_cat2(result, ";\n");
+        } else {
+            rb_str_cat2(result, ";");
+            // Add space after semicolon except for last declaration
+            if (j < decl_len - 1) {
+                rb_str_cat2(result, " ");
+            }
         }
-
-        rb_str_cat2(result, ";\n");
     }
 }
 
@@ -201,13 +185,13 @@ static void serialize_at_rule(VALUE result, VALUE at_rule) {
                 rb_str_cat2(result, "  ");
                 rb_str_append(result, nested_selector);
                 rb_str_cat2(result, " { ");
-                serialize_declarations(result, nested_declarations);
+                serialize_declarations(result, nested_declarations, NULL);
                 rb_str_cat2(result, " }\n");
             }
         } else {
             // Serialize as declarations (e.g., @font-face)
             rb_str_cat2(result, "  ");
-            serialize_declarations(result, content);
+            serialize_declarations(result, content, NULL);
             rb_str_cat2(result, "\n");
         }
     }
@@ -284,7 +268,7 @@ static void serialize_rule(VALUE result, VALUE rule) {
 
     rb_str_append(result, selector);
     rb_str_cat2(result, " { ");
-    serialize_declarations(result, declarations);
+    serialize_declarations(result, declarations, NULL);
     rb_str_cat2(result, " }\n");
 }
 
@@ -318,7 +302,7 @@ static void serialize_at_rule_formatted(VALUE result, VALUE at_rule, const char
                 VALUE nested_indent = rb_str_new_cstr(indent);
                 rb_str_cat2(nested_indent, "    ");
                 const char *nested_indent_ptr = RSTRING_PTR(nested_indent);
-                serialize_declarations_formatted(result, nested_declarations, nested_indent_ptr);
+                serialize_declarations(result, nested_declarations, nested_indent_ptr);
                 RB_GC_GUARD(nested_indent);
 
                 // Closing brace (2-space indent)
@@ -330,7 +314,7 @@ static void serialize_at_rule_formatted(VALUE result, VALUE at_rule, const char
             VALUE content_indent = rb_str_new_cstr(indent);
             rb_str_cat2(content_indent, "  ");
             const char *content_indent_ptr = RSTRING_PTR(content_indent);
-            serialize_declarations_formatted(result, content, content_indent_ptr);
+            serialize_declarations(result, content, content_indent_ptr);
             RB_GC_GUARD(content_indent);
         }
     }
@@ -360,7 +344,7 @@ static void serialize_rule_formatted(VALUE result, VALUE rule, const char *inden
     VALUE decl_indent = rb_str_new_cstr(indent);
     rb_str_cat2(decl_indent, "  ");
     const char *decl_indent_ptr = RSTRING_PTR(decl_indent);
-    serialize_declarations_formatted(result, declarations, decl_indent_ptr);
+    serialize_declarations(result, declarations, decl_indent_ptr);
     RB_GC_GUARD(decl_indent);
 
     // Closing brace - double newline for all except last rule
@@ -393,6 +377,54 @@ static int build_mq_reverse_map_callback(VALUE list_id, VALUE mq_ids, VALUE arg)
     return ST_CONTINUE;
 }
 
+// Build the media_query_id => list_id reverse map used by both stylesheet
+// serializers (grouping and nesting) to detect when a rule's media query is
+// part of a comma-separated list (e.g. "@media screen, print").
+static VALUE build_mq_id_to_list_id(VALUE media_query_lists) {
+    VALUE mq_id_to_list_id = rb_hash_new();
+    if (!NIL_P(media_query_lists) && TYPE(media_query_lists) == T_HASH) {
+        struct build_mq_reverse_map_ctx ctx = { mq_id_to_list_id };
+        rb_hash_foreach(media_query_lists, build_mq_reverse_map_callback, (VALUE)&ctx);
+    }
+    return mq_id_to_list_id;
+}
+
+// Build a rule_id => rule lookup. rules_array is NOT guaranteed to satisfy
+// rules[i].id == i here - that invariant only holds for the full,
+// freshly-parsed rules array; Stylesheet#to_s(media: ...) passes a filtered
+// subset whenever the media filter isn't :all, so a plain array index would
+// silently fetch the wrong rule (or even an AtRule, which doesn't share
+// Rule's struct layout) once any rule has been filtered out. Both Rule and
+// AtRule keep id at field index 0, so a single RULE_ID read is safe for
+// either struct type.
+static VALUE build_rules_by_id(VALUE rules_array) {
+    VALUE rules_by_id = rb_hash_new();
+    long len = RARRAY_LEN(rules_array);
+    for (long i = 0; i < len; i++) {
+        VALUE rule = rb_ary_entry(rules_array, i);
+        VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
+        rb_hash_aset(rules_by_id, rule_id, rule);
+    }
+    return rules_by_id;
+}
+
+// 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
+// struct it actually is rather than always using Rule's index - otherwise,
+// for an AtRule, RULE_PARENT_RULE_ID's index (4) actually reads its
+// media_query_id field instead.
+static inline VALUE rule_parent_id(VALUE rule) {
+    // AtRule instances are never nested via CSS nesting - only Rule can be.
+    return rb_obj_is_kind_of(rule, cAtRule) ? Qnil : rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
+}
+
+static inline VALUE rule_media_query_id_of(VALUE rule) {
+    return rb_obj_is_kind_of(rule, cAtRule)
+        ? rb_struct_aref(rule, INT2FIX(AT_RULE_MEDIA_QUERY_ID))
+        : rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+}
+
 // Formatting options for stylesheet serialization
 // Avoids mode flags and if/else branches - all behavior controlled by struct values
 struct format_opts {
@@ -404,6 +436,126 @@ struct format_opts {
     int add_blank_lines;            // 0 (compact) vs 1 (formatted)
 };
 
+// Serialize a single rule, compact or formatted depending on whether
+// decl_indent is NULL - mirrors the format_opts indent-as-mode-flag
+// convention used throughout this file.
+static inline void emit_rule(VALUE result, VALUE rule, const char *decl_indent, const char *rule_prefix) {
+    if (decl_indent) {
+        serialize_rule_formatted(result, rule, rule_prefix, 1);
+    } else {
+        serialize_rule(result, rule);
+    }
+}
+
+// Scan rule_ids_in_list for other not-yet-processed rules that share
+// rule_media_query_id and rule_declarations with the current rule, marking
+// each match as processed. Returns an array of their selectors (does not
+// include the current rule's own selector or mark it processed - the
+// caller's rule_id is handled by serialize_rule_in_group).
+static VALUE collect_matching_selectors(VALUE rule_ids_in_list, VALUE rule_media_query_id, VALUE rule_declarations, VALUE rules_by_id, VALUE processed_rule_ids) {
+    VALUE matching_selectors = rb_ary_new();
+    long list_len = RARRAY_LEN(rule_ids_in_list);
+
+    for (long j = 0; j < list_len; j++) {
+        VALUE other_rule_id = rb_ary_entry(rule_ids_in_list, j);
+
+        // Skip if already processed
+        if (RTEST(rb_hash_aref(processed_rule_ids, other_rule_id))) {
+            continue;
+        }
+
+        // Find the rule by ID
+        VALUE other_rule = rb_hash_aref(rules_by_id, other_rule_id);
+        if (NIL_P(other_rule)) continue;
+
+        // Check same media context (compare media_query_id directly)
+        VALUE other_rule_media_query_id = rb_struct_aref(other_rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+        if (!rb_equal(rule_media_query_id, other_rule_media_query_id)) {
+            continue;
+        }
+
+        // Check if declarations match
+        VALUE other_declarations = rb_struct_aref(other_rule, INT2FIX(RULE_DECLARATIONS));
+        if (rb_equal(rule_declarations, other_declarations)) {
+            VALUE other_selector = rb_struct_aref(other_rule, INT2FIX(RULE_SELECTOR));
+            rb_ary_push(matching_selectors, other_selector);
+            rb_hash_aset(processed_rule_ids, other_rule_id, Qtrue);
+        }
+    }
+
+    return matching_selectors;
+}
+
+// Emit a comma-joined group of matching selectors sharing one declaration
+// block, or fall back to a single rule if grouping didn't find any matches.
+// rule_prefix is written before the (possibly joined) selector line and
+// before the closing brace - "" at the top level, opts->media_indent inside
+// a media block (a no-op when "").
+static void emit_grouped_rule(VALUE result, VALUE rule, VALUE matching_selectors, VALUE rule_declarations, const struct format_opts *opts, const char *decl_indent, const char *rule_prefix) {
+    if (RARRAY_LEN(matching_selectors) > 1) {
+        VALUE selector_str = rb_ary_join(matching_selectors, rb_str_new_cstr(", "));
+        rb_str_cat2(result, rule_prefix);
+        rb_str_append(result, selector_str);
+        rb_str_cat2(result, opts->opening_brace);
+        serialize_declarations(result, rule_declarations, decl_indent);
+        rb_str_cat2(result, rule_prefix);
+        rb_str_cat2(result, opts->closing_brace);
+        RB_GC_GUARD(selector_str);
+    } else {
+        emit_rule(result, rule, decl_indent, rule_prefix);
+    }
+}
+
+// Loop-invariant state shared by every serialize_rule_in_group call within
+// one serialize_stylesheet_with_grouping invocation - populated once instead
+// of threading 5 params through on every call.
+struct rule_group_ctx {
+    VALUE selector_lists;
+    int grouping_enabled;
+    VALUE rules_by_id;
+    VALUE processed_rule_ids;
+    const struct format_opts *opts;
+};
+
+// Serialize one rule, applying selector-list grouping if enabled. Used
+// identically for both the base (not-in-media) and in-media contexts -
+// in_media selects the relevant format_opts fields ("" and
+// opts->decl_indent_base at the base level; opts->media_indent and
+// opts->decl_indent_media inside a media block).
+static void serialize_rule_in_group(
+    VALUE result,
+    VALUE rule,
+    VALUE rule_id,
+    VALUE rule_media_query_id,
+    const struct rule_group_ctx *ctx,
+    int in_media
+) {
+    const char *decl_indent = in_media ? ctx->opts->decl_indent_media : ctx->opts->decl_indent_base;
+    const char *rule_prefix = in_media ? ctx->opts->media_indent : "";
+
+    // Try to group with other rules from same selector list
+    // Check if this is a Rule (not AtRule) before accessing selector_list_id
+    if (ctx->grouping_enabled && rb_obj_is_kind_of(rule, cRule)) {
+        VALUE selector_list_id = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR_LIST_ID));
+        if (!NIL_P(selector_list_id)) {
+            // Get list of rule IDs in this selector list
+            VALUE rule_ids_in_list = rb_hash_aref(ctx->selector_lists, selector_list_id);
+
+            if (!NIL_P(rule_ids_in_list) && RARRAY_LEN(rule_ids_in_list) > 1) {
+                VALUE rule_declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
+                VALUE matching_selectors = collect_matching_selectors(rule_ids_in_list, rule_media_query_id, rule_declarations, ctx->rules_by_id, ctx->processed_rule_ids);
+                emit_grouped_rule(result, rule, matching_selectors, rule_declarations, ctx->opts, decl_indent, rule_prefix);
+                return;
+            }
+        }
+    }
+
+    // No grouping applies (disabled, not a Rule, no selector_list_id, or a
+    // selector list of 1) - serialize normally
+    emit_rule(result, rule, decl_indent, rule_prefix);
+    rb_hash_aset(ctx->processed_rule_ids, rule_id, Qtrue);
+}
+
 // Private shared implementation for stylesheet serialization with optional selector list grouping
 // All formatting behavior controlled by format_opts struct to avoid mode flags and if/else branches
 static VALUE serialize_stylesheet_with_grouping(
@@ -421,15 +573,19 @@ static VALUE serialize_stylesheet_with_grouping(
 
     // Build reverse map: media_query_id => list_id
     // This allows us to detect when multiple rules share a comma-separated media query list
-    VALUE mq_id_to_list_id = rb_hash_new();
-    if (!NIL_P(media_query_lists) && TYPE(media_query_lists) == T_HASH) {
-        struct build_mq_reverse_map_ctx ctx = { mq_id_to_list_id };
-        rb_hash_foreach(media_query_lists, build_mq_reverse_map_callback, (VALUE)&ctx);
-    }
+    VALUE mq_id_to_list_id = build_mq_id_to_list_id(media_query_lists);
+
+    // Only needed by the grouping path - rules_array here may already be
+    // filtered (Stylesheet#to_s(media: ...) for anything but :all), so
+    // looking up "other rules in this selector list" needs a real id => rule
+    // map rather than indexing directly into rules_array.
+    VALUE rules_by_id = grouping_enabled ? build_rules_by_id(rules_array) : Qnil;
 
     // Track processed rules to avoid duplicates when grouping
     VALUE processed_rule_ids = rb_hash_new();
 
+    struct rule_group_ctx group_ctx = { selector_lists, grouping_enabled, rules_by_id, processed_rule_ids, opts };
+
     // Iterate through rules in insertion order, grouping consecutive media queries
     VALUE current_media = Qnil;
     int in_media_block = 0;
@@ -443,8 +599,8 @@ static VALUE serialize_stylesheet_with_grouping(
             continue;
         }
 
-        // Get media_query_id and fetch MediaQuery object (nil for AtRule or rules without media query)
-        VALUE rule_media_query_id = rb_obj_is_kind_of(rule, cAtRule) ? Qnil : rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+        // Get media_query_id and fetch MediaQuery object (nil for rules without media query)
+        VALUE rule_media_query_id = rule_media_query_id_of(rule);
         VALUE rule_media = Qnil;
         if (!NIL_P(rule_media_query_id)) {
             rule_media = rb_ary_entry(media_queries, FIX2INT(rule_media_query_id));
@@ -464,95 +620,7 @@ static VALUE serialize_stylesheet_with_grouping(
                 rb_str_cat2(result, "\n");
             }
 
-            // Try to group with other rules from same selector list
-            // Check if this is a Rule (not AtRule) before accessing selector_list_id
-            if (grouping_enabled && rb_obj_is_kind_of(rule, cRule)) {
-                VALUE selector_list_id = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR_LIST_ID));
-                if (!NIL_P(selector_list_id)) {
-                    // Get list of rule IDs in this selector list
-                    VALUE rule_ids_in_list = rb_hash_aref(selector_lists, selector_list_id);
-
-                    if (NIL_P(rule_ids_in_list) || RARRAY_LEN(rule_ids_in_list) <= 1) {
-                        // Just this rule, serialize normally
-                        if (opts->decl_indent_base) {
-                            serialize_rule_formatted(result, rule, "", 1);
-                        } else {
-                            serialize_rule(result, rule);
-                        }
-                        rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-                    } else {
-                        // Find all rules with matching declarations and same media context
-                        VALUE matching_selectors = rb_ary_new();
-                        VALUE rule_declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
-
-                        long list_len = RARRAY_LEN(rule_ids_in_list);
-                        for (long j = 0; j < list_len; j++) {
-                            VALUE other_rule_id = rb_ary_entry(rule_ids_in_list, j);
-
-                            // Skip if already processed
-                            if (RTEST(rb_hash_aref(processed_rule_ids, other_rule_id))) {
-                                continue;
-                            }
-
-                            // Find the rule by ID
-                            VALUE other_rule = rb_ary_entry(rules_array, FIX2INT(other_rule_id));
-                            if (NIL_P(other_rule)) continue;
-
-                            // Check same media context (compare media_query_id directly)
-                            VALUE other_rule_media_query_id = rb_struct_aref(other_rule, INT2FIX(RULE_MEDIA_QUERY_ID));
-                            if (!rb_equal(rule_media_query_id, other_rule_media_query_id)) {
-                                continue;
-                            }
-
-                            // Check if declarations match
-                            VALUE other_declarations = rb_struct_aref(other_rule, INT2FIX(RULE_DECLARATIONS));
-                            if (rb_equal(rule_declarations, other_declarations)) {
-                                VALUE other_selector = rb_struct_aref(other_rule, INT2FIX(RULE_SELECTOR));
-                                rb_ary_push(matching_selectors, other_selector);
-                                rb_hash_aset(processed_rule_ids, other_rule_id, Qtrue);
-                            }
-                        }
-
-                        // Serialize grouped or single rule
-                        if (RARRAY_LEN(matching_selectors) > 1) {
-                            // Group selectors with comma-space separator
-                            VALUE selector_str = rb_ary_join(matching_selectors, rb_str_new_cstr(", "));
-                            rb_str_append(result, selector_str);
-                            rb_str_cat2(result, opts->opening_brace);
-                            if (opts->decl_indent_base) {
-                                serialize_declarations_formatted(result, rule_declarations, opts->decl_indent_base);
-                            } else {
-                                serialize_declarations(result, rule_declarations);
-                            }
-                            rb_str_cat2(result, opts->closing_brace);
-                            RB_GC_GUARD(selector_str);
-                        } else {
-                            // Just one rule, serialize normally
-                            if (opts->decl_indent_base) {
-                                serialize_rule_formatted(result, rule, "", 1);
-                            } else {
-                                serialize_rule(result, rule);
-                            }
-                        }
-                    }
-                } else {
-                    // No selector_list_id, serialize normally
-                    if (opts->decl_indent_base) {
-                        serialize_rule_formatted(result, rule, "", 1);
-                    } else {
-                        serialize_rule(result, rule);
-                    }
-                    rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-                }
-            } else {
-                // Grouping disabled, serialize normally
-                if (opts->decl_indent_base) {
-                    serialize_rule_formatted(result, rule, "", 1);
-                } else {
-                    serialize_rule(result, rule);
-                }
-                rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-            }
+            serialize_rule_in_group(result, rule, rule_id, rule_media_query_id, &group_ctx, 0);
         } else {
             // This rule is in a media query
             // Check if media query changed from previous rule (compare MediaQuery objects by value)
@@ -580,80 +648,7 @@ static VALUE serialize_stylesheet_with_grouping(
                 in_media_block = 1;
             }
 
-            // Serialize rule inside media block (with grouping if enabled)
-            // Check if this is a Rule (not AtRule) before accessing selector_list_id
-            if (grouping_enabled && rb_obj_is_kind_of(rule, cRule)) {
-                VALUE selector_list_id = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR_LIST_ID));
-                if (!NIL_P(selector_list_id)) {
-                    VALUE rule_ids_in_list = rb_hash_aref(selector_lists, selector_list_id);
-
-                    if (NIL_P(rule_ids_in_list) || RARRAY_LEN(rule_ids_in_list) <= 1) {
-                        if (opts->decl_indent_media) {
-                            serialize_rule_formatted(result, rule, opts->media_indent, 1);
-                        } else {
-                            serialize_rule(result, rule);
-                        }
-                        rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-                    } else {
-                        VALUE matching_selectors = rb_ary_new();
-                        VALUE rule_declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
-
-                        long list_len = RARRAY_LEN(rule_ids_in_list);
-                        for (long j = 0; j < list_len; j++) {
-                            VALUE other_rule_id = rb_ary_entry(rule_ids_in_list, j);
-                            if (RTEST(rb_hash_aref(processed_rule_ids, other_rule_id))) continue;
-
-                            VALUE other_rule = rb_ary_entry(rules_array, FIX2INT(other_rule_id));
-                            if (NIL_P(other_rule)) continue;
-
-                            VALUE other_rule_media_query_id = rb_struct_aref(other_rule, INT2FIX(RULE_MEDIA_QUERY_ID));
-                            if (!rb_equal(rule_media_query_id, other_rule_media_query_id)) continue;
-
-                            VALUE other_declarations = rb_struct_aref(other_rule, INT2FIX(RULE_DECLARATIONS));
-                            if (rb_equal(rule_declarations, other_declarations)) {
-                                VALUE other_selector = rb_struct_aref(other_rule, INT2FIX(RULE_SELECTOR));
-                                rb_ary_push(matching_selectors, other_selector);
-                                rb_hash_aset(processed_rule_ids, other_rule_id, Qtrue);
-                            }
-                        }
-
-                        if (RARRAY_LEN(matching_selectors) > 1) {
-                            VALUE selector_str = rb_ary_join(matching_selectors, rb_str_new_cstr(", "));
-                            rb_str_cat2(result, opts->media_indent);
-                            rb_str_append(result, selector_str);
-                            rb_str_cat2(result, opts->opening_brace);
-                            if (opts->decl_indent_media) {
-                                serialize_declarations_formatted(result, rule_declarations, opts->decl_indent_media);
-                            } else {
-                                serialize_declarations(result, rule_declarations);
-                            }
-                            rb_str_cat2(result, opts->media_indent);
-                            rb_str_cat2(result, opts->closing_brace);
-                            RB_GC_GUARD(selector_str);
-                        } else {
-                            if (opts->decl_indent_media) {
-                                serialize_rule_formatted(result, rule, opts->media_indent, 1);
-                            } else {
-                                serialize_rule(result, rule);
-                            }
-                        }
-                    }
-                } else {
-                    if (opts->decl_indent_media) {
-                        serialize_rule_formatted(result, rule, opts->media_indent, 1);
-                    } else {
-                        serialize_rule(result, rule);
-                    }
-                    rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-                }
-            } else {
-                if (opts->decl_indent_media) {
-                    serialize_rule_formatted(result, rule, opts->media_indent, 1);
-                } else {
-                    serialize_rule(result, rule);
-                }
-                rb_hash_aset(processed_rule_ids, rule_id, Qtrue);
-            }
+            serialize_rule_in_group(result, rule, rule_id, rule_media_query_id, &group_ctx, 1);
         }
     }
 
@@ -664,37 +659,11 @@ static VALUE serialize_stylesheet_with_grouping(
 
     // Guard hash 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);
     return result;
 }
 
-// Original stylesheet serialization (no nesting support) - compact format
-static VALUE stylesheet_to_s_without_nesting(VALUE rules_array, VALUE media_queries, VALUE media_query_lists, VALUE charset, VALUE selector_lists) {
-    Check_Type(rules_array, T_ARRAY);
-    Check_Type(media_queries, T_ARRAY);
-
-    VALUE result = rb_str_new_cstr("");
-
-    // Add charset if present
-    if (!NIL_P(charset)) {
-        rb_str_cat2(result, "@charset \"");
-        rb_str_append(result, charset);
-        rb_str_cat2(result, "\";\n");
-    }
-
-    // Compact formatting options
-    struct format_opts opts = {
-        .opening_brace = " { ",
-        .closing_brace = " }\n",
-        .media_indent = "",
-        .decl_indent_base = NULL,
-        .decl_indent_media = NULL,
-        .add_blank_lines = 0
-    };
-
-    return serialize_stylesheet_with_grouping(rules_array, media_queries, media_query_lists, result, selector_lists, &opts);
-}
-
 // Forward declarations
 static void serialize_children_only(VALUE result, VALUE rules_array, long rule_idx,
                                     VALUE parent_to_children, VALUE parent_selector,
@@ -766,7 +735,7 @@ static void serialize_children_only(VALUE result, VALUE rules_array, long rule_i
                             rb_str_cat2(child_indent, "  ");
                         }
                         const char *child_indent_ptr = RSTRING_PTR(child_indent);
-                        serialize_declarations_formatted(result, child_declarations, child_indent_ptr);
+                        serialize_declarations(result, child_declarations, child_indent_ptr);
                         RB_GC_GUARD(child_indent);
                     }
 
@@ -787,7 +756,7 @@ static void serialize_children_only(VALUE result, VALUE rules_array, long rule_i
 
                     // Serialize child declarations
                     VALUE child_declarations = rb_struct_aref(child, INT2FIX(RULE_DECLARATIONS));
-                    serialize_declarations(result, child_declarations);
+                    serialize_declarations(result, child_declarations, NULL);
 
                     // Recursively serialize grandchildren
                     serialize_children_only(result, rules_array, child_idx, parent_to_children,
@@ -823,7 +792,7 @@ static void serialize_children_only(VALUE result, VALUE rules_array, long rule_i
                             rb_str_cat2(child_indent, "  ");
                         }
                         const char *child_indent_ptr = RSTRING_PTR(child_indent);
-                        serialize_declarations_formatted(result, child_declarations, child_indent_ptr);
+                        serialize_declarations(result, child_declarations, child_indent_ptr);
                         RB_GC_GUARD(child_indent);
                     }
 
@@ -835,7 +804,7 @@ static void serialize_children_only(VALUE result, VALUE rules_array, long rule_i
                     rb_str_cat2(result, " { ");
 
                     VALUE child_declarations = rb_struct_aref(child, INT2FIX(RULE_DECLARATIONS));
-                    serialize_declarations(result, child_declarations);
+                    serialize_declarations(result, child_declarations, NULL);
 
                     rb_str_cat2(result, " }");
                 }
@@ -876,7 +845,7 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
         if (!NIL_P(declarations) && RARRAY_LEN(declarations) > 0) {
             DEBUG_PRINTF("[SERIALIZE_RULE] Serializing %ld declarations with indent='%s' (%d spaces)\n",
                         RARRAY_LEN(declarations), decl_indent, decl_spaces);
-            serialize_declarations_formatted(result, declarations, decl_indent);
+            serialize_declarations(result, declarations, decl_indent);
         }
 
         // Serialize nested children
@@ -891,7 +860,7 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
         rb_str_cat2(result, " { ");
 
         // Serialize own declarations
-        serialize_declarations(result, declarations);
+        serialize_declarations(result, declarations, NULL);
 
         // Serialize nested children
         serialize_children_only(result, rules_array, rule_idx, parent_to_children,
@@ -904,50 +873,31 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
     RB_GC_GUARD(rule);
 }
 
-// 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) {
-    DEBUG_PRINTF("[STYLESHEET_TO_S] Called with:\n");
-    DEBUG_PRINTF("  rules_array length: %ld\n", RARRAY_LEN(rules_array));
-    DEBUG_PRINTF("  media_queries type: %s, length: %ld\n",
-                rb_obj_classname(media_queries),
-                TYPE(media_queries) == T_ARRAY ? RARRAY_LEN(media_queries) : -1);
-    DEBUG_PRINTF("  media_queries inspect: %s\n", RSTRING_PTR(rb_inspect(media_queries)));
-    DEBUG_PRINTF("  media_query_lists class: %s\n", rb_obj_classname(media_query_lists));
-    DEBUG_PRINTF("  selector_lists class: %s\n", rb_obj_classname(selector_lists));
-
-    DEBUG_PRINTF("[STYLESHEET_TO_S] About to Check_Type\n");
-    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);
-    DEBUG_PRINTF("[STYLESHEET_TO_S] Check_Type passed\n");
-    // TODO: Phase 2 - use selector_lists for grouping
-    (void)selector_lists; // Suppress unused parameter warning
-
-    // Fast path: if no nesting, use original implementation (zero overhead)
-    if (!RTEST(has_nesting)) {
-        DEBUG_PRINTF("[STYLESHEET_TO_S] Taking fast path (no nesting)\n");
-        return stylesheet_to_s_without_nesting(rules_array, media_queries, media_query_lists, charset, selector_lists);
-    }
-
-    DEBUG_PRINTF("[STYLESHEET_TO_S] Taking slow path (has nesting)\n");
-    // SLOW PATH: Has nesting - use lookahead approach
+// Shared implementation for stylesheet serialization with nesting support.
+// Handles both compact (to_s) and formatted (to_formatted_s) output via the
+// format_opts struct, mirroring the pattern serialize_stylesheet_with_grouping
+// uses for the no-nesting fast path.
+static VALUE serialize_stylesheet_with_nesting(
+    VALUE rules_array,
+    VALUE media_queries,
+    VALUE media_query_lists,
+    VALUE result,
+    const struct format_opts *opts
+) {
+    int formatted = (opts->decl_indent_base != NULL);
     long total_rules = RARRAY_LEN(rules_array);
-    VALUE result = rb_str_new_cstr("");
 
-    // Add charset if present
-    if (!NIL_P(charset)) {
-        rb_str_cat2(result, "@charset \"");
-        rb_str_append(result, charset);
-        rb_str_cat2(result, "\";\n");
-    }
+    // Reverse map: media_query_id => list_id, so a rule whose media query is
+    // part of a comma-separated list (e.g. "@media screen, print") renders
+    // the full list, not just its own single media query.
+    VALUE mq_id_to_list_id = build_mq_id_to_list_id(media_query_lists);
 
     // Build parent_to_children map (parent_rule_id -> array of child indices)
     // This allows O(1) lookup of children when serializing each parent
     VALUE parent_to_children = rb_hash_new();
     for (long i = 0; i < total_rules; i++) {
         VALUE rule = rb_ary_entry(rules_array, i);
-        VALUE parent_id = rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
+        VALUE parent_id = rule_parent_id(rule);
 
         if (!NIL_P(parent_id)) {
             DEBUG_PRINTF("[MAP] Rule %ld has parent_id=%s, adding to map\n", i,
@@ -973,7 +923,7 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
     DEBUG_PRINTF("[SERIALIZE] Starting serialization, total_rules=%ld\n", total_rules);
     for (long i = 0; i < total_rules; i++) {
         VALUE rule = rb_ary_entry(rules_array, i);
-        VALUE parent_id = rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
+        VALUE parent_id = rule_parent_id(rule);
 
         DEBUG_PRINTF("[SERIALIZE] Rule %ld: selector=%s, parent_id=%s\n", i,
                     RSTRING_PTR(rb_struct_aref(rule, INT2FIX(RULE_SELECTOR))),
@@ -986,7 +936,7 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
         }
 
         // Get media_query_id for this rule and fetch the MediaQuery object
-        VALUE rule_media_query_id = rb_obj_is_kind_of(rule, cAtRule) ? Qnil : rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+        VALUE rule_media_query_id = rule_media_query_id_of(rule);
         VALUE rule_media = Qnil;
         if (!NIL_P(rule_media_query_id)) {
             rule_media = rb_ary_entry(media_queries, FIX2INT(rule_media_query_id));
@@ -1002,6 +952,10 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
                 rb_str_cat2(result, "}\n");
                 in_media_block = 0;
                 current_media = Qnil;
+
+                if (opts->add_blank_lines) {
+                    rb_str_cat2(result, "\n");
+                }
             }
         } else {
             // In media - check if we need to open/change block (compare MediaQuery objects by value)
@@ -1009,11 +963,14 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
                 // Close previous media block if open
                 if (in_media_block) {
                     rb_str_cat2(result, "}\n");
+                } else if (opts->add_blank_lines && RSTRING_LEN(result) > 0) {
+                    // Add blank line before new media block (except at start)
+                    rb_str_cat2(result, "\n");
                 }
                 // Open new media block - store the MediaQuery object for comparison
                 current_media = rule_media;
                 rb_str_cat2(result, "@media ");
-                append_media_query_text(result, rule_media);
+                append_media_query_string(result, rule_media_query_id, mq_id_to_list_id, media_query_lists, media_queries);
                 rb_str_cat2(result, " {\n");
                 in_media_block = 1;
             }
@@ -1025,11 +982,18 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
             continue;
         }
 
+        // Add indent if inside media block (no-op in compact mode, where media_indent is "")
+        if (in_media_block) {
+            DEBUG_PRINTF("[FORMATTED] Adding base indent for media block\n");
+            rb_str_cat2(result, opts->media_indent);
+        }
+
         // Serialize rule with nested children
+        DEBUG_PRINTF("[FORMATTED] Calling serialize_rule_with_children, in_media_block=%d\n", in_media_block);
         serialize_rule_with_children(
             result, rules_array, i, parent_to_children, media_queries,
-            0,  // formatted (compact)
-            0   // indent_level (top-level)
+            formatted,
+            in_media_block ? 1 : 0   // indent_level (unused when !formatted)
         );
     }
 
@@ -1042,47 +1006,16 @@ static VALUE stylesheet_to_s(VALUE self, VALUE rules_array, VALUE charset, VALUE
     return result;
 }
 
-// Original formatted serialization (no nesting support)
-static VALUE stylesheet_to_formatted_s_without_nesting(VALUE rules_array, VALUE media_queries, VALUE media_query_lists, VALUE charset, VALUE selector_lists) {
-    Check_Type(rules_array, T_ARRAY);
-    Check_Type(media_queries, T_ARRAY);
-
-    VALUE result = rb_str_new_cstr("");
-
-    // Add charset if present
-    if (!NIL_P(charset)) {
-        rb_str_cat2(result, "@charset \"");
-        rb_str_append(result, charset);
-        rb_str_cat2(result, "\";\n");
-    }
-
-    // Formatted output options
-    struct format_opts opts = {
-        .opening_brace = " {\n",
-        .closing_brace = "}\n",
-        .media_indent = "  ",
-        .decl_indent_base = "  ",
-        .decl_indent_media = "    ",
-        .add_blank_lines = 1
-    };
-
-    return serialize_stylesheet_with_grouping(rules_array, media_queries, media_query_lists, result, selector_lists, &opts);
-}
-
-// 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) {
+// Shared implementation for stylesheet_to_s/stylesheet_to_formatted_s - both wrap
+// 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) {
     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);
 
-    // Fast path: if no nesting, use original implementation (zero overhead)
-    if (!RTEST(has_nesting)) {
-        return stylesheet_to_formatted_s_without_nesting(rules_array, media_queries, media_query_lists, charset, selector_lists);
-    }
-
-    // SLOW PATH: Has nesting - use parameterized serialization with formatted=1
-    long total_rules = RARRAY_LEN(rules_array);
     VALUE result = rb_str_new_cstr("");
 
     // Add charset if present
@@ -1092,101 +1025,45 @@ static VALUE stylesheet_to_formatted_s(VALUE self, VALUE rules_array, VALUE char
         rb_str_cat2(result, "\";\n");
     }
 
-    // Build parent_to_children map (parent_rule_id -> array of child indices)
-    VALUE parent_to_children = rb_hash_new();
-    for (long i = 0; i < total_rules; i++) {
-        VALUE rule = rb_ary_entry(rules_array, i);
-        VALUE parent_id = rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
-
-        if (!NIL_P(parent_id)) {
-            VALUE children = rb_hash_aref(parent_to_children, parent_id);
-            if (NIL_P(children)) {
-                children = rb_ary_new();
-                rb_hash_aset(parent_to_children, parent_id, children);
-            }
-            rb_ary_push(children, LONG2FIX(i));
-        }
+    struct format_opts opts;
+    if (formatted) {
+        opts = (struct format_opts){
+            .opening_brace = " {\n",
+            .closing_brace = "}\n",
+            .media_indent = "  ",
+            .decl_indent_base = "  ",
+            .decl_indent_media = "    ",
+            .add_blank_lines = 1
+        };
+    } else {
+        opts = (struct format_opts){
+            .opening_brace = " { ",
+            .closing_brace = " }\n",
+            .media_indent = "",
+            .decl_indent_base = NULL,
+            .decl_indent_media = NULL,
+            .add_blank_lines = 0
+        };
     }
 
-    // Track media block state for proper opening/closing
-    VALUE current_media = Qnil;
-    int in_media_block = 0;
-
-    // Serialize only top-level rules (parent_rule_id == nil)
-    for (long i = 0; i < total_rules; i++) {
-        VALUE rule = rb_ary_entry(rules_array, i);
-        VALUE parent_id = rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
-
-        // Skip child rules - they're serialized when we hit their parent
-        if (!NIL_P(parent_id)) {
-            continue;
-        }
-
-        // Get media_query_id for this rule and fetch the MediaQuery object
-        VALUE rule_media_query_id = rb_obj_is_kind_of(rule, cAtRule) ? Qnil : rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
-        VALUE rule_media = Qnil;
-        if (!NIL_P(rule_media_query_id)) {
-            rule_media = rb_ary_entry(media_queries, FIX2INT(rule_media_query_id));
-        }
-
-        // Handle media block transitions
-        if (NIL_P(rule_media)) {
-            // Not in media - close any open media block
-            if (in_media_block) {
-                rb_str_cat2(result, "}\n");
-                in_media_block = 0;
-                current_media = Qnil;
-
-                // Add blank line after closing media block
-                rb_str_cat2(result, "\n");
-            }
-        } else {
-            // In media - check if we need to open/change block (compare MediaQuery objects by value)
-            if (NIL_P(current_media) || !rb_equal(current_media, rule_media)) {
-                // Close previous media block if open
-                if (in_media_block) {
-                    rb_str_cat2(result, "}\n");
-                } else if (RSTRING_LEN(result) > 0) {
-                    // Add blank line before new media block (except at start)
-                    rb_str_cat2(result, "\n");
-                }
-                // Open new media block - store the MediaQuery object for comparison
-                current_media = rule_media;
-                rb_str_cat2(result, "@media ");
-                append_media_query_text(result, rule_media);
-                rb_str_cat2(result, " {\n");
-                in_media_block = 1;
-            }
-        }
-
-        // Check if this is an AtRule
-        if (rb_obj_is_kind_of(rule, cAtRule)) {
-            serialize_at_rule(result, rule);
-            continue;
-        }
-
-        // Add indent if inside media block
-        if (in_media_block) {
-            DEBUG_PRINTF("[FORMATTED] Adding base indent for media block\n");
-            rb_str_cat2(result, "  ");
-        }
-
-        // Serialize rule with nested children
-        DEBUG_PRINTF("[FORMATTED] Calling serialize_rule_with_children, in_media_block=%d\n", in_media_block);
-        serialize_rule_with_children(
-            result, rules_array, i, parent_to_children, media_queries,
-            1,  // formatted (with indentation)
-            in_media_block ? 1 : 0   // indent_level (1 if inside media block, 0 otherwise)
-        );
+    // 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);
     }
 
-    // Close final media block if still open
-    if (in_media_block) {
-        rb_str_cat2(result, "}\n");
-    }
+    // Has nesting - use the parent/child lookahead serializer
+    // TODO: Phase 2 - use selector_lists for grouping on the nesting path too
+    return serialize_stylesheet_with_nesting(rules_array, media_queries, media_query_lists, result, &opts);
+}
 
-    RB_GC_GUARD(parent_to_children);
-    return result;
+// 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);
+}
+
+// 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);
 }
 
 /*
@@ -1207,62 +1084,18 @@ static VALUE new_parse_declarations_string(const char *start, const char *end) {
         while (pos < end && (IS_WHITESPACE(*pos) || *pos == ';')) pos++;
         if (pos >= end) break;
 
-        // Find property (up to colon)
-        const char *prop_start = pos;
-        while (pos < end && *pos != ':') pos++;
-        if (pos >= end) break;  // No colon found
-
-        const char *prop_end = pos;
-        // Trim trailing whitespace
-        while (prop_end > prop_start && IS_WHITESPACE(*(prop_end-1))) prop_end--;
-        // Trim leading whitespace
-        while (prop_start < prop_end && IS_WHITESPACE(*prop_start)) prop_start++;
-
-        pos++;  // Skip colon
-        // Trim leading whitespace
-        while (pos < end && IS_WHITESPACE(*pos)) pos++;
-
-        // Find value (up to semicolon or end), handling parentheses
-        const char *val_start = pos;
-        int paren_depth = 0;
-        while (pos < end) {
-            if (*pos == '(') paren_depth++;
-            else if (*pos == ')') paren_depth--;
-            else if (*pos == ';' && paren_depth == 0) break;
-            pos++;
-        }
-        const char *val_end = pos;
-        // Trim trailing whitespace
-        while (val_end > val_start && IS_WHITESPACE(*(val_end-1))) val_end--;
-
-        // Check for !important
-        int is_important = 0;
-        if (val_end - val_start >= 10) {  // strlen("!important") = 10
-            const char *check = val_end - 10;
-            while (check < val_end && IS_WHITESPACE(*check)) check++;
-            if (check < val_end && *check == '!') {
-                check++;
-                while (check < val_end && IS_WHITESPACE(*check)) check++;
-                if ((val_end - check) >= 9 && strncmp(check, "important", 9) == 0) {
-                    is_important = 1;
-                    const char *important_pos = check - 1;
-                    while (important_pos > val_start && (IS_WHITESPACE(*(important_pos-1)) || *(important_pos-1) == '!')) {
-                        important_pos--;
-                    }
-                    val_end = important_pos;
-                    // Trim trailing whitespace again
-                    while (val_end > val_start && IS_WHITESPACE(*(val_end-1))) val_end--;
-                }
-            }
-        }
+        // Standalone declaration-list input never contains braces, so only
+        // ':' terminates the property scan (stop_prop_scan_early=0).
+        struct declaration_span span;
+        if (!parse_one_declaration(&pos, end, 0, &span)) break;  // No colon found
 
         // Skip if value is empty
-        if (val_end > val_start) {
-            long prop_len = prop_end - prop_start;
-            long val_len = val_end - val_start;
+        if (span.val_end > span.val_start) {
+            long prop_len = span.prop_end - span.prop_start;
+            long val_len = span.val_end - span.val_start;
 
             // Create property string (US-ASCII, lowercased)
-            VALUE property = rb_usascii_str_new(prop_start, prop_len);
+            VALUE property = rb_usascii_str_new(span.prop_start, prop_len);
             // Lowercase it inline
             char *prop_ptr = RSTRING_PTR(property);
             for (long i = 0; i < prop_len; i++) {
@@ -1271,11 +1104,11 @@ static VALUE new_parse_declarations_string(const char *start, const char *end) {
                 }
             }
 
-            VALUE value = rb_utf8_str_new(val_start, val_len);
+            VALUE value = rb_utf8_str_new(span.val_start, val_len);
 
             // Create Declaration struct
             VALUE decl = rb_struct_new(cDeclaration,
-                property, value, is_important ? Qtrue : Qfalse);
+                property, value, span.is_important ? Qtrue : Qfalse);
 
             rb_ary_push(declarations, decl);
         }
@@ -1284,78 +1117,6 @@ static VALUE new_parse_declarations_string(const char *start, const char *end) {
     return declarations;
 }
 
-/*
- * Convert array of Declaration structs to CSS string
- * Format: "prop: value; prop2: value2 !important; "
- *
- * This is a copy of declarations_array_to_s from cataract.c,
- * but works with Declaration structs instead of Declaration structs
- */
-static VALUE new_declarations_array_to_s(VALUE declarations_array) {
-    Check_Type(declarations_array, T_ARRAY);
-
-    long len = RARRAY_LEN(declarations_array);
-    if (len == 0) {
-        return rb_str_new_cstr("");
-    }
-
-    // Use rb_str_buf_new for efficient string building
-    VALUE result = rb_str_buf_new(len * 32); // Estimate 32 chars per declaration
-
-    for (long i = 0; i < len; i++) {
-        VALUE decl = rb_ary_entry(declarations_array, i);
-
-        // Validate this is a Declaration struct
-        if (!RB_TYPE_P(decl, T_STRUCT) || rb_obj_class(decl) != cDeclaration) {
-            rb_raise(rb_eTypeError,
-                     "Expected array of Declaration structs, got %s at index %ld",
-                     rb_obj_classname(decl), i);
-        }
-
-        // Extract struct fields
-        VALUE property = rb_struct_aref(decl, INT2FIX(DECL_PROPERTY));
-        VALUE value = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
-        VALUE important = rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT));
-
-        // Append: "property: value"
-        rb_str_buf_append(result, property);
-        rb_str_buf_cat2(result, ": ");
-        rb_str_buf_append(result, value);
-
-        // Append " !important" if needed
-        if (RTEST(important)) {
-            rb_str_buf_cat2(result, " !important");
-        }
-
-        rb_str_buf_cat2(result, "; ");
-
-        RB_GC_GUARD(decl);
-        RB_GC_GUARD(property);
-        RB_GC_GUARD(value);
-        RB_GC_GUARD(important);
-    }
-
-    // Strip trailing space
-    rb_str_set_len(result, RSTRING_LEN(result) - 1);
-
-    RB_GC_GUARD(result);
-    return result;
-}
-
-/*
- * Instance method: Declarations#to_s
- * Converts declarations to CSS string
- *
- * @return [String] CSS declarations like "color: red; margin: 10px !important;"
- */
-static VALUE new_declarations_to_s_method(VALUE self) {
-    // Get @values instance variable (array of Declaration structs)
-    VALUE values = rb_ivar_get(self, rb_intern("@values"));
-
-    // Call core serialization function
-    return new_declarations_array_to_s(values);
-}
-
 /*
  * Ruby-facing wrapper for new_parse_declarations
  *
@@ -1446,23 +1207,24 @@ void Init_native_extension(void) {
         rb_raise(rb_eLoadError, "Cataract::MediaQuery not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
     }
 
-    // Define Declarations class and add to_s method
-    VALUE cDeclarations = rb_define_class_under(mCataract, "Declarations", rb_cObject);
-    rb_define_method(cDeclarations, "to_s", new_declarations_to_s_method, 0);
-
-    // Define Stylesheet class (Ruby will add instance methods like each_selector)
+    // 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.
     cStylesheet = rb_define_class_under(mCataract, "Stylesheet", rb_cObject);
 
-    // Define module functions
-    rb_define_module_function(mCataract, "_parse_css", parse_css_new, -1);
-    rb_define_module_function(mCataract, "stylesheet_to_s", stylesheet_to_s, 6);
-    rb_define_module_function(mCataract, "stylesheet_to_formatted_s", stylesheet_to_formatted_s, 6);
-    rb_define_module_function(mCataract, "parse_media_types", parse_media_types, 1);
-    rb_define_module_function(mCataract, "parse_declarations", new_parse_declarations, 1);
-    rb_define_module_function(mCataract, "flatten", cataract_flatten, 1);
-    rb_define_module_function(mCataract, "merge", cataract_flatten, 1); // Deprecated alias for backwards compatibility
-    rb_define_module_function(mCataract, "calculate_specificity", calculate_specificity, 1);
-    rb_define_module_function(mCataract, "expand_shorthand", cataract_expand_shorthand, 1);
+    // Every native-specific entry point lives under Cataract::Backends::Native,
+    // never directly on Cataract itself, so the pure Ruby backend can be loaded
+    // in the same process without either backend clobbering the other's methods.
+    VALUE mBackends = rb_define_module_under(mCataract, "Backends");
+    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, "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);
+    rb_define_module_function(mNative, "expand_shorthand", cataract_expand_shorthand, 1);
 
     // Initialize flatten constants (cached property strings)
     init_flatten_constants();
@@ -1482,11 +1244,11 @@ void Init_native_extension(void) {
         rb_hash_aset(compile_flags, ID2SYM(rb_intern("str_buf_optimization")), Qtrue);
     #endif
 
-    rb_define_const(mCataract, "COMPILE_FLAGS", compile_flags);
+    rb_define_const(mNative, "COMPILE_FLAGS", compile_flags);
 
-    // Flag to indicate native extension is loaded (for pure Ruby fallback detection)
-    rb_define_const(mCataract, "NATIVE_EXTENSION_LOADED", Qtrue);
+    // Flag to indicate the native backend is loaded (for pure Ruby fallback detection)
+    rb_define_const(mNative, "NATIVE_EXTENSION_LOADED", Qtrue);
 
     // Implementation type constant
-    rb_define_const(mCataract, "IMPLEMENTATION", ID2SYM(rb_intern("native")));
+    rb_define_const(mNative, "IMPLEMENTATION", ID2SYM(rb_intern("native")));
 }