cataract 0.2.4 → 0.3.0

data/lib/cataract/pure/parser.rb

@@ -23,10 +23,6 @@ module Cataract
     # Maximum media queries (prevent symbol table exhaustion)
     MAX_MEDIA_QUERIES = 1000
 
-    # Maximum property name/value lengths
-    MAX_PROPERTY_NAME_LENGTH = 256
-    MAX_PROPERTY_VALUE_LENGTH = 32_768
-
     AT_RULE_TYPES = %w[supports layer container scope].freeze
 
     # Extract substring and force specified encoding
@@ -64,6 +60,9 @@ module Cataract
     end
 
     def initialize(css_string, parser_options: {}, parent_media_sym: nil, parent_media_query_id: nil, depth: 0)
+      # Type validation
+      raise TypeError, "css_string must be a String, got #{css_string.class}" unless css_string.is_a?(String)
+
       # Private: Internal parsing state
       @_css = css_string.dup.freeze
       @_pos = 0
@@ -77,7 +76,8 @@ module Cataract
         selector_lists: true,
         base_uri: nil,
         absolute_paths: false,
-        uri_resolver: nil
+        uri_resolver: nil,
+        raise_parse_errors: false
       }.merge(parser_options)
 
       # Private: Extract options to ivars to avoid repeated hash lookups in hot path
@@ -86,6 +86,34 @@ module Cataract
       @_absolute_paths = @_parser_options[:absolute_paths]
       @_uri_resolver = @_parser_options[:uri_resolver] || Cataract::DEFAULT_URI_RESOLVER
 
+      # Parse error handling options - extract to ivars for hot path performance
+      @_raise_parse_errors = @_parser_options[:raise_parse_errors]
+      if @_raise_parse_errors.is_a?(Hash)
+        # Granular control - default all to false (opt-in)
+        @_check_empty_values = @_raise_parse_errors[:empty_values] || false
+        @_check_malformed_declarations = @_raise_parse_errors[:malformed_declarations] || false
+        @_check_invalid_selectors = @_raise_parse_errors[:invalid_selectors] || false
+        @_check_invalid_selector_syntax = @_raise_parse_errors[:invalid_selector_syntax] || false
+        @_check_malformed_at_rules = @_raise_parse_errors[:malformed_at_rules] || false
+        @_check_unclosed_blocks = @_raise_parse_errors[:unclosed_blocks] || false
+      elsif @_raise_parse_errors == true
+        # Enable all error checks
+        @_check_empty_values = true
+        @_check_malformed_declarations = true
+        @_check_invalid_selectors = true
+        @_check_invalid_selector_syntax = true
+        @_check_malformed_at_rules = true
+        @_check_unclosed_blocks = true
+      else
+        # Disabled
+        @_check_empty_values = false
+        @_check_malformed_declarations = false
+        @_check_invalid_selectors = false
+        @_check_invalid_selector_syntax = false
+        @_check_malformed_at_rules = false
+        @_check_unclosed_blocks = false
+      end
+
       # Private: Internal counters
       @_media_query_id_counter = 0   # Next MediaQuery ID (0-indexed)
       @_next_selector_list_id = 0    # Counter for selector list IDs
@@ -139,10 +167,9 @@ module Cataract
         if has_nested_selectors?(decl_start, decl_end)
           # NESTED PATH: Parse mixed declarations + nested rules
           # Split comma-separated selectors and parse each one
-          selectors = selector.split(',')
+          selectors = split_and_validate_selectors(selector, decl_start)
 
           selectors.each do |individual_selector|
-            individual_selector.strip!
             next if individual_selector.empty?
 
             # Get rule ID for this selector
@@ -181,7 +208,7 @@ module Cataract
           declarations = parse_declarations
 
           # Split comma-separated selectors into individual rules
-          selectors = selector.split(',')
+          selectors = split_and_validate_selectors(selector, decl_start)
 
           # Determine if we should track this as a selector list
           # Check boolean first to potentially avoid size() call via short-circuit evaluation
@@ -193,7 +220,6 @@ module Cataract
           end
 
           selectors.each do |individual_selector|
-            individual_selector.strip!
             next if individual_selector.empty?
 
             rule_id = @_rule_id_counter
@@ -241,6 +267,30 @@ module Cataract
 
     private
 
+    # Split a comma-separated selector list into individual selector strings,
+    # stripping whitespace from each and validating (in strict mode) that
+    # none are empty. Empty entries are left in the returned array - callers
+    # skip them - since the emptiness check needs the original
+    # comma-separated count (selectors.size > 1) to know whether this is
+    # really a list or just a single selector, which callers no longer have
+    # once they've filtered.
+    #
+    # @param selector [String] Raw selector text (already trimmed as a whole)
+    # @param pos [Integer] Position to report in a raised ParseError
+    # @return [Array<String>] Individual selectors, stripped
+    def split_and_validate_selectors(selector, pos)
+      selectors = selector.split(',')
+      selectors.each do |individual_selector|
+        individual_selector.strip!
+
+        if @_check_invalid_selector_syntax && individual_selector.empty? && selectors.size > 1
+          raise ParseError.new('Invalid selector syntax: empty selector in comma-separated list',
+                               css: @_css, pos: pos, type: :invalid_selector_syntax)
+        end
+      end
+      selectors
+    end
+
     # Check if we're at end of input
     def eof?
       @_pos >= @_len
@@ -303,20 +353,119 @@ module Cataract
       end until @_pos == old_pos # No progress made # rubocop:disable Lint/Loop
     end
 
+    # Check if a selector contains only valid CSS selector characters and sequences
+    # Returns true if valid, false if invalid
+    # Valid characters: a-z A-Z 0-9 - _ . # [ ] : * > + ~ ( ) ' " = ^ $ | \ & % / whitespace
+    def valid_selector_syntax?(selector_text)
+      i = 0
+      len = selector_text.bytesize
+
+      while i < len
+        byte = selector_text.getbyte(i)
+
+        # Check for invalid character sequences
+        if i + 1 < len
+          next_byte = selector_text.getbyte(i + 1)
+          # Double dot (..) is invalid
+          return false if byte == BYTE_DOT && next_byte == BYTE_DOT
+          # Double hash (##) is invalid
+          return false if byte == BYTE_HASH && next_byte == BYTE_HASH
+        end
+
+        # Alphanumeric
+        if (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) || (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z) || (byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9)
+          i += 1
+          next
+        end
+
+        # Whitespace
+        if byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
+          i += 1
+          next
+        end
+
+        # Valid CSS selector special characters
+        case byte
+        when BYTE_HYPHEN, BYTE_UNDERSCORE, BYTE_DOT, BYTE_HASH, BYTE_LBRACKET, BYTE_RBRACKET,
+             BYTE_COLON, BYTE_ASTERISK, BYTE_GT, BYTE_PLUS, BYTE_TILDE, BYTE_LPAREN, BYTE_RPAREN,
+             BYTE_SQUOTE, BYTE_DQUOTE, BYTE_EQUALS, BYTE_CARET, BYTE_DOLLAR,
+             BYTE_PIPE, BYTE_BACKSLASH, BYTE_AMPERSAND, BYTE_PERCENT, BYTE_SLASH, BYTE_BANG,
+             BYTE_COMMA
+          i += 1
+        else
+          # Invalid character found
+          return false
+        end
+      end
+
+      true
+    end
+
+    # Detect and strip a trailing '!important' marker from an already-extracted,
+    # already-right-trimmed declaration value, in place. Shared by
+    # parse_single_declaration and parse_declarations so both code paths agree
+    # on what counts as important.
+    #
+    # The CSS2.1 grammar defines the IMPORTANT_SYM lexical token as:
+    #   "!"({w}|{comment})*{I}{M}{P}{O}{R}{T}{A}{N}{T}
+    # (https://www.w3.org/TR/CSS2/grammar.html) - i.e. zero or more whitespace
+    # tokens are allowed between '!' and 'important'.
+    #
+    # Mutates value in place (via slice!) instead of returning a new
+    # [value, important] tuple, so the common case (no !important present)
+    # allocates nothing beyond the two getbyte/compare checks below.
+    #
+    # @param value [String] already-extracted, right-trimmed declaration value (mutated in place)
+    # @return [Boolean] whether an important marker was found and stripped
+    def extract_important!(value) # rubocop:disable Naming/PredicateMethod
+      return false if value.bytesize < 10
+
+      i = value.bytesize - 1
+      # Skip trailing whitespace
+      while i >= 0 && whitespace?(value.getbyte(i))
+        i -= 1
+      end
+
+      # Check for 'important' (9 chars)
+      return false if i < 8 || value[(i - 8), 9] != 'important'
+
+      i -= 9
+      # Skip whitespace between '!' and 'important'
+      while i >= 0 && whitespace?(value.getbyte(i))
+        i -= 1
+      end
+
+      # Check for '!'
+      return false unless i >= 0 && value.getbyte(i) == BYTE_BANG
+
+      # Remove everything from '!' onwards, in place
+      value.slice!(i..-1)
+      value.strip!
+      true
+    end
+
     # Parse a single CSS declaration (property: value)
     #
     # Performance-critical helper that parses one declaration.
-    # Shared by parse_mixed_block, parse_declarations, and parse_declarations_block.
+    # Shared by parse_mixed_block and parse_declarations_block.
     #
     # @param pos [Integer] Current position in CSS string
     # @param end_pos [Integer] End position (boundary for parsing)
     # @param parse_important [Boolean] Whether to parse !important flag (false for at-rules)
     # @return [Array(Declaration|nil, Integer)] Tuple of [declaration, new_position]
     def parse_single_declaration(pos, end_pos, parse_important)
-      # Parse property name (scan until ':')
+      # Parse property name (scan until ':').
+      # Also stops at '{' - a property name can never legitimately contain
+      # one, so its presence means this is actually an unsupported/invalid
+      # nested selector (e.g. a bare type selector without '&') that wasn't
+      # recognized as nesting. Treating it as malformed here (instead of
+      # scanning through the '{' looking for a colon) keeps its matching '}'
+      # from being silently swallowed later, which was corrupting output
+      # with unbalanced braces.
       prop_start = pos
       while pos < end_pos && @_css.getbyte(pos) != BYTE_COLON &&
-            @_css.getbyte(pos) != BYTE_SEMICOLON && @_css.getbyte(pos) != BYTE_RBRACE
+            @_css.getbyte(pos) != BYTE_SEMICOLON && @_css.getbyte(pos) != BYTE_RBRACE &&
+            @_css.getbyte(pos) != BYTE_LBRACE
         pos += 1
       end
 
@@ -352,9 +501,20 @@ module Cataract
         pos += 1
       end
 
-      # Parse value (scan until ';' or '}')
+      # Parse value (scan until ';' outside parens, or '}'). Paren depth
+      # tracking keeps a ';' inside url(...)/rgba(...) from ending the value
+      # early - e.g. "url(data:image/svg+xml;base64,...)".
       val_start = pos
-      while pos < end_pos && @_css.getbyte(pos) != BYTE_SEMICOLON && @_css.getbyte(pos) != BYTE_RBRACE
+      paren_depth = 0
+      while pos < end_pos && @_css.getbyte(pos) != BYTE_RBRACE
+        byte = @_css.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
@@ -367,12 +527,7 @@ module Cataract
       value = byteslice_encoded(val_start, val_end - val_start)
 
       # Parse !important flag if requested
-      important = false
-      if parse_important && value.end_with?('!important')
-        important = true
-        # Remove '!important' and trailing whitespace
-        value = value[0, value.length - 10].rstrip
-      end
+      important = parse_important && extract_important!(value)
 
       # Skip semicolon if present
       pos += 1 if pos < end_pos && @_css.getbyte(pos) == BYTE_SEMICOLON
@@ -410,20 +565,35 @@ module Cataract
         pos += 1
       end
 
+      # Reached EOF without finding matching closing brace
+      if @_check_unclosed_blocks && depth > 0
+        raise ParseError.new('Unclosed block: missing closing brace',
+                             css: @_css, pos: start_pos - 1, type: :unclosed_block)
+      end
+
       pos
     end
 
     # Parse selector (read until '{')
-    def parse_selector
-      start_pos = @_pos
-
-      # Read until we find '{'
+    # Advance @_pos to the next unescaped '{', or through to EOF if none is
+    # found. Doesn't consume the brace itself. Shared by parse_selector and
+    # scan_at_rule_selector, which both need this same scan but differ in
+    # what they do with the boundary afterward (validation, trimming, what
+    # to return on EOF).
+    #
+    # @return [Boolean] true if '{' was found, false if EOF was hit first
+    def skip_to_opening_brace # rubocop:disable Naming/PredicateMethod
       until eof? || peek_byte == BYTE_LBRACE # Flip to save a 'opt_not' instruction: while !eof? && peek_byte != BYTE_LBRACE
         @_pos += 1
       end
+      !eof?
+    end
+
+    def parse_selector
+      start_pos = @_pos
 
       # If we hit EOF without finding '{', return nil
-      return nil if eof?
+      return nil unless skip_to_opening_brace
 
       # Extract selector text
       selector_text = byteslice_encoded(start_pos, @_pos - start_pos)
@@ -433,6 +603,29 @@ module Cataract
 
       # Trim whitespace from selector (in-place to avoid allocation)
       selector_text.strip!
+
+      # Validate selector (strict mode) - only if enabled to avoid overhead
+      if @_check_invalid_selectors
+        # Check for empty selector
+        if selector_text.empty?
+          raise ParseError.new('Invalid selector: empty selector',
+                               css: @_css, pos: start_pos, type: :invalid_selector)
+        end
+
+        # Check if selector starts with a combinator (>, +, ~)
+        first_char = selector_text.getbyte(0)
+        if first_char == BYTE_GT || first_char == BYTE_PLUS || first_char == BYTE_TILDE
+          raise ParseError.new("Invalid selector: selector cannot start with combinator '#{selector_text[0]}'",
+                               css: @_css, pos: start_pos, type: :invalid_selector)
+        end
+      end
+
+      # Check selector syntax (whitelist validation for invalid characters/sequences)
+      if @_check_invalid_selector_syntax && !valid_selector_syntax?(selector_text)
+        raise ParseError.new('Invalid selector syntax: selector contains invalid characters',
+                             css: @_css, pos: start_pos, type: :invalid_selector_syntax)
+      end
+
       selector_text
     end
 
@@ -514,7 +707,7 @@ module Cataract
 
                                     # This should never happen - parent_media_query_id should always be valid
                                     if parent_mq.nil?
-                                      raise ParserError, "Invalid parent_media_query_id: #{parent_media_query_id} (not found in @media_queries)"
+                                      raise ParseError, "Invalid parent_media_query_id: #{parent_media_query_id} (not found in @media_queries)"
                                     end
 
                                     # Combine parent media query with child
@@ -664,17 +857,35 @@ module Cataract
           break
         end
 
-        # Parse property name (read until ':')
+        # Parse property name (read until ':'). Also stops at '{' - a property
+        # name can never legitimately contain one, so its presence means this
+        # is actually an unsupported/invalid nested selector (e.g. a bare type
+        # selector without '&') that wasn't recognized as nesting. Treating it
+        # as malformed here (instead of scanning through the '{' looking for a
+        # colon) keeps its matching '}' from being silently swallowed later,
+        # which was corrupting output with unbalanced braces.
         property_start = @_pos
         until eof?
           byte = peek_byte
-          break if byte == BYTE_COLON || byte == BYTE_SEMICOLON || byte == BYTE_RBRACE
+          break if byte == BYTE_COLON || byte == BYTE_SEMICOLON || byte == BYTE_RBRACE || byte == BYTE_LBRACE
 
           @_pos += 1
         end
 
         # Skip if no colon found (malformed)
         if eof? || peek_byte != BYTE_COLON
+          # Check for malformed declaration (strict mode)
+          if @_check_malformed_declarations
+            property_text = byteslice_encoded(property_start, @_pos - property_start).strip
+            if property_text.empty?
+              raise ParseError.new('Malformed declaration: missing property name',
+                                   css: @_css, pos: property_start, type: :malformed_declaration)
+            else
+              raise ParseError.new("Malformed declaration: missing colon after property '#{property_text}'",
+                                   css: @_css, pos: property_start, type: :malformed_declaration)
+            end
+          end
+
           # Try to recover by finding next ; or }
           skip_to_semicolon_or_brace
           next
@@ -694,10 +905,13 @@ module Cataract
 
         skip_ws_and_comments
 
-        # Parse value (read until ';' or '}', but respect quoted strings)
+        # Parse value (read until ';' outside parens, or '}', but respect
+        # quoted strings). Paren depth tracking keeps a ';' inside
+        # url(...)/rgba(...) from ending the value early - e.g.
+        # "url(data:image/svg+xml;base64,...)".
         value_start = @_pos
-        important = false
         in_quote = nil # nil, BYTE_SQUOTE, or BYTE_DQUOTE
+        paren_depth = 0
 
         until eof?
           byte = peek_byte
@@ -711,11 +925,17 @@ module Cataract
               @_pos += 1
             end
           else
-            # Not in quote - check for terminators or quote start
-            break if byte == BYTE_SEMICOLON || byte == BYTE_RBRACE
+            # Not in quote - check for terminators or quote/paren start
+            break if byte == BYTE_RBRACE || (byte == BYTE_SEMICOLON && paren_depth == 0)
 
-            if byte == BYTE_SQUOTE || byte == BYTE_DQUOTE
+            # case/when compiles to opt_send(===) here, not opt_eq - benchmarked
+            # ~1.7x slower without YJIT, still slower with it.
+            if byte == BYTE_SQUOTE || byte == BYTE_DQUOTE # rubocop:disable Style/CaseLikeIf
               in_quote = byte
+            elsif byte == BYTE_LPAREN
+              paren_depth += 1
+            elsif byte == BYTE_RPAREN
+              paren_depth -= 1
             end
           end
 
@@ -726,35 +946,12 @@ module Cataract
         value.strip!
 
         # Check for !important (byte-by-byte, no regexp)
-        if value.bytesize > 10
-          # Scan backwards to find !important
-          i = value.bytesize - 1
-          # Skip trailing whitespace
-          while i >= 0
-            b = value.getbyte(i)
-            break unless b == BYTE_SPACE || b == BYTE_TAB
-
-            i -= 1
-          end
-
-          # Check for 'important' (9 chars)
-          if i >= 8 && value[(i - 8), 9] == 'important'
-            i -= 9
-            # Skip whitespace before 'important'
-            while i >= 0
-              b = value.getbyte(i)
-              break unless b == BYTE_SPACE || b == BYTE_TAB
+        important = extract_important!(value)
 
-              i -= 1
-            end
-            # Check for '!'
-            if i >= 0 && value.getbyte(i) == BYTE_BANG
-              important = true
-              # Remove everything from '!' onwards (use byteslice and strip in-place)
-              value = value.byteslice(0, i)
-              value.strip!
-            end
-          end
+        # Check for empty value (strict mode) - only if enabled to avoid overhead
+        if @_check_empty_values && value.empty?
+          raise ParseError.new("Empty value for property '#{property}'",
+                               css: @_css, pos: property_start, type: :empty_value)
         end
 
         # Skip semicolon if present
@@ -770,6 +967,82 @@ module Cataract
       declarations
     end
 
+    # Scan from at_rule_start (pointing at the '@') to the at-rule's opening
+    # brace, returning the trimmed selector text (e.g. "@keyframes fade").
+    # Leaves @_pos just past the opening brace. Shared by at-rule kinds whose
+    # selector is just "everything up to '{'" with no separate condition/query
+    # text to extract along the way (@keyframes, @font-face, and the unknown/
+    # default at-rule fallback).
+    #
+    # @param at_rule_start [Integer] Position of the at-rule's leading '@'
+    # @return [String, nil] The trimmed selector, or nil if '{' was never found
+    def scan_at_rule_selector(at_rule_start)
+      return nil unless skip_to_opening_brace
+
+      selector_end = @_pos
+      while selector_end > at_rule_start && whitespace?(@_css.getbyte(selector_end - 1))
+        selector_end -= 1
+      end
+      selector = byteslice_encoded(at_rule_start, selector_end - at_rule_start)
+
+      @_pos += 1 # skip '{'
+      selector
+    end
+
+    # Merge selector_lists from a nested Parser's result into this parser,
+    # offsetting list ids and rule ids to avoid collisions. Shared by the
+    # conditional-group (@supports/@layer/@container/@scope) and @media
+    # at-rule handlers, which both recurse into a fresh Parser instance for
+    # their block content.
+    #
+    # @param nested_result [Hash] Result hash from a nested Parser#parse call
+    # @return [Integer] The list_id_offset used - pass through to
+    #   merge_nested_rules so each rule's selector_list_id stays consistent
+    def merge_nested_selector_lists(nested_result)
+      list_id_offset = @_next_selector_list_id
+      if nested_result[:_selector_lists] && !nested_result[:_selector_lists].empty?
+        nested_result[:_selector_lists].each do |list_id, rule_ids|
+          new_list_id = list_id + list_id_offset
+          offsetted_rule_ids = rule_ids.map { |rid| rid + @_rule_id_counter }
+          @_selector_lists[new_list_id] = offsetted_rule_ids
+        end
+        @_next_selector_list_id = list_id_offset + nested_result[:_selector_lists].size
+      end
+      list_id_offset
+    end
+
+    # Merge rules from a nested Parser's result into this parser's @rules,
+    # renumbering ids and offsetting selector_list_id, then propagate whether
+    # nesting was found inside the block up to this parser - the nested
+    # parser tracked its own independent @_has_nesting, so without this a
+    # rule nested inside a top-level at-rule block would carry a correct
+    # parent_rule_id but the stylesheet would still report has_nesting:
+    # false, causing serialization to use the flat, non-nesting-aware path
+    # and print the rule's already-resolved selector as an unrelated
+    # top-level rule instead of reconstructing the nested syntax.
+    #
+    # Yields each rule (after id/selector_list_id are updated, before it's
+    # appended to @rules) for callers needing extra per-rule handling - e.g.
+    # @media combining media_query_id with its outer media context.
+    #
+    # @param nested_result [Hash] Result hash from a nested Parser#parse call
+    # @param list_id_offset [Integer] Offset from merge_nested_selector_lists
+    def merge_nested_rules(nested_result, list_id_offset)
+      nested_result[:rules].each do |rule|
+        rule.id = @_rule_id_counter
+        if rule.is_a?(Rule) && rule.selector_list_id
+          rule.selector_list_id += list_id_offset
+        end
+
+        yield rule if block_given?
+
+        @_rule_id_counter += 1
+        @rules << rule
+      end
+
+      @_has_nesting ||= nested_result[:_has_nesting] # rubocop:disable Naming/MemoizedInstanceVariableName -- not memoization, propagating a flag from the nested parse
+    end
+
     # Parse at-rule (@media, @supports, @charset, @keyframes, @font-face, etc)
     # Translated from C: see ext/cataract/css_parser.c lines 962-1128
     def parse_at_rule
@@ -788,401 +1061,363 @@ module Cataract
       at_rule_name = byteslice_encoded(name_start, @_pos - name_start)
 
       # Handle @charset specially - it's just @charset "value";
-      if at_rule_name == 'charset'
-        skip_ws_and_comments
-        # Read until semicolon
-        value_start = @_pos
-        while !eof? && peek_byte != BYTE_SEMICOLON
-          @_pos += 1
-        end
-
-        charset_value = byteslice_encoded(value_start, @_pos - value_start)
-        charset_value.strip!
-        # Remove quotes
-        @charset = charset_value.delete('"\'')
-
-        @_pos += 1 if peek_byte == BYTE_SEMICOLON # consume semicolon
-        return
-      end
+      return parse_charset_at_rule if at_rule_name == 'charset'
 
       # Handle @import - must come before rules (except @charset)
-      if at_rule_name == 'import'
-        # If we've already seen a rule, this @import is invalid
-        if @rules.size > 0
-          warn 'CSS @import ignored: @import must appear before all rules (found import after rules)'
-          # Skip to semicolon
-          while !eof? && peek_byte != BYTE_SEMICOLON
-            @_pos += 1
-          end
-          @_pos += 1 if peek_byte == BYTE_SEMICOLON
-          return
-        end
-
-        parse_import_statement
-        return
-      end
+      return parse_import_at_rule if at_rule_name == 'import'
 
       # Handle conditional group at-rules: @supports, @layer, @container, @scope
       # These behave like @media but don't affect media context
-      if AT_RULE_TYPES.include?(at_rule_name)
-        skip_ws_and_comments
+      return parse_conditional_group_at_rule(at_rule_name) if AT_RULE_TYPES.include?(at_rule_name)
 
-        # Skip to opening brace
-        while !eof? && peek_byte != BYTE_LBRACE
-          @_pos += 1
-        end
+      # Handle @media specially - parse content and track in media_index
+      return parse_media_at_rule if at_rule_name == 'media'
 
-        return if eof? || peek_byte != BYTE_LBRACE
+      # Check for @keyframes (contains <rule-list>)
+      is_keyframes = at_rule_name == 'keyframes' ||
+                     at_rule_name == '-webkit-keyframes' ||
+                     at_rule_name == '-moz-keyframes'
+      return parse_keyframes_at_rule(at_rule_start) if is_keyframes
 
-        @_pos += 1 # skip '{'
+      # Check for @font-face (contains <declaration-list>)
+      return parse_font_face_at_rule(at_rule_start) if at_rule_name == 'font-face'
 
-        # Find matching closing brace
-        block_start = @_pos
-        block_end = find_matching_brace(@_pos)
+      # Unknown at-rule (@property, @page, @counter-style, etc.)
+      # Treat as a regular selector-based rule with declarations
+      parse_unknown_at_rule(at_rule_start)
+    end
 
-        # Check depth before recursing
-        if @_depth + 1 > MAX_PARSE_DEPTH
-          raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
-        end
+    # @charset "value"; - stores the value and consumes through the semicolon.
+    def parse_charset_at_rule
+      skip_ws_and_comments
+      # Read until semicolon
+      value_start = @_pos
+      while !eof? && peek_byte != BYTE_SEMICOLON
+        @_pos += 1
+      end
 
-        # Recursively parse block content (preserve parent media context)
-        nested_parser = Parser.new(
-          byteslice_encoded(block_start, block_end - block_start),
-          parser_options: @_parser_options,
-          parent_media_sym: @_parent_media_sym,
-          depth: @_depth + 1
-        )
-
-        nested_result = nested_parser.parse
-
-        # Merge nested selector_lists with offsetted IDs
-        list_id_offset = @_next_selector_list_id
-        if nested_result[:_selector_lists] && !nested_result[:_selector_lists].empty?
-          nested_result[:_selector_lists].each do |list_id, rule_ids|
-            new_list_id = list_id + list_id_offset
-            offsetted_rule_ids = rule_ids.map { |rid| rid + @_rule_id_counter }
-            @_selector_lists[new_list_id] = offsetted_rule_ids
-          end
-          @_next_selector_list_id = list_id_offset + nested_result[:_selector_lists].size
-        end
+      charset_value = byteslice_encoded(value_start, @_pos - value_start)
+      charset_value.strip!
+      # Remove quotes
+      @charset = charset_value.delete('"\'')
 
-        # NOTE: We no longer build media_index during parse
-        # It will be built from MediaQuery objects after import resolution
+      @_pos += 1 if peek_byte == BYTE_SEMICOLON # consume semicolon
+    end
 
-        # Add nested rules to main rules array
-        nested_result[:rules].each do |rule|
-          rule.id = @_rule_id_counter
-          # Update selector_list_id if applicable
-          if rule.is_a?(Rule) && rule.selector_list_id
-            rule.selector_list_id += list_id_offset
-          end
-          @_rule_id_counter += 1
-          @rules << rule
+    # @import must appear before all rules (except @charset) per CSS spec -
+    # anything else is invalid and gets skipped with a warning instead of
+    # being parsed as an import.
+    def parse_import_at_rule
+      # If we've already seen a rule, this @import is invalid
+      if @rules.size > 0
+        warn 'CSS @import ignored: @import must appear before all rules (found import after rules)'
+        # Skip to semicolon
+        while !eof? && peek_byte != BYTE_SEMICOLON
+          @_pos += 1
         end
-
-        # Move position past the closing brace
-        @_pos = block_end
-        @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
-
+        @_pos += 1 if peek_byte == BYTE_SEMICOLON
         return
       end
 
-      # Handle @media specially - parse content and track in media_index
-      if at_rule_name == 'media'
-        skip_ws_and_comments
+      parse_import_statement
+    end
 
-        # Find media query (up to opening brace)
-        mq_start = @_pos
-        while !eof? && peek_byte != BYTE_LBRACE
-          @_pos += 1
-        end
+    # @supports, @layer, @container, @scope - behave like @media but don't
+    # affect media context, so unlike parse_media_at_rule there's no media
+    # query/media_query_id merging to do on top of the shared nested-parser
+    # result merge.
+    #
+    # @param at_rule_name [String] The at-rule name (e.g. "supports"), used
+    #   to decide whether a condition is required and for error messages
+    def parse_conditional_group_at_rule(at_rule_name)
+      skip_ws_and_comments
 
-        return if eof? || peek_byte != BYTE_LBRACE
+      # Remember start of condition for error reporting
+      condition_start = @_pos
 
-        mq_end = @_pos
-        # Trim trailing whitespace
-        while mq_end > mq_start && whitespace?(@_css.getbyte(mq_end - 1))
-          mq_end -= 1
-        end
+      # Skip to opening brace
+      condition_end = @_pos
+      while !eof? && peek_byte != BYTE_LBRACE
+        condition_end = @_pos
+        @_pos += 1
+      end
 
-        child_media_string = byteslice_encoded(mq_start, mq_end - mq_start)
-        # Keep media query exactly as written - parentheses are required per CSS spec
-        child_media_string.strip!
-        child_media_sym = child_media_string.to_sym
-
-        # Split comma-separated media queries (e.g., "screen, print" -> ["screen", "print"])
-        # Per W3C spec, comma acts as logical OR - each query is independent
-        media_query_strings = child_media_string.split(',').map(&:strip)
-
-        # Create MediaQuery objects for each query in the list
-        media_query_ids = []
-        media_query_strings.each do |query_string|
-          media_type, media_conditions = parse_media_query_parts(query_string)
-          media_query = Cataract::MediaQuery.new(@_media_query_id_counter, media_type, media_conditions)
-          @media_queries << media_query
-          media_query_ids << @_media_query_id_counter
-          @_media_query_id_counter += 1
-        end
+      return if eof? || peek_byte != BYTE_LBRACE
 
-        # If multiple queries, track them as a list for serialization
-        if media_query_ids.size > 1
-          @_media_query_lists[@_next_media_query_list_id] = media_query_ids
-          @_next_media_query_list_id += 1
+      # Validate condition (strict mode) - @supports, @container, @scope require conditions
+      if @_check_malformed_at_rules && (at_rule_name == 'supports' || at_rule_name == 'container' || at_rule_name == 'scope')
+        condition_str = byteslice_encoded(condition_start, condition_end - condition_start).strip
+        if condition_str.empty?
+          raise ParseError.new("Malformed @#{at_rule_name}: missing condition",
+                               css: @_css, pos: condition_start, type: :malformed_at_rule)
         end
+      end
 
-        # Use first query ID as the primary one for rules in this block
-        current_media_query_id = media_query_ids.first
-
-        # Combine with parent media context
-        combined_media_sym = combine_media_queries(@_parent_media_sym, child_media_sym)
+      @_pos += 1 # skip '{'
 
-        # NOTE: @_parent_media_query_id is always nil here because top-level @media blocks
-        # create separate parsers without passing parent_media_query_id (see nested_parser creation below).
-        # MediaQuery combining for nested @media happens in parse_mixed_block instead.
-        # So this is just an alias to current_media_query_id.
-        combined_media_query_id = current_media_query_id
+      # Find matching closing brace
+      block_start = @_pos
+      block_end = find_matching_brace(@_pos)
 
-        # Check media query limit
-        unless @media_index.key?(combined_media_sym)
-          @_media_query_count += 1
-          if @_media_query_count > MAX_MEDIA_QUERIES
-            raise SizeError, "Too many media queries: exceeded maximum of #{MAX_MEDIA_QUERIES}"
-          end
-        end
+      # Check depth before recursing
+      if @_depth + 1 > MAX_PARSE_DEPTH
+        raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
+      end
 
-        @_pos += 1 # skip '{'
+      # Recursively parse block content (preserve parent media context)
+      nested_parser = Parser.new(
+        byteslice_encoded(block_start, block_end - block_start),
+        parser_options: @_parser_options,
+        parent_media_sym: @_parent_media_sym,
+        depth: @_depth + 1
+      )
 
-        # Find matching closing brace
-        block_start = @_pos
-        block_end = find_matching_brace(@_pos)
+      nested_result = nested_parser.parse
 
-        # Check depth before recursing
-        if @_depth + 1 > MAX_PARSE_DEPTH
-          raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
-        end
-
-        # Parse the content with the combined media context
-        # Note: We don't pass parent_media_query_id because MediaQuery IDs are local to each parser
-        # The nested parser will create its own MediaQueries, which we'll merge with offsetted IDs
-        nested_parser = Parser.new(
-          byteslice_encoded(block_start, block_end - block_start),
-          parser_options: @_parser_options,
-          parent_media_sym: combined_media_sym,
-          depth: @_depth + 1
-        )
-
-        nested_result = nested_parser.parse
-
-        # Merge nested selector_lists with offsetted IDs
-        list_id_offset = @_next_selector_list_id
-        if nested_result[:_selector_lists] && !nested_result[:_selector_lists].empty?
-          nested_result[:_selector_lists].each do |list_id, rule_ids|
-            new_list_id = list_id + list_id_offset
-            offsetted_rule_ids = rule_ids.map { |rid| rid + @_rule_id_counter }
-            @_selector_lists[new_list_id] = offsetted_rule_ids
-          end
-          @_next_selector_list_id = list_id_offset + nested_result[:_selector_lists].size
-        end
+      # NOTE: We no longer build media_index during parse
+      # It will be built from MediaQuery objects after import resolution
+      list_id_offset = merge_nested_selector_lists(nested_result)
+      merge_nested_rules(nested_result, list_id_offset)
 
-        # Merge nested MediaQuery objects with offsetted IDs
-        mq_id_offset = @_media_query_id_counter
-        if nested_result[:media_queries] && !nested_result[:media_queries].empty?
-          nested_result[:media_queries].each do |mq|
-            # Create new MediaQuery with offsetted ID
-            new_mq = Cataract::MediaQuery.new(mq.id + mq_id_offset, mq.type, mq.conditions)
-            @media_queries << new_mq
-          end
-          @_media_query_id_counter += nested_result[:media_queries].size
-        end
+      # Move position past the closing brace
+      @_pos = block_end
+      @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
+    end
 
-        # Merge nested media_query_lists with offsetted IDs
-        if nested_result[:_media_query_lists] && !nested_result[:_media_query_lists].empty?
-          nested_result[:_media_query_lists].each do |list_id, mq_ids|
-            # Offset the list_id and media_query_ids
-            new_list_id = list_id + @_next_media_query_list_id
-            offsetted_mq_ids = mq_ids.map { |mq_id| mq_id + mq_id_offset }
-            @_media_query_lists[new_list_id] = offsetted_mq_ids
-          end
-          @_next_media_query_list_id += nested_result[:_media_query_lists].size
-        end
+    # @media - parses the media query, recurses into a nested Parser for the
+    # block content (combining its media context with any parent), and
+    # merges the result. Unlike parse_conditional_group_at_rule, this also
+    # merges MediaQuery objects/lists and combines each nested rule's
+    # media_query_id with this block's own media context.
+    def parse_media_at_rule
+      skip_ws_and_comments
 
-        # Merge nested media_index into ours (for nested @media)
-        # Note: We no longer build media_index during parse
-        # It will be built from MediaQuery objects after import resolution
+      # Find media query (up to opening brace)
+      mq_start = @_pos
+      return unless skip_to_opening_brace
 
-        # Add nested rules to main rules array
-        nested_result[:rules].each do |rule|
-          rule.id = @_rule_id_counter
-          # Update selector_list_id if applicable
-          if rule.is_a?(Rule) && rule.selector_list_id
-            rule.selector_list_id += list_id_offset
-          end
+      mq_end = @_pos
+      # Trim trailing whitespace
+      while mq_end > mq_start && whitespace?(@_css.getbyte(mq_end - 1))
+        mq_end -= 1
+      end
 
-          # Update media_query_id if applicable (both Rule and AtRule can have media_query_id)
-          if rule.media_query_id
-            # Nested parser assigned a media_query_id - need to combine with our context
-            nested_mq_id = rule.media_query_id + mq_id_offset
-            nested_mq = @media_queries[nested_mq_id]
-
-            # Combine nested media query with our media context
-            if nested_mq && combined_media_query_id
-              outer_mq = @media_queries[combined_media_query_id]
-              if outer_mq
-                # Combine media queries directly without string building
-                combined_type, combined_conditions = combine_media_query_parts(outer_mq, nested_mq.conditions)
-                combined_mq = Cataract::MediaQuery.new(@_media_query_id_counter, combined_type, combined_conditions)
-                @media_queries << combined_mq
-                rule.media_query_id = @_media_query_id_counter
-                @_media_query_id_counter += 1
-              else
-                rule.media_query_id = nested_mq_id
-              end
-            else
-              rule.media_query_id = nested_mq_id
-            end
-          elsif rule.respond_to?(:media_query_id=)
-            # Assign the combined media_query_id if no media_query_id set
-            # (applies to both Rule and AtRule)
-            rule.media_query_id = combined_media_query_id
-          end
+      child_media_string = byteslice_encoded(mq_start, mq_end - mq_start)
+      # Keep media query exactly as written - parentheses are required per CSS spec
+      child_media_string.strip!
 
-          # NOTE: We no longer build media_index during parse
-          # It will be built from MediaQuery objects after import resolution
+      # Validate @media has a query (strict mode)
+      if @_check_malformed_at_rules && child_media_string.empty?
+        raise ParseError.new('Malformed @media: missing media query or condition',
+                             css: @_css, pos: mq_start, type: :malformed_at_rule)
+      end
 
-          @_rule_id_counter += 1
-          @rules << rule
-        end
+      child_media_sym = child_media_string.to_sym
 
-        # Move position past the closing brace
-        @_pos = block_end
-        @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
+      # Split comma-separated media queries (e.g., "screen, print" -> ["screen", "print"])
+      # Per W3C spec, comma acts as logical OR - each query is independent
+      media_query_strings = child_media_string.split(',').map(&:strip)
 
-        return
+      # Create MediaQuery objects for each query in the list
+      media_query_ids = []
+      media_query_strings.each do |query_string|
+        media_type, media_conditions = parse_media_query_parts(query_string)
+        media_query = Cataract::MediaQuery.new(@_media_query_id_counter, media_type, media_conditions)
+        @media_queries << media_query
+        media_query_ids << @_media_query_id_counter
+        @_media_query_id_counter += 1
       end
 
-      # Check for @keyframes (contains <rule-list>)
-      is_keyframes = at_rule_name == 'keyframes' ||
-                     at_rule_name == '-webkit-keyframes' ||
-                     at_rule_name == '-moz-keyframes'
+      # If multiple queries, track them as a list for serialization
+      if media_query_ids.size > 1
+        @_media_query_lists[@_next_media_query_list_id] = media_query_ids
+        @_next_media_query_list_id += 1
+      end
 
-      if is_keyframes
-        # Build full selector string: "@keyframes fade"
-        selector_start = at_rule_start # Points to '@'
+      # Use first query ID as the primary one for rules in this block
+      current_media_query_id = media_query_ids.first
 
-        # Skip to opening brace
-        while !eof? && peek_byte != BYTE_LBRACE
-          @_pos += 1
-        end
+      # Combine with parent media context
+      combined_media_sym = combine_media_queries(@_parent_media_sym, child_media_sym)
 
-        return if eof? || peek_byte != BYTE_LBRACE
+      # NOTE: @_parent_media_query_id is always nil here because top-level @media blocks
+      # create separate parsers without passing parent_media_query_id (see nested_parser creation below).
+      # MediaQuery combining for nested @media happens in parse_mixed_block instead.
+      # So this is just an alias to current_media_query_id.
+      combined_media_query_id = current_media_query_id
 
-        selector_end = @_pos
-        # Trim trailing whitespace
-        while selector_end > selector_start && whitespace?(@_css.getbyte(selector_end - 1))
-          selector_end -= 1
+      # Check media query limit
+      unless @media_index.key?(combined_media_sym)
+        @_media_query_count += 1
+        if @_media_query_count > MAX_MEDIA_QUERIES
+          raise SizeError, "Too many media queries: exceeded maximum of #{MAX_MEDIA_QUERIES}"
         end
-        selector = byteslice_encoded(selector_start, selector_end - selector_start)
-
-        @_pos += 1 # skip '{'
+      end
 
-        # Find matching closing brace
-        block_start = @_pos
-        block_end = find_matching_brace(@_pos)
+      @_pos += 1 # skip '{'
 
-        # Check depth before recursing
-        if @_depth + 1 > MAX_PARSE_DEPTH
-          raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
-        end
+      # Find matching closing brace
+      block_start = @_pos
+      block_end = find_matching_brace(@_pos)
 
-        # Parse keyframe blocks as rules (0%/from/to etc)
-        # Create a nested parser context
-        nested_parser = Parser.new(
-          byteslice_encoded(block_start, block_end - block_start),
-          parser_options: @_parser_options,
-          depth: @_depth + 1
-        )
-        nested_result = nested_parser.parse
-        content = nested_result[:rules]
-
-        # Move position past the closing brace
-        @_pos = block_end
-        # The closing brace should be at block_end
-        @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
-
-        # Get rule ID and increment
-        rule_id = @_rule_id_counter
-        @_rule_id_counter += 1
+      # Check depth before recursing
+      if @_depth + 1 > MAX_PARSE_DEPTH
+        raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
+      end
 
-        # Create AtRule with nested rules
-        at_rule = AtRule.new(rule_id, selector, content, nil, @_parent_media_query_id)
-        @rules << at_rule
+      # Parse the content with the combined media context
+      # Note: We don't pass parent_media_query_id because MediaQuery IDs are local to each parser
+      # The nested parser will create its own MediaQueries, which we'll merge with offsetted IDs
+      nested_parser = Parser.new(
+        byteslice_encoded(block_start, block_end - block_start),
+        parser_options: @_parser_options,
+        parent_media_sym: combined_media_sym,
+        depth: @_depth + 1
+      )
 
-        return
-      end
+      nested_result = nested_parser.parse
 
-      # Check for @font-face (contains <declaration-list>)
-      if at_rule_name == 'font-face'
-        # Build selector string: "@font-face"
-        selector_start = at_rule_start # Points to '@'
+      list_id_offset = merge_nested_selector_lists(nested_result)
 
-        # Skip to opening brace
-        while !eof? && peek_byte != BYTE_LBRACE
-          @_pos += 1
+      # Merge nested MediaQuery objects with offsetted IDs
+      mq_id_offset = @_media_query_id_counter
+      if nested_result[:media_queries] && !nested_result[:media_queries].empty?
+        nested_result[:media_queries].each do |mq|
+          # Create new MediaQuery with offsetted ID
+          new_mq = Cataract::MediaQuery.new(mq.id + mq_id_offset, mq.type, mq.conditions)
+          @media_queries << new_mq
         end
+        @_media_query_id_counter += nested_result[:media_queries].size
+      end
 
-        return if eof? || peek_byte != BYTE_LBRACE
+      # Merge nested media_query_lists with offsetted IDs
+      if nested_result[:_media_query_lists] && !nested_result[:_media_query_lists].empty?
+        nested_result[:_media_query_lists].each do |list_id, mq_ids|
+          # Offset the list_id and media_query_ids
+          new_list_id = list_id + @_next_media_query_list_id
+          offsetted_mq_ids = mq_ids.map { |mq_id| mq_id + mq_id_offset }
+          @_media_query_lists[new_list_id] = offsetted_mq_ids
+        end
+        @_next_media_query_list_id += nested_result[:_media_query_lists].size
+      end
 
-        selector_end = @_pos
-        # Trim trailing whitespace
-        while selector_end > selector_start && whitespace?(@_css.getbyte(selector_end - 1))
-          selector_end -= 1
+      # Merge nested media_index into ours (for nested @media)
+      # Note: We no longer build media_index during parse
+      # It will be built from MediaQuery objects after import resolution
+
+      merge_nested_rules(nested_result, list_id_offset) do |rule|
+        # Update media_query_id if applicable (both Rule and AtRule can have media_query_id)
+        if rule.media_query_id
+          # Nested parser assigned a media_query_id - need to combine with our context
+          nested_mq_id = rule.media_query_id + mq_id_offset
+          nested_mq = @media_queries[nested_mq_id]
+
+          # Combine nested media query with our media context
+          if nested_mq && combined_media_query_id
+            outer_mq = @media_queries[combined_media_query_id]
+            if outer_mq
+              # Combine media queries directly without string building
+              combined_type, combined_conditions = combine_media_query_parts(outer_mq, nested_mq.conditions)
+              combined_mq = Cataract::MediaQuery.new(@_media_query_id_counter, combined_type, combined_conditions)
+              @media_queries << combined_mq
+              rule.media_query_id = @_media_query_id_counter
+              @_media_query_id_counter += 1
+            else
+              rule.media_query_id = nested_mq_id
+            end
+          else
+            rule.media_query_id = nested_mq_id
+          end
+        elsif rule.respond_to?(:media_query_id=)
+          # Assign the combined media_query_id if no media_query_id set
+          # (applies to both Rule and AtRule)
+          rule.media_query_id = combined_media_query_id
         end
-        selector = byteslice_encoded(selector_start, selector_end - selector_start)
+      end
 
-        @_pos += 1 # skip '{'
+      # Move position past the closing brace
+      @_pos = block_end
+      @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
+    end
 
-        # Find matching closing brace
-        decl_start = @_pos
-        decl_end = find_matching_brace(@_pos)
+    # @keyframes (contains a <rule-list> of percentage/from/to blocks)
+    #
+    # @param at_rule_start [Integer] Position of the at-rule's leading '@'
+    def parse_keyframes_at_rule(at_rule_start)
+      # Build full selector string: "@keyframes fade"
+      selector = scan_at_rule_selector(at_rule_start)
+      return if selector.nil?
+
+      # Find matching closing brace
+      block_start = @_pos
+      block_end = find_matching_brace(@_pos)
+
+      # Check depth before recursing
+      if @_depth + 1 > MAX_PARSE_DEPTH
+        raise DepthError, "CSS nesting too deep: exceeded maximum depth of #{MAX_PARSE_DEPTH}"
+      end
 
-        # Parse declarations
-        content = parse_declarations_block(decl_start, decl_end)
+      # Parse keyframe blocks as rules (0%/from/to etc)
+      # Create a nested parser context
+      nested_parser = Parser.new(
+        byteslice_encoded(block_start, block_end - block_start),
+        parser_options: @_parser_options,
+        depth: @_depth + 1
+      )
+      nested_result = nested_parser.parse
+      content = nested_result[:rules]
 
-        # Move position past the closing brace
-        @_pos = decl_end
-        # The closing brace should be at decl_end
-        @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
+      # Move position past the closing brace
+      @_pos = block_end
+      # The closing brace should be at block_end
+      @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
 
-        # Get rule ID and increment
-        rule_id = @_rule_id_counter
-        @_rule_id_counter += 1
+      # Get rule ID and increment
+      rule_id = @_rule_id_counter
+      @_rule_id_counter += 1
 
-        # Create AtRule with declarations
-        at_rule = AtRule.new(rule_id, selector, content, nil, @_parent_media_query_id)
-        @rules << at_rule
+      # Create AtRule with nested rules
+      at_rule = AtRule.new(rule_id, selector, content, nil, @_parent_media_query_id)
+      @rules << at_rule
+    end
 
-        return
-      end
+    # @font-face (contains a <declaration-list>)
+    #
+    # @param at_rule_start [Integer] Position of the at-rule's leading '@'
+    def parse_font_face_at_rule(at_rule_start)
+      # Build selector string: "@font-face"
+      selector = scan_at_rule_selector(at_rule_start)
+      return if selector.nil?
 
-      # Unknown at-rule (@property, @page, @counter-style, etc.)
-      # Treat as a regular selector-based rule with declarations
-      selector_start = at_rule_start # Points to '@'
+      # Find matching closing brace
+      decl_start = @_pos
+      decl_end = find_matching_brace(@_pos)
 
-      # Skip to opening brace
-      until eof? || peek_byte == BYTE_LBRACE # Save a not_opt instruction: while !eof? && peek_byte != BYTE_LBRACE
-        @_pos += 1
-      end
+      # Parse declarations
+      content = parse_declarations_block(decl_start, decl_end)
 
-      return if eof? || peek_byte != BYTE_LBRACE
+      # Move position past the closing brace
+      @_pos = decl_end
+      # The closing brace should be at decl_end
+      @_pos += 1 if @_pos < @_len && @_css.getbyte(@_pos) == BYTE_RBRACE
 
-      selector_end = @_pos
-      # Trim trailing whitespace
-      while selector_end > selector_start && whitespace?(@_css.getbyte(selector_end - 1))
-        selector_end -= 1
-      end
-      selector = byteslice_encoded(selector_start, selector_end - selector_start)
+      # Get rule ID and increment
+      rule_id = @_rule_id_counter
+      @_rule_id_counter += 1
 
-      @_pos += 1 # skip '{'
+      # Create AtRule with declarations
+      at_rule = AtRule.new(rule_id, selector, content, nil, @_parent_media_query_id)
+      @rules << at_rule
+    end
+
+    # Unknown at-rule (@property, @page, @counter-style, etc.) - treated as a
+    # regular selector-based rule with declarations, since this parser has no
+    # special handling for it.
+    #
+    # @param at_rule_start [Integer] Position of the at-rule's leading '@'
+    def parse_unknown_at_rule(at_rule_start)
+      selector = scan_at_rule_selector(at_rule_start)
+      return if selector.nil?
 
       # Parse declarations
       declarations = parse_declarations