cataract 0.1.0

data/ext/cataract_old/cataract.c

@@ -0,0 +1,393 @@
+#include <ruby.h>
+#include <stdio.h>
+#include "cataract.h"
+
+// Global struct class definitions (declared extern in cataract.h)
+VALUE cDeclaration;
+VALUE cRule;
+
+// Error class definitions (declared extern in cataract.h)
+VALUE eCataractError;
+VALUE eParseError;
+VALUE eDepthError;
+VALUE eSizeError;
+
+// ============================================================================
+// Ruby Bindings and Public API
+// ============================================================================
+
+static VALUE parse_css_internal(VALUE self, VALUE css_string, int depth) {
+    // Check recursion depth to prevent stack overflow and memory exhaustion
+    if (depth > MAX_PARSE_DEPTH) {
+        rb_raise(eDepthError,
+                 "CSS nesting too deep: exceeded maximum depth of %d",
+                 MAX_PARSE_DEPTH);
+    }
+
+    Check_Type(css_string, T_STRING);
+
+    // Extract @charset if present (must be at very start per W3C spec)
+    // Handled separately because @charset must be at the absolute start
+    // and can be processed with simple string operations
+    VALUE charset = Qnil;
+    const char *css_start = RSTRING_PTR(css_string);
+    long css_len = RSTRING_LEN(css_string);
+
+    // Check for @charset at very start: @charset "UTF-8";
+    // Per spec: exact syntax with double quotes required
+    if (css_len > 10 && strncmp(css_start, "@charset ", 9) == 0) {
+        // Find opening quote
+        char *quote_start = strchr(css_start + 9, '"');
+        if (quote_start != NULL) {
+            // Find closing quote and semicolon
+            char *quote_end = strchr(quote_start + 1, '"');
+            if (quote_end != NULL) {
+                char *semicolon = quote_end + 1;
+                // Skip whitespace between quote and semicolon
+                while (semicolon < css_start + css_len && IS_WHITESPACE(*semicolon)) {
+                    semicolon++;
+                }
+                if (semicolon < css_start + css_len && *semicolon == ';') {
+                    // Valid @charset rule found
+                    charset = rb_str_new(quote_start + 1, quote_end - quote_start - 1);
+                    DEBUG_PRINTF("[@charset] Extracted: '%s'\n", RSTRING_PTR(charset));
+                }
+            }
+        }
+    }
+
+    // Parse CSS using our C parser implementation
+    // Returns hash: {query_string => [rules]} already grouped
+    VALUE rules_by_media = parse_css_impl(css_string, depth, Qnil);
+
+    // GC Guard: Protect Ruby objects from garbage collection
+    RB_GC_GUARD(css_string);
+    RB_GC_GUARD(rules_by_media);
+    RB_GC_GUARD(charset);
+
+    // At depth 0 (top-level parse), return hash with rules and charset
+    // Nested parses (depth > 0) return the hash directly
+    if (depth == 0) {
+        VALUE result = rb_hash_new();
+        rb_hash_aset(result, ID2SYM(rb_intern("rules")), rules_by_media);
+        rb_hash_aset(result, ID2SYM(rb_intern("charset")), charset);
+        return result;
+    }
+    return rules_by_media;
+}
+
+/*
+ * Ruby-facing wrapper for parse_declarations
+ *
+ * @param declarations_string [String] CSS declarations like "color: red; margin: 10px"
+ * @return [Array<Declaration>] Array of parsed declaration structs
+ */
+static VALUE parse_declarations(VALUE self, VALUE declarations_string) {
+    Check_Type(declarations_string, T_STRING);
+
+    const char *input = RSTRING_PTR(declarations_string);
+    long input_len = RSTRING_LEN(declarations_string);
+
+    // Strip outer braces and whitespace (css_parser compatibility)
+    const char *start = input;
+    const char *end = input + input_len;
+
+    while (start < end && (IS_WHITESPACE(*start) || *start == '{')) start++;
+    while (end > start && (IS_WHITESPACE(*(end-1)) || *(end-1) == '}')) end--;
+
+    VALUE result = parse_declarations_string(start, end);
+
+    RB_GC_GUARD(result);
+    return result;
+}
+
+// Public wrapper for Ruby - starts at depth 0
+static VALUE parse_css(VALUE self, VALUE css_string) {
+    // Verify that cRule was initialized in Init_cataract
+    if (cRule == Qnil || cRule == 0) {
+        rb_raise(rb_eRuntimeError, "cRule struct class not initialized - Init_cataract may have failed");
+    }
+    return parse_css_internal(self, css_string, 0);
+}
+
+/*
+ * Convert array of Rule structs to full CSS string
+ * Format: "selector { prop: value; }\nselector2 { prop: value; }"
+ */
+static VALUE rules_to_s(VALUE self, VALUE rules_array) {
+    Check_Type(rules_array, T_ARRAY);
+
+    long len = RARRAY_LEN(rules_array);
+    if (len == 0) {
+        return rb_str_new_cstr("");
+    }
+
+    // Estimate: ~100 chars per rule (selector + declarations)
+    VALUE result = rb_str_buf_new(len * 100);
+
+    for (long i = 0; i < len; i++) {
+        VALUE rule = rb_ary_entry(rules_array, i);
+
+        // Validate this is a Rule struct
+        if (!RB_TYPE_P(rule, T_STRUCT)) {
+            rb_raise(rb_eTypeError,
+                     "Expected array of Rule structs, got %s at index %ld",
+                     rb_obj_classname(rule), i);
+        }
+
+        // Extract: selector, declarations, specificity, media_query
+        VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
+        VALUE declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
+
+        // Append selector
+        rb_str_buf_append(result, selector);
+        rb_str_buf_cat2(result, " { ");
+
+        // Serialize each declaration
+        long decl_len = RARRAY_LEN(declarations);
+        for (long j = 0; j < decl_len; j++) {
+            VALUE decl = rb_ary_entry(declarations, j);
+
+            VALUE property = rb_struct_aref(decl, INT2FIX(DECL_PROPERTY));
+            VALUE value = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
+            VALUE important = rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT));
+
+            rb_str_buf_append(result, property);
+            rb_str_buf_cat2(result, ": ");
+            rb_str_buf_append(result, value);
+
+            if (RTEST(important)) {
+                rb_str_buf_cat2(result, " !important");
+            }
+
+            rb_str_buf_cat2(result, "; ");
+        }
+
+        rb_str_buf_cat2(result, "}\n");
+
+        RB_GC_GUARD(rule);
+        RB_GC_GUARD(selector);
+        RB_GC_GUARD(declarations);
+    }
+
+    RB_GC_GUARD(result);
+    return result;
+}
+
+/*
+ * Convert array of Declaration structs to CSS string
+ * Format: "prop: value; prop2: value2 !important; "
+ *
+ * This is the core serialization logic used by both:
+ * - Declarations#to_s (instance method)
+ * - Internal C serialization (stylesheet.c)
+ *
+ * Exported (non-static) so stylesheet.c can call it
+ */
+VALUE declarations_array_to_s(VALUE declarations_array) {
+    Check_Type(declarations_array, T_ARRAY);
+
+    long len = RARRAY_LEN(declarations_array);
+    if (len == 0) {
+        return rb_str_new_cstr("");
+    }
+
+    // Use rb_str_buf_new for efficient string building
+    VALUE result = rb_str_buf_new(len * 32); // Estimate 32 chars per declaration
+
+    for (long i = 0; i < len; i++) {
+        VALUE decl = rb_ary_entry(declarations_array, i);
+
+        // Validate this is a Declaration struct
+        if (!RB_TYPE_P(decl, T_STRUCT) || rb_obj_class(decl) != cDeclaration) {
+            rb_raise(rb_eTypeError,
+                     "Expected array of Declaration structs, got %s at index %ld",
+                     rb_obj_classname(decl), i);
+        }
+
+        // Extract struct fields
+        VALUE property = rb_struct_aref(decl, INT2FIX(DECL_PROPERTY));
+        VALUE value = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
+        VALUE important = rb_struct_aref(decl, INT2FIX(DECL_IMPORTANT));
+
+        // Append: "property: value"
+        rb_str_buf_append(result, property);
+        rb_str_buf_cat2(result, ": ");
+        rb_str_buf_append(result, value);
+
+        // Append " !important" if needed
+        if (RTEST(important)) {
+            rb_str_buf_cat2(result, " !important");
+        }
+
+        rb_str_buf_cat2(result, "; ");
+
+        RB_GC_GUARD(decl);
+        RB_GC_GUARD(property);
+        RB_GC_GUARD(value);
+        RB_GC_GUARD(important);
+    }
+
+    // Strip trailing space
+    rb_str_set_len(result, RSTRING_LEN(result) - 1);
+
+    RB_GC_GUARD(result);
+    return result;
+}
+
+/*
+ * Instance method: Declarations#to_s
+ * Converts declarations to CSS string
+ *
+ * @return [String] CSS declarations like "color: red; margin: 10px !important;"
+ */
+static VALUE declarations_to_s_method(VALUE self) {
+    // Get @values instance variable (array of Declaration structs)
+    VALUE values = rb_ivar_get(self, rb_intern("@values"));
+
+    // Call core serialization function
+    return declarations_array_to_s(values);
+}
+
+void Init_cataract() {
+    VALUE module = rb_define_module("Cataract");
+
+    // Initialize merge constants (cached strings and symbol IDs)
+    init_merge_constants();
+
+    // Define error class hierarchy
+    eCataractError = rb_define_class_under(module, "Error", rb_eStandardError);
+    eParseError = rb_define_class_under(module, "ParseError", eCataractError);
+    eDepthError = rb_define_class_under(module, "DepthError", eCataractError);
+    eSizeError = rb_define_class_under(module, "SizeError", eCataractError);
+
+    // Define Cataract::Declarations class (Ruby side will add methods)
+    VALUE cDeclarations = rb_define_class_under(module, "Declarations", rb_cObject);
+
+    // Define Cataract::Declaration = Struct.new(:property, :value, :important)
+    cDeclaration = rb_struct_define_under(
+        module,
+        "Declaration",
+        "property",
+        "value",
+        "important",
+        NULL
+    );
+
+    // Add methods to Declarations class
+    rb_define_method(cDeclarations, "to_s", declarations_to_s_method, 0);
+
+    // Define Cataract::Rule = Struct.new(:selector, :declarations, :specificity)
+    // Note: media_query removed - media info now stored at group level in hash structure
+    cRule = rb_struct_define_under(
+        module,
+        "Rule",
+        "selector",
+        "declarations",
+        "specificity",
+        NULL
+    );
+
+    // Define Cataract::Stylesheet class (Ruby side will reopen and add methods)
+    rb_define_class_under(module, "Stylesheet", rb_cObject);
+
+    rb_define_module_function(module, "parse_css", parse_css, 1);
+    rb_define_module_function(module, "parse_declarations", parse_declarations, 1);
+    rb_define_module_function(module, "calculate_specificity", calculate_specificity, 1);
+    rb_define_module_function(module, "merge_rules", cataract_merge_wrapper, 1);
+    rb_define_module_function(module, "apply_cascade", cataract_merge_wrapper, 1);  // Alias with better name
+    /* @api private */
+    rb_define_module_function(module, "_rules_to_s", rules_to_s, 1);
+
+    /* @api private */
+    rb_define_module_function(module, "_split_value", cataract_split_value, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_margin", cataract_expand_margin, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_padding", cataract_expand_padding, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_border_color", cataract_expand_border_color, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_border_style", cataract_expand_border_style, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_border_width", cataract_expand_border_width, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_border", cataract_expand_border, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_border_side", cataract_expand_border_side, 2);
+    /* @api private */
+    rb_define_module_function(module, "_expand_font", cataract_expand_font, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_list_style", cataract_expand_list_style, 1);
+    /* @api private */
+    rb_define_module_function(module, "_expand_background", cataract_expand_background, 1);
+
+    // Shorthand creation (inverse of expansion)
+    /* @api private */
+    rb_define_module_function(module, "_create_margin_shorthand", cataract_create_margin_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_padding_shorthand", cataract_create_padding_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_border_width_shorthand", cataract_create_border_width_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_border_style_shorthand", cataract_create_border_style_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_border_color_shorthand", cataract_create_border_color_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_border_shorthand", cataract_create_border_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_background_shorthand", cataract_create_background_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_font_shorthand", cataract_create_font_shorthand, 1);
+    /* @api private */
+    rb_define_module_function(module, "_create_list_style_shorthand", cataract_create_list_style_shorthand, 1);
+
+    // Serialization
+    /* @api private */
+    rb_define_module_function(module, "_stylesheet_to_s_c", stylesheet_to_s_c, 2);
+    /* @api private */
+    rb_define_module_function(module, "_stylesheet_to_formatted_s_c", stylesheet_to_formatted_s_c, 2);
+
+    // Import scanning
+    rb_define_module_function(module, "extract_imports", extract_imports, 1);
+
+    // Export string allocation mode as a constant for verification in benchmarks
+    #ifdef DISABLE_STR_BUF_OPTIMIZATION
+        rb_define_const(module, "STRING_ALLOC_MODE", ID2SYM(rb_intern("dynamic")));
+    #else
+        rb_define_const(module, "STRING_ALLOC_MODE", ID2SYM(rb_intern("buffer")));
+    #endif
+
+    // Export compile-time optimization flags as a hash for runtime introspection
+    VALUE compile_flags = rb_hash_new();
+
+    #ifdef DISABLE_STR_BUF_OPTIMIZATION
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("str_buf_optimization")), Qfalse);
+    #else
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("str_buf_optimization")), Qtrue);
+    #endif
+
+    #ifdef CATARACT_DEBUG
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("debug")), Qtrue);
+    #else
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("debug")), Qfalse);
+    #endif
+
+    #ifdef DISABLE_LOOP_UNROLL
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("loop_unroll")), Qfalse);
+    #else
+        rb_hash_aset(compile_flags, ID2SYM(rb_intern("loop_unroll")), Qtrue);
+    #endif
+
+    // Note: Compiler flags like -O3, -march=native, -funroll-loops don't have
+    // preprocessor defines, so we can't detect them at runtime. They're purely
+    // compiler optimizations that affect the generated code.
+
+    rb_define_const(module, "COMPILE_FLAGS", compile_flags);
+
+    // NOTE: Color conversion is now a separate extension (cataract_color)
+    // It's initialized when you require 'cataract/color_conversion'
+}
+
+// NOTE: shorthand_expander.c and value_splitter.c are now compiled separately (not included)
+

data/ext/cataract_old/cataract.h

@@ -0,0 +1,250 @@
+#ifndef CATARACT_H
+#define CATARACT_H
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+// ============================================================================
+// Global struct class references (defined in cataract.c, declared extern here)
+// ============================================================================
+
+extern VALUE cDeclaration;
+extern VALUE cRule;
+
+// Error class references
+extern VALUE eCataractError;
+extern VALUE eParseError;
+extern VALUE eDepthError;
+extern VALUE eSizeError;
+
+// ============================================================================
+// Struct field indices
+// ============================================================================
+
+// Rule struct field indices (selector, declarations, specificity)
+#define RULE_SELECTOR 0
+#define RULE_DECLARATIONS 1
+#define RULE_SPECIFICITY 2
+
+// Declaration struct field indices (property, value, important)
+#define DECL_PROPERTY 0
+#define DECL_VALUE 1
+#define DECL_IMPORTANT 2
+
+// ============================================================================
+// Macros
+// ============================================================================
+
+// Whitespace detection
+#define IS_WHITESPACE(c) ((c) == ' ' || (c) == '\t' || (c) == '\n' || (c) == '\r')
+
+// US-ASCII string literal creation (compile-time length for efficiency)
+// Use this for string literals like "margin-top" to avoid strlen() at runtime
+// Example: USASCII_STR("margin-top") expands to rb_usascii_str_new("margin-top", 10)
+#define USASCII_STR(str) rb_usascii_str_new((str), sizeof(str) - 1)
+
+// UTF-8 string literal creation (compile-time length for efficiency)
+// Use this for string literals that may be concatenated with UTF-8 content
+// Example: UTF8_STR("@") expands to rb_utf8_str_new("@", 1)
+#define UTF8_STR(str) rb_utf8_str_new((str), sizeof(str) - 1)
+
+// Debug output (disabled by default)
+// #define CATARACT_DEBUG 1
+
+#ifdef CATARACT_DEBUG
+  #define DEBUG_PRINTF(...) printf(__VA_ARGS__)
+#else
+  #define DEBUG_PRINTF(...) ((void)0)
+#endif
+
+// String allocation optimization (enabled by default)
+// Uses rb_str_buf_new for pre-allocation when building selector strings
+//
+// Disable for benchmarking baseline:
+//   Development: DISABLE_STR_BUF_OPTIMIZATION=1 rake compile
+//   Gem install: gem install cataract -- --disable-str-buf-optimization
+//
+#ifndef DISABLE_STR_BUF_OPTIMIZATION
+  #define STR_NEW_WITH_CAPACITY(capacity) rb_str_buf_new(capacity)
+  #define STR_NEW_CSTR(str) rb_str_new_cstr(str)
+#else
+  #define STR_NEW_WITH_CAPACITY(capacity) rb_str_new_cstr("")
+  #define STR_NEW_CSTR(str) rb_str_new_cstr(str)
+#endif
+
+// Sanity limits for CSS properties and values
+// These prevent crashes from pathological inputs (fuzzer-found edge cases)
+// Override at compile time if needed: -DMAX_PROPERTY_NAME_LENGTH=512
+#ifndef MAX_PROPERTY_NAME_LENGTH
+  #define MAX_PROPERTY_NAME_LENGTH 256  // Reasonable max for property names (e.g., "background-position-x")
+#endif
+
+#ifndef MAX_PROPERTY_VALUE_LENGTH
+  #define MAX_PROPERTY_VALUE_LENGTH 32768  // 32KB - handles large data URLs and complex values
+#endif
+
+#ifndef MAX_AT_RULE_BLOCK_LENGTH
+  #define MAX_AT_RULE_BLOCK_LENGTH 1048576  // 1MB - max size for @media, @supports, etc. block content
+#endif
+
+#ifndef MAX_PARSE_DEPTH
+  #define MAX_PARSE_DEPTH 10  // Max recursion depth for nested @media/@supports blocks
+#endif
+
+// ============================================================================
+// Inline helper functions
+// ============================================================================
+
+// Trim leading whitespace - modifies start pointer
+static inline void trim_leading(const char **start, const char *end) {
+    while (*start < end && IS_WHITESPACE(**start)) {
+        (*start)++;
+    }
+}
+
+// Trim trailing whitespace - modifies end pointer
+static inline void trim_trailing(const char *start, const char **end) {
+    while (*end > start && IS_WHITESPACE(*(*end - 1))) {
+        (*end)--;
+    }
+}
+
+// Strip whitespace from both ends and return new string
+static inline VALUE strip_string(const char *str, long len) {
+    const char *start = str;
+    const char *end = str + len;
+    trim_leading(&start, end);
+    trim_trailing(start, &end);
+    return rb_str_new(start, end - start);
+}
+
+// Lowercase property name (CSS property names are ASCII-only)
+//
+// Performance: Manual loop unrolling (USE_LOOP_UNROLL) provides ~6.6% speedup
+// on Apple Silicon M1 (tested with bootstrap.css parsing benchmark).
+static inline VALUE lowercase_property(VALUE property_str) {
+    Check_Type(property_str, T_STRING);
+
+    long len = RSTRING_LEN(property_str);
+    const char *src = RSTRING_PTR(property_str);
+
+    // Create new US-ASCII string with same length (CSS property names are ASCII-only)
+    VALUE result = rb_str_buf_new(len);
+    rb_enc_associate(result, rb_usascii_encoding());
+
+#ifndef DISABLE_LOOP_UNROLL
+    // Manual loop unrolling: process 4 chars at a time (default, ~6.6% faster on M1)
+    // Benefits: Fewer loop iterations, better ILP, fewer rb_str_buf_cat calls
+    long i = 0;
+
+    // Process 4 characters at a time
+    for (; i + 3 < len; i += 4) {
+        char c0 = src[i];
+        char c1 = src[i+1];
+        char c2 = src[i+2];
+        char c3 = src[i+3];
+
+        // Lowercase each character
+        if (c0 >= 'A' && c0 <= 'Z') c0 += 32;
+        if (c1 >= 'A' && c1 <= 'Z') c1 += 32;
+        if (c2 >= 'A' && c2 <= 'Z') c2 += 32;
+        if (c3 >= 'A' && c3 <= 'Z') c3 += 32;
+
+        char buf[4] = {c0, c1, c2, c3};
+        rb_str_buf_cat(result, buf, 4);
+    }
+
+    // Handle remaining characters (0-3)
+    for (; i < len; i++) {
+        char c = src[i];
+        if (c >= 'A' && c <= 'Z') {
+            c += 32;
+        }
+        rb_str_buf_cat(result, &c, 1);
+    }
+#else
+    // Unrolling disabled: process one character at a time
+    for (long i = 0; i < len; i++) {
+        char c = src[i];
+        // Lowercase ASCII letters only (CSS properties are ASCII)
+        if (c >= 'A' && c <= 'Z') {
+            c = c + ('a' - 'A');
+        }
+        rb_str_buf_cat(result, &c, 1);
+    }
+#endif
+
+    return result;
+}
+
+// ============================================================================
+// Function declarations (implemented in various .c/.rl files)
+// ============================================================================
+
+// Serialization functions (cataract.c)
+// Helper function for internal use (called by stylesheet.c)
+VALUE declarations_array_to_s(VALUE declarations_array);
+
+// Stylesheet serialization (stylesheet.c)
+VALUE stylesheet_to_s_c(VALUE self, VALUE rules_array, VALUE charset);
+VALUE stylesheet_to_formatted_s_c(VALUE self, VALUE rules_array, VALUE charset);
+
+// Import scanning (import_scanner.c)
+VALUE extract_imports(VALUE self, VALUE css_string);
+
+// Merge/cascade functions (merge.c)
+void init_merge_constants(void);
+VALUE cataract_merge(VALUE self, VALUE rules_array);
+VALUE cataract_merge_wrapper(VALUE self, VALUE input);
+
+// Shorthand expansion (shorthand_expander.rl)
+VALUE cataract_split_value(VALUE self, VALUE value);
+VALUE cataract_expand_margin(VALUE self, VALUE value);
+VALUE cataract_expand_padding(VALUE self, VALUE value);
+VALUE cataract_expand_border_color(VALUE self, VALUE value);
+VALUE cataract_expand_border_style(VALUE self, VALUE value);
+VALUE cataract_expand_border_width(VALUE self, VALUE value);
+VALUE cataract_expand_border(VALUE self, VALUE value);
+VALUE cataract_expand_border_side(VALUE self, VALUE side, VALUE value);
+VALUE cataract_expand_font(VALUE self, VALUE value);
+VALUE cataract_expand_list_style(VALUE self, VALUE value);
+VALUE cataract_expand_background(VALUE self, VALUE value);
+
+// Shorthand creation (shorthand_expander.rl)
+VALUE cataract_create_margin_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_padding_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_border_width_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_border_style_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_border_color_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_border_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_background_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_font_shorthand(VALUE self, VALUE properties);
+VALUE cataract_create_list_style_shorthand(VALUE self, VALUE properties);
+
+// CSS parser implementation (css_parser.c)
+VALUE parse_css_impl(VALUE css_string, int depth, VALUE parent_media_query);
+
+// CSS parsing helper functions (css_parser.c)
+VALUE parse_media_query(const char *query_str, long query_len);
+VALUE parse_declarations_string(const char *start, const char *end);
+void capture_declarations_fn(
+    const char **decl_start_ptr,
+    const char *p,
+    VALUE *current_declarations,
+    const char *css_string_base
+);
+void finish_rule_fn(
+    int inside_at_rule_block,
+    VALUE *current_selectors,
+    VALUE *current_declarations,
+    VALUE *current_media_types,
+    VALUE rules_array,
+    const char **mark_ptr
+);
+
+// Specificity calculator (specificity.c)
+VALUE calculate_specificity(VALUE self, VALUE selector_string);
+
+// NOTE: Color conversion moved to separate extension (ext/cataract_color/)
+
+#endif // CATARACT_H