studio-engine 0.40.0 → 0.42.0

data/app/services/studio/banner.rb

@@ -0,0 +1,186 @@
+module Studio
+  # A LAYERED email banner: a background image with the header, sub-text and
+  # logo sitting on top as live HTML, rather than composed into the picture.
+  #
+  # ## Why layered rather than composited
+  #
+  # The alternative is drawing the text into the image server-side. That gives
+  # pixel-exact brand typography in every client, but it cannot do the one thing
+  # this design needs: an ANIMATED background WITH per-recipient text. Composing
+  # "Welcome Mason!" into sixty frames means a multi-megabyte GIF generated per
+  # recipient, per send.
+  #
+  # Layering separates them. The background animates, the greeting is live, and
+  # nothing is generated at send time.
+  #
+  # ## What it costs, stated plainly
+  #
+  # Gmail and Outlook strip webfonts, so the heading falls back to a system face
+  # rather than the brand font. In exchange the text survives blocked images
+  # (which Outlook desktop does by default), stays selectable and translatable,
+  # and no asset is produced per send.
+  #
+  # ## Why the markup looks like 1999
+  #
+  # Outlook on Windows renders through Word, which ignores `background-image` on
+  # nearly everything. The `<td background>` attribute plus a VML `v:rect` /
+  # `v:fill` block — the long-established "bulletproof background" pattern — is
+  # what makes a background image work there at all. The conditional comment is
+  # invisible to every other client.
+  # A plain class, not a Struct-with-block: constants declared inside a
+  # `Struct.new do ... end` attach to the ENCLOSING module, so DEFAULT_SCRIM
+  # would have been Studio::DEFAULT_SCRIM and Banner::DEFAULT_SCRIM would not
+  # exist. Named constants are part of this object's API, so they live on it.
+  class Banner
+    ATTRIBUTES = %i[background_url header subtext logo_url logo_alt scrim width height].freeze
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(**attrs)
+      unknown = attrs.keys - ATTRIBUTES
+      raise ArgumentError, "unknown banner attribute: #{unknown.join(", ")}" if unknown.any?
+
+      ATTRIBUTES.each { |name| instance_variable_set(:"@#{name}", attrs[name]) }
+    end
+
+    # The email card is 600px wide; the banner fills it.
+    DEFAULT_WIDTH  = 600
+    DEFAULT_HEIGHT = 200
+
+    # A wash between the artwork and the text. Not decoration: background art is
+    # chosen for looks, not contrast, and white text over a pale sky is
+    # unreadable. 0 disables it for artwork already dark enough to carry type.
+    #
+    # Raised from 0.34 after seeing it in a real inbox — bright artwork left the
+    # sub-text working harder than it should. Rendered at 0.34 / 0.45 / 0.55 and
+    # chosen by eye, because "legible" is a judgement about a picture, not a
+    # number a test can settle.
+    DEFAULT_SCRIM = 0.40
+
+    def width  = (@width  || DEFAULT_WIDTH).to_i
+    def height = (@height || DEFAULT_HEIGHT).to_i
+
+    # The scrim as a SOLID hex, for Outlook.
+    #
+    # Word's rendering engine ignores rgba(), so the wash simply does not exist
+    # there — white text over bare artwork, which is the exact contrast case the
+    # scrim was added to solve, in the one client nobody can spot-check. VML
+    # cannot layer a translucent fill over an image fill either, so the honest
+    # approximation is a solid colour: the scrim tint blended toward the artwork's
+    # own darkness by the same fraction. It is not the same picture as everywhere
+    # else, and it is legible, which is the point.
+    SCRIM_RGB = [24, 16, 64].freeze
+
+    def scrim_solid_hex
+      fraction = scrim_opacity
+      # Blend the tint toward mid-grey rather than to black: at low opacities a
+      # blend toward black reads far darker in Outlook than the rgba() wash does
+      # elsewhere, which trades one wrong picture for another.
+      blended = SCRIM_RGB.map { |channel| ((channel * fraction) + (128 * (1 - fraction))).round.clamp(0, 255) }
+      format("#%02X%02X%02X", *blended)
+    end
+
+    def scrim_opacity
+      value = @scrim
+      return DEFAULT_SCRIM if value.nil?
+
+      value.to_f.clamp(0.0, 1.0)
+    end
+
+    # A banner with nothing to show is not a banner. The layout falls back to
+    # the plain <img> path (or to no banner at all).
+    def renderable? = background_url.present? || header.present?
+
+    # Everything the layout needs for one email, or nil.
+    #
+    # Reads the catalogue for the artwork so an app inherits the shared
+    # background and logo without repeating them, and lets a caller override any
+    # piece per send — which is the whole point of the header being dynamic.
+    # `name` is the DYNAMIC part and the only thing a mailer should normally
+    # pass. A mailer that hands over a finished header instead takes the wording
+    # away from the operator: the /admin/emails field would still accept an edit
+    # and the email would still ignore it — a control that lies about what it
+    # does. So the mailer supplies who the person is, and the operator supplies
+    # what the banner says about them.
+    def self.for(key, name: nil, header: nil, subtext: nil, background_url: nil,
+                 logo_url: nil, scrim: nil, logo_alt: nil)
+      banner = new(
+        background_url: background_url || Studio::EmailCatalog.background_url(key),
+        logo_url:       logo_url       || safe_image_url(Studio::EmailCatalog.resolved_logo_url(key)),
+        logo_alt:       logo_alt       || Studio.app_name,
+        header:         header         || header_for(key, name),
+        subtext:        subtext        || Studio::EmailCatalog.subtext(key),
+        # Resolution order: an explicit argument (a caller who knows better),
+        # then what the OPERATOR saved on /admin/emails, then the registry, then
+        # the default. The operator sits above the registry on purpose — they
+        # are the one looking at the artwork.
+        scrim:          scrim || Studio::EmailCatalog.scrim(key)
+      )
+      # A LAYERED banner needs its picture, and renderable? deliberately accepts
+      # a header alone — right for a caller building a Banner directly, wrong
+      # here. A nil background means the catalogue said this app sends the email
+      # flat, and a text-only card is not what that inbox gets.
+      banner.background_url.present? ? banner : nil
+    end
+
+    # The placeholder an operator types into the header field. Braces rather
+    # than Ruby's %{name}: an operator-editable string is passed to no formatter
+    # here, and a stray "%" in "50% off" would raise inside format() where a
+    # stray brace is simply left alone.
+    # An operator types the logo URL into an admin form, and it is rendered into
+    # an <img src>. Admin-only and low risk, but "javascript:" and "data:" in a
+    # src are cheap to refuse and there is no reason to carry them: a logo is
+    # fetched over http(s) or served from this app's own asset path.
+    def self.safe_image_url(url)
+      value = url.to_s.strip
+      return nil if value.empty?
+      return value if value.start_with?("/")
+
+      value.match?(%r{\Ahttps?://}i) ? value : nil
+    end
+
+    NAME_PLACEHOLDER = "{name}".freeze
+
+    # The app's own name. Present because the DEFAULTS need it: "Your sign-in
+    # link" reads as though it could be from anyone, and a registry constant
+    # cannot interpolate Studio.app_name at load time. An operator gets it for
+    # free in any field.
+    APP_PLACEHOLDER = "{app}".freeze
+
+    # FIRST name only. The banner is one line of large type in a 600px box, and
+    # "Welcome Bartholomew Fitzgerald-Montgomery!" wraps out of it.
+    # Shared with the SUBJECT, which takes the same placeholder. One
+    # implementation, so "{name}" cannot mean two things on one email.
+    def self.interpolate(template, name)
+      text = template.to_s.gsub(APP_PLACEHOLDER, Studio.app_name.to_s)
+      first = name.to_s.strip.split.first
+      return text.gsub(NAME_PLACEHOLDER, first) if first.present?
+
+      # NO NAME, AND NO RAW PLACEHOLDER EITHER. The header carries a whole second
+      # field for this case; a subject line does not, and "Sign in to Studio,
+      # {name}" reaching an inbox is the most visible way this feature fails. The
+      # token goes, and the punctuation it hung off goes with it — the result is
+      # "Sign in to Studio", not "Sign in to Studio, ".
+      # Two passes, because the punctuation can sit on either side: "Sign in,
+      # {name}" and "{name}, your link is here" both have to come out clean, and
+      # "Hi {name} welcome" must not become "Hiwelcome".
+      text.gsub(/[,;:\u2014-]?\s*#{Regexp.escape(NAME_PLACEHOLDER)}/, "")
+          .sub(/\A\s*[,;:\u2014-]\s*/, "")
+          .squeeze(" ").strip
+    end
+
+    def self.header_for(key, name)
+      template = Studio::EmailCatalog.header_template(key).to_s
+      first = name.to_s.strip.split.first
+
+      return interpolate(template, name) if first.present?
+      # No name: a template that asks for one cannot be rendered honestly, so
+      # the fallback answers instead. A template with no name placeholder is
+      # already name-free and stands as written — still interpolated, because
+      # {app} does not depend on the recipient.
+      fallback = Studio::EmailCatalog.header_fallback(key) if template.include?(NAME_PLACEHOLDER)
+
+      interpolate(fallback || template, nil)
+    end
+  end
+
+end

data/app/services/studio/email_catalog.rb

@@ -61,6 +61,12 @@ module Studio
   module EmailCatalog
     PURPOSE = "email_banner".freeze
 
+    # The LOGO is a separate purpose, not a variant of the banner. They are
+    # different pictures with different rules: a banner is 3:1 artwork that may be
+    # an animated GIF, a logo is a small transparent mark. Sharing one purpose
+    # would make "revert the banner" and "revert the logo" the same row.
+    LOGO_PURPOSE = "email_logo".freeze
+
     # What an email is FOR. Transactional = sent in response to something the
     # recipient did; marketing = sent because we decided to. Kept because
     # turf-monster's catalog carried it and the distinction drives real policy
@@ -74,7 +80,9 @@ module Studio
     #   type          — :transactional or :marketing.
     #   preview       — callable returning a Mail, or nil.
     Entry = Struct.new(:key, :label, :description, :default_asset, :type, :preview,
-                       :default_origin, :aspect_ratio, keyword_init: true) do
+                       :default_origin, :aspect_ratio, :background, :logo, :scrim,
+                       :header, :header_fallback, :subtext, :subject,
+                       keyword_init: true) do
       def to_s = key
       def previewable? = preview.respond_to?(:call)
       # nil-safe: an Entry built directly (the STANDARD seed) may carry no type.
@@ -103,20 +111,50 @@ module Studio
         label: "Magic-link sign-in",
         description: "Passwordless sign-in link. Sent whenever someone asks to sign in by email.",
         default_asset: "emails/magic-link.gif",
-        aspect_ratio: 3.0
+        aspect_ratio: 3.0,
+        # Layered artwork: the background animates, the greeting is live HTML on
+        # top. default_asset above stays the flat <img> for a mailer that has not
+        # adopted the layered banner.
+        background: "emails/magic-link-background.gif",
+        logo: "emails/logo-horizontal.png",
+        # The DEFAULT wording, overridable per app on /admin/emails. {name} is
+        # filled from whoever the mailer says the recipient is.
+        header: "Welcome {name}!",
+        header_fallback: "Your Magic Link",
+        subtext: "your sign-in link is below",
+        subject: "Your {app} sign-in link"
       },
       {
-        key: "email_change_confirmation",
-        label: "Email change confirmation",
-        description: "Confirms a new address before the change takes effect.",
-        default_asset: "emails/email-change-confirmation.gif",
-        aspect_ratio: 3.0
+        key: "newsletter_subscribed",
+        label: "Newsletter subscribed",
+        description: "Welcomes someone who has just joined the mailing list.",
+        aspect_ratio: 3.0,
+        # LAYERED-NATIVE: no default_asset. A flat asset is the pre-layered
+        # fallback — artwork with the words baked in, for a mailer that only
+        # knows how to render an <img>. Studio::NewsletterMailer has known how to
+        # layer since the day it was written, so a baked-in copy of the same
+        # picture would be a second thing to keep in sync and never be shown.
+        background: "emails/newsletter-subscribed-background.gif",
+        logo: "emails/logo-horizontal.png",
+        header: "Welcome {name}!",
+        header_fallback: "You're subscribed!",
+        subtext: "you're on the list",
+        subject: "You're subscribed to {app}",
+        # The engine ships this email's preview because it can: the mailer takes
+        # a bare address, so no host sample data is involved. Every other entry's
+        # builder needs records only the host has — this one does not, and an
+        # inherited email with no preview is a row on every app's manager that
+        # cannot be looked at.
+        preview: -> { Studio::NewsletterMailer.subscribed("preview@example.com", name: "Alex") }
       }
     ].freeze
 
-    # Banners render full-bleed at 600px in a 600px card. 1200x600 is the
-    # right cut: 2:1, retina-sharp at render width, and small enough to stay
-    # out of an inbox clipping limit.
+    # The FALLBACK shape, for an email that states none. 2:1 because that is what
+    # turf-monster's eight banners are, and changing it would recrop all of them.
+    #
+    # It is NOT what the engine's own emails use: both STANDARD entries declare
+    # aspect_ratio: 3.0 and both shipped backgrounds are 1200x400. The ratio is
+    # per-entry precisely so those two answers can differ.
     ASPECT_RATIO = 2.0
     MAX_WIDTH = 1200
 
@@ -130,7 +168,8 @@ module Studio
     # existing value — that is what lets a host relabel an inherited email, or
     # attach a preview builder to it, without restating its artwork.
     def register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: nil,
-                 aspect_ratio: nil)
+                 aspect_ratio: nil, background: nil, logo: nil, scrim: nil,
+                 header: nil, header_fallback: nil, subtext: nil, subject: nil)
       key = key.to_s
       existing = registry[key]
       registry[key] = Entry.new(
@@ -145,7 +184,14 @@ module Studio
         # had, so a host relabelling an inherited email does not accidentally
         # claim the engine's picture as its own.
         default_origin: default_asset.nil? ? (existing&.default_origin || :engine) : :app,
-        aspect_ratio: aspect_ratio || existing&.aspect_ratio
+        aspect_ratio: aspect_ratio || existing&.aspect_ratio,
+        background: background.nil? ? existing&.background : background.presence,
+        logo: logo.nil? ? existing&.logo : logo.presence,
+        scrim: scrim.nil? ? existing&.scrim : scrim,
+        header: header.nil? ? existing&.header : header.presence,
+        header_fallback: header_fallback.nil? ? existing&.header_fallback : header_fallback.presence,
+        subtext: subtext.nil? ? existing&.subtext : subtext.presence,
+        subject: subject.nil? ? existing&.subject : subject.presence
       )
       key
     end
@@ -202,7 +248,9 @@ module Studio
       @registry ||= STANDARD.each_with_object({}) do |attrs, out|
         out[attrs[:key]] = Entry.new(**attrs, type: normalize_type(attrs[:type]),
                                      preview: attrs[:preview], default_origin: :engine,
-                                     aspect_ratio: attrs[:aspect_ratio])
+                                     aspect_ratio: attrs[:aspect_ratio],
+                                     background: attrs[:background], logo: attrs[:logo],
+                                     scrim: attrs[:scrim])
       end
     end
 
@@ -239,6 +287,110 @@ module Studio
     # This email's banner shape, falling back to the shared default.
     def ratio(key) = entry(key)&.ratio || ASPECT_RATIO
 
+    # --- layered banner artwork ---------------------------------------------
+    #
+    # Absolute URLs, because a mail client fetches these from an inbox and a
+    # root-relative path resolves against nothing there.
+
+    # Saved by the operator > registered by the app > engine default.
+    def scrim(key)
+      Studio::EmailSetting.scrim_for(key) || entry(key)&.scrim
+    rescue StandardError
+      entry(key)&.scrim
+    end
+
+    # --- the banner's words -------------------------------------------------
+    #
+    # Same order as the tint, for the same reason: the operator is the one
+    # looking at the artwork. Each falls back to the registry, then to a
+    # sensible default, so an email that nobody has configured still reads.
+
+    # The header TEMPLATE — it may contain {name}. Interpolation happens in
+    # Studio::Banner, which is the only place that knows the recipient.
+    def header_template(key)
+      saved(key, :header) || entry(key)&.header || entry(key)&.label
+    end
+
+    # What the header says when no name is known. A magic link is often the
+    # first contact we have with someone, so "Welcome {name}!" must have
+    # somewhere to land that is not "Welcome !".
+    def header_fallback(key)
+      saved(key, :header_fallback) || entry(key)&.header_fallback || entry(key)&.label
+    end
+
+    def subtext(key)
+      saved(key, :subtext) || entry(key)&.subtext
+    end
+
+    # The subject line, resolved the same way and supporting the same {name}
+    # placeholder. A mailer calls this instead of hard-coding a string, which is
+    # what makes the field on /admin/emails real rather than decorative.
+    def subject_for(key, name: nil)
+      template = saved(key, :subject) || entry(key)&.subject
+      return nil if template.blank?
+
+      Studio::Banner.interpolate(template, name).presence
+    end
+
+    # nil when the operator has hidden the logo — distinct from "none saved",
+    # which inherits the registry's.
+    # Hidden > uploaded here > a URL the operator typed > the registry's.
+    # "Hidden" comes first because it is the one answer the others cannot express.
+    def resolved_logo_url(key)
+      return nil if Studio::EmailSetting.hide_logo?(key)
+
+      uploaded_logo_url(key) || saved(key, :logo_url) || logo_url(key)
+    rescue StandardError
+      logo_url(key)
+    end
+
+    # An operator-saved field, or nil. Rescues because these are read on a
+    # delivery path: a settings table that is missing, locked, or mid-migration
+    # must degrade to the registry default rather than fail the send.
+    def saved(key, field)
+      Studio::EmailSetting.copy_for(key, field)
+    rescue StandardError
+      nil
+    end
+
+    def scrim_percent(key)
+      value = scrim(key) || Studio::Banner::DEFAULT_SCRIM
+      (value.to_f * 100).round
+    end
+
+    # THE APP'S OWN UPLOAD WINS, then the registered artwork. Same two layers as
+    # resolved_url, and for the same reason: uploading on /admin/emails is how an
+    # operator says "this picture is ours now".
+    #
+    # Reading only the registry made the Upload button a control that lies on a
+    # LAYERED email — the upload landed, the page showed it, the provenance badge
+    # flipped to "Uploaded here", and the email kept sending the gem's artwork
+    # because the layered banner never looked at the row.
+    #
+    # NIL WHEN THIS APP OWNS THE ARTWORK. A host registering its own flat
+    # default_asset sends that picture; the background it also inherited is the
+    # engine's and nothing sends it. The list row carried this guard alone, so
+    # the detail page still layered live text over artwork no inbox receives.
+    def background_url(key)
+      return nil unless entry(key)&.engine_artwork?
+
+      url(key) || absolute_asset_url(entry(key)&.background)
+    end
+    def logo_url(key)       = absolute_asset_url(entry(key)&.logo)
+
+    def absolute_asset_url(asset)
+      return nil if asset.blank?
+
+      path = ActionController::Base.helpers.asset_path(asset)
+      return nil if path.blank?
+      return path if path.start_with?("http")
+
+      host = mailer_asset_host
+      host ? "#{host}#{path}" : path
+    rescue StandardError
+      nil
+    end
+
     def app_owned?(key) = source(key) == :app
 
     # --- Preview -----------------------------------------------------------
@@ -348,7 +500,31 @@ module Studio
     # whatever host and port this app is being viewed on (an absolute mailer
     # asset_host is set for the inbox, not for a browser on localhost:3042).
     def preview_url(key)
-      url(key) || default_asset_path(key)
+      url(key) || preview_asset_path(key)
+    end
+
+    # What the manager DRAWS, which is a different question from what the flat
+    # <img> fallback sends — so it resolves in the opposite order.
+    #
+    # LAYERED FIRST. magic_link ships both: `emails/magic-link.gif`, the old
+    # banner with "Your Magic Link" baked into the picture, and
+    # `emails/magic-link-background.gif`, the artwork the layered banner draws
+    # live text on top of. A mailer that has adopted layering sends the SECOND
+    # one — so previewing the first showed the operator a picture no inbox
+    # receives, and did it convincingly, because baked-in words look like a real
+    # banner. Same failure as the "No image" badge, one door further along: the
+    # page answering from the field it happened to read instead of from what
+    # ships.
+    #
+    # The flat asset stays the fallback, for a host still on the engine's own
+    # unlayered UserMailer — there, the baked-text banner IS what arrives.
+    #
+    # Unless THIS APP owns the artwork, in which case it previews exactly what
+    # the flat resolution sends — same method, so the two cannot disagree.
+    def preview_asset_path(key)
+      return default_asset_path(key) unless entry(key)&.engine_artwork?
+
+      asset_path(entry(key)&.background.presence || entry(key)&.default_asset)
     end
 
     # The ImageCache row holding this app's override, or nil (nothing uploaded /
@@ -359,14 +535,60 @@ module Studio
       ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: key.to_s)
     end
 
-    # Root-relative path to the inherited default asset, or nil when the email
-    # has no default registered or the host's pipeline cannot resolve it.
+    def logo_record(key)
+      return nil unless table_ready?
+
+      ::ImageCache.find_by(owner: nil, purpose: LOGO_PURPOSE, variant: key.to_s)
+    end
+
+    # An uploaded logo for this email, or nil to inherit.
+    def uploaded_logo_url(key)
+      logo_record(key)&.url
+    rescue StandardError
+      nil
+    end
+
+    def store_logo(key, io:, content_type: nil)
+      s3_key = "email_logos/#{key}-#{SecureRandom.hex(4)}#{ext_for(content_type)}"
+      Studio::S3.upload(key: s3_key, body: io.read, content_type: content_type,
+                        cache_control: "public, max-age=300")
+      record = ::ImageCache.find_or_initialize_by(owner: nil, purpose: LOGO_PURPOSE, variant: key.to_s)
+      previous = record.s3_key
+      record.update!(s3_key: s3_key)
+      delete_object(previous) if previous.present? && previous != s3_key
+      record
+    rescue StandardError
+      delete_object(s3_key)
+      raise
+    end
+
+    def revert_logo(key)
+      row = logo_record(key)
+      return false if row.nil?
+
+      previous = row.s3_key
+      row.destroy!
+      delete_object(previous) if previous.present?
+      true
+    end
+
+    # Root-relative path to the FLAT artwork — what the <img> fallback sends.
+    # Flat first, then the layered background as a last resort so a
+    # layered-native email (newsletter_subscribed registers no flat asset,
+    # because it never renders one) still has something rather than nothing.
+    # See preview_asset_path above for why the manager resolves the other way.
     def default_asset_path(key)
-      asset = entry(key)&.default_asset
+      asset_path(entry(key)&.default_asset.presence || entry(key)&.background)
+    end
+
+    # Shared tail of both resolutions: a logical asset name to a root-relative
+    # path, or nil when there is no asset or the host's pipeline cannot resolve
+    # it. Rescues broadly because a missing asset must degrade to "no image",
+    # never take the manager down.
+    def asset_path(asset)
       return nil if asset.nil? || asset.empty?
 
-      path = ActionController::Base.helpers.asset_path(asset)
-      path.presence
+      ActionController::Base.helpers.asset_path(asset).presence
     rescue StandardError
       nil
     end
@@ -477,11 +699,18 @@ module Studio
 
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 0.0.0.0 ::1].freeze
 
+    # GIF is listed because animated banners are uploaded whole — they bypass the
+    # cropper, which would flatten them to a single PNG frame. Without this branch
+    # a GIF was stored under a ".png" key: the object's Content-Type was still
+    # image/gif so it played, but the URL said otherwise, and anything that trusts
+    # an extension (a CDN, a proxy, a person reading the bucket) was told the
+    # wrong thing.
     def ext_for(content_type)
       case content_type.to_s
       when %r{png}    then ".png"
       when %r{jpe?g}  then ".jpg"
       when %r{webp}   then ".webp"
+      when %r{gif}    then ".gif"
       else ".png"
       end
     end