cataract 0.3.0 → 0.5.0

data/ext/cataract/flatten.c

@@ -644,12 +644,15 @@ static int flatten_selector_group_callback(VALUE group_key, VALUE group_indices,
 
     int new_rule_id = *ctx->rule_id_counter;
 
-    // Extract media_query_id from first rule in group (all should have same media_query_id)
+    // Extract media_query_id/conditional_group_id from first rule in group
+    // (all should share both, same as selector_list_id above)
     VALUE media_query_id = Qnil;
+    VALUE conditional_group_id = Qnil;
     if (RARRAY_LEN(group_indices) > 0) {
         long first_rule_idx = FIX2LONG(RARRAY_AREF(group_indices, 0));
         VALUE first_rule = RARRAY_AREF(ctx->rules_array, first_rule_idx);
         media_query_id = rb_struct_aref(first_rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+        conditional_group_id = rb_struct_aref(first_rule, INT2FIX(RULE_CONDITIONAL_GROUP_ID));
     }
 
     // Track old rule IDs to new rule ID mapping (only for rules in media queries)
@@ -672,7 +675,8 @@ static int flatten_selector_group_callback(VALUE group_key, VALUE group_indices,
         Qnil,  // parent_rule_id
         Qnil,  // nesting_style
         selector_list_id,  // Preserve selector_list_id if all rules in group share same ID
-        media_query_id  // Preserve media_query_id from source rules
+        media_query_id,  // Preserve media_query_id from source rules
+        conditional_group_id  // Preserve conditional_group_id from source rules
     );
     rb_ary_push(ctx->merged_rules, new_rule);
 

data/ext/cataract/specificity.c

@@ -13,6 +13,8 @@
  *   - :not() doesn't count itself, but its content does
  *   - Legacy pseudo-elements with single colon (:before) count as pseudo-elements
  *   - Universal selector (*) has zero specificity
+ *   - A namespace prefix (ns|E, *|E, |E) contributes zero itself - only the
+ *     local name after '|' counts, same as a bare "E" would
  */
 
 #include "cataract.h"
@@ -188,14 +190,23 @@ VALUE calculate_specificity(VALUE self, VALUE selector_string) {
             continue;
         }
 
-        // Type selector (element name): div, span, etc.
+        // Type selector (element name): div, span, etc. - or a namespace
+        // prefix (css-namespaces-3 qname grammar: prefix? '|' ident). A
+        // prefix contributes nothing itself; only the local name after '|'
+        // is the real type selector, so don't count it here - just skip
+        // past it and the separator and let the next iteration count the
+        // local name instead.
         if ((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z')) {
-            element_count++;
             // Skip the identifier
             while (p < pe && ((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') ||
                               (*p >= '0' && *p <= '9') || *p == '-' || *p == '_')) {
                 p++;
             }
+            if (p < pe && *p == '|') {
+                p++; // skip namespace separator - prefix itself doesn't count
+                continue;
+            }
+            element_count++;
             continue;
         }
 

data/lib/cataract/at_rule.rb

@@ -8,7 +8,6 @@ module Cataract
   # The content field varies by at-rule type:
   # - `@keyframes`: Array of Rule (keyframe percentage blocks like "0%", "100%")
   # - `@font-face`: Array of Declaration (font property declarations)
-  # - `@supports`: Array of Rule (conditional rules)
   #
   # @example Parse @keyframes
   #   css = "@keyframes fade { 0% { opacity: 0; } 100% { opacity: 1; } }"
@@ -29,7 +28,10 @@ module Cataract
   # @attr [Array<Rule>, Array<Declaration>] content Nested rules or declarations
   # @attr [nil] specificity Always nil for at-rules (they don't have CSS specificity)
   # @attr [Integer, nil] media_query_id ID of MediaQuery if inside @media block, nil otherwise
-  AtRule = Struct.new(:id, :selector, :content, :specificity, :media_query_id) unless const_defined?(:AtRule)
+  # @attr [Integer, nil] conditional_group_id ID of ConditionalGroup if inside @supports/@layer/@container/@scope, nil otherwise
+  unless const_defined?(:AtRule)
+    AtRule = Struct.new(:id, :selector, :content, :specificity, :media_query_id, :conditional_group_id)
+  end
 
   class AtRule
     # Check if this is a selector-based rule (vs an at-rule like @keyframes).

data/lib/cataract/conditional_group.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Cataract
+  # ConditionalGroup represents a CSS "conditional group" at-rule wrapper -
+  # @supports, @layer, @container, or @scope.
+  #
+  # Like MediaQuery, these are stored in the Stylesheet and referenced by
+  # Rules/AtRules via conditional_group_id, so the rules they wrap stay flat
+  # and queryable in Stylesheet#rules while the wrapper's own name/condition
+  # (and nesting inside other conditional groups, via parent_id) survive for
+  # round-trip serialization. Cataract never evaluates the condition/name
+  # (no feature-query or container-query matching) - it's kept as opaque
+  # text.
+  #
+  # @example Access conditional-group properties
+  #   group = ConditionalGroup.new(0, :supports, nil, '(display: grid)', nil)
+  #   group.id #=> 0
+  #   group.type #=> :supports
+  #   group.condition #=> "(display: grid)"
+  #
+  # @attr [Integer] id Unique identifier for this conditional group within the stylesheet
+  # @attr [Symbol] type At-rule kind (:supports, :layer, :container, :scope)
+  # @attr [String, nil] name Named form (e.g. `@layer utilities`, `@container sidebar`), nil if unnamed
+  # @attr [String, nil] condition Opaque condition/prelude text (feature query, container query, scope root/limit), nil if none
+  # @attr [Integer, nil] parent_id Id of the enclosing ConditionalGroup, or nil if not nested inside another one
+  ConditionalGroup = Struct.new(:id, :type, :name, :condition, :parent_id) do
+    # Create a ConditionalGroup with keyword arguments for readability.
+    #
+    # @param id [Integer] Unique ID for this conditional group
+    # @param type [Symbol] At-rule kind (:supports, :layer, :container, :scope)
+    # @param name [String, nil] Named form, if any
+    # @param condition [String, nil] Opaque condition/prelude text, if any
+    # @param parent_id [Integer, nil] Enclosing ConditionalGroup's id, if nested
+    # @return [ConditionalGroup] New conditional group instance
+    #
+    # @example
+    #   ConditionalGroup.make(id: 0, type: :supports, condition: '(display: grid)')
+    def self.make(id:, type:, name: nil, condition: nil, parent_id: nil)
+      new(id, type, name, condition, parent_id)
+    end
+
+    # Compare conditional groups for equality based on type, name, condition,
+    # and nesting. IDs are not considered since they're internal identifiers.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if conditional groups match
+    def ==(other)
+      case other
+      when ConditionalGroup
+        type == other.type && name == other.name && condition == other.condition
+      else
+        false
+      end
+    end
+    alias_method :eql?, :==
+
+    # Generate hash code for this conditional group.
+    #
+    # @return [Integer] hash code
+    def hash
+      [self.class, type, name, condition].hash
+    end
+
+    # Get detailed inspection string.
+    #
+    # @return [String] Inspection string
+    def inspect
+      "#<ConditionalGroup id=#{id} type=#{type.inspect} name=#{name.inspect} " \
+        "condition=#{condition.inspect} parent_id=#{parent_id.inspect}>"
+    end
+  end
+end

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

data/lib/cataract/native.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Native (C extension) backend for Cataract.
+#
+# Load this instead of the pure Ruby version by NOT setting CATARACT_PURE
+# before requiring 'cataract' (not by requiring this file directly -
+# lib/cataract.rb is what sets up Cataract::Backends.active and the
+# top-level identity constants like IMPLEMENTATION; this file alone does
+# not):
+#   require 'cataract'
+
+require_relative 'error'
+require_relative 'version'
+require_relative 'constants'
+
+# Load struct definitions first (before the C extension) - the extension's
+# Init function looks these up and raises if they're missing.
+require_relative 'declaration'
+require_relative 'rule'
+require_relative 'at_rule'
+require_relative 'media_query'
+require_relative 'conditional_group'
+require_relative 'import_statement'
+
+require_relative 'native_extension'
+
+# Load supporting Ruby files (used by both implementations)
+require_relative 'stylesheet_scope'
+require_relative 'stylesheet'
+require_relative 'declarations'
+require_relative 'import_resolver'

data/lib/cataract/pure/byte_constants.rb

@@ -4,80 +4,84 @@
 # Using getbyte() instead of String#[] to avoid allocating millions of string objects
 
 module Cataract
-  # Whitespace bytes
-  BYTE_SPACE     = 32  # ' '
-  BYTE_TAB       = 9   # '\t'
-  BYTE_NEWLINE   = 10  # '\n'
-  BYTE_CR        = 13  # '\r'
+  module Backends
+    class PureImpl
+      # Whitespace bytes
+      BYTE_SPACE     = 32  # ' '
+      BYTE_TAB       = 9   # '\t'
+      BYTE_NEWLINE   = 10  # '\n'
+      BYTE_CR        = 13  # '\r'
 
-  # CSS structural characters
-  BYTE_AT        = 64  # '@'
-  BYTE_LBRACE    = 123 # '{'
-  BYTE_RBRACE    = 125 # '}'
-  BYTE_LPAREN    = 40  # '('
-  BYTE_RPAREN    = 41  # ')'
-  BYTE_LBRACKET  = 91  # '['
-  BYTE_RBRACKET  = 93  # ']'
-  BYTE_SEMICOLON = 59  # ';'
-  BYTE_COLON     = 58  # ':'
-  BYTE_COMMA     = 44  # ','
+      # CSS structural characters
+      BYTE_AT        = 64  # '@'
+      BYTE_LBRACE    = 123 # '{'
+      BYTE_RBRACE    = 125 # '}'
+      BYTE_LPAREN    = 40  # '('
+      BYTE_RPAREN    = 41  # ')'
+      BYTE_LBRACKET  = 91  # '['
+      BYTE_RBRACKET  = 93  # ']'
+      BYTE_SEMICOLON = 59  # ';'
+      BYTE_COLON     = 58  # ':'
+      BYTE_COMMA     = 44  # ','
 
-  # Comment characters
-  BYTE_SLASH     = 47  # '/'
-  BYTE_STAR      = 42  # '*'
+      # Comment characters
+      BYTE_SLASH     = 47  # '/'
+      BYTE_STAR      = 42  # '*'
 
-  # Quote characters
-  BYTE_SQUOTE    = 39  # "'"
-  BYTE_DQUOTE    = 34  # '"'
+      # Quote characters
+      BYTE_SQUOTE    = 39  # "'"
+      BYTE_DQUOTE    = 34  # '"'
 
-  # Selector characters
-  BYTE_HASH      = 35  # '#'
-  BYTE_DOT       = 46  # '.'
-  BYTE_GT        = 62  # '>'
-  BYTE_PLUS      = 43  # '+'
-  BYTE_TILDE     = 126 # '~'
-  BYTE_ASTERISK  = 42  # '*'
-  BYTE_AMPERSAND = 38  # '&'
+      # Selector characters
+      BYTE_HASH      = 35  # '#'
+      BYTE_DOT       = 46  # '.'
+      BYTE_GT        = 62  # '>'
+      BYTE_PLUS      = 43  # '+'
+      BYTE_TILDE     = 126 # '~'
+      BYTE_ASTERISK  = 42  # '*'
+      BYTE_AMPERSAND = 38  # '&'
 
-  # Other
-  BYTE_HYPHEN     = 45 # '-'
-  BYTE_UNDERSCORE = 95 # '_'
-  BYTE_BACKSLASH  = 92 # '\\'
-  BYTE_BANG       = 33 # '!'
-  BYTE_PERCENT    = 37 # '%'
-  BYTE_EQUALS     = 61 # '='
-  BYTE_CARET      = 94 # '^'
-  BYTE_DOLLAR     = 36 # '$'
-  BYTE_PIPE       = 124 # '|'
+      # Other
+      BYTE_HYPHEN     = 45 # '-'
+      BYTE_UNDERSCORE = 95 # '_'
+      BYTE_BACKSLASH  = 92 # '\\'
+      BYTE_BANG       = 33 # '!'
+      BYTE_PERCENT    = 37 # '%'
+      BYTE_EQUALS     = 61 # '='
+      BYTE_CARET      = 94 # '^'
+      BYTE_DOLLAR     = 36 # '$'
+      BYTE_PIPE       = 124 # '|'
 
-  # Specific lowercase letters (for keyword matching)
-  BYTE_LOWER_U    = 117 # 'u'
-  BYTE_LOWER_R    = 114 # 'r'
-  BYTE_LOWER_L    = 108 # 'l'
-  BYTE_LOWER_D    = 100 # 'd'
-  BYTE_LOWER_T    = 116 # 't'
-  BYTE_LOWER_N    = 110 # 'n'
+      # Specific lowercase letters (for keyword matching)
+      BYTE_LOWER_U    = 117 # 'u'
+      BYTE_LOWER_R    = 114 # 'r'
+      BYTE_LOWER_L    = 108 # 'l'
+      BYTE_LOWER_D    = 100 # 'd'
+      BYTE_LOWER_T    = 116 # 't'
+      BYTE_LOWER_N    = 110 # 'n'
 
-  # Specific uppercase letters (for case-insensitive matching)
-  BYTE_UPPER_U    = 85  # 'U'
-  BYTE_UPPER_R    = 82  # 'R'
-  BYTE_UPPER_L    = 76  # 'L'
-  BYTE_UPPER_D    = 68  # 'D'
-  BYTE_UPPER_T    = 84  # 'T'
-  BYTE_UPPER_N    = 78  # 'N'
+      # Specific uppercase letters (for case-insensitive matching)
+      BYTE_UPPER_U    = 85  # 'U'
+      BYTE_UPPER_R    = 82  # 'R'
+      BYTE_UPPER_L    = 76  # 'L'
+      BYTE_UPPER_D    = 68  # 'D'
+      BYTE_UPPER_T    = 84  # 'T'
+      BYTE_UPPER_N    = 78  # 'N'
 
-  # Letter ranges (a-z, A-Z)
-  BYTE_LOWER_A   = 97  # 'a'
-  BYTE_LOWER_Z   = 122 # 'z'
-  BYTE_UPPER_A   = 65  # 'A'
-  BYTE_UPPER_Z   = 90  # 'Z'
-  BYTE_CASE_DIFF = 32  # Difference between lowercase and uppercase ('a' - 'A')
+      # Letter ranges (a-z, A-Z)
+      BYTE_LOWER_A   = 97  # 'a'
+      BYTE_LOWER_Z   = 122 # 'z'
+      BYTE_UPPER_A   = 65  # 'A'
+      BYTE_UPPER_Z   = 90  # 'Z'
+      BYTE_CASE_DIFF = 32  # Difference between lowercase and uppercase ('a' - 'A')
 
-  # Digit range (0-9)
-  BYTE_DIGIT_0   = 48  # '0'
-  BYTE_DIGIT_9   = 57  # '9'
+      # Digit range (0-9)
+      BYTE_DIGIT_0   = 48  # '0'
+      BYTE_DIGIT_9   = 57  # '9'
 
-  # Nesting styles (for CSS nesting support)
-  NESTING_STYLE_IMPLICIT = 0  # Implicit nesting: .parent { .child { ... } } => .parent .child
-  NESTING_STYLE_EXPLICIT = 1  # Explicit nesting: .parent { &:hover { ... } } => .parent:hover
+      # Nesting styles (for CSS nesting support)
+      NESTING_STYLE_IMPLICIT = 0  # Implicit nesting: .parent { .child { ... } } => .parent .child
+      NESTING_STYLE_EXPLICIT = 1  # Explicit nesting: .parent { &:hover { ... } } => .parent:hover
+    end
+  end
 end

data/lib/cataract/pure/declarations.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Pure Ruby CSS parser - standalone declaration-list string parsing
+# NO REGEXP ALLOWED - char-by-char parsing only
+#
+# Backs Declarations.new(some_string), NOT the main parser's declaration
+# handling - the two intentionally disagree in a few ways:
+#   - Custom properties (--foo) are downcased here too (the main parser
+#     preserves their case, since they're case-sensitive per spec)
+#   - No relative-URL conversion (there's no base_uri to convert against)
+#   - A missing colon stops parsing entirely, rather than recovering at the
+#     next semicolon like the main parser does
+# Mirrors ext/cataract/cataract.c's new_parse_declarations_string exactly,
+# byte for byte, since both backends must agree here.
+
+module Cataract
+  module Backends
+    class PureImpl
+      # Parse a standalone CSS declaration-list string ("color: red; margin: 10px")
+      # into an array of Declaration structs.
+      #
+      # @param str [String] CSS declarations, optionally wrapped in { ... }
+      # @return [Array<Declaration>] Parsed declarations
+      def parse_declarations(str)
+        fin = str.bytesize
+        pos = 0
+
+        # Strip outer braces and whitespace (css_parser compatibility)
+        pos += 1 while pos < fin && (decl_whitespace?(str.getbyte(pos)) || str.getbyte(pos) == BYTE_LBRACE)
+        fin -= 1 while fin > pos && (decl_whitespace?(str.getbyte(fin - 1)) || str.getbyte(fin - 1) == BYTE_RBRACE)
+
+        declarations = []
+
+        while pos < fin
+          pos += 1 while pos < fin && (decl_whitespace?(str.getbyte(pos)) || str.getbyte(pos) == BYTE_SEMICOLON)
+          break if pos >= fin
+
+          span = scan_one_declaration(str, pos, fin)
+          break unless span # No colon found - stop parsing entirely
+
+          pos = span[:next_pos]
+          next unless span[:val_end] > span[:val_start] # Skip if value is empty
+
+          property = str.byteslice(span[:prop_start], span[:prop_end] - span[:prop_start])
+                        .force_encoding(Encoding::US_ASCII).downcase
+          value = str.byteslice(span[:val_start], span[:val_end] - span[:val_start]).force_encoding(Encoding::UTF_8)
+
+          declarations << Declaration.new(property, value, span[:important])
+        end
+
+        declarations
+      end
+
+      # Scans one "prop: value" declaration starting at pos, stopping at fin
+      # (never reads past it). On success, returns a span hash and next_pos is
+      # the position just past the terminating ';' (or fin/'}' if there wasn't
+      # one). On failure - no ':' found - returns nil, leaving the caller to
+      # decide how to recover (this parser stops entirely).
+      #
+      # The value scan tracks paren depth, so a ';' inside url(...) or rgba(...)
+      # doesn't end the value early, and always stops at an unguarded '}'.
+      def scan_one_declaration(str, pos, fin)
+        prop_start = pos
+        pos += 1 while pos < fin && str.getbyte(pos) != BYTE_COLON
+        return nil if pos >= fin
+
+        prop_end = pos
+        prop_end -= 1 while prop_end > prop_start && decl_whitespace?(str.getbyte(prop_end - 1))
+        prop_start += 1 while prop_start < prop_end && decl_whitespace?(str.getbyte(prop_start))
+
+        pos += 1 # Skip ':'
+        pos += 1 while pos < fin && decl_whitespace?(str.getbyte(pos))
+
+        val_start = pos
+        paren_depth = 0
+        while pos < fin && str.getbyte(pos) != BYTE_RBRACE
+          byte = str.getbyte(pos)
+          if byte == BYTE_LPAREN
+            paren_depth += 1
+          elsif byte == BYTE_RPAREN
+            paren_depth -= 1
+          elsif byte == BYTE_SEMICOLON && paren_depth == 0
+            break
+          end
+          pos += 1
+        end
+        val_end = pos
+        val_end -= 1 while val_end > val_start && decl_whitespace?(str.getbyte(val_end - 1))
+
+        important, val_end = extract_important(str, val_start, val_end)
+        val_end -= 1 while val_end > val_start && decl_whitespace?(str.getbyte(val_end - 1))
+
+        pos += 1 if pos < fin && str.getbyte(pos) == BYTE_SEMICOLON
+
+        { prop_start: prop_start, prop_end: prop_end, val_start: val_start, val_end: val_end,
+          important: important, next_pos: pos }
+      end
+      private :scan_one_declaration
+
+      # Detects and strips a trailing '!important' marker from [val_start, val_end).
+      # Assumes trailing whitespace has already been trimmed once. Zero or more
+      # whitespace tokens are allowed between '!' and 'important' per the CSS2.1
+      # grammar. Returns [important?, new_val_end].
+      def extract_important(str, val_start, val_end)
+        check = val_end
+        return [false, val_end] if check - val_start < 10 # strlen("!important") == 10
+
+        check -= 1 while check > val_start && decl_whitespace?(str.getbyte(check - 1))
+        return [false, val_end] if check - val_start < 9 || str.byteslice(check - 9, 9) != 'important'
+
+        check -= 9
+        check -= 1 while check > val_start && decl_whitespace?(str.getbyte(check - 1))
+        return [false, val_end] if check <= val_start || str.getbyte(check - 1) != BYTE_BANG
+
+        [true, check - 1]
+      end
+      private :extract_important
+
+      def decl_whitespace?(byte)
+        byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
+      end
+      private :decl_whitespace?
+    end
+  end
+end