cataract 0.2.3 → 0.2.4

data/lib/cataract/pure/serializer.rb

@@ -2,17 +2,52 @@
 
 # Pure Ruby CSS parser - Serialization methods
 # NO REGEXP ALLOWED - char-by-char parsing only
+#
+# @api private
+# This module contains internal serialization methods for converting parsed CSS
+# back to strings. These methods are called by Stylesheet#to_s and should not be
+# used directly. The public API is through the Stylesheet class.
 
 module Cataract
+  # @api private
+  # Helper: Build media query string from MediaQuery object or list
+  # @param media_query [MediaQuery] The MediaQuery object
+  # @param media_query_list_id [Integer, nil] Optional list ID if this is part of a comma-separated list
+  # @param media_query_lists [Hash] Hash mapping list_id => array of MediaQuery IDs
+  # @param media_queries [Array] Array of all MediaQuery objects
+  # @return [String] Serialized media query string (e.g., "screen", "screen, print", "screen and (min-width: 768px)")
+  def self._build_media_query_string(media_query, media_query_list_id, media_query_lists, media_queries)
+    if media_query_list_id
+      # Comma-separated list
+      mq_ids = media_query_lists[media_query_list_id]
+      mq_ids.map do |mq_id|
+        mq = media_queries[mq_id]
+        if mq.conditions
+          mq.type == :all ? mq.conditions : "#{mq.type} and #{mq.conditions}"
+        else
+          mq.type.to_s
+        end
+      end.join(', ')
+    else
+      # Single query
+      if media_query.conditions
+        media_query.type == :all ? media_query.conditions : "#{media_query.type} and #{media_query.conditions}"
+      else
+        media_query.type.to_s
+      end
+    end
+  end
+
   # Serialize stylesheet to compact CSS string
   #
   # @param rules [Array<Rule>] Array of rules
-  # @param media_index [Hash] Media query symbol => array of rule IDs
   # @param charset [String, nil] @charset value
   # @param has_nesting [Boolean] Whether any nested rules exist
   # @param selector_lists [Hash] Selector list ID => array of rule IDs (for grouping)
+  # @param media_queries [Array<MediaQuery>] Array of MediaQuery objects (optional, for proper serialization)
+  # @param media_query_lists [Hash] List ID => array of MediaQuery IDs (optional, for comma-separated queries)
   # @return [String] Compact CSS string
-  def self._stylesheet_to_s(rules, media_index, charset, has_nesting, selector_lists = {})
+  def self.stylesheet_to_s(rules, charset, has_nesting, selector_lists = {}, media_queries = [], media_query_lists = {})
     result = +''
 
     # Add @charset if present
@@ -22,7 +57,7 @@ module Cataract
 
     # Fast path: no nesting - use simple algorithm
     unless has_nesting
-      return stylesheet_to_s_original(rules, media_index, result, selector_lists)
+      return _stylesheet_to_s_without_nesting(rules, result, selector_lists, media_queries, media_query_lists)
     end
 
     # Build parent-child relationships
@@ -35,44 +70,60 @@ module Cataract
       rule_children[parent_id] << rule
     end
 
-    # Build rule_id => media_symbol map
-    rule_to_media = {}
-    media_index.each do |media_sym, rule_ids|
-      rule_ids.each do |rule_id|
-        rule_to_media[rule_id] = media_sym
-      end
+    # Build reverse map: media_query_id => list_id
+    mq_id_to_list_id = {}
+    media_query_lists.each do |list_id, mq_ids|
+      mq_ids.each { |mq_id| mq_id_to_list_id[mq_id] = list_id }
     end
 
     # Serialize top-level rules only (those without parent_rule_id)
-    current_media = nil
+    current_media_query_list_id = nil
+    current_media_query = nil
     in_media_block = false
 
     rules.each do |rule|
       # Skip rules that have a parent (they'll be serialized as nested)
       next if rule.parent_rule_id
 
-      rule_media = rule_to_media[rule.id]
+      rule_media_query_id = rule.is_a?(Rule) ? rule.media_query_id : nil
+      rule_media_query = rule_media_query_id ? media_queries[rule_media_query_id] : nil
+      rule_media_query_list_id = rule_media_query_id ? mq_id_to_list_id[rule_media_query_id] : nil
 
-      if rule_media.nil?
+      if rule_media_query.nil?
         # Close any open media block
         if in_media_block
           result << "}\n"
           in_media_block = false
-          current_media = nil
+          current_media_query = nil
+          current_media_query_list_id = nil
         end
       else
-        # Media query
-        if current_media.nil? || current_media != rule_media
+        # Check if we need to open a new media block
+        # For lists: compare list_id
+        # For single queries: compare by content (type + conditions)
+        needs_new_block = if rule_media_query_list_id
+                            current_media_query_list_id != rule_media_query_list_id
+                          else
+                            !current_media_query ||
+                              current_media_query.type != rule_media_query.type ||
+                              current_media_query.conditions != rule_media_query.conditions
+                          end
+
+        if needs_new_block
           if in_media_block
             result << "}\n"
           end
-          current_media = rule_media
-          result << "@media #{current_media} {\n"
+          current_media_query = rule_media_query
+          current_media_query_list_id = rule_media_query_list_id
+
+          # Serialize the media query (or list)
+          media_query_string = _build_media_query_string(rule_media_query, rule_media_query_list_id, media_query_lists, media_queries)
+          result << "@media #{media_query_string} {\n"
           in_media_block = true
         end
       end
 
-      serialize_rule_with_nesting(result, rule, rule_children, rule_to_media)
+      _serialize_rule_with_nesting(result, rule, rule_children, media_queries)
     end
 
     if in_media_block
@@ -83,12 +134,13 @@ module Cataract
   end
 
   # Helper: serialize rules without nesting support (compact format)
-  def self.stylesheet_to_s_original(rules, media_index, result, selector_lists)
+  def self._stylesheet_to_s_without_nesting(rules, result, selector_lists, media_queries = [], media_query_lists = {})
     _serialize_stylesheet_with_grouping(
       rules: rules,
-      media_index: media_index,
       result: result,
       selector_lists: selector_lists,
+      media_queries: media_queries,
+      media_query_lists: media_query_lists,
       opening_brace: ' { ',
       closing_brace: " }\n",
       media_indent: '',
@@ -99,14 +151,14 @@ module Cataract
   end
 
   # Helper: serialize a rule with its nested children
-  def self.serialize_rule_with_nesting(result, rule, rule_children, rule_to_media)
+  def self._serialize_rule_with_nesting(result, rule, rule_children, media_queries)
     # Start selector
     result << "#{rule.selector} { "
 
     # Serialize declarations
     has_declarations = !rule.declarations.empty?
     if has_declarations
-      serialize_declarations(result, rule.declarations)
+      _serialize_declarations(result, rule.declarations)
     end
 
     # Get nested children for this rule
@@ -122,27 +174,32 @@ module Cataract
       end
 
       # Determine if we need to reconstruct the nested selector with &
-      nested_selector = reconstruct_nested_selector(rule.selector, child.selector, child.nesting_style)
+      nested_selector = _reconstruct_nested_selector(rule.selector, child.selector, child.nesting_style)
 
       # Check if this child has @media nesting (parent_rule_id present but nesting_style is nil)
-      if child.nesting_style.nil? && rule_to_media[child.id]
+      if child.nesting_style.nil? && child.media_query_id && media_queries[child.media_query_id]
         # This is a nested @media rule
-        media_sym = rule_to_media[child.id]
-        result << "@media #{media_sym} { "
-        serialize_declarations(result, child.declarations)
+        mq = media_queries[child.media_query_id]
+        media_query_string = if mq.conditions
+                               mq.type == :all ? mq.conditions : "#{mq.type} and #{mq.conditions}"
+                             else
+                               mq.type.to_s
+                             end
+        result << "@media #{media_query_string} { "
+        _serialize_declarations(result, child.declarations)
 
         # Recursively serialize any children of this @media rule
         media_children = rule_children[child.id] || []
         media_children.each_with_index do |media_child, media_idx|
           result << ' ' if media_idx > 0 || !child.declarations.empty?
 
-          nested_media_selector = reconstruct_nested_selector(
+          nested_media_selector = _reconstruct_nested_selector(
             child.selector, media_child.selector,
             media_child.nesting_style
           )
 
           result << "#{nested_media_selector} { "
-          serialize_declarations(result, media_child.declarations)
+          _serialize_declarations(result, media_child.declarations)
           result << ' }'
         end
 
@@ -150,21 +207,21 @@ module Cataract
       else
         # Regular nested selector
         result << "#{nested_selector} { "
-        serialize_declarations(result, child.declarations)
+        _serialize_declarations(result, child.declarations)
 
         # Recursively serialize any children of this nested rule
         grandchildren = rule_children[child.id] || []
         grandchildren.each_with_index do |grandchild, grandchild_idx|
           result << ' ' if grandchild_idx > 0 || !child.declarations.empty?
 
-          nested_grandchild_selector = reconstruct_nested_selector(
+          nested_grandchild_selector = _reconstruct_nested_selector(
             child.selector,
             grandchild.selector,
             grandchild.nesting_style
           )
 
           result << "#{nested_grandchild_selector} { "
-          serialize_declarations(result, grandchild.declarations)
+          _serialize_declarations(result, grandchild.declarations)
           result << ' }'
         end
 
@@ -178,7 +235,7 @@ module Cataract
   # Reconstruct nested selector representation
   # If nesting_style == 1 (explicit), try to use & notation
   # If nesting_style == 0 (implicit), use plain selector
-  def self.reconstruct_nested_selector(parent_selector, child_selector, nesting_style)
+  def self._reconstruct_nested_selector(parent_selector, child_selector, nesting_style)
     return child_selector if nesting_style.nil?
 
     if nesting_style == 1 # NESTING_STYLE_EXPLICIT
@@ -204,7 +261,7 @@ module Cataract
 
   # Helper: find all selectors from same list with matching declarations
   # Returns array of selectors that can be grouped, marks rules as processed
-  def self.find_groupable_selectors(rule:, rules:, selector_lists:, processed_rule_ids:, rule_to_media:, current_media:)
+  def self._find_groupable_selectors(rule:, rules:, selector_lists:, processed_rule_ids:, current_media_query_id:)
     list_id = rule.selector_list_id
     rule_ids_in_list = selector_lists[list_id]
 
@@ -217,16 +274,16 @@ module Cataract
     # Find all rules in this list that have identical declarations AND same media context
     matching_selectors = []
     rule_ids_in_list.each do |rid|
-      # Find the rule by ID
-      other_rule = rules.find { |r| r.id == rid }
+      # Direct array access (O(1)) - rules[i].id == i invariant is guaranteed by parser
+      other_rule = rules[rid]
       next unless other_rule
       next if processed_rule_ids[rid]
 
-      # Check same media context
-      next if rule_to_media[rid] != current_media
+      # Check same media context (compare media_query_id directly)
+      next if other_rule.media_query_id != current_media_query_id
 
       # Check declarations match (compare arrays directly for performance)
-      if declarations_equal?(rule.declarations, other_rule.declarations)
+      if _declarations_equal?(rule.declarations, other_rule.declarations)
         matching_selectors << other_rule.selector
         processed_rule_ids[rid] = true
       end
@@ -239,7 +296,6 @@ module Cataract
   # All formatting behavior controlled by kwargs to avoid mode flags and if/else branches
   def self._serialize_stylesheet_with_grouping(
     rules:,
-    media_index:,
     result:,
     selector_lists:,
     opening_brace:,      # ' { ' (compact) vs " {\n" (formatted)
@@ -247,23 +303,24 @@ module Cataract
     media_indent:,       # '' (compact) vs '  ' (formatted)
     decl_indent_base:,   # nil (compact) vs '  ' (formatted base rules)
     decl_indent_media:,  # nil (compact) vs '    ' (formatted media rules)
-    add_blank_lines:     # false (compact) vs true (formatted)
+    add_blank_lines:,    # false (compact) vs true (formatted)
+    media_queries: [],   # Array of MediaQuery objects
+    media_query_lists: {} # Hash: list_id => array of MediaQuery IDs
   )
     grouping_enabled = selector_lists && !selector_lists.empty?
 
-    # Build rule_id => media_symbol map
-    rule_to_media = {}
-    media_index.each do |media_sym, rule_ids|
-      rule_ids.each do |rule_id|
-        rule_to_media[rule_id] = media_sym
-      end
+    # Build reverse map: media_query_id => list_id
+    mq_id_to_list_id = {}
+    media_query_lists.each do |list_id, mq_ids|
+      mq_ids.each { |mq_id| mq_id_to_list_id[mq_id] = list_id }
     end
 
     # Track processed rules to avoid duplicates when grouping
     processed_rule_ids = {}
 
     # Iterate through rules in insertion order, grouping consecutive media queries
-    current_media = nil
+    current_media_query_list_id = nil
+    current_media_query = nil
     in_media_block = false
     rule_index = 0
 
@@ -271,15 +328,18 @@ module Cataract
       # Skip if already processed (when grouped)
       next if processed_rule_ids[rule.id]
 
-      rule_media = rule_to_media[rule.id]
+      rule_media_query_id = rule.is_a?(Rule) ? rule.media_query_id : nil
+      rule_media_query = rule_media_query_id ? media_queries[rule_media_query_id] : nil
+      rule_media_query_list_id = rule_media_query_id ? mq_id_to_list_id[rule_media_query_id] : nil
       is_first_rule = (rule_index == 0)
 
-      if rule_media.nil?
+      if rule_media_query.nil?
         # Not in any media query - close any open media block first
         if in_media_block
           result << "}\n"
           in_media_block = false
-          current_media = nil
+          current_media_query = nil
+          current_media_query_list_id = nil
         end
 
         # Add blank line prefix for non-first rules (formatted only)
@@ -287,35 +347,44 @@ module Cataract
 
         # Try to group with other rules from same selector list
         if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
-          selectors = find_groupable_selectors(
+          selectors = _find_groupable_selectors(
             rule: rule,
             rules: rules,
             selector_lists: selector_lists,
             processed_rule_ids: processed_rule_ids,
-            rule_to_media: rule_to_media,
-            current_media: rule_media
+            current_media_query_id: rule_media_query_id
           )
 
           # Serialize with grouped selectors
           result << selectors.join(', ') << opening_brace
           if decl_indent_base
-            serialize_declarations_formatted(result, rule.declarations, decl_indent_base)
+            _serialize_declarations_formatted(result, rule.declarations, decl_indent_base)
           else
-            serialize_declarations(result, rule.declarations)
+            _serialize_declarations(result, rule.declarations)
           end
           result << closing_brace
         else
           # Serialize individual rule
           if decl_indent_base
-            serialize_rule_formatted(result, rule, '', true)
+            _serialize_rule_formatted(result, rule, '', true)
           else
-            serialize_rule(result, rule)
+            _serialize_rule(result, rule)
           end
           processed_rule_ids[rule.id] = true
         end
       else
         # This rule is in a media query
-        if current_media.nil? || current_media != rule_media
+        # For lists: compare list_id
+        # For single queries: compare by content (type + conditions)
+        needs_new_block = if rule_media_query_list_id
+                            current_media_query_list_id != rule_media_query_list_id
+                          else
+                            !current_media_query ||
+                              current_media_query.type != rule_media_query.type ||
+                              current_media_query.conditions != rule_media_query.conditions
+                          end
+
+        if needs_new_block
           # Close previous media block if open
           if in_media_block
             result << "}\n"
@@ -325,36 +394,39 @@ module Cataract
           result << "\n" if add_blank_lines && !is_first_rule
 
           # Open new media block
-          current_media = rule_media
-          result << "@media #{current_media} {\n"
+          current_media_query = rule_media_query
+          current_media_query_list_id = rule_media_query_list_id
+
+          # Serialize the media query (or list)
+          media_query_string = _build_media_query_string(rule_media_query, rule_media_query_list_id, media_query_lists, media_queries)
+          result << "@media #{media_query_string} {\n"
           in_media_block = true
         end
 
         # Try to group with other rules from same selector list
         if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
-          selectors = find_groupable_selectors(
+          selectors = _find_groupable_selectors(
             rule: rule,
             rules: rules,
             selector_lists: selector_lists,
             processed_rule_ids: processed_rule_ids,
-            rule_to_media: rule_to_media,
-            current_media: rule_media
+            current_media_query_id: rule_media_query_id
           )
 
           # Serialize with grouped selectors (with media indent)
           result << media_indent << selectors.join(', ') << opening_brace
           if decl_indent_media
-            serialize_declarations_formatted(result, rule.declarations, decl_indent_media)
+            _serialize_declarations_formatted(result, rule.declarations, decl_indent_media)
           else
-            serialize_declarations(result, rule.declarations)
+            _serialize_declarations(result, rule.declarations)
           end
           result << media_indent << closing_brace
         else
           # Serialize individual rule inside media block
           if decl_indent_media
-            serialize_rule_formatted(result, rule, media_indent, true)
+            _serialize_rule_formatted(result, rule, media_indent, true)
           else
-            serialize_rule(result, rule)
+            _serialize_rule(result, rule)
           end
           processed_rule_ids[rule.id] = true
         end
@@ -373,7 +445,7 @@ module Cataract
   private_class_method :_serialize_stylesheet_with_grouping
 
   # Helper: check if two declaration arrays are equal
-  def self.declarations_equal?(decls1, decls2)
+  def self._declarations_equal?(decls1, decls2)
     return false if decls1.size != decls2.size
 
     decls1.each_with_index do |d1, i|
@@ -387,21 +459,21 @@ module Cataract
   end
 
   # Helper: serialize a single rule
-  def self.serialize_rule(result, rule)
+  def self._serialize_rule(result, rule)
     # Check if this is an AtRule
     if rule.is_a?(AtRule)
-      serialize_at_rule(result, rule)
+      _serialize_at_rule(result, rule)
       return
     end
 
     # Regular Rule serialization
     result << "#{rule.selector} { "
-    serialize_declarations(result, rule.declarations)
+    _serialize_declarations(result, rule.declarations)
     result << " }\n"
   end
 
   # Helper: serialize declarations (compact, single line)
-  def self.serialize_declarations(result, declarations)
+  def self._serialize_declarations(result, declarations)
     declarations.each_with_index do |decl, i|
       important_suffix = decl.important ? ' !important;' : ';'
       separator = i < declarations.length - 1 ? ' ' : ''
@@ -410,7 +482,7 @@ module Cataract
   end
 
   # Helper: serialize declarations (formatted, one per line)
-  def self.serialize_declarations_formatted(result, declarations, indent)
+  def self._serialize_declarations_formatted(result, declarations, indent)
     declarations.each do |decl|
       result << indent
       result << decl.property
@@ -426,7 +498,7 @@ module Cataract
   end
 
   # Helper: serialize an at-rule (@keyframes, @font-face, etc)
-  def self.serialize_at_rule(result, at_rule)
+  def self._serialize_at_rule(result, at_rule)
     result << "#{at_rule.selector} {\n"
 
     # Check if content is rules or declarations
@@ -437,13 +509,13 @@ module Cataract
         # Serialize as nested rules (e.g., @keyframes)
         at_rule.content.each do |nested_rule|
           result << "  #{nested_rule.selector} { "
-          serialize_declarations(result, nested_rule.declarations)
+          _serialize_declarations(result, nested_rule.declarations)
           result << " }\n"
         end
       else
         # Serialize as declarations (e.g., @font-face)
         result << '  '
-        serialize_declarations(result, at_rule.content)
+        _serialize_declarations(result, at_rule.content)
         result << "\n"
       end
     end
@@ -454,12 +526,13 @@ module Cataract
   # Serialize stylesheet to formatted CSS string (with indentation)
   #
   # @param rules [Array<Rule>] Array of rules
-  # @param media_index [Hash] Media query symbol => array of rule IDs
   # @param charset [String, nil] @charset value
   # @param has_nesting [Boolean] Whether any nested rules exist
   # @param selector_lists [Hash] Selector list ID => array of rule IDs (for grouping)
+  # @param media_queries [Array<MediaQuery>] Array of MediaQuery objects (optional, for proper serialization)
+  # @param media_query_lists [Hash] List ID => array of MediaQuery IDs (optional, for comma-separated queries)
   # @return [String] Formatted CSS string
-  def self._stylesheet_to_formatted_s(rules, media_index, charset, has_nesting, selector_lists = {})
+  def self.stylesheet_to_formatted_s(rules, charset, has_nesting, selector_lists = {}, media_queries = [], media_query_lists = {})
     result = +''
 
     # Add @charset if present
@@ -469,7 +542,7 @@ module Cataract
 
     # Fast path: no nesting - use simple algorithm
     unless has_nesting
-      return stylesheet_to_formatted_s_original(rules, media_index, result, selector_lists)
+      return _stylesheet_to_formatted_s_without_nesting(rules, result, selector_lists, media_queries, media_query_lists)
     end
 
     # Build parent-child relationships
@@ -482,47 +555,62 @@ module Cataract
       rule_children[parent_id] << rule
     end
 
-    # Build rule_id => media_symbol map
-    rule_to_media = {}
-    media_index.each do |media_sym, rule_ids|
-      rule_ids.each do |rule_id|
-        rule_to_media[rule_id] = media_sym
-      end
+    # Build reverse map: media_query_id => list_id
+    mq_id_to_list_id = {}
+    media_query_lists.each do |list_id, mq_ids|
+      mq_ids.each { |mq_id| mq_id_to_list_id[mq_id] = list_id }
     end
 
     # Serialize top-level rules only
-    current_media = nil
+    current_media_query_list_id = nil
+    current_media_query = nil
     in_media_block = false
 
     rules.each do |rule|
       next if rule.parent_rule_id
 
-      rule_media = rule_to_media[rule.id]
+      rule_media_query_id = rule.is_a?(Rule) ? rule.media_query_id : nil
+      rule_media_query = rule_media_query_id ? media_queries[rule_media_query_id] : nil
+      rule_media_query_list_id = rule_media_query_id ? mq_id_to_list_id[rule_media_query_id] : nil
 
-      if rule_media.nil?
+      if rule_media_query.nil?
         if in_media_block
           result << "}\n"
           in_media_block = false
-          current_media = nil
+          current_media_query = nil
+          current_media_query_list_id = nil
         end
 
         # Add blank line before base rule if we just closed a media block (ends with "}\n")
         result << "\n" if result.length > 1 && result.getbyte(-1) == BYTE_NEWLINE && result.getbyte(-2) == BYTE_RBRACE
 
-        serialize_rule_with_nesting_formatted(result, rule, rule_children, rule_to_media, '')
+        _serialize_rule_with_nesting_formatted(result, rule, rule_children, '', media_queries)
       else
-        if current_media.nil? || current_media != rule_media
+        # For lists: compare list_id
+        # For single queries: compare by content (type + conditions)
+        needs_new_block = if rule_media_query_list_id
+                            current_media_query_list_id != rule_media_query_list_id
+                          else
+                            !current_media_query ||
+                              current_media_query.type != rule_media_query.type ||
+                              current_media_query.conditions != rule_media_query.conditions
+                          end
+
+        if needs_new_block
           if in_media_block
             result << "}\n"
           elsif result.length > 0
             result << "\n"
           end
-          current_media = rule_media
-          result << "@media #{current_media} {\n"
+          current_media_query = rule_media_query
+          current_media_query_list_id = rule_media_query_list_id
+          # Serialize the media query (or list)
+          media_query_string = _build_media_query_string(rule_media_query, rule_media_query_list_id, media_query_lists, media_queries)
+          result << "@media #{media_query_string} {\n"
           in_media_block = true
         end
 
-        serialize_rule_with_nesting_formatted(result, rule, rule_children, rule_to_media, '  ')
+        _serialize_rule_with_nesting_formatted(result, rule, rule_children, '  ', media_queries)
       end
     end
 
@@ -534,12 +622,13 @@ module Cataract
   end
 
   # Helper: formatted serialization without nesting support
-  def self.stylesheet_to_formatted_s_original(rules, media_index, result, selector_lists)
+  def self._stylesheet_to_formatted_s_without_nesting(rules, result, selector_lists, media_queries = [], media_query_lists = {})
     _serialize_stylesheet_with_grouping(
       rules: rules,
-      media_index: media_index,
       result: result,
       selector_lists: selector_lists,
+      media_queries: media_queries,
+      media_query_lists: media_query_lists,
       opening_brace: " {\n",
       closing_brace: "}\n",
       media_indent: '  ',
@@ -550,7 +639,7 @@ module Cataract
   end
 
   # Helper: serialize a rule with nested children (formatted)
-  def self.serialize_rule_with_nesting_formatted(result, rule, rule_children, rule_to_media, indent)
+  def self._serialize_rule_with_nesting_formatted(result, rule, rule_children, indent, media_queries)
     # Selector line with opening brace
     result << indent
     result << rule.selector
@@ -558,7 +647,7 @@ module Cataract
 
     # Serialize declarations (one per line)
     unless rule.declarations.empty?
-      serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
+      _serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
     end
 
     # Get nested children
@@ -566,22 +655,27 @@ module Cataract
 
     # Serialize nested children
     children.each do |child|
-      nested_selector = reconstruct_nested_selector(rule.selector, child.selector, child.nesting_style)
+      nested_selector = _reconstruct_nested_selector(rule.selector, child.selector, child.nesting_style)
 
-      if child.nesting_style.nil? && rule_to_media[child.id]
+      if child.nesting_style.nil? && child.media_query_id && media_queries[child.media_query_id]
         # Nested @media
-        media_sym = rule_to_media[child.id]
+        mq = media_queries[child.media_query_id]
+        media_query_string = if mq.conditions
+                               mq.type == :all ? mq.conditions : "#{mq.type} and #{mq.conditions}"
+                             else
+                               mq.type.to_s
+                             end
         result << indent
-        result << "  @media #{media_sym} {\n"
+        result << "  @media #{media_query_string} {\n"
 
         unless child.declarations.empty?
-          serialize_declarations_formatted(result, child.declarations, "#{indent}    ")
+          _serialize_declarations_formatted(result, child.declarations, "#{indent}    ")
         end
 
         # Recursively handle media children
         media_children = rule_children[child.id] || []
         media_children.each do |media_child|
-          nested_media_selector = reconstruct_nested_selector(
+          nested_media_selector = _reconstruct_nested_selector(
             child.selector,
             media_child.selector,
             media_child.nesting_style
@@ -590,7 +684,7 @@ module Cataract
           result << indent
           result << "    #{nested_media_selector} {\n"
           unless media_child.declarations.empty?
-            serialize_declarations_formatted(result, media_child.declarations, "#{indent}      ")
+            _serialize_declarations_formatted(result, media_child.declarations, "#{indent}      ")
           end
           result << indent
           result << "    }\n"
@@ -604,13 +698,13 @@ module Cataract
         result << "  #{nested_selector} {\n"
 
         unless child.declarations.empty?
-          serialize_declarations_formatted(result, child.declarations, "#{indent}    ")
+          _serialize_declarations_formatted(result, child.declarations, "#{indent}    ")
         end
 
         # Recursively handle grandchildren
         grandchildren = rule_children[child.id] || []
         grandchildren.each do |grandchild|
-          nested_grandchild_selector = reconstruct_nested_selector(
+          nested_grandchild_selector = _reconstruct_nested_selector(
             child.selector,
             grandchild.selector,
             grandchild.nesting_style
@@ -619,7 +713,7 @@ module Cataract
           result << indent
           result << "    #{nested_grandchild_selector} {\n"
           unless grandchild.declarations.empty?
-            serialize_declarations_formatted(result, grandchild.declarations, "#{indent}      ")
+            _serialize_declarations_formatted(result, grandchild.declarations, "#{indent}      ")
           end
           result << indent
           result << "    }\n"
@@ -636,10 +730,10 @@ module Cataract
   end
 
   # Helper: serialize a single rule with formatting
-  def self.serialize_rule_formatted(result, rule, indent, is_last_rule = false)
+  def self._serialize_rule_formatted(result, rule, indent, is_last_rule = false)
     # Check if this is an AtRule
     if rule.is_a?(AtRule)
-      serialize_at_rule_formatted(result, rule, indent)
+      _serialize_at_rule_formatted(result, rule, indent)
       return
     end
 
@@ -650,7 +744,7 @@ module Cataract
     result << " {\n"
 
     # Declarations (one per line)
-    serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
+    _serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
 
     # Closing brace - double newline for all except last rule
     result << indent
@@ -658,7 +752,7 @@ module Cataract
   end
 
   # Helper: serialize an at-rule with formatting
-  def self.serialize_at_rule_formatted(result, at_rule, indent)
+  def self._serialize_at_rule_formatted(result, at_rule, indent)
     result << indent
     result << at_rule.selector
     result << " {\n"
@@ -677,7 +771,7 @@ module Cataract
           result << " {\n"
 
           # Declarations (one per line, 4-space indent)
-          serialize_declarations_formatted(result, nested_rule.declarations, "#{indent}    ")
+          _serialize_declarations_formatted(result, nested_rule.declarations, "#{indent}    ")
 
           # Closing brace (2-space indent)
           result << indent
@@ -685,11 +779,18 @@ module Cataract
         end
       else
         # Serialize as declarations (e.g., @font-face, one per line)
-        serialize_declarations_formatted(result, at_rule.content, "#{indent}  ")
+        _serialize_declarations_formatted(result, at_rule.content, "#{indent}  ")
       end
     end
 
     result << indent
     result << "}\n"
   end
+
+  # Mark helper methods as private (public APIs: stylesheet_to_s, stylesheet_to_formatted_s)
+  private_class_method :_build_media_query_string, :_stylesheet_to_s_without_nesting, :_serialize_rule_with_nesting,
+                       :_reconstruct_nested_selector, :_find_groupable_selectors, :_declarations_equal?,
+                       :_serialize_rule, :_serialize_declarations, :_serialize_declarations_formatted,
+                       :_serialize_at_rule, :_stylesheet_to_formatted_s_without_nesting, :_serialize_rule_with_nesting_formatted,
+                       :_serialize_rule_formatted, :_serialize_at_rule_formatted
 end