studio-engine 0.33.0 → 0.37.0

data/app/mailers/user_mailer.rb

@@ -21,7 +21,10 @@ class UserMailer < ApplicationMailer
     @app_name   = Studio.app_name
     @email      = email
     @magic_url  = magic_link_url_for(token)
-    @banner_url = Studio::EmailImage.url(:magic_link) # admin-managed; nil renders bannerless
+    # resolved_url, not url: this app's own upload if it has one, otherwise the
+    # engine's default banner — which is what makes a brand-new app's sign-in
+    # email branded on day one. nil renders bannerless.
+    @banner_url = Studio::EmailImage.resolved_url(:magic_link)
     @banner_alt = "Your #{@app_name} sign-in link"
     mail(to: email, subject: "Your #{@app_name} sign-in link")
   end

data/app/services/studio/email_image.rb

@@ -1,64 +1,263 @@
 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.
+  # The transactional-email registry, and the banner image each registered email
+  # ships with.
   #
-  # 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).
+  # A registered email is MOSTLY SYMBOLIC of a workflow — a key, a human label,
+  # a line of description. The only real asset is its banner image, which is why
+  # the registry lives here rather than in a model. The branded mailer resolves
+  # the live banner with .url; /admin/emails lists the registry and writes an
+  # override with .store.
+  #
+  # ## Two layers: inherited default, app-owned override
+  #
+  #   .resolved_url(key) => app's own ImageCache row (its S3 bucket)  # app-owned
+  #                      -> the engine's default gem asset            # inherited
+  #                      -> nil                                       # no image
+  #
+  # `.url(key)` stays the PRE-REGISTRY contract — this app's own image or nil —
+  # so every caller written before the registry keeps its behavior until its app
+  # adopts. See the note on #url; getting this wrong swaps a host's committed
+  # artwork for the engine placeholder in live email.
+  #
+  # Defaults RIDE THE GEM (app/assets/images/emails/*), so a brand-new app with
+  # an empty bucket sends good-looking email on day one and needs no cross-app S3
+  # permission. Uploading on an app's /admin/emails writes to THAT app's bucket
+  # and THAT app's ImageCache row — which is exactly "the asset now belongs to
+  # this app". Every app has its own bucket and its own image_caches table, so an
+  # override never leaks between apps.
+  #
+  # ## Registering
+  #
+  # The engine pre-registers the two every Studio app sends (STANDARD below), so
+  # hosts inherit them without declaring anything. A host adds its own workflows
+  # from an initializer, mirroring Studio::ModelPage.register:
+  #
+  #   # config/initializers/studio_emails.rb
+  #   Rails.application.config.to_prepare do
+  #     Studio::EmailImage.register("winnings", label: "Contest winnings",
+  #                                 description: "Sent when a player wins a contest.")
+  #   end
+  #
+  # Re-registering a key updates it in place and keeps its position, so a host
+  # can relabel an inherited email without reordering the page.
   module EmailImage
     PURPOSE = "email_banner".freeze
 
-    # variant => human label, in admin display order.
-    VARIANTS = {
-      "magic_link" => "Magic-link sign-in"
-    }.freeze
+    # A registered email. `default_asset` is a logical asset path inside the gem
+    # (resolved through the host's asset pipeline); nil means the email has no
+    # inherited artwork and renders bannerless until someone uploads one.
+    Entry = Struct.new(:key, :label, :description, :default_asset, keyword_init: true) do
+      def to_s = key
+    end
+
+    # The emails EVERY Studio app sends. Pre-registered, so a host inherits both
+    # without declaring anything.
+    STANDARD = [
+      {
+        key: "magic_link",
+        label: "Magic-link sign-in",
+        description: "Passwordless sign-in link. Sent whenever someone asks to sign in by email.",
+        default_asset: "emails/magic-link.png"
+      },
+      {
+        key: "email_change_confirmation",
+        label: "Email change confirmation",
+        description: "Confirms a new address before the change takes effect.",
+        default_asset: "emails/email-change-confirmation.png"
+      }
+    ].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.
+    ASPECT_RATIO = 2.0
+    MAX_WIDTH = 1200
 
     module_function
 
+    # --- Registry ----------------------------------------------------------
+
+    # Register (or update) an email workflow. Returns the key.
+    def register(key, label: nil, description: nil, default_asset: nil)
+      key = key.to_s
+      existing = registry[key]
+      registry[key] = Entry.new(
+        key: key,
+        label: label || existing&.label || key.humanize,
+        description: description || existing&.description,
+        default_asset: default_asset.nil? ? existing&.default_asset : default_asset.presence
+      )
+      key
+    end
+
+    # Every registered email, in display order: the standard two first, then the
+    # host's own in declaration order.
+    def entries
+      registry.values
+    end
+
+    def entry(key)
+      registry[key.to_s]
+    end
+
+    def keys
+      registry.keys
+    end
+
+    def known?(key)
+      registry.key?(key.to_s)
+    end
+    def registered?(key) = known?(key)
+
+    def label(key)
+      entry(key)&.label || key.to_s.humanize
+    end
+
+    # Legacy shape — key => label. Kept because it is the API the pre-registry
+    # admin page and any host that read VARIANTS were written against.
     def variants
-      VARIANTS
+      registry.transform_values(&:label)
     end
 
-    def label(variant)
-      VARIANTS[variant.to_s] || variant.to_s.humanize
+    # Drops host registrations back to the standard two. For tests and for
+    # to_prepare re-registration.
+    def reset!
+      @registry = nil
+      registry
+      nil
+    end
+
+    def registry
+      @registry ||= STANDARD.each_with_object({}) do |attrs, out|
+        out[attrs[:key]] = Entry.new(**attrs)
+      end
     end
 
-    def known?(variant)
-      VARIANTS.key?(variant.to_s)
+    # --- Resolution --------------------------------------------------------
+
+    # Where the live banner for this email comes from:
+    #   :app     — this app uploaded its own (ImageCache row in its bucket)
+    #   :default — the inherited engine default (gem asset)
+    #   :none    — no image at all; the email sends bannerless
+    def source(key)
+      return :app if record(key)
+      return :default if default_asset_path(key)
+
+      :none
     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)
+    def app_owned?(key) = source(key) == :app
+
+    # THIS APP'S OWN image only — nil when nothing has been uploaded here.
+    #
+    # This is the PRE-REGISTRY contract, kept EXACTLY: `url` has always meant
+    # "the admin-managed override, or nil", and callers were written to fall back
+    # themselves. turf-monster's mailer is the live example:
+    #
+    #   @banner_url = Studio::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")
+    #
+    # Making `url` resolve to the engine default would make that `||` dead code
+    # and silently replace turf-monster's own branded 1200x600 banner with the
+    # engine's PLACEHOLDER in real sign-in email. A method whose signature is
+    # unchanged but whose return value flips from nil to a value is not additive.
+    # So the new two-layer resolution lives in resolved_url, and every existing
+    # caller keeps the behavior it was written against until its app adopts.
+    def url(key)
+      record(key)&.url
+    end
+
+    # What ACTUALLY SHIPS on this email — the two-layer resolution. Absolute, so
+    # it resolves from an inbox. App-owned override first, then the inherited
+    # engine default, then nil (the mailer renders bannerless).
+    #
+    # This is what a mailer should call once its app has adopted the registry.
+    # The engine's own UserMailer already does, which is what gives an app with
+    # an empty bucket branded email on day one.
+    def resolved_url(key)
+      url(key) || default_url(key)
+    end
+
+    # What the ADMIN PAGE previews. Same two layers as resolved_url, but a
+    # default stays a root-relative asset path so it renders correctly on
+    # 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)
+    end
+
+    # The ImageCache row holding this app's override, or nil (nothing uploaded /
+    # table not installed yet). Nil-safe so the mailer renders before any upload.
+    def record(key)
       return nil unless table_ready?
 
-      ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: variant.to_s)
+      ::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 default_asset_path(key)
+      asset = entry(key)&.default_asset
+      return nil if asset.nil? || asset.empty?
+
+      path = ActionController::Base.helpers.asset_path(asset)
+      path.presence
+    rescue StandardError
+      nil
+    end
+
+    # Absolute URL to the inherited default asset — what a mailer needs. Uses
+    # action_mailer.asset_host (set per env), falling back to the mailer's
+    # default_url_options host. Returns the bare path if neither is configured,
+    # which still renders in the local inbox preview.
+    def default_url(key)
+      path = default_asset_path(key)
+      return nil if path.nil?
+      return path if path.start_with?("http")
+
+      host = mailer_asset_host
+      host ? "#{host}#{path}" : path
     end
 
-    # Permanent public S3 url for the current banner, or nil.
-    def url(variant)
-      record(variant)&.url
+    # --- Upload ------------------------------------------------------------
+
+    # Whether THIS app can accept an upload. False when the host never set
+    # Studio.s3_bucket_prefix — /admin/emails then shows inherited defaults
+    # read-only rather than 500ing on the first upload.
+    def uploads_available?
+      Studio::S3.configured? && table_ready?
     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,
+    # Upload bytes to this app's bucket + upsert its ImageCache row (replacing
+    # any prior object). Returns the ::ImageCache. Raises on failure after
+    # cleaning up the new object.
+    def store(key, io:, content_type: nil)
+      s3_key = "email_banners/#{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: PURPOSE, variant: variant.to_s)
+      record = ::ImageCache.find_or_initialize_by(owner: nil, purpose: PURPOSE, variant: key.to_s)
       previous = record.s3_key
-      record.update!(s3_key: key)
-      delete_object(previous) if previous.present? && previous != key
+      record.update!(s3_key: s3_key)
+      delete_object(previous) if previous.present? && previous != s3_key
       record
     rescue StandardError
-      delete_object(key)
+      delete_object(s3_key)
       raise
     end
 
+    # Drop this app's override and fall back to the inherited default. Returns
+    # true when a row was removed.
+    def revert(key)
+      row = record(key)
+      return false if row.nil?
+
+      previous = row.s3_key
+      row.destroy!
+      delete_object(previous) if previous.present?
+      true
+    end
+
+    # --- Internals ---------------------------------------------------------
+
     # 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?
@@ -67,6 +266,51 @@ module Studio
       false
     end
 
+    # The origin an email's banner URL hangs off. action_mailer.asset_host when
+    # the host sets one (turf-monster does, per env); otherwise built from the
+    # mailer's default_url_options.
+    #
+    # That fallback has to reconstruct a real origin, not just the hostname.
+    # default_url_options is routinely {host: "localhost", port: 3001} — taking
+    # :host alone and prefixing "https://" yields https://localhost, which is the
+    # wrong scheme AND the wrong port, and the banner comes back
+    # ERR_CONNECTION_REFUSED. Caught by opening the preview page on a worktree
+    # stack; every dev/QA preview took that path.
+    def mailer_asset_host
+      configured = Rails.application.config.action_mailer.asset_host.presence
+      return configured if configured
+
+      options = ActionMailer::Base.default_url_options || {}
+      host = options[:host].presence
+      return nil if host.nil?
+      return host if host.start_with?("http")
+
+      "#{mailer_protocol(options, host)}://#{host}#{mailer_port_suffix(options)}"
+    rescue StandardError
+      nil
+    end
+
+    # Honor an explicit :protocol. Otherwise https — EXCEPT on loopback, which is
+    # a dev stack with no TLS. Defaulting the other way would downgrade every
+    # production app that sets only {host: "mcritchie.studio"}.
+    def mailer_protocol(options, host)
+      explicit = options[:protocol].presence
+      return explicit.to_s.sub(%r{://\z}, "") if explicit
+
+      LOOPBACK_HOSTS.include?(host.downcase) ? "http" : "https"
+    end
+
+    # Ports are part of the origin, and omitting one sends the reader to :443.
+    # The scheme defaults are left off so a normal URL stays normal.
+    def mailer_port_suffix(options)
+      port = options[:port]
+      return "" if port.blank? || [80, 443].include?(port.to_i)
+
+      ":#{port}"
+    end
+
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 0.0.0.0 ::1].freeze
+
     def ext_for(content_type)
       case content_type.to_s
       when %r{png}    then ".png"

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::EmailImage.preview_url(variant) %>
+      <% inherited = current_url.present? && Studio::EmailImage.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,102 @@
+<%# 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::EmailImage.source(entry.key)
+  banner_url = Studio::EmailImage.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">
+    <p class="font-semibold text-heading"><%= entry.label %></p>
+    <% 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::EmailImage::ASPECT_RATIO
+  max_width  = Studio::EmailImage::MAX_WIDTH
+  app_owned  = @entries.count { |entry| Studio::EmailImage.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::EmailImage.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 %>