activemail 1.2.3 → 2.1.0

data/lib/activemail/components/cta.rb

@@ -1,48 +1,24 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'button_renderer'
 
 module ActiveMail
   module Components
-    # Colors read from tokens at transform time (runtime config), not load-time constants.
-    # Styles are inlined so the button survives clients that strip <style> (Gmail mobile…).
-    class Cta < Base
+    class Cta < ButtonRenderer
       extend T::Sig
 
-      sig { override.overridable.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      sig { override.returns(String) }
+      def root_class
+        'cta'
+      end
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
         # A CTA without a link is an authoring bug — surface it at render time.
         raise ArgumentError, '<cta> requires an href attribute' if node.attr('href').to_s.strip.empty?
 
-        style = ActiveMail.tokens.button_style(class?(node, 'secondary') ? :secondary : :primary)
-        anchor = %(<a href="#{escape_attr(node.attr('href'))}"#{link_attributes(node)} ) +
-                 %(style="#{link_style(style)}">#{inner}</a>)
-        bulletproof_button_table(
-          outer_classes: combine_classes(node, 'cta'),
-          inner: anchor,
-          cell_style: cell_style(style)
-        )
-      end
-
-      private
-
-      sig { params(style: ActiveMail::Tokens::ButtonStyle).returns(String) }
-      def cell_style(style)
-        "background:#{style.background};border-radius:#{style.radius};#{border_css(style)}"
-      end
-
-      # No border here: it lives on the cell only — a repeated <a> border doubles the line.
-      sig { params(style: ActiveMail::Tokens::ButtonStyle).returns(String) }
-      def link_style(style)
-        "display:inline-block;text-decoration:none;#{BUTTON_PADDING}" \
-          "background:#{style.background};color:#{style.color};font-weight:bold;" \
-          "border-radius:#{style.radius};"
-      end
-
-      sig { params(style: ActiveMail::Tokens::ButtonStyle).returns(String) }
-      def border_css(style)
-        style.border ? "border:1px solid #{style.border};" : ''
+        super
       end
     end
   end

data/lib/activemail/components/h_line.rb

@@ -1,18 +1,16 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class HLine < Base
+    class HLine < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, _inner: String).returns(String) }
       def transform(node, _inner)
-        classes = combine_classes(node, 'h-line')
-        attributes = pass_through_attributes(node)
-        %(<table #{attributes}class="#{classes}" #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr><th>&nbsp;</th></tr></tbody></table>)
+        %(<table#{root_attributes(node, classes: 'h-line', layout_style: 'width:100%;')} #{TABLE_RESET}><tbody><tr><th>&nbsp;</th></tr></tbody></table>)
       end
     end
   end

data/lib/activemail/components/info_box.rb

@@ -1,19 +1,18 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
     # Colors read from tokens at transform time (runtime config), not load-time constants.
-    class InfoBox < Base
+    class InfoBox < TableComponent
       extend T::Sig
 
       sig { override.overridable.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
-        classes = combine_classes(node, 'info-box')
         [
-          %(<table class="#{classes}" #{TABLE_RESET} style="width:100%;"><tbody><tr>),
+          %(<table#{root_attributes(node, classes: 'info-box', layout_style: 'width:100%;')} #{TABLE_RESET}><tbody><tr>),
           %(<td style="#{cell_style}">#{inner}</td>),
           '</tr></tbody></table>'
         ].join
@@ -21,16 +20,11 @@ module ActiveMail
 
       private
 
-      # Box-scoped tokens (fall back to page-level ones) so a host can give the box
-      # a distinct surface without colliding with :background/:border/:text.
       sig { returns(String) }
       def cell_style
-        tokens = ActiveMail.tokens
-        background = tokens.color(:info_box_background) || tokens.color!(:background)
-        border = tokens.color(:info_box_border) || tokens.color!(:border)
-        text = tokens.color(:info_box_text) || tokens.color!(:text)
-        "background-color:#{background};border-left:5px solid #{border};border-radius:#{tokens.radius!(:box)};" \
-          "color:#{text};padding:#{tokens.spacing!(:md)};"
+        tokens = core.config.tokens
+        "background-color:#{tokens.color!(:info_box_background)};border-left:5px solid #{tokens.color!(:info_box_border)};" \
+          "border-radius:#{tokens.radius!(:box)};color:#{tokens.color!(:info_box_text)};padding:#{tokens.spacing!(:md)};"
       end
     end
   end

data/lib/activemail/components/menu.rb

@@ -1,18 +1,17 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class Menu < Base
+    class Menu < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
-        attributes = combine_attributes(node, 'menu')
         [
-          %(<table #{attributes} #{TABLE_RESET}#{style_attribute(node)}><tbody><tr><td>),
+          %(<table#{root_attributes(node, classes: 'menu')} #{TABLE_RESET}><tbody><tr><td>),
           %(<table #{TABLE_RESET}><tbody><tr>#{inner}</tr></tbody></table>),
           '</td></tr></tbody></table>'
         ].join

data/lib/activemail/components/menu_item.rb

@@ -10,11 +10,18 @@ module ActiveMail
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
-        attributes = combine_attributes(node, 'menu-item')
+        attributes = root_attributes(node, classes: 'menu-item')
         # No href → a non-link item, not a broken <a href="">; mirrors <button>.
-        content = node.attr('href') ? %(<a href="#{escape_attr(node.attr('href'))}"#{link_attributes(node)}>#{inner}</a>) : inner
+        content = node.attr('href') ? anchor(node, inner) : inner
         th = ::ActiveMail::Core::INTERIM_TH_TAG
-        %(<#{th} #{attributes}#{style_attribute(node)}>#{content}</#{th}>)
+        %(<#{th}#{attributes}>#{content}</#{th}>)
+      end
+
+      private
+
+      sig { override.returns(T::Array[String]) }
+      def consumed_attributes
+        LINK_ATTRIBUTES
       end
     end
   end

data/lib/activemail/components/row.rb

@@ -1,17 +1,16 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class Row < Base
+    class Row < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
-        attributes = combine_attributes(node, 'row')
-        %(<table #{attributes} #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>#{inner}</tr></tbody></table>)
+        %(<table#{root_attributes(node, classes: 'row', layout_style: 'width:100%;')} #{TABLE_RESET}><tbody><tr>#{inner}</tr></tbody></table>)
       end
     end
   end

data/lib/activemail/components/spacer.rb

@@ -1,41 +1,45 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class Spacer < Base
+    class Spacer < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, _inner: String).returns(String) }
       def transform(node, _inner)
-        classes = combine_classes(node, 'spacer')
         size_sm = node.attr('size-sm')
         size_lg = node.attr('size-lg')
 
-        return build_table(node, classes, nil, size_for(node.attr('size'))) unless size_sm || size_lg
+        return build_table(node, 'spacer', size_for(node.attr('size')), skip: []) unless size_sm || size_lg
 
-        html = +''
-        html << build_table(node, classes, 'hide-for-large', size_for(size_sm)) if size_sm
-        html << build_table(node, classes, 'show-for-large', size_for(size_lg)) if size_lg
-        html
+        tables = []
+        tables << ['spacer hide-for-large', size_for(size_sm)] if size_sm
+        tables << ['spacer show-for-large', size_for(size_lg)] if size_lg
+        tables.each_with_index.map { |(classes, size), index| build_table(node, classes, size, skip: index.zero? ? [] : %w[id]) }.join
       end
 
       private
 
+      sig { override.returns(T::Array[String]) }
+      def consumed_attributes
+        [*super, 'size', 'size-sm', 'size-lg']
+      end
+
       sig { params(value: T.untyped).returns(Integer) }
       def size_for(value)
         positive_int(value) || 16
       end
 
-      sig { params(node: Nokogiri::XML::Node, classes: String, extra: T.nilable(String), size: Integer).returns(String) }
-      def build_table(node, classes, extra, size)
-        css_class = extra ? "#{classes} #{extra}" : classes
+      # A repeated id would be invalid HTML: only the first table carries it.
+      sig { params(node: Nokogiri::XML::Node, classes: String, size: Integer, skip: T::Array[String]).returns(String) }
+      def build_table(node, classes, size, skip:)
         # mso-line-height-rule:exactly keeps Outlook from inflating the spacer.
         style = "font-size:#{size}px;line-height:#{size}px;mso-line-height-rule:exactly;"
         [
-          %(<table class="#{css_class}" #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>),
+          %(<table#{root_attributes(node, classes: classes, layout_style: 'width:100%;', skip: skip)} #{TABLE_RESET}><tbody><tr>),
           %(<td height="#{size}" style="#{style}">&nbsp;</td>),
           '</tr></tbody></table>'
         ].join

data/lib/activemail/components/table_component.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    # Root element is a layout table: its reset attributes are fixed, not author-overridable.
+    class TableComponent < Base
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      private
+
+      sig { override.overridable.returns(T::Array[String]) }
+      def consumed_attributes
+        TABLE_RESET_ATTRIBUTES
+      end
+    end
+  end
+end

data/lib/activemail/components/wrapper.rb

@@ -1,21 +1,27 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class Wrapper < Base
+    class Wrapper < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
-        attributes = combine_attributes(node, 'wrapper')
         [
-          %(<table #{attributes} #{TABLE_RESET} align="center"#{style_attribute(node, 'width:100%;')}><tbody><tr>),
+          %(<table#{root_attributes(node, classes: 'wrapper', layout_style: 'width:100%;')} #{TABLE_RESET} align="center"><tbody><tr>),
           %(<td class="wrapper-inner">#{inner}</td></tr></tbody></table>)
         ].join
       end
+
+      private
+
+      sig { override.returns(T::Array[String]) }
+      def consumed_attributes
+        [*super, 'align']
+      end
     end
   end
 end

data/lib/activemail/configuration.rb

@@ -4,10 +4,7 @@
 require 'sorbet-runtime'
 
 require_relative 'tokens'
-require_relative 'inliner/base'
-require_relative 'inliner/premailer'
-require_relative 'inliner/roadie'
-require_relative 'inliner/null'
+require_relative 'inliner'
 
 module ActiveMail
   extend T::Sig
@@ -36,17 +33,17 @@ module ActiveMail
     block.call(configuration)
   end
 
-  # Parse mode (and the Guard's same decision): a full document carries <html.
+  # <html[\s>] so a <htmlfoo> custom tag or "<html" in text never flips the parse mode.
   sig { params(html: String).returns(T::Boolean) }
   def self.full_document?(html)
-    html.match?(/<html/i)
+    html.match?(/<html[\s>]/i)
   end
 
-  # The complete SCSS variable bridge — tokens + the container_width layout knob.
   # Single source for the .scss.erb bridge (Sprockets) and tokens:export (Propshaft).
   sig { returns(String) }
   def self.scss_variables
-    "#{tokens.to_scss}$am-grid-container-width: #{configuration.container_width}px !default;\n"
+    "#{tokens.to_scss}$am-grid-container-width: #{configuration.container_width}px !default;\n" \
+      "$am-column-count: #{configuration.column_count} !default;\n"
   end
 
   # Route warnings to the app logger when present (Sentry breadcrumbs, log
@@ -67,9 +64,8 @@ module ActiveMail
 
   # Invalid bytes degrade deterministically to U+FFFD, but that silently corrupts
   # content — surface it per on_parse_error before scrubbing.
-  sig { params(html_string: String).returns(String) }
-  def self.scrub_invalid_bytes(html_string)
-    mode = configuration.on_parse_error
+  sig { params(html_string: String, mode: Symbol).returns(String) }
+  def self.scrub_invalid_bytes(html_string, mode)
     message = '[activemail] input had invalid byte sequences; scrubbed to U+FFFD'
     raise ParseError, message if mode == :raise
 
@@ -77,20 +73,25 @@ module ActiveMail
     html_string.scrub
   end
 
-  # Zero or negative dimensions blow up at transform time (Infinity ghost width).
-  # Reject non-integers rather than silently coercing ("abc"→0, 12.9→12).
+  # Rejects non-integers rather than silently coercing ("abc"→0, 12.9→12); zero or
+  # negative dimensions blow up at transform time (Infinity ghost width).
   sig { params(name: Symbol, value: T.untyped).returns(Integer) }
-  def self.assert_positive_dimension!(name, value)
-    raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}" unless value.is_a?(Integer) && value.positive?
+  def self.positive_integer!(name, value)
+    raise TypeError, "#{name} must be an Integer, got #{value.inspect} (#{value.class})" unless value.is_a?(Integer)
+    raise ArgumentError, "#{name} must be positive, got #{value}" unless value.positive?
 
     value
   end
 
-  sig { params(name: Symbol, value: T.untyped).returns(Integer) }
-  def self.positive_integer!(name, value)
-    raise TypeError, "#{name} must be an Integer, got #{value.inspect} (#{value.class})" unless value.is_a?(Integer)
+  # Author attributes are untrusted strings: base 10 only (Integer() reads "010" as
+  # octal and "0x20" as hex), nil when not a positive integer.
+  sig { params(value: T.untyped).returns(T.nilable(Integer)) }
+  def self.parse_positive_integer(value)
+    string = value.to_s.strip
+    return unless string.match?(/\A\d+\z/)
 
-    assert_positive_dimension!(name, value)
+    int = string.to_i
+    int if int.positive?
   end
 
   class Configuration
@@ -98,27 +99,9 @@ module ActiveMail
 
     ON_PARSE_ERROR_MODES = T.let(%i[ignore warn raise].freeze, T::Array[Symbol])
 
-    INLINERS = T.let(
-      { premailer: ActiveMail::Inliner::Premailer, roadie: ActiveMail::Inliner::Roadie, null: ActiveMail::Inliner::Null }.freeze,
-      T::Hash[Symbol, T.class_of(ActiveMail::Inliner::Base)]
-    )
-
-    InlinerSetting = T.type_alias { T.any(Symbol, ActiveMail::Inliner::Base, T.class_of(ActiveMail::Inliner::Base)) }
-
-    sig { returns(InlinerSetting) }
+    sig { returns(ActiveMail::Inliner::Setting) }
     attr_reader :inliner
 
-    # Lets a host already running another inliner (e.g. premailer-rails) opt out.
-    sig { returns(T::Boolean) }
-    attr_reader :register_inline_interceptor
-
-    sig { params(value: T.untyped).void }
-    def register_inline_interceptor=(value)
-      raise TypeError, 'register_inline_interceptor must be true or false' unless [true, false].include?(value)
-
-      @register_inline_interceptor = value
-    end
-
     sig { returns(Symbol) }
     attr_reader :template_engine, :on_parse_error
 
@@ -146,26 +129,27 @@ module ActiveMail
       @container_width = T.let(600, Integer)
       @components = T.let({}, ActiveMail::ComponentMap)
       @on_parse_error = T.let(:warn, Symbol)
-      @tokens = T.let(nil, T.nilable(ActiveMail::Tokens))
-      @inliner = T.let(:premailer, InlinerSetting)
-      @resolved_inliner = T.let(nil, T.nilable(ActiveMail::Inliner::Base))
-      @register_inline_interceptor = T.let(true, T::Boolean)
+      @inliner = T.let(:premailer, ActiveMail::Inliner::Setting)
       @blank_link_rel = T.let('noopener', T.nilable(String))
     end
 
+    # Shared: building the component map per render is pure overhead.
+    sig { returns(ActiveMail::Core) }
+    def core
+      @core ||= T.let(ActiveMail::Core.new(config: self), T.nilable(ActiveMail::Core))
+    end
+
     # Validates eagerly (like sibling setters): a typo fails at boot, not silently mid-delivery.
-    sig { params(value: T.any(Symbol, String, ActiveMail::Inliner::Base, T.class_of(ActiveMail::Inliner::Base))).returns(InlinerSetting) }
+    sig { params(value: T.any(String, ActiveMail::Inliner::Setting)).returns(ActiveMail::Inliner::Setting) }
     def inliner=(value)
-      resolved = value.is_a?(String) ? value.to_sym : value
-      resolve_inliner(resolved) # raises on an invalid value, eagerly
-      @resolved_inliner = nil   # a new setting invalidates the memoized instance
-      @inliner = resolved
+      setting = value.is_a?(String) ? value.to_sym : value
+      @resolved_inliner = T.let(ActiveMail::Inliner.resolve(setting), T.nilable(ActiveMail::Inliner::Base))
+      @inliner = setting
     end
 
-    # Memoized so the lifecycle is consistent (one instance reused, not re-built per call).
     sig { returns(ActiveMail::Inliner::Base) }
     def resolved_inliner
-      @resolved_inliner ||= resolve_inliner(@inliner)
+      @resolved_inliner ||= T.let(ActiveMail::Inliner.resolve(@inliner), T.nilable(ActiveMail::Inliner::Base))
     end
 
     sig { params(value: T.untyped).returns(Symbol) }
@@ -186,11 +170,15 @@ module ActiveMail
     sig { params(value: T.untyped).returns(Integer) }
     def column_count=(value)
       @column_count = ActiveMail.positive_integer!(:column_count, value)
+      invalidate_core!
+      @column_count
     end
 
     sig { params(value: T.untyped).returns(Integer) }
     def container_width=(value)
       @container_width = ActiveMail.positive_integer!(:container_width, value)
+      invalidate_core!
+      @container_width
     end
 
     sig { params(value: T.untyped).returns(T.nilable(String)) }
@@ -209,6 +197,8 @@ module ActiveMail
       normalized = value.to_hash.transform_keys(&:to_s)
       normalized.each { |tag, klass| ActiveMail::Components.validate_component!(tag, klass) }
       @components = normalized
+      invalidate_core!
+      normalized
     end
 
     sig { params(tag: T.any(String, Symbol), component_class: T.class_of(ActiveMail::Components::Base)).void }
@@ -216,18 +206,14 @@ module ActiveMail
       ActiveMail::Components.validate_component!(tag, component_class)
 
       @components = @components.merge(tag.to_s => component_class)
+      invalidate_core!
     end
 
     private
 
-    # Single source for both eager validation (in the setter) and resolution.
-    sig { params(value: InlinerSetting).returns(ActiveMail::Inliner::Base) }
-    def resolve_inliner(value)
-      return value if value.is_a?(ActiveMail::Inliner::Base)
-      return value.new if value.is_a?(Class) && value < ActiveMail::Inliner::Base
-      return T.must(INLINERS[value]).new if value.is_a?(Symbol) && INLINERS.key?(value)
-
-      raise ArgumentError, "unknown inliner #{value.inspect}, expected one of #{INLINERS.keys.inspect}, an Inliner::Base subclass, or an instance"
+    sig { void }
+    def invalidate_core!
+      @core = nil
     end
   end
 end

data/lib/activemail/errors.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ActiveMail
+  class Error < StandardError; end
+
+  class ParseError < Error; end
+
+  class StylesheetNotFound < Error; end
+
+  module Inliner
+    # The adapter's original exception is preserved as Exception#cause.
+    class Error < ActiveMail::Error; end
+  end
+end

data/lib/activemail/inliner/base.rb

@@ -3,12 +3,10 @@
 
 require 'sorbet-runtime'
 
+require_relative '../errors'
+
 module ActiveMail
   module Inliner
-    # Raised when an adapter fails; the original (premailer/roadie/nokogiri)
-    # exception is preserved as Exception#cause with its backtrace intact.
-    class Error < StandardError; end
-
     # DIP seam: ActiveMail depends on this abstraction, not premailer/roadie.
     class Base
       extend T::Sig
@@ -18,12 +16,6 @@ module ActiveMail
 
       sig { abstract.params(html: String).returns(String) }
       def inline(html); end
-
-      # Lets the interceptor skip work without type-checking concrete adapters.
-      sig { returns(T::Boolean) }
-      def noop?
-        false
-      end
     end
   end
 end

data/lib/activemail/inliner/null.rb

@@ -13,11 +13,6 @@ module ActiveMail
       def inline(html)
         html
       end
-
-      sig { override.returns(T::Boolean) }
-      def noop?
-        true
-      end
     end
   end
 end

data/lib/activemail/inliner/premailer/document.rb

@@ -0,0 +1,100 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'digest'
+require 'premailer'
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Inliner
+    class Premailer < Base
+      # Premailer re-parses every <style> block with css_parser on each email; the framework
+      # CSS never changes between two emails, so its rule sets are parsed once per fingerprint.
+      class Document < ::Premailer
+        extend T::Sig
+
+        # Mirrors the parser Premailer builds for these options.
+        PARSER_OPTIONS = T.let(
+          { absolute_paths: true, import: true, io_exceptions: false, rule_set_exceptions: true, allow_local_network: false }.freeze,
+          T::Hash[Symbol, T.untyped]
+        )
+
+        # FIFO-bounded and thread-safe: mailers render from several threads and a dev reload
+        # compiles new CSS under a new fingerprint.
+        class RuleSetCache
+          extend T::Sig
+
+          LIMIT = 16
+
+          sig { void }
+          def initialize
+            @entries = T.let({}, T::Hash[T.untyped, T.untyped])
+            @mutex = T.let(Mutex.new, Mutex)
+          end
+
+          sig { params(key: T.untyped, block: T.proc.returns(T.untyped)).returns(T.untyped) }
+          def fetch(key, &block)
+            @mutex.synchronize { @entries[key] } || store(key, block.call)
+          end
+
+          sig { void }
+          def clear
+            @mutex.synchronize { @entries.clear }
+          end
+
+          sig { returns(Integer) }
+          def size
+            @mutex.synchronize { @entries.size }
+          end
+
+          private
+
+          sig { params(key: T.untyped, value: T.untyped).returns(T.untyped) }
+          def store(key, value)
+            @mutex.synchronize do
+              @entries[key] = value
+              @entries.shift while @entries.size > LIMIT
+            end
+            value
+          end
+        end
+
+        class CachedParser < ::CssParser::Parser
+          extend T::Sig
+
+          sig { params(block: String, options: T::Hash[Symbol, T.untyped]).void }
+          def add_block!(block, options = {})
+            Document.rule_sets.fetch([Digest::SHA256.hexdigest(block), options]) { parse(block, options) }.each do |rule_set, media_types|
+              add_rule_set!(rule_set, media_types)
+            end
+          end
+
+          private
+
+          sig { params(block: String, options: T::Hash[Symbol, T.untyped]).returns(T::Array[T.untyped]) }
+          def parse(block, options)
+            parser = ::CssParser::Parser.new(PARSER_OPTIONS)
+            parser.add_block!(block, options)
+            rule_sets = T.let([], T::Array[T.untyped])
+            parser.each_rule_set { |rule_set, media_types| rule_sets << [rule_set, media_types] }
+            rule_sets
+          end
+        end
+
+        sig { returns(RuleSetCache) }
+        def self.rule_sets
+          @rule_sets ||= T.let(RuleSetCache.new, T.nilable(RuleSetCache))
+        end
+
+        protected
+
+        # Premailer exposes no hook for its parser: swap it before the <style> blocks are read.
+        sig { void }
+        def load_css_from_html!
+          T.unsafe(self).instance_variable_set(:@css_parser, CachedParser.new(PARSER_OPTIONS))
+          super
+        end
+      end
+    end
+  end
+end