cataract 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89396bf500fc32cfa8d632d90f8b1ff5e80b93a24793cc8c6fd183ca47619f7e
-  data.tar.gz: bef49a87c354f9947616bb4d07047bb876e7a2861a7de2e2846f2dd0cd9cd8e8
+  metadata.gz: b8c9aa122ff45945bef0a05d6fa6a5dcfd46252ffe5970bf288074db5d3514c9
+  data.tar.gz: cdafcb1ca599a58449dc03c239e5b8891f4399629dbdf7ca4e3ef23fb7f6ab94
 SHA512:
-  metadata.gz: 0d395bcb60f2a6646daae924eabe1c83c2aa79e174de9186b6ab3bf9f855c34a2f464fa1d221e550afa47d4e271b0aaf9d4184986ac516d0feb412fecd18772f
-  data.tar.gz: feb093da902ee218121c112471c2ea899540373c9ce74eff0db588f94ae5ab0992f7b39014bf6a3edb74a54e9b11e7f80d7c584f15dd08a56e4e4b37a63ee2c1
+  metadata.gz: 35bbffc26c5eb757a90935fd0caf362818d80cc33af0860c738061ca3d0047f6b6d5c8124087d8283c0bb93b26699990279f98af96215456099a493d1e4720ee
+  data.tar.gz: 567ffe7ce56412c5913384ce8b6470b9d8d0e7e880463e2024a6d4cd6fca4bcb9b792ce0ca890aea1edf07ed218497a8369058f38b8b30ab94bee63694ef03e9

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

@@ -0,0 +1,27 @@
+name: CI - Manual Rubies
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test-alt-rubies:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [jruby, truffleruby]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+
+    - name: Display Ruby version
+      run: ruby --version
+
+    - name: Run tests
+      run: bundle exec rake compile test

data/.overcommit.yml

@@ -8,7 +8,7 @@ PreCommit:
   RuboCop:
     enabled: true
     on_warn: fail # Treat warnings as failures
-    command: ['bundle', 'exec', 'rubocop']
+    # Remove explicit command to allow Overcommit to pass staged files only
     flags: ['--force-exclusion']
     include:
       - '**/*.rb'

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 plugins:
   - rubocop-performance
   - rubocop-minitest
@@ -44,6 +46,12 @@ Metrics/BlockLength:
 Metrics/ParameterLists:
   Enabled: false
 
+# Block nesting in byte-level parsers reflects CSS structure, not complexity
+# Extracting helper methods would add method dispatch overhead in hot path
+Metrics/BlockNesting:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
 # Keep line length for tests disabled - long test strings are fine
 Layout/LineLength:
   Exclude:
@@ -63,6 +71,8 @@ Style/Documentation:
    Exclude:
     - 'test/**/*'
     - 'benchmarks/**/*'
+    - 'lib/cataract/pure/**/*.rb'
+    - 'lib/cataract/pure.rb'
 
 # Disable modifier if/unless enforcement - use it when it's clearer, not because a cop says so
 Style/IfUnlessModifier:
@@ -81,3 +91,55 @@ Naming/VariableNumber:
 Naming/PredicatePrefix:
   Exclude:
     - 'lib/**/*.rb'
+
+# Performance-critical hot path exclusions for lib/cataract/pure
+# These cosmetic style rules add overhead via method dispatch or allocation
+
+# Disable numeric predicates in hot path - method dispatch overhead
+# Benchmark shows `> 0` is faster than `.positive?` due to avoiding method call
+Style/NumericPredicate:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable multiple comparison style - avoid array allocation
+# `||` chain is faster than `Array#include?` which allocates an array
+Style/MultipleComparison:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable zero-length predicate in hot path - method dispatch overhead
+# Direct comparison `.length > 0` is faster than `.empty?` method call
+Style/ZeroLengthPredicate:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Benchmarked range vs offsets. Range has to allocated
+# so not ideal in the hot path
+Style/SlicingWithRange:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable modifier while/until style in parsing code - readability
+# Byte-level parsing loops are clearer with traditional while...end form
+# Example: `while i < len && ident_char?(selector.getbyte(i)); i += 1; end`
+# is more readable than `i += 1 while i < len && ident_char?(selector.getbyte(i))`
+Style/WhileUntilModifier:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable between? suggestion in hot path - method dispatch overhead
+# Benchmark shows `byte >= X && byte <= Y` is 2.60-4.82x faster than `.between?(X, Y)`
+Style/ComparableBetween:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable map suggestion for array building - performance
+# Benchmark shows `each { arr << x }` is 1.05-1.11x faster than `arr = map { x }`
+# The << pattern is faster than map's implicit array return (even without YJIT)
+Style/MapIntoArray:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'

data/.rubocop_todo.yml

@@ -0,0 +1,186 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-11-12 02:24:55 UTC using RuboCop version 1.81.7.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 13
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLineAfterGuardClause:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+    - 'scripts/generate_benchmarks_md.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+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
+# This cop supports safe autocorrection (--autocorrect).
+Lint/AmbiguousOperatorPrecedence:
+  Exclude:
+    - 'lib/cataract/pure/merge.rb'
+
+# Offense count: 2
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/cataract/pure/merge.rb'
+
+# Offense count: 1
+Lint/IneffectiveAccessModifier:
+  Exclude:
+    - 'benchmarks/speedup_calculator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: ContextCreatingMethods, MethodCreatingMethods.
+Lint/UselessAccessModifier:
+  Exclude:
+    - 'benchmarks/speedup_calculator.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+Lint/UselessAssignment:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Minitest/EmptyLineBeforeAssertionMethods:
+  Exclude:
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/UnfreezeString:
+  Exclude:
+    - 'lib/cataract/pure.rb'
+    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
+# SupportedStyles: assign_to_condition, assign_inside_condition
+Style/ConditionalAssignment:
+  Exclude:
+    - 'lib/cataract/pure/imports.rb'
+    - 'lib/cataract/pure/merge.rb'
+
+# Offense count: 4
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'test/**/*'
+    - 'benchmarks/**/*'
+    - 'lib/cataract/pure/**/*.rb'
+    - 'lib/cataract/pure.rb'
+    - 'lib/cataract/at_rule.rb'
+    - 'lib/cataract/declaration.rb'
+    - 'lib/cataract/rule.rb'
+
+# Offense count: 4
+# Configuration parameters: MinBranchesCount.
+Style/HashLikeCase:
+  Exclude:
+    - 'benchmarks/merging_tests.rb'
+    - 'benchmarks/parsing_tests.rb'
+    - 'benchmarks/serialization_tests.rb'
+    - 'benchmarks/specificity_tests.rb'
+
+# Offense count: 14
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/IdenticalConditionalBranches:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+    - 'lib/cataract/pure/parser.rb'
+    - 'lib/cataract/pure/serializer.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowIfModifier.
+Style/IfInsideElse:
+  Exclude:
+    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/serializer.rb'
+    - 'lib/cataract/pure/specificity.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/NegatedIfElseCondition:
+  Exclude:
+    - 'lib/cataract/pure/merge.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantAssignment:
+  Exclude:
+    - 'lib/cataract/pure/specificity.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantParentheses:
+  Exclude:
+    - 'lib/cataract/pure/imports.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantRegexpArgument:
+  Exclude:
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowModifier.
+Style/SoleNestedConditional:
+  Exclude:
+    - 'lib/cataract/pure/merge.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'benchmarks/merging_tests.rb'
+    - 'scripts/generate_benchmarks_md.rb'
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: .
+# SupportedStyles: percent, brackets
+Style/SymbolArray:
+  EnforcedStyle: percent
+  MinSize: 3
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 184

data/BENCHMARKS.md

@@ -4,176 +4,97 @@
 
 # Performance Benchmarks
 
-Comprehensive performance comparison between Cataract and css_parser gem.
+Performance comparison between Cataract's C extension and pure Ruby implementations, with css_parser as a reference.
 
 ## Test Environment
 
-- **Ruby**: ruby 3.4.5 (2025-07-16 revision 20cda200d3) +YJIT +PRISM [arm64-darwin23]
+- **Ruby**: ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +YJIT +PRISM [arm64-darwin23]
 - **CPU**: Apple M1 Pro
 - **Memory**: 32GB
 - **OS**: macOS 14.5
-- **Generated**: 2025-10-30T16:01:15-05:00
+- **Generated**: 2025-11-11T16:02:08-06:00
 
-<details>
-<summary><h2>CSS Parsing</h2></summary>
-
-Performance of parsing CSS into internal data structures.
+## CSS Parsing
 
 Time to parse CSS into internal data structures
 
-### Small CSS (64 lines, 1.0KB)
-
-
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | 6.16K i/s | 162.34 μs |
-| **Cataract** | **63.79K i/s** | **15.68 μs** |
-| **Speedup** | **10.36x faster** | |
-
-### Medium CSS with @media (139 lines, 1.6KB)
-
+| 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 |
 
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | 3.44K i/s | 290.64 μs |
-| **Cataract** | **41.45K i/s** | **24.13 μs** |
-| **Speedup** | **12.05x faster** | |
+### Speedups
 
-
-</details>
+| Comparison | Speedup |
+|------------|---------|
+| Native vs Pure (no YJIT) | 18.58x faster (avg) |
+| Native vs Pure (YJIT) | 4.26x faster (avg) |
+| YJIT impact on Pure Ruby | 4.31x faster (avg) |
 
 ---
 
-<details>
-<summary><h2>CSS Serialization (to_s)</h2></summary>
-
-Performance of converting parsed CSS back to string format.
+## CSS Serialization
 
 Time to convert parsed CSS back to string format
 
-### Full Serialization (Bootstrap CSS - 191KB)
-
-
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | 34.0 i/s | 29.41 ms |
-| **Cataract** | **714.8 i/s** | **1.4 ms** |
-| **Speedup** | **21.02x faster** | |
+| 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 |
 
-### Media Type Filtering (print only)
+### Speedups
 
-
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | 4.06K i/s | 246.56 μs |
-| **Cataract** | **232.22K i/s** | **4.31 μs** |
-| **Speedup** | **57.26x faster** | |
-
-
-</details>
+| 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) |
 
 ---
 
-<details>
-<summary><h2>Specificity Calculation</h2></summary>
-
-Performance of calculating CSS selector specificity values.
+## Specificity Calculation
 
 Time to calculate CSS selector specificity values
 
-| Test Case | Speedup |
-|-----------|---------|
-| Simple Selectors | **22.03x faster** |
-| Compound Selectors | **30.55x faster** |
-| Combinators | **28.34x faster** |
-| Pseudo-classes & Pseudo-elements | **46.06x faster** |
-| :not() Pseudo-class (CSS3) | **23.64x faster** |
-| Complex Real-world Selectors | **49.17x faster** |
+| 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 |
 
-**Summary:** 22.03x faster to 49.17x faster (avg 33.3x faster)
+### Speedups
 
-</details>
+| 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) |
 
 ---
 
-<details>
-<summary><h2>CSS Merging</h2></summary>
-
-Performance of merging multiple CSS rule sets with the same selector.
+## CSS Merging
 
 Time to merge multiple CSS rule sets with same selector
 
-| Test Case | Speedup |
-|-----------|---------|
-| No shorthand properties (large) | **4.14x faster** |
-| Simple properties | **3.86x faster** |
-| Cascade with specificity | **5.75x faster** |
-| Important declarations | **6.1x faster** |
-| Shorthand expansion | **4.16x faster** |
-| Complex merging | **3.07x faster** |
-
-**Summary:** 3.07x faster to 6.1x faster (avg 4.51x faster)
-
-### What's Being Tested
-- Specificity-based CSS cascade (ID > class > element)
-- `!important` declaration handling
-- Shorthand property expansion (e.g., `margin` → `margin-top`, `margin-right`, etc.)
-- Shorthand property creation from longhand properties
-
-</details>
-
----
-
-<details>
-<summary><h2>YJIT Impact</h2></summary>
-
-Impact of Ruby's YJIT JIT compiler on Ruby-side operations. The C extension performance is the same regardless of YJIT.
-
-Ruby-side operations with and without YJIT
-
-### Operations Per Second
-
-| Operation | Without YJIT | With YJIT | YJIT Improvement |
-|-----------|--------------|-----------|------------------|
-| property access | 227.18K i/s | 322.32K i/s | **1.42x faster** (42% faster) |
-| declaration merging | 204.26K i/s | 337.81K i/s | **1.65x faster** (65% faster) |
-| to_s generation | 242.66K i/s | 391.16K i/s | **1.61x faster** (61% faster) |
-| parse + iterate | 121.52K i/s | 142.77K i/s | **1.17x faster** (17% faster) |
-
-### Key Takeaways
-- YJIT provides significant performance boost for Ruby-side operations
-- Greatest impact on declaration merging
-- Parse + iterate benefits least since most work is in C
-- Recommended: Enable YJIT in production (`--yjit` flag or `RUBY_YJIT_ENABLE=1`)
-
-</details>
-
----
-
-## Summary
-
-### Performance Highlights
-
-| Category | Min Speedup | Max Speedup | Avg Speedup |
-|----------|-------------|-------------|-------------|
-| **Parsing** | 10.36x faster | 12.05x faster | 11.2x faster |
-| **Serialization** | 21.02x faster | 57.26x faster | 39.14x faster |
-| **Specificity** | 22.03x faster | 49.17x faster | 33.3x faster |
-| **Merging** | 3.07x faster | 6.1x faster | 4.51x faster |
-
-### Implementation Notes
-
-1. **C Extension**: Critical paths (parsing, specificity, merging, serialization) implemented in C
-2. **Efficient Data Structures**: Rules grouped by media query for O(1) lookups
-3. **Memory Efficient**: Pre-allocated string buffers, minimal Ruby object allocations
-4. **Optimized Algorithms**: Purpose-built CSS specificity calculator
+| 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 |
 
-### Use Cases
+### Speedups
 
-- **Large CSS files**: Handles complex stylesheets efficiently
-- **Specificity calculations**: Optimized for selector analysis
-- **High-volume processing**: Reduced allocations minimize GC pressure
-- **Production applications**: Tested with Bootstrap CSS and real-world stylesheets
+| 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) |
 
 ---
 
@@ -181,14 +102,13 @@ Ruby-side operations with and without YJIT
 
 ```bash
 # All benchmarks
-rake benchmark 2>&1 | tee benchmark_output.txt
+rake benchmark
 
 # Individual benchmarks
 rake benchmark:parsing
 rake benchmark:serialization
 rake benchmark:specificity
 rake benchmark:merging
-rake benchmark:yjit
 
 # Generate documentation
 rake benchmark:generate_docs
@@ -196,6 +116,7 @@ rake benchmark:generate_docs
 
 ## Notes
 
-- All benchmarks use benchmark-ips with 3s warmup and 5-10s measurement periods
-- Measurements are median i/s (iterations per second) with standard deviation
-- css_parser gem must be installed for comparison benchmarks
+- Benchmarks use benchmark-ips with 1-2s warmup and 2-5s measurement periods
+- Measurements show median iterations per second (i/s)
+- css_parser gem is included for reference comparison
+- YJIT is enabled/disabled per subprocess for accurate comparison

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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
+- Fix: CSS merge declaration ordering made consistent between C and pure Ruby implementations
+- Fix: Shorthand property recreation (margin, padding, border, font, background, list-style) ordering
+- Fix: Rule equality comparisons (Rule#==, AtRule#==)
+
+## [0.1.3] - 2025-11-11
+- Fix: Proper handling of at-rules (@keyframes, @font-face, etc.) during CSS merge operations
+
 ## [0.1.2] - 2025-11-11
 
 - Fix segfault in merge

data/README.md

@@ -34,6 +34,32 @@ gem install cataract
 
 - Ruby >= 3.1.0
 
+### Pure Ruby Implementation
+
+Cataract includes a pure Ruby implementation alongside the C extension. This is useful for:
+- Platforms where C extensions cannot be compiled
+- Development/debugging without needing to recompile C code
+- Environments with restricted native code execution
+
+**In your Gemfile:**
+```ruby
+gem 'cataract', require: 'cataract/pure'
+```
+
+**Or set environment variable:**
+```ruby
+# For CI, testing, or one-off usage
+ENV['CATARACT_PURE'] = '1'
+require 'cataract'
+```
+
+**Check which implementation is loaded:**
+```ruby
+Cataract::IMPLEMENTATION  # => :native or :ruby
+```
+
+**Note:** The pure Ruby implementation does not include color conversion functionality (`convert_colors!`), which is only available in the C extension.
+
 ## Usage
 
 ### Basic Parsing
@@ -142,9 +168,11 @@ See [BENCHMARKS.md](BENCHMARKS.md) for detailed performance comparisons.
 
 ## CSS Support
 
-Cataract aims to support all CSS specifications including:
+Cataract parses and preserves all standard CSS including:
 - **Selectors**: All CSS2/CSS3 selectors (type, class, ID, attribute, pseudo-classes, pseudo-elements, combinators)
-- **At-rules**: `@media`, `@font-face`, `@keyframes`, `@supports`, `@page`, `@layer`, `@container`, `@property`, `@scope`, `@counter-style`
+- **At-rules**:
+  - **`@media`**: Special handling with indexing and filtering API (`with_media(:print)`, `with_media(:all)`)
+  - **Others** (`@font-face`, `@keyframes`, `@supports`, `@page`, `@layer`, `@container`, `@property`, `@scope`, `@counter-style`): Parsed and preserved as-is (pass-through)
 - **Media Queries**: Full support including nested queries and media features
 - **Special syntax**: Data URIs, `calc()`, `url()`, CSS functions with parentheses
 - **!important**: Full support with correct cascade behavior