cataract 0.2.4 → 0.3.0

data/ext/cataract/flatten.c

@@ -51,6 +51,49 @@ static struct shorthand_mapping SHORTHAND_MAPPINGS[] = {
     {NULL, 0, Qnil, NULL, Qnil, NULL, Qnil, NULL, Qnil, NULL, Qnil, NULL} // Sentinel to mark end of array
 };
 
+/*
+ * Family shorthand mapping: for shorthands whose longhand components aren't
+ * "all N required" like the 4-sided shorthands above, but a mix of required
+ * and optional candidates - border only requires border-style (width/color
+ * optional); font requires font-size and font-family (4 others optional);
+ * list-style and background don't require any specific candidate, just a
+ * minimum count of any 2 present.
+ *
+ * Candidates must be listed with any REQUIRED ones first: the recreation
+ * logic uses "first present candidate in this order" as the source of
+ * source_order/specificity/importance for the resulting shorthand, which is
+ * always the first required candidate when there is one (border-style for
+ * border, font-size for font) or the first present optional candidate
+ * otherwise (matching what list-style/background use) - see
+ * try_recreate_shorthand_family.
+ */
+#define MAX_SHORTHAND_FAMILY_CANDIDATES 6
+
+struct shorthand_family_mapping {
+    VALUE shorthand_name_val;                              // Cached Ruby string for the shorthand property name
+    VALUE candidate_vals[MAX_SHORTHAND_FAMILY_CANDIDATES]; // Cached candidate longhand property names, populated in init_flatten_constants()
+    int num_candidates;
+    int num_required;  // First `num_required` candidates are mandatory; 0 means "optional-only" (see min_present)
+    int min_present;    // Only checked when num_required == 0: minimum count of ANY candidates that must be present
+    VALUE (*creator_func)(VALUE, VALUE);
+};
+
+// Order matches the original inline recreation blocks (border, list-style,
+// font, background) - properties_hash is a Ruby Hash, whose iteration order
+// (and therefore the final declaration output order) follows insertion
+// order, so this table's order is observable behavior, not just style.
+static struct shorthand_family_mapping SHORTHAND_FAMILY_MAPPINGS[] = {
+    // border: only border-style is required; border-width/border-color are optional
+    { Qnil, { Qnil, Qnil, Qnil, Qnil, Qnil, Qnil }, 3, 1, 0, cataract_create_border_shorthand },
+    // list-style: none individually required, but at least 2 of the 3 must be present
+    { Qnil, { Qnil, Qnil, Qnil, Qnil, Qnil, Qnil }, 3, 0, 2, cataract_create_list_style_shorthand },
+    // font: font-size and font-family are both required; the rest are optional
+    { Qnil, { Qnil, Qnil, Qnil, Qnil, Qnil, Qnil }, 6, 2, 0, cataract_create_font_shorthand },
+    // background: none individually required, but at least 2 of the 5 must be present
+    { Qnil, { Qnil, Qnil, Qnil, Qnil, Qnil, Qnil }, 5, 0, 2, cataract_create_background_shorthand },
+};
+#define NUM_SHORTHAND_FAMILIES (sizeof(SHORTHAND_FAMILY_MAPPINGS) / sizeof(SHORTHAND_FAMILY_MAPPINGS[0]))
+
 // Cached property name strings (frozen, never GC'd)
 // Initialized in init_flatten_constants() at module load time
 static VALUE str_margin = Qnil;
@@ -97,68 +140,6 @@ static VALUE str_background_repeat = Qnil;
 static VALUE str_background_attachment = Qnil;
 static VALUE str_background_position = Qnil;
 
-// Context for expanded property iteration
-struct expand_context {
-    VALUE properties_hash;
-    long source_order;
-    int specificity;
-    VALUE important;
-};
-
-// Callback for rb_hash_foreach - process expanded properties and apply cascade
-static int flatten_expanded_callback(VALUE exp_prop, VALUE exp_value, VALUE ctx_val) {
-    struct expand_context *ctx = (struct expand_context *)ctx_val;
-
-    // Expanded properties from shorthand expanders are already lowercase
-    // No need to lowercase again
-    int is_important = RTEST(ctx->important);
-
-    // Apply cascade rules for expanded property
-    VALUE existing = rb_hash_aref(ctx->properties_hash, exp_prop);
-
-    if (NIL_P(existing)) {
-        // Create array: [source_order, specificity, important, value]
-        VALUE prop_data = rb_ary_new_capa(4);
-        rb_ary_push(prop_data, LONG2NUM(ctx->source_order));
-        rb_ary_push(prop_data, INT2NUM(ctx->specificity));
-        rb_ary_push(prop_data, ctx->important);
-        rb_ary_push(prop_data, exp_value);
-        rb_hash_aset(ctx->properties_hash, exp_prop, prop_data);
-    } else {
-        // Access array elements directly
-        long existing_order = NUM2LONG(RARRAY_AREF(existing, PROP_SOURCE_ORDER));
-        int existing_spec_int = NUM2INT(RARRAY_AREF(existing, PROP_SPECIFICITY));
-        VALUE existing_important = RARRAY_AREF(existing, PROP_IMPORTANT);
-        int existing_is_important = RTEST(existing_important);
-
-        int should_replace = 0;
-        if (is_important) {
-            if (!existing_is_important || existing_spec_int < ctx->specificity ||
-                (existing_spec_int == ctx->specificity && existing_order <= ctx->source_order)) {
-                should_replace = 1;
-            }
-        } else {
-            if (!existing_is_important &&
-                (existing_spec_int < ctx->specificity ||
-                 (existing_spec_int == ctx->specificity && existing_order <= ctx->source_order))) {
-                should_replace = 1;
-            }
-        }
-
-        if (should_replace) {
-            // Update array elements
-            RARRAY_ASET(existing, PROP_SOURCE_ORDER, LONG2NUM(ctx->source_order));
-            RARRAY_ASET(existing, PROP_SPECIFICITY, INT2NUM(ctx->specificity));
-            RARRAY_ASET(existing, PROP_IMPORTANT, ctx->important);
-            RARRAY_ASET(existing, PROP_VALUE, exp_value);
-        }
-    }
-
-    RB_GC_GUARD(exp_prop);
-    RB_GC_GUARD(exp_value);
-    return ST_CONTINUE;
-}
-
 // Callback for rb_hash_foreach - builds result array from properties hash
 static int flatten_build_result_callback(VALUE property, VALUE prop_data, VALUE result_ary) {
     // Extract value and important flag from array: [source_order, specificity, important, value]
@@ -322,139 +303,34 @@ void init_flatten_constants(void) {
     SHORTHAND_MAPPINGS[4].prop_right_val = str_border_right_color;
     SHORTHAND_MAPPINGS[4].prop_bottom_val = str_border_bottom_color;
     SHORTHAND_MAPPINGS[4].prop_left_val = str_border_left_color;
-}
 
-// Helper macros to extract property data from properties_hash
-// Properties are stored as arrays: [source_order, specificity, important, value]
-#define GET_PROP_VALUE(hash, prop_name) \
-    ({ VALUE pd = rb_hash_aref(hash, USASCII_STR(prop_name)); \
-       NIL_P(pd) ? Qnil : RARRAY_AREF(pd, PROP_VALUE); })
-
-#define GET_PROP_DATA(hash, prop_name) \
-    rb_hash_aref(hash, USASCII_STR(prop_name))
-
-// Versions that accept cached VALUE strings instead of string literals
-#define GET_PROP_VALUE_STR(hash, str_prop) \
-    ({ VALUE pd = rb_hash_aref(hash, str_prop); \
-       NIL_P(pd) ? Qnil : RARRAY_AREF(pd, PROP_VALUE); })
-
-#define GET_PROP_DATA_STR(hash, str_prop) \
-    rb_hash_aref(hash, str_prop)
-
-// Helper macro to check if a property's !important flag matches a reference
-#define CHECK_IMPORTANT_MATCH(hash, str_prop, ref_important) \
-    ({ VALUE _pd = GET_PROP_DATA_STR(hash, str_prop); \
-       NIL_P(_pd) ? 1 : (RTEST(RARRAY_AREF(_pd, PROP_IMPORTANT)) == (ref_important)); })
-
-// Macro to create shorthand from 4-sided properties (margin, padding, border-width/style/color)
-// Reduces repetitive code by encapsulating the common pattern:
-// 1. Get 4 longhand values (top, right, bottom, left)
-// 2. Check if all 4 exist
-// 3. Call shorthand creator function
-// 4. Add shorthand to properties_hash and remove longhands
-// Note: Uses cached static strings (VALUE) for property names - no runtime allocation
-#define TRY_CREATE_FOUR_SIDED_SHORTHAND(hash, str_top, str_right, str_bottom, str_left, str_shorthand, creator_func) \
-    do { \
-        VALUE _top = GET_PROP_VALUE_STR(hash, str_top); \
-        VALUE _right = GET_PROP_VALUE_STR(hash, str_right); \
-        VALUE _bottom = GET_PROP_VALUE_STR(hash, str_bottom); \
-        VALUE _left = GET_PROP_VALUE_STR(hash, str_left); \
-        \
-        if (!NIL_P(_top) && !NIL_P(_right) && !NIL_P(_bottom) && !NIL_P(_left)) { \
-            /* Check that all properties have the same !important flag */ \
-            VALUE _top_data = GET_PROP_DATA_STR(hash, str_top); \
-            VALUE _right_data = GET_PROP_DATA_STR(hash, str_right); \
-            VALUE _bottom_data = GET_PROP_DATA_STR(hash, str_bottom); \
-            VALUE _left_data = GET_PROP_DATA_STR(hash, str_left); \
-            \
-            VALUE _top_imp = RARRAY_AREF(_top_data, PROP_IMPORTANT); \
-            VALUE _right_imp = RARRAY_AREF(_right_data, PROP_IMPORTANT); \
-            VALUE _bottom_imp = RARRAY_AREF(_bottom_data, PROP_IMPORTANT); \
-            VALUE _left_imp = RARRAY_AREF(_left_data, PROP_IMPORTANT); \
-            \
-            int _top_is_imp = RTEST(_top_imp); \
-            int _right_is_imp = RTEST(_right_imp); \
-            int _bottom_is_imp = RTEST(_bottom_imp); \
-            int _left_is_imp = RTEST(_left_imp); \
-            \
-            /* Only create shorthand if all have same !important flag */ \
-            if (_top_is_imp == _right_is_imp && _top_is_imp == _bottom_is_imp && _top_is_imp == _left_is_imp) { \
-                VALUE _props = rb_hash_new(); \
-                rb_hash_aset(_props, str_top, _top); \
-                rb_hash_aset(_props, str_right, _right); \
-                rb_hash_aset(_props, str_bottom, _bottom); \
-                rb_hash_aset(_props, str_left, _left); \
-                \
-                VALUE _shorthand_value = creator_func(Qnil, _props); \
-                if (!NIL_P(_shorthand_value)) { \
-                    long _source_order = NUM2LONG(RARRAY_AREF(_top_data, PROP_SOURCE_ORDER)); \
-                    int _specificity = NUM2INT(RARRAY_AREF(_top_data, PROP_SPECIFICITY)); \
-                    \
-                    VALUE _shorthand_data = rb_ary_new_capa(4); \
-                    rb_ary_push(_shorthand_data, LONG2NUM(_source_order)); \
-                    rb_ary_push(_shorthand_data, INT2NUM(_specificity)); \
-                    rb_ary_push(_shorthand_data, _top_imp); \
-                    rb_ary_push(_shorthand_data, _shorthand_value); \
-                    rb_hash_aset(hash, str_shorthand, _shorthand_data); \
-                    \
-                    rb_hash_delete(hash, str_top); \
-                    rb_hash_delete(hash, str_right); \
-                    rb_hash_delete(hash, str_bottom); \
-                    rb_hash_delete(hash, str_left); \
-                    \
-                    RB_GC_GUARD(_shorthand_value); \
-                } \
-                RB_GC_GUARD(_props); \
-            } \
-        } \
-    } while(0)
-
-// Helper macro: Recreate dimension shorthand (margin, padding, border-width)
-// Takes a property prefix like "margin" and creates "margin" from margin-top/right/bottom/left
-#define RECREATE_DIMENSION_SHORTHAND(hash, prefix, creator_func) \
-    do { \
-        char _top_name[64], _right_name[64], _bottom_name[64], _left_name[64]; \
-        snprintf(_top_name, sizeof(_top_name), "%s-top", prefix); \
-        snprintf(_right_name, sizeof(_right_name), "%s-right", prefix); \
-        snprintf(_bottom_name, sizeof(_bottom_name), "%s-bottom", prefix); \
-        snprintf(_left_name, sizeof(_left_name), "%s-left", prefix); \
-        \
-        VALUE _top_data = rb_hash_aref(hash, STR_NEW_CSTR(_top_name)); \
-        VALUE _right_data = rb_hash_aref(hash, STR_NEW_CSTR(_right_name)); \
-        VALUE _bottom_data = rb_hash_aref(hash, STR_NEW_CSTR(_bottom_name)); \
-        VALUE _left_data = rb_hash_aref(hash, STR_NEW_CSTR(_left_name)); \
-        \
-        if (!NIL_P(_top_data) && !NIL_P(_right_data) && !NIL_P(_bottom_data) && !NIL_P(_left_data)) { \
-            VALUE _top_imp = RARRAY_AREF(_top_data, PROP_IMPORTANT); \
-            VALUE _right_imp = RARRAY_AREF(_right_data, PROP_IMPORTANT); \
-            VALUE _bottom_imp = RARRAY_AREF(_bottom_data, PROP_IMPORTANT); \
-            VALUE _left_imp = RARRAY_AREF(_left_data, PROP_IMPORTANT); \
-            \
-            if (RTEST(_top_imp) == RTEST(_right_imp) && RTEST(_top_imp) == RTEST(_bottom_imp) && RTEST(_top_imp) == RTEST(_left_imp)) { \
-                VALUE _props = rb_hash_new(); \
-                rb_hash_aset(_props, STR_NEW_CSTR(_top_name), RARRAY_AREF(_top_data, PROP_VALUE)); \
-                rb_hash_aset(_props, STR_NEW_CSTR(_right_name), RARRAY_AREF(_right_data, PROP_VALUE)); \
-                rb_hash_aset(_props, STR_NEW_CSTR(_bottom_name), RARRAY_AREF(_bottom_data, PROP_VALUE)); \
-                rb_hash_aset(_props, STR_NEW_CSTR(_left_name), RARRAY_AREF(_left_data, PROP_VALUE)); \
-                \
-                VALUE _shorthand_value = creator_func(Qnil, _props); \
-                if (!NIL_P(_shorthand_value)) { \
-                    VALUE _shorthand_data = rb_ary_new_capa(4); \
-                    rb_ary_push(_shorthand_data, RARRAY_AREF(_top_data, PROP_SOURCE_ORDER)); \
-                    rb_ary_push(_shorthand_data, RARRAY_AREF(_top_data, PROP_SPECIFICITY)); \
-                    rb_ary_push(_shorthand_data, _top_imp); \
-                    rb_ary_push(_shorthand_data, _shorthand_value); \
-                    rb_hash_aset(hash, rb_usascii_str_new(prefix, strlen(prefix)), _shorthand_data); \
-                    \
-                    rb_hash_delete(hash, STR_NEW_CSTR(_top_name)); \
-                    rb_hash_delete(hash, STR_NEW_CSTR(_right_name)); \
-                    rb_hash_delete(hash, STR_NEW_CSTR(_bottom_name)); \
-                    rb_hash_delete(hash, STR_NEW_CSTR(_left_name)); \
-                    DEBUG_PRINTF("      -> Recreated %s shorthand\n", prefix); \
-                } \
-            } \
-        } \
-    } while(0)
+    // Populate the family shorthand mapping table. Candidate order matches
+    // what each original inline block checked (required candidates first).
+    SHORTHAND_FAMILY_MAPPINGS[0].shorthand_name_val = str_border;
+    SHORTHAND_FAMILY_MAPPINGS[0].candidate_vals[0] = str_border_style;
+    SHORTHAND_FAMILY_MAPPINGS[0].candidate_vals[1] = str_border_width;
+    SHORTHAND_FAMILY_MAPPINGS[0].candidate_vals[2] = str_border_color;
+
+    SHORTHAND_FAMILY_MAPPINGS[1].shorthand_name_val = str_list_style;
+    SHORTHAND_FAMILY_MAPPINGS[1].candidate_vals[0] = str_list_style_type;
+    SHORTHAND_FAMILY_MAPPINGS[1].candidate_vals[1] = str_list_style_position;
+    SHORTHAND_FAMILY_MAPPINGS[1].candidate_vals[2] = str_list_style_image;
+
+    SHORTHAND_FAMILY_MAPPINGS[2].shorthand_name_val = str_font;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[0] = str_font_size;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[1] = str_font_family;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[2] = str_font_style;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[3] = str_font_variant;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[4] = str_font_weight;
+    SHORTHAND_FAMILY_MAPPINGS[2].candidate_vals[5] = str_line_height;
+
+    SHORTHAND_FAMILY_MAPPINGS[3].shorthand_name_val = str_background;
+    SHORTHAND_FAMILY_MAPPINGS[3].candidate_vals[0] = str_background_color;
+    SHORTHAND_FAMILY_MAPPINGS[3].candidate_vals[1] = str_background_image;
+    SHORTHAND_FAMILY_MAPPINGS[3].candidate_vals[2] = str_background_repeat;
+    SHORTHAND_FAMILY_MAPPINGS[3].candidate_vals[3] = str_background_position;
+    SHORTHAND_FAMILY_MAPPINGS[3].candidate_vals[4] = str_background_attachment;
+}
 
 // Helper function: Try to recreate a shorthand property from its longhand components
 // Uses cached VALUE objects for property names to avoid repeated string allocations
@@ -511,6 +387,92 @@ static inline void try_recreate_shorthand(VALUE properties_hash, const struct sh
     DEBUG_PRINTF("      -> Recreated %s shorthand\n", mapping->shorthand_name);
 }
 
+// Helper function: Try to recreate a "family" shorthand (border, font,
+// list-style, background) from its longhand components. Unlike
+// try_recreate_shorthand above (always exactly 4 required sides), these
+// allow a mix of required and optional candidates - see
+// shorthand_family_mapping for the exact rules.
+static inline void try_recreate_shorthand_family(VALUE properties_hash, const struct shorthand_family_mapping *family) {
+    // Zero-initialize all slots (not just the first num_candidates) so every
+    // read below is well-defined regardless of a given family's arity.
+    VALUE datas[MAX_SHORTHAND_FAMILY_CANDIDATES] = { Qnil, Qnil, Qnil, Qnil, Qnil, Qnil };
+    int present_count = 0;
+
+    for (int i = 0; i < family->num_candidates; i++) {
+        datas[i] = rb_hash_aref(properties_hash, family->candidate_vals[i]);
+        if (!NIL_P(datas[i])) present_count++;
+    }
+
+    // Required candidates (if any) must all be present
+    for (int i = 0; i < family->num_required; i++) {
+        if (NIL_P(datas[i])) return;
+    }
+
+    // If nothing is individually required, need a minimum count of ANY present
+    if (family->num_required == 0 && present_count < family->min_present) {
+        return;
+    }
+
+    // All present candidates must share the same !important flag
+    VALUE reference_imp = Qnil;
+    int have_reference = 0;
+    for (int i = 0; i < family->num_candidates; i++) {
+        if (NIL_P(datas[i])) continue;
+        VALUE imp = RARRAY_AREF(datas[i], PROP_IMPORTANT);
+        if (!have_reference) {
+            reference_imp = imp;
+            have_reference = 1;
+        } else if (RTEST(reference_imp) != RTEST(imp)) {
+            return;
+        }
+    }
+
+    // Build a hash of present property values for the creator function
+    VALUE props = rb_hash_new();
+    for (int i = 0; i < family->num_candidates; i++) {
+        if (!NIL_P(datas[i])) {
+            rb_hash_aset(props, family->candidate_vals[i], RARRAY_AREF(datas[i], PROP_VALUE));
+        }
+    }
+
+    VALUE shorthand_value = family->creator_func(Qnil, props);
+    if (NIL_P(shorthand_value)) {
+        return; // Creator decided not to create shorthand
+    }
+
+    // First present candidate (in declared order) supplies source_order/
+    // specificity/importance for the shorthand - always the first required
+    // candidate when there is one (border-style for border, font-size for
+    // font), otherwise the first present optional candidate, matching what
+    // each original inline block hardcoded.
+    int primary_idx = -1;
+    for (int i = 0; i < family->num_candidates; i++) {
+        if (!NIL_P(datas[i])) {
+            primary_idx = i;
+            break;
+        }
+    }
+    if (primary_idx < 0) {
+        return; // Nothing present to build a shorthand from
+    }
+
+    VALUE shorthand_data = rb_ary_new_capa(4);
+    rb_ary_push(shorthand_data, RARRAY_AREF(datas[primary_idx], PROP_SOURCE_ORDER));
+    rb_ary_push(shorthand_data, RARRAY_AREF(datas[primary_idx], PROP_SPECIFICITY));
+    rb_ary_push(shorthand_data, reference_imp);
+    rb_ary_push(shorthand_data, shorthand_value);
+
+    // Add shorthand and remove longhand properties
+    rb_hash_aset(properties_hash, family->shorthand_name_val, shorthand_data);
+    for (int i = 0; i < family->num_candidates; i++) {
+        if (!NIL_P(datas[i])) {
+            rb_hash_delete(properties_hash, family->candidate_vals[i]);
+        }
+    }
+
+    DEBUG_PRINTF("      -> Recreated family shorthand\n");
+}
+
 /*
  * Helper struct: For processing expanded properties during merge
  */
@@ -829,44 +791,49 @@ static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, V
             if (first_char == 'm' || first_char == 'p' || first_char == 'b' ||
                 first_char == 'f' || first_char == 'l') {
                 // Potentially a shorthand - check specific property names
+                //
+                // Importance is always passed as Qfalse here: the expanded
+                // declarations' own `important` field is never read below
+                // (see expand_data.is_important) - actual importance comes
+                // from the original, un-expanded declaration instead.
                 if (strcmp(prop_cstr, "margin") == 0) {
-                    expanded = cataract_expand_margin(Qnil, value);
+                    expanded = cataract_expand_margin(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding margin shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "padding") == 0) {
-                    expanded = cataract_expand_padding(Qnil, value);
+                    expanded = cataract_expand_padding(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding padding shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "background") == 0) {
-                    expanded = cataract_expand_background(Qnil, value);
+                    expanded = cataract_expand_background(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding background shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "font") == 0) {
-                    expanded = cataract_expand_font(Qnil, value);
+                    expanded = cataract_expand_font(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding font shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border") == 0) {
-                    expanded = cataract_expand_border(Qnil, value);
+                    expanded = cataract_expand_border(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-color") == 0) {
-                    expanded = cataract_expand_border_color(Qnil, value);
+                    expanded = cataract_expand_border_color(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-color shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-style") == 0) {
-                    expanded = cataract_expand_border_style(Qnil, value);
+                    expanded = cataract_expand_border_style(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-style shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-width") == 0) {
-                    expanded = cataract_expand_border_width(Qnil, value);
+                    expanded = cataract_expand_border_width(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-width shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "list-style") == 0) {
-                    expanded = cataract_expand_list_style(Qnil, value);
+                    expanded = cataract_expand_list_style(Qnil, value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding list-style shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-top") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("top"), value);
+                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("top"), value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-top shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-right") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("right"), value);
+                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("right"), value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-right shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-bottom") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("bottom"), value);
+                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("bottom"), value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-bottom shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 } else if (strcmp(prop_cstr, "border-left") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("left"), value);
+                    expanded = cataract_expand_border_side(Qnil, STR_NEW_CSTR("left"), value, Qfalse);
                     DEBUG_PRINTF("          -> Expanding border-left shorthand (%ld longhands)\n", RARRAY_LEN(expanded));
                 }
             }
@@ -916,204 +883,9 @@ static VALUE flatten_rules_for_selector(VALUE rules_array, VALUE rule_indices, V
         try_recreate_shorthand(properties_hash, mapping);
     }
 
-    // Try to recreate full border shorthand (if border-width, border-style, border-color present)
-    {
-        VALUE width = rb_hash_aref(properties_hash, STR_NEW_CSTR("border-width"));
-        VALUE style = rb_hash_aref(properties_hash, STR_NEW_CSTR("border-style"));
-        VALUE color = rb_hash_aref(properties_hash, STR_NEW_CSTR("border-color"));
-
-        // Need at least style (border shorthand requires style)
-        if (!NIL_P(style)) {
-            // Check all have same !important flag
-            VALUE style_imp = RARRAY_AREF(style, PROP_IMPORTANT);
-            int same_importance = 1;
-            if (!NIL_P(width)) same_importance = same_importance && (RTEST(style_imp) == RTEST(RARRAY_AREF(width, PROP_IMPORTANT)));
-            if (!NIL_P(color)) same_importance = same_importance && (RTEST(style_imp) == RTEST(RARRAY_AREF(color, PROP_IMPORTANT)));
-
-            if (same_importance) {
-                VALUE props = rb_hash_new();
-                if (!NIL_P(width)) rb_hash_aset(props, STR_NEW_CSTR("border-width"), RARRAY_AREF(width, PROP_VALUE));
-                rb_hash_aset(props, STR_NEW_CSTR("border-style"), RARRAY_AREF(style, PROP_VALUE));
-                if (!NIL_P(color)) rb_hash_aset(props, STR_NEW_CSTR("border-color"), RARRAY_AREF(color, PROP_VALUE));
-
-                VALUE shorthand_value = cataract_create_border_shorthand(Qnil, props);
-                if (!NIL_P(shorthand_value)) {
-                    VALUE shorthand_data = rb_ary_new_capa(4);
-                    rb_ary_push(shorthand_data, RARRAY_AREF(style, PROP_SOURCE_ORDER));
-                    rb_ary_push(shorthand_data, RARRAY_AREF(style, PROP_SPECIFICITY));
-                    rb_ary_push(shorthand_data, style_imp);
-                    rb_ary_push(shorthand_data, shorthand_value);
-                    rb_hash_aset(properties_hash, USASCII_STR("border"), shorthand_data);
-
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("border-width"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("border-style"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("border-color"));
-                    DEBUG_PRINTF("      -> Recreated border shorthand\n");
-                }
-            }
-        }
-    }
-
-    // Try to recreate list-style shorthand
-    {
-        VALUE type = rb_hash_aref(properties_hash, STR_NEW_CSTR("list-style-type"));
-        VALUE position = rb_hash_aref(properties_hash, STR_NEW_CSTR("list-style-position"));
-        VALUE image = rb_hash_aref(properties_hash, STR_NEW_CSTR("list-style-image"));
-
-        // Need at least 2 properties to create shorthand
-        // Single property should stay as longhand (semantic difference)
-        int list_count = 0;
-        if (!NIL_P(type)) list_count++;
-        if (!NIL_P(position)) list_count++;
-        if (!NIL_P(image)) list_count++;
-
-        if (list_count >= 2) {
-            // Check all have same !important flag
-            VALUE first_imp = Qnil;
-            if (!NIL_P(type)) first_imp = RARRAY_AREF(type, PROP_IMPORTANT);
-            else if (!NIL_P(position)) first_imp = RARRAY_AREF(position, PROP_IMPORTANT);
-            else if (!NIL_P(image)) first_imp = RARRAY_AREF(image, PROP_IMPORTANT);
-
-            int same_importance = 1;
-            if (!NIL_P(type)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(type, PROP_IMPORTANT)));
-            if (!NIL_P(position)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(position, PROP_IMPORTANT)));
-            if (!NIL_P(image)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(image, PROP_IMPORTANT)));
-
-            if (same_importance) {
-                VALUE props = rb_hash_new();
-                if (!NIL_P(type)) rb_hash_aset(props, STR_NEW_CSTR("list-style-type"), RARRAY_AREF(type, PROP_VALUE));
-                if (!NIL_P(position)) rb_hash_aset(props, STR_NEW_CSTR("list-style-position"), RARRAY_AREF(position, PROP_VALUE));
-                if (!NIL_P(image)) rb_hash_aset(props, STR_NEW_CSTR("list-style-image"), RARRAY_AREF(image, PROP_VALUE));
-
-                VALUE shorthand_value = cataract_create_list_style_shorthand(Qnil, props);
-                if (!NIL_P(shorthand_value)) {
-                    VALUE first_prop = !NIL_P(type) ? type : (!NIL_P(position) ? position : image);
-                    VALUE shorthand_data = rb_ary_new_capa(4);
-                    rb_ary_push(shorthand_data, RARRAY_AREF(first_prop, PROP_SOURCE_ORDER));
-                    rb_ary_push(shorthand_data, RARRAY_AREF(first_prop, PROP_SPECIFICITY));
-                    rb_ary_push(shorthand_data, first_imp);
-                    rb_ary_push(shorthand_data, shorthand_value);
-                    rb_hash_aset(properties_hash, USASCII_STR("list-style"), shorthand_data);
-
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("list-style-type"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("list-style-position"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("list-style-image"));
-                    DEBUG_PRINTF("      -> Recreated list-style shorthand\n");
-                }
-            }
-        }
-    }
-
-    // Try to recreate font shorthand (requires at least font-size and font-family)
-    {
-        VALUE size = rb_hash_aref(properties_hash, STR_NEW_CSTR("font-size"));
-        VALUE family = rb_hash_aref(properties_hash, STR_NEW_CSTR("font-family"));
-
-        if (!NIL_P(size) && !NIL_P(family)) {
-            VALUE style = rb_hash_aref(properties_hash, STR_NEW_CSTR("font-style"));
-            VALUE variant = rb_hash_aref(properties_hash, STR_NEW_CSTR("font-variant"));
-            VALUE weight = rb_hash_aref(properties_hash, STR_NEW_CSTR("font-weight"));
-            VALUE line_height = rb_hash_aref(properties_hash, STR_NEW_CSTR("line-height"));
-
-            // Check all font properties have same !important flag
-            VALUE size_imp = RARRAY_AREF(size, PROP_IMPORTANT);
-            VALUE family_imp = RARRAY_AREF(family, PROP_IMPORTANT);
-
-            int same_importance = (RTEST(size_imp) == RTEST(family_imp));
-            if (!NIL_P(style)) same_importance = same_importance && (RTEST(size_imp) == RTEST(RARRAY_AREF(style, PROP_IMPORTANT)));
-            if (!NIL_P(variant)) same_importance = same_importance && (RTEST(size_imp) == RTEST(RARRAY_AREF(variant, PROP_IMPORTANT)));
-            if (!NIL_P(weight)) same_importance = same_importance && (RTEST(size_imp) == RTEST(RARRAY_AREF(weight, PROP_IMPORTANT)));
-            if (!NIL_P(line_height)) same_importance = same_importance && (RTEST(size_imp) == RTEST(RARRAY_AREF(line_height, PROP_IMPORTANT)));
-
-            if (same_importance) {
-                VALUE props = rb_hash_new();
-                rb_hash_aset(props, STR_NEW_CSTR("font-size"), RARRAY_AREF(size, PROP_VALUE));
-                rb_hash_aset(props, STR_NEW_CSTR("font-family"), RARRAY_AREF(family, PROP_VALUE));
-                if (!NIL_P(style)) rb_hash_aset(props, STR_NEW_CSTR("font-style"), RARRAY_AREF(style, PROP_VALUE));
-                if (!NIL_P(variant)) rb_hash_aset(props, STR_NEW_CSTR("font-variant"), RARRAY_AREF(variant, PROP_VALUE));
-                if (!NIL_P(weight)) rb_hash_aset(props, STR_NEW_CSTR("font-weight"), RARRAY_AREF(weight, PROP_VALUE));
-                if (!NIL_P(line_height)) rb_hash_aset(props, STR_NEW_CSTR("line-height"), RARRAY_AREF(line_height, PROP_VALUE));
-
-                VALUE shorthand_value = cataract_create_font_shorthand(Qnil, props);
-                if (!NIL_P(shorthand_value)) {
-                    VALUE shorthand_data = rb_ary_new_capa(4);
-                    rb_ary_push(shorthand_data, RARRAY_AREF(size, PROP_SOURCE_ORDER));
-                    rb_ary_push(shorthand_data, RARRAY_AREF(size, PROP_SPECIFICITY));
-                    rb_ary_push(shorthand_data, size_imp);
-                    rb_ary_push(shorthand_data, shorthand_value);
-                    rb_hash_aset(properties_hash, USASCII_STR("font"), shorthand_data);
-
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("font-size"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("font-family"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("font-style"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("font-variant"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("font-weight"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("line-height"));
-                    DEBUG_PRINTF("      -> Recreated font shorthand\n");
-                }
-            }
-        }
-    }
-
-    // Try to recreate background shorthand (if 2+ properties present)
-    {
-        VALUE color = rb_hash_aref(properties_hash, STR_NEW_CSTR("background-color"));
-        VALUE image = rb_hash_aref(properties_hash, STR_NEW_CSTR("background-image"));
-        VALUE repeat = rb_hash_aref(properties_hash, STR_NEW_CSTR("background-repeat"));
-        VALUE position = rb_hash_aref(properties_hash, STR_NEW_CSTR("background-position"));
-        VALUE attachment = rb_hash_aref(properties_hash, STR_NEW_CSTR("background-attachment"));
-
-        int bg_count = 0;
-        if (!NIL_P(color)) bg_count++;
-        if (!NIL_P(image)) bg_count++;
-        if (!NIL_P(repeat)) bg_count++;
-        if (!NIL_P(position)) bg_count++;
-        if (!NIL_P(attachment)) bg_count++;
-
-        // Need at least 2 properties to create shorthand
-        if (bg_count >= 2) {
-            // Check all have same !important flag
-            VALUE first_imp = Qnil;
-            if (!NIL_P(color)) first_imp = RARRAY_AREF(color, PROP_IMPORTANT);
-            else if (!NIL_P(image)) first_imp = RARRAY_AREF(image, PROP_IMPORTANT);
-            else if (!NIL_P(repeat)) first_imp = RARRAY_AREF(repeat, PROP_IMPORTANT);
-            else if (!NIL_P(position)) first_imp = RARRAY_AREF(position, PROP_IMPORTANT);
-            else if (!NIL_P(attachment)) first_imp = RARRAY_AREF(attachment, PROP_IMPORTANT);
-
-            int same_importance = 1;
-            if (!NIL_P(color)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(color, PROP_IMPORTANT)));
-            if (!NIL_P(image)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(image, PROP_IMPORTANT)));
-            if (!NIL_P(repeat)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(repeat, PROP_IMPORTANT)));
-            if (!NIL_P(position)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(position, PROP_IMPORTANT)));
-            if (!NIL_P(attachment)) same_importance = same_importance && (RTEST(first_imp) == RTEST(RARRAY_AREF(attachment, PROP_IMPORTANT)));
-
-            if (same_importance) {
-                VALUE props = rb_hash_new();
-                if (!NIL_P(color)) rb_hash_aset(props, STR_NEW_CSTR("background-color"), RARRAY_AREF(color, PROP_VALUE));
-                if (!NIL_P(image)) rb_hash_aset(props, STR_NEW_CSTR("background-image"), RARRAY_AREF(image, PROP_VALUE));
-                if (!NIL_P(repeat)) rb_hash_aset(props, STR_NEW_CSTR("background-repeat"), RARRAY_AREF(repeat, PROP_VALUE));
-                if (!NIL_P(position)) rb_hash_aset(props, STR_NEW_CSTR("background-position"), RARRAY_AREF(position, PROP_VALUE));
-                if (!NIL_P(attachment)) rb_hash_aset(props, STR_NEW_CSTR("background-attachment"), RARRAY_AREF(attachment, PROP_VALUE));
-
-                VALUE shorthand_value = cataract_create_background_shorthand(Qnil, props);
-                if (!NIL_P(shorthand_value)) {
-                    VALUE first_prop = !NIL_P(color) ? color : (!NIL_P(image) ? image : (!NIL_P(repeat) ? repeat : (!NIL_P(position) ? position : attachment)));
-                    VALUE shorthand_data = rb_ary_new_capa(4);
-                    rb_ary_push(shorthand_data, RARRAY_AREF(first_prop, PROP_SOURCE_ORDER));
-                    rb_ary_push(shorthand_data, RARRAY_AREF(first_prop, PROP_SPECIFICITY));
-                    rb_ary_push(shorthand_data, first_imp);
-                    rb_ary_push(shorthand_data, shorthand_value);
-                    rb_hash_aset(properties_hash, USASCII_STR("background"), shorthand_data);
-
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("background-color"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("background-image"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("background-repeat"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("background-position"));
-                    rb_hash_delete(properties_hash, STR_NEW_CSTR("background-attachment"));
-                    DEBUG_PRINTF("      -> Recreated background shorthand\n");
-                }
-            }
-        }
+    // Try to recreate family shorthands (border, font, list-style, background) using the mapping table
+    for (size_t i = 0; i < NUM_SHORTHAND_FAMILIES; i++) {
+        try_recreate_shorthand_family(properties_hash, &SHORTHAND_FAMILY_MAPPINGS[i]);
     }
 
     // Build declarations array from properties_hash
@@ -1311,6 +1083,104 @@ static void update_selector_lists_for_divergence(VALUE merged_rules, VALUE selec
     DEBUG_PRINTF("\n=== End divergence tracking: %ld selector lists preserved ===\n\n", RHASH_SIZE(selector_lists));
 }
 
+// Build a map from rule_id -> media_query_id for all Rule (non-AtRule)
+// entries that have one set. Used to group rules by (selector, media)
+// instead of just selector, and later to remap the stylesheet's media_index
+// after flattening.
+//
+// @param out_input_media_index Output: the input Stylesheet's @media_index
+//   ivar (Qnil if input isn't a Stylesheet), needed by the caller for
+//   remap_media_index_callback
+static VALUE build_rule_media_map(VALUE input, VALUE rules_array, long num_rules, VALUE *out_input_media_index) {
+    VALUE rule_media_map = rb_hash_new();
+    *out_input_media_index = Qnil;
+
+    if (!rb_obj_is_kind_of(input, cStylesheet)) {
+        return rule_media_map;
+    }
+
+    *out_input_media_index = rb_ivar_get(input, id_ivar_media_index);
+
+    // Only process Rule objects, not AtRules (AtRules don't have media_query_id field at same offset)
+    for (long i = 0; i < num_rules; i++) {
+        VALUE rule = rb_ary_entry(rules_array, i);
+        if (!rb_obj_is_kind_of(rule, cAtRule)) {
+            VALUE media_query_id = rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
+            if (!NIL_P(media_query_id)) {
+                VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
+                rb_hash_aset(rule_media_map, rule_id, media_query_id);
+            }
+        }
+    }
+
+    return rule_media_map;
+}
+
+// Group rules by (selector, media) - not just selector - since rules with
+// the same selector but different media contexts must NOT be merged
+// together. AtRule entries (e.g. @keyframes, @font-face) have no
+// declarations to merge and can't be grouped this way at all, so they're
+// collected separately into passthrough_rules and passed through unchanged.
+//
+// @param passthrough_rules Output: empty array to populate with AtRule entries
+// @return Hash of [selector, media_context] => Array of rule indices
+static VALUE group_rules_by_selector_and_media(VALUE rules_array, long num_rules, VALUE rule_media_map, VALUE passthrough_rules) {
+    VALUE selector_groups = rb_hash_new();
+
+    for (long i = 0; i < num_rules; i++) {
+        VALUE rule = RARRAY_AREF(rules_array, i);
+
+        // Handle AtRule objects (@keyframes, @font-face, etc.) - pass through unchanged
+        // AtRule has 'content' (string) instead of 'declarations' (array)
+        if (rb_obj_is_kind_of(rule, cAtRule)) {
+            DEBUG_PRINTF("  [Rule %ld] PASSTHROUGH: AtRule (e.g., @keyframes, @font-face)\n", i);
+            rb_ary_push(passthrough_rules, rule);
+            continue;
+        }
+
+        VALUE declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
+        VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
+        VALUE rule_id_val = rb_struct_aref(rule, INT2FIX(RULE_ID));
+
+        // Skip empty rules (no declarations)
+        // This handles both empty containers and rules with no properties
+        if (RARRAY_LEN(declarations) == 0) {
+            DEBUG_PRINTF("  [Rule %ld] SKIP: selector='%s' (empty declarations)\n",
+                         i, RSTRING_PTR(selector));
+            continue;
+        }
+
+        // Note: We do NOT skip parent rules that have children!
+        // Per CSS spec, parent can have its own declarations AND nested rules.
+        // Example: .parent { color: red; .child { color: blue; } }
+        // Should output both .parent (color: red) and .parent .child (color: blue)
+        // The nesting is already flattened during parsing, so they have different selectors.
+
+        // Get media context for this rule (nil if not in media query)
+        VALUE media_context = rb_hash_aref(rule_media_map, rule_id_val);
+
+        // Build grouping key as [selector, media_context]
+        VALUE group_key = rb_ary_new3(2, selector, media_context);
+
+        DEBUG_PRINTF("  [Rule %ld] ADD: selector='%s', media=%s, %ld declarations\n",
+                     i, RSTRING_PTR(selector),
+                     NIL_P(media_context) ? "nil" : RSTRING_PTR(rb_inspect(media_context)),
+                     RARRAY_LEN(declarations));
+
+        VALUE group = rb_hash_aref(selector_groups, group_key);
+        if (NIL_P(group)) {
+            group = rb_ary_new();
+            rb_hash_aset(selector_groups, group_key, group);
+            DEBUG_PRINTF("    -> Created new selector+media group for '%s' + %s\n",
+                        RSTRING_PTR(selector),
+                        NIL_P(media_context) ? "nil" : RSTRING_PTR(rb_inspect(media_context)));
+        }
+        rb_ary_push(group, LONG2FIX(i));
+    }
+
+    return selector_groups;
+}
+
 // Flatten CSS rules by applying cascade rules
 // Input: Stylesheet object or CSS string
 // Output: Stylesheet with flattened declarations (cascade applied)
@@ -1334,13 +1204,6 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
 
     Check_Type(rules_array, T_ARRAY);
 
-    // Check if stylesheet has nesting (affects selector rollup)
-    int has_nesting = 0;
-    if (rb_obj_is_kind_of(input, cStylesheet)) {
-        VALUE has_nesting_ivar = rb_ivar_get(input, rb_intern("@_has_nesting"));
-        has_nesting = RTEST(has_nesting_ivar);
-    }
-
     long num_rules = RARRAY_LEN(rules_array);
     // Empty stylesheets are rare
     if (num_rules == 0) {
@@ -1421,107 +1284,16 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
      * ============================================================================
      */
 
-    // For nested CSS: identify parent rules (rules that have children)
-    // These should be skipped during flatten, even if they have declarations
-    // Use Ruby hash as a set: parent_id => true
-    VALUE parent_ids = Qnil;
-    if (has_nesting) {
-        DEBUG_PRINTF("\n=== FLATTEN: has_nesting=true, num_rules=%ld ===\n", num_rules);
-        parent_ids = rb_hash_new();
-        for (long i = 0; i < num_rules; i++) {
-            VALUE rule = RARRAY_AREF(rules_array, i);
-            VALUE parent_rule_id = rb_struct_aref(rule, INT2FIX(RULE_PARENT_RULE_ID));
-            DEBUG_PRINTF("  Rule %ld: selector='%s', rule_id=%d, parent_rule_id=%s\n",
-                         i,
-                         RSTRING_PTR(rb_struct_aref(rule, INT2FIX(RULE_SELECTOR))),
-                         FIX2INT(rb_struct_aref(rule, INT2FIX(RULE_ID))),
-                         NIL_P(parent_rule_id) ? "nil" : RSTRING_PTR(rb_inspect(parent_rule_id)));
-            if (!NIL_P(parent_rule_id)) {
-                // This rule has a parent, so mark that parent ID
-                rb_hash_aset(parent_ids, parent_rule_id, Qtrue);
-            }
-        }
-    }
-
     // Build rule_media_map: rule_id => media_query_id
     // This is used to group rules by (selector, media) instead of just selector
     VALUE input_media_index = Qnil;
-    VALUE rule_media_map = rb_hash_new();
-    if (rb_obj_is_kind_of(input, cStylesheet)) {
-        input_media_index = rb_ivar_get(input, id_ivar_media_index);
-
-        // Build map from rules' media_query_id field
-        // Only process Rule objects, not AtRules (AtRules don't have media_query_id field at same offset)
-        for (long i = 0; i < num_rules; i++) {
-            VALUE rule = rb_ary_entry(rules_array, i);
-            if (!rb_obj_is_kind_of(rule, cAtRule)) {
-                VALUE media_query_id = rb_struct_aref(rule, INT2FIX(RULE_MEDIA_QUERY_ID));
-                if (!NIL_P(media_query_id)) {
-                    VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
-                    // Store media_query_id as the grouping key
-                    rb_hash_aset(rule_media_map, rule_id, media_query_id);
-                }
-            }
-        }
-    }
+    VALUE rule_media_map = build_rule_media_map(input, rules_array, num_rules, &input_media_index);
 
     // Group rules by (selector, media) instead of just selector
     // Rules with same selector but different media contexts should NOT be merged
-    // selector_and_media_key => [rule indices]
-    DEBUG_PRINTF("\n=== Building selector+media groups (has_nesting=%d) ===\n", has_nesting);
-    VALUE selector_groups = rb_hash_new();
+    DEBUG_PRINTF("\n=== Building selector+media groups ===\n");
     VALUE passthrough_rules = rb_ary_new(); // AtRules to pass through unchanged
-
-    for (long i = 0; i < num_rules; i++) {
-        VALUE rule = RARRAY_AREF(rules_array, i);
-
-        // Handle AtRule objects (@keyframes, @font-face, etc.) - pass through unchanged
-        // AtRule has 'content' (string) instead of 'declarations' (array)
-        if (rb_obj_is_kind_of(rule, cAtRule)) {
-            DEBUG_PRINTF("  [Rule %ld] PASSTHROUGH: AtRule (e.g., @keyframes, @font-face)\n", i);
-            rb_ary_push(passthrough_rules, rule);
-            continue;
-        }
-
-        VALUE declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
-        VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
-        VALUE rule_id_val = rb_struct_aref(rule, INT2FIX(RULE_ID));
-
-        // Skip empty rules (no declarations)
-        // This handles both empty containers and rules with no properties
-        if (RARRAY_LEN(declarations) == 0) {
-            DEBUG_PRINTF("  [Rule %ld] SKIP: selector='%s' (empty declarations)\n",
-                         i, RSTRING_PTR(selector));
-            continue;
-        }
-
-        // Note: We do NOT skip parent rules that have children!
-        // Per CSS spec, parent can have its own declarations AND nested rules.
-        // Example: .parent { color: red; .child { color: blue; } }
-        // Should output both .parent (color: red) and .parent .child (color: blue)
-        // The nesting is already flattened during parsing, so they have different selectors.
-
-        // Get media context for this rule (nil if not in media query)
-        VALUE media_context = rb_hash_aref(rule_media_map, rule_id_val);
-
-        // Build grouping key as [selector, media_context]
-        VALUE group_key = rb_ary_new3(2, selector, media_context);
-
-        DEBUG_PRINTF("  [Rule %ld] ADD: selector='%s', media=%s, %ld declarations\n",
-                     i, RSTRING_PTR(selector),
-                     NIL_P(media_context) ? "nil" : RSTRING_PTR(rb_inspect(media_context)),
-                     RARRAY_LEN(declarations));
-
-        VALUE group = rb_hash_aref(selector_groups, group_key);
-        if (NIL_P(group)) {
-            group = rb_ary_new();
-            rb_hash_aset(selector_groups, group_key, group);
-            DEBUG_PRINTF("    -> Created new selector+media group for '%s' + %s\n",
-                        RSTRING_PTR(selector),
-                        NIL_P(media_context) ? "nil" : RSTRING_PTR(rb_inspect(media_context)));
-        }
-        rb_ary_push(group, LONG2FIX(i));
-    }
+    VALUE selector_groups = group_rules_by_selector_and_media(rules_array, num_rules, rule_media_map, passthrough_rules);
     DEBUG_PRINTF("=== Total selector+media groups: %ld ===\n\n", RHASH_SIZE(selector_groups));
 
     // ALWAYS group by selector and keep them separate
@@ -1559,9 +1331,7 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
         }
 
         return passthrough_sheet;
-    }
-
-    if (RHASH_SIZE(selector_groups) > 0) {
+    } else {
         DEBUG_PRINTF("  -> Taking SELECTOR-GROUPED path (%ld unique selectors)\n",
                      RHASH_SIZE(selector_groups));
         VALUE merged_sheet = rb_class_new_instance(0, NULL, cStylesheet);
@@ -1665,486 +1435,4 @@ VALUE cataract_flatten(VALUE self, VALUE input) {
         return merged_sheet;
     }
 
-    // Single-merge path: merge all rules into one
-    VALUE properties_hash = rb_hash_new();
-
-    // Track selector for rollup (minimize allocations)
-    // Store pointer + length to first non-parent selector
-    // Also keep the VALUE alive since we extract C pointer before allocations
-    const char *first_selector_ptr = NULL;
-    long first_selector_len = 0;
-    VALUE first_selector_value = Qnil;
-    int all_same_selector = 1;
-
-    // Track source order for cascade rules
-    long source_order = 0;
-
-    // Iterate through each rule
-    for (long i = 0; i < num_rules; i++) {
-        VALUE rule = RARRAY_AREF(rules_array, i);
-        Check_Type(rule, T_STRUCT);
-
-        // Extract rule fields
-        VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
-        VALUE selector = rb_struct_aref(rule, INT2FIX(RULE_SELECTOR));
-        VALUE declarations = rb_struct_aref(rule, INT2FIX(RULE_DECLARATIONS));
-
-        // Skip parent rules when handling nested CSS
-        // Example: .button { color: black; &:hover { color: red; } }
-        //   - Rule id=0, selector=".button", declarations=[color: black] (SKIP - has children)
-        //   - Rule id=1, selector=".button:hover", declarations=[color: red] (PROCESS)
-        if (has_nesting && !NIL_P(parent_ids)) {
-            VALUE is_parent = rb_hash_aref(parent_ids, rule_id);
-            if (RTEST(is_parent)) {
-                continue;
-            }
-        }
-
-        long num_decls = RARRAY_LEN(declarations);
-        // Skip rules with no declarations (empty parent containers)
-        if (num_decls == 0) {
-            continue;
-        }
-
-        // Track selectors for rollup (delay allocation)
-        const char *sel_ptr = RSTRING_PTR(selector);
-        long sel_len = RSTRING_LEN(selector);
-        if (first_selector_ptr == NULL) {
-            first_selector_ptr = sel_ptr;
-            first_selector_len = sel_len;
-            first_selector_value = selector;  // Keep VALUE alive for RB_GC_GUARD
-        } else if (all_same_selector) {
-            if (sel_len != first_selector_len || memcmp(sel_ptr, first_selector_ptr, sel_len) != 0) {
-                all_same_selector = 0;
-            }
-        }
-
-        VALUE specificity_val = rb_struct_aref(rule, INT2FIX(RULE_SPECIFICITY));
-
-        // Calculate specificity if not provided (lazy)
-        int specificity = 0;
-        if (NIL_P(specificity_val)) {
-            specificity_val = calculate_specificity(Qnil, selector);
-            // Cache the calculated value back to the struct
-            rb_struct_aset(rule, INT2FIX(RULE_SPECIFICITY), specificity_val);
-        }
-        specificity = NUM2INT(specificity_val);
-
-        // Process each declaration in this rule
-        Check_Type(declarations, T_ARRAY);
-
-        for (long j = 0; j < num_decls; j++) {
-            VALUE decl = RARRAY_AREF(declarations, j);
-
-            // Extract property, value, important from Declaration struct
-            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));
-
-            // Properties are already lowercased during parsing (see cataract_new.c)
-            // No need to lowercase again
-            int is_important = RTEST(important);
-
-            // Expand shorthand properties if needed
-            // Most properties are NOT shorthands, so hint compiler accordingly
-            const char *prop_str = StringValueCStr(property);
-            VALUE expanded = Qnil;
-
-            // Early exit: shorthand properties only start with m, p, b, f, or l
-            char first_char = prop_str[0];
-            if (first_char == 'm' || first_char == 'p' || first_char == 'b' ||
-                first_char == 'f' || first_char == 'l') {
-                // Potentially a shorthand - check specific property names
-                if (strcmp(prop_str, "margin") == 0) {
-                    expanded = cataract_expand_margin(Qnil, value);
-                } else if (strcmp(prop_str, "padding") == 0) {
-                    expanded = cataract_expand_padding(Qnil, value);
-                } else if (strcmp(prop_str, "border") == 0) {
-                    expanded = cataract_expand_border(Qnil, value);
-                } else if (strcmp(prop_str, "border-color") == 0) {
-                    expanded = cataract_expand_border_color(Qnil, value);
-                } else if (strcmp(prop_str, "border-style") == 0) {
-                    expanded = cataract_expand_border_style(Qnil, value);
-                } else if (strcmp(prop_str, "border-width") == 0) {
-                    expanded = cataract_expand_border_width(Qnil, value);
-                } else if (strcmp(prop_str, "border-top") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, USASCII_STR("top"), value);
-                } else if (strcmp(prop_str, "border-right") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, USASCII_STR("right"), value);
-                } else if (strcmp(prop_str, "border-bottom") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, USASCII_STR("bottom"), value);
-                } else if (strcmp(prop_str, "border-left") == 0) {
-                    expanded = cataract_expand_border_side(Qnil, USASCII_STR("left"), value);
-                } else if (strcmp(prop_str, "font") == 0) {
-                    expanded = cataract_expand_font(Qnil, value);
-                } else if (strcmp(prop_str, "list-style") == 0) {
-                    expanded = cataract_expand_list_style(Qnil, value);
-                } else if (strcmp(prop_str, "background") == 0) {
-                    expanded = cataract_expand_background(Qnil, value);
-                }
-            }
-            // If first_char doesn't match, expanded stays Qnil
-
-            // If property was expanded, iterate array and apply cascade
-            // Expansion is rare (most properties are not shorthands)
-            if (!NIL_P(expanded)) {
-                Check_Type(expanded, T_ARRAY);
-
-                struct expand_context ctx;
-                ctx.properties_hash = properties_hash;
-                ctx.source_order = source_order;
-                ctx.specificity = specificity;
-                ctx.important = important;
-
-                long expanded_len = RARRAY_LEN(expanded);
-                for (long i = 0; i < expanded_len; i++) {
-                    VALUE decl = rb_ary_entry(expanded, i);
-                    VALUE prop = rb_struct_aref(decl, INT2FIX(DECL_PROPERTY));
-                    VALUE val = rb_struct_aref(decl, INT2FIX(DECL_VALUE));
-                    flatten_expanded_callback(prop, val, (VALUE)&ctx);
-                }
-
-                RB_GC_GUARD(expanded);
-                continue; // Skip processing the original shorthand property
-            }
-
-            // Apply CSS cascade rules
-            VALUE existing = rb_hash_aref(properties_hash, property);
-
-            // In merge scenarios, properties often collide (same property in multiple rules)
-            // so existing property is the common case
-            if (NIL_P(existing)) {
-                // New property - add it as array: [source_order, specificity, important, value]
-                VALUE prop_data = rb_ary_new_capa(4);
-                rb_ary_push(prop_data, LONG2NUM(source_order));
-                rb_ary_push(prop_data, INT2NUM(specificity));
-                rb_ary_push(prop_data, important);
-                rb_ary_push(prop_data, value);
-                rb_hash_aset(properties_hash, property, prop_data);
-            } else {
-                // Property exists - check cascade rules
-                long existing_order = NUM2LONG(RARRAY_AREF(existing, PROP_SOURCE_ORDER));
-                int existing_spec_int = NUM2INT(RARRAY_AREF(existing, PROP_SPECIFICITY));
-                VALUE existing_important = RARRAY_AREF(existing, PROP_IMPORTANT);
-                int existing_is_important = RTEST(existing_important);
-
-                int should_replace = 0;
-
-                // Most declarations are NOT !important
-                if (is_important) {
-                    // New is !important - wins if existing is NOT important OR higher specificity OR (equal specificity AND later order)
-                    if (!existing_is_important || existing_spec_int < specificity ||
-                        (existing_spec_int == specificity && existing_order <= source_order)) {
-                        should_replace = 1;
-                    }
-                } else {
-                    // New is NOT important - only wins if existing is also NOT important AND (higher specificity OR equal specificity with later order)
-                    if (!existing_is_important &&
-                        (existing_spec_int < specificity ||
-                         (existing_spec_int == specificity && existing_order <= source_order))) {
-                        should_replace = 1;
-                    }
-                }
-
-                // Replacement is common in merge scenarios
-                if (should_replace) {
-                    RARRAY_ASET(existing, PROP_SOURCE_ORDER, LONG2NUM(source_order));
-                    RARRAY_ASET(existing, PROP_SPECIFICITY, INT2NUM(specificity));
-                    RARRAY_ASET(existing, PROP_IMPORTANT, important);
-                    RARRAY_ASET(existing, PROP_VALUE, value);
-                }
-            }
-
-            RB_GC_GUARD(property);
-            RB_GC_GUARD(value);
-            RB_GC_GUARD(decl);
-            source_order++;
-        }
-
-        RB_GC_GUARD(selector);
-        RB_GC_GUARD(declarations);
-        RB_GC_GUARD(rule);
-    }
-
-    // Create shorthand from longhand properties
-    // Uses cached static strings to avoid runtime allocation
-
-    // Try to create margin shorthand
-    TRY_CREATE_FOUR_SIDED_SHORTHAND(properties_hash,
-        str_margin_top, str_margin_right, str_margin_bottom, str_margin_left,
-        str_margin, cataract_create_margin_shorthand);
-
-    // Try to create padding shorthand
-    TRY_CREATE_FOUR_SIDED_SHORTHAND(properties_hash,
-        str_padding_top, str_padding_right, str_padding_bottom, str_padding_left,
-        str_padding, cataract_create_padding_shorthand);
-
-    // Create border-width from individual sides
-    TRY_CREATE_FOUR_SIDED_SHORTHAND(properties_hash,
-        str_border_top_width, str_border_right_width, str_border_bottom_width, str_border_left_width,
-        str_border_width, cataract_create_border_width_shorthand);
-
-    // Create border-style from individual sides
-    TRY_CREATE_FOUR_SIDED_SHORTHAND(properties_hash,
-        str_border_top_style, str_border_right_style, str_border_bottom_style, str_border_left_style,
-        str_border_style, cataract_create_border_style_shorthand);
-
-    // Create border-color from individual sides
-    TRY_CREATE_FOUR_SIDED_SHORTHAND(properties_hash,
-        str_border_top_color, str_border_right_color, str_border_bottom_color, str_border_left_color,
-        str_border_color, cataract_create_border_color_shorthand);
-
-    // Now create border shorthand from border-{width,style,color}
-    VALUE border_width = GET_PROP_VALUE_STR(properties_hash, str_border_width);
-    VALUE border_style = GET_PROP_VALUE_STR(properties_hash, str_border_style);
-    VALUE border_color = GET_PROP_VALUE_STR(properties_hash, str_border_color);
-
-    if (!NIL_P(border_width) || !NIL_P(border_style) || !NIL_P(border_color)) {
-        // Use first available property's metadata as reference
-        VALUE border_data_src = !NIL_P(border_width) ? GET_PROP_DATA_STR(properties_hash, str_border_width) :
-                                !NIL_P(border_style) ? GET_PROP_DATA_STR(properties_hash, str_border_style) :
-                                GET_PROP_DATA_STR(properties_hash, str_border_color);
-        VALUE border_important = RARRAY_AREF(border_data_src, PROP_IMPORTANT);
-        int border_is_important = RTEST(border_important);
-
-        // Check that all present properties have the same !important flag
-        int important_match = CHECK_IMPORTANT_MATCH(properties_hash, str_border_width, border_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_border_style, border_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_border_color, border_is_important);
-
-        if (important_match) {
-            VALUE border_props = rb_hash_new();
-            if (!NIL_P(border_width)) rb_hash_aset(border_props, str_border_width, border_width);
-            if (!NIL_P(border_style)) rb_hash_aset(border_props, str_border_style, border_style);
-            if (!NIL_P(border_color)) rb_hash_aset(border_props, str_border_color, border_color);
-
-            VALUE border_shorthand = cataract_create_border_shorthand(Qnil, border_props);
-            if (!NIL_P(border_shorthand)) {
-                VALUE border_data = rb_ary_new_capa(4);
-                rb_ary_push(border_data, RARRAY_AREF(border_data_src, PROP_SOURCE_ORDER));
-                rb_ary_push(border_data, RARRAY_AREF(border_data_src, PROP_SPECIFICITY));
-                rb_ary_push(border_data, border_important);
-                rb_ary_push(border_data, border_shorthand);
-                rb_hash_aset(properties_hash, str_border, border_data);
-
-                if (!NIL_P(border_width)) rb_hash_delete(properties_hash, str_border_width);
-                if (!NIL_P(border_style)) rb_hash_delete(properties_hash, str_border_style);
-                if (!NIL_P(border_color)) rb_hash_delete(properties_hash, str_border_color);
-            }
-            RB_GC_GUARD(border_props);
-            RB_GC_GUARD(border_shorthand);
-        }
-    }
-
-    // Try to create font shorthand
-    VALUE font_size = GET_PROP_VALUE_STR(properties_hash, str_font_size);
-    VALUE font_family = GET_PROP_VALUE_STR(properties_hash, str_font_family);
-
-    // Font shorthand requires at least font-size and font-family
-    if (!NIL_P(font_size) && !NIL_P(font_family)) {
-        VALUE font_style = GET_PROP_VALUE_STR(properties_hash, str_font_style);
-        VALUE font_variant = GET_PROP_VALUE_STR(properties_hash, str_font_variant);
-        VALUE font_weight = GET_PROP_VALUE_STR(properties_hash, str_font_weight);
-        VALUE line_height = GET_PROP_VALUE_STR(properties_hash, str_line_height);
-
-        // Get metadata from font-size as reference
-        VALUE size_data = GET_PROP_DATA_STR(properties_hash, str_font_size);
-        VALUE font_important = RARRAY_AREF(size_data, PROP_IMPORTANT);
-        int font_is_important = RTEST(font_important);
-
-        // Check that all present properties have the same !important flag
-        int important_match = CHECK_IMPORTANT_MATCH(properties_hash, str_font_style, font_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_font_variant, font_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_font_weight, font_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_line_height, font_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_font_family, font_is_important);
-
-        if (important_match) {
-            VALUE font_props = rb_hash_new();
-            if (!NIL_P(font_style)) rb_hash_aset(font_props, str_font_style, font_style);
-            if (!NIL_P(font_variant)) rb_hash_aset(font_props, str_font_variant, font_variant);
-            if (!NIL_P(font_weight)) rb_hash_aset(font_props, str_font_weight, font_weight);
-            rb_hash_aset(font_props, str_font_size, font_size);
-            if (!NIL_P(line_height)) rb_hash_aset(font_props, str_line_height, line_height);
-            rb_hash_aset(font_props, str_font_family, font_family);
-
-            VALUE font_shorthand = cataract_create_font_shorthand(Qnil, font_props);
-            if (!NIL_P(font_shorthand)) {
-                VALUE font_data = rb_ary_new_capa(4);
-                rb_ary_push(font_data, RARRAY_AREF(size_data, PROP_SOURCE_ORDER));
-                rb_ary_push(font_data, RARRAY_AREF(size_data, PROP_SPECIFICITY));
-                rb_ary_push(font_data, font_important);
-                rb_ary_push(font_data, font_shorthand);
-                rb_hash_aset(properties_hash, str_font, font_data);
-
-                // Remove longhand properties
-                if (!NIL_P(font_style)) rb_hash_delete(properties_hash, str_font_style);
-                if (!NIL_P(font_variant)) rb_hash_delete(properties_hash, str_font_variant);
-                if (!NIL_P(font_weight)) rb_hash_delete(properties_hash, str_font_weight);
-                rb_hash_delete(properties_hash, str_font_size);
-                if (!NIL_P(line_height)) rb_hash_delete(properties_hash, str_line_height);
-                rb_hash_delete(properties_hash, str_font_family);
-            }
-            RB_GC_GUARD(font_props);
-            RB_GC_GUARD(font_shorthand);
-        }
-    }
-
-    // Try to create list-style shorthand
-    VALUE list_style_type = GET_PROP_VALUE_STR(properties_hash, str_list_style_type);
-    VALUE list_style_position = GET_PROP_VALUE_STR(properties_hash, str_list_style_position);
-    VALUE list_style_image = GET_PROP_VALUE_STR(properties_hash, str_list_style_image);
-
-    // List-style shorthand requires at least 2 properties
-    int list_style_count = (!NIL_P(list_style_type) ? 1 : 0) +
-                           (!NIL_P(list_style_position) ? 1 : 0) +
-                           (!NIL_P(list_style_image) ? 1 : 0);
-
-    if (list_style_count >= 2) {
-        // Use first available property's metadata as reference
-        VALUE list_style_data_src = !NIL_P(list_style_type) ? GET_PROP_DATA_STR(properties_hash, str_list_style_type) :
-                                    !NIL_P(list_style_position) ? GET_PROP_DATA_STR(properties_hash, str_list_style_position) :
-                                    GET_PROP_DATA_STR(properties_hash, str_list_style_image);
-        VALUE list_style_important = RARRAY_AREF(list_style_data_src, PROP_IMPORTANT);
-        int list_style_is_important = RTEST(list_style_important);
-
-        // Check that all present properties have the same !important flag
-        int important_match = CHECK_IMPORTANT_MATCH(properties_hash, str_list_style_type, list_style_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_list_style_position, list_style_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_list_style_image, list_style_is_important);
-
-        if (important_match) {
-            VALUE list_style_props = rb_hash_new();
-            if (!NIL_P(list_style_type)) rb_hash_aset(list_style_props, str_list_style_type, list_style_type);
-            if (!NIL_P(list_style_position)) rb_hash_aset(list_style_props, str_list_style_position, list_style_position);
-            if (!NIL_P(list_style_image)) rb_hash_aset(list_style_props, str_list_style_image, list_style_image);
-
-            VALUE list_style_shorthand = cataract_create_list_style_shorthand(Qnil, list_style_props);
-            if (!NIL_P(list_style_shorthand)) {
-                VALUE list_style_data = rb_ary_new_capa(4);
-                rb_ary_push(list_style_data, RARRAY_AREF(list_style_data_src, PROP_SOURCE_ORDER));
-                rb_ary_push(list_style_data, RARRAY_AREF(list_style_data_src, PROP_SPECIFICITY));
-                rb_ary_push(list_style_data, list_style_important);
-                rb_ary_push(list_style_data, list_style_shorthand);
-                rb_hash_aset(properties_hash, str_list_style, list_style_data);
-
-                // Remove longhand properties
-                if (!NIL_P(list_style_type)) rb_hash_delete(properties_hash, str_list_style_type);
-                if (!NIL_P(list_style_position)) rb_hash_delete(properties_hash, str_list_style_position);
-                if (!NIL_P(list_style_image)) rb_hash_delete(properties_hash, str_list_style_image);
-            }
-            RB_GC_GUARD(list_style_props);
-            RB_GC_GUARD(list_style_shorthand);
-        }
-    }
-
-    // Try to create background shorthand
-    VALUE background_color = GET_PROP_VALUE_STR(properties_hash, str_background_color);
-    VALUE background_image = GET_PROP_VALUE_STR(properties_hash, str_background_image);
-    VALUE background_repeat = GET_PROP_VALUE_STR(properties_hash, str_background_repeat);
-    VALUE background_attachment = GET_PROP_VALUE_STR(properties_hash, str_background_attachment);
-    VALUE background_position = GET_PROP_VALUE_STR(properties_hash, str_background_position);
-
-    // Background shorthand requires at least 2 properties
-    int background_count = (!NIL_P(background_color) ? 1 : 0) +
-                          (!NIL_P(background_image) ? 1 : 0) +
-                          (!NIL_P(background_repeat) ? 1 : 0) +
-                          (!NIL_P(background_attachment) ? 1 : 0) +
-                          (!NIL_P(background_position) ? 1 : 0);
-
-    if (background_count >= 2) {
-        // Use first available property's metadata as reference
-        VALUE background_data_src = !NIL_P(background_color) ? GET_PROP_DATA_STR(properties_hash, str_background_color) :
-                                   !NIL_P(background_image) ? GET_PROP_DATA_STR(properties_hash, str_background_image) :
-                                   !NIL_P(background_repeat) ? GET_PROP_DATA_STR(properties_hash, str_background_repeat) :
-                                   !NIL_P(background_attachment) ? GET_PROP_DATA_STR(properties_hash, str_background_attachment) :
-                                   GET_PROP_DATA_STR(properties_hash, str_background_position);
-        VALUE background_important = RARRAY_AREF(background_data_src, PROP_IMPORTANT);
-        int background_is_important = RTEST(background_important);
-
-        // Check that all present properties have the same !important flag
-        int important_match = CHECK_IMPORTANT_MATCH(properties_hash, str_background_color, background_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_background_image, background_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_background_repeat, background_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_background_attachment, background_is_important) &&
-                             CHECK_IMPORTANT_MATCH(properties_hash, str_background_position, background_is_important);
-
-        if (important_match) {
-            VALUE background_props = rb_hash_new();
-            if (!NIL_P(background_color)) rb_hash_aset(background_props, str_background_color, background_color);
-            if (!NIL_P(background_image)) rb_hash_aset(background_props, str_background_image, background_image);
-            if (!NIL_P(background_repeat)) rb_hash_aset(background_props, str_background_repeat, background_repeat);
-            if (!NIL_P(background_attachment)) rb_hash_aset(background_props, str_background_attachment, background_attachment);
-            if (!NIL_P(background_position)) rb_hash_aset(background_props, str_background_position, background_position);
-
-            VALUE background_shorthand = cataract_create_background_shorthand(Qnil, background_props);
-            if (!NIL_P(background_shorthand)) {
-                VALUE background_data = rb_ary_new_capa(4);
-                rb_ary_push(background_data, RARRAY_AREF(background_data_src, PROP_SOURCE_ORDER));
-                rb_ary_push(background_data, RARRAY_AREF(background_data_src, PROP_SPECIFICITY));
-                rb_ary_push(background_data, background_important);
-                rb_ary_push(background_data, background_shorthand);
-                rb_hash_aset(properties_hash, str_background, background_data);
-
-                // Remove longhand properties
-                if (!NIL_P(background_color)) rb_hash_delete(properties_hash, str_background_color);
-                if (!NIL_P(background_image)) rb_hash_delete(properties_hash, str_background_image);
-                if (!NIL_P(background_repeat)) rb_hash_delete(properties_hash, str_background_repeat);
-                if (!NIL_P(background_attachment)) rb_hash_delete(properties_hash, str_background_attachment);
-                if (!NIL_P(background_position)) rb_hash_delete(properties_hash, str_background_position);
-            }
-            RB_GC_GUARD(background_props);
-            RB_GC_GUARD(background_shorthand);
-        }
-    }
-
-    #undef GET_PROP_VALUE
-    #undef GET_PROP_DATA
-
-    // Build merged declarations array
-    VALUE merged_declarations = rb_ary_new();
-    rb_hash_foreach(properties_hash, flatten_build_result_callback, merged_declarations);
-
-    // Determine final selector (allocate only once at the end)
-    VALUE final_selector;
-    if (has_nesting && all_same_selector && first_selector_ptr != NULL) {
-        // All rules have same selector - use it for rollup
-        final_selector = rb_usascii_str_new(first_selector_ptr, first_selector_len);
-    } else {
-        // Mixed selectors or no nesting - use "merged"
-        final_selector = str_merged_selector;
-    }
-
-    // Create a new Stylesheet with a single merged rule
-    // Use rb_class_new_instance instead of rb_funcall for better performance
-    VALUE merged_sheet = rb_class_new_instance(0, NULL, cStylesheet);
-
-    // Create merged rule
-    VALUE merged_rule = rb_struct_new(cRule,
-        INT2FIX(0),              // id
-        final_selector,          // selector (rolled-up or "merged")
-        merged_declarations,      // declarations
-        Qnil,                     // specificity (not applicable)
-        Qnil,                     // parent_rule_id (not nested)
-        Qnil,                     // nesting_style (not nested)
-        Qnil,                     // selector_list_id
-        Qnil                      // media_query_id
-    );
-
-    // Set @rules array with single merged rule (use cached ID)
-    VALUE rules_ary = rb_ary_new_from_args(1, merged_rule);
-    rb_ivar_set(merged_sheet, id_ivar_rules, rules_ary);
-
-    // Set @media_index with :all pointing to rule 0 (use cached ID)
-    VALUE media_idx = rb_hash_new();
-    VALUE all_ids = rb_ary_new_from_args(1, INT2FIX(0));
-    rb_hash_aset(media_idx, ID2SYM(id_all), all_ids);
-    rb_ivar_set(merged_sheet, id_ivar_media_index, media_idx);
-
-    // Guard first_selector_value: C pointer extracted via RSTRING_PTR during iteration,
-    // then used after many allocations (hash operations, shorthand expansions) when
-    // creating final_selector with rb_usascii_str_new
-    RB_GC_GUARD(first_selector_value);
-
-    return merged_sheet;
 }