cataract 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8c9aa122ff45945bef0a05d6fa6a5dcfd46252ffe5970bf288074db5d3514c9
-  data.tar.gz: cdafcb1ca599a58449dc03c239e5b8891f4399629dbdf7ca4e3ef23fb7f6ab94
+  metadata.gz: a1c4727f2f1b3c3aafa117ca105ee0d55a6d6f33b0fed789533af10c24173918
+  data.tar.gz: 86c0e96b1a953fb817fa235517e00215b4b363baea7d1225c5fcb2b9643b29c9
 SHA512:
-  metadata.gz: 35bbffc26c5eb757a90935fd0caf362818d80cc33af0860c738061ca3d0047f6b6d5c8124087d8283c0bb93b26699990279f98af96215456099a493d1e4720ee
-  data.tar.gz: 567ffe7ce56412c5913384ce8b6470b9d8d0e7e880463e2024a6d4cd6fca4bcb9b792ce0ca890aea1edf07ed218497a8369058f38b8b30ab94bee63694ef03e9
+  metadata.gz: 7282bde75fb5cd81ad2b7f2d7134a6fde2941a8f5320a4de2d463114d25bfc709e80f1639e9479cb69b7f22d685d203a7097fa0cf8c2e952041b733420991080
+  data.tar.gz: f8af1d50b389d64c36c5138f431b5b09f95ec3ca8f68b6c342ec280e7e1c84a8fca95ec6c95a81d97f9bced8d0f295acfbf2849ca47939e16cbf1b408544cdbe

data/.github/workflows/ci-manual-rubies.yml

@@ -4,12 +4,29 @@ on:
   workflow_dispatch:
 
 jobs:
+  test-jruby:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: jruby
+        bundler-cache: true
+
+    - name: Display Ruby version
+      run: ruby --version
+
+    - name: Run tests
+      run: bundle exec rake test:pure
+
   test-alt-rubies:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        ruby: [jruby, truffleruby]
+        ruby: [truffleruby, ruby-head]
 
     steps:
     - uses: actions/checkout@v4

data/.rubocop.yml

@@ -1,5 +1,8 @@
 inherit_from: .rubocop_todo.yml
 
+require:
+  - ./.rubocop/cataract/ban_assert_includes.rb
+
 plugins:
   - rubocop-performance
   - rubocop-minitest
@@ -66,13 +69,17 @@ Layout/LineLength:
 Minitest/MultipleAssertions:
   Max: 10
 
-Style/Documentation:
-   Enabled: true
-   Exclude:
+# Disable ambiguous block association warnings in tests
+# Tests frequently use assert/refute with blocks that call methods with their own blocks,
+# e.g., `assert sheet.rules.any? { |r| r == '.box { color: red; }' }`
+# This compares Rule objects against CSS strings using our custom Rule#== implementation.
+# While this triggers the ambiguous block warning, it's intentional and clear in context.
+Lint/AmbiguousBlockAssociation:
+  Exclude:
     - 'test/**/*'
-    - 'benchmarks/**/*'
-    - 'lib/cataract/pure/**/*.rb'
-    - 'lib/cataract/pure.rb'
+
+Style/Documentation:
+   Enabled: false
 
 # Disable modifier if/unless enforcement - use it when it's clearer, not because a cop says so
 Style/IfUnlessModifier:
@@ -143,3 +150,26 @@ Style/MapIntoArray:
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/cataract/pure/**/*.rb'
+
+Style/StderrPuts:
+  Exclude:
+    - 'scripts/**/*.rb'
+
+# Disable all performance cops in tests - test clarity is more important than micro-optimizations
+# Performance suggestions often hurt readability without meaningful benefit in test code
+Performance:
+  Exclude:
+    - 'test/**/*'
+
+Style/HashLikeCase:
+  Exclude:
+    - 'benchmarks/**/*'
+
+# Custom Cataract cops
+Cataract/BanAssertIncludes:
+  Enabled: true
+  Include:
+    - 'test/**/*'
+  Exclude:
+    - 'test/test_benchmark_doc_generator.rb'
+    - 'test/support/**/*'  # Support files define assert_contains which uses assert_includes internally

data/.rubocop_todo.yml

@@ -34,13 +34,13 @@ Layout/MultilineOperationIndentation:
 # This cop supports safe autocorrection (--autocorrect).
 Lint/AmbiguousOperatorPrecedence:
   Exclude:
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
 
 # Offense count: 2
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
 
 # Offense count: 1
 Lint/IneffectiveAccessModifier:
@@ -74,7 +74,7 @@ Minitest/EmptyLineBeforeAssertionMethods:
 Performance/UnfreezeString:
   Exclude:
     - 'lib/cataract/pure.rb'
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
     - 'lib/cataract/pure/parser.rb'
 
 # Offense count: 4
@@ -84,7 +84,7 @@ Performance/UnfreezeString:
 Style/ConditionalAssignment:
   Exclude:
     - 'lib/cataract/pure/imports.rb'
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
 
 # Offense count: 4
 # Configuration parameters: AllowedConstants.
@@ -123,7 +123,7 @@ Style/IdenticalConditionalBranches:
 # Configuration parameters: AllowIfModifier.
 Style/IfInsideElse:
   Exclude:
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
     - 'lib/cataract/pure/serializer.rb'
     - 'lib/cataract/pure/specificity.rb'
 
@@ -131,7 +131,7 @@ Style/IfInsideElse:
 # This cop supports safe autocorrection (--autocorrect).
 Style/NegatedIfElseCondition:
   Exclude:
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -157,7 +157,7 @@ Style/RedundantRegexpArgument:
 # Configuration parameters: AllowModifier.
 Style/SoleNestedConditional:
   Exclude:
-    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/flatten.rb'
     - 'lib/cataract/pure/parser.rb'
 
 # Offense count: 3

data/BENCHMARKS.md

@@ -20,15 +20,15 @@ Time to parse CSS into internal data structures
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
 |-----------|--------|----------------|-------------|----------------------|-------------------|
-| Small CSS (64 lines, 1.0KB) | 63.2K i/s | 3.56K i/s | 15.49K i/s | 4.7K i/s | 6.39K i/s |
-| Medium CSS with @media (139 lines, 1.6KB) | 40.14K i/s | 2.07K i/s | 8.76K i/s | 2.81K i/s | 3.54K i/s |
+| Small CSS (64 lines, 1.0KB) | 62.47K i/s | 3.59K i/s | 15.67K i/s | 4.73K i/s | 6.17K i/s |
+| Medium CSS with @media (139 lines, 1.6KB) | 39.7K i/s | 2.05K i/s | 8.64K i/s | 2.76K i/s | 3.52K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 18.58x faster (avg) |
-| Native vs Pure (YJIT) | 4.26x faster (avg) |
+| Native vs Pure (no YJIT) | 18.4x faster (avg) |
+| Native vs Pure (YJIT) | 4.2x faster (avg) |
 | YJIT impact on Pure Ruby | 4.31x faster (avg) |
 
 ---
@@ -39,16 +39,16 @@ Time to convert parsed CSS back to string format
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
 |-----------|--------|----------------|-------------|----------------------|-------------------|
-| Full Serialization (Bootstrap CSS - 191KB) | 1.79K i/s | 442.2 i/s | 716.9 i/s | 38.5 i/s | 39.7 i/s |
-| Media Type Filtering (print only) | 282.98K i/s | 114.55K i/s | 167.51K i/s | 2.74K i/s | 4.32K i/s |
+| Full Serialization (Bootstrap CSS - 191KB) | 1.77K i/s | 444.3 i/s | 676.3 i/s | 37.1 i/s | 35.9 i/s |
+| Media Type Filtering (print only) | 282.58K i/s | 114.27K i/s | 155.82K i/s | 2.67K i/s | 4.03K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 3.26x faster (avg) |
-| Native vs Pure (YJIT) | 1.69x faster (avg) |
-| YJIT impact on Pure Ruby | 1.46x faster (avg) |
+| Native vs Pure (no YJIT) | 3.23x faster (avg) |
+| Native vs Pure (YJIT) | 1.82x faster (avg) |
+| YJIT impact on Pure Ruby | 1.36x faster (avg) |
 
 ---
 
@@ -58,43 +58,43 @@ Time to calculate CSS selector specificity values
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
 |-----------|--------|----------------|-------------|----------------------|-------------------|
-| Simple Selectors | 8.31M i/s | 499.15K i/s | 2.59M i/s | 370.14K i/s | 344.42K i/s |
-| Compound Selectors | 6.57M i/s | 184.61K i/s | 403.41K i/s | 223.76K i/s | 204.19K i/s |
-| Combinators | 5.24M i/s | 144.7K i/s | 253.9K i/s | 188.05K i/s | 177.88K i/s |
-| Pseudo-classes & Pseudo-elements | 5.39M i/s | 115.46K i/s | 194.13K i/s | 116.96K i/s | 109.64K i/s |
-| :not() Pseudo-class (CSS3) | 3.31M i/s | 101.48K i/s | 160.62K i/s | 144.35K i/s | 141.24K i/s |
-| Complex Real-world Selectors | 4.09M i/s | 51.63K i/s | 77.37K i/s | 82.16K i/s | 80.6K i/s |
+| Simple Selectors | 7.35M i/s | 506.04K i/s | 2.59M i/s | 357.72K i/s | 353.42K i/s |
+| Compound Selectors | 6.36M i/s | 184.96K i/s | 406.99K i/s | 216.59K i/s | 214.86K i/s |
+| Combinators | 5.04M i/s | 146.91K i/s | 252.94K i/s | 185.44K i/s | 183.71K i/s |
+| Pseudo-classes & Pseudo-elements | 5.1M i/s | 116.46K i/s | 197.06K i/s | 113.05K i/s | 113.99K i/s |
+| :not() Pseudo-class (CSS3) | 3.23M i/s | 102.63K i/s | 161.55K i/s | 144.04K i/s | 144.53K i/s |
+| Complex Real-world Selectors | 4.01M i/s | 52.03K i/s | 77.65K i/s | 83.91K i/s | 82.03K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 41.16x faster (avg) |
-| Native vs Pure (YJIT) | 8.94x faster (avg) |
-| YJIT impact on Pure Ruby | 3.36x faster (avg) |
+| Native vs Pure (no YJIT) | 39.27x faster (avg) |
+| Native vs Pure (YJIT) | 8.43x faster (avg) |
+| YJIT impact on Pure Ruby | 3.32x faster (avg) |
 
 ---
 
-## CSS Merging
+## CSS Flattening (Cascade)
 
-Time to merge multiple CSS rule sets with same selector
+Time to flatten multiple CSS rule sets with same selector
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
 |-----------|--------|----------------|-------------|----------------------|-------------------|
-| No shorthand properties (large) | 10.5K i/s | 3.46K i/s | 6.73K i/s | 1.51K i/s | 2.27K i/s |
-| Simple properties | 125.51K i/s | 77.36K i/s | 110.86K i/s | 27.92K i/s | 40.42K i/s |
-| Cascade with specificity | 140.46K i/s | 80.08K i/s | 116.35K i/s | 31.48K i/s | 45.99K i/s |
-| Important declarations | 139.59K i/s | 80.29K i/s | 116.39K i/s | 30.84K i/s | 44.87K i/s |
-| Shorthand expansion | 10.5K i/s | 3.46K i/s | 6.73K i/s | 1.51K i/s | 2.27K i/s |
-| Complex merging | 24.74K i/s | 16.62K i/s | 23.57K i/s | 11.59K i/s | 16.48K i/s |
+| No shorthand properties (large) | 21.34K i/s | 3.11K i/s | 5.23K i/s | 1.58K i/s | 2.3K i/s |
+| Simple properties | 158.81K i/s | 75.72K i/s | 102.44K i/s | 28.29K i/s | 40.72K i/s |
+| Cascade with specificity | 204.11K i/s | 77.93K i/s | 108.77K i/s | 31.92K i/s | 46.39K i/s |
+| Important declarations | 203.43K i/s | 77.88K i/s | 109.38K i/s | 31.25K i/s | 45.25K i/s |
+| Shorthand expansion | 21.34K i/s | 3.11K i/s | 5.23K i/s | 1.58K i/s | 2.3K i/s |
+| Complex merging | 30.94K i/s | 16.09K i/s | 21.57K i/s | 11.6K i/s | 16.63K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 1.87x faster (avg) |
-| Native vs Pure (YJIT) | 1.16x faster (avg) |
-| YJIT impact on Pure Ruby | 1.45x faster (avg) |
+| Native vs Pure (no YJIT) | 3.03x faster (avg) |
+| Native vs Pure (YJIT) | 1.72x faster (avg) |
+| YJIT impact on Pure Ruby | 1.38x faster (avg) |
 
 ---
 
@@ -108,7 +108,7 @@ rake benchmark
 rake benchmark:parsing
 rake benchmark:serialization
 rake benchmark:specificity
-rake benchmark:merging
+rake benchmark:flattening
 
 # Generate documentation
 rake benchmark:generate_docs

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.2.1] - 2025-11-14
+
+- Fix serializer bug related to media queries
+
+## [0.2.0] - 2025-11-14
+
+- Major: CSS `@import` resolution refactored from string-concatenation to parsed-object architecture with proper charset handling, media query combining,
+and circular import detection
+- Major: Terminology change: all `merge` methods renamed to `flatten` to better represent CSS cascade behavior (old names deprecated with warnings)
+- Major: Rule equality now considers shorthand/longhand property equivalence (e.g., `margin: 10px` equals `margin-top: 10px; margin-right: 10px; ...`)
+- Performance: Flatten operation optimized with array-based property storage, pre-allocated frozen strings, and lazy specificity calculation
+- Feature: New Stylesheet collection methods (`+`, `-`, `|`, `concat`, `take`, `take_while`) with cascade rules applied
+- Feature: Added source order tracking for proper CSS cascade resolution
+
 ## [0.1.4] - 2025-11-12
 - Major: Pure Ruby implementation added (#12)
 - Fix: Media query serialization bugs - parentheses now preserved per CSS spec (min-width: 768px), fixed media query ordering

data/RAGEL_MIGRATION.md

@@ -2,7 +2,7 @@
 
 ## Why We Switched
 
-Started with Ragel as an experiment for the CSS parser, but quickly moved to hand-written pure C in October 2024.
+Started with Ragel as an experiment for the CSS parser, but quickly moved to hand-written pure C in October 2025.
 
 ### Performance
 
@@ -55,6 +55,6 @@ Pure C is more verbose than Ragel's DSL, but the performance gains and simpler b
 
 ## Details
 
-- Swapped in October 2024
+- Swapped in October 2025
 - Files: `css_parser.c`, `specificity.c`, `value_splitter.c`
 - API unchanged, all tests pass

data/README.md

@@ -181,7 +181,10 @@ Cataract parses and preserves all standard CSS including:
 
 Cataract supports converting colors between multiple CSS color formats with high precision.
 
-**Note:** Color conversion is an optional extension. Load it explicitly to reduce memory footprint:
+**Note:** Color conversion is an optional extension and _not_ loaded by default.
+
+<details>
+<summary>Color conversion examples and supported formats</summary>
 
 ```ruby
 require 'cataract'
@@ -241,6 +244,8 @@ sheet.convert_colors!(to: :hex)  # Converts all formats to hex
 - CSS Color Level 5 features (`none`, `infinity`, relative color syntax with `from`) are preserved but not converted
 - Unknown or future color functions are passed through unchanged
 
+</details>
+
 ### `@import` Support
 
 `@import` statements can be resolved with security controls:
@@ -301,7 +306,7 @@ Each `Rule` is a struct containing:
 - `specificity`: Calculated CSS specificity (cached)
 
 Implementation details:
-- **C implementation**: Critical paths implemented in C (parsing, merging, serialization)
+- **C implementation**: Critical paths implemented in C (parsing, cascade/flatten, serialization)
 - **Flat rule array**: All rules stored in a single array, preserving source order
 - **Efficient media query handling**: O(1) lookup via internal media index
 - **Memory efficient**: Minimal allocations, reuses string buffers where possible

data/Rakefile

@@ -79,7 +79,7 @@ task :benchmark do
   Rake::Task['benchmark:parsing'].invoke
   Rake::Task['benchmark:serialization'].invoke
   Rake::Task['benchmark:specificity'].invoke
-  Rake::Task['benchmark:merging'].invoke
+  Rake::Task['benchmark:flattening'].invoke
   puts "\n#{'-' * 80}"
   puts 'All benchmarks complete!'
   puts 'Generate documentation with: rake benchmark:generate_docs'
@@ -105,10 +105,10 @@ namespace :benchmark do
     ruby 'benchmarks/benchmark_specificity.rb'
   end
 
-  desc 'Benchmark CSS merging performance'
-  task merging: :compile do
-    puts 'Running merging benchmark...'
-    ruby 'benchmarks/benchmark_merging.rb'
+  desc 'Benchmark CSS flattening performance'
+  task flattening: :compile do
+    puts 'Running flattening benchmark...'
+    ruby 'benchmarks/benchmark_flattening.rb'
   end
 
   desc 'Benchmark string allocation optimization (buffer vs dynamic)'
@@ -195,14 +195,27 @@ task :lint do
 end
 
 # Fuzz testing
-desc 'Run fuzzer to test parser robustness (including color conversion)'
-task fuzz: :compile do
-  iterations = ENV['ITERATIONS'] || '10000'
-  puts "Running CSS parser fuzzer (#{iterations} iterations)..."
-  # Use system with ENV.to_h to preserve environment variables like FUZZ_GC_STRESS
-  system(ENV.to_h, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+namespace :fuzz do
+  desc 'Run fuzzer with C extension'
+  task c: :compile do
+    iterations = ENV['ITERATIONS'] || '10000'
+    puts "Running CSS parser fuzzer with C extension (#{iterations} iterations)..."
+    system(ENV.to_h, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+  end
+
+  desc 'Run fuzzer with pure Ruby implementation'
+  task :pure do
+    iterations = ENV['ITERATIONS'] || '10000'
+    debug_msg = ENV['FUZZ_DEBUG'] == '1' ? ' (debug mode)' : ''
+    puts "Running CSS parser fuzzer with pure Ruby (#{iterations} iterations#{debug_msg})..."
+    env = ENV.to_h.merge('CATARACT_PURE' => '1')
+    system(env, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+  end
 end
 
+desc 'Run fuzzer with both C extension and pure Ruby'
+task fuzz: ['fuzz:c', 'fuzz:pure']
+
 # Documentation generation with YARD
 begin
   require 'yard'

data/cataract.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{^(test|spec|features|benchmarks|scripts)/}) ||
+      f.match(%r{^(test|spec|features|benchmarks|scripts|\.rubocop)/}) ||
         f.match(/^(test|benchmark)_.*\.rb$/)
     end
   end

data/ext/cataract/cataract.c

@@ -7,6 +7,7 @@ VALUE cRule;
 VALUE cDeclaration;
 VALUE cAtRule;
 VALUE cStylesheet;
+VALUE cImportStatement;
 
 // Error class definitions (shared with main extension)
 VALUE eCataractError;
@@ -548,18 +549,34 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
 
     if (formatted) {
         // Formatted output with indentation
+        DEBUG_PRINTF("[SERIALIZE_RULE] Formatted mode, indent_level=%d, selector=%s\n", indent_level, RSTRING_PTR(selector));
         rb_str_append(result, selector);
         rb_str_cat2(result, " {\n");
 
+        // Build indent strings based on indent_level
+        // Declarations are inside the rule, so add 1 level (2 spaces per level)
+        // Closing brace matches the opening selector level
+        char decl_indent[MAX_INDENT_BUFFER];
+        char closing_indent[MAX_INDENT_BUFFER];
+        int decl_spaces = (indent_level + 1) * 2;
+        int closing_spaces = indent_level * 2;
+        memset(decl_indent, ' ', decl_spaces);
+        decl_indent[decl_spaces] = '\0';
+        memset(closing_indent, ' ', closing_spaces);
+        closing_indent[closing_spaces] = '\0';
+
         // Serialize own declarations with indentation (each on its own line)
         if (!NIL_P(declarations) && RARRAY_LEN(declarations) > 0) {
-            serialize_declarations_formatted(result, declarations, "  ");
+            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 nested children
         serialize_children_only(result, rules_array, rule_idx, rule_to_media, parent_to_children,
                               selector, declarations, formatted, indent_level + 1);
 
+        rb_str_cat2(result, closing_indent);
         rb_str_cat2(result, "}\n");
     } else {
         // Compact output
@@ -575,6 +592,9 @@ static void serialize_rule_with_children(VALUE result, VALUE rules_array, long r
 
         rb_str_cat2(result, " }\n");
     }
+
+    // Prevent compiler from optimizing away 'rule' before we're done with selector/declarations
+    RB_GC_GUARD(rule);
 }
 
 // New stylesheet serialization entry point - checks for nesting and delegates
@@ -625,6 +645,10 @@ static VALUE stylesheet_to_s_new(VALUE self, VALUE rules_array, VALUE media_inde
 
     DEBUG_PRINTF("[MAP] parent_to_children map: %s\n", RSTRING_PTR(rb_inspect(parent_to_children)));
 
+    // 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)
     // Children are serialized recursively
     DEBUG_PRINTF("[SERIALIZE] Starting serialization, total_rules=%ld\n", total_rules);
@@ -642,6 +666,34 @@ static VALUE stylesheet_to_s_new(VALUE self, VALUE rules_array, VALUE media_inde
             continue;
         }
 
+        // Get media for this rule
+        VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
+        VALUE rule_media = rb_hash_aref(rule_to_media, rule_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;
+            }
+        } else {
+            // In media - check if we need to open/change block
+            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");
+                }
+                // Open new media block
+                current_media = rule_media;
+                rb_str_cat2(result, "@media ");
+                rb_str_append(result, rb_sym2str(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);
@@ -656,6 +708,11 @@ static VALUE stylesheet_to_s_new(VALUE self, VALUE rules_array, VALUE media_inde
         );
     }
 
+    // Close final media block if still open
+    if (in_media_block) {
+        rb_str_cat2(result, "}\n");
+    }
+
     return result;
 }
 
@@ -778,6 +835,10 @@ static VALUE stylesheet_to_formatted_s_new(VALUE self, VALUE rules_array, VALUE
         }
     }
 
+    // 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);
@@ -788,20 +849,66 @@ static VALUE stylesheet_to_formatted_s_new(VALUE self, VALUE rules_array, VALUE
             continue;
         }
 
+        // Get media for this rule
+        VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
+        VALUE rule_media = rb_hash_aref(rule_to_media, rule_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
+            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
+                current_media = rule_media;
+                rb_str_cat2(result, "@media ");
+                rb_str_append(result, rb_sym2str(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, rule_to_media, parent_to_children,
             1,  // formatted (with indentation)
-            0   // indent_level (top-level)
+            in_media_block ? 1 : 0   // indent_level (1 if inside media block, 0 otherwise)
         );
     }
 
+    // Close final media block if still open
+    if (in_media_block) {
+        rb_str_cat2(result, "}\n");
+    }
+
     return result;
 }
 
@@ -1044,6 +1151,12 @@ void Init_native_extension(void) {
         rb_raise(rb_eLoadError, "Cataract::AtRule not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
     }
 
+    if (rb_const_defined(mCataract, rb_intern("ImportStatement"))) {
+        cImportStatement = rb_const_get(mCataract, rb_intern("ImportStatement"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::ImportStatement 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);
@@ -1057,12 +1170,14 @@ void Init_native_extension(void) {
     rb_define_module_function(mCataract, "_stylesheet_to_formatted_s", stylesheet_to_formatted_s_new, 4);
     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, "merge", cataract_merge_new, 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, "extract_imports", extract_imports, 1);
     rb_define_module_function(mCataract, "calculate_specificity", calculate_specificity, 1);
+    rb_define_module_function(mCataract, "_expand_shorthand", cataract_expand_shorthand, 1);
 
-    // Initialize merge constants (cached property strings)
-    init_merge_constants();
+    // Initialize flatten constants (cached property strings)
+    init_flatten_constants();
 
     // Export compile-time flags as a hash for runtime introspection
     VALUE compile_flags = rb_hash_new();