cataract 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90e5adcec05553f73e5829b769d010ecda9ca5bf5eb1b2cc621b74707758c913
-  data.tar.gz: 4a82a843a72f2cc3c944798af3b7e7a8271b5ad696c1ed53247854d5ecdda7bb
+  metadata.gz: 898883ee4a30ccd34c034b4799e7a43eccae7f79693a4309d7ac7ef130f21840
+  data.tar.gz: 511eaf6d4a9fd1f1a601a999f496bc3493900daa2696d20bc1a6b97eaff60eae
 SHA512:
-  metadata.gz: afb9718d653c7bc0c905eb3d273afec8a364ae37de2952ea3285ecf3ef7f5ff29b40887348ef3646adedfab0baeff873211a883750e7c9b992f3e6a25b14cbb0
-  data.tar.gz: c40ba4cefa95024f34c7d9306d93ad07b8f448e847c51231381fa83833f2b97e314e5fbab9d7fb2a8edd1fe45fea0760c6db514c79225829e397c339fd5951a6
+  metadata.gz: 59f87ff83a95fecb4e508a71e3055d8ebc53c23ad2d1316358e4a9e53ff8532c66b5686611e1706d6d95f1309428eda2e2df3b1884cbcb8d318dc866a256920b
+  data.tar.gz: 85eb22a3be35e25d7cfd01fcbb2bd9148411e3cb4ee49ccfd808f57ec17a6a8c95c1dc56b29cb563cc9cc7523fbacfc4083a5953dcf3010c6cb14c872a48872c

data/.rubocop.yml

@@ -178,4 +178,5 @@ Cataract/BanAssertIncludes:
     - 'test/color/**/*.rb'
     - 'test/test_benchmark_doc_generator.rb'
     - 'test/test_speedup_calculator.rb'
+    - 'test/test_parse_errors.rb'  # Parse error tests check error messages with assert_match
     - 'test/support/**/*'  # Support files define assert_contains which uses assert_includes internally

data/BENCHMARKS.md

@@ -20,17 +20,35 @@ Time to parse CSS into internal data structures
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Small CSS (64 lines, 1.0KB) | 37.4K i/s | 3.25K i/s | 13.43K i/s |
-| Medium CSS with @media (139 lines, 1.6KB) | 34.71K i/s | 2.04K i/s | 9.15K i/s |
-| Selector lists (3500 lines, 62.5KB, 500 lists) | 471.8 i/s | 56.7 i/s | 214.1 i/s |
+| Small CSS (64 lines, 1.0KB) | 37.27K i/s | 3.32K i/s | 13.48K i/s |
+| Medium CSS with @media (139 lines, 1.6KB) | 34.66K i/s | 2.06K i/s | 8.94K i/s |
+| Selector lists (3500 lines, 62.5KB, 500 lists) | 485.7 i/s | 55.7 i/s | 213.6 i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 12.76x faster (avg) |
-| Native vs Pure (YJIT) | 2.99x faster (avg) |
-| YJIT impact on Pure Ruby | 4.22x faster (avg) |
+| Native vs Pure (no YJIT) | 14.4x faster (avg) |
+| Native vs Pure (YJIT) | 3.38x faster (avg) |
+| YJIT impact on Pure Ruby | 4.23x faster (avg) |
+
+### Parse Error Checking Overhead
+
+Parse error detection can be enabled with `raise_parse_errors: true`. This compares performance impact:
+
+| Configuration | Native | Pure (no YJIT) | Pure (YJIT) |
+|---------------|--------|----------------|-------------|
+| Medium CSS (139 lines) - no error checking | 35.18K i/s | 2.07K i/s | 9.05K i/s |
+| Medium CSS (139 lines) - with error checking | 34.84K i/s | 1.9K i/s | 8.19K i/s |
+
+**Overhead Analysis:**
+
+
+| Implementation | Overhead |
+|----------------|----------|
+| Native | ~0% (within noise) |
+| Pure (no YJIT) | 8.9% slower |
+| Pure (YJIT) | 10.4% slower |
 
 ---
 

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [ Unreleased ]
+## [Unreleased]
+
+## [0.2.5 - 2025-11-25]
+
+- Feature: Parse error detection with `raise_parse_errors` option - validates CSS structure and raises `ParseError` exceptions for malformed input with line/column tracking
+- Feature: Granular error control - enable specific checks (empty values, malformed declarations, invalid selectors, invalid selector syntax, malformed at-rules, unclosed blocks)
+- Feature: Type safety validation for C extension - `Stylesheet.parse` and `Stylesheet.new` now validate argument types and raise clear `TypeError` instead of segfaulting
+- Feature: Selector syntax validation using whitelist approach - catches invalid characters and sequences like `..class`, `##id`, `???`
+- Fix: `add_block` with multiple `@import` statements now correctly tracks media type for each import instead of reusing the first import's media context
+- Performance: Parse error checking adds minimal overhead (effectively zero for C/Pure Ruby, ~5% for Pure Ruby with YJIT)
+- Testing: Fuzzer corpus enhanced with invalid CSS patterns for crash testing
 
 ## [0.2.4 - 2025-11-23]
 - MediaQuery first-class objects: Refactored media queries from simple symbols to proper structs with id, type, and conditions, enabling accurate

data/ext/cataract/cataract.c

@@ -14,7 +14,7 @@ VALUE cMediaQuery;
 VALUE eCataractError;
 VALUE eDepthError;
 VALUE eSizeError;
-VALUE eParserError;
+VALUE eParseError;
 
 // ============================================================================
 // Helper Functions
@@ -1408,10 +1408,10 @@ void Init_native_extension(void) {
         eSizeError = rb_define_class_under(mCataract, "SizeError", eCataractError);
     }
 
-    if (rb_const_defined(mCataract, rb_intern("ParserError"))) {
-        eParserError = rb_const_get(mCataract, rb_intern("ParserError"));
+    if (rb_const_defined(mCataract, rb_intern("ParseError"))) {
+        eParseError = rb_const_get(mCataract, rb_intern("ParseError"));
     } else {
-        eParserError = rb_define_class_under(mCataract, "ParserError", eCataractError);
+        eParseError = rb_define_class_under(mCataract, "ParseError", eCataractError);
     }
 
     // Reuse Ruby-defined structs (they must be defined before loading this extension)

data/ext/cataract/cataract.h

@@ -19,7 +19,7 @@ extern VALUE cMediaQuery;
 extern VALUE eCataractError;
 extern VALUE eDepthError;
 extern VALUE eSizeError;
-extern VALUE eParserError;
+extern VALUE eParseError;
 
 // ============================================================================
 // Struct field indices

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 {
@@ -27,13 +32,21 @@ typedef struct {
     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;
 
 // Macro to skip CSS comments /* ... */
@@ -63,6 +76,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 +105,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 +297,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;
@@ -606,6 +726,46 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
 
         // Malformed declaration - skip to next semicolon to recover
         if (pos >= end || *pos != ':') {
+            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;
@@ -645,7 +805,7 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
         trim_trailing(val_start, &val_end);
 
         // Check for !important
-        int is_important = 0;
+        BOOLEAN 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++;
@@ -667,6 +827,34 @@ static VALUE parse_declarations(const char *start, const char *end, ParserContex
         // Final trim
         trim_trailing(val_start, &val_end);
 
+        // Check for empty value
+        if (val_end <= val_start && ctx->check_empty_values) {
+            long prop_len = prop_end - prop_start;
+            const char *css = RSTRING_PTR(ctx->css_string);
+            long error_pos = 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, 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);
+        }
+
         // Skip if value is empty
         if (val_end > val_start) {
             long prop_len = prop_end - prop_start;
@@ -896,7 +1084,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 +1097,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 +1210,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 }
@@ -1111,7 +1299,7 @@ static VALUE parse_mixed_block(ParserContext *ctx, const char *start, const char
         trim_leading(&p, end);
 
         const char *val_start = p;
-        int important = 0;
+        BOOLEAN important = 0;
 
         // Find end of value (semicolon or closing brace or end)
         while (p < end && *p != ';' && *p != '}') p++;
@@ -1432,6 +1620,30 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
             // 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");
+                } else {
+                    // Empty media query with check disabled - skip @media wrapper and parse contents as regular rules
+                    if (p >= pe || *p != '{') {
+                        continue;  // 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++;
+                    continue;
+                }
+            }
+
             if (p >= pe || *p != '{') {
                 continue;  // Malformed
             }
@@ -1546,7 +1758,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
             // Find matching closing brace
             const char *block_start = p;
-            const char *block_end = find_matching_brace(p, pe);
+            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
@@ -1573,13 +1785,22 @@ 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) {
+                // 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
                 p = at_name_end;
                 while (p < pe && *p != '{') p++;
@@ -1588,11 +1809,22 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                     continue;  // 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(p, pe);
+                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)
@@ -1606,7 +1838,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
             // 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);
@@ -1631,7 +1863,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
                 // Find matching closing brace
                 const char *block_start = p;
-                const char *block_end = find_matching_brace(p, pe);
+                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)
@@ -1680,7 +1912,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
             }
 
             // 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"
@@ -1702,7 +1934,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
                 // Find matching closing brace
                 const char *decl_start = p;
-                const char *decl_end = find_matching_brace(p, pe);
+                const char *decl_end = find_matching_brace_strict(p, pe, ctx->check_unclosed_blocks);
                 p = decl_end;
 
                 // Parse declarations
@@ -1740,6 +1972,10 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
         // 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;
             }
@@ -1755,7 +1991,7 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                 // 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);
+                BOOLEAN has_nesting = has_nested_selectors(decl_start, p);
 
                 // Get selector string
                 const char *sel_end = decl_start - 1;
@@ -1763,6 +1999,23 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                     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);
@@ -1809,6 +2062,37 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
                             }
 
                             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
@@ -1882,6 +2166,9 @@ static void parse_css_recursive(ParserContext *ctx, const char *css, const char
 
                                 // 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;
@@ -2023,6 +2310,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 +2348,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);
@@ -2115,6 +2442,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);

data/lib/cataract/error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Cataract
+  class Error < StandardError; end
+
+  # Error raised during import resolution
+  class ImportError < Error; end
+
+  # Parsing errors
+  class DepthError < Error; end
+  class SizeError < Error; end
+  # Internal parser consistency errors
+
+  # Error raised when invalid CSS is encountered in strict mode
+  class ParseError < Error
+    attr_reader :line, :column, :error_type
+
+    # @param message [String] Error message (without position info)
+    # @param css [String, nil] Full CSS string for calculating position
+    # @param pos [Integer, nil] Byte position in CSS where error occurred
+    # @param line [Integer, nil] Line number (if already calculated)
+    # @param column [Integer, nil] Column number (if already calculated)
+    # @param type [Symbol, nil] Type of parse error (:empty_value, :malformed_declaration, etc.)
+    def initialize(message, css: nil, pos: nil, line: nil, column: nil, type: nil)
+      # Calculate line/column from css and pos if provided
+      if css && pos
+        @line = css.byteslice(0, pos).count("\n") + 1
+        line_start = css.rindex("\n", pos - 1)
+        @column = line_start ? pos - line_start : pos + 1
+      else
+        @line = line
+        @column = column
+      end
+
+      @error_type = type
+
+      # Build message with position info
+      full_message = if @line && @column
+                       "#{message} at line #{@line}, column #{@column}"
+                     elsif @line
+                       "#{message} at line #{@line}"
+                     else
+                       message
+                     end
+
+      super(full_message)
+    end
+  end
+end

data/lib/cataract/pure/byte_constants.rb

@@ -46,6 +46,10 @@ module Cataract
   BYTE_BANG       = 33 # '!'
   BYTE_PERCENT    = 37 # '%'
   BYTE_SLASH_FWD  = 47 # '/' (also defined as BYTE_SLASH above)
+  BYTE_EQUALS     = 61 # '='
+  BYTE_CARET      = 94 # '^'
+  BYTE_DOLLAR     = 36 # '$'
+  BYTE_PIPE       = 124 # '|'
 
   # Specific lowercase letters (for keyword matching)
   BYTE_LOWER_U    = 117 # 'u'

data/lib/cataract/pure/parser.rb

@@ -64,6 +64,9 @@ module Cataract
     end
 
     def initialize(css_string, parser_options: {}, parent_media_sym: nil, parent_media_query_id: nil, depth: 0)
+      # Type validation
+      raise TypeError, "css_string must be a String, got #{css_string.class}" unless css_string.is_a?(String)
+
       # Private: Internal parsing state
       @_css = css_string.dup.freeze
       @_pos = 0
@@ -77,7 +80,8 @@ module Cataract
         selector_lists: true,
         base_uri: nil,
         absolute_paths: false,
-        uri_resolver: nil
+        uri_resolver: nil,
+        raise_parse_errors: false
       }.merge(parser_options)
 
       # Private: Extract options to ivars to avoid repeated hash lookups in hot path
@@ -86,6 +90,34 @@ module Cataract
       @_absolute_paths = @_parser_options[:absolute_paths]
       @_uri_resolver = @_parser_options[:uri_resolver] || Cataract::DEFAULT_URI_RESOLVER
 
+      # Parse error handling options - extract to ivars for hot path performance
+      @_raise_parse_errors = @_parser_options[:raise_parse_errors]
+      if @_raise_parse_errors.is_a?(Hash)
+        # Granular control - default all to false (opt-in)
+        @_check_empty_values = @_raise_parse_errors[:empty_values] || false
+        @_check_malformed_declarations = @_raise_parse_errors[:malformed_declarations] || false
+        @_check_invalid_selectors = @_raise_parse_errors[:invalid_selectors] || false
+        @_check_invalid_selector_syntax = @_raise_parse_errors[:invalid_selector_syntax] || false
+        @_check_malformed_at_rules = @_raise_parse_errors[:malformed_at_rules] || false
+        @_check_unclosed_blocks = @_raise_parse_errors[:unclosed_blocks] || false
+      elsif @_raise_parse_errors == true
+        # Enable all error checks
+        @_check_empty_values = true
+        @_check_malformed_declarations = true
+        @_check_invalid_selectors = true
+        @_check_invalid_selector_syntax = true
+        @_check_malformed_at_rules = true
+        @_check_unclosed_blocks = true
+      else
+        # Disabled
+        @_check_empty_values = false
+        @_check_malformed_declarations = false
+        @_check_invalid_selectors = false
+        @_check_invalid_selector_syntax = false
+        @_check_malformed_at_rules = false
+        @_check_unclosed_blocks = false
+      end
+
       # Private: Internal counters
       @_media_query_id_counter = 0   # Next MediaQuery ID (0-indexed)
       @_next_selector_list_id = 0    # Counter for selector list IDs
@@ -143,6 +175,13 @@ module Cataract
 
           selectors.each do |individual_selector|
             individual_selector.strip!
+
+            # Check for empty selector in comma-separated list
+            if @_check_invalid_selector_syntax && individual_selector.empty? && selectors.size > 1
+              raise ParseError.new('Invalid selector syntax: empty selector in comma-separated list',
+                                   css: @_css, pos: decl_start, type: :invalid_selector_syntax)
+            end
+
             next if individual_selector.empty?
 
             # Get rule ID for this selector
@@ -194,6 +233,13 @@ module Cataract
 
           selectors.each do |individual_selector|
             individual_selector.strip!
+
+            # Check for empty selector in comma-separated list
+            if @_check_invalid_selector_syntax && individual_selector.empty? && selectors.size > 1
+              raise ParseError.new('Invalid selector syntax: empty selector in comma-separated list',
+                                   css: @_css, pos: decl_start, type: :invalid_selector_syntax)
+            end
+
             next if individual_selector.empty?
 
             rule_id = @_rule_id_counter
@@ -303,6 +349,54 @@ module Cataract
       end until @_pos == old_pos # No progress made # rubocop:disable Lint/Loop
     end
 
+    # Check if a selector contains only valid CSS selector characters and sequences
+    # Returns true if valid, false if invalid
+    # Valid characters: a-z A-Z 0-9 - _ . # [ ] : * > + ~ ( ) ' " = ^ $ | \ & % / whitespace
+    def valid_selector_syntax?(selector_text)
+      i = 0
+      len = selector_text.bytesize
+
+      while i < len
+        byte = selector_text.getbyte(i)
+
+        # Check for invalid character sequences
+        if i + 1 < len
+          next_byte = selector_text.getbyte(i + 1)
+          # Double dot (..) is invalid
+          return false if byte == BYTE_DOT && next_byte == BYTE_DOT
+          # Double hash (##) is invalid
+          return false if byte == BYTE_HASH && next_byte == BYTE_HASH
+        end
+
+        # Alphanumeric
+        if (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) || (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z) || (byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9)
+          i += 1
+          next
+        end
+
+        # Whitespace
+        if byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
+          i += 1
+          next
+        end
+
+        # Valid CSS selector special characters
+        case byte
+        when BYTE_HYPHEN, BYTE_UNDERSCORE, BYTE_DOT, BYTE_HASH, BYTE_LBRACKET, BYTE_RBRACKET,
+             BYTE_COLON, BYTE_ASTERISK, BYTE_GT, BYTE_PLUS, BYTE_TILDE, BYTE_LPAREN, BYTE_RPAREN,
+             BYTE_SQUOTE, BYTE_DQUOTE, BYTE_EQUALS, BYTE_CARET, BYTE_DOLLAR,
+             BYTE_PIPE, BYTE_BACKSLASH, BYTE_AMPERSAND, BYTE_PERCENT, BYTE_SLASH, BYTE_BANG,
+             BYTE_COMMA
+          i += 1
+        else
+          # Invalid character found
+          return false
+        end
+      end
+
+      true
+    end
+
     # Parse a single CSS declaration (property: value)
     #
     # Performance-critical helper that parses one declaration.
@@ -410,6 +504,12 @@ module Cataract
         pos += 1
       end
 
+      # Reached EOF without finding matching closing brace
+      if @_check_unclosed_blocks && depth > 0
+        raise ParseError.new('Unclosed block: missing closing brace',
+                             css: @_css, pos: start_pos - 1, type: :unclosed_block)
+      end
+
       pos
     end
 
@@ -433,6 +533,29 @@ module Cataract
 
       # Trim whitespace from selector (in-place to avoid allocation)
       selector_text.strip!
+
+      # Validate selector (strict mode) - only if enabled to avoid overhead
+      if @_check_invalid_selectors
+        # Check for empty selector
+        if selector_text.empty?
+          raise ParseError.new('Invalid selector: empty selector',
+                               css: @_css, pos: start_pos, type: :invalid_selector)
+        end
+
+        # Check if selector starts with a combinator (>, +, ~)
+        first_char = selector_text.getbyte(0)
+        if first_char == BYTE_GT || first_char == BYTE_PLUS || first_char == BYTE_TILDE
+          raise ParseError.new("Invalid selector: selector cannot start with combinator '#{selector_text[0]}'",
+                               css: @_css, pos: start_pos, type: :invalid_selector)
+        end
+      end
+
+      # Check selector syntax (whitelist validation for invalid characters/sequences)
+      if @_check_invalid_selector_syntax && !valid_selector_syntax?(selector_text)
+        raise ParseError.new('Invalid selector syntax: selector contains invalid characters',
+                             css: @_css, pos: start_pos, type: :invalid_selector_syntax)
+      end
+
       selector_text
     end
 
@@ -514,7 +637,7 @@ module Cataract
 
                                     # This should never happen - parent_media_query_id should always be valid
                                     if parent_mq.nil?
-                                      raise ParserError, "Invalid parent_media_query_id: #{parent_media_query_id} (not found in @media_queries)"
+                                      raise ParseError, "Invalid parent_media_query_id: #{parent_media_query_id} (not found in @media_queries)"
                                     end
 
                                     # Combine parent media query with child
@@ -675,6 +798,18 @@ module Cataract
 
         # Skip if no colon found (malformed)
         if eof? || peek_byte != BYTE_COLON
+          # Check for malformed declaration (strict mode)
+          if @_check_malformed_declarations
+            property_text = byteslice_encoded(property_start, @_pos - property_start).strip
+            if property_text.empty?
+              raise ParseError.new('Malformed declaration: missing property name',
+                                   css: @_css, pos: property_start, type: :malformed_declaration)
+            else
+              raise ParseError.new("Malformed declaration: missing colon after property '#{property_text}'",
+                                   css: @_css, pos: property_start, type: :malformed_declaration)
+            end
+          end
+
           # Try to recover by finding next ; or }
           skip_to_semicolon_or_brace
           next
@@ -726,7 +861,7 @@ module Cataract
         value.strip!
 
         # Check for !important (byte-by-byte, no regexp)
-        if value.bytesize > 10
+        if value.bytesize >= 10
           # Scan backwards to find !important
           i = value.bytesize - 1
           # Skip trailing whitespace
@@ -757,6 +892,12 @@ module Cataract
           end
         end
 
+        # Check for empty value (strict mode) - only if enabled to avoid overhead
+        if @_check_empty_values && value.empty?
+          raise ParseError.new("Empty value for property '#{property}'",
+                               css: @_css, pos: property_start, type: :empty_value)
+        end
+
         # Skip semicolon if present
         @_pos += 1 if peek_byte == BYTE_SEMICOLON
 
@@ -827,13 +968,27 @@ module Cataract
       if AT_RULE_TYPES.include?(at_rule_name)
         skip_ws_and_comments
 
+        # Remember start of condition for error reporting
+        condition_start = @_pos
+
         # Skip to opening brace
+        condition_end = @_pos
         while !eof? && peek_byte != BYTE_LBRACE
+          condition_end = @_pos
           @_pos += 1
         end
 
         return if eof? || peek_byte != BYTE_LBRACE
 
+        # Validate condition (strict mode) - @supports, @container, @scope require conditions
+        if @_check_malformed_at_rules && (at_rule_name == 'supports' || at_rule_name == 'container' || at_rule_name == 'scope')
+          condition_str = byteslice_encoded(condition_start, condition_end - condition_start).strip
+          if condition_str.empty?
+            raise ParseError.new("Malformed @#{at_rule_name}: missing condition",
+                                 css: @_css, pos: condition_start, type: :malformed_at_rule)
+          end
+        end
+
         @_pos += 1 # skip '{'
 
         # Find matching closing brace
@@ -908,6 +1063,13 @@ module Cataract
         child_media_string = byteslice_encoded(mq_start, mq_end - mq_start)
         # Keep media query exactly as written - parentheses are required per CSS spec
         child_media_string.strip!
+
+        # Validate @media has a query (strict mode)
+        if @_check_malformed_at_rules && child_media_string.empty?
+          raise ParseError.new('Malformed @media: missing media query or condition',
+                               css: @_css, pos: mq_start, type: :malformed_at_rule)
+        end
+
         child_media_sym = child_media_string.to_sym
 
         # Split comma-separated media queries (e.g., "screen, print" -> ["screen", "print"])

data/lib/cataract/pure.rb

@@ -25,6 +25,8 @@ module Cataract
   class SizeError < Error; end
 end
 
+require_relative 'error'
+
 require_relative 'version'
 require_relative 'constants'
 

data/lib/cataract/stylesheet.rb

@@ -109,6 +109,9 @@ module Cataract
     # @option options [Hash] :parser ({}) Parser configuration options
     #   - :selector_lists [Boolean] (true) Track selector lists for W3C-compliant serialization
     def initialize(options = {})
+      # Type validation
+      raise TypeError, "options must be a Hash, got #{options.class}" unless options.is_a?(Hash)
+
       # Support :imports as alias for :import (backwards compatibility)
       options[:import] = options.delete(:imports) if options.key?(:imports) && !options.key?(:import)
 
@@ -119,12 +122,27 @@ module Cataract
         base_dir: nil,
         absolute_paths: false,
         uri_resolver: nil,
-        parser: {}
+        parser: {},
+        raise_parse_errors: false
       }.merge(options)
 
+      # Type validation for specific options
+      if @options[:import_fetcher] && !@options[:import_fetcher].respond_to?(:call)
+        raise TypeError, "import_fetcher must be a Proc or callable, got #{@options[:import_fetcher].class}"
+      end
+
+      if @options[:base_uri] && !@options[:base_uri].is_a?(String)
+        raise TypeError, "base_uri must be a String, got #{@options[:base_uri].class}"
+      end
+
+      if @options[:uri_resolver] && !@options[:uri_resolver].respond_to?(:call)
+        raise TypeError, "uri_resolver must be a Proc or callable, got #{@options[:uri_resolver].class}"
+      end
+
       # Parser options with defaults (stored for passing to parser)
       @parser_options = {
-        selector_lists: true
+        selector_lists: true,
+        raise_parse_errors: @options[:raise_parse_errors]
       }.merge(@options[:parser] || {})
 
       @rules = [] # Flat array of Rule structs
@@ -822,6 +840,10 @@ module Cataract
         new_imports = result[:imports]
         new_imports.each do |import|
           import.id += offset
+          # Update media_query_id to point to offsetted MediaQuery
+          if import.media_query_id
+            import.media_query_id += media_query_id_offset
+          end
           @imports << import
         end
 

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.2.4'
+  VERSION = '0.2.5'
 end

data/lib/cataract.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'cataract/version'
+require_relative 'cataract/error'
 require_relative 'cataract/constants'
 
 # Load struct definitions first (before C extension or pure Ruby)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - James Cook
@@ -83,6 +83,7 @@ files:
 - lib/cataract/constants.rb
 - lib/cataract/declaration.rb
 - lib/cataract/declarations.rb
+- lib/cataract/error.rb
 - lib/cataract/import_resolver.rb
 - lib/cataract/import_statement.rb
 - lib/cataract/media_query.rb