cataract 0.3.0 → 0.4.0

data/lib/cataract/pure/serializer.rb

@@ -1,801 +1,661 @@
 # frozen_string_literal: true
 
-# Pure Ruby CSS parser - Serialization methods
+# Pure Ruby CSS parser - Serialization
 # 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
+  module Backends
+    class PureImpl
+      # Serializes one stylesheet's rules to a CSS string, compact or formatted.
+      # One instance per #stylesheet_to_s / #stylesheet_to_formatted_s call - the
+      # accumulating result, the rules/media being serialized, and the
+      # compact-vs-formatted knobs all live on ivars instead of being threaded
+      # through every helper as parameters.
+      class Serializer
+        def initialize(rules, charset, has_nesting, selector_lists, media_queries, media_query_lists, formatted:)
+          @rules = rules
+          @charset = charset
+          @has_nesting = has_nesting
+          @selector_lists = selector_lists || {}
+          @media_queries = media_queries || []
+          @media_query_lists = media_query_lists || {}
+          @formatted = formatted
+          @result = +''
+
+          if formatted
+            @opening_brace = " {\n"
+            @closing_brace = "}\n"
+            @media_indent = '  '
+            @decl_indent_base = '  '
+            @decl_indent_media = '    '
+            @add_blank_lines = true
+          else
+            @opening_brace = ' { '
+            @closing_brace = " }\n"
+            @media_indent = ''
+            @decl_indent_base = nil
+            @decl_indent_media = nil
+            @add_blank_lines = false
+          end
         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
-
-  # @api private
-  # Helper: does the rule's media query differ from the currently open media
-  # block, requiring a new "@media ... {" to be opened? Comma-separated
-  # lists are compared by list id; single queries are compared by content
-  # (type + conditions), since two separately-parsed queries with the same
-  # content should still be grouped under one block.
-  # @return [Boolean]
-  def self._needs_new_media_block?(current_media_query, current_media_query_list_id, rule_media_query,
-                                   rule_media_query_list_id)
-    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
-  end
-
-  # @api private
-  # Helper: read a rule's parent_rule_id, guarding against AtRule (which has
-  # no such member - only Rule participates in CSS nesting, AtRule never is
-  # nested via '&' nesting). Calling .parent_rule_id directly on an AtRule
-  # raises NoMethodError.
-  # @param rule [Rule, AtRule] The rule to check
-  # @return [Integer, nil] parent_rule_id, or nil if the rule isn't a Rule
-  def self._rule_parent_id(rule)
-    rule.is_a?(Rule) ? rule.parent_rule_id : nil
-  end
-
-  # Serialize stylesheet to compact CSS string
-  #
-  # @param rules [Array<Rule>] Array of rules
-  # @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, charset, has_nesting, selector_lists = {}, media_queries = [], media_query_lists = {})
-    result = +''
-
-    # Add @charset if present
-    unless charset.nil?
-      result << "@charset \"#{charset}\";\n"
-    end
-
-    # Fast path: no nesting - use simple algorithm
-    unless has_nesting
-      return _stylesheet_to_s_without_nesting(rules, result, selector_lists, media_queries, media_query_lists)
-    end
-
-    # Build parent-child relationships
-    rule_children = {}
-    rules.each do |rule|
-      parent_rule_id = _rule_parent_id(rule)
-      next unless parent_rule_id
-
-      parent_id = parent_rule_id.is_a?(Integer) ? parent_rule_id : parent_rule_id.to_i
-      rule_children[parent_id] ||= []
-      rule_children[parent_id] << rule
-    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_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_id(rule)
+        # Serialize the stylesheet to a CSS string (compact or formatted,
+        # depending on how this Serializer was constructed).
+        #
+        # @return [String] CSS string
+        def to_s
+          @result << "@charset \"#{@charset}\";\n" unless @charset.nil?
 
-      rule_media_query_id = rule.media_query_id
-      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
+          build_mq_id_to_list_id!
 
-      if rule_media_query.nil?
-        # Close any open media block
-        if in_media_block
-          result << "}\n"
-          in_media_block = false
-          current_media_query = nil
-          current_media_query_list_id = nil
-        end
-      else
-        # 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 = _needs_new_media_block?(current_media_query, current_media_query_list_id, rule_media_query,
-                                                  rule_media_query_list_id)
-
-        if needs_new_block
-          if in_media_block
-            result << "}\n"
+          if @has_nesting
+            @formatted ? serialize_with_nesting_formatted : serialize_with_nesting_compact
+          else
+            serialize_with_grouping
           end
-          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
+          @result
         end
-      end
-
-      _serialize_rule_with_nesting(result, rule, rule_children, media_queries)
-    end
-
-    if in_media_block
-      result << "}\n"
-    end
 
-    result
-  end
-
-  # Helper: serialize rules without nesting support (compact format)
-  def self._stylesheet_to_s_without_nesting(rules, result, selector_lists, media_queries = [], media_query_lists = {})
-    _serialize_stylesheet_with_grouping(
-      rules: rules,
-      result: result,
-      selector_lists: selector_lists,
-      media_queries: media_queries,
-      media_query_lists: media_query_lists,
-      opening_brace: ' { ',
-      closing_brace: " }\n",
-      media_indent: '',
-      decl_indent_base: nil,
-      decl_indent_media: nil,
-      add_blank_lines: false
-    )
-  end
-
-  # Helper: serialize a rule with its nested children
-  def self._serialize_rule_with_nesting(result, rule, rule_children, media_queries)
-    # Check if this is an AtRule - it can never have nested children of its
-    # own via rule_children (only Rule participates in CSS nesting), so it
-    # always serializes the same way regardless of has_nesting
-    if rule.is_a?(AtRule)
-      _serialize_at_rule(result, rule)
-      return
-    end
+        private
 
-    # Start selector
-    result << "#{rule.selector} { "
-
-    # Serialize declarations
-    has_declarations = !rule.declarations.empty?
-    if has_declarations
-      _serialize_declarations(result, rule.declarations)
-    end
-
-    _serialize_children(result, rule.selector, rule_children[rule.id] || [], rule_children, media_queries, has_declarations)
-
-    result << " }\n"
-  end
-
-  # Helper: recursively serialize a rule's nested children. CSS nesting can go
-  # as deep as the parser allows (MAX_PARSE_DEPTH), so this recurses rather
-  # than hand-unrolling a fixed number of levels - a nested rule's own nested
-  # rules are found the same way its parent's were, via rule_children[id].
-  def self._serialize_children(result, parent_selector, children, rule_children, media_queries, parent_has_declarations)
-    children.each_with_index do |child, index|
-      # Add space before nested content
-      # - Always add space if the parent had declarations
-      # - Add space between nested rules (not before first if no declarations)
-      if parent_has_declarations || index > 0
-        result << ' '
-      end
-
-      # Check if this child has @media nesting (parent_rule_id present but nesting_style is nil)
-      if child.nesting_style.nil? && child.media_query_id && media_queries[child.media_query_id]
-        # This is a nested @media rule
-        mq = media_queries[child.media_query_id]
-        media_query_string = _build_media_query_string(mq, nil, nil, media_queries)
-        result << "@media #{media_query_string} { "
-        _serialize_declarations(result, child.declarations)
-
-        # 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(
-            child.selector, media_child.selector,
-            media_child.nesting_style
-          )
-
-          result << "#{nested_media_selector} { "
-          _serialize_declarations(result, media_child.declarations)
-          result << ' }'
+        # Build reverse map: media_query_id => list_id (used by both the
+        # nesting-aware and selector-list-grouping paths)
+        def build_mq_id_to_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
         end
 
-        result << ' }'
-      else
-        # Regular nested selector - determine if we need to reconstruct it with &
-        nested_selector = _reconstruct_nested_selector(parent_selector, child.selector, child.nesting_style)
-
-        result << "#{nested_selector} { "
-        _serialize_declarations(result, child.declarations)
-
-        # Recurse into this child's own nested children, however deep they go
-        _serialize_children(result, child.selector, rule_children[child.id] || [], rule_children, media_queries, !child.declarations.empty?)
-
-        result << ' }'
-      end
-    end
-  end
-
-  # 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)
-    return child_selector if nesting_style.nil?
-
-    if nesting_style == 1 # NESTING_STYLE_EXPLICIT
-      # Try to reconstruct & notation
-      # ".parent .child" with parent ".parent" => "& .child"
-      # ".parent:hover" with parent ".parent" => "&:hover"
-      if child_selector.start_with?(parent_selector)
-        rest = child_selector[parent_selector.length..-1]
-        return "&#{rest}"
-      end
-      # More complex cases like ".parent .foo .child"
-      child_selector.sub(parent_selector, '&')
-    else # NESTING_STYLE_IMPLICIT
-      # Remove parent prefix for implicit nesting
-      # ".parent .child" with parent ".parent" => ".child"
-      if child_selector.start_with?(parent_selector)
-        rest = child_selector[parent_selector.length..-1]
-        return rest.lstrip
-      end
-      child_selector
-    end
-  end
-
-  # 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:, current_media_query_id:)
-    list_id = rule.selector_list_id
-    rule_ids_in_list = selector_lists[list_id]
-
-    # If no other rules in this list, return just this selector
-    if rule_ids_in_list.nil? || rule_ids_in_list.size <= 1
-      processed_rule_ids[rule.id] = true
-      return [rule.selector]
-    end
-
-    # Find all rules in this list that have identical declarations AND same media context
-    matching_selectors = []
-    rule_ids_in_list.each do |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 (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)
-        matching_selectors << other_rule.selector
-        processed_rule_ids[rid] = true
-      end
-    end
-
-    matching_selectors
-  end
-
-  # Private shared implementation for stylesheet serialization with optional selector list grouping
-  # All formatting behavior controlled by kwargs to avoid mode flags and if/else branches
-  def self._serialize_stylesheet_with_grouping(
-    rules:,
-    result:,
-    selector_lists:,
-    opening_brace:,      # ' { ' (compact) vs " {\n" (formatted)
-    closing_brace:,      # " }\n" (compact) vs "}\n" (formatted)
-    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)
-    media_queries: [],   # Array of MediaQuery objects
-    media_query_lists: {} # Hash: list_id => array of MediaQuery IDs
-  )
-    grouping_enabled = selector_lists && !selector_lists.empty?
-
-    # 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_query_list_id = nil
-    current_media_query = nil
-    in_media_block = false
-    rule_index = 0
+        # Build id => rule lookup (used only by the selector-list-grouping
+        # path). @rules is NOT guaranteed to satisfy rules[i].id == i here -
+        # that invariant only holds for the full, freshly-parsed rules array;
+        # Stylesheet#to_s(media: ...) passes a filtered subset whenever the
+        # media filter isn't :all, so a plain array index would silently
+        # fetch the wrong rule (or even an AtRule, which has no
+        # #declarations) once any rule has been filtered out.
+        def build_rules_by_id!
+          @rules_by_id = {}
+          @rules.each { |rule| @rules_by_id[rule.id] = rule }
+        end
 
-    rules.each do |rule|
-      # Skip if already processed (when grouped)
-      next if processed_rule_ids[rule.id]
+        # Build parent-child relationships (used only by the nesting-aware path)
+        def build_rule_children!
+          @rule_children = {}
+          @rules.each do |rule|
+            parent_rule_id = rule_parent_id(rule)
+            next unless parent_rule_id
 
-      rule_media_query_id = rule.media_query_id
-      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)
+            parent_id = parent_rule_id.is_a?(Integer) ? parent_rule_id : parent_rule_id.to_i
+            @rule_children[parent_id] ||= []
+            @rule_children[parent_id] << rule
+          end
+        end
 
-      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_query = nil
-          current_media_query_list_id = nil
+        # Read a rule's parent_rule_id, guarding against AtRule (which has no
+        # such member - only Rule participates in CSS nesting, AtRule never is
+        # nested via '&' nesting). Calling .parent_rule_id directly on an AtRule
+        # raises NoMethodError.
+        def rule_parent_id(rule)
+          rule.is_a?(Rule) ? rule.parent_rule_id : nil
         end
 
-        # Add blank line prefix for non-first rules (formatted only)
-        result << "\n" if add_blank_lines && !is_first_rule
-
-        # 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(
-            rule: rule,
-            rules: rules,
-            selector_lists: selector_lists,
-            processed_rule_ids: processed_rule_ids,
-            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)
+        # Build media query string from a 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
+        # @return [String] e.g. "screen", "screen, print", "screen and (min-width: 768px)"
+        def build_media_query_string(media_query, media_query_list_id)
+          if media_query_list_id
+            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(', ')
+          elsif media_query.conditions
+            media_query.type == :all ? media_query.conditions : "#{media_query.type} and #{media_query.conditions}"
           else
-            _serialize_declarations(result, rule.declarations)
+            media_query.type.to_s
           end
-          result << closing_brace
-        else
-          # Serialize individual rule
-          if decl_indent_base
-            _serialize_rule_formatted(result, rule, '', true)
+        end
+
+        # Does the rule's media query differ from the currently open media
+        # block, requiring a new "@media ... {" to be opened? Comma-separated
+        # lists are compared by list id; single queries are compared by content
+        # (type + conditions), since two separately-parsed queries with the same
+        # content should still be grouped under one block.
+        def needs_new_media_block?(current_media_query, current_media_query_list_id, rule_media_query,
+                                   rule_media_query_list_id)
+          if rule_media_query_list_id
+            current_media_query_list_id != rule_media_query_list_id
           else
-            _serialize_rule(result, rule)
+            !current_media_query ||
+              current_media_query.type != rule_media_query.type ||
+              current_media_query.conditions != rule_media_query.conditions
           end
-          processed_rule_ids[rule.id] = true
         end
-      else
-        # This rule is in a media query
-        # For lists: compare list_id
-        # For single queries: compare by content (type + conditions)
-        needs_new_block = _needs_new_media_block?(current_media_query, current_media_query_list_id, rule_media_query,
-                                                  rule_media_query_list_id)
-
-        if needs_new_block
-          # Close previous media block if open
-          if in_media_block
-            result << "}\n"
-          end
 
-          # Add blank line prefix for non-first rules (formatted only)
-          result << "\n" if add_blank_lines && !is_first_rule
+        # ---- Nesting-aware path (has_nesting == true), compact format ----
 
-          # Open new media block
-          current_media_query = rule_media_query
-          current_media_query_list_id = rule_media_query_list_id
+        def serialize_with_nesting_compact
+          build_rule_children!
 
-          # 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
+          current_media_query_list_id = nil
+          current_media_query = nil
+          in_media_block = false
 
-        # 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(
-            rule: rule,
-            rules: rules,
-            selector_lists: selector_lists,
-            processed_rule_ids: processed_rule_ids,
-            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)
-          else
-            _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)
-          else
-            _serialize_rule(result, rule)
+          @rules.each do |rule|
+            next if rule_parent_id(rule)
+
+            rule_media_query_id = rule.media_query_id
+            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_query.nil?
+              if in_media_block
+                @result << "}\n"
+                in_media_block = false
+                current_media_query = nil
+                current_media_query_list_id = nil
+              end
+            else
+              needs_new_block = needs_new_media_block?(current_media_query, current_media_query_list_id,
+                                                       rule_media_query, rule_media_query_list_id)
+
+              if needs_new_block
+                @result << "}\n" if in_media_block
+                current_media_query = rule_media_query
+                current_media_query_list_id = rule_media_query_list_id
+
+                media_query_string = build_media_query_string(rule_media_query, rule_media_query_list_id)
+                @result << "@media #{media_query_string} {\n"
+                in_media_block = true
+              end
+            end
+
+            serialize_rule_with_nesting(rule)
           end
-          processed_rule_ids[rule.id] = true
+
+          @result << "}\n" if in_media_block
         end
-      end
 
-      rule_index += 1
-    end
+        def serialize_rule_with_nesting(rule)
+          # AtRule can never have nested children of its own via @rule_children
+          # (only Rule participates in CSS nesting), so it always serializes the
+          # same way regardless of has_nesting.
+          if rule.is_a?(AtRule)
+            serialize_at_rule(rule)
+            return
+          end
 
-    # Close final media block if still open
-    if in_media_block
-      result << "}\n"
-    end
+          @result << "#{rule.selector} { "
 
-    result
-  end
-  private_class_method :_serialize_stylesheet_with_grouping
+          has_declarations = !rule.declarations.empty?
+          serialize_declarations(rule.declarations) if has_declarations
 
-  # Helper: check if two declaration arrays are equal
-  def self._declarations_equal?(decls1, decls2)
-    return false if decls1.size != decls2.size
+          serialize_children(rule.selector, @rule_children[rule.id] || [], has_declarations)
 
-    decls1.each_with_index do |d1, i|
-      d2 = decls2[i]
-      return false if d1.property != d2.property
-      return false if d1.value != d2.value
-      return false if d1.important != d2.important
-    end
+          @result << " }\n"
+        end
 
-    true
-  end
+        # Recursively serialize a rule's nested children. CSS nesting can go as
+        # deep as the parser allows (MAX_PARSE_DEPTH), so this recurses rather
+        # than hand-unrolling a fixed number of levels - a nested rule's own
+        # nested rules are found the same way its parent's were, via
+        # @rule_children[id].
+        def serialize_children(parent_selector, children, parent_has_declarations)
+          children.each_with_index do |child, index|
+            # Add space before nested content - always if the parent had
+            # declarations, otherwise between nested rules (not before the first).
+            @result << ' ' if parent_has_declarations || index > 0
+
+            if child.nesting_style.nil? && child.media_query_id && @media_queries[child.media_query_id]
+              # Nested @media rule (parent_rule_id present but nesting_style is nil)
+              mq = @media_queries[child.media_query_id]
+              media_query_string = build_media_query_string(mq, nil)
+              @result << "@media #{media_query_string} { "
+              serialize_declarations(child.declarations)
+
+              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(
+                  child.selector, media_child.selector, media_child.nesting_style
+                )
+
+                @result << "#{nested_media_selector} { "
+                serialize_declarations(media_child.declarations)
+                @result << ' }'
+              end
+
+              @result << ' }'
+            else
+              # Regular nested selector - reconstruct it with & if needed
+              nested_selector = reconstruct_nested_selector(parent_selector, child.selector, child.nesting_style)
+
+              @result << "#{nested_selector} { "
+              serialize_declarations(child.declarations)
+
+              serialize_children(child.selector, @rule_children[child.id] || [], !child.declarations.empty?)
+
+              @result << ' }'
+            end
+          end
+        end
 
-  # Helper: serialize a single rule
-  def self._serialize_rule(result, rule)
-    # Check if this is an AtRule
-    if rule.is_a?(AtRule)
-      _serialize_at_rule(result, rule)
-      return
-    end
+        # Reconstruct nested selector representation.
+        # If nesting_style == 1 (explicit), try to use & notation.
+        # If nesting_style == 0 (implicit), use plain selector.
+        def reconstruct_nested_selector(parent_selector, child_selector, nesting_style)
+          return child_selector if nesting_style.nil?
+
+          if nesting_style == 1 # NESTING_STYLE_EXPLICIT
+            # ".parent .child" with parent ".parent" => "& .child"
+            # ".parent:hover" with parent ".parent" => "&:hover"
+            if child_selector.start_with?(parent_selector)
+              rest = child_selector[parent_selector.length..-1]
+              return "&#{rest}"
+            end
+            # More complex cases like ".parent .foo .child"
+            child_selector.sub(parent_selector, '&')
+          else # NESTING_STYLE_IMPLICIT
+            # ".parent .child" with parent ".parent" => ".child"
+            if child_selector.start_with?(parent_selector)
+              rest = child_selector[parent_selector.length..-1]
+              return rest.lstrip
+            end
+            child_selector
+          end
+        end
 
-    # Regular Rule serialization
-    result << "#{rule.selector} { "
-    _serialize_declarations(result, rule.declarations)
-    result << " }\n"
-  end
+        # ---- Selector-list-grouping path (has_nesting == false) ----
+        # Shared between compact and formatted output - all formatting behavior
+        # is controlled by ivars set in #initialize, so there's no mode-flag
+        # kwarg pile to keep in sync.
 
-  # Helper: serialize declarations (compact, single line)
-  def self._serialize_declarations(result, declarations)
-    declarations.each_with_index do |decl, i|
-      important_suffix = decl.important ? ' !important;' : ';'
-      separator = i < declarations.length - 1 ? ' ' : ''
-      result << "#{decl.property}: #{decl.value}#{important_suffix}#{separator}"
-    end
-  end
+        def serialize_with_grouping
+          @processed_rule_ids = {}
+          grouping_enabled = @selector_lists && !@selector_lists.empty?
+          build_rules_by_id! if grouping_enabled
 
-  # Helper: serialize declarations (formatted, one per line)
-  def self._serialize_declarations_formatted(result, declarations, indent)
-    declarations.each do |decl|
-      result << indent
-      result << decl.property
-      result << ': '
-      result << decl.value
+          current_media_query_list_id = nil
+          current_media_query = nil
+          in_media_block = false
+          rule_index = 0
+
+          @rules.each do |rule|
+            next if @processed_rule_ids[rule.id]
+
+            rule_media_query_id = rule.media_query_id
+            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_query.nil?
+              if in_media_block
+                @result << "}\n"
+                in_media_block = false
+                current_media_query = nil
+                current_media_query_list_id = nil
+              end
+
+              @result << "\n" if @add_blank_lines && !is_first_rule
+
+              if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
+                selectors = find_groupable_selectors(rule, rule_media_query_id)
+
+                @result << selectors.join(', ') << @opening_brace
+                if @decl_indent_base
+                  serialize_declarations_formatted(rule.declarations, @decl_indent_base)
+                else
+                  serialize_declarations(rule.declarations)
+                end
+                @result << @closing_brace
+              else
+                if @decl_indent_base
+                  serialize_rule_formatted(rule, '', true)
+                else
+                  serialize_rule(rule)
+                end
+                @processed_rule_ids[rule.id] = true
+              end
+            else
+              needs_new_block = needs_new_media_block?(current_media_query, current_media_query_list_id,
+                                                       rule_media_query, rule_media_query_list_id)
+
+              if needs_new_block
+                @result << "}\n" if in_media_block
+                @result << "\n" if @add_blank_lines && !is_first_rule
+
+                current_media_query = rule_media_query
+                current_media_query_list_id = rule_media_query_list_id
+
+                media_query_string = build_media_query_string(rule_media_query, rule_media_query_list_id)
+                @result << "@media #{media_query_string} {\n"
+                in_media_block = true
+              end
+
+              if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
+                selectors = find_groupable_selectors(rule, rule_media_query_id)
+
+                @result << @media_indent << selectors.join(', ') << @opening_brace
+                if @decl_indent_media
+                  serialize_declarations_formatted(rule.declarations, @decl_indent_media)
+                else
+                  serialize_declarations(rule.declarations)
+                end
+                @result << @media_indent << @closing_brace
+              else
+                if @decl_indent_media
+                  serialize_rule_formatted(rule, @media_indent, true)
+                else
+                  serialize_rule(rule)
+                end
+                @processed_rule_ids[rule.id] = true
+              end
+            end
+
+            rule_index += 1
+          end
 
-      if decl.important
-        result << ' !important'
-      end
+          @result << "}\n" if in_media_block
+        end
 
-      result << ";\n"
-    end
-  end
+        # Find all selectors from the same selector list with matching
+        # declarations (and the same media context). Returns the array of
+        # selectors that can be grouped, marking them processed as it goes.
+        def find_groupable_selectors(rule, current_media_query_id)
+          list_id = rule.selector_list_id
+          rule_ids_in_list = @selector_lists[list_id]
 
-  # Helper: serialize an at-rule (@keyframes, @font-face, etc)
-  def self._serialize_at_rule(result, at_rule)
-    result << "#{at_rule.selector} {\n"
+          if rule_ids_in_list.nil? || rule_ids_in_list.size <= 1
+            @processed_rule_ids[rule.id] = true
+            return [rule.selector]
+          end
 
-    # Check if content is rules or declarations
-    if at_rule.content.length > 0
-      first = at_rule.content[0]
+          matching_selectors = []
+          rule_ids_in_list.each do |rid|
+            other_rule = @rules_by_id[rid]
+            next unless other_rule
+            next if @processed_rule_ids[rid]
+            next if other_rule.media_query_id != current_media_query_id
+
+            if declarations_equal?(rule.declarations, other_rule.declarations)
+              matching_selectors << other_rule.selector
+              @processed_rule_ids[rid] = true
+            end
+          end
 
-      if first.is_a?(Rule)
-        # Serialize as nested rules (e.g., @keyframes)
-        at_rule.content.each do |nested_rule|
-          result << "  #{nested_rule.selector} { "
-          _serialize_declarations(result, nested_rule.declarations)
-          result << " }\n"
+          matching_selectors
         end
-      else
-        # Serialize as declarations (e.g., @font-face)
-        result << '  '
-        _serialize_declarations(result, at_rule.content)
-        result << "\n"
-      end
-    end
-
-    result << "}\n"
-  end
-
-  # Serialize stylesheet to formatted CSS string (with indentation)
-  #
-  # @param rules [Array<Rule>] Array of rules
-  # @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, charset, has_nesting, selector_lists = {}, media_queries = [], media_query_lists = {})
-    result = +''
-
-    # Add @charset if present
-    unless charset.nil?
-      result << "@charset \"#{charset}\";\n"
-    end
-
-    # Fast path: no nesting - use simple algorithm
-    unless has_nesting
-      return _stylesheet_to_formatted_s_without_nesting(rules, result, selector_lists, media_queries, media_query_lists)
-    end
 
-    # Build parent-child relationships
-    rule_children = {}
-    rules.each do |rule|
-      parent_rule_id = _rule_parent_id(rule)
-      next unless parent_rule_id
+        def declarations_equal?(decls1, decls2)
+          return false if decls1.size != decls2.size
 
-      parent_id = parent_rule_id.is_a?(Integer) ? parent_rule_id : parent_rule_id.to_i
-      rule_children[parent_id] ||= []
-      rule_children[parent_id] << rule
-    end
+          decls1.each_with_index do |d1, i|
+            d2 = decls2[i]
+            return false if d1.property != d2.property
+            return false if d1.value != d2.value
+            return false if d1.important != d2.important
+          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
+          true
+        end
 
-    # Serialize top-level rules only
-    current_media_query_list_id = nil
-    current_media_query = nil
-    in_media_block = false
+        def serialize_rule(rule)
+          if rule.is_a?(AtRule)
+            serialize_at_rule(rule)
+            return
+          end
 
-    rules.each do |rule|
-      next if _rule_parent_id(rule)
+          @result << "#{rule.selector} { "
+          serialize_declarations(rule.declarations)
+          @result << " }\n"
+        end
 
-      rule_media_query_id = rule.media_query_id
-      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
+        # Declarations, compact (single line)
+        def serialize_declarations(declarations)
+          declarations.each_with_index do |decl, i|
+            important_suffix = decl.important ? ' !important;' : ';'
+            separator = i < declarations.length - 1 ? ' ' : ''
+            @result << "#{decl.property}: #{decl.value}#{important_suffix}#{separator}"
+          end
+        end
 
-      if rule_media_query.nil?
-        if in_media_block
-          result << "}\n"
-          in_media_block = false
-          current_media_query = nil
-          current_media_query_list_id = nil
+        # Declarations, formatted (one per line)
+        def serialize_declarations_formatted(declarations, indent)
+          declarations.each do |decl|
+            @result << indent
+            @result << decl.property
+            @result << ': '
+            @result << decl.value
+            @result << ' !important' if decl.important
+            @result << ";\n"
+          end
         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, '', media_queries)
-      else
-        # For lists: compare list_id
-        # For single queries: compare by content (type + conditions)
-        needs_new_block = _needs_new_media_block?(current_media_query, current_media_query_list_id, rule_media_query,
-                                                  rule_media_query_list_id)
-
-        if needs_new_block
-          if in_media_block
-            result << "}\n"
-          elsif result.length > 0
-            result << "\n"
+        # An at-rule (@keyframes, @font-face, etc), compact
+        def serialize_at_rule(at_rule)
+          @result << "#{at_rule.selector} {\n"
+
+          if at_rule.content.length > 0
+            first = at_rule.content[0]
+
+            if first.is_a?(Rule)
+              at_rule.content.each do |nested_rule|
+                @result << "  #{nested_rule.selector} { "
+                serialize_declarations(nested_rule.declarations)
+                @result << " }\n"
+              end
+            else
+              @result << '  '
+              serialize_declarations(at_rule.content)
+              @result << "\n"
+            end
           end
-          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
+
+          @result << "}\n"
         end
 
-        _serialize_rule_with_nesting_formatted(result, rule, rule_children, '  ', media_queries)
-      end
-    end
+        # ---- Nesting-aware path (has_nesting == true), formatted ----
 
-    if in_media_block
-      result << "}\n"
-    end
+        def serialize_with_nesting_formatted
+          build_rule_children!
 
-    result
-  end
+          current_media_query_list_id = nil
+          current_media_query = nil
+          in_media_block = false
 
-  # Helper: formatted serialization without nesting support
-  def self._stylesheet_to_formatted_s_without_nesting(rules, result, selector_lists, media_queries = [], media_query_lists = {})
-    _serialize_stylesheet_with_grouping(
-      rules: rules,
-      result: result,
-      selector_lists: selector_lists,
-      media_queries: media_queries,
-      media_query_lists: media_query_lists,
-      opening_brace: " {\n",
-      closing_brace: "}\n",
-      media_indent: '  ',
-      decl_indent_base: '  ',
-      decl_indent_media: '    ',
-      add_blank_lines: true
-    )
-  end
+          @rules.each do |rule|
+            next if rule_parent_id(rule)
+
+            rule_media_query_id = rule.media_query_id
+            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_query.nil?
+              if in_media_block
+                @result << "}\n"
+                in_media_block = false
+                current_media_query = nil
+                current_media_query_list_id = nil
+              end
+
+              # Blank line before a base rule if we just closed a media block (ends with "}\n")
+              if @result.length > 1 && @result.getbyte(-1) == BYTE_NEWLINE && @result.getbyte(-2) == BYTE_RBRACE
+                @result << "\n"
+              end
+
+              serialize_rule_with_nesting_formatted(rule, '')
+            else
+              needs_new_block = needs_new_media_block?(current_media_query, current_media_query_list_id,
+                                                       rule_media_query, rule_media_query_list_id)
+
+              if needs_new_block
+                if in_media_block
+                  @result << "}\n"
+                elsif @result.length > 0
+                  @result << "\n"
+                end
+                current_media_query = rule_media_query
+                current_media_query_list_id = rule_media_query_list_id
+                media_query_string = build_media_query_string(rule_media_query, rule_media_query_list_id)
+                @result << "@media #{media_query_string} {\n"
+                in_media_block = true
+              end
+
+              serialize_rule_with_nesting_formatted(rule, '  ')
+            end
+          end
 
-  # Helper: serialize a rule with nested children (formatted)
-  def self._serialize_rule_with_nesting_formatted(result, rule, rule_children, indent, media_queries)
-    # Check if this is an AtRule - it can never have nested children of its
-    # own via rule_children (only Rule participates in CSS nesting), so it
-    # always serializes the same way regardless of has_nesting
-    if rule.is_a?(AtRule)
-      _serialize_at_rule_formatted(result, rule, indent)
-      return
-    end
+          @result << "}\n" if in_media_block
+        end
 
-    # Selector line with opening brace
-    result << indent
-    result << rule.selector
-    result << " {\n"
+        def serialize_rule_with_nesting_formatted(rule, indent)
+          if rule.is_a?(AtRule)
+            serialize_at_rule_formatted(rule, indent)
+            return
+          end
 
-    # Serialize declarations (one per line)
-    unless rule.declarations.empty?
-      _serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
-    end
+          @result << indent
+          @result << rule.selector
+          @result << " {\n"
 
-    _serialize_children_formatted(result, rule.selector, rule_children[rule.id] || [], rule_children, media_queries, "#{indent}  ")
+          serialize_declarations_formatted(rule.declarations, "#{indent}  ") unless rule.declarations.empty?
 
-    # Closing brace
-    result << indent
-    result << "}\n"
-  end
+          serialize_children_formatted(rule.selector, @rule_children[rule.id] || [], "#{indent}  ")
 
-  # Helper: recursively serialize a rule's nested children with indentation.
-  # CSS nesting can go as deep as the parser allows (MAX_PARSE_DEPTH), so this
-  # recurses rather than hand-unrolling a fixed number of levels - a nested
-  # rule's own nested rules are found the same way its parent's were, via
-  # rule_children[id], with the indent growing by one level each call.
-  def self._serialize_children_formatted(result, parent_selector, children, rule_children, media_queries, indent)
-    children.each do |child|
-      if child.nesting_style.nil? && child.media_query_id && media_queries[child.media_query_id]
-        # Nested @media
-        mq = media_queries[child.media_query_id]
-        media_query_string = _build_media_query_string(mq, nil, nil, media_queries)
-        result << indent
-        result << "@media #{media_query_string} {\n"
-
-        unless child.declarations.empty?
-          _serialize_declarations_formatted(result, child.declarations, "#{indent}  ")
+          @result << indent
+          @result << "}\n"
         end
 
-        # Handle nested media children
-        media_children = rule_children[child.id] || []
-        media_children.each do |media_child|
-          nested_media_selector = _reconstruct_nested_selector(
-            child.selector,
-            media_child.selector,
-            media_child.nesting_style
-          )
-
-          result << indent
-          result << "  #{nested_media_selector} {\n"
-          unless media_child.declarations.empty?
-            _serialize_declarations_formatted(result, media_child.declarations, "#{indent}    ")
+        # Recursively serialize a rule's nested children with indentation. CSS
+        # nesting can go as deep as the parser allows (MAX_PARSE_DEPTH), so this
+        # recurses rather than hand-unrolling a fixed number of levels - a nested
+        # rule's own nested rules are found the same way its parent's were, via
+        # @rule_children[id], with the indent growing by one level each call.
+        def serialize_children_formatted(parent_selector, children, indent)
+          children.each do |child|
+            if child.nesting_style.nil? && child.media_query_id && @media_queries[child.media_query_id]
+              mq = @media_queries[child.media_query_id]
+              media_query_string = build_media_query_string(mq, nil)
+              @result << indent
+              @result << "@media #{media_query_string} {\n"
+
+              serialize_declarations_formatted(child.declarations, "#{indent}  ") unless child.declarations.empty?
+
+              media_children = @rule_children[child.id] || []
+              media_children.each do |media_child|
+                nested_media_selector = reconstruct_nested_selector(
+                  child.selector, media_child.selector, media_child.nesting_style
+                )
+
+                @result << indent
+                @result << "  #{nested_media_selector} {\n"
+                unless media_child.declarations.empty?
+                  serialize_declarations_formatted(media_child.declarations, "#{indent}    ")
+                end
+                @result << indent
+                @result << "  }\n"
+              end
+
+              @result << indent
+              @result << "}\n"
+            else
+              nested_selector = reconstruct_nested_selector(parent_selector, child.selector, child.nesting_style)
+
+              @result << indent
+              @result << "#{nested_selector} {\n"
+
+              serialize_declarations_formatted(child.declarations, "#{indent}  ") unless child.declarations.empty?
+
+              serialize_children_formatted(child.selector, @rule_children[child.id] || [], "#{indent}  ")
+
+              @result << indent
+              @result << "}\n"
+            end
           end
-          result << indent
-          result << "  }\n"
         end
 
-        result << indent
-        result << "}\n"
-      else
-        # Regular nested selector
-        nested_selector = _reconstruct_nested_selector(parent_selector, child.selector, child.nesting_style)
+        def serialize_rule_formatted(rule, indent, is_last_rule = false)
+          if rule.is_a?(AtRule)
+            serialize_at_rule_formatted(rule, indent)
+            return
+          end
+
+          @result << indent
+          @result << rule.selector
+          @result << " {\n"
 
-        result << indent
-        result << "#{nested_selector} {\n"
+          serialize_declarations_formatted(rule.declarations, "#{indent}  ")
 
-        unless child.declarations.empty?
-          _serialize_declarations_formatted(result, child.declarations, "#{indent}  ")
+          # Closing brace - double newline for all except last rule
+          @result << indent
+          @result << (is_last_rule ? "}\n" : "}\n\n")
         end
 
-        # Recurse into this child's own nested children, however deep they go
-        _serialize_children_formatted(result, child.selector, rule_children[child.id] || [], rule_children, media_queries, "#{indent}  ")
+        def serialize_at_rule_formatted(at_rule, indent)
+          @result << indent
+          @result << at_rule.selector
+          @result << " {\n"
+
+          if at_rule.content.length > 0
+            first = at_rule.content[0]
+
+            if first.is_a?(Rule)
+              at_rule.content.each do |nested_rule|
+                @result << indent
+                @result << '  '
+                @result << nested_rule.selector
+                @result << " {\n"
+
+                serialize_declarations_formatted(nested_rule.declarations, "#{indent}    ")
+
+                @result << indent
+                @result << "  }\n"
+              end
+            else
+              serialize_declarations_formatted(at_rule.content, "#{indent}  ")
+            end
+          end
 
-        result << indent
-        result << "}\n"
+          @result << indent
+          @result << "}\n"
+        end
       end
-    end
-  end
-
-  # Helper: serialize a single rule with formatting
-  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)
-      return
-    end
-
-    # Regular Rule serialization with formatting
-    # Selector line with opening brace
-    result << indent
-    result << rule.selector
-    result << " {\n"
-
-    # Declarations (one per line)
-    _serialize_declarations_formatted(result, rule.declarations, "#{indent}  ")
 
-    # Closing brace - double newline for all except last rule
-    result << indent
-    result << (is_last_rule ? "}\n" : "}\n\n")
-  end
+      # Serialize stylesheet to compact CSS string.
+      #
+      # @param rules [Array<Rule>] Array of rules
+      # @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
+      # @param media_query_lists [Hash] List ID => array of MediaQuery IDs (for comma-separated queries)
+      # @return [String] Compact CSS string
+      def stylesheet_to_s(rules, charset, has_nesting, selector_lists = {}, media_queries = [], media_query_lists = {})
+        Serializer.new(rules, charset, has_nesting, selector_lists, media_queries, media_query_lists, formatted: false).to_s
+      end
 
-  # Helper: serialize an at-rule with formatting
-  def self._serialize_at_rule_formatted(result, at_rule, indent)
-    result << indent
-    result << at_rule.selector
-    result << " {\n"
-
-    # Check if content is rules or declarations
-    if at_rule.content.length > 0
-      first = at_rule.content[0]
-
-      if first.is_a?(Rule)
-        # Serialize as nested rules (e.g., @keyframes) with formatting
-        at_rule.content.each do |nested_rule|
-          # Nested selector with opening brace (2-space indent)
-          result << indent
-          result << '  '
-          result << nested_rule.selector
-          result << " {\n"
-
-          # Declarations (one per line, 4-space indent)
-          _serialize_declarations_formatted(result, nested_rule.declarations, "#{indent}    ")
-
-          # Closing brace (2-space indent)
-          result << indent
-          result << "  }\n"
-        end
-      else
-        # Serialize as declarations (e.g., @font-face, one per line)
-        _serialize_declarations_formatted(result, at_rule.content, "#{indent}  ")
+      # Serialize stylesheet to formatted CSS string (with indentation).
+      #
+      # @param rules [Array<Rule>] Array of rules
+      # @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
+      # @param media_query_lists [Hash] List ID => array of MediaQuery IDs (for comma-separated queries)
+      # @return [String] Formatted CSS string
+      def stylesheet_to_formatted_s(rules, charset, has_nesting, selector_lists = {}, media_queries = [],
+                                    media_query_lists = {})
+        Serializer.new(rules, charset, has_nesting, selector_lists, media_queries, media_query_lists,
+                       formatted: true).to_s
       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, :_needs_new_media_block?, :_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