studio-engine 0.41.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4b5672c89f5dc5feeaf54432eed9992c022a69992c1ff58311b0b85a58a23e9
-  data.tar.gz: 3a3489c4d4f8174d0d5facbf53f020505392f78e51f13a96a4c8f95367224608
+  metadata.gz: d675146488bc53f26f2ab9df774878f26b8c6fe714f8298fda17fbf85b3632de
+  data.tar.gz: afb41c11138b07903925c87abe6bab93d82476db7789226b79b2b38872f0ab2a
 SHA512:
-  metadata.gz: e1d83d1b55f15fb4ecaa74a261b5db8c6cc874ca93166e4323814295caf16724b3bfd65dcda07c27918024ea5db9967e09fe63e0777d48c74c7b8f9c9b21d4ff
-  data.tar.gz: 64d9556f766654a143e966d7b8f784c27773acfcf3bd35065f2cc9c24284a2113ab659dfe937ca090ff1030a0225d0ae0780e0e2f509fc6fc8868811d7e65dad
+  metadata.gz: f209b273cfacd2d9f428f43cc886b15e57ff7b1131a6753589d8ddcd17b07c9458c678ae1583e4826038a8d3cd2004757f460695952f60367677fbac7c44fc73
+  data.tar.gz: 5aa5fe2bf6fa67cfdf30aa6fdfe253f34f6c29715aa42ef56c95d892d61706d049c6b6f137908db54d6d8fda72ebb7e16e7b66e4c2705fc0286cbbcabbdcb9f8

data/CHANGELOG.md

@@ -4,6 +4,103 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Changed
+
+- **`email_change_confirmation` leaves the pre-registered set; `newsletter_subscribed`
+  joins it.** `STANDARD` means "the emails EVERY Studio app sends", and only
+  turf-monster sends an email-change confirmation — which it **already registers
+  itself**, with its own artwork, in `config/initializers/studio_emails.rb`. No
+  host loses a banner, and no host action is required for the removal.
+
+  What DOES break consumers is the ADDITION. Three suites assert against the
+  whole shared catalogue, so a new standard email fails them:
+
+  | Consumer | Assertion | Fix | State |
+  |---|---|---|---|
+  | turf-monster | `EmailRegistrationTest` compares the full key list | McRitchie-Studio/turf-monster#292 | merged |
+  | turf-monster | `AdminEmailsRenderTest` counts `tbody img` exactly | McRitchie-Studio/turf-monster#294 | merged |
+  | mcritchie-studio | `StudioEmailsPageTest` pins the registry list, an `email_change_confirmation` link, and the upload-rejection wording | McRitchie-Studio/mcritchie-studio#813 | merged |
+
+  The second turf fix is the easy one to miss: a layered standard email renders
+  its banner through an `<iframe>` rather than an `<img>`, so an exact image
+  count comes up one short. #292 alone does NOT turn that lane green.
+
+  Consumer CI builds each app against its **default branch**, so all three had to
+  reach `main` before this engine's consumer lanes could go green. All three now
+  have, and the lanes pass. Nothing on this branch ever could have turned them
+  green — a red consumer lane here is a consumer-side fix, not an engine defect.
+
+  The artwork `emails/email-change-confirmation.gif` still ships, so a host that
+  wants the entry can register it.
+
+### Added
+
+- **`Studio::NewsletterMailer` — a sendable "you're on the list" email.**
+  Namespaced under `Studio::` on purpose: a host that defines its own top-level
+  `UserMailer` (McRitchie Studio does) SHADOWS the engine's outright, so an
+  action added there would reach only the apps that never customised their mail.
+  Layered-native — animated background with the greeting as live HTML on top,
+  and no flat `default_asset`, because a baked-in copy of the same picture is a
+  second thing to keep in sync and would never be shown. `unsubscribe_url:` is
+  optional and the line renders only when a host wires a real one.
+
+- **The banner's WORDS are operator-editable on /admin/emails.** Header,
+  a name-free fallback header, sub-text, subject, logo and tint, saved per app in
+  a new `studio_email_settings` row and resolved operator > registry > default.
+  `{name}` and `{app}` are filled per recipient — so the mailer now supplies WHO
+  the recipient is (`Studio::Banner.for(key, name:)`) and the operator supplies
+  what the banner says about them. A mailer that hands over a finished header
+  takes the wording away from the operator: the field still accepts the edit and
+  the email still ignores it, which is a control that lies.
+
+  An unresolved `{name}` never reaches an inbox. The header falls back to its
+  name-free variant; a subject, which has no second field, drops the token along
+  with the punctuation holding it — "Sign in to {app}, {name}" sends as
+  "Sign in to Studio" to someone with no name on file.
+
+- **The email manager previews what actually SHIPS.** Each email renders the
+  real layered banner through the mailer's own partial (not a re-creation of it),
+  repaints as the operator types, and offers an example recipient — an admin, who
+  usually has a full name on file, and a member, who often has none. The nameless
+  case is the one the fallback header exists for and the one nobody thinks to
+  check. Preview hooks are opt-in (`preview: true`); with them off the email
+  markup is byte-identical, asserted by test.
+
+  What makes that true rather than aspirational: the engine's own
+  `UserMailer#magic_link` ADOPTS the layered banner (`Studio::Banner.for`), and
+  /admin/emails builds its preview from the same call — one expression, so the
+  two cannot disagree. Before this, the manager drew a layered banner with live
+  "Welcome Alex!" text for a sign-in email that shipped flat artwork with the
+  words baked in: a preview showing something no recipient receives. A test
+  renders the mailer and the manager for the same key and compares the artwork
+  and the layered-ness, so the two are held together rather than trusted to
+  match. An app that registers no layered artwork still sends the plain `<img>`
+  — layered is opt-in, never a migration.
+
+- **Animated GIF banners upload without losing their animation.** The cropper
+  paints onto a canvas and calls `toBlob(..., "image/png")`, which keeps frame one
+  and discards the rest — silently, leaving a good-looking still. `allowGifs: true`
+  routes a GIF around the cropper and stores the original bytes under a `.gif`
+  key.
+
+- **`Studio::EmailPreviewTarget`** — who an email is previewed as, read from the
+  host's own users with avatar and initials, degrading to a sample when an app has
+  none.
+
+### Fixed
+
+- **The manager reported artwork that was not being sent.** A layered-native email
+  (no flat `default_asset`) drew an empty box and a "sends without a banner" badge
+  while it was sending one, and an email with BOTH assets previewed the flat one —
+  a picture with the words baked in that a layered mailer never sends. The page
+  and the `<img>` fallback now resolve in opposite orders, each documented, because
+  they answer different questions.
+
+- **A doc comment leaked onto the page.** An ERB tag inside an ERB comment closes
+  it at its own delimiter; the rest of the sentence rendered above the banner. The
+  existing guard was real and only ran on the index, so it never saw the page that
+  shipped it.
+
 ### Added
 
 - **A browser lane — the engine now runs Playwright against its own partials.**

data/README.md

@@ -361,7 +361,7 @@ declaring anything:
 | Key | Label |
 |-----|-------|
 | `magic_link` | Magic-link sign-in |
-| `email_change_confirmation` | Email change confirmation |
+| `newsletter_subscribed` | Newsletter subscribed |
 
 A host adds its own workflows from an initializer, mirroring
 `Studio::ModelPage.register`:
@@ -387,6 +387,60 @@ than raising.
 > `Studio::EmailImage` is the old name for this module and still works as a
 > delegating shim. It is deprecated; prefer `Studio::EmailCatalog`.
 
+### Layered banners — a background image with live text on it
+
+An email's banner can be a picture with the header, sub-text and logo rendered
+as HTML **on top**, rather than drawn into the image:
+
+```ruby
+def magic_link(email, token)
+  # The mailer supplies WHO the recipient is. What the banner SAYS about them —
+  # the greeting, the sub-text, whether the name is used at all — belongs to the
+  # operator, editable on /admin/emails. Pass a finished `header:` here and those
+  # fields still accept edits no inbox ever sees.
+  @banner = Studio::Banner.for(:magic_link, name: recipient_name(email))
+  # ...
+end
+```
+
+`layouts/branded_mailer` renders it. The engine's own `UserMailer#magic_link`
+does exactly the above, and /admin/emails builds its preview from the same
+`Studio::Banner.for` call — so preview and send cannot disagree.
+
+A mailer that sets `@banner_url` instead still renders a plain `<img>` exactly
+as before, and `Studio::Banner.for` returns `nil` when the app has registered no
+layered artwork, so the flat path is what an unadopted app keeps getting —
+layered is opt-in, never a migration.
+
+Register the artwork once and every app inherits it:
+
+```ruby
+Studio::EmailCatalog.register("magic_link",
+  background: "emails/magic-link-background.gif",
+  logo: "emails/logo-horizontal.png",
+  scrim: 0.40)
+```
+
+**Why layered rather than composited.** Drawing the text into the image gives
+pixel-exact brand typography everywhere, but it cannot have an ANIMATED
+background AND per-recipient text — composing a greeting into sixty frames means
+a multi-megabyte GIF per recipient, per send. Layering separates them.
+
+**What it costs.** Gmail and Outlook strip webfonts, so the heading falls back to
+a system face rather than the brand font. In exchange the text survives blocked
+images (Outlook desktop blocks by default), stays selectable, and nothing is
+generated at send time.
+
+**The scrim** is a wash between artwork and type, on by default at 0.40.
+Background art is chosen to look good, not to guarantee contrast, and white text
+over a pale sky cannot be read. Pass `scrim: 0` for artwork dark enough to carry
+the type itself.
+
+**The markup is deliberately old-fashioned.** Outlook on Windows renders through
+Word and ignores `background-image`, so the picture is carried by the `<td
+background>` attribute, by CSS, and by a VML block inside an `mso` conditional.
+Remove any one of the three and a client loses the banner.
+
 ### Live preview
 
 `preview:` is any callable returning a `Mail`. It powers `/admin/emails/:key`,

data/app/controllers/studio/emails_controller.rb

@@ -15,23 +15,48 @@ module Studio
   # is currently sending.
   class EmailsController < ApplicationController
     before_action :require_admin
-    before_action :load_entry, only: %i[show raw update destroy]
-    before_action :require_uploads, only: %i[update destroy]
+    before_action :load_entry, only: %i[show raw update destroy settings copy logo]
+    before_action :require_uploads, only: %i[update destroy logo]
 
     MAX_BYTES = 8.megabytes
 
     def index
       @entries = Studio::EmailCatalog.entries
       @uploads_available = Studio::EmailCatalog.uploads_available?
+
+      # The list renders every banner and subject AS THEY WOULD ARRIVE, which has
+      # no answer until someone is receiving them.
+      @targets = Studio::EmailPreviewTarget.all
+      @target = Studio::EmailPreviewTarget.resolve(params[:target])
+      @preview_name = @target&.name
     end
 
     # GET /admin/emails/:key — one email: its banner, its type, and a live
     # preview built from the host's sample data.
     def show
+      # nil for an ORPHAN — an email that left the registry while this app still
+      # holds an upload for it. The view renders a minimal page whose only real
+      # affordance is Revert, which is the whole reason the route stays open.
       @entry = Studio::EmailCatalog.entry(@key)
+      @orphan = @entry.nil?
+      return render(:orphan) if @orphan
+
       @subject = Studio::EmailCatalog.preview_subject(@key)
       @preview_error = Studio::EmailCatalog.preview_error(@key)
       @uploads_available = Studio::EmailCatalog.uploads_available?
+
+      # WHO this is previewed as. The banner greets by name, so "what does this
+      # email look like" has no answer until someone is receiving it — and the
+      # two people who break email differently (an admin with a full name on
+      # file, a member with none) are both offered.
+      @targets = Studio::EmailPreviewTarget.all
+      @target = Studio::EmailPreviewTarget.resolve(params[:target])
+      @preview_name = @target&.name
+
+      # The banner AS IT ARRIVES, built the same way a mailer builds it so the
+      # page cannot show something the inbox never gets.
+      @banner = Studio::Banner.for(@key, name: @preview_name)
+      @subject = Studio::EmailCatalog.subject_for(@key, name: @preview_name) || @subject
     end
 
     # GET /admin/emails/:key/raw — the rendered email itself, as the iframe
@@ -52,7 +77,7 @@ module Studio
     def update
       file = params[:image]
       unless valid_image?(file)
-        message = file.blank? ? "Choose an image to upload." : "Use a PNG, JPG, or WebP under 8 MB."
+        message = file.blank? ? "Choose an image to upload." : "Use a PNG, JPG, WebP or GIF under 8 MB."
         return redirect_to admin_emails_path, alert: message, status: :see_other
       end
 
@@ -64,6 +89,81 @@ module Studio
       redirect_to admin_emails_path, alert: "Couldn't save the image. Please try again.", status: :see_other
     end
 
+    # PATCH /admin/emails/:key/settings — operator-tunable knobs.
+    #
+    # The scrim is the dial between a readable header and a visible picture, and
+    # the right value depends on artwork that changes without a deploy. Blank
+    # clears the override so the email falls back to the registry default rather
+    # than being pinned to whatever that default was on the day.
+    def settings
+      percent = params[:scrim_percent]
+
+      if percent.present? && !Studio::EmailSetting::SCRIM_RANGE.cover?(percent.to_i)
+        return redirect_to admin_email_path(@key), status: :see_other,
+                           alert: "Tint must be between 0 and 100."
+      end
+
+      rescue_and_log do
+        Studio::EmailSetting.set_scrim(@key, percent)
+        redirect_to admin_email_path(@key), status: :see_other,
+                    notice: percent.present? ? "Tint set to #{percent.to_i}%." : "Tint reset to the default."
+      end
+    rescue StandardError
+      redirect_to admin_email_path(@key), status: :see_other,
+                  alert: "Couldn't save the tint. Please try again."
+    end
+
+    # PATCH /admin/emails/:key/copy — the banner's words and logo.
+    #
+    # Separate from #settings rather than one big form: the tint is a slider you
+    # nudge while looking at the picture, the copy is a sentence you write. They
+    # save independently so tuning one never risks clobbering an unsaved edit to
+    # the other.
+    # Saves EVERYTHING the page edits, in one write. The page has a single Save
+    # button, so it must: three buttons that each saved a third of the form meant
+    # an operator who changed the subject and the tint had to notice there were
+    # two places to press.
+    def copy
+      rescue_and_log do
+        Studio::EmailSetting.set_copy(@key, copy_params)
+        if params.key?(:scrim_percent)
+          percent = params[:scrim_percent]
+          percent = nil unless percent.present? && Studio::EmailSetting::SCRIM_RANGE.cover?(percent.to_i)
+          Studio::EmailSetting.set_scrim(@key, percent)
+        end
+        redirect_to admin_email_path(@key), status: :see_other, notice: "Saved."
+      end
+    rescue StandardError
+      redirect_to admin_email_path(@key), status: :see_other,
+                  alert: "Couldn't save the banner text. Please try again."
+    end
+
+    # PATCH /admin/emails/:key/logo — upload a logo for THIS email, or drop it.
+    #
+    # Its own action and its own ImageCache purpose: a logo is a small transparent
+    # mark, a banner is 3:1 artwork that may be animated, and reverting one must
+    # not touch the other.
+    def logo
+      if params[:remove].present?
+        rescue_and_log { Studio::EmailCatalog.revert_logo(@key) }
+        return redirect_to admin_email_path(@key), status: :see_other,
+                           notice: "Back to the standard logo."
+      end
+
+      file = params[:image]
+      unless valid_image?(file)
+        message = file.blank? ? "Choose an image to upload." : "Use a PNG, JPG, WebP or GIF under 8 MB."
+        return redirect_to admin_email_path(@key), alert: message, status: :see_other
+      end
+
+      rescue_and_log do
+        Studio::EmailCatalog.store_logo(@key, io: file, content_type: file.content_type)
+        redirect_to admin_email_path(@key), notice: "Logo updated.", status: :see_other
+      end
+    rescue StandardError
+      redirect_to admin_email_path(@key), alert: "Couldn't save the logo. Please try again.", status: :see_other
+    end
+
     # DELETE /admin/emails/:key — drop this app's override and fall back to the
     # inherited default.
     def destroy
@@ -74,10 +174,13 @@ module Studio
       # ErrorLog to say why.
       rescue_and_log do
         reverted = Studio::EmailCatalog.revert(@key)
+        # label() falls back to the humanised key, so an ORPHAN (no registry
+        # entry at all) still gets a readable message rather than a blank one.
+        label = Studio::EmailCatalog.label(@key).presence || @key.humanize
         notice = if reverted
-                   "#{Studio::EmailCatalog.label(@key)} reverted to the inherited default."
+                   "#{label} reverted to the inherited default."
                  else
-                   "#{Studio::EmailCatalog.label(@key)} was already using the inherited default."
+                   "#{label} was already using the inherited default."
                  end
         redirect_to admin_emails_path, notice: notice, status: :see_other
       end
@@ -87,9 +190,36 @@ module Studio
 
     private
 
+    # COPY_FIELDS plus :hide_logo, and the awkward shape is the honest one.
+    #
+    # This list was DERIVED from COPY_FIELDS precisely because a hand-typed one
+    # dropped :subject — the form posted it, strong params filtered it out, and
+    # the page still said "Saved." Deriving it then reintroduced exactly that bug
+    # for the one editable column that is NOT a copy field: hide_logo is a
+    # boolean rather than text, so it lives outside COPY_FIELDS and vanished from
+    # the permit list. Hiding the logo saved nothing and reported success.
+    #
+    # Every model-level logo test passed throughout, because set_copy was never
+    # the broken part. The filter lives here, so the assertion does too.
+    def copy_params
+      params.permit(*Studio::EmailSetting::COPY_FIELDS, :hide_logo)
+            .to_h.symbolize_keys
+    end
+
+    # A key is reachable when it is REGISTERED, or when this app still holds an
+    # upload for it.
+    #
+    # The second half matters because the standard set can change. An email that
+    # leaves it takes its page with it — and a host that had uploaded its own
+    # artwork was left with a live ImageCache row, a paid-for S3 object, and a
+    # 404 on the only page that could delete either. Keeping the page reachable
+    # for an orphan is what gives that operator a revert button.
     def load_entry
       @key = params[:key].to_s
-      head :not_found unless Studio::EmailCatalog.known?(@key)
+      return if Studio::EmailCatalog.known?(@key)
+      return if Studio::EmailCatalog.record(@key).present?
+
+      head :not_found
     end
 
     def require_uploads

data/app/mailers/studio/newsletter_mailer.rb

@@ -0,0 +1,43 @@
+module Studio
+  # The "you're on the list" email.
+  #
+  # NAMESPACED, unlike the engine's UserMailer, and that is the whole point. A
+  # host that defines its own top-level `UserMailer` (McRitchie Studio does)
+  # SHADOWS the engine's outright — Zeitwerk resolves the constant to the host's
+  # file and the engine's actions simply do not exist there. Putting this under
+  # Studio:: means every app inherits a sendable newsletter email on day one,
+  # and a host that wants different copy overrides the VIEW rather than losing
+  # the action.
+  class NewsletterMailer < ApplicationMailer
+    # Branded shell — banner + card. The layout renders @banner layered (artwork
+    # with live text on top) and falls back to the flat @banner_url <img>.
+    layout "branded_mailer"
+
+    # `email` is a raw string: someone can join a mailing list without ever
+    # holding an account, so this must not require a User.
+    #
+    # unsubscribe_url is OPTIONAL and the line renders only when it is given.
+    # A newsletter needs a way out, but a hard-coded dead link is worse than an
+    # honest omission — a host wires its real one and the line appears.
+    def subscribed(email, name: nil, unsubscribe_url: nil)
+      @app_name        = Studio.app_name
+      @email           = email
+      @name            = name.presence
+      @unsubscribe_url = unsubscribe_url.presence
+
+      # The mailer passes WHO, not WHAT THE BANNER SAYS. The wording — including
+      # whether it greets by name at all — is the operator's, editable on
+      # /admin/emails. Handing over a finished header here would make that field
+      # accept edits and change nothing.
+      @banner = Studio::Banner.for(:newsletter_subscribed, name: @name)
+      @banner_alt = "#{@banner&.header} — #{@app_name}"
+      # The floor, exactly as UserMailer does it: if no layered artwork is
+      # registered the layout renders the flat <img> instead of nothing.
+      @banner_url = Studio::EmailCatalog.resolved_url(:newsletter_subscribed)
+
+      subject = Studio::EmailCatalog.subject_for(:newsletter_subscribed, name: @name) ||
+                "You're subscribed to #{@app_name}"
+      mail(to: email, subject: subject)
+    end
+  end
+end

data/app/mailers/user_mailer.rb

@@ -21,11 +21,58 @@ class UserMailer < ApplicationMailer
     @app_name   = Studio.app_name
     @email      = email
     @magic_url  = magic_link_url_for(token)
+    # ONE lookup, two consumers. recipient_name queries the host's users table,
+    # and the banner and the subject want the same answer — asking twice on a
+    # delivery path buys nothing and risks the two disagreeing.
+    name        = recipient_name(email)
+    # THE LAYERED BANNER, when this app has layered artwork for the email.
+    #
+    # The mailer supplies only WHO the recipient is. What the banner SAYS about
+    # them — the greeting, the sub-text, whether the name is used at all — is
+    # the operator's, editable on /admin/emails. Handing over a finished header
+    # here would leave those fields accepting edits no inbox ever sees.
+    #
+    # Why this assignment exists at all: /admin/emails draws its preview from
+    # this same Studio::Banner.for call, so a mailer that set only @banner_url
+    # made the manager show a layered banner with live text for an email that
+    # shipped flat baked-in artwork. Preview and send now resolve through one
+    # expression and cannot disagree.
+    #
+    # nil when the app registers no background (or owns the artwork itself), and
+    # the layout falls through to the flat <img> below.
+    @banner     = Studio::Banner.for(:magic_link, name: name)
     # 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.
+    #
+    # KEPT AS THE FLOOR. @banner above wins when it is present; this is what an
+    # app with no layered artwork registered still sends, exactly as before.
+    # Layered is opt-in, never a migration.
     @banner_url = Studio::EmailCatalog.resolved_url(:magic_link)
     @banner_alt = "Your #{@app_name} sign-in link"
-    mail(to: email, subject: "Your #{@app_name} sign-in link")
+    # The operator's subject when they have set one, the hard-coded line
+    # otherwise — so an app that never visits /admin/emails is unchanged.
+    subject = Studio::EmailCatalog.subject_for(:magic_link, name: name) ||
+              "Your #{@app_name} sign-in link"
+    mail(to: email, subject: subject)
+  end
+
+  private
+
+  # The recipient's name when this app holds an account for them. Defensive about
+  # the whole chain — a host may have no User model, no display_name, or no row —
+  # because a subject line must never be the reason a send raises.
+  def recipient_name(email)
+    model = "User".safe_constantize
+    return nil unless model.respond_to?(:find_by)
+
+    record = model.find_by(email: email.to_s.strip.downcase)
+    %i[display_name name full_name].each do |method|
+      value = record.try(method)
+      return value if value.present?
+    end
+    nil
+  rescue StandardError
+    nil
   end
 end

data/app/models/studio/email_setting.rb

@@ -0,0 +1,131 @@
+module Studio
+  # An operator's per-email overrides, editable from /admin/emails.
+  #
+  # The registry (code) supplies defaults; a row here overrides them for THIS
+  # app. That split matters: the scrim is the dial between a readable header and
+  # a visible picture, and the right value depends on artwork that changes
+  # without a deploy — so it has to be tunable by the person looking at it.
+  #
+  # Nil-safe throughout, because the table is installed by a migration the host
+  # runs. An app that has not run it yet must still send email.
+  class EmailSetting < ApplicationRecord
+    self.table_name = "studio_email_settings"
+
+    SCRIM_RANGE = (0..100).freeze
+
+    validates :email_key, presence: true, uniqueness: true
+    validates :scrim_percent, numericality: { only_integer: true,
+                                              greater_than_or_equal_to: SCRIM_RANGE.min,
+                                              less_than_or_equal_to: SCRIM_RANGE.max },
+                              allow_nil: true
+
+    # The banner's words and logo. Each is nil until the operator sets it, and
+    # nil means INHERIT — never "empty".
+    COPY_FIELDS = %i[header header_fallback subtext logo_url subject].freeze
+
+    class << self
+      # The saved scrim for this email as a 0.0-1.0 fraction, or nil when the
+      # operator has not set one (the registry default then applies).
+      def scrim_for(key)
+        return nil unless table_ready?
+
+        percent = for_key(key)&.scrim_percent
+        percent.nil? ? nil : percent / 100.0
+      end
+
+      # One saved copy field, or nil to inherit. Blank is stored as nil by
+      # #set_copy, so a blank return here always means "not set".
+      def copy_for(key, field)
+        return nil unless table_ready?
+        return nil unless COPY_FIELDS.include?(field.to_sym)
+
+        for_key(key)&.public_send(field).presence
+      end
+
+      # The row for this email, memoised PER REQUEST.
+      #
+      # Building one banner asks for the header, the fallback, the sub-text, the
+      # logo, the subject, the scrim and hide_logo — seven find_by calls for one
+      # row, on the mail DELIVERY path, and multiplied by every row on
+      # /admin/emails. The cache is request-scoped rather than a class variable
+      # so a write in one request cannot be served to the next.
+      # IsolatedExecutionState, not Thread.current: Puma reuses threads, so a
+      # thread-local outlives the request that filled it and the next request
+      # served by that thread would get the previous one's row. Rails resets
+      # IsolatedExecutionState around every request and job.
+      def for_key(key)
+        cache = ActiveSupport::IsolatedExecutionState[:studio_email_settings] ||= {}
+        return cache[key.to_s] if cache.key?(key.to_s)
+
+        cache[key.to_s] = find_by(email_key: key.to_s)
+      end
+
+      # Called after any write, because a memoised row that outlives its update
+      # serves the operator their old copy back and looks like the save failed.
+      def forget!(key = nil)
+        cache = ActiveSupport::IsolatedExecutionState[:studio_email_settings]
+        return if cache.nil?
+
+        key.nil? ? cache.clear : cache.delete(key.to_s)
+      end
+
+      # True when the operator has explicitly hidden the logo — which is a
+      # different answer from "no logo url saved" (that one inherits).
+      def hide_logo?(key)
+        return false unless table_ready?
+
+        for_key(key)&.hide_logo || false
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      # Save the words. A blank field is stored as NULL rather than "", so
+      # clearing a box means "go back to the registry default" — the same
+      # gesture that resets the tint.
+      def set_copy(key, attrs)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: key.to_s)
+        COPY_FIELDS.each do |field|
+          next unless attrs.key?(field) || attrs.key?(field.to_s)
+
+          record.public_send(:"#{field}=", (attrs[field] || attrs[field.to_s]).presence)
+        end
+        # ONLY when the form carried it. Two separate cards post to this method,
+        # and an absent checkbox means "this form does not manage the logo", not
+        # "show the logo" — writing false either way let saving the subject
+        # silently un-hide a logo the operator had hidden.
+        if attrs.key?(:hide_logo) || attrs.key?("hide_logo")
+          record.hide_logo = ActiveModel::Type::Boolean.new.cast(attrs[:hide_logo] || attrs["hide_logo"]) || false
+        end
+        record.save!
+        # Drop the memo, or the operator is shown the value they just replaced —
+        # the same "saved successfully, changed nothing" shape the permit bug had.
+        forget!(key)
+        record
+      end
+
+      # Store a percent, or clear the override with nil/blank so the email falls
+      # back to the registry default rather than being pinned to whatever the
+      # default happened to be on the day.
+      def set_scrim(key, percent)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: key.to_s)
+        record.scrim_percent = percent.presence&.to_i
+        record.save!
+        forget!(key)
+        record
+      end
+
+      # Reference the constant directly so Zeitwerk autoloads it — defined?()
+      # does NOT trigger autoload, so it reads "undefined" for a not-yet-loaded
+      # const and would silently disable every setting.
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+    end
+  end
+end