cataract 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6424d26e77e0dd4e0167324dc6190f03a9ca041e51fa9e61a78163f6fe312b
-  data.tar.gz: 7c538f41ebd8e93a53caed4a5f066eea076277c26174bff7d22837730f03d90d
+  metadata.gz: 67046f0d371d7b0b077971e8634ff4054e64fe23a55c80b1a9f80e3dee6d804b
+  data.tar.gz: 776865b7490e22c326c0bab93a3da32f088177817b3e237c68b66e233df39021
 SHA512:
-  metadata.gz: d2297f4139e8025ac39b9467eaa4bd0541683af7e4870813159c557df813f411d389b59f5b28adb9c46f5390aba73405b937e946d9097b943e0ba70f6cb37963
-  data.tar.gz: 0b4d9b6ec564fd674ad8558b7b4f309494c0ca12628947a8501b17ccb3567e1a2667dd0ea89f88ad82f688ac580122ec7e9505b8149433504ef40d923228b75b
+  metadata.gz: 21f5ccd9b4ed3e0831fa8723d02493b7b4a3582c359a3e3bae927e554d207422a0139592b23889d273ca1ed3a1888679c729d9ad0f4aa2bf4c90d18b2e16fe0c
+  data.tar.gz: f149256218337a47a1b27cd945857dd358199ceb47f70274c0c7db5cb3fa196d84a55281528c0f22d12da4bbbaff3b92c6e315210906a75aee2d304a9b91c275

data/.gitignore

@@ -4,9 +4,6 @@ tmp/
 *.so
 *.o
 
-# Generated C code from Ragel
-ext/**/cataract.c
-
 # Compiled extensions
 lib/**/*.so
 lib/**/*.bundle

data/.rubocop_todo.yml

@@ -22,21 +22,13 @@ Layout/EmptyLinesAfterModuleInclusion:
   Exclude:
     - 'benchmarks/parsing_tests.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: aligned, indented
-Layout/MultilineOperationIndentation:
-  Exclude:
-    - 'lib/cataract/pure/helpers.rb'
-
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Lint/AmbiguousOperatorPrecedence:
   Exclude:
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
@@ -69,7 +61,7 @@ Minitest/EmptyLineBeforeAssertionMethods:
   Exclude:
     - 'test/test_stylesheet.rb'
 
-# Offense count: 7
+# Offense count: 14
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Performance/UnfreezeString:
   Exclude:
@@ -77,7 +69,7 @@ Performance/UnfreezeString:
     - 'lib/cataract/pure/flatten.rb'
     - 'lib/cataract/pure/parser.rb'
 
-# Offense count: 4
+# Offense count: 8
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
 # SupportedStyles: assign_to_condition, assign_inside_condition
@@ -86,7 +78,7 @@ Style/ConditionalAssignment:
     - 'lib/cataract/pure/imports.rb'
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 4
+# Offense count: 8
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
@@ -107,7 +99,7 @@ Style/HashLikeCase:
     - 'benchmarks/serialization_tests.rb'
     - 'benchmarks/specificity_tests.rb'
 
-# Offense count: 14
+# Offense count: 28
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/IdenticalConditionalBranches:
   Exclude:
@@ -118,7 +110,7 @@ Style/IdenticalConditionalBranches:
     - 'lib/cataract/pure/parser.rb'
     - 'lib/cataract/pure/serializer.rb'
 
-# Offense count: 5
+# Offense count: 10
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowIfModifier.
 Style/IfInsideElse:
@@ -127,19 +119,19 @@ Style/IfInsideElse:
     - 'lib/cataract/pure/serializer.rb'
     - 'lib/cataract/pure/specificity.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Style/NegatedIfElseCondition:
   Exclude:
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantAssignment:
   Exclude:
     - 'lib/cataract/pure/specificity.rb'
 
-# Offense count: 2
+# Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantParentheses:
   Exclude:
@@ -152,7 +144,7 @@ Style/RedundantRegexpArgument:
   Exclude:
     - 'test/test_stylesheet.rb'
 
-# Offense count: 3
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowModifier.
 Style/SoleNestedConditional:

data/BENCHMARKS.md

@@ -8,11 +8,11 @@ Performance comparison between Cataract's C extension and pure Ruby implementati
 
 ## Test Environment
 
-- **Ruby**: ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +YJIT +PRISM [arm64-darwin23]
+- **Ruby**: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin25]
 - **CPU**: Apple M1 Pro
 - **Memory**: 32GB
-- **OS**: macOS 14.5
-- **Generated**: 2025-11-11T16:02:08-06:00
+- **OS**: macOS 26.3.1
+- **Generated**: 2026-07-08T10:35:16-05:00
 
 ## CSS Parsing
 
@@ -20,17 +20,17 @@ Time to parse CSS into internal data structures
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Small CSS (64 lines, 1.0KB) | 37.27K i/s | 3.32K i/s | 13.48K i/s |
-| Medium CSS with @media (139 lines, 1.6KB) | 34.66K i/s | 2.06K i/s | 8.94K i/s |
-| Selector lists (3500 lines, 62.5KB, 500 lists) | 485.7 i/s | 55.7 i/s | 213.6 i/s |
+| Small CSS (64 lines, 1.0KB) | 36.76K i/s | 3.33K i/s | 13.66K i/s |
+| Medium CSS with @media (139 lines, 1.6KB) | 29.98K i/s | 2.11K i/s | 8.98K i/s |
+| Selector lists (3500 lines, 62.5KB, 500 lists) | 447.4 i/s | 58.0 i/s | 219.8 i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 14.4x faster (avg) |
-| Native vs Pure (YJIT) | 3.38x faster (avg) |
-| YJIT impact on Pure Ruby | 4.23x faster (avg) |
+| Native vs Pure (no YJIT) | 13.03x faster (avg) |
+| Native vs Pure (YJIT) | 3.12x faster (avg) |
+| YJIT impact on Pure Ruby | 4.15x faster (avg) |
 
 ### Parse Error Checking Overhead
 
@@ -38,17 +38,17 @@ Parse error detection can be enabled with `raise_parse_errors: true`. This compa
 
 | Configuration | Native | Pure (no YJIT) | Pure (YJIT) |
 |---------------|--------|----------------|-------------|
-| Medium CSS (139 lines) - no error checking | 35.18K i/s | 2.07K i/s | 9.05K i/s |
-| Medium CSS (139 lines) - with error checking | 34.84K i/s | 1.9K i/s | 8.19K i/s |
+| Medium CSS (139 lines) - no error checking | 33.57K i/s | 2.12K i/s | 9.08K i/s |
+| Medium CSS (139 lines) - with error checking | 33.09K i/s | 1.94K i/s | 8.19K i/s |
 
 **Overhead Analysis:**
 
 
 | Implementation | Overhead |
 |----------------|----------|
-| Native | ~0% (within noise) |
-| Pure (no YJIT) | 8.9% slower |
-| Pure (YJIT) | 10.4% slower |
+| Native | 1.5% slower |
+| Pure (no YJIT) | 9.2% slower |
+| Pure (YJIT) | 10.9% slower |
 
 ---
 
@@ -58,19 +58,19 @@ Time to convert parsed CSS back to string format
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| to_s (Bootstrap - 191KB) | 1.32K i/s | 360.2 i/s | 656.6 i/s |
-| to_s (Compact utilities - 2.9KB) | 1.32K i/s | 360.2 i/s | 656.6 i/s |
-| to_formatted_s (Nested CSS - 1.3KB) | 176.13K i/s | 60.97K i/s | 121.5K i/s |
-| to_s with selector_lists (3.4KB) | 19.03K i/s | 8.01K i/s | 14.2K i/s |
-| Media filtering (Bootstrap print only) | 283.24K i/s | 97.28K i/s | 161.56K i/s |
+| to_s (Bootstrap - 191KB) | 1.05K i/s | 368.6 i/s | 555.6 i/s |
+| to_s (Compact utilities - 2.9KB) | 1.05K i/s | 368.6 i/s | 555.6 i/s |
+| to_formatted_s (Nested CSS - 1.3KB) | 156.05K i/s | 53.98K i/s | 90.18K i/s |
+| to_s with selector_lists (3.4KB) | 15.37K i/s | 7.71K i/s | 12.09K i/s |
+| Media filtering (Bootstrap print only) | 1.18K i/s | 547.1 i/s | 769.2 i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 3.24x faster (avg) |
-| Native vs Pure (YJIT) | 1.73x faster (avg) |
-| YJIT impact on Pure Ruby | 1.86x faster (avg) |
+| Native vs Pure (no YJIT) | 2.71x faster (avg) |
+| Native vs Pure (YJIT) | 1.75x faster (avg) |
+| YJIT impact on Pure Ruby | 1.55x faster (avg) |
 
 ---
 
@@ -80,20 +80,20 @@ Time to calculate CSS selector specificity values
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Simple Selectors | 7.28M i/s | 506.61K i/s | 2.45M i/s |
-| Compound Selectors | 6.4M i/s | 186.62K i/s | 405.15K i/s |
-| Combinators | 5.04M i/s | 147.07K i/s | 255.92K i/s |
-| Pseudo-classes & Pseudo-elements | 5.17M i/s | 117.16K i/s | 195.12K i/s |
-| :not() Pseudo-class (CSS3) | 3.48M i/s | 103.47K i/s | 161.34K i/s |
-| Complex Real-world Selectors | 4.01M i/s | 52.41K i/s | 77.48K i/s |
+| Simple Selectors | 1.97M i/s | 419.98K i/s | 1.44M i/s |
+| Compound Selectors | 1.89M i/s | 186.59K i/s | 523.08K i/s |
+| Combinators | 1.43M i/s | 142.61K i/s | 285.41K i/s |
+| Pseudo-classes & Pseudo-elements | 1.41M i/s | 114.7K i/s | 235.07K i/s |
+| :not() Pseudo-class (CSS3) | 1.52M i/s | 110.64K i/s | 247.84K i/s |
+| Complex Real-world Selectors | 1.62M i/s | 56.2K i/s | 126.65K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 39.54x faster (avg) |
-| Native vs Pure (YJIT) | 23.05x faster (avg) |
-| YJIT impact on Pure Ruby | 2.24x faster (avg) |
+| Native vs Pure (no YJIT) | 13.28x faster (avg) |
+| Native vs Pure (YJIT) | 5.82x faster (avg) |
+| YJIT impact on Pure Ruby | 2.46x faster (avg) |
 
 ---
 
@@ -103,20 +103,20 @@ Time to flatten multiple CSS rule sets with same selector
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| No shorthand properties (large) | 13.91K i/s | 3.23K i/s | 6.39K i/s |
-| Simple properties | 144.19K i/s | 71.11K i/s | 101.38K i/s |
-| Cascade with specificity | 172.96K i/s | 69.16K i/s | 99.23K i/s |
-| Important declarations | 173.35K i/s | 69.12K i/s | 100.16K i/s |
-| Shorthand expansion | 13.91K i/s | 3.23K i/s | 6.39K i/s |
-| Complex flattening | 29.86K i/s | 15.77K i/s | 22.09K i/s |
+| No shorthand properties (large) | 12.75K i/s | 3.69K i/s | 6.41K i/s |
+| Simple properties | 142.64K i/s | 69.09K i/s | 100.71K i/s |
+| Cascade with specificity | 178.29K i/s | 67.87K i/s | 101.77K i/s |
+| Important declarations | 177.88K i/s | 68.12K i/s | 101.75K i/s |
+| Shorthand expansion | 12.75K i/s | 3.69K i/s | 6.41K i/s |
+| Complex flattening | 31.73K i/s | 16.04K i/s | 23.28K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 2.54x faster (avg) |
-| Native vs Pure (YJIT) | 1.63x faster (avg) |
-| YJIT impact on Pure Ruby | 1.53x faster (avg) |
+| Native vs Pure (no YJIT) | 2.45x faster (avg) |
+| Native vs Pure (YJIT) | 1.6x faster (avg) |
+| YJIT impact on Pure Ruby | 1.52x faster (avg) |
 
 ---
 

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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`.
+- Fix: a compound `@media` list (e.g. `@media screen, print { ... }`) no longer silently collapses to just its first member when the document also contains CSS nesting elsewhere.
+- Fix: `to_s`/`to_formatted_s` with a specific `media:` filter (anything but `:all`) could crash while grouping comma-separated selector lists (e.g. `h1, h2 { ... }`), if an unrelated rule elsewhere in the document was excluded by the filter. Present in both backends since at least 0.3.0.
+- Fix: `Stylesheet#flatten` (non-destructive) could silently expand shorthand properties (e.g. `margin: 0`) on the *original* stylesheet as a side effect, under the pure Ruby backend. Present since at least 0.3.0; the C extension was unaffected.
+- Breaking (minor): removed `Cataract.merge` (a long-deprecated alias for `.flatten`) and `Cataract.parse_media_types` (undocumented, no real callers) from the C extension's public surface. Use `Cataract.flatten`/`Stylesheet#flatten` instead of `.merge`.
+- Internal: `Cataract`'s own directly-callable methods are now just `.flatten` and `.parse_css`. Previously `Cataract` also exposed `calculate_specificity`, `expand_shorthand`, `parse_declarations`, `stylesheet_to_s`, `stylesheet_to_formatted_s`, and `_parse_css` directly - undocumented implementation leakage, not intended for direct use. The documented ways to reach this functionality (`Rule#specificity`, `Rule#expanded_declarations`, `Declarations.new(some_string)`, `Stylesheet#to_s`/`#to_formatted_s`) are unchanged. The native C extension and pure Ruby backend also now live under `Cataract::Backends::Native` / `Cataract::Backends::Pure`, resolved once per process and held per-`Stylesheet` - this lets both backends coexist in the same process (e.g. for direct comparison). Existing callers relying only on the documented public API should notice nothing.
+
 ## [0.3.0] - 2026-07-06
 
 - Security/Breaking: `Stylesheet#load_uri` and `#load_file` now reject `file://` paths under `/etc/`, `/proc/`, `/sys/`, and `/dev/` by default (override with `dangerous_path_prefixes: []`). Previously these methods used a separate, unvalidated fetch implementation; they now reuse `ImportResolver` (the same validation and fetching `@import` resolution already uses), which also fixes `load_uri` not following HTTP redirects.

data/ext/cataract/cataract.c

@@ -377,6 +377,37 @@ 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
@@ -421,7 +452,7 @@ static inline void emit_rule(VALUE result, VALUE rule, const char *decl_indent,
 // 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_array, VALUE processed_rule_ids) {
+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);
 
@@ -434,7 +465,7 @@ static VALUE collect_matching_selectors(VALUE rule_ids_in_list, VALUE rule_media
         }
 
         // Find the rule by ID
-        VALUE other_rule = rb_ary_entry(rules_array, FIX2INT(other_rule_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)
@@ -481,7 +512,7 @@ static void emit_grouped_rule(VALUE result, VALUE rule, VALUE matching_selectors
 struct rule_group_ctx {
     VALUE selector_lists;
     int grouping_enabled;
-    VALUE rules_array;
+    VALUE rules_by_id;
     VALUE processed_rule_ids;
     const struct format_opts *opts;
 };
@@ -512,7 +543,7 @@ static void serialize_rule_in_group(
 
             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_array, ctx->processed_rule_ids);
+                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;
             }
@@ -542,16 +573,18 @@ 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_array, processed_rule_ids, opts };
+    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;
@@ -626,6 +659,7 @@ 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;
 }
@@ -846,12 +880,18 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
 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);
 
+    // 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();
@@ -930,7 +970,7 @@ static VALUE serialize_stylesheet_with_nesting(
                 // 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;
             }
@@ -1013,7 +1053,7 @@ static VALUE stylesheet_serialize_impl(VALUE rules_array, VALUE charset, VALUE h
 
     // 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, result, &opts);
+    return serialize_stylesheet_with_nesting(rules_array, media_queries, media_query_lists, result, &opts);
 }
 
 // New stylesheet serialization entry point - checks for nesting and delegates
@@ -1077,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
  *
@@ -1239,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();
@@ -1275,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")));
 }

data/ext/cataract/cataract.h

@@ -262,7 +262,6 @@ static inline VALUE strip_string(const char *str, long len) {
 // CSS parser (css_parser_new.c)
 VALUE parse_css_new(int argc, VALUE *argv, VALUE self);
 VALUE parse_css_new_impl(VALUE css_string, VALUE parser_options, int rule_id_offset);
-VALUE parse_media_types(VALUE self, VALUE media_query_sym);
 
 // Flatten (flatten.c)
 VALUE cataract_flatten(VALUE self, VALUE rules_array);

data/ext/cataract/css_parser.c

@@ -2312,24 +2312,6 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
     }
 }
 
-/*
- * Parse media query string and extract media types (Ruby-facing function)
- * Example: "screen, print" => [:screen, :print]
- * Example: "screen and (min-width: 768px)" => [:screen]
- *
- * @param media_query_sym [Symbol] Media query as symbol
- * @return [Array<Symbol>] Array of media type symbols
- */
-VALUE parse_media_types(VALUE self, VALUE media_query_sym) {
-    Check_Type(media_query_sym, T_SYMBOL);
-
-    VALUE query_string = rb_sym2str(media_query_sym);
-    const char *query_str = RSTRING_PTR(query_string);
-    long query_len = RSTRING_LEN(query_string);
-
-    return extract_media_types(query_str, query_len);
-}
-
 /*
  * Main parse entry point
  * Returns: { rules: [...], media_index: {...}, charset: "..." | nil, last_rule_id: N }

data/lib/cataract/declarations.rb

@@ -198,12 +198,22 @@ module Cataract
 
     # Convert declarations to CSS string.
     #
-    # Implemented in C for performance.
-    #
     # @return [String] CSS declaration block string
     #
     # @example
     #   decls.to_s #=> "color: red; margin: 10px !important;"
+    def to_s
+      result = +''
+      @values.each_with_index do |decl, i|
+        result << decl.property
+        result << ': '
+        result << decl.value
+        result << ' !important' if decl.important
+        result << ';'
+        result << ' ' if i < @values.length - 1 # Add space after semicolon except for last
+      end
+      result
+    end
 
     # Enable implicit string conversion for comparisons
     alias to_str to_s
@@ -290,7 +300,7 @@ module Cataract
     # @param source [Declarations] Source Declarations being copied
     def initialize_copy(source)
       super
-      @values = source.instance_variable_get(:@values).dup
+      @values = source.to_a.dup
     end
 
     # Compare this Declarations with another object.
@@ -331,7 +341,7 @@ module Cataract
 
     # Parse "color: red; background: blue" string into array of Declaration structs
     def parse_declaration_string(str)
-      Cataract.parse_declarations(str)
+      Cataract::Backends.active.parse_declarations(str)
     end
   end
 end