studio-engine 0.36.0 → 0.38.0

data/app/services/studio/email_image.rb

@@ -1,85 +1,68 @@
 module Studio
-  # Admin-managed banner images for transactional emails. One image per "variant"
-  # (the email type), uploaded to S3 with a stable PUBLIC url via Studio::S3 and
-  # tracked by an owner-less ImageCache row (purpose "email_banner"). The branded
-  # mailer resolves the current banner with .url; the admin email-image page
-  # writes it with .store.
+  # DEPRECATED NAME — this is Studio::EmailCatalog now. Every method here just
+  # forwards; there is no behavior in this file.
   #
-  # VARIANTS is the registry — magic_link now; adding an entry is all it takes to
-  # admin-manage another email's header image (the "extensible" part of the
-  # magic-link-now-extensible scope).
+  # The METHOD surface is kept complete, for two reasons:
+  #
+  #   1. Engine 0.33 shipped this module as the registry's public name, so any
+  #      app already on 0.33 is calling it.
+  #   2. consumer-ci.yml runs each consumer's DEFAULT BRANCH suite against an
+  #      engine PR, and mcritchie-studio's test/integration/studio_email_image_test.rb
+  #      on `main` calls .url, .store and .record directly. Dropping any of them
+  #      reddens that lane from the moment the PR opens, and nothing inside the
+  #      engine PR can reach the consumer's main to fix it.
+  #
+  # ONE thing did not survive: the `VARIANTS` CONSTANT. It was a frozen literal
+  # hash, and the registry it stood for is now built at runtime, so a constant
+  # cannot express it. The `variants` METHOD returns the same key => label shape
+  # and is the supported replacement. Checked before dropping it: no consumer's
+  # `main` names the constant — only .url, .store and .record — so consumer CI
+  # stays green. A host that did reference it gets a NameError, not a silent
+  # wrong answer.
+  #
+  # Delete it once no consumer's main names it — the same staged retirement
+  # /admin/email_images is on.
+  #
+  # Deliberately explicit rather than method_missing: a typo should still raise
+  # NoMethodError here, and the delegated surface should be readable as a list.
   module EmailImage
-    PURPOSE = "email_banner".freeze
-
-    # variant => human label, in admin display order.
-    VARIANTS = {
-      "magic_link" => "Magic-link sign-in"
-    }.freeze
+    PURPOSE = EmailCatalog::PURPOSE
+    ASPECT_RATIO = EmailCatalog::ASPECT_RATIO
+    MAX_WIDTH = EmailCatalog::MAX_WIDTH
 
     module_function
 
-    def variants
-      VARIANTS
-    end
-
-    def label(variant)
-      VARIANTS[variant.to_s] || variant.to_s.humanize
-    end
-
-    def known?(variant)
-      VARIANTS.key?(variant.to_s)
-    end
-
-    # The ImageCache row for this variant, or nil (no banner uploaded / table not
-    # installed yet). Nil-safe so the mailer renders bannerless before any upload.
-    def record(variant)
-      return nil unless table_ready?
-
-      ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: variant.to_s)
-    end
-
-    # Permanent public S3 url for the current banner, or nil.
-    def url(variant)
-      record(variant)&.url
-    end
-
-    # Upload bytes to S3 + upsert the ImageCache row (replacing any prior object).
-    # Returns the ::ImageCache. Raises on failure after cleaning up the new object.
-    def store(variant, io:, content_type: nil)
-      key = "email_banners/#{variant}-#{SecureRandom.hex(4)}#{ext_for(content_type)}"
-      Studio::S3.upload(key: key, body: io.read, content_type: content_type,
-                        cache_control: "public, max-age=300")
-      record = ::ImageCache.find_or_initialize_by(owner: nil, purpose: PURPOSE, variant: variant.to_s)
-      previous = record.s3_key
-      record.update!(s3_key: key)
-      delete_object(previous) if previous.present? && previous != key
-      record
-    rescue StandardError
-      delete_object(key)
-      raise
-    end
+    # Registry
+    def register(...)   = EmailCatalog.register(...)
+    def entries         = EmailCatalog.entries
+    def entry(key)      = EmailCatalog.entry(key)
+    def keys            = EmailCatalog.keys
+    def known?(key)     = EmailCatalog.known?(key)
+    def registered?(key) = EmailCatalog.registered?(key)
+    def label(key)      = EmailCatalog.label(key)
+    def variants        = EmailCatalog.variants
+    def reset!          = EmailCatalog.reset!
 
-    # Reference ImageCache directly so Zeitwerk autoloads it — defined?() does NOT
-    # trigger autoload, so it would read "undefined" for a not-yet-loaded const.
-    def table_ready?
-      ::ImageCache.table_exists?
-    rescue NameError, ActiveRecord::ActiveRecordError
-      false
-    end
+    # Image resolution. `url` is the pre-registry contract — this app's own
+    # image or nil — and must stay that way; see the note on EmailCatalog#url.
+    def url(key)          = EmailCatalog.url(key)
+    def resolved_url(key) = EmailCatalog.resolved_url(key)
+    def preview_url(key)  = EmailCatalog.preview_url(key)
+    def source(key)       = EmailCatalog.source(key)
+    def app_owned?(key)   = EmailCatalog.app_owned?(key)
+    def record(key)       = EmailCatalog.record(key)
+    def default_url(key)  = EmailCatalog.default_url(key)
+    def default_asset_path(key) = EmailCatalog.default_asset_path(key)
 
-    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"
-      else ".png"
-      end
-    end
+    # Writes
+    def store(key, io:, content_type: nil) = EmailCatalog.store(key, io: io, content_type: content_type)
+    def revert(key)        = EmailCatalog.revert(key)
+    def uploads_available? = EmailCatalog.uploads_available?
+    def table_ready?       = EmailCatalog.table_ready?
 
-    def delete_object(key)
-      Studio::S3.delete(key: key)
-    rescue StandardError
-      nil
-    end
+    # Origin resolution. Delegated because 0.34's suite asserted these directly.
+    def mailer_asset_host = EmailCatalog.mailer_asset_host
+    def mailer_protocol(options, host) = EmailCatalog.mailer_protocol(options, host)
+    def mailer_port_suffix(options)    = EmailCatalog.mailer_port_suffix(options)
   end
 end

data/app/views/layouts/branded_mailer.html.erb

@@ -1,6 +1,6 @@
 <%#
   Shared branded transactional email shell. A full-bleed banner (set @banner_url,
-  e.g. from Studio::EmailImage.url(:magic_link)) sits flush at the top and sets
+  e.g. from Studio::EmailCatalog.resolved_url(:magic_link)) sits flush at the top and sets
   the 600px width; each email view supplies the body via yield. Bannerless is
   fine — the card still renders. Lifted from turf-monster so every Studio app
   shares one branded look. An app can override by defining its own

data/app/views/studio/email_images/index.html.erb

@@ -1,3 +1,6 @@
+<%# DEPRECATED page — superseded by /admin/emails (studio/emails/index).
+    Kept for one release so consumer suites on their default branch keep passing;
+    see Studio::EmailImagesController for the full staging note. %>
 <% content_for(:title) { "Email images" } %>
 <div class="max-w-2xl mx-auto px-4 py-8">
   <header class="mb-6">
@@ -8,6 +11,20 @@
     </p>
   </header>
 
+  <%# Only when this app actually DREW /admin/emails — it is opt-in, and pointing
+      at a route that does not exist raises NameError and 500s this page. %>
+  <% if successor_path %>
+    <div class="mb-6 rounded-xl border border-subtle bg-inset px-4 py-3">
+      <p class="text-sm font-semibold text-heading">There's a better page now</p>
+      <p class="text-sm text-body mt-1">
+        <%= link_to "Emails", successor_path, class: "underline underline-offset-2" %>
+        lists every email this app sends with its live banner, says whether that
+        banner is the shared default or this app's own, and crops on upload.
+        This page is going away.
+      </p>
+    </div>
+  <% end %>
+
   <% flash.each do |type, message| %>
     <div class="mb-4 rounded-lg px-4 py-3 text-sm <%= type.to_s == "alert" ? "bg-danger/10 text-danger" : "bg-success/10 text-success" %>">
       <%= message %>
@@ -16,7 +33,12 @@
 
   <div class="space-y-6">
     <% @variants.each do |variant, label| %>
-      <% current_url = Studio::EmailImage.url(variant) %>
+      <%# preview_url, not url: this page's ORIGINAL BUG was reading only the S3
+          override, so it announced "No image yet" for an email that was visibly
+          sending a banner from a committed repo asset. Even on its way out it
+          should tell the truth about what ships. %>
+      <% current_url = Studio::EmailCatalog.preview_url(variant) %>
+      <% inherited = current_url.present? && Studio::EmailCatalog.source(variant) == :default %>
       <section class="rounded-xl border border-subtle p-5">
         <h2 class="font-semibold mb-3"><%= label %></h2>
 
@@ -30,6 +52,13 @@
           <% end %>
         </div>
 
+        <% if inherited %>
+          <p class="text-xs text-muted mb-3">
+            This is the shared default that ships with the engine. Uploading here
+            makes the image this app's own.
+          </p>
+        <% end %>
+
         <%= form_with url: admin_email_image_path(variant), method: :patch, html: { multipart: true }, class: "flex flex-wrap items-center gap-3" do %>
           <%= file_field_tag :image, accept: "image/png,image/jpeg,image/webp",
                 class: "text-sm file:mr-3 file:rounded-md file:border-0 file:bg-primary file:px-3 file:py-1.5 file:text-white file:cursor-pointer" %>

data/app/views/studio/emails/_row.html.erb

@@ -0,0 +1,107 @@
+<%# locals: (entry:, uploads_available:, aspect:, max_width:)
+    One registered email: its live banner, its name, and where that banner comes
+    from. The whole row is the imageUploadHost x-data so the thumbnail, the Edit
+    button, and the hidden multipart form the cropper submits all sit together —
+    the same unit turf-monster's og:image uploader uses, on the page-scoped
+    `emailModals` store. %>
+<%
+  source     = Studio::EmailCatalog.source(entry.key)
+  banner_url = Studio::EmailCatalog.preview_url(entry.key)
+  form_id    = "email-banner-form-#{entry.key.dasherize}"
+
+  # `badge` is a shape-only utility in engine.css — the state color comes from
+  # theme-token utilities so it follows each app's palette in light and dark.
+  badge_class, badge_label, badge_note =
+    case source
+    when :app
+      ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s own",
+       "Uploaded here — this app owns it."]
+    when :default
+      ["badge bg-inset text-muted border-subtle", "Inherited default",
+       "Shared Studio artwork, shipped with the engine."]
+    else
+      ["badge bg-warning/10 text-warning border-warning/30", "No image",
+       "This email sends without a banner."]
+    end
+%>
+<%# The uploader host is attached ONLY when this app can actually store an
+    override. On a read-only app the cropper assets are not loaded either, so an
+    unconditional x-data would reference an undefined factory and Alpine would
+    throw on every row. %>
+<tr class="border-b border-subtle last:border-0"
+    <% if uploads_available %>
+      x-data="imageUploadHost({
+        store: 'emailModals',
+        aspectRatio: <%= aspect %>,
+        maxWidth: <%= max_width %>,
+        transparent: false,
+        filename: '<%= entry.key %>.png',
+        saving: 'Saving banner…',
+        success: 'Banner updated',
+        successMessage: '<%= j entry.label %> now uses this app\'s own image.',
+        failure: 'Couldn\'t save the banner'
+      })"
+      @crop-photo-confirmed.window="onCropConfirmed($event.detail)"
+    <% end %>>
+
+  <td class="px-4 py-4">
+    <div class="rounded-lg overflow-hidden border border-subtle w-40"
+         style="aspect-ratio: <%= aspect %>; background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));">
+      <% if banner_url %>
+        <%= image_tag banner_url, class: "w-full h-full object-cover",
+              alt: "#{entry.label} email banner", loading: "lazy" %>
+      <% else %>
+        <div class="w-full h-full flex items-center justify-center text-2xs text-white/80 text-center px-3">
+          No banner
+        </div>
+      <% end %>
+    </div>
+  </td>
+
+  <td class="px-4 py-4">
+    <%# The name is the link to the email's own page — banner + live preview. %>
+    <%= link_to entry.label, admin_email_path(entry.key),
+          class: "font-semibold text-heading hover:text-primary underline-offset-2 hover:underline" %>
+    <% if entry.marketing? %>
+      <span class="badge bg-primary/10 text-primary border-primary/30 ml-1.5 whitespace-nowrap">Marketing</span>
+    <% end %>
+    <% if entry.description.present? %>
+      <p class="text-sm text-body mt-0.5 max-w-md"><%= entry.description %></p>
+    <% end %>
+    <p class="font-mono text-2xs text-muted mt-1"><%= entry.key %></p>
+  </td>
+
+  <%# whitespace-nowrap keeps the pill a pill — "<App>'s own" is long enough to
+      wrap inside a bordered badge, which reads as a broken box next to the
+      short "Inherited default". %>
+  <td class="px-4 py-4">
+    <span class="<%= badge_class %> whitespace-nowrap"><%= badge_label %></span>
+    <p class="text-2xs text-muted mt-1.5 max-w-[12rem]"><%= badge_note %></p>
+  </td>
+
+  <% if uploads_available %>
+    <td class="px-4 py-4 text-right whitespace-nowrap">
+      <button type="button" @click="open()" class="btn btn-outline btn-sm inline-flex items-center gap-1.5">
+        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"/>
+        </svg>
+        <%= source == :app ? "Replace" : "Upload" %>
+      </button>
+
+      <%# Only an APP-OWNED image can be reverted — there is nothing to drop when
+          the row is already showing the inherited default. %>
+      <% if source == :app %>
+        <%= button_to "Revert", admin_email_path(entry.key), method: :delete,
+              class: "btn btn-neutral btn-sm mt-1.5 w-full",
+              form: { data: { turbo_confirm: "Drop #{Studio.app_name}'s own #{entry.label} banner and go back to the shared default?" } } %>
+      <% end %>
+
+      <%# The cropper drops its Blob into this hidden input and submits. %>
+      <%= form_with url: admin_email_path(entry.key), method: :patch,
+            html: { multipart: true, id: form_id, "x-ref": "form" } do %>
+        <%= file_field_tag :image, class: "hidden", "x-ref": "fileInput" %>
+      <% end %>
+    </td>
+  <% end %>
+</tr>

data/app/views/studio/emails/index.html.erb

@@ -0,0 +1,116 @@
+<%#  admin/emails — the standard transactional-email page.
+
+     A bare content wrapper (no `layout` call), like the living style guide at
+     /admin/style: it renders inside each host's application.html.erb and
+     inherits that app's navbar and theme, so one shared engine page looks
+     native in every app.
+
+     The table is the primary view — one row per registered email, each carrying
+     the NAME and the LIVE IMAGE so an email is identifiable at a glance, plus
+     whether that image is the INHERITED engine default or an APP-OWNED
+     override. Editing goes through the shared crop modal (studio/cropper_assets
+     + the page-scoped host at the bottom), never a bare file input.
+
+     Page-scoped modal host: the crop + saving modals mount on `emailModals`
+     rather than the app's shared `modals` store, so this page works identically
+     in an app that renders a shared modal host (mcritchie-studio, turf-monster)
+     and one that renders none at all (mcritchie-industries, moms-app). It uses
+     studio/modals/scoped_host, NOT studio/modals/host — the latter is forked by
+     mcritchie-studio and turf-monster, and an app fork shadows the engine's
+     partial in this non-isolated engine. %>
+<% content_for(:title) { "Emails" } %>
+<%
+  aspect     = Studio::EmailCatalog::ASPECT_RATIO
+  max_width  = Studio::EmailCatalog::MAX_WIDTH
+  app_owned  = @entries.count { |entry| Studio::EmailCatalog.source(entry.key) == :app }
+%>
+<div class="max-w-5xl mx-auto px-4 pb-16">
+  <header class="space-y-2 pt-8 pb-6">
+    <p class="label-upper">studio-engine &middot; v<%= Studio::VERSION %></p>
+    <h1 class="text-3xl font-bold text-heading">Emails</h1>
+    <p class="text-body max-w-2xl">
+      Every transactional email <%= Studio.app_name %> sends, and the banner that
+      rides at the top of it. Each one starts on the shared Studio artwork; upload
+      your own and it belongs to this app from then on.
+    </p>
+    <p class="text-sm text-muted">
+      <%= pluralize(@entries.size, "email") %> registered &middot;
+      <%= app_owned.zero? ? "all inheriting the default artwork" : "#{app_owned} with #{Studio.app_name}'s own artwork" %>
+    </p>
+  </header>
+
+  <%# No flash block here on purpose — every host layout already renders the
+      shared layouts/studio/flash partial, so the controller's notice/alert
+      surfaces once rather than twice. %>
+
+  <%# Honest degradation: an app whose host never set Studio.s3_bucket_prefix can
+      SHOW what each email is sending but cannot store an override. Say so plainly
+      instead of offering an Edit button that 500s. %>
+  <% unless @uploads_available %>
+    <div class="mb-6 rounded-xl border border-subtle bg-inset px-4 py-3">
+      <p class="text-sm font-semibold text-heading">Read-only on this app</p>
+      <p class="text-sm text-body mt-1">
+        <%= Studio.app_name %> has no object storage configured, so the images below
+        can be viewed but not replaced yet. They are the shared defaults that ship
+        with the engine, and they are what this app is sending right now. Set
+        <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config.s3_bucket_prefix</code>
+        in <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config/initializers/studio.rb</code>
+        to turn on uploads.
+      </p>
+    </div>
+  <% end %>
+
+  <div class="card overflow-hidden">
+    <div class="overflow-x-auto">
+      <table class="w-full text-left align-middle">
+        <thead>
+          <tr class="border-b border-subtle">
+            <th class="label-upper px-4 py-3 w-48">Banner</th>
+            <th class="label-upper px-4 py-3">Email</th>
+            <th class="label-upper px-4 py-3 w-52">Image</th>
+            <% if @uploads_available %>
+              <th class="label-upper px-4 py-3 w-40 text-right">Actions</th>
+            <% end %>
+          </tr>
+        </thead>
+        <tbody>
+          <% @entries.each do |entry| %>
+            <%= render "studio/emails/row", entry: entry,
+                  uploads_available: @uploads_available,
+                  aspect: aspect, max_width: max_width %>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  </div>
+
+  <p class="text-xs text-muted mt-4">
+    Banners render full-bleed at 600px wide inside the email card. The crop is
+    fixed at <%= aspect.to_i %>:1 and saved at up to <%= max_width %>px, which is
+    retina-sharp in an inbox without tripping a clipping limit.
+    <% if @entries.any? { |entry| Studio::EmailCatalog.source(entry.key) == :none } %>
+      An email with no image sends bannerless — the card still renders.
+    <% end %>
+  </p>
+</div>
+
+<% if @uploads_available %>
+  <%# Cropper.js + the imageUploadHost / cropPhotoModal / submitFormWithProgress
+      factories, loaded only on this page. %>
+  <%= render "studio/cropper_assets" %>
+
+  <%# Page-scoped modal host — see the header note. Brings its own crop-photo +
+      saving modals so no host app has to register them. Deliberately NOT
+      studio/modals/host: mcritchie-studio and turf-monster ship app copies of
+      that path which shadow the engine's, so the page would get their fork. %>
+  <%# Optional chaining on current() is load-bearing: the outer template unmounts
+      one tick AFTER the stack empties, so a bare .id throws on every close. %>
+  <%= render "studio/modals/scoped_host", store: "emailModals" do %>
+    <template x-if="$store.emailModals.current()?.id === 'crop-photo'">
+      <div><%= render "studio/modals/crop_photo", store: "emailModals" %></div>
+    </template>
+    <template x-if="$store.emailModals.current()?.id === 'saving'">
+      <div><%= render "studio/modals/saving", store: "emailModals" %></div>
+    </template>
+  <% end %>
+<% end %>

data/app/views/studio/emails/show.html.erb

@@ -0,0 +1,91 @@
+<%#  admin/emails/:key — one email, previewed live.
+
+     A bare content wrapper like the index, so it renders inside each host's
+     layout. Lifted from turf-monster's admin/emails/show (the prior art this
+     work folds into the engine) and given the banner half: the same iframe over
+     the real rendered email, plus what artwork is riding on top of it and where
+     that artwork came from. %>
+<% content_for(:title) { @entry.label } %>
+<%
+  source     = Studio::EmailCatalog.source(@entry.key)
+  banner_url = Studio::EmailCatalog.preview_url(@entry.key)
+  aspect     = Studio::EmailCatalog::ASPECT_RATIO
+
+  badge_class, badge_label =
+    case source
+    when :app     then ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s own"]
+    when :default then ["badge bg-inset text-muted border-subtle", "Inherited default"]
+    else               ["badge bg-warning/10 text-warning border-warning/30", "No image"]
+    end
+%>
+<div class="max-w-5xl mx-auto px-4 pb-16">
+  <header class="pt-8 pb-5">
+    <%= link_to "← All emails", admin_emails_path,
+          class: "text-sm text-muted hover:text-heading underline underline-offset-2" %>
+    <h1 class="text-3xl font-bold text-heading mt-2"><%= @entry.label %></h1>
+
+    <div class="flex flex-wrap items-center gap-2 mt-3">
+      <span class="badge <%= @entry.marketing? ? "bg-primary/10 text-primary border-primary/30" : "bg-inset text-muted border-subtle" %> whitespace-nowrap">
+        <%= @entry.type.to_s.titleize %>
+      </span>
+      <span class="<%= badge_class %> whitespace-nowrap"><%= badge_label %></span>
+      <span class="font-mono text-2xs text-muted"><%= @entry.key %></span>
+    </div>
+
+    <% if @entry.description.present? %>
+      <p class="text-body max-w-2xl mt-3"><%= @entry.description %></p>
+    <% end %>
+
+    <% if @subject.present? %>
+      <p class="text-sm text-muted mt-2">
+        Subject: <strong class="text-heading"><%= @subject %></strong>
+      </p>
+    <% end %>
+  </header>
+
+  <%# The banner riding on top of this email, and where it came from. %>
+  <section class="card p-4 mb-6">
+    <p class="label-upper mb-3">Banner</p>
+    <div class="rounded-lg overflow-hidden border border-subtle max-w-md"
+         style="aspect-ratio: <%= aspect %>; background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));">
+      <% if banner_url %>
+        <%= image_tag banner_url, class: "w-full h-full object-cover",
+              alt: "#{@entry.label} email banner" %>
+      <% else %>
+        <div class="w-full h-full flex items-center justify-center text-xs text-white/80 text-center px-4">
+          This email sends without a banner.
+        </div>
+      <% end %>
+    </div>
+    <p class="text-sm text-muted mt-3">
+      <% if @uploads_available %>
+        Change it on the <%= link_to "emails list", admin_emails_path, class: "underline underline-offset-2" %>.
+      <% else %>
+        <%= Studio.app_name %> has no object storage configured, so this image can be
+        viewed but not replaced yet.
+      <% end %>
+    </p>
+  </section>
+
+  <%# The email itself. An iframe because the response IS an email document —
+      its own <html>, its own table layout, and no business inheriting the admin
+      page's stylesheet. %>
+  <section class="card p-3 bg-inset">
+    <p class="label-upper mb-3 px-1">Preview</p>
+    <% if @entry.previewable? %>
+      <iframe src="<%= admin_email_raw_path(@entry.key) %>"
+              style="width:100%;height:780px;border:0;border-radius:8px;background:#ffffff;"
+              title="<%= @entry.label %> preview"></iframe>
+    <% else %>
+      <div class="px-3 pb-4">
+        <p class="text-sm text-body">
+          No preview is registered for this email. Pass a <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">preview:</code>
+          callable when registering it — anything that returns a Mail — and it renders here.
+        </p>
+      </div>
+    <% end %>
+    <% if @preview_error.present? %>
+      <p class="text-2xs text-danger mt-2 px-1 font-mono break-all"><%= @preview_error %></p>
+    <% end %>
+  </section>
+</div>

data/app/views/studio/modals/_image_upload.html.erb

@@ -58,6 +58,9 @@
         if (props.maxHeight) this.maxHeight = props.maxHeight;
         if (typeof props.transparent === "boolean") this.transparent = props.transparent;
         if (props.dispatch) this.dispatch = true;
+        // Carried through untouched and echoed back on confirm, so the host that
+        // OPENED the cropper is the only one that acts on the result.
+        this.owner = props.owner || null;
         if (props.autoCropArea) this.autoCropArea = props.autoCropArea;
         if (props.imageUrl) {
           this.fromParent = true;
@@ -139,7 +142,15 @@
         var canvas = this.cropper.getCroppedCanvas(canvasOpts);
         canvas.toBlob(function (blob) {
           try {
-            window.dispatchEvent(new CustomEvent("crop-photo-confirmed", { detail: { blob: blob } }));
+            // OWNER RIDES WITH THE BLOB. `crop-photo-confirmed` is a WINDOW event, so
+            // every imageUploadHost on the page hears it — and /admin/emails mounts
+            // one host PER ROW. Without an owner, one confirmed crop PATCHed every
+            // row's banner with the same image, destroying any app-owned banner
+            // already there; the FIRST upload an admin ever performed hit it, because
+            // the engine pre-registers two emails. `owner` is the token the opening
+            // host stamped on the crop props, echoed back untouched.
+            window.dispatchEvent(new CustomEvent("crop-photo-confirmed",
+                                                 { detail: { blob: blob, owner: self.owner || null } }));
           } catch (_) {}
           if (self.cropper) { self.cropper.destroy(); self.cropper = null; }
           // dispatch mode: the opener's host owns the post-confirm flow
@@ -162,10 +173,11 @@
   // Swaps in the 'saving' card while the form uploads, then closes it (held
   // >= ~450ms so it doesn't flash) and toasts on completion. opts: { saving,
   // success, successMessage, failure, failureMessage, dismissible (default
-  // false), toast (default true) }.
+  // false), toast (default true), store (Alpine store name, default "modals" —
+  // pass a page-scoped host's name, e.g. "emailModals") }.
   window.submitFormWithProgress = function (form, opts) {
     opts = opts || {};
-    var store = window.Alpine && Alpine.store("modals");
+    var store = window.Alpine && Alpine.store(opts.store || "modals");
     var hold = (window.StudioModals && window.StudioModals.holdAtLeast)
       ? window.StudioModals.holdAtLeast(450)
       : { then: function (cb) { cb(); } };
@@ -199,9 +211,14 @@
   // it into the host's own hidden form input and submits immediately with a
   // loading card + toast (submitFormWithProgress). opts = crop config
   // (aspectRatio, maxWidth, maxHeight, transparent, autoCropArea) + save copy
-  // (saving, success, successMessage, failure, dismissible, toast, filename).
+  // (saving, success, successMessage, failure, dismissible, toast, filename) +
+  // store (Alpine store name, default "modals"). Pass `store` when the crop and
+  // saving modals are mounted on a PAGE-SCOPED host rather than the app's shared
+  // one — /admin/emails does, so the uploader works even in a host app that
+  // renders no shared modal host at all.
   window.imageUploadHost = function (opts) {
     opts = opts || {};
+    var storeName = opts.store || "modals";
     function cropProps(extra) {
       var p = {
         aspectRatio: opts.aspectRatio || 1,
@@ -214,11 +231,25 @@
       if (extra) { for (var k in extra) { p[k] = extra[k]; } }
       return p;
     }
+    // A token unique to THIS host instance. Many hosts can be mounted on one page
+    // (one per row on /admin/emails) and they all hear the same window event, so a
+    // confirm has to say WHICH host opened the cropper.
+    var ownerId = "iuh-" + (window.__studioImageUploadHostSeq = (window.__studioImageUploadHostSeq || 0) + 1);
+
     return {
+      ownerId: ownerId,
       // Modal-as-picker: the crop modal itself is the file picker / drop target.
       open() {
-        if (!window.Alpine || !Alpine.store("modals")) return;
-        Alpine.store("modals").open("crop-photo", cropProps());
+        if (!window.Alpine || !Alpine.store(storeName)) return;
+        Alpine.store(storeName).open("crop-photo", cropProps({ owner: ownerId }));
+      },
+      // The window-event guard: a confirm addressed to a DIFFERENT host is not ours
+      // to act on. An owner-LESS confirm still applies, so every existing
+      // single-host page keeps working unchanged.
+      onCropConfirmed(detail) {
+        if (!detail) return;
+        if (detail.owner && detail.owner !== ownerId) return;
+        this.applyCrop(detail.blob);
       },
       // Native picker: read the chosen image, then hand it to the modal.
       onFileSelected(event) {
@@ -226,7 +257,7 @@
         if (!file) return;
         var reader = new FileReader();
         reader.onload = function (e) {
-          Alpine.store("modals").open("crop-photo", cropProps({ imageUrl: e.target.result }));
+          Alpine.store(storeName).open("crop-photo", cropProps({ imageUrl: e.target.result, owner: ownerId }));
         };
         reader.readAsDataURL(file);
         event.target.value = "";