studio-engine 0.41.0 → 0.43.0

data/app/services/studio/email_preview_target.rb

@@ -0,0 +1,195 @@
+module Studio
+  # WHO the email manager previews an email as.
+  #
+  # The banner's header is per-recipient ("Welcome Mason!"), so "what does this
+  # email look like" has no answer until you say who is receiving it. The page
+  # offers a small set of real people to stand in, and every variable on the page
+  # — first name, email — comes from the chosen one.
+  #
+  # ## Why real records rather than made-up samples
+  #
+  # A fabricated "Sample User <sample@example.com>" previews a person who cannot
+  # receive mail, and it hides the failures that actually happen: an account with
+  # no display name, a name that is one word, a name long enough to wrap the
+  # banner. Reading the host's own users puts those in front of the operator.
+  #
+  # ## Why an ADMIN and a MEMBER
+  #
+  # They differ in the ways that break email. An admin is usually the operator
+  # themselves — a full name on file, an internal address. A member is whoever
+  # signed up: often no name at all, which is the case that renders "Welcome !"
+  # if the fallback header is wrong. Being able to flip between them is how that
+  # gets caught here rather than in someone's inbox.
+  #
+  # Nil-safe throughout. The host's User model may be absent, may not respond to
+  # `admin?`, may have no rows. The preview degrades to a synthetic stand-in
+  # rather than taking the manager down — this is a page for looking at pictures.
+  class EmailPreviewTarget
+    ATTRIBUTES = %i[id label name email admin avatar_url avatar_color].freeze
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(id:, label:, name: nil, email: nil, admin: false,
+                   avatar_url: nil, avatar_color: nil, initials: nil)
+      @id = id.to_s
+      @label = label
+      @name = name.presence
+      @email = email.presence
+      @admin = admin
+      @avatar_url = avatar_url.presence
+      @avatar_color = avatar_color.presence || DEFAULT_AVATAR_COLOR
+      @initials = initials.presence
+    end
+
+    # The HOST's own initials when it has them, so this circle matches the one in
+    # the navbar rather than being a second opinion about the same person.
+    # Falls back to the address when there is no name, because "no name on file"
+    # is the ordinary case for a member and an empty circle identifies nobody.
+    def initials
+      return @initials if @initials
+
+      source = name.presence || email.to_s.split("@").first.to_s
+      parts = source.split(/[\s._-]+/).reject(&:empty?)
+      return "?" if parts.empty?
+
+      (parts.length == 1 ? parts.first[0, 2] : parts.first(2).map { |part| part[0] }.join).upcase
+    end
+
+    DEFAULT_AVATAR_COLOR = "#6b7280".freeze
+
+    def admin? = !!@admin
+    def first_name = name.to_s.strip.split.first
+    def to_param = id
+
+    # A stand-in used only when the host has no matching user. Named as a sample
+    # so nobody mistakes the preview for a real account.
+    def sample? = id.start_with?("sample-")
+
+    class << self
+      # Every target the page can offer, admin first.
+      #
+      # The NAMELESS sample is always offered, even when a real member exists.
+      # It is the only way to see what the name-free fallback header sends, and
+      # the accounts an app actually parks tend to be real people with real names
+      # — McRitchie Studio's member is Mack McRitchie. The alternative was
+      # stripping a real person's name to make a preview reachable, which trades
+      # a worse app for a better test.
+      def all
+        [find_admin, find_member, sample_member].compact.uniq(&:id)
+      end
+
+      # The one to preview as. Falls back to the first available rather than
+      # erroring on a stale id from a bookmarked URL.
+      def resolve(id)
+        list = all
+        list.find { |target| target.id == id.to_s } || list.first
+      end
+
+      private
+
+      def find_admin
+        record = first_user { |scope| admins(scope) }
+        return sample_admin if record.nil?
+
+        from_record(record, id_prefix: "admin", label: "Admin", admin: true)
+      end
+
+      def find_member
+        record = first_user { |scope| members(scope) }
+        return nil if record.nil?
+
+        from_record(record, id_prefix: "member", label: "Member", admin: false)
+      end
+
+      # The host's User model, or nil. `safe_constantize` rather than defined?()
+      # so an app without one simply has no records to offer.
+      def user_model
+        model = "User".safe_constantize
+        return nil unless model.respond_to?(:all) && model.respond_to?(:column_names)
+
+        model
+      end
+
+      def first_user
+        model = user_model
+        return nil if model.nil?
+
+        yield(model)
+      rescue StandardError
+        # A missing table, a mid-migration column, a host User that is not an
+        # ActiveRecord at all. None of them should cost more than the dropdown.
+        nil
+      end
+
+      # `admin` may be a column, a method, or absent entirely. Only the column
+      # can be queried; anything else is filtered in Ruby over a bounded slice,
+      # because a preview must not table-scan a production users table.
+      def admins(model)
+        return model.where(admin: true).first if model.column_names.include?("admin")
+
+        model.limit(50).detect { |user| user.try(:admin?) }
+      end
+
+      def members(model)
+        return model.where(admin: [false, nil]).first if model.column_names.include?("admin")
+
+        model.limit(50).detect { |user| !user.try(:admin?) }
+      end
+
+      def from_record(record, id_prefix:, label:, admin:)
+        new(id: "#{id_prefix}-#{record.id}", label: label, admin: admin,
+            name: display_name_for(record), email: record.try(:email),
+            avatar_url: avatar_url_for(record), avatar_color: record.try(:avatar_color),
+            initials: record.try(:avatar_initials))
+      end
+
+      # ActiveStorage, defensively. A host may not attach avatars at all, the blob
+      # may be missing, and url helpers need a host that a background job does not
+      # have — none of which should cost more than a plain initials circle.
+      def avatar_url_for(record)
+        avatar = record.try(:avatar)
+        return nil unless avatar.respond_to?(:attached?) && avatar.attached?
+
+        Rails.application.routes.url_helpers.rails_blob_path(avatar, only_path: true)
+      rescue StandardError
+        nil
+      end
+
+      # "Is there a REAL name on file", not "what should we call this person".
+      #
+      # display_name is asked LAST and only when the record has no name attribute
+      # at all. It is a presentation helper: McRitchie Studio's synthesises one
+      # from the email address, so member@… came back as "Member" and the
+      # nameless member — the entire reason that option exists — previewed as
+      # somebody with a name. A blank `name` is the honest nil.
+      def display_name_for(record)
+        return record.name.presence if record.respond_to?(:name)
+        return record.full_name.presence if record.respond_to?(:full_name)
+
+        record.try(:display_name).presence
+      end
+
+      # The app's own domain, read off the configured from-address rather than
+      # a new config knob — a sample address on some other domain would look
+      # like a real account somewhere else.
+      def sample_domain
+        Studio.mailer_from.to_s[/@([^\s>]+)/, 1].presence || "example.com"
+      rescue StandardError
+        "example.com"
+      end
+
+      def sample_admin
+        new(id: "sample-admin", label: "Admin (sample)", admin: true,
+            name: "Alex McRitchie", email: "alex@#{sample_domain}")
+      end
+
+      # Deliberately NAMELESS, and always present. This is the only recipient that
+      # exercises the name-free fallback header — the case a magic link hits every
+      # time it reaches someone with no account yet, and the one nobody thinks to
+      # check because whoever is previewing has a name on file.
+      def sample_member
+        new(id: "sample-member", label: "No name on file", admin: false,
+            name: nil, email: "someone@#{sample_domain}")
+      end
+    end
+  end
+end

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

@@ -1,17 +1,34 @@
 <%#
-  Shared branded transactional email shell. A full-bleed banner (set @banner_url,
-  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
+  Shared branded transactional email shell. A full-bleed banner 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
   layouts/branded_mailer.html.erb.
+
+  TWO banner shapes, in priority order:
+
+    @banner — a Studio::Banner, built by Studio::Banner.for and drawn by the
+      studio/mailers/layered_banner partial. LAYERED: a
+      background image with the header, sub-text and logo as live HTML on top.
+      This is the shape that supports an ANIMATED background together with
+      per-recipient text, because the text is never drawn into the picture.
+
+    @banner_url — a plain image URL, rendered as an <img>. The original shape,
+      UNCHANGED: every mailer already shipping sets this and renders exactly as
+      before. A layered banner is opt-in, never a migration.
 %>
 <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="margin:0;padding:24px 0;background:#f4f5f7;">
   <tr>
     <td align="center" style="padding:0 12px;">
       <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" style="width:600px;max-width:600px;background:#ffffff;border-radius:14px;overflow:hidden;box-shadow:0 1px 4px rgba(15,23,42,0.08);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
 
-        <% if @banner_url.present? %>
+        <% if @banner.respond_to?(:renderable?) && @banner.renderable? %>
+          <tr>
+            <td style="padding:0;line-height:0;">
+              <%= render "studio/mailers/layered_banner", banner: @banner %>
+            </td>
+          </tr>
+        <% elsif @banner_url.present? %>
           <tr>
             <td style="padding:0;line-height:0;">
               <img src="<%= @banner_url %>" width="600" alt="<%= @banner_alt || Studio.app_name %>"
@@ -25,6 +42,38 @@
             <%= yield %>
           </td>
         </tr>
+
+        <%# THE SHARED FOOTER — the same on every email this app sends, which is
+            why it lives in the layout and is stored once rather than per email.
+
+            FULL-BLEED AND DARK. The band closes the white card: a light sign-off
+            floating under the body reads as part of the message rather than the
+            end of it. bgcolor as well as the CSS, because Outlook renders through
+            Word and drops background-color on a td often enough that the
+            attribute is the only reliable half.
+
+            Renders nothing when the operator has cleared both fields. %>
+        <% footer = Studio::EmailCatalog.footer %>
+        <% if footer[:logo_url].present? || footer[:discord_url].present? %>
+          <tr>
+            <td align="center" bgcolor="<%= Studio::EmailCatalog::FOOTER_BACKGROUND %>"
+                <%# color as well as the background: with images blocked, the alt
+                    text is all that is left, and a client's near-black default on
+                    a near-black band is invisible. %>
+                style="background-color:<%= Studio::EmailCatalog::FOOTER_BACKGROUND %>;padding:28px 36px;color:#F5F3FF;">
+              <% if footer[:logo_url].present? %>
+                <%# height as well as width: Outlook collapses an alt placeholder
+                    that has no height, so a blocked image leaves nothing at all. %>
+                <img src="<%= footer[:logo_url] %>" width="132" height="32" alt="<%= Studio.app_name %>"
+                     style="display:block;margin:0 auto 14px;width:132px;height:auto;border:0;color:#F5F3FF;" />
+              <% end %>
+              <% if footer[:discord_url].present? %>
+                <a href="<%= footer[:discord_url] %>"
+                   style="font-size:13px;color:#C9C2FF;text-decoration:none;">Join us on Discord</a>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
       </table>
     </td>
   </tr>

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

@@ -0,0 +1,199 @@
+<%# The live banner editor: typing repaints the banner, and ONE Save button in
+    the header reports whether there is anything to save.
+
+    WHY THE PREVIEW IS PAINTED IN THE BROWSER AND NOT RE-RENDERED
+    The banner is already server-rendered by the mailer's own partial, which is
+    what makes it trustworthy. This does not replace it — it edits the text
+    nodes, the logo and the tint of that same rendered banner in place. The
+    shape, the typography and the scaling stay the server's. Re-rendering a
+    second banner in JavaScript would be a second implementation of the email,
+    and it would drift.
+
+    WHY THE PLACEHOLDER RULE IS REPEATED HERE
+    Studio::Banner fills {name} and {app} server-side. Repeating that in script
+    is a real duplication and worth naming: the alternative is a round trip per
+    keystroke. The rule is small and pinned on both sides — banner_copy_test.rb
+    for Ruby, e2e/email_banner_editor.spec.js for the browser. If they ever
+    disagree, the server is right.
+
+    TOUCHED VS DIRTY — they are different questions and the button answers both.
+    `touched` is "has anyone typed here", and it decides whether the button is
+    SHOWN. `dirty` is "is anything actually different from what is saved", and it
+    decides whether the button is ENABLED. Typing "A" into the subject and
+    deleting it again leaves touched true and dirty false: the button stays
+    visible and goes back to disabled, which is what tells the operator their
+    edit was undone rather than silently swallowed.
+%>
+<style>
+  /* The tint slider, in the app's own palette.
+
+     appearance:none and explicit track/thumb rules rather than `accent-color`:
+     accent-color tints a native slider but leaves its proportions to the
+     browser, so the control looked like a system widget dropped into the page —
+     a blue rail in a purple app. These rules give it the same rail, radius and
+     primary colour as everything else on the card.
+
+     The FILLED portion is a gradient driven by --range-fill, which the component
+     sets from the current value. Firefox has ::-moz-range-progress and WebKit
+     has nothing equivalent, so one gradient serves both rather than two
+     divergent implementations. */
+  .studio-range {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 100%;
+    height: 6px;
+    border-radius: 999px;
+    background: linear-gradient(to right,
+                var(--color-primary, #8E82FE) var(--range-fill, 40%),
+                var(--color-inset, rgba(148, 163, 184, 0.35)) var(--range-fill, 40%));
+    outline: none;
+    cursor: pointer;
+  }
+  .studio-range::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 16px;
+    height: 16px;
+    border-radius: 999px;
+    background: var(--color-primary, #8E82FE);
+    border: 2px solid var(--color-surface, #ffffff);
+    box-shadow: 0 1px 3px rgba(15, 23, 42, 0.35);
+  }
+  .studio-range::-moz-range-thumb {
+    width: 16px;
+    height: 16px;
+    border-radius: 999px;
+    background: var(--color-primary, #8E82FE);
+    border: 2px solid var(--color-surface, #ffffff);
+    box-shadow: 0 1px 3px rgba(15, 23, 42, 0.35);
+  }
+  .studio-range::-moz-range-track { height: 6px; border-radius: 999px; background: transparent; }
+  .studio-range:focus-visible { box-shadow: 0 0 0 3px color-mix(in srgb, var(--color-primary, #8E82FE) 35%, transparent); }
+</style>
+<script>
+  (function () {
+    function editor(config) {
+      return {
+        form: Object.assign({}, config.values),
+        initial: Object.assign({}, config.values),
+        targets: config.targets || [],
+        targetId: config.targetId,
+        touched: false,
+        pickerOpen: false,
+
+        init() {
+          this.paint();
+          this.$watch("form", () => { this.touched = true; this.paint(); });
+          this.$watch("targetId", () => this.paint());
+        },
+
+        target() {
+          return this.targets.find((t) => t.id === this.targetId) || this.targets[0] || {};
+        },
+
+        firstName() {
+          return (this.target().name || "").trim().split(/\s+/)[0] || "";
+        },
+
+        // {app} is substituted on both paths because it does not depend on the
+        // recipient — a header reading "Welcome to {app}" must not show a raw
+        // brace here while the inbox shows the app's name.
+        resolve(template, fallback) {
+          var first = this.firstName();
+          var app = config.appName || "";
+          var text = (template || "").replace(/\{app\}/g, app);
+          if (first) return text.replace(/\{name\}/g, first);
+          if (text.indexOf("{name}") !== -1) return (fallback || "").replace(/\{app\}/g, app);
+          return text;
+        },
+
+        headerText() { return this.resolve(this.form.header, this.form.header_fallback); },
+        subjectText() { return this.resolve(this.form.subject, this.form.subject); },
+
+        // Field by field rather than JSON.stringify, whose output depends on key
+        // order — two equal objects can stringify differently.
+        //
+        // No type coercion here, deliberately. An earlier version normalised
+        // booleans on the theory that a checkbox holds true while the server
+        // echoes "1"; a mutation run showed removing it changed nothing, because
+        // the payload sends real booleans for the two checkboxes and strings for
+        // everything else. Unproven defensive code in a comparison that decides
+        // whether a Save button appears is worse than none.
+        dirty() {
+          return Object.keys(this.initial).some(function (k) {
+            return (this.form[k] ?? "") !== (this.initial[k] ?? "");
+          }, this);
+        },
+
+        // The logo has THREE states, and a URL field alone can only express two.
+        // "standard" inherits, "custom" uses what this app uploaded, "hidden" is
+        // the deliberate no-logo answer that blank cannot say.
+        logoMode() {
+          if (this.form.hide_logo === true || this.form.hide_logo === "1") return "hidden";
+          if (config.uploadedLogo) return "custom";
+          return "standard";
+        },
+
+        setLogoMode(mode) {
+          this.form.hide_logo = mode === "hidden";
+        },
+
+        currentLogo() {
+          if (this.logoMode() === "hidden") return "";
+          return config.uploadedLogo || config.inheritedLogo || "";
+        },
+
+        // The slider's own fill, as a percentage string for --range-fill.
+        scrimFill() {
+          var percent = parseInt(this.form.scrim_percent, 10);
+          if (isNaN(percent)) percent = config.defaultScrim;
+          return Math.min(Math.max(percent, 0), 100) + "%";
+        },
+
+        scrimCss() {
+          var percent = parseInt(this.form.scrim_percent, 10);
+          if (isNaN(percent)) percent = config.defaultScrim;
+          percent = Math.min(Math.max(percent, 0), 100);
+          return "rgba(24,16,64," + (percent / 100) + ")";
+        },
+
+        paint() {
+          var root = this.$root;
+          var header = root.querySelector("[data-banner-header]");
+          var subtext = root.querySelector("[data-banner-subtext]");
+          var logo = root.querySelector("[data-banner-logo]");
+          var scrim = root.querySelector("[data-banner-scrim]");
+
+          if (header) header.textContent = this.headerText();
+          if (subtext) subtext.textContent = this.form.subtext || "";
+          if (scrim) scrim.style.backgroundColor = this.scrimCss();
+          if (logo) {
+            var url = this.currentLogo();
+            if (url) {
+              if (logo.getAttribute("src") !== url) logo.setAttribute("src", url);
+              logo.style.display = "block";
+            } else {
+              logo.style.display = "none";
+            }
+          }
+        },
+
+        // Every visible field is x-model bound and carries no name; the hidden
+        // form below mirrors them. One submit writes the whole page.
+        save() {
+          if (!this.dirty()) return;
+          this.$refs.saveForm.requestSubmit();
+        }
+      };
+    }
+
+    window.emailBannerEditor = editor;
+    if (typeof Alpine !== "undefined") {
+      Alpine.data("emailBannerEditor", editor);
+    } else {
+      document.addEventListener("alpine:init", function () {
+        Alpine.data("emailBannerEditor", editor);
+      });
+    }
+  })();
+</script>

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

@@ -0,0 +1,62 @@
+<%# THE banner preview — one component, every size.
+
+    locals:
+      banner:   a Studio::Banner (required)
+      ratio:    the frame's aspect ratio (default: the banner's own)
+      max_width: cap the frame in px, or nil to fill its column
+      isolate:  render inside an iframe (default true)
+
+    WHY IT IS A COMPONENT
+    There were two copies of this — the list row and the email's own page — and
+    they had already drifted: one carried the "does this app actually send a
+    layered banner" guard and the other did not, so the detail page previewed
+    live text over artwork no inbox receives. One component means a fix lands
+    everywhere, which is the same argument as rendering through the mailer's own
+    partial rather than a lookalike.
+
+    WHY THE IFRAME
+    The banner is the EMAIL's markup — a <table>. Dropping one into a list row
+    nests rows inside rows, and every host asserting "one row per email" counted
+    three per layered email. A separate document keeps the host page's markup
+    contract intact. Pass isolate: false where nesting is not a concern and a
+    plain preview is cheaper.
+
+    WHY THE RESET
+    A srcdoc document is a fresh page with the browser's default stylesheet, so
+    it inherits `body { margin: 8px }` — which showed as a band of padding around
+    every thumbnail. The email itself never sees this: the reset lives here, not
+    in the partial the mailer renders.
+%>
+<%
+  banner    = local_assigns.fetch(:banner)
+  ratio     = local_assigns.fetch(:ratio, banner.width.to_f / banner.height)
+  max_width = local_assigns.fetch(:max_width, Studio::Banner::DEFAULT_WIDTH)
+  isolate   = local_assigns.fetch(:isolate, true)
+
+  markup = render("studio/mailers/layered_banner", banner: banner, preview: true)
+  document = <<~HTML
+    <!doctype html><html><head><meta charset="utf-8">
+    <style>html,body{margin:0;padding:0;background:transparent;}</style>
+    </head><body>#{markup}</body></html>
+  HTML
+  frame_style = ["aspect-ratio: #{ratio}"]
+  frame_style << "max-width: #{max_width}px" if max_width
+%>
+<div class="rounded-lg overflow-hidden border border-subtle" data-email-banner-frame
+     style="<%= frame_style.join("; ") %>;">
+  <% if isolate %>
+    <iframe class="pointer-events-none block" scrolling="no" tabindex="-1" loading="lazy"
+            data-email-banner-preview data-banner-width="<%= banner.width %>"
+            title="<%= banner.header.presence || "Email banner" %>"
+            style="width:<%= banner.width %>px;height:<%= banner.height %>px;border:0;display:block;transform-origin:top left;"
+            <%# ESCAPED EXPLICITLY: render returns an html_safe buffer, so a bare
+                output tag injects it RAW and closes the iframe at the banner's
+                first quote. to_str drops the safe flag so escaping happens. %>
+            srcdoc="<%= ERB::Util.html_escape(document.to_str) %>"></iframe>
+  <% else %>
+    <div data-email-banner-preview data-banner-width="<%= banner.width %>"
+         style="width:<%= banner.width %>px;transform-origin:top left;">
+      <%= markup %>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,56 @@
+<%# Scales the 600px email banner down to whatever width its frame has.
+
+    Why this needs script at all: the banner is the EMAIL's own markup, a fixed
+    600px table, and it must stay that way — an inbox has no responsive layout,
+    so making it fluid here would mean previewing markup no one receives. The
+    frame beside it is fluid. Nothing in CSS converts a fixed-width box into a
+    fluid one without knowing the container's width, so the width is read and a
+    transform applied.
+
+    What it does NOT do: move anything. It sets a scale on a box whose height is
+    already reserved by `aspect-ratio`, so no reflow follows and there is no
+    paint-time jump — the failure mode of measuring layout in script.
+
+    Degrades to an unscaled, clipped preview if script never runs. That is the
+    behaviour this replaced, so a failure here costs the improvement, not the page.
+%>
+<script>
+  (function () {
+    function fit(preview) {
+      var frame = preview.parentElement;
+      if (!frame) return;
+      var natural = parseFloat(preview.dataset.bannerWidth) || 600;
+      var available = frame.clientWidth;
+      if (!available) return;
+      // Never scale UP past the real size: at 1:1 this preview is exactly the
+      // 600px the recipient sees, and blowing it past that would show the
+      // operator a banner larger than any inbox renders.
+      var scale = Math.min(available / natural, 1);
+      preview.style.transform = "scale(" + scale + ")";
+    }
+
+    function fitAll() {
+      document.querySelectorAll("[data-email-banner-preview]").forEach(fit);
+    }
+
+    // ResizeObserver rather than a resize listener: the frame changes width when
+    // a sidebar opens or the grid reflows, neither of which resizes the window.
+    var observer = typeof ResizeObserver === "function" ? new ResizeObserver(fitAll) : null;
+
+    function start() {
+      fitAll();
+      if (!observer) return;
+      observer.disconnect();
+      document.querySelectorAll("[data-email-banner-frame]").forEach(function (frame) {
+        observer.observe(frame);
+      });
+    }
+
+    // turbo:load as well as DOMContentLoaded — a Turbo visit swaps the body
+    // without firing DOMContentLoaded, which would leave the preview at its
+    // unscaled 600px until a full reload.
+    document.addEventListener("DOMContentLoaded", start);
+    document.addEventListener("turbo:load", start);
+    if (document.readyState !== "loading") start();
+  })();
+</script>

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

@@ -0,0 +1,63 @@
+<%# locals: (targets:, target:) — the "preview as" control, shared by the emails
+    list and one email's own page.
+
+    Extracted rather than copied. The list repaints EVERY row's banner and
+    subject from this one selection; the detail page repaints one. Two copies of
+    an avatar listbox would be two places for the fallback circle to rot, and the
+    fallback is the branch that renders for a member with no avatar — the common
+    case.
+
+    A custom listbox rather than a select, because a native option cannot carry
+    an image, and the avatar is the whole point: it is how you tell at a glance
+    which account you are looking at. %>
+<div class="relative" @keydown.escape="pickerOpen = false" @click.outside="pickerOpen = false">
+  <button type="button" @click="pickerOpen = !pickerOpen" data-preview-target
+          class="input-field w-full py-2 flex items-center gap-3 text-left"
+          :aria-expanded="pickerOpen" aria-haspopup="listbox">
+    <template x-if="target().avatar_url">
+      <img :src="target().avatar_url" alt="" data-target-avatar
+           class="w-8 h-8 rounded-full object-cover shrink-0">
+    </template>
+    <template x-if="!target().avatar_url">
+      <span data-target-initials
+            class="w-8 h-8 rounded-full flex items-center justify-center text-xs font-bold text-white shrink-0"
+            :style="'background-color: ' + (target().avatar_color || '#6b7280')"
+            x-text="target().initials"></span>
+    </template>
+    <span class="min-w-0">
+      <span class="block text-heading truncate" x-text="target().name || target().label"></span>
+      <span class="block text-2xs text-muted truncate" x-text="target().email"></span>
+    </span>
+    <svg class="w-4 h-4 text-muted ml-auto shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
+    </svg>
+  </button>
+
+  <ul x-show="pickerOpen" x-cloak role="listbox"
+      class="absolute z-20 mt-1 w-full rounded-lg border border-subtle bg-surface shadow-lg overflow-hidden">
+    <template x-for="option in targets" :key="option.id">
+      <li>
+        <button type="button" role="option" data-preview-option :data-option-id="option.id"
+                @click="targetId = option.id; pickerOpen = false"
+                :aria-selected="option.id === targetId"
+                class="w-full px-3 py-2 flex items-center gap-3 text-left hover:bg-inset"
+                :class="option.id === targetId ? 'bg-inset' : ''">
+          <template x-if="option.avatar_url">
+            <img :src="option.avatar_url" alt="" data-option-avatar
+                 class="w-8 h-8 rounded-full object-cover shrink-0">
+          </template>
+          <template x-if="!option.avatar_url">
+            <span data-option-initials
+                  class="w-8 h-8 rounded-full flex items-center justify-center text-xs font-bold text-white shrink-0"
+                  :style="'background-color: ' + (option.avatar_color || '#6b7280')"
+                  x-text="option.initials"></span>
+          </template>
+          <span class="min-w-0">
+            <span class="block text-heading truncate" x-text="option.name || option.label"></span>
+            <span class="block text-2xs text-muted truncate" x-text="option.email"></span>
+          </span>
+        </button>
+      </li>
+    </template>
+  </ul>
+</div>