cataract 0.2.4 → 0.3.0

data/ext/cataract/css_parser.c

@@ -12,6 +12,11 @@
 
 #include "cataract.h"
 #include <string.h>
+#include <stdint.h>
+
+// Use uint8_t for boolean flags to reduce struct size and improve cache efficiency
+// (int is 4 bytes, uint8_t is 1 byte - saves 27 bytes across 9 flags)
+#define BOOLEAN uint8_t
 
 // Parser context passed through recursive calls
 typedef struct {
@@ -26,16 +31,55 @@ typedef struct {
     int media_query_id_counter; // Next MediaQuery ID (0-indexed)
     int next_media_query_list_id; // Next media query list ID (0-indexed)
     int media_query_count;    // Safety limit for media queries
-    st_table *media_cache;    // Parse-time cache: string => parsed media types
-    int has_nesting;          // Set to 1 if any nested rules are created
-    int selector_lists_enabled; // Parser option: track selector lists (1=enabled, 0=disabled)
-    int depth;                // Current recursion depth (safety limit)
+    BOOLEAN has_nesting;      // Set to 1 if any nested rules are created
+    BOOLEAN selector_lists_enabled; // Parser option: track selector lists (1=enabled, 0=disabled)
+    BOOLEAN depth;            // Current recursion depth (safety limit)
     // URL conversion options
     VALUE base_uri;           // Base URI for resolving relative URLs (Qnil if disabled)
     VALUE uri_resolver;       // Proc to call for URL resolution (Qnil for default)
-    int absolute_paths;       // Whether to convert relative URLs to absolute
+    BOOLEAN absolute_paths;   // Whether to convert relative URLs to absolute
+    // Parse error checking options
+    VALUE css_string;         // Full CSS string for error position calculation
+    BOOLEAN check_empty_values; // Raise error on empty declaration values
+    BOOLEAN check_malformed_declarations; // Raise error on declarations without colons
+    BOOLEAN check_invalid_selectors; // Raise error on empty/malformed selectors
+    BOOLEAN check_invalid_selector_syntax; // Raise error on syntax violations (.. ## etc)
+    BOOLEAN check_malformed_at_rules; // Raise error on @media/@supports without conditions
+    BOOLEAN check_unclosed_blocks; // Raise error on missing closing braces
 } ParserContext;
 
+// Build a fresh ParserContext for a nested parse (e.g. @keyframes contents).
+// The child gets its own rule/media collections, but explicitly inherits the
+// parent's error-checking flags and URL/error-reporting fields instead of
+// relying on zero-initialization, which previously left check_* flags
+// disabled and css_string/base_uri NULL regardless of the parent's settings.
+static inline ParserContext init_child_context(ParserContext *parent) {
+    ParserContext child = {0};
+
+    child.rules_array = rb_ary_new();
+    child.media_index = rb_hash_new();
+    child.selector_lists = rb_hash_new();
+    child.imports_array = rb_ary_new();
+    child.media_queries = rb_ary_new();
+    child.media_query_lists = rb_hash_new();
+
+    child.selector_lists_enabled = parent->selector_lists_enabled;
+
+    child.base_uri = parent->base_uri;
+    child.uri_resolver = parent->uri_resolver;
+    child.absolute_paths = parent->absolute_paths;
+
+    child.css_string = parent->css_string;
+    child.check_empty_values = parent->check_empty_values;
+    child.check_malformed_declarations = parent->check_malformed_declarations;
+    child.check_invalid_selectors = parent->check_invalid_selectors;
+    child.check_invalid_selector_syntax = parent->check_invalid_selector_syntax;
+    child.check_malformed_at_rules = parent->check_malformed_at_rules;
+    child.check_unclosed_blocks = parent->check_unclosed_blocks;
+
+    return child;
+}
+
 // Macro to skip CSS comments /* ... */
 // Usage: SKIP_COMMENT(p, end) where p is current position, end is limit
 // Side effect: advances p past the comment and continues to next iteration
@@ -63,6 +107,20 @@ static inline const char* find_matching_brace(const char *start, const char *end
     return p;
 }
 
+// Find matching closing brace with strict error checking
+// Input: start = position after opening '{', end = limit, check_unclosed = whether to raise error
+// Returns: pointer to matching '}' (raises error if not found and check_unclosed is true)
+static inline const char* find_matching_brace_strict(const char *start, const char *end, int check_unclosed) {
+    const char *closing_brace = find_matching_brace(start, end);
+
+    // Check if we found the closing brace
+    if (check_unclosed && closing_brace >= end) {
+        rb_raise(eParseError, "Unclosed block: missing closing brace");
+    }
+
+    return closing_brace;
+}
+
 // Find matching closing paren
 // Input: start = position after opening '(', end = limit
 // Returns: pointer to matching ')' (or end if not found)
@@ -78,6 +136,99 @@ static inline const char* find_matching_paren(const char *start, const char *end
     return p;
 }
 
+// Helper function to raise ParseError with automatic position calculation
+// Does not return - raises error and exits
+__attribute__((noreturn))
+static void raise_parse_error_at(ParserContext *ctx, const char *error_pos, const char *message, const char *error_type) {
+    const char *css = RSTRING_PTR(ctx->css_string);
+    long pos = error_pos - css;
+
+    // Build keyword args hash
+    VALUE kwargs = rb_hash_new();
+    rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+    rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(pos));
+    rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern(error_type)));
+
+    // Create ParseError instance
+    VALUE msg_str = rb_str_new_cstr(message);
+    VALUE argv[2] = {msg_str, kwargs};
+    VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+
+    // Raise the error
+    rb_exc_raise(error);
+}
+
+// Check if a selector contains only valid CSS selector characters and sequences
+// Returns 1 if valid, 0 if invalid
+// Valid characters: a-z A-Z 0-9 - _ . # [ ] : * > + ~ ( ) ' " = ^ $ | \ & % / whitespace
+static inline int is_valid_selector(const char *start, const char *end) {
+    const char *p = start;
+    while (p < end) {
+        unsigned char c = (unsigned char)*p;
+
+        // Check for invalid character sequences
+        if (p + 1 < end) {
+            // Double dot (..) is invalid
+            if (c == '.' && *(p + 1) == '.') {
+                return 0;
+            }
+            // Double hash (##) is invalid
+            if (c == '#' && *(p + 1) == '#') {
+                return 0;
+            }
+        }
+
+        // Alphanumeric
+        if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')) {
+            p++;
+            continue;
+        }
+
+        // Whitespace
+        if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
+            p++;
+            continue;
+        }
+
+        // Valid CSS selector special characters
+        switch (c) {
+            case '-':  // Hyphen (in identifiers, attribute selectors)
+            case '_':  // Underscore (in identifiers)
+            case '.':  // Class selector
+            case '#':  // ID selector
+            case '[':  // Attribute selector start
+            case ']':  // Attribute selector end
+            case ':':  // Pseudo-class/element (:: is valid for pseudo-elements)
+            case '*':  // Universal selector, attribute operator
+            case '>':  // Child combinator
+            case '+':  // Adjacent sibling combinator
+            case '~':  // General sibling combinator
+            case '(':  // Pseudo-class function
+            case ')':  // Pseudo-class function end
+            case '\'': // String in attribute selector
+            case '"':  // String in attribute selector
+            case '=':  // Attribute operator
+            case '^':  // Attribute operator ^=
+            case '$':  // Attribute operator $=
+            case '|':  // Attribute operator |=, namespace separator
+            case '\\': // Escape character
+            case '&':  // Nesting selector
+            case '%':  // Sometimes used in selectors
+            case '/':  // Sometimes used in selectors
+            case '!':  // Negation (though rare)
+            case ',':  // List separator (shouldn't be here after splitting, but allow it)
+                p++;
+                break;
+
+            default:
+                // Invalid character found
+                return 0;
+        }
+    }
+
+    return 1;
+}
+
 // Lowercase property name (CSS property names are ASCII-only)
 // Non-static so merge_new.c can use it
 VALUE lowercase_property(VALUE property_str) {
@@ -177,7 +328,7 @@ static VALUE resolve_nested_selector(VALUE parent_selector, const char *nested_s
     long parent_len = RSTRING_LEN(parent_selector);
 
     // Check if nested selector contains &
-    int has_ampersand = 0;
+    BOOLEAN has_ampersand = 0;
     for (long i = 0; i < nested_len; i++) {
         if (nested_sel[i] == '&') {
             has_ampersand = 1;
@@ -598,79 +749,94 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
         }
         if (pos >= end) break;
 
-        // Find property (up to colon)
-        // Example: "color: red; ..."
-        //           ^pos  ^pos (at :)
+        // A property name can never legitimately contain '{' - its presence
+        // means this is actually an unsupported/invalid nested selector (e.g.
+        // a bare type selector without '&') that has_nested_selectors() didn't
+        // recognize 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. So stop_prop_scan_early=1.
         const char *prop_start = pos;
-        while (pos < end && *pos != ':' && *pos != ';') pos++;
-
-        // Malformed declaration - skip to next semicolon to recover
-        if (pos >= end || *pos != ':') {
+        struct declaration_span span;
+        if (!parse_one_declaration(&pos, end, 1, &span)) {
+            // Malformed declaration - skip to next semicolon to recover
+            if (ctx->check_malformed_declarations) {
+                // Extract property text for error message
+                const char *prop_text_end = pos;
+                trim_trailing(prop_start, &prop_text_end);
+                long prop_text_len = prop_text_end - prop_start;
+
+                const char *css = RSTRING_PTR(ctx->css_string);
+                long error_pos = prop_start - css;
+
+                if (prop_text_len == 0) {
+                    // Build keyword args hash
+                    VALUE kwargs = rb_hash_new();
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(error_pos));
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern("malformed_declaration")));
+
+                    VALUE msg_str = rb_str_new_cstr("Malformed declaration: missing property name");
+                    VALUE argv[2] = {msg_str, kwargs};
+                    VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+                    rb_exc_raise(error);
+                } else {
+                    // Limit property name to 200 chars in error message
+                    int display_len = (prop_text_len > 200) ? 200 : (int)prop_text_len;
+                    char error_msg[256];
+                    snprintf(error_msg, sizeof(error_msg),
+                           "Malformed declaration: missing colon after '%.*s'",
+                           display_len, prop_start);
+
+                    // Build keyword args hash
+                    VALUE kwargs = rb_hash_new();
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(error_pos));
+                    rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern("malformed_declaration")));
+
+                    VALUE msg_str = rb_str_new_cstr(error_msg);
+                    VALUE argv[2] = {msg_str, kwargs};
+                    VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+                    rb_exc_raise(error);
+                }
+            }
             while (pos < end && *pos != ';') pos++;
             if (pos < end) pos++;  // Skip the semicolon
             continue;
         }
 
-        const char *prop_end = pos;
-        // Trim whitespace from property
-        trim_trailing(prop_start, &prop_end);
-        trim_leading(&prop_start, prop_end);
-
-        pos++;  // Skip colon
-
-        // Skip whitespace after colon
-        while (pos < end && IS_WHITESPACE(*pos)) {
-            pos++;
-        }
-
-        // Find value (up to semicolon or end)
-        // Must track paren depth to avoid breaking on semicolons inside url() or rgba()
-        // Example: "url(data:image/svg+xml;base64,...); next-prop: ..."
-        //           ^val_start                        ^pos (at ; outside parens)
-        const char *val_start = pos;
-        int paren_depth = 0;
-        while (pos < end) {
-            if (*pos == '(') {                      // At: '('
-                paren_depth++;                       // Depth: 1
-            } else if (*pos == ')') {                // At: ')'
-                paren_depth--;                       // Depth: 0
-            } else if (*pos == ';' && paren_depth == 0) {  // At: ';' (outside parens)
-                break;  // Found terminating semicolon
-            }
-            pos++;
-        }
-        const char *val_end = pos;
-
-        // Trim trailing whitespace from value
-        trim_trailing(val_start, &val_end);
-
-        // Check for !important
-        int is_important = 0;
-        if (val_end - val_start >= 10) {  // strlen("!important") = 10
-            const char *check = val_end - 10;
-            while (check < val_end && IS_WHITESPACE(*check)) check++;
-            if (check < val_end && *check == '!') {
-                check++;
-                while (check < val_end && IS_WHITESPACE(*check)) check++;
-                // strncmp safely handles remaining length check
-                if (check + 9 <= val_end && strncmp(check, "important", 9) == 0) {
-                    is_important = 1;
-                    const char *important_pos = check - 1;
-                    while (important_pos > val_start && (IS_WHITESPACE(*(important_pos-1)) || *(important_pos-1) == '!')) {
-                        important_pos--;
-                    }
-                    val_end = important_pos;
-                }
-            }
+        // Check for empty value
+        if (span.val_end <= span.val_start && ctx->check_empty_values) {
+            long prop_len = span.prop_end - span.prop_start;
+            const char *css = RSTRING_PTR(ctx->css_string);
+            long error_pos = span.val_start - css;
+
+            // Build error message
+            int display_len = (prop_len > 200) ? 200 : (int)prop_len;
+            char error_msg[256];
+            snprintf(error_msg, sizeof(error_msg),
+                   "Empty value for property '%.*s'",
+                   display_len, span.prop_start);
+
+            // Build keyword args hash
+            VALUE kwargs = rb_hash_new();
+            rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+            rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(error_pos));
+            rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern("empty_value")));
+
+            // Create ParseError instance: ParseError.new(message, **kwargs)
+            VALUE msg_str = rb_str_new_cstr(error_msg);
+            VALUE argv[2] = {msg_str, kwargs};
+            VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+
+            // Raise the error
+            rb_exc_raise(error);
         }
 
-        // Final trim
-        trim_trailing(val_start, &val_end);
-
         // Skip if value is empty
-        if (val_end > val_start) {
-            long prop_len = prop_end - prop_start;
-            long val_len = val_end - val_start;
+        if (span.val_end > span.val_start) {
+            long prop_len = span.prop_end - span.prop_start;
+            long val_len = span.val_end - span.val_start;
 
             // Check property name length
             if (prop_len > MAX_PROPERTY_NAME_LENGTH) {
@@ -687,18 +853,18 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
             }
 
             // Create property string - use UTF-8 to support custom properties with Unicode
-            VALUE property = rb_utf8_str_new(prop_start, prop_len);
+            VALUE property = rb_utf8_str_new(span.prop_start, prop_len);
             // Custom properties (--foo) are case-sensitive and can contain Unicode
             // Regular properties are ASCII-only and case-insensitive
-            if (!(prop_len >= 2 && prop_start[0] == '-' && prop_start[1] == '-')) {
+            if (!(prop_len >= 2 && span.prop_start[0] == '-' && span.prop_start[1] == '-')) {
                 // Regular property: force ASCII encoding and lowercase
                 rb_enc_associate(property, rb_usascii_encoding());
                 property = lowercase_property(property);
             }
-            VALUE value = rb_utf8_str_new(val_start, val_len);
+            VALUE value = rb_utf8_str_new(span.val_start, val_len);
 
             // Convert relative URLs to absolute if enabled
-            if (ctx && ctx->absolute_paths && !NIL_P(ctx->base_uri)) {
+            if (ctx->absolute_paths && !NIL_P(ctx->base_uri)) {
                 value = convert_urls_in_value(value, ctx->base_uri, ctx->uri_resolver);
             }
 
@@ -706,13 +872,12 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
             VALUE decl = rb_struct_new(cDeclaration,
                 property,
                 value,
-                is_important ? Qtrue : Qfalse
+                span.is_important ? Qtrue : Qfalse
             );
 
             rb_ary_push(declarations, decl);
         }
-
-        if (pos < end && *pos == ';') pos++;  // Skip semicolon if present
+        // parse_one_declaration already advanced pos past the ';' on success
     }
 
     return declarations;
@@ -801,6 +966,54 @@ static VALUE intern_media_query_safe(ParserContext *ctx, const char *query_str,
     return sym;
 }
 
+/*
+ * Parse a single media query (already split on commas, if applicable, and
+ * trimmed of surrounding whitespace) into a type symbol and an optional
+ * conditions string.
+ *
+ * Examples:
+ *   "(min-width: 500px)"          -> type=:all,    conditions="(min-width: 500px)"
+ *   "screen"                      -> type=:screen, conditions=nil
+ *   "screen and (min-width: 500)" -> type=:screen, conditions="(min-width: 500)"
+ *
+ * Shared by @media block parsing (parse_mixed_block's nested-@media case and
+ * parse_css_recursive's top-level case) and @import's trailing media query,
+ * so all three agree on stripping the "and" keyword between type and
+ * conditions.
+ */
+static void parse_single_media_query(const char *query_start, const char *query_end,
+                                      VALUE *media_type_out, VALUE *media_conditions_out) {
+    const char *mq_ptr = query_start;
+    VALUE media_type;
+    VALUE media_conditions = Qnil;
+
+    if (*mq_ptr == '(') {
+        // Starts with '(' - just conditions, type defaults to :all
+        media_type = ID2SYM(rb_intern("all"));
+        media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
+    } else {
+        // Extract media type (first word)
+        const char *type_start = mq_ptr;
+        while (mq_ptr < query_end && !IS_WHITESPACE(*mq_ptr) && *mq_ptr != '(') mq_ptr++;
+        VALUE type_str = rb_utf8_str_new(type_start, mq_ptr - type_start);
+        media_type = ID2SYM(rb_intern_str(type_str));
+
+        // Skip whitespace and "and" keyword if present
+        while (mq_ptr < query_end && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
+        if (mq_ptr + 3 <= query_end && strncmp(mq_ptr, "and", 3) == 0) {
+            mq_ptr += 3;
+            while (mq_ptr < query_end && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
+        }
+
+        if (mq_ptr < query_end) {
+            media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
+        }
+    }
+
+    *media_type_out = media_type;
+    *media_conditions_out = media_conditions;
+}
+
 /*
  * Parse mixed declarations and nested selectors from a block
  * Used when a CSS rule block contains both declarations and nested rules
@@ -856,31 +1069,9 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
             trim_trailing(media_query_start, &media_query_end_trimmed);
 
             // Parse media query and create MediaQuery object
-            const char *mq_ptr = media_query_start;
             VALUE media_type;
-            VALUE media_conditions = Qnil;
-
-            if (*mq_ptr == '(') {
-                // Starts with '(' - just conditions, type defaults to :all
-                media_type = ID2SYM(rb_intern("all"));
-                media_conditions = rb_utf8_str_new(mq_ptr, media_query_end_trimmed - mq_ptr);
-            } else {
-                // Extract media type (first word)
-                const char *type_start = mq_ptr;
-                while (mq_ptr < media_query_end_trimmed && !IS_WHITESPACE(*mq_ptr) && *mq_ptr != '(') mq_ptr++;
-                VALUE type_str = rb_utf8_str_new(type_start, mq_ptr - type_start);
-                media_type = ID2SYM(rb_intern_str(type_str));
-
-                // Skip "and" keyword if present
-                while (mq_ptr < media_query_end_trimmed && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
-                if (mq_ptr + 3 <= media_query_end_trimmed && strncmp(mq_ptr, "and", 3) == 0) {
-                    mq_ptr += 3;
-                    while (mq_ptr < media_query_end_trimmed && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
-                }
-                if (mq_ptr < media_query_end_trimmed) {
-                    media_conditions = rb_utf8_str_new(mq_ptr, media_query_end_trimmed - mq_ptr);
-                }
-            }
+            VALUE media_conditions;
+            parse_single_media_query(media_query_start, media_query_end_trimmed, &media_type, &media_conditions);
 
             // Create MediaQuery object
             VALUE media_query = rb_struct_new(cMediaQuery,
@@ -896,7 +1087,7 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
 
             // Find matching closing brace
             const char *media_block_start = p;
-            const char *media_block_end = find_matching_brace(p, end);
+            const char *media_block_end = find_matching_brace_strict(p, end, ctx->check_unclosed_blocks);
             p = media_block_end;
 
             if (p < end) p++;  // Skip }
@@ -909,7 +1100,7 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
 
                 // This should never happen - parent_media_query_id should always be valid
                 if (NIL_P(parent_mq)) {
-                    rb_raise(eParserError,
+                    rb_raise(eParseError,
                         "Invalid parent_media_query_id: %d (not found in media_queries array)",
                         parent_media_query_id);
                 }
@@ -1022,7 +1213,7 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
             // Example: "& .child { font: 14px; }"
             //                     ^nested_block_start  ^nested_block_end (at })
             const char *nested_block_start = p;
-            const char *nested_block_end = find_matching_brace(p, end);
+            const char *nested_block_end = find_matching_brace_strict(p, end, ctx->check_unclosed_blocks);
             p = nested_block_end;
 
             if (p < end) p++;  // Skip }
@@ -1095,49 +1286,18 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
         }
 
         // This is a declaration - parse it
-        const char *prop_start = p;
-        while (p < end && *p != ':' && *p != ';' && *p != '{') p++;
-        if (p >= end || *p != ':') {
+        struct declaration_span span;
+        if (!parse_one_declaration(&p, end, 1, &span)) {
             // Malformed - skip to semicolon
             while (p < end && *p != ';') p++;
             if (p < end) p++;
             continue;
         }
 
-        const char *prop_end = p;
-        trim_trailing(prop_start, &prop_end);
-
-        p++;  // Skip :
-        trim_leading(&p, end);
-
-        const char *val_start = p;
-        int important = 0;
-
-        // Find end of value (semicolon or closing brace or end)
-        while (p < end && *p != ';' && *p != '}') p++;
-        const char *val_end = p;
-
-        // Check for !important
-        const char *important_check = val_end - 10;  // " !important"
-        if (important_check >= val_start) {
-            trim_trailing(val_start, &val_end);
-            if (val_end - val_start >= 10) {
-                if (strncmp(val_end - 10, "!important", 10) == 0) {
-                    important = 1;
-                    val_end -= 10;
-                    trim_trailing(val_start, &val_end);
-                }
-            }
-        } else {
-            trim_trailing(val_start, &val_end);
-        }
-
-        if (p < end && *p == ';') p++;
-
         // Create declaration
-        if (prop_end > prop_start && val_end > val_start) {
-            long prop_len = prop_end - prop_start;
-            long val_len = val_end - val_start;
+        if (span.prop_end > span.prop_start && span.val_end > span.val_start) {
+            long prop_len = span.prop_end - span.prop_start;
+            long val_len = span.val_end - span.val_start;
 
             // Check property name length
             if (prop_len > MAX_PROPERTY_NAME_LENGTH) {
@@ -1154,15 +1314,15 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
             }
 
             // Create property string - use UTF-8 to support custom properties with Unicode
-            VALUE property = rb_utf8_str_new(prop_start, prop_len);
+            VALUE property = rb_utf8_str_new(span.prop_start, prop_len);
             // Custom properties (--foo) are case-sensitive and can contain Unicode
             // Regular properties are ASCII-only and case-insensitive
-            if (!(prop_len >= 2 && prop_start[0] == '-' && prop_start[1] == '-')) {
+            if (!(prop_len >= 2 && span.prop_start[0] == '-' && span.prop_start[1] == '-')) {
                 // Regular property: force ASCII encoding and lowercase
                 rb_enc_associate(property, rb_usascii_encoding());
                 property = lowercase_property(property);
             }
-            VALUE value = rb_utf8_str_new(val_start, val_len);
+            VALUE value = rb_utf8_str_new(span.val_start, val_len);
 
             // Convert relative URLs to absolute if enabled
             if (ctx->absolute_paths && !NIL_P(ctx->base_uri)) {
@@ -1172,7 +1332,7 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
             VALUE decl = rb_struct_new(cDeclaration,
                 property,
                 value,
-                important ? Qtrue : Qfalse
+                span.is_important ? Qtrue : Qfalse
             );
 
             rb_ary_push(declarations, decl);
@@ -1283,29 +1443,9 @@ static void parse_import_statement(ParserContext *ctx, const char **p_ptr, const
 
                     if (query_start < query_end) {
                         // Parse this individual media query
-                        const char *mq_ptr = query_start;
                         VALUE media_type;
-                        VALUE media_conditions = Qnil;
-
-                        if (*mq_ptr == '(') {
-                            // Starts with '(' - just conditions, type defaults to :all
-                            media_type = ID2SYM(rb_intern("all"));
-                            media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
-                        } else {
-                            // Extract media type (first word)
-                            const char *type_start = mq_ptr;
-                            while (mq_ptr < query_end && !IS_WHITESPACE(*mq_ptr) && *mq_ptr != '(') mq_ptr++;
-                            VALUE type_str = rb_utf8_str_new(type_start, mq_ptr - type_start);
-                            media_type = ID2SYM(rb_intern_str(type_str));
-
-                            // Skip whitespace
-                            while (mq_ptr < query_end && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
-
-                            // Check if there are conditions (rest of string)
-                            if (mq_ptr < query_end) {
-                                media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
-                            }
-                        }
+                        VALUE media_conditions;
+                        parse_single_media_query(query_start, query_end, &media_type, &media_conditions);
 
                         // Create MediaQuery struct
                         VALUE media_query = rb_struct_new(cMediaQuery,
@@ -1362,6 +1502,665 @@ static void parse_import_statement(ParserContext *ctx, const char **p_ptr, const
     RB_GC_GUARD(import_stmt);
 }
 
+/*
+ * Handle an @media at-rule found at brace_depth 0. Called with *p_ptr
+ * pointing at the '@' of "@media"; advances *p_ptr past the entire
+ * "@media ... { ... }" construct (including its closing '}', if found).
+ */
+static void handle_media_at_rule(ParserContext *ctx, const char **p_ptr, const char *pe,
+                                  VALUE parent_media_sym, int parent_media_query_id) {
+    const char *p = *p_ptr;
+    p += 6;  // Skip "@media"
+
+    // Skip whitespace
+    while (p < pe && IS_WHITESPACE(*p)) p++;
+
+    // Find media query (up to opening brace)
+    const char *mq_start = p;
+    while (p < pe && *p != '{') p++;
+    const char *mq_end = p;
+
+    // Trim
+    trim_trailing(mq_start, &mq_end);
+
+    // Check for empty media query
+    if (mq_end <= mq_start) {
+        if (ctx->check_malformed_at_rules) {
+            raise_parse_error_at(ctx, mq_start, "Malformed @media: missing media query", "malformed_at_rule");
+        }
+
+        // Empty media query with check disabled - skip @media wrapper and parse contents as regular rules
+        if (p >= pe || *p != '{') {
+            *p_ptr = p;
+            return;  // Malformed structure
+        }
+        p++;  // Skip opening {
+        const char *block_start = p;
+        const char *block_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
+        p = block_end;
+
+        // Parse block contents with NO media query context
+        ctx->depth++;
+        parse_css_recursive(ctx, block_start, block_end, parent_media_sym, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID, parent_media_query_id);
+        ctx->depth--;
+
+        if (p < pe && *p == '}') p++;
+        *p_ptr = p;
+        return;
+    }
+
+    if (p >= pe || *p != '{') {
+        *p_ptr = p;
+        return;  // Malformed
+    }
+
+    // Split comma-separated media queries (e.g., "screen, print" -> ["screen", "print"])
+    // Per W3C spec, comma acts as logical OR - each query is independent
+    VALUE media_query_ids = rb_ary_new();
+
+    const char *query_start = mq_start;
+    for (const char *p_comma = mq_start; p_comma <= mq_end; p_comma++) {
+        if (p_comma == mq_end || *p_comma == ',') {
+            const char *query_end = p_comma;
+
+            // Trim whitespace from this query
+            while (query_start < query_end && IS_WHITESPACE(*query_start)) query_start++;
+            while (query_end > query_start && IS_WHITESPACE(*(query_end - 1))) query_end--;
+
+            if (query_start < query_end) {
+                // Parse this individual media query
+                VALUE media_type;
+                VALUE media_conditions;
+                parse_single_media_query(query_start, query_end, &media_type, &media_conditions);
+
+                // Create MediaQuery object for this query
+                VALUE media_query = rb_struct_new(cMediaQuery,
+                    INT2FIX(ctx->media_query_id_counter),
+                    media_type,
+                    media_conditions
+                );
+                rb_ary_push(ctx->media_queries, media_query);
+                rb_ary_push(media_query_ids, INT2FIX(ctx->media_query_id_counter));
+                ctx->media_query_id_counter++;
+            }
+
+            // Move to start of next query
+            query_start = p_comma + 1;
+        }
+    }
+
+    // If multiple queries, track them as a list for serialization
+    int media_query_list_id = -1;
+    if (RARRAY_LEN(media_query_ids) > 1) {
+        media_query_list_id = ctx->next_media_query_list_id;
+        rb_hash_aset(ctx->media_query_lists, INT2FIX(media_query_list_id), media_query_ids);
+        ctx->next_media_query_list_id++;
+    }
+
+    // Use first query ID as the primary one for rules in this block
+    int current_media_query_id = FIX2INT(rb_ary_entry(media_query_ids, 0));
+
+    // Handle nested @media by combining with parent
+    if (parent_media_query_id >= 0) {
+        VALUE parent_mq = rb_ary_entry(ctx->media_queries, parent_media_query_id);
+        VALUE parent_type = rb_struct_aref(parent_mq, INT2FIX(1)); // type field
+        VALUE parent_conditions = rb_struct_aref(parent_mq, INT2FIX(2)); // conditions field
+
+        // Get child media query (first one in the list)
+        VALUE child_mq = rb_ary_entry(ctx->media_queries, current_media_query_id);
+        VALUE child_conditions = rb_struct_aref(child_mq, INT2FIX(2)); // conditions field
+
+        // Combined type is parent's type (outermost wins, child type ignored)
+        VALUE combined_type = parent_type;
+        VALUE combined_conditions;
+
+        if (!NIL_P(parent_conditions) && !NIL_P(child_conditions)) {
+            combined_conditions = rb_sprintf("%"PRIsVALUE" and %"PRIsVALUE, parent_conditions, child_conditions);
+        } else if (!NIL_P(parent_conditions)) {
+            combined_conditions = parent_conditions;
+        } else {
+            combined_conditions = child_conditions;
+        }
+
+        VALUE combined_mq = rb_struct_new(cMediaQuery,
+            INT2FIX(ctx->media_query_id_counter),
+            combined_type,
+            combined_conditions
+        );
+        rb_ary_push(ctx->media_queries, combined_mq);
+        current_media_query_id = ctx->media_query_id_counter;
+        ctx->media_query_id_counter++;
+    }
+
+    // For backwards compat, also create symbol (will be removed later)
+    VALUE child_media_sym = intern_media_query_safe(ctx, mq_start, mq_end - mq_start);
+    VALUE combined_media_sym = combine_media_queries(parent_media_sym, child_media_sym);
+
+    p++;  // Skip opening {
+
+    // Find matching closing brace
+    const char *block_start = p;
+    const char *block_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
+    p = block_end;
+
+    // Recursively parse @media block with new media query context
+    ctx->depth++;
+    parse_css_recursive(ctx, block_start, block_end, combined_media_sym, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID, current_media_query_id);
+    ctx->depth--;
+
+    if (p < pe && *p == '}') p++;
+    *p_ptr = p;
+}
+
+/*
+ * Handle a conditional-group at-rule (@supports/@layer/@container/@scope)
+ * found at brace_depth 0. Behaves like @media but doesn't affect media
+ * context, so it recurses with the same parent_media_sym/parent_selector/
+ * parent_rule_id it was called with. Called with *p_ptr pointing at the
+ * '@'; at_start/at_name_end/at_name_len describe the already-scanned
+ * at-rule name. Advances *p_ptr past the entire construct (including its
+ * closing '}', if found).
+ */
+static void handle_conditional_group_at_rule(ParserContext *ctx, const char **p_ptr, const char *pe,
+                                              const char *at_start, const char *at_name_end, long at_name_len,
+                                              VALUE parent_media_sym, VALUE parent_selector, VALUE parent_rule_id,
+                                              int parent_media_query_id) {
+    // Check if this rule requires a condition
+    BOOLEAN requires_condition =
+        (at_name_len == 8 && strncmp(at_start, "supports", 8) == 0) ||
+        (at_name_len == 9 && strncmp(at_start, "container", 9) == 0);
+
+    // Extract condition (between at-rule name and opening brace)
+    const char *cond_start = at_name_end;
+    while (cond_start < pe && IS_WHITESPACE(*cond_start)) cond_start++;
+
+    // Skip to opening brace
+    const char *p = at_name_end;
+    while (p < pe && *p != '{') p++;
+
+    if (p >= pe || *p != '{') {
+        *p_ptr = p;
+        return;  // Malformed
+    }
+
+    // Trim condition
+    const char *cond_end = p;
+    while (cond_end > cond_start && IS_WHITESPACE(*(cond_end - 1))) cond_end--;
+
+    // Check for missing condition
+    if (requires_condition && cond_end <= cond_start && ctx->check_malformed_at_rules) {
+        char error_msg[100];
+        snprintf(error_msg, sizeof(error_msg), "Malformed @%.*s: missing condition", (int)at_name_len, at_start);
+        raise_parse_error_at(ctx, at_start - 1, error_msg, "malformed_at_rule");
+    }
+
+    p++;  // Skip opening {
+
+    // Find matching closing brace
+    const char *block_start = p;
+    const char *block_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
+    p = block_end;
+
+    // Recursively parse block content (preserve parent media context)
+    ctx->depth++;
+    parse_css_recursive(ctx, block_start, block_end, parent_media_sym, parent_selector, parent_rule_id, parent_media_query_id);
+    ctx->depth--;
+
+    if (p < pe && *p == '}') p++;
+    *p_ptr = p;
+}
+
+/*
+ * Handle an @keyframes (or -webkit-/-moz- prefixed) at-rule found at
+ * brace_depth 0. Called with *p_ptr pointing at the '@'; at_name_end marks
+ * the end of the already-scanned at-rule name. Advances *p_ptr past the
+ * entire construct (including its closing '}', if found).
+ */
+static void handle_keyframes_at_rule(ParserContext *ctx, const char **p_ptr, const char *pe,
+                                      const char *at_name_end, VALUE parent_media_sym, int parent_media_query_id) {
+    // Build full selector string: "@keyframes fade"
+    const char *selector_start = *p_ptr;  // Points to '@'
+    const char *p = at_name_end;
+    while (p < pe && *p != '{') p++;
+
+    if (p >= pe || *p != '{') {
+        *p_ptr = p;
+        return;  // Malformed
+    }
+
+    const char *selector_end = p;
+    while (selector_end > selector_start && IS_WHITESPACE(*(selector_end - 1))) {
+        selector_end--;
+    }
+    VALUE selector = rb_utf8_str_new(selector_start, selector_end - selector_start);
+
+    p++;  // Skip opening {
+
+    // Find matching closing brace
+    const char *block_start = p;
+    const char *block_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
+    p = block_end;
+
+    // Parse keyframe blocks as rules (from/to/0%/50% etc). Unlike @media/@supports,
+    // which thread ctx straight through, these aren't real page selectors and must
+    // NOT land in ctx->rules_array — they need their own array to become this
+    // AtRule's `content` below, so parse into an isolated child context instead.
+    ParserContext nested_ctx = init_child_context(ctx);
+    parse_css_recursive(&nested_ctx, block_start, block_end, NO_PARENT_MEDIA, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID, NO_MEDIA_QUERY_ID);
+
+    // Get rule ID and increment
+    int rule_id = ctx->rule_id_counter++;
+
+    // Create AtRule with nested rules
+    VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
+    VALUE at_rule = rb_struct_new(cAtRule,
+        INT2FIX(rule_id),
+        selector,
+        nested_ctx.rules_array,  // Array of Rule (keyframe blocks)
+        Qnil,  // specificity
+        media_query_id_val  // media_query_id from parent context
+    );
+
+    // Add to rules array
+    rb_ary_push(ctx->rules_array, at_rule);
+
+    // Add to media index if in media query
+    if (!NIL_P(parent_media_sym)) {
+        VALUE rule_ids = rb_hash_aref(ctx->media_index, parent_media_sym);
+        if (NIL_P(rule_ids)) {
+            rule_ids = rb_ary_new();
+            rb_hash_aset(ctx->media_index, parent_media_sym, rule_ids);
+        }
+        rb_ary_push(rule_ids, INT2FIX(rule_id));
+    }
+
+    if (p < pe && *p == '}') p++;
+    *p_ptr = p;
+}
+
+/*
+ * Handle an @font-face at-rule found at brace_depth 0. Called with *p_ptr
+ * pointing at the '@'; at_name_end marks the end of the already-scanned
+ * at-rule name. Advances *p_ptr past the entire construct (including its
+ * closing '}', if found).
+ */
+static void handle_font_face_at_rule(ParserContext *ctx, const char **p_ptr, const char *pe,
+                                      const char *at_name_end, VALUE parent_media_sym, int parent_media_query_id) {
+    // Build selector string: "@font-face"
+    const char *selector_start = *p_ptr;  // Points to '@'
+    const char *p = at_name_end;
+    while (p < pe && *p != '{') p++;
+
+    if (p >= pe || *p != '{') {
+        *p_ptr = p;
+        return;  // Malformed
+    }
+
+    const char *selector_end = p;
+    while (selector_end > selector_start && IS_WHITESPACE(*(selector_end - 1))) {
+        selector_end--;
+    }
+    VALUE selector = rb_utf8_str_new(selector_start, selector_end - selector_start);
+
+    p++;  // Skip opening {
+
+    // Find matching closing brace
+    const char *decl_start = p;
+    const char *decl_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
+    p = decl_end;
+
+    // Parse declarations
+    VALUE declarations = parse_declarations(decl_start, decl_end, ctx);
+
+    // Get rule ID and increment
+    int rule_id = ctx->rule_id_counter++;
+
+    // Create AtRule with declarations
+    VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
+    VALUE at_rule = rb_struct_new(cAtRule,
+        INT2FIX(rule_id),
+        selector,
+        declarations,  // Array of Declaration
+        Qnil,  // specificity
+        media_query_id_val  // media_query_id from parent context
+    );
+
+    // Add to rules array
+    rb_ary_push(ctx->rules_array, at_rule);
+
+    // Add to media index if in media query
+    if (!NIL_P(parent_media_sym)) {
+        VALUE rule_ids = rb_hash_aref(ctx->media_index, parent_media_sym);
+        if (NIL_P(rule_ids)) {
+            rule_ids = rb_ary_new();
+            rb_hash_aset(ctx->media_index, parent_media_sym, rule_ids);
+        }
+        rb_ary_push(rule_ids, INT2FIX(rule_id));
+    }
+
+    if (p < pe && *p == '}') p++;
+    *p_ptr = p;
+}
+
+/*
+ * Finish a complete top-level CSS rule block just found at its closing '}'
+ * (p points at that '}'; [selector_start, decl_start) is the selector text
+ * and [decl_start, p) is the body). Determines whether the body has nested
+ * selectors and either parses it as pure declarations (fast path, possibly
+ * split across comma-separated selectors) or recurses per comma-separated
+ * selector via parse_mixed_block (nested path). Does not modify p or reset
+ * selector_start/decl_start - the caller does that once this returns.
+ */
+static void finish_rule_block(ParserContext *ctx, const char *selector_start, const char *decl_start, const char *p,
+                               VALUE parent_selector, VALUE parent_rule_id, VALUE parent_media_sym, int parent_media_query_id) {
+    // We've found a complete CSS rule block - now determine if it has nesting
+    // Example: .parent { color: red; & .child { font-size: 14px; } }
+    //          ^selector_start    ^decl_start                    ^p (at })
+    BOOLEAN has_nesting = has_nested_selectors(decl_start, p);
+
+    // Get selector string
+    const char *sel_end = decl_start - 1;
+    while (sel_end > selector_start && IS_WHITESPACE(*(sel_end - 1))) {
+        sel_end--;
+    }
+
+    // Check for empty selector
+    if (ctx->check_invalid_selectors && sel_end <= selector_start) {
+        const char *css = RSTRING_PTR(ctx->css_string);
+        long error_pos = selector_start - css;
+
+        // Build keyword args hash
+        VALUE kwargs = rb_hash_new();
+        rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+        rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(error_pos));
+        rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern("invalid_selector")));
+
+        VALUE msg_str = rb_str_new_cstr("Invalid selector: empty selector");
+        VALUE argv[2] = {msg_str, kwargs};
+        VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+        rb_exc_raise(error);
+    }
+
+    if (!has_nesting) {
+        // FAST PATH: No nesting - parse as pure declarations
+        VALUE declarations = parse_declarations(decl_start, p, ctx);
+
+        // Split on commas to handle multi-selector rules
+        // Example: ".a, .b, .c { color: red; }" creates 3 separate rules
+        //           ^selector_start      ^sel_end
+        //              ^seg_start=seg (scanning for commas)
+
+        // Count selectors for selector list tracking
+        int selector_count = 1;
+        if (ctx->selector_lists_enabled) {
+            const char *count_ptr = selector_start;
+            while (count_ptr < sel_end) {
+                if (*count_ptr == ',') {
+                    selector_count++;
+                }
+                count_ptr++;
+            }
+        }
+
+        // Create selector list if enabled and multiple selectors
+        int list_id = -1;
+        VALUE rule_ids_array = Qnil;
+        if (ctx->selector_lists_enabled && selector_count > 1) {
+            list_id = ctx->next_selector_list_id++;
+            rule_ids_array = rb_ary_new();
+            rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
+        }
+
+        const char *seg_start = selector_start;
+        const char *seg = selector_start;
+
+        while (seg <= sel_end) {
+            if (seg == sel_end || *seg == ',') {  // At: ',' or end
+                // Trim segment
+                while (seg_start < seg && IS_WHITESPACE(*seg_start)) {
+                    seg_start++;
+                }
+
+                const char *seg_end_ptr = seg;
+                while (seg_end_ptr > seg_start && IS_WHITESPACE(*(seg_end_ptr - 1))) {
+                    seg_end_ptr--;
+                }
+
+                if (seg_end_ptr > seg_start) {
+                    // Check for invalid selectors
+                    if (ctx->check_invalid_selectors) {
+                        // Check if selector starts with combinator
+                        char first_char = *seg_start;
+                        if (first_char == '>' || first_char == '+' || first_char == '~') {
+                            const char *css = RSTRING_PTR(ctx->css_string);
+                            long error_pos = seg_start - css;
+
+                            char error_msg[256];
+                            snprintf(error_msg, sizeof(error_msg),
+                                   "Invalid selector: selector cannot start with combinator '%c'",
+                                   first_char);
+
+                            // Build keyword args hash
+                            VALUE kwargs = rb_hash_new();
+                            rb_hash_aset(kwargs, ID2SYM(rb_intern("css")), ctx->css_string);
+                            rb_hash_aset(kwargs, ID2SYM(rb_intern("pos")), LONG2NUM(error_pos));
+                            rb_hash_aset(kwargs, ID2SYM(rb_intern("type")), ID2SYM(rb_intern("invalid_selector")));
+
+                            VALUE msg_str = rb_str_new_cstr(error_msg);
+                            VALUE argv[2] = {msg_str, kwargs};
+                            VALUE error = rb_funcallv_kw(eParseError, rb_intern("new"), 2, argv, RB_PASS_KEYWORDS);
+                            rb_exc_raise(error);
+                        }
+                    }
+
+                    // Check for invalid selector syntax (whitelist validation)
+                    if (ctx->check_invalid_selector_syntax && !is_valid_selector(seg_start, seg_end_ptr)) {
+                        raise_parse_error_at(ctx, seg_start, "Invalid selector syntax: selector contains invalid characters", "invalid_selector_syntax");
+                    }
+
+                    VALUE selector = rb_utf8_str_new(seg_start, seg_end_ptr - seg_start);
+
+                    // Resolve against parent if nested
+                    VALUE resolved_selector;
+                    VALUE nesting_style_val;
+                    VALUE parent_id_val;
+
+                    if (!NIL_P(parent_selector)) {
+                        // This is a nested rule - resolve selector
+                        VALUE result = resolve_nested_selector(parent_selector, RSTRING_PTR(selector), RSTRING_LEN(selector));
+                        resolved_selector = rb_ary_entry(result, 0);
+                        nesting_style_val = rb_ary_entry(result, 1);
+                        parent_id_val = parent_rule_id;
+                    } else {
+                        // Top-level rule
+                        resolved_selector = selector;
+                        nesting_style_val = Qnil;
+                        parent_id_val = Qnil;
+                    }
+
+                    // Get rule ID and increment
+                    int rule_id = ctx->rule_id_counter++;
+
+                    // Determine selector_list_id value
+                    VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
+
+                    // Deep copy declarations for selector lists to avoid shared state
+                    // (principle of least surprise - modifying one rule shouldn't affect others)
+                    VALUE rule_declarations;
+                    if (list_id >= 0) {
+                        // Deep copy: both array and Declaration structs inside
+                        long decl_count = RARRAY_LEN(declarations);
+                        rule_declarations = rb_ary_new_capa(decl_count);
+                        for (long k = 0; k < decl_count; k++) {
+                            VALUE decl = rb_ary_entry(declarations, k);
+                            VALUE new_decl = rb_struct_new(cDeclaration,
+                                rb_struct_aref(decl, INT2FIX(DECL_PROPERTY)),
+                                rb_struct_aref(decl, INT2FIX(DECL_VALUE)),
+                                rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT))
+                            );
+                            rb_ary_push(rule_declarations, new_decl);
+                        }
+                    } else {
+                        rule_declarations = rb_ary_dup(declarations);
+                    }
+
+                    // Create Rule
+                    VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
+                    VALUE rule = rb_struct_new(cRule,
+                        INT2FIX(rule_id),
+                        resolved_selector,
+                        rule_declarations,
+                        Qnil,  // specificity
+                        parent_id_val,
+                        nesting_style_val,
+                        selector_list_id_val,
+                        media_query_id_val  // media_query_id from parent context
+                    );
+
+                    // Track rule in selector list if applicable
+                    if (list_id >= 0) {
+                        rb_ary_push(rule_ids_array, INT2FIX(rule_id));
+                    }
+
+                    // Mark that we have nesting (only set once)
+                    if (!ctx->has_nesting && !NIL_P(parent_id_val)) {
+                        ctx->has_nesting = 1;
+                    }
+
+                    rb_ary_push(ctx->rules_array, rule);
+
+                    // Update media index
+                    update_media_index(ctx, parent_media_sym, rule_id);
+                } else if (ctx->check_invalid_selector_syntax && selector_count > 1) {
+                    // Empty selector in comma-separated list (e.g., "h1, , h3")
+                    raise_parse_error_at(ctx, seg_start, "Invalid selector syntax: empty selector in comma-separated list", "invalid_selector_syntax");
+                }
+
+                seg_start = seg + 1;
+            }
+            seg++;
+        }
+    } else {
+        // NESTED PATH: Parse mixed declarations + nested rules
+        // For each comma-separated parent selector, parse the block with that parent
+        //
+        // Example: ".a, .b { color: red; & .child { font: 14px; } }"
+        //           ^selector_start ^sel_end
+        // Creates:
+        //   - .a with declarations [color: red]
+        //   - .a .child with declarations [font: 14px]
+        //   - .b with declarations [color: red]
+        //   - .b .child with declarations [font: 14px]
+
+        // Count selectors for selector list tracking
+        int selector_count = 1;
+        if (ctx->selector_lists_enabled) {
+            const char *count_ptr = selector_start;
+            while (count_ptr < sel_end) {
+                if (*count_ptr == ',') {
+                    selector_count++;
+                }
+                count_ptr++;
+            }
+        }
+
+        // Create selector list if enabled and multiple selectors
+        int list_id = -1;
+        VALUE rule_ids_array = Qnil;
+        if (ctx->selector_lists_enabled && selector_count > 1) {
+            list_id = ctx->next_selector_list_id++;
+            rule_ids_array = rb_ary_new();
+            rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
+        }
+
+        const char *seg_start = selector_start;
+        const char *seg = selector_start;
+
+        while (seg <= sel_end) {
+            if (seg == sel_end || *seg == ',') {  // At: ',' or end
+                // Trim segment
+                while (seg_start < seg && IS_WHITESPACE(*seg_start)) {
+                    seg_start++;
+                }
+
+                const char *seg_end_ptr = seg;
+                while (seg_end_ptr > seg_start && IS_WHITESPACE(*(seg_end_ptr - 1))) {
+                    seg_end_ptr--;
+                }
+
+                if (seg_end_ptr > seg_start) {
+                    VALUE current_selector = rb_utf8_str_new(seg_start, seg_end_ptr - seg_start);
+
+                    // Resolve against parent if we're already nested
+                    VALUE resolved_current;
+                    VALUE current_nesting_style;
+                    VALUE current_parent_id;
+
+                    if (!NIL_P(parent_selector)) {
+                        VALUE result = resolve_nested_selector(parent_selector, RSTRING_PTR(current_selector), RSTRING_LEN(current_selector));
+                        resolved_current = rb_ary_entry(result, 0);
+                        current_nesting_style = rb_ary_entry(result, 1);
+                        current_parent_id = parent_rule_id;
+                    } else {
+                        resolved_current = current_selector;
+                        current_nesting_style = Qnil;
+                        current_parent_id = Qnil;
+                    }
+
+                    // Get rule ID for current selector (increment to reserve it)
+                    int current_rule_id = ctx->rule_id_counter++;
+
+                    // Reserve parent's position in rules array with placeholder
+                    // This ensures parent comes before nested rules in array order (per W3C spec)
+                    long parent_position = RARRAY_LEN(ctx->rules_array);
+                    rb_ary_push(ctx->rules_array, Qnil);
+
+                    // Parse mixed block (declarations + nested selectors)
+                    // Nested rules will be added AFTER the placeholder
+                    ctx->depth++;
+                    VALUE parent_declarations = parse_mixed_block(ctx, decl_start, p,
+                                                                 resolved_current, INT2FIX(current_rule_id), parent_media_sym, parent_media_query_id);
+                    ctx->depth--;
+
+                    // Determine selector_list_id value
+                    VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
+
+                    // Create parent rule and replace placeholder
+                    // Always create the rule (even if empty) to avoid edge cases
+                    VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
+                    VALUE rule = rb_struct_new(cRule,
+                        INT2FIX(current_rule_id),
+                        resolved_current,
+                        parent_declarations,
+                        Qnil,  // specificity
+                        current_parent_id,
+                        current_nesting_style,
+                        selector_list_id_val,
+                        media_query_id_val  // media_query_id from parent context
+                    );
+
+                    // Track rule in selector list if applicable
+                    if (list_id >= 0) {
+                        rb_ary_push(rule_ids_array, INT2FIX(current_rule_id));
+                    }
+
+                    // Mark that we have nesting (only set once)
+                    if (!ctx->has_nesting && !NIL_P(current_parent_id)) {
+                        ctx->has_nesting = 1;
+                    }
+
+                    // Replace placeholder with actual rule - just pointer assignment, fast!
+                    rb_ary_store(ctx->rules_array, parent_position, rule);
+                    update_media_index(ctx, parent_media_sym, current_rule_id);
+                }
+
+                seg_start = seg + 1;
+            }
+            seg++;
+        }
+    }
+}
+
 /*
  * Parse CSS recursively with media query context and optional parent selector for nesting
  *
@@ -1419,142 +2218,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
         // Check for @media at-rule (only at depth 0)
         if (RB_UNLIKELY(brace_depth == 0 && p + 6 < pe && *p == '@' &&
             strncmp(p + 1, "media", 5) == 0 && IS_WHITESPACE(p[6]))) {
-            p += 6;  // Skip "@media"
-
-            // Skip whitespace
-            while (p < pe && IS_WHITESPACE(*p)) p++;
-
-            // Find media query (up to opening brace)
-            const char *mq_start = p;
-            while (p < pe && *p != '{') p++;
-            const char *mq_end = p;
-
-            // Trim
-            trim_trailing(mq_start, &mq_end);
-
-            if (p >= pe || *p != '{') {
-                continue;  // Malformed
-            }
-
-            // Split comma-separated media queries (e.g., "screen, print" -> ["screen", "print"])
-            // Per W3C spec, comma acts as logical OR - each query is independent
-            VALUE media_query_ids = rb_ary_new();
-
-            const char *query_start = mq_start;
-            for (const char *p_comma = mq_start; p_comma <= mq_end; p_comma++) {
-                if (p_comma == mq_end || *p_comma == ',') {
-                    const char *query_end = p_comma;
-
-                    // Trim whitespace from this query
-                    while (query_start < query_end && IS_WHITESPACE(*query_start)) query_start++;
-                    while (query_end > query_start && IS_WHITESPACE(*(query_end - 1))) query_end--;
-
-                    if (query_start < query_end) {
-                        // Parse this individual media query
-                        const char *mq_ptr = query_start;
-                        VALUE media_type;
-                        VALUE media_conditions = Qnil;
-
-                        if (*mq_ptr == '(') {
-                            // Starts with '(' - just conditions, type defaults to :all
-                            media_type = ID2SYM(rb_intern("all"));
-                            media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
-                        } else {
-                            // Extract media type (first word, stopping at whitespace, comma, or '(')
-                            const char *type_start = mq_ptr;
-                            while (mq_ptr < query_end && !IS_WHITESPACE(*mq_ptr) && *mq_ptr != '(') mq_ptr++;
-                            VALUE type_str = rb_utf8_str_new(type_start, mq_ptr - type_start);
-                            media_type = ID2SYM(rb_intern_str(type_str));
-
-                            // Skip whitespace and "and" keyword if present
-                            while (mq_ptr < query_end && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
-                            if (mq_ptr + 3 <= query_end && strncmp(mq_ptr, "and", 3) == 0) {
-                                mq_ptr += 3;
-                                while (mq_ptr < query_end && IS_WHITESPACE(*mq_ptr)) mq_ptr++;
-                            }
-
-                            // Rest is conditions
-                            if (mq_ptr < query_end) {
-                                media_conditions = rb_utf8_str_new(mq_ptr, query_end - mq_ptr);
-                            }
-                        }
-
-                        // Create MediaQuery object for this query
-                        VALUE media_query = rb_struct_new(cMediaQuery,
-                            INT2FIX(ctx->media_query_id_counter),
-                            media_type,
-                            media_conditions
-                        );
-                        rb_ary_push(ctx->media_queries, media_query);
-                        rb_ary_push(media_query_ids, INT2FIX(ctx->media_query_id_counter));
-                        ctx->media_query_id_counter++;
-                    }
-
-                    // Move to start of next query
-                    query_start = p_comma + 1;
-                }
-            }
-
-            // If multiple queries, track them as a list for serialization
-            int media_query_list_id = -1;
-            if (RARRAY_LEN(media_query_ids) > 1) {
-                media_query_list_id = ctx->next_media_query_list_id;
-                rb_hash_aset(ctx->media_query_lists, INT2FIX(media_query_list_id), media_query_ids);
-                ctx->next_media_query_list_id++;
-            }
-
-            // Use first query ID as the primary one for rules in this block
-            int current_media_query_id = FIX2INT(rb_ary_entry(media_query_ids, 0));
-
-            // Handle nested @media by combining with parent
-            if (parent_media_query_id >= 0) {
-                VALUE parent_mq = rb_ary_entry(ctx->media_queries, parent_media_query_id);
-                VALUE parent_type = rb_struct_aref(parent_mq, INT2FIX(1)); // type field
-                VALUE parent_conditions = rb_struct_aref(parent_mq, INT2FIX(2)); // conditions field
-
-                // Get child media query (first one in the list)
-                VALUE child_mq = rb_ary_entry(ctx->media_queries, current_media_query_id);
-                VALUE child_conditions = rb_struct_aref(child_mq, INT2FIX(2)); // conditions field
-
-                // Combined type is parent's type (outermost wins, child type ignored)
-                VALUE combined_type = parent_type;
-                VALUE combined_conditions;
-
-                if (!NIL_P(parent_conditions) && !NIL_P(child_conditions)) {
-                    combined_conditions = rb_sprintf("%"PRIsVALUE" and %"PRIsVALUE, parent_conditions, child_conditions);
-                } else if (!NIL_P(parent_conditions)) {
-                    combined_conditions = parent_conditions;
-                } else {
-                    combined_conditions = child_conditions;
-                }
-
-                VALUE combined_mq = rb_struct_new(cMediaQuery,
-                    INT2FIX(ctx->media_query_id_counter),
-                    combined_type,
-                    combined_conditions
-                );
-                rb_ary_push(ctx->media_queries, combined_mq);
-                current_media_query_id = ctx->media_query_id_counter;
-                ctx->media_query_id_counter++;
-            }
-
-            // For backwards compat, also create symbol (will be removed later)
-            VALUE child_media_sym = intern_media_query_safe(ctx, mq_start, mq_end - mq_start);
-            VALUE combined_media_sym = combine_media_queries(parent_media_sym, child_media_sym);
-
-            p++;  // Skip opening {
-
-            // Find matching closing brace
-            const char *block_start = p;
-            const char *block_end = find_matching_brace(p, pe);
-            p = block_end;
-
-            // Recursively parse @media block with new media query context
-            ctx->depth++;
-            parse_css_recursive(ctx, block_start, block_end, combined_media_sym, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID, current_media_query_id);
-            ctx->depth--;
-
-            if (p < pe && *p == '}') p++;
+            handle_media_at_rule(ctx, &p, pe, parent_media_sym, parent_media_query_id);
             continue;
         }
 
@@ -1573,173 +2237,45 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
             long at_name_len = at_name_end - at_start;
 
             // Check if this is a conditional group rule
-            int is_conditional_group =
+            BOOLEAN is_conditional_group =
                 (at_name_len == 8 && strncmp(at_start, "supports", 8) == 0) ||
                 (at_name_len == 5 && strncmp(at_start, "layer", 5) == 0) ||
                 (at_name_len == 9 && strncmp(at_start, "container", 9) == 0) ||
                 (at_name_len == 5 && strncmp(at_start, "scope", 5) == 0);
 
             if (is_conditional_group) {
-                // Skip to opening brace
-                p = at_name_end;
-                while (p < pe && *p != '{') p++;
-
-                if (p >= pe || *p != '{') {
-                    continue;  // Malformed
-                }
-
-                p++;  // Skip opening {
-
-                // Find matching closing brace
-                const char *block_start = p;
-                const char *block_end = find_matching_brace(p, pe);
-                p = block_end;
-
-                // Recursively parse block content (preserve parent media context)
-                ctx->depth++;
-                parse_css_recursive(ctx, block_start, block_end, parent_media_sym, parent_selector, parent_rule_id, parent_media_query_id);
-                ctx->depth--;
-
-                if (p < pe && *p == '}') p++;
+                handle_conditional_group_at_rule(ctx, &p, pe, at_start, at_name_end, at_name_len,
+                                                  parent_media_sym, parent_selector, parent_rule_id, parent_media_query_id);
                 continue;
             }
 
             // Check for @keyframes (contains <rule-list>)
             // TODO: Test perf gains by using RB_UNLIKELY(is_keyframes) wrapper
-            int is_keyframes =
+            BOOLEAN is_keyframes =
                 (at_name_len == 9 && strncmp(at_start, "keyframes", 9) == 0) ||
                 (at_name_len == 17 && strncmp(at_start, "-webkit-keyframes", 17) == 0) ||
                 (at_name_len == 13 && strncmp(at_start, "-moz-keyframes", 13) == 0);
 
             if (is_keyframes) {
-                // Build full selector string: "@keyframes fade"
-                const char *selector_start = p;  // Points to '@'
-                p = at_name_end;
-                while (p < pe && *p != '{') p++;
-
-                if (p >= pe || *p != '{') {
-                    continue;  // Malformed
-                }
-
-                const char *selector_end = p;
-                while (selector_end > selector_start && IS_WHITESPACE(*(selector_end - 1))) {
-                    selector_end--;
-                }
-                VALUE selector = rb_utf8_str_new(selector_start, selector_end - selector_start);
-
-                p++;  // Skip opening {
-
-                // Find matching closing brace
-                const char *block_start = p;
-                const char *block_end = find_matching_brace(p, pe);
-                p = block_end;
-
-                // Parse keyframe blocks as rules (from/to/0%/50% etc)
-                ParserContext nested_ctx = {
-                    .rules_array = rb_ary_new(),
-                    .media_index = rb_hash_new(),
-                    .selector_lists = rb_hash_new(),
-                    .imports_array = rb_ary_new(),
-                    .rule_id_counter = 0,
-                    .next_selector_list_id = 0,
-                    .media_query_count = 0,
-                    .media_cache = NULL,
-                    .has_nesting = 0,
-                    .selector_lists_enabled = ctx->selector_lists_enabled,
-                    .depth = 0
-                };
-                parse_css_recursive(&nested_ctx, block_start, block_end, NO_PARENT_MEDIA, NO_PARENT_SELECTOR, NO_PARENT_RULE_ID, NO_MEDIA_QUERY_ID);
-
-                // Get rule ID and increment
-                int rule_id = ctx->rule_id_counter++;
-
-                // Create AtRule with nested rules
-                VALUE at_rule = rb_struct_new(cAtRule,
-                    INT2FIX(rule_id),
-                    selector,
-                    nested_ctx.rules_array,  // Array of Rule (keyframe blocks)
-                    Qnil,  // specificity
-                    Qnil   // media_query_id
-                );
-
-                // Add to rules array
-                rb_ary_push(ctx->rules_array, at_rule);
-
-                // Add to media index if in media query
-                if (!NIL_P(parent_media_sym)) {
-                    VALUE rule_ids = rb_hash_aref(ctx->media_index, parent_media_sym);
-                    if (NIL_P(rule_ids)) {
-                        rule_ids = rb_ary_new();
-                        rb_hash_aset(ctx->media_index, parent_media_sym, rule_ids);
-                    }
-                    rb_ary_push(rule_ids, INT2FIX(rule_id));
-                }
-
-                if (p < pe && *p == '}') p++;
+                handle_keyframes_at_rule(ctx, &p, pe, at_name_end, parent_media_sym, parent_media_query_id);
                 continue;
             }
 
             // Check for @font-face (contains <declaration-list>)
-            int is_font_face = (at_name_len == 9 && strncmp(at_start, "font-face", 9) == 0);
+            BOOLEAN is_font_face = (at_name_len == 9 && strncmp(at_start, "font-face", 9) == 0);
 
             if (is_font_face) {
-                // Build selector string: "@font-face"
-                const char *selector_start = p;  // Points to '@'
-                p = at_name_end;
-                while (p < pe && *p != '{') p++;
-
-                if (p >= pe || *p != '{') {
-                    continue;  // Malformed
-                }
-
-                const char *selector_end = p;
-                while (selector_end > selector_start && IS_WHITESPACE(*(selector_end - 1))) {
-                    selector_end--;
-                }
-                VALUE selector = rb_utf8_str_new(selector_start, selector_end - selector_start);
-
-                p++;  // Skip opening {
-
-                // Find matching closing brace
-                const char *decl_start = p;
-                const char *decl_end = find_matching_brace(p, pe);
-                p = decl_end;
-
-                // Parse declarations
-                VALUE declarations = parse_declarations(decl_start, decl_end, ctx);
-
-                // Get rule ID and increment
-                int rule_id = ctx->rule_id_counter++;
-
-                // Create AtRule with declarations
-                VALUE at_rule = rb_struct_new(cAtRule,
-                    INT2FIX(rule_id),
-                    selector,
-                    declarations,  // Array of Declaration
-                    Qnil,  // specificity
-                    Qnil   // media_query_id
-                );
-
-                // Add to rules array
-                rb_ary_push(ctx->rules_array, at_rule);
-
-                // Add to media index if in media query
-                if (!NIL_P(parent_media_sym)) {
-                    VALUE rule_ids = rb_hash_aref(ctx->media_index, parent_media_sym);
-                    if (NIL_P(rule_ids)) {
-                        rule_ids = rb_ary_new();
-                        rb_hash_aset(ctx->media_index, parent_media_sym, rule_ids);
-                    }
-                    rb_ary_push(rule_ids, INT2FIX(rule_id));
-                }
-
-                if (p < pe && *p == '}') p++;
+                handle_font_face_at_rule(ctx, &p, pe, at_name_end, parent_media_sym, parent_media_query_id);
                 continue;
             }
         }
 
         // Opening brace
         if (*p == '{') {
+            // Check for empty selector (opening brace with no selector before it)
+            if (ctx->check_invalid_selectors && brace_depth == 0 && selector_start == NULL) {
+                raise_parse_error_at(ctx, p, "Invalid selector: empty selector", "invalid_selector");
+            }
             if (brace_depth == 0 && selector_start != NULL) {
                 decl_start = p + 1;
             }
@@ -1752,262 +2288,8 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
         if (*p == '}') {
             brace_depth--;
             if (brace_depth == 0 && selector_start != NULL && decl_start != NULL) {
-                // We've found a complete CSS rule block - now determine if it has nesting
-                // Example: .parent { color: red; & .child { font-size: 14px; } }
-                //          ^selector_start    ^decl_start                    ^p (at })
-                int has_nesting = has_nested_selectors(decl_start, p);
-
-                // Get selector string
-                const char *sel_end = decl_start - 1;
-                while (sel_end > selector_start && IS_WHITESPACE(*(sel_end - 1))) {
-                    sel_end--;
-                }
-
-                if (!has_nesting) {
-                    // FAST PATH: No nesting - parse as pure declarations
-                    VALUE declarations = parse_declarations(decl_start, p, ctx);
-
-                    // Split on commas to handle multi-selector rules
-                    // Example: ".a, .b, .c { color: red; }" creates 3 separate rules
-                    //           ^selector_start      ^sel_end
-                    //              ^seg_start=seg (scanning for commas)
-
-                    // Count selectors for selector list tracking
-                    int selector_count = 1;
-                    if (ctx->selector_lists_enabled) {
-                        const char *count_ptr = selector_start;
-                        while (count_ptr < sel_end) {
-                            if (*count_ptr == ',') {
-                                selector_count++;
-                            }
-                            count_ptr++;
-                        }
-                    }
-
-                    // Create selector list if enabled and multiple selectors
-                    int list_id = -1;
-                    VALUE rule_ids_array = Qnil;
-                    if (ctx->selector_lists_enabled && selector_count > 1) {
-                        list_id = ctx->next_selector_list_id++;
-                        rule_ids_array = rb_ary_new();
-                        rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
-                    }
-
-                    const char *seg_start = selector_start;
-                    const char *seg = selector_start;
-
-                    while (seg <= sel_end) {
-                        if (seg == sel_end || *seg == ',') {  // At: ',' or end
-                            // Trim segment
-                            while (seg_start < seg && IS_WHITESPACE(*seg_start)) {
-                                seg_start++;
-                            }
-
-                            const char *seg_end_ptr = seg;
-                            while (seg_end_ptr > seg_start && IS_WHITESPACE(*(seg_end_ptr - 1))) {
-                                seg_end_ptr--;
-                            }
-
-                            if (seg_end_ptr > seg_start) {
-                                VALUE selector = rb_utf8_str_new(seg_start, seg_end_ptr - seg_start);
-
-                                // Resolve against parent if nested
-                                VALUE resolved_selector;
-                                VALUE nesting_style_val;
-                                VALUE parent_id_val;
-
-                                if (!NIL_P(parent_selector)) {
-                                    // This is a nested rule - resolve selector
-                                    VALUE result = resolve_nested_selector(parent_selector, RSTRING_PTR(selector), RSTRING_LEN(selector));
-                                    resolved_selector = rb_ary_entry(result, 0);
-                                    nesting_style_val = rb_ary_entry(result, 1);
-                                    parent_id_val = parent_rule_id;
-                                } else {
-                                    // Top-level rule
-                                    resolved_selector = selector;
-                                    nesting_style_val = Qnil;
-                                    parent_id_val = Qnil;
-                                }
-
-                                // Get rule ID and increment
-                                int rule_id = ctx->rule_id_counter++;
-
-                                // Determine selector_list_id value
-                                VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
-
-                                // Deep copy declarations for selector lists to avoid shared state
-                                // (principle of least surprise - modifying one rule shouldn't affect others)
-                                VALUE rule_declarations;
-                                if (list_id >= 0) {
-                                    // Deep copy: both array and Declaration structs inside
-                                    long decl_count = RARRAY_LEN(declarations);
-                                    rule_declarations = rb_ary_new_capa(decl_count);
-                                    for (long k = 0; k < decl_count; k++) {
-                                        VALUE decl = rb_ary_entry(declarations, k);
-                                        VALUE new_decl = rb_struct_new(cDeclaration,
-                                            rb_struct_aref(decl, INT2FIX(DECL_PROPERTY)),
-                                            rb_struct_aref(decl, INT2FIX(DECL_VALUE)),
-                                            rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT))
-                                        );
-                                        rb_ary_push(rule_declarations, new_decl);
-                                    }
-                                } else {
-                                    rule_declarations = rb_ary_dup(declarations);
-                                }
-
-                                // Create Rule
-                                VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
-                                VALUE rule = rb_struct_new(cRule,
-                                    INT2FIX(rule_id),
-                                    resolved_selector,
-                                    rule_declarations,
-                                    Qnil,  // specificity
-                                    parent_id_val,
-                                    nesting_style_val,
-                                    selector_list_id_val,
-                                    media_query_id_val  // media_query_id from parent context
-                                );
-
-                                // Track rule in selector list if applicable
-                                if (list_id >= 0) {
-                                    rb_ary_push(rule_ids_array, INT2FIX(rule_id));
-                                }
-
-                                // Mark that we have nesting (only set once)
-                                if (!ctx->has_nesting && !NIL_P(parent_id_val)) {
-                                    ctx->has_nesting = 1;
-                                }
-
-                                rb_ary_push(ctx->rules_array, rule);
-
-                                // Update media index
-                                update_media_index(ctx, parent_media_sym, rule_id);
-                            }
-
-                            seg_start = seg + 1;
-                        }
-                        seg++;
-                    }
-                } else {
-                    // NESTED PATH: Parse mixed declarations + nested rules
-                    // For each comma-separated parent selector, parse the block with that parent
-                    //
-                    // Example: ".a, .b { color: red; & .child { font: 14px; } }"
-                    //           ^selector_start ^sel_end
-                    // Creates:
-                    //   - .a with declarations [color: red]
-                    //   - .a .child with declarations [font: 14px]
-                    //   - .b with declarations [color: red]
-                    //   - .b .child with declarations [font: 14px]
-
-                    // Count selectors for selector list tracking
-                    int selector_count = 1;
-                    if (ctx->selector_lists_enabled) {
-                        const char *count_ptr = selector_start;
-                        while (count_ptr < sel_end) {
-                            if (*count_ptr == ',') {
-                                selector_count++;
-                            }
-                            count_ptr++;
-                        }
-                    }
-
-                    // Create selector list if enabled and multiple selectors
-                    int list_id = -1;
-                    VALUE rule_ids_array = Qnil;
-                    if (ctx->selector_lists_enabled && selector_count > 1) {
-                        list_id = ctx->next_selector_list_id++;
-                        rule_ids_array = rb_ary_new();
-                        rb_hash_aset(ctx->selector_lists, INT2FIX(list_id), rule_ids_array);
-                    }
-
-                    const char *seg_start = selector_start;
-                    const char *seg = selector_start;
-
-                    while (seg <= sel_end) {
-                        if (seg == sel_end || *seg == ',') {  // At: ',' or end
-                            // Trim segment
-                            while (seg_start < seg && IS_WHITESPACE(*seg_start)) {
-                                seg_start++;
-                            }
-
-                            const char *seg_end_ptr = seg;
-                            while (seg_end_ptr > seg_start && IS_WHITESPACE(*(seg_end_ptr - 1))) {
-                                seg_end_ptr--;
-                            }
-
-                            if (seg_end_ptr > seg_start) {
-                                VALUE current_selector = rb_utf8_str_new(seg_start, seg_end_ptr - seg_start);
-
-                                // Resolve against parent if we're already nested
-                                VALUE resolved_current;
-                                VALUE current_nesting_style;
-                                VALUE current_parent_id;
-
-                                if (!NIL_P(parent_selector)) {
-                                    VALUE result = resolve_nested_selector(parent_selector, RSTRING_PTR(current_selector), RSTRING_LEN(current_selector));
-                                    resolved_current = rb_ary_entry(result, 0);
-                                    current_nesting_style = rb_ary_entry(result, 1);
-                                    current_parent_id = parent_rule_id;
-                                } else {
-                                    resolved_current = current_selector;
-                                    current_nesting_style = Qnil;
-                                    current_parent_id = Qnil;
-                                }
-
-                                // Get rule ID for current selector (increment to reserve it)
-                                int current_rule_id = ctx->rule_id_counter++;
-
-                                // Reserve parent's position in rules array with placeholder
-                                // This ensures parent comes before nested rules in array order (per W3C spec)
-                                long parent_position = RARRAY_LEN(ctx->rules_array);
-                                rb_ary_push(ctx->rules_array, Qnil);
-
-                                // Parse mixed block (declarations + nested selectors)
-                                // Nested rules will be added AFTER the placeholder
-                                ctx->depth++;
-                                VALUE parent_declarations = parse_mixed_block(ctx, decl_start, p,
-                                                                             resolved_current, INT2FIX(current_rule_id), parent_media_sym, parent_media_query_id);
-                                ctx->depth--;
-
-                                // Determine selector_list_id value
-                                VALUE selector_list_id_val = (list_id >= 0) ? INT2FIX(list_id) : Qnil;
-
-                                // Create parent rule and replace placeholder
-                                // Always create the rule (even if empty) to avoid edge cases
-                                VALUE media_query_id_val = (parent_media_query_id >= 0) ? INT2FIX(parent_media_query_id) : Qnil;
-                                VALUE rule = rb_struct_new(cRule,
-                                    INT2FIX(current_rule_id),
-                                    resolved_current,
-                                    parent_declarations,
-                                    Qnil,  // specificity
-                                    current_parent_id,
-                                    current_nesting_style,
-                                    selector_list_id_val,
-                                    media_query_id_val  // media_query_id from parent context
-                                );
-
-                                // Track rule in selector list if applicable
-                                if (list_id >= 0) {
-                                    rb_ary_push(rule_ids_array, INT2FIX(current_rule_id));
-                                }
-
-                                // Mark that we have nesting (only set once)
-                                if (!ctx->has_nesting && !NIL_P(current_parent_id)) {
-                                    ctx->has_nesting = 1;
-                                }
-
-                                // Replace placeholder with actual rule - just pointer assignment, fast!
-                                rb_ary_store(ctx->rules_array, parent_position, rule);
-                                update_media_index(ctx, parent_media_sym, current_rule_id);
-                            }
-
-                            seg_start = seg + 1;
-                        }
-                        seg++;
-                    }
-                }
-
+                finish_rule_block(ctx, selector_start, decl_start, p,
+                                   parent_selector, parent_rule_id, parent_media_sym, parent_media_query_id);
                 selector_start = NULL;
                 decl_start = NULL;
             }
@@ -2023,6 +2305,11 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
         p++;
     }
+
+    // Check for unclosed blocks at end of parsing
+    if (ctx->check_unclosed_blocks && brace_depth > 0) {
+        rb_raise(eParseError, "Unclosed block: missing closing brace");
+    }
 }
 
 /*
@@ -2056,13 +2343,48 @@ VALUE parse_css_new_impl(VALUE css_string, VALUE parser_options, int rule_id_off
 
     // Read parser options
     VALUE selector_lists_opt = rb_hash_aref(parser_options, ID2SYM(rb_intern("selector_lists")));
-    int selector_lists_enabled = (NIL_P(selector_lists_opt) || RTEST(selector_lists_opt)) ? 1 : 0;
+    BOOLEAN selector_lists_enabled = (NIL_P(selector_lists_opt) || RTEST(selector_lists_opt)) ? 1 : 0;
 
     // URL conversion options
     VALUE base_uri = rb_hash_aref(parser_options, ID2SYM(rb_intern("base_uri")));
     VALUE absolute_paths_opt = rb_hash_aref(parser_options, ID2SYM(rb_intern("absolute_paths")));
     VALUE uri_resolver = rb_hash_aref(parser_options, ID2SYM(rb_intern("uri_resolver")));
-    int absolute_paths = RTEST(absolute_paths_opt) ? 1 : 0;
+    BOOLEAN absolute_paths = RTEST(absolute_paths_opt) ? 1 : 0;
+
+    // Parse error options
+    VALUE raise_parse_errors_opt = rb_hash_aref(parser_options, ID2SYM(rb_intern("raise_parse_errors")));
+    BOOLEAN check_empty_values = 0;
+    BOOLEAN check_malformed_declarations = 0;
+    BOOLEAN check_invalid_selectors = 0;
+    BOOLEAN check_invalid_selector_syntax = 0;
+    BOOLEAN check_malformed_at_rules = 0;
+    BOOLEAN check_unclosed_blocks = 0;
+
+    if (RTEST(raise_parse_errors_opt)) {
+        if (TYPE(raise_parse_errors_opt) == T_HASH) {
+            // Hash of specific error types
+            VALUE empty_values_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("empty_values")));
+            VALUE malformed_declarations_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("malformed_declarations")));
+            VALUE invalid_selectors_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("invalid_selectors")));
+            VALUE invalid_selector_syntax_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("invalid_selector_syntax")));
+            VALUE malformed_at_rules_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("malformed_at_rules")));
+            VALUE unclosed_blocks_opt = rb_hash_aref(raise_parse_errors_opt, ID2SYM(rb_intern("unclosed_blocks")));
+            check_empty_values = RTEST(empty_values_opt) ? 1 : 0;
+            check_malformed_declarations = RTEST(malformed_declarations_opt) ? 1 : 0;
+            check_invalid_selectors = RTEST(invalid_selectors_opt) ? 1 : 0;
+            check_invalid_selector_syntax = RTEST(invalid_selector_syntax_opt) ? 1 : 0;
+            check_malformed_at_rules = RTEST(malformed_at_rules_opt) ? 1 : 0;
+            check_unclosed_blocks = RTEST(unclosed_blocks_opt) ? 1 : 0;
+        } else {
+            // true - enable all checks
+            check_empty_values = 1;
+            check_malformed_declarations = 1;
+            check_invalid_selectors = 1;
+            check_invalid_selector_syntax = 1;
+            check_malformed_at_rules = 1;
+            check_unclosed_blocks = 1;
+        }
+    }
 
     const char *css = RSTRING_PTR(css_string);
     const char *pe = css + RSTRING_LEN(css_string);
@@ -2107,7 +2429,6 @@ VALUE parse_css_new_impl(VALUE css_string, VALUE parser_options, int rule_id_off
     ctx.media_query_id_counter = 0;  // Start from 0
     ctx.next_media_query_list_id = 0;  // Start from 0
     ctx.media_query_count = 0;
-    ctx.media_cache = NULL;  // Removed - no perf benefit
     ctx.has_nesting = 0;  // Will be set to 1 if any nested rules are created
     ctx.selector_lists_enabled = selector_lists_enabled;
     ctx.depth = 0;  // Start at depth 0
@@ -2115,6 +2436,14 @@ VALUE parse_css_new_impl(VALUE css_string, VALUE parser_options, int rule_id_off
     ctx.base_uri = base_uri;
     ctx.uri_resolver = uri_resolver;
     ctx.absolute_paths = absolute_paths;
+    // Parse error options
+    ctx.css_string = css_string;
+    ctx.check_empty_values = check_empty_values;
+    ctx.check_malformed_declarations = check_malformed_declarations;
+    ctx.check_invalid_selectors = check_invalid_selectors;
+    ctx.check_invalid_selector_syntax = check_invalid_selector_syntax;
+    ctx.check_malformed_at_rules = check_malformed_at_rules;
+    ctx.check_unclosed_blocks = check_unclosed_blocks;
 
     // Parse CSS (top-level, no parent context)
     DEBUG_PRINTF("[PARSE] Starting parse_css_recursive from: %.80s\n", p);