goodmail 0.3.1 → 0.4.0

data/lib/goodmail/configuration.rb

@@ -4,6 +4,8 @@ require "ostruct"
 module Goodmail
   # Handles configuration settings for the Goodmail gem.
   module Configuration
+    THREAD_CONFIG_KEY = :goodmail_current_config
+
     # Default configuration values
     DEFAULT_CONFIG = OpenStruct.new(
       brand_color:  "#348eda",
@@ -29,22 +31,57 @@ module Goodmail
     # Provides the configuration block helper.
     # Ensures validation runs after the block is executed.
     def configure
-      yield config # Ensures config is initialized via accessor
-      validate_config!(config)
+      yield global_config # Ensures global config is initialized via accessor
+      validate_config!(global_config)
     end
 
     # Returns the current configuration object.
     # Initializes with a copy of the defaults if not already configured.
     def config
+      Thread.current[THREAD_CONFIG_KEY] || global_config
+    end
+    alias_method :configuration, :config
+
+    # Runs a block with a per-render configuration override in the current
+    # thread. This keeps whitelabel / tenant-specific emails from mutating the
+    # process-wide config while preserving the existing `Goodmail.config` read
+    # path used by Builder, Layout, and Plaintext.
+    #
+    # Source: Ruby thread-local variables:
+    # https://docs.ruby-lang.org/en/3.4/Thread.html#method-i-5B-5D
+    def with_config(overrides)
+      return yield if overrides.nil?
+
+      previous_config = Thread.current[THREAD_CONFIG_KEY]
+      Thread.current[THREAD_CONFIG_KEY] = config_with(overrides)
+      yield
+    ensure
+      Thread.current[THREAD_CONFIG_KEY] = previous_config if defined?(previous_config)
+    end
+
+    def config_with(overrides)
+      override_config = config.dup
+      if overrides.respond_to?(:to_h)
+        overrides.to_h.each { |key, value| override_config[key] = value }
+      else
+        overrides.each_pair { |key, value| override_config[key] = value }
+      end
+      validate_config!(override_config)
+      override_config
+    end
+
+    # Returns the process-wide configuration object, ignoring any temporary
+    # per-render override installed by `with_config`.
+    def global_config
       @config = DEFAULT_CONFIG.dup unless defined?(@config) && @config
       @config
     end
-    alias_method :configuration, :config
 
     # Resets the configuration back to the default values.
     # Primarily useful for testing environments.
     def reset_config!
       @config = nil
+      Thread.current[THREAD_CONFIG_KEY] = nil
     end
 
     private

data/lib/goodmail/dispatcher.rb

@@ -1,60 +1,59 @@
 # frozen_string_literal: true
 require "action_mailer"
-require "cgi" # For unescaping HTML in plaintext generation
-require_relative "mailer" # Require the internal mailer
+require_relative "mailer"
 
 module Goodmail
-  # Responsible for orchestrating the building of the Mail::Message object.
+  # Responsible for orchestrating the building of the Action Mailer delivery.
   module Dispatcher
     extend self
 
-    # Builds the Mail::Message object with HTML and Text parts, wrapped in
-    # an ActionMailer::MessageDelivery object.
+    # Builds an ActionMailer::MessageDelivery with HTML and text parts.
     # @api private
     def build_message(headers, &block)
-      # 1. Initialize the Builder
-      builder = Goodmail::Builder.new
-
-      # 2. Execute the DSL block within the Builder instance
-      builder.instance_eval(&block) if block_given?
-
-      # 3. Determine the final unsubscribe URL (user-provided)
-      unsubscribe_url = headers[:unsubscribe_url] || Goodmail.config.unsubscribe_url
-
-      # 4. Determine preheader text (priority: header > config > subject)
-      preheader = headers[:preheader] || Goodmail.config.default_preheader || headers[:subject]
-
-      # 5. Render the raw HTML body using the Layout
-      raw_html_body = Goodmail::Layout.render(
-        builder.html_output,
-        headers[:subject],
-        unsubscribe_url: unsubscribe_url,
-        preheader: preheader # Pass preheader to layout
-      )
-
-      # 6. Slice standard headers for the mailer action
-      mailer_headers = slice_mail_headers(headers)
-
-      # 7. Build the mail object via the internal Mailer class action.
-      delivery_object = Goodmail::Mailer.compose_message(
-        mailer_headers,
-        raw_html_body,
-        nil, # Pass nil for raw_text_body - Premailer generates it
-        unsubscribe_url
-      )
-
-      # 8. Return the ActionMailer::MessageDelivery object
-      delivery_object
+      headers = headers.dup
+      render_config_overrides = render_config(headers)
+
+      Goodmail.with_config(render_config_overrides) do
+        parts = Goodmail.render(headers, &block)
+
+        # ActionMailer::MessageDelivery processes this mailer action lazily and
+        # `deliver_later` serializes only action arguments, so pass already
+        # rendered strings and plain attachment descriptor hashes into the action.
+        # Sources:
+        # - MessageDelivery laziness:
+        #   https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/message_delivery.rb#L22-L35
+        # - deliver_later serializes mailer action arguments:
+        #   https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/message_delivery.rb#L142-L155
+        Goodmail::Mailer.compose_message(
+          slice_mail_headers(headers),
+          parts.html,
+          parts.text,
+          resolved_unsubscribe_url(headers),
+          parts.attachments
+        )
+      end
     end
 
     private
 
-    # Whitelist standard headers to pass to ActionMailer's mail() method
-    # Excludes custom headers like :unsubscribe_url, :preheader
+    # Pass Action Mailer's normal header surface through, excluding only
+    # Goodmail render-only options such as :unsubscribe_url and :preheader.
     def slice_mail_headers(h)
-      h.slice(:to, :from, :cc, :bcc, :reply_to, :subject)
+      Goodmail.action_mailer_headers(h)
     end
 
-    # Removed generate_plaintext - now handled by Premailer in Mailer#compose_message
+    def render_config(headers)
+      render_option(headers, :config) || render_option(headers, :configuration)
+    end
+
+    def resolved_unsubscribe_url(headers)
+      render_option(headers, :unsubscribe_url) || Goodmail.config.unsubscribe_url
+    end
+
+    def render_option(headers, key)
+      return headers[key] if headers.key?(key)
+
+      headers[key.to_s] if headers.key?(key.to_s)
+    end
   end
 end

data/lib/goodmail/email.rb

@@ -3,69 +3,105 @@ require "premailer"
 require "cgi" # For unescaping HTML in plaintext generation (though Premailer might handle most)
 
 module Goodmail
-  # Simple struct to hold the rendered HTML and text parts of an email.
-  EmailParts = Struct.new(:html, :text, keyword_init: true)
+  # Simple struct to hold the rendered HTML and text parts of an email, plus
+  # any attachments collected via the `attach` / `inline_image` DSL helpers.
+  # Custom Action Mailer classes can call Goodmail's auto-installed
+  # `goodmail_mail_parts(parts, headers)` helper to apply attachments, pin
+  # inline Content-IDs, add unsubscribe headers, and send the multipart body.
+  #
+  # `attachments` defaults to `[]` for backwards compatibility — callers
+  # written against 0.3.x keep working unchanged.
+  EmailParts = Struct.new(:html, :text, :attachments, keyword_init: true) do
+    def initialize(html: nil, text: nil, attachments: [])
+      super(html: html, text: text, attachments: attachments || [])
+    end
+  end
 
   # Renders the email content using the Goodmail DSL and returns HTML and text parts.
   # This method does not send the email but prepares its content for sending.
   #
   # @param headers [Hash] Mail headers. Expected to contain :subject.
-  #                       Can also contain :unsubscribe_url and :preheader to override defaults.
+  #                       Can also contain :unsubscribe_url, :preheader, :locale,
+  #                       :context, :config, and :layout_path to override
+  #                       render-only behavior.
   # @param dsl_block [Proc] Block containing Goodmail DSL calls (text, button, etc.)
   # @return [Goodmail::EmailParts] An object containing the :html and :text email parts.
   def self.render(headers = {}, &dsl_block)
     # 1. Initialize the Builder and execute the DSL block
-    builder = Goodmail::Builder.new
-    builder.instance_eval(&dsl_block) if block_given?
-    core_html_content = builder.html_output
-
-    # 2. Determine unsubscribe_url and preheader
-    #    These are removed from headers as they are Goodmail-specific, not standard mail headers.
     current_headers = headers.dup # Avoid modifying the original headers hash directly
-    unsubscribe_url = current_headers.delete(:unsubscribe_url) || Goodmail.config.unsubscribe_url
-    preheader = current_headers.delete(:preheader) || Goodmail.config.default_preheader || current_headers[:subject]
+    context = render_header_value!(current_headers, :context)
+    locale = render_header_value!(current_headers, :locale)
+    render_config = render_header_value!(current_headers, :config)
+    render_config = render_header_value!(current_headers, :configuration) if render_config.nil?
+    layout_path = render_header_value!(current_headers, :layout_path)
+    subject = render_header_value!(current_headers, :subject)
 
-    # 3. Render the raw HTML body using the Layout
-    #    The subject is passed for the <title> tag and potentially other uses in layout.
-    #    Unsubscribe URL and preheader are passed for inclusion in the layout.
-    raw_html_body = Goodmail::Layout.render(
-      core_html_content,
-      current_headers[:subject], # Use subject from (potentially modified) current_headers
-      unsubscribe_url: unsubscribe_url,
-      preheader: preheader
-    )
+    Goodmail.with_config(render_config) do
+      builder = Goodmail::Builder.new(context: context)
+      evaluate_builder_dsl(builder, locale, &dsl_block)
+      core_html_content = builder.html_output
 
-    # 4. Use Premailer to inline CSS and generate plaintext
-    premailer = Premailer.new(
-      raw_html_body,
-      with_html_string: true,
-      adapter: :nokogiri,
-      preserve_styles: false, # Force inlining and remove <style> block
-      remove_ids: true,       # Remove IDs
-      remove_comments: false  # Keep MSO conditional comments
-    )
+      # 2. Determine unsubscribe_url and preheader
+      #    These are removed from headers as they are Goodmail-specific, not standard mail headers.
+      unsubscribe_url = render_header_value!(current_headers, :unsubscribe_url) || Goodmail.config.unsubscribe_url
+      preheader = render_header_value!(current_headers, :preheader) || Goodmail.config.default_preheader || subject
 
-    final_inlined_html = premailer.to_inline_css
-    generated_plain_text = premailer.to_plain_text
+      # 3. Render the raw HTML body using the Layout
+      #    The subject is passed for the <title> tag and potentially other uses in layout.
+      #    Unsubscribe URL and preheader are passed for inclusion in the layout.
+      raw_html_body = Goodmail::Layout.render(
+        core_html_content,
+        subject,
+        layout_path: layout_path,
+        unsubscribe_url: unsubscribe_url,
+        preheader: preheader
+      )
 
-    # 5. Perform refined plaintext cleanup (ported from Goodmail::Mailer)
-    # 5.1. Remove logo alt text line (if logo exists and has associated URL)
-    if Goodmail.config.logo_url.present? && Goodmail.config.company_url.present? && Goodmail.config.company_name.present?
-      company_name_escaped = Regexp.escape(Goodmail.config.company_name)
-      company_url_escaped = Regexp.escape(Goodmail.config.company_url)
-      # Regex to match the typical alt text pattern for a linked logo image
-      logo_alt_pattern = /^\s*#{company_name_escaped}\s+Logo\s*\(.*?#{company_url_escaped}.*?\).*\n?/i
-      generated_plain_text.gsub!(logo_alt_pattern, "")
+      # 4. Run Premailer for CSS inlining (HTML part). Plaintext goes
+      #    through `Goodmail::Plaintext` which pre-processes the source
+      #    HTML to neutralize MSO-only markup and the hidden preheader
+      #    span — both of which Premailer's plaintext extractor would
+      #    otherwise leak into the text body.
+      premailer = Premailer.new(
+        raw_html_body,
+        with_html_string: true,
+        adapter: :nokogiri,
+        preserve_styles: false, # Force inlining and remove <style> block
+        remove_ids: true,       # Remove IDs
+        remove_comments: false, # Keep MSO conditional comments in HTML
+        input_encoding: "UTF-8" # See Goodmail::Plaintext for the full
+                                # rationale — short version: Premailer
+                                # double-encodes accented characters when
+                                # the source has no <meta charset>.
+      )
+      final_inlined_html = premailer.to_inline_css
+      final_plain_text = Goodmail::Plaintext.generate(raw_html_body, preheader: preheader)
+
+      # 5. Return the structured parts
+      EmailParts.new(
+        html: final_inlined_html,
+        text: final_plain_text,
+        attachments: builder.attachments
+      )
     end
+  end
 
-    # 5.2. Remove any remaining standalone URL lines (often from logo links or similar artifacts)
-    # This targets lines that consist *only* of a URL.
-    generated_plain_text.gsub!(/^\s*https?:\/\/\S+\s*$\n?/i, "")
+  def self.render_header_value!(headers, key)
+    value = headers.delete(key)
+    value = headers.delete(key.to_s) if value.nil? && headers.key?(key.to_s)
+    value
+  end
+  private_class_method :render_header_value!
 
-    # 5.3. Compact excess blank lines (more than two consecutive newlines)
-    generated_plain_text.gsub!(/\n{3,}/, "\n\n")
+  def self.evaluate_builder_dsl(builder, locale, &dsl_block)
+    return unless block_given?
 
-    # 6. Return the structured parts
-    EmailParts.new(html: final_inlined_html, text: generated_plain_text.strip)
+    render_block = proc { builder.instance_eval(&dsl_block) }
+    if !locale.nil? && !locale.to_s.empty? && defined?(I18n)
+      I18n.with_locale(locale, &render_block)
+    else
+      render_block.call
+    end
   end
+  private_class_method :evaluate_builder_dsl
 end

data/lib/goodmail/layout.erb

@@ -107,7 +107,6 @@
       cursor: pointer;
       display: inline-block;
       border-radius: 5px;
-      text-transform: capitalize;
       background-color: <%= config.brand_color %>;
       margin: 0;
       border-color: <%= config.brand_color %>;

data/lib/goodmail/layout.rb

@@ -32,7 +32,7 @@ module Goodmail
         body_html:       body_html,
         subject:         subject || "",
         config:          Goodmail.config, # Make config available
-        unsubscribe_url: unsubscribe_url,  # Pass unsubscribe URL to template
+        unsubscribe_url: unsubscribe_url, # Pass unsubscribe URL to template
         preheader:       preheader # Pass preheader to template
       )
     rescue => e

data/lib/goodmail/mailer.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 require "action_mailer"
-require "premailer" # Require premailer library
 
 module Goodmail
   # Internal Mailer class.
@@ -16,53 +15,29 @@ module Goodmail
     # This instance method acts as the mailer action.
     # It's called via Goodmail::Mailer.compose_message(...)
     # Action Mailer wraps the result in a MessageDelivery object.
-    # It uses Premailer to inline CSS and generate plaintext.
     # @api internal
-    def compose_message(headers, raw_html_body, _raw_text_body, unsubscribe_url)
-      # Initialize Premailer with the raw HTML body from the layout
-      premailer = Premailer.new(
-        raw_html_body,
-        with_html_string: true,
-        # Common options:
-        adapter: :nokogiri,
-        preserve_styles: false, # Set to false to force inlining *and* remove <style> block
-        remove_ids: true, # Can usually remove IDs
-        remove_comments: false, # KEEP conditional comments so MSO conditionals in the template work!
-        # Note: `plain_text_images: false` might exist but is not standard;
-        # relying on gsub cleanup below.
-      )
+    def compose_message(
+      headers,
+      html_body,
+      text_body,
+      unsubscribe_url,
+      dsl_attachments = []
+    )
+      headers = headers.dup
+      goodmail_add_list_unsubscribe_headers!(headers, unsubscribe_url)
+      goodmail_apply_attachments!(dsl_attachments)
 
-      # Get processed content
-      inlined_html = premailer.to_inline_css
-      # Generate plain text, skipping image conversion
-      generated_plain_text = premailer.to_plain_text
-
-      # Clean up plaintext:
-      # 1. Remove logo alt text line (if logo exists and has associated URL)
-      if Goodmail.config.logo_url.present? && Goodmail.config.company_url.present? && Goodmail.config.company_name.present?
-        company_name_escaped = Regexp.escape(Goodmail.config.company_name)
-        company_url_escaped = Regexp.escape(Goodmail.config.company_url)
-        logo_alt_pattern = /^\s*#{company_name_escaped}\s+Logo\s+\(.*?#{company_url_escaped}.*?\).*\n?/i
-        generated_plain_text.gsub!(logo_alt_pattern, '')
-      end
-      # 2. Remove any remaining standalone URL lines (often from logo links)
-      generated_plain_text.gsub!(/^\s*https?:\/\/\S+\s*$\n?/i, '')
-      # 3. Compact excess blank lines created by gsubbing
-      generated_plain_text.gsub!(/\n{3,}/, "\n\n")
-
-      # Add List-Unsubscribe header to the headers hash *before* calling mail()
-      if unsubscribe_url.is_a?(String) && !unsubscribe_url.strip.empty?
-        headers["List-Unsubscribe"] = "<#{unsubscribe_url.strip}>"
-      end
-
-      # Call the instance-level `mail` method
+      # Attachments must be registered before `mail` materializes the message;
+      # the block form below lets Rails build the multipart/alternative tree.
+      # Sources:
+      # - late attachments raise:
+      #   https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L766-L781
+      # - block-form `mail` with direct plain/html rendering:
+      #   https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L851-L873
       mail(headers) do |format|
-        # Use the premailer-generated plaintext
-        format.text { render plain: generated_plain_text.strip }
-        # Use the CSS-inlined HTML
-        format.html { render html: inlined_html.html_safe }
+        format.text { render plain: text_body.to_s }
+        format.html { render html: html_body.to_s.html_safe }
       end
-      # Action Mailer automatically returns the MessageDelivery object
     end
   end
 end

data/lib/goodmail/plaintext.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+require "premailer"
+require "nokogiri"
+
+module Goodmail
+  # Plain-text generator for the `text/plain` part of every Goodmail
+  # multipart message. Single source of truth shared by
+  # `Goodmail::Email.render` and `Goodmail::Mailer#compose_message` —
+  # before this consolidation, both code paths had a copy of the
+  # same gsub cleanup pipeline and the same Premailer call, which
+  # made it easy for plaintext quality to drift between them.
+  #
+  # Why we DO NOT just hand the raw HTML to Premailer:
+  # ────────────────────────────────────────────────────────────────
+  # The Goodmail layout is built for HTML email clients that
+  # respect display:none, conditional comments, and inline alt
+  # attributes — none of which Premailer's `to_plain_text` honors.
+  # If we feed it the layout HTML directly, the plaintext part has
+  # three artifacts that look like rendering bugs to a recipient
+  # using a text-only client:
+  #
+  #   1. Preheader leak — the layout's hidden inbox-preview
+  #      `<span style="display:none">` is rendered as a phantom
+  #      first line of the message body.
+  #   2. Button text duplication — the `button` DSL helper emits
+  #      both a `<v:roundrect>` (Outlook VML, wrapped in
+  #      `<!--[if mso]>...<![endif]-->`) AND a regular `<a>`.
+  #      Premailer ignores the conditional comment and extracts
+  #      text from BOTH, so the button label appears twice in
+  #      plaintext.
+  #   3. Image alt-text leak — `image` / `inline_image` calls
+  #      with no explicit alt fall back to `config.company_name`.
+  #      That alt is fine in HTML (screen readers read it) but
+  #      shows up as a stray "CompanyName" line in plaintext
+  #      since Premailer extracts alt attributes verbatim.
+  #
+  # We pre-process the HTML to neutralize each of these BEFORE
+  # plaintext extraction, then apply a small post-extraction
+  # cleanup pass for the residual artifacts (logo alt line,
+  # blank-line compaction).
+  #
+  # Sources:
+  #   - Premailer to_plain_text:
+  #     https://github.com/premailer/premailer/blob/master/lib/premailer/premailer.rb
+  #   - MSO conditional comments syntax:
+  #     https://www.litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients
+  module Plaintext
+    extend self
+
+    # Matches the `<!--[if mso]>...<![endif]-->` blocks Outlook reads
+    # exclusively. The `m` flag lets `.*?` span newlines (these blocks
+    # are usually multi-line). The non-greedy quantifier ensures we
+    # don't eat past the first matching `<![endif]-->`.
+    MSO_CONDITIONAL_BLOCK = /<!--\[if mso\]>.*?<!\[endif\]-->/m
+
+    # Generates the plaintext part for a multipart message.
+    #
+    # @param raw_html [String] The full layout-rendered HTML body.
+    # @param preheader [String, nil] The preheader text (the value
+    #   we wrote into the hidden inbox-preview span). Passed in so
+    #   we can strip it specifically from plaintext rather than
+    #   guessing at a generic heuristic.
+    # @return [String] The cleaned plaintext, ready for the text/plain
+    #   part of the outgoing message.
+    def generate(raw_html, preheader: nil)
+      premailer_html = strip_mso_only_markup(raw_html)
+      premailer = Premailer.new(
+        premailer_html,
+        with_html_string: true,
+        adapter: :nokogiri,
+        preserve_styles: false,
+        remove_ids: true,
+        remove_comments: false,
+        # Goodmail outputs UTF-8 end-to-end. Without this, Premailer's
+        # libxml2 backend defaults to Latin-1 when no `<meta charset>`
+        # tag is present in the source, double-encoding every accented
+        # character ("Duración" → "Duración", "€" → "â¬"). The shipped
+        # layout DOES include the meta tag, but custom `layout_path:`
+        # callers might not — pinning here makes us robust to either.
+        input_encoding: "UTF-8"
+      )
+      text = premailer.to_plain_text
+
+      text = strip_preheader_line(text, preheader)
+      text = strip_logo_alt_line(text)
+      text = strip_company_name_alt_line(text)
+      text = compact_blank_lines(text)
+      text.strip
+    end
+
+    private
+
+    # Removes everything Outlook-only from the source HTML before it's
+    # handed to Premailer's plaintext extractor:
+    #
+    #   - The `<!--[if mso]>...<![endif]-->` blocks themselves (Premailer
+    #     doesn't honor conditional comments and would otherwise extract
+    #     text from the VML button INSIDE the block — duplicating every
+    #     button label in plaintext).
+    #   - The hidden preheader span (display:none in HTML, but Premailer
+    #     ignores CSS visibility and would otherwise emit the preheader
+    #     as a phantom first line).
+    def strip_mso_only_markup(html)
+      cleaned = html.gsub(MSO_CONDITIONAL_BLOCK, "")
+      cleaned = strip_hidden_preheader(cleaned)
+      flatten_info_rows(cleaned)
+    end
+
+    # Replaces every `<table class="goodmail-info-row">` (the markup
+    # `Builder#info_row` emits) with a single-line `Label: Value`
+    # paragraph. Two-cell tables otherwise extract as two separate
+    # lines (Premailer renders each `<td>` on its own line) — the
+    # colon-form is the conventional plaintext shape every modern
+    # transactional sender uses for label/value pairs.
+    #
+    # Why we Nokogiri-parse rather than regex-match: tables can be
+    # nested inside other layout chrome (the layout's `.main` table,
+    # the content-wrap cell, the data-row table itself). Trying to
+    # match nested tables with a regex is the canonical case study
+    # for "don't parse HTML with regex".
+    #
+    # We parse as a FULL DOCUMENT, not a fragment. `Nokogiri::HTML.fragment`
+    # would strip the `<head>` wrapper and expose the `<title>` text as
+    # body content — Premailer's plaintext extractor would then leak the
+    # subject as a phantom first line.
+    #
+    # We pin the encoding to UTF-8 explicitly. Without that, Nokogiri's
+    # libxml2 backend falls back to Latin-1 when no `<meta charset>` tag
+    # is present, which mangles every accented character in the layout
+    # ("Duración" → "Duración", "€" → "€"). The shipped layout
+    # DOES declare `<meta http-equiv="Content-Type" content=".../UTF-8">`,
+    # but downstream apps may use a custom `layout_path:` that doesn't,
+    # and the API contract is "Goodmail outputs UTF-8 end-to-end" — so
+    # we don't depend on the meta tag for correctness.
+    # Source: https://nokogiri.org/rdoc/Nokogiri/HTML4.html#method-c-parse
+    def flatten_info_rows(html)
+      doc = Nokogiri::HTML.parse(html, nil, "UTF-8")
+      doc.css("table.goodmail-info-row").each do |table|
+        cells = table.css("td")
+        next if cells.length < 2
+
+        label = cells[0].text.strip
+        value = cells[1].text.strip
+        replacement = Nokogiri::XML::Node.new("p", doc)
+        replacement.content = "#{label}: #{value}"
+        table.replace(replacement)
+      end
+      doc.to_html
+    rescue StandardError => e
+      # If Nokogiri ever chokes (truncated HTML, malformed input from a
+      # custom layout), preserve the original behavior — the table
+      # cells still get emitted as two lines, which is ugly but not
+      # broken. We only log so the failure is visible without crashing
+      # the whole email pipeline.
+      warn "[Goodmail::Plaintext] info-row flatten failed: #{e.class}: #{e.message}"
+      html
+    end
+
+    # The layout emits the preheader inside a `<span>` with a strong
+    # signature: `display:none !important; font-size:1px; color:#ffffff;
+    # line-height:1px; ...`. We use a regex anchored on `display:none`
+    # AND `font-size:1px` to avoid stripping any legit hidden span a
+    # downstream caller might emit via the raw `html` DSL helper.
+    #
+    # The non-greedy `.*?` between the opening tag and `</span>`, plus
+    # the `m` flag, lets the match span the whitespace and the
+    # interpolated preheader text inside the tag.
+    HIDDEN_PREHEADER_SPAN = /
+      <span\s[^>]*
+        style="[^"]*
+          display:\s*none[^"]*
+          font-size:\s*1px[^"]*
+        "[^>]*>
+        .*?
+      <\/span>
+    /xm
+
+    def strip_hidden_preheader(html)
+      html.gsub(HIDDEN_PREHEADER_SPAN, "")
+    end
+
+    # Belt-and-suspenders for the preheader: if the caller passed an
+    # explicit preheader and it happens to land at the top of the
+    # plaintext anyway (e.g. a custom layout that doesn't use the
+    # hidden-span pattern, or a preheader that ALSO appears as visible
+    # body content), strip the leading occurrence so the plaintext
+    # doesn't open with a duplicate.
+    def strip_preheader_line(text, preheader)
+      return text if preheader.to_s.strip.empty?
+
+      escaped = Regexp.escape(preheader.to_s.strip)
+      text.sub(/\A\s*#{escaped}\s*\n+/, "")
+    end
+
+    # Removes the historical "CompanyName Logo (https://company.url/...)"
+    # line generated by the layout's clickable header logo. The opening
+    # `<a href=...><img alt="CompanyName Logo">...</a>` extracts as
+    # `CompanyName Logo ( https://... )` in plaintext.
+    def strip_logo_alt_line(text)
+      return text unless Goodmail.config.logo_url.present? &&
+                         Goodmail.config.company_url.present? &&
+                         Goodmail.config.company_name.present?
+
+      company_name = Regexp.escape(Goodmail.config.company_name)
+      company_url = Regexp.escape(Goodmail.config.company_url)
+      pattern = /^\s*#{company_name}\s+Logo\s*\(.*?#{company_url}.*?\).*\n?/i
+      text.gsub(pattern, "")
+    end
+
+    # Builder's `image` / `inline_image` DSL helpers fall back to
+    # `config.company_name` for the alt attribute when the caller
+    # doesn't pass one. That's reasonable in HTML (screen readers
+    # need SOMETHING). In plaintext, Premailer extracts the alt
+    # verbatim — leaving a stray "CompanyName" line on its own
+    # next to wherever the image landed.
+    #
+    # We strip standalone lines that EXACTLY match the company name.
+    # This is conservative: a message with the company name embedded
+    # in a sentence ("Welcome to ExampleApp, thanks for joining")
+    # is preserved verbatim — only lines that are nothing but the
+    # bare company name are removed.
+    def strip_company_name_alt_line(text)
+      return text unless Goodmail.config.company_name.present?
+
+      company_name = Regexp.escape(Goodmail.config.company_name)
+      text.gsub(/^\s*#{company_name}\s*$\n?/, "")
+    end
+
+    # Compacts runs of 3+ newlines down to exactly 2 (one blank line
+    # between paragraphs is the canonical readable shape; more is
+    # visual noise from cumulative gsubs above).
+    def compact_blank_lines(text)
+      text.gsub(/\n{3,}/, "\n\n")
+    end
+  end
+end