studio-engine 0.40.0 → 0.42.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 %>"

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

@@ -0,0 +1,192 @@
+<%# 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.
+        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_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>

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

@@ -0,0 +1,122 @@
+<%# Repaints EVERY row on the emails list when the example recipient changes.
+
+    The list shows each email's banner and subject as they would arrive. Both are
+    per-recipient — the banner greets by first name and the subject may too — so
+    a list rendered for one person is a list of half-truths about everyone else.
+    Changing the selection has to repaint all of them.
+
+    WHY THE TEMPLATES RIDE ON THE ROW
+    Each row carries its own header / fallback / subject templates as data
+    attributes, and this reads them from the DOM. The alternative was a second
+    JSON payload listing every email, which would have to be kept in step with
+    the rows themselves — and a row whose payload entry went missing would
+    silently stop repainting while still looking correct for whoever was selected
+    at page load.
+
+    The placeholder rule is the same one Studio::Banner applies server-side, and
+    the same one the detail page's editor applies. It is small, and it is pinned
+    on both sides. If they disagree, the server is right. %>
+<script>
+  (function () {
+    function recipients(config) {
+      return {
+        targets: config.targets || [],
+        targetId: config.targetId,
+        pickerOpen: false,
+
+        init() {
+          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] || "";
+        },
+
+        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;
+        },
+
+        // A subject has no second field for the nameless case, so an unresolved
+        // placeholder is removed along with the punctuation holding it — the
+        // same two passes Studio::Banner.interpolate makes, so "Sign in, {name}"
+        // reads "Sign in" here exactly as it would in an inbox.
+        resolveSubject(template) {
+          var app = config.appName || "";
+          var text = (template || "").replace(/\{app\}/g, app);
+          var first = this.firstName();
+          if (first) return text.replace(/\{name\}/g, first);
+          return text.replace(/[,;:—-]?\s*\{name\}/g, "")
+                     .replace(/^\s*[,;:—-]\s*/, "")
+                     .replace(/\s+/g, " ")
+                     .trim();
+        },
+
+        // A row's banner lives in an IFRAME — the email's table is its own
+        // document so it cannot nest rows inside the list. Same-origin srcdoc,
+        // so its nodes are reachable; contentDocument is null until the frame
+        // has parsed, which is why the load listener is wired as well as the
+        // immediate attempt.
+        bannerNode(row, selector) {
+          var frame = row.querySelector("iframe[data-email-banner-preview]");
+          if (frame) {
+            try { return frame.contentDocument && frame.contentDocument.querySelector(selector); }
+            catch (_) { return null; }
+          }
+          return row.querySelector(selector);
+        },
+
+        paintRow(row) {
+          var header = this.bannerNode(row, "[data-banner-header]");
+          var subject = row.querySelector("[data-row-subject]");
+          if (header) {
+            header.textContent = this.resolve(row.dataset.header, row.dataset.headerFallback);
+          }
+          if (subject) subject.textContent = this.resolveSubject(row.dataset.subject);
+        },
+
+        paint() {
+          var self = this;
+          this.$root.querySelectorAll("[data-email-row]").forEach(function (row) {
+            self.paintRow(row);
+            var frame = row.querySelector("iframe[data-email-banner-preview]");
+            if (frame && !frame.dataset.repaintBound) {
+              frame.dataset.repaintBound = "1";
+              frame.addEventListener("load", function () { self.paintRow(row); });
+            }
+          });
+        },
+
+        // Anything interactive keeps its own behaviour; everything else opens
+        // the email. Without the closest() guard, clicking Upload would both
+        // open the cropper and navigate away from it.
+        openRow(event, row) {
+          // The listener sits on the tbody, so a click can land between rows and
+          // arrive with no row at all.
+          if (!row) return;
+          if (event.target.closest("a, button, input, label, form")) return;
+          var path = row.dataset.emailPath;
+          if (path) window.location = path;
+        }
+      };
+    }
+
+    window.emailRecipients = recipients;
+    if (typeof Alpine !== "undefined") {
+      Alpine.data("emailRecipients", recipients);
+    } else {
+      document.addEventListener("alpine:init", function () {
+        Alpine.data("emailRecipients", recipients);
+      });
+    }
+  })();
+</script>