studio-engine 0.36.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c692fc135af1ba83c08b27398c875bc547ae07bbcc492540ffd83250fccf680
-  data.tar.gz: 891c561fe2bef1386137af4fbbc22547f38613efe8bd373bf6ec31894086feef
+  metadata.gz: d497957db77f7b61823d1d12422672bf4339d71381163b79a6c42d705abf3492
+  data.tar.gz: e31717daca9b7722e4b9e87d44a507d9ec8c8055421e192bb3de78aa31175542
 SHA512:
-  metadata.gz: 9cb8bb03d5adeec99336b5fab4d28b29c57be8686ca2afef58932ce866c321fe44f6ab0123609e6845151f938ab28790685bda6b9b21815ef3a3594d6c589921
-  data.tar.gz: 2c3be4aadf2a88d7838dab26b27c4a22604268138bba818f0b82890774f7bc5b81424d53a645d3fcc5ebf59a8f10197a9b37bd9cd44246c988d8dca3dfd2cd62
+  metadata.gz: 6f75c493e66ebae0fd31571d237fa6a4f1546e9c50143382a4f54bfe88d5614c1f582af6d758cafe93ffc47b744b01d875a280de92823012bf224f028859627d
+  data.tar.gz: dfa14e14dbe5796816a0247bd965da477b69e27e8c81750f554e1d2d497fbf486da5d14f1ae900aa26b28dcfe22c14a51f2e83ead2089d98f9667b0142d43b6d

data/CHANGELOG.md

@@ -2,8 +2,218 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## Unreleased
+
+**The email registry becomes the email catalog.** 0.37 gave every app a shared
+page for its transactional email banners. This folds in the rest — **what each
+email is, and what it actually looks like** — so an app has ONE email manager
+instead of two.
+
+**`Studio::EmailImage` is now `Studio::EmailCatalog`.** The old name is a
+**delegating shim** with its full surface intact (`url`, `store`, `record`,
+`register`, `label`, `known?`, `variants`, `resolved_url`, `preview_url`,
+`source`, and the constants), so nothing that names it breaks. It is deprecated
+and will be deleted once no consumer's `main` references it.
+
+Named for the prior art it absorbs: `turf-monster` built `::EmailCatalog` +
+`Admin::EmailsController` first, and left a note on both saying this manager
+*"moves into the shared studio-engine email framework (Phase 2)"*. This is
+Phase 2. turf-monster deletes its copy in its adoption task rather than running a
+second email page.
+
+**Registry entries carry a type and a preview builder:**
+
+```ruby
+Studio::EmailCatalog.register("winnings",
+  label: "Contest winnings",
+  description: "Sent when a player wins a contest.",
+  type: :marketing,                                   # or :transactional (default)
+  preview: -> { ContestMailer.winnings(sample_entry) })
+```
+
+Every keyword is optional, and omitting one on a re-register **keeps** the
+existing value — so a host can attach a preview to an inherited email, or
+relabel it, without restating its artwork. An unknown `type` falls back to
+`:transactional` rather than raising: a typo in an initializer must not take a
+host's boot down over a badge.
+
+**New: `/admin/emails/:key`** — one email's own page: its banner, its type, its
+subject, and a **live preview** of the real rendered email in an iframe
+(`/admin/emails/:key/raw`). The emails list links each row to it.
+
+**A preview can never take the manager down.** A `preview:` builder is host code
+run against whatever sample data an environment happens to hold — an empty table,
+a moved fixture, a mailer whose signature changed. Every call is contained: a
+raising builder yields `nil`, records why, and renders the reason inside the
+iframe. One broken builder costs one preview, not the page. Builders run **only**
+on that page — listing the emails never executes one.
+
+**Consumer note.** Nothing is required to upgrade; the shim keeps 0.37 call sites
+working. To adopt the preview: pass `preview:` when registering, and switch any
+`Studio::EmailImage` reference to `Studio::EmailCatalog`.
+
+### Added
+
+- **`Studio::EmailCatalog`** — the email registry, renamed from
+  `Studio::EmailImage` and now carrying each entry's `type:` and `preview:`
+  callable. The old name stays as a delegating shim.
+- **`/admin/emails/:key`** — one email's own page: its banner, its type, its
+  subject, and a live preview of the real rendered email in an iframe.
+
+## 0.37.0 — 2026-08-10
+
+### Added
+- Standard transactional email primitive with a registry-backed catalog.
+
+### Fixed
+- The crop confirm is guarded by owner, so one confirmed crop can no longer fan out
+  and overwrite every row's banner on /admin/emails.
+
 ## 0.36.0 — 2026-08-10
 
+**Transactional emails become an engine primitive.** Every consuming app now
+ships working, branded transactional email the moment it boots, and can grow its
+own workflows and artwork. Additive — no host change is required to take this
+release.
+
+**`Studio::EmailImage` is now a registry.** It was a one-entry `VARIANTS` hash;
+it is now a host-declared registry following the `Studio::ModelPage.register`
+precedent. A registered email is mostly symbolic of a workflow — a key, a label,
+a description — and its only real asset is its banner image.
+
+- The engine **pre-registers the two every Studio app sends**, `magic_link` and
+  `email_change_confirmation`, so a host inherits both without declaring
+  anything.
+- A host registers its own from an initializer:
+  `Studio::EmailImage.register("winnings", label: "Contest winnings")`.
+  Re-registering an inherited key **updates it in place**, keeping its page
+  position and its inherited artwork.
+- `variants`, `label`, `known?`, `record`, `url`, and `store` keep their old
+  shapes, so `Studio::EmailImage.url(:magic_link)` — the only external caller
+  today — is untouched.
+
+**Inheritance with per-app override.** Resolution is now two-layered:
+
+```
+resolved_url(:magic_link)  ->  this app's ImageCache row (its own S3 bucket)  app-owned
+                           ->  the engine's default gem asset                 inherited
+                           ->  nil                                            bannerless
+```
+
+`resolved_url`, **not** `url`. `url` deliberately keeps its pre-registry meaning —
+this app's own image, or nil — so a caller written before the registry keeps the
+behavior it was built against. A mailer that falls back itself
+(`url(...) || own_banner`) must stay on `url`; switching it to `resolved_url`
+would make that fallback dead code and replace the app's own artwork with the
+engine default.
+
+Defaults **ride the gem** (`app/assets/images/emails/*`), so a brand-new app with
+an empty bucket sends good-looking email on day one with no cross-app S3
+permission. Uploading writes to that app's own bucket and its own `image_caches`
+row — which is exactly "the asset now belongs to this app". Placeholder artwork
+ships for both standard emails; real artwork lands in a later release.
+
+**New: `/admin/emails`**, modelled on the living style guide — one shared engine
+page, admin-gated, rendering inside each host's layout.
+
+**It is OPT-IN, and must be.** Add to `config/initializers/studio.rb`:
+
+```ruby
+config.draw_admin_emails_routes = true
+```
+
+`turf-monster` already owns `/admin/emails` (its `EmailCatalog` manager:
+`namespace :admin { get "emails", as: :emails }`) and therefore both helper
+names, `admin_emails_path` and `admin_email_path`. Drawing the engine's page
+unconditionally raises `ArgumentError: Invalid route name, already in use:
+'admin_emails'` *while turf-monster's own routes are loading*, which takes down
+its **entire** route set — every `admin_*_path` in the app goes undefined. A host
+cannot opt out of a failure that happens before its config is read, so the
+default is off until no consumer owns the name.
+
+The gate covers only the **page**. The registry and the inherited-default
+resolution are always on, and the engine's `UserMailer` already calls
+`resolved_url`, so an app sends branded email whether or not it draws the page.
+
+**`/admin/email_images` is deprecated, not deleted.** It still renders, and its
+`admin_email_images_path` / `admin_email_image_path` helpers still resolve —
+`mcritchie-studio` and `turf-monster` both have tests on `main` that drive it,
+and consumer CI runs each consumer's default branch. A later engine minor deletes
+the controller, view, and routes once no consumer references them. In the
+meantime the old page had its own reporting bug fixed too: it now reads
+`preview_url`, so it no longer claims "No image yet" about an email that is
+visibly sending one.
+
+- The table is the primary view: **name + live image on every row**, so an email
+  is identifiable at a glance.
+- Each row says whether the live image is the **inherited default** or
+  **app-owned**, and an app-owned image can be reverted back to the default.
+- Uploading goes through the **standard crop modal**, not a bare file input.
+
+**Fix — the page misreported what was actually shipping.** It read only the S3
+override, so it announced *"No image yet — emails send without a banner until you
+upload one"* for an email that was visibly sending a banner from a committed repo
+asset. `current_url` now resolves what really ships, and the copy distinguishes
+"inherited default" from "no image at all".
+
+**New: `Studio.s3_key_prefix`** — an optional key namespace inside the bucket, so
+a satellite app can share an already-provisioned bucket instead of standing up
+its own pair:
+
+```ruby
+config.s3_bucket_prefix = "mcritchie-studio"
+config.s3_key_prefix    = "mcritchie-industries/"
+# -> s3://mcritchie-studio-dev/mcritchie-industries/email_banners/...
+```
+
+`Studio::S3` applies it to `upload`, `download`, `url`, `signed_url`, `exists?`,
+`delete`, and `list` — callers keep passing logical keys and never see it, and
+`list` strips it back off so a result feeds straight into `download`/`url`.
+**Unset by default, so every already-shipped app's keys are byte-identical.**
+Also new: `Studio::S3.configured?`, for callers that must degrade rather than
+rescue `NotConfigured`.
+
+**Honest degradation.** An app whose host never set `s3_bucket_prefix` renders
+`/admin/emails` **read-only** — showing the inherited defaults it is genuinely
+sending, naming the one setting that turns uploads on — instead of 500ing on the
+first upload.
+
+**New partial: `studio/modals/scoped_host`** — a self-contained modal host on its
+own Alpine store, for a page that must bring its own modals. `/admin/emails` uses
+it (`store: "emailModals"`) to ship its crop + saving modals, so the page works
+identically in an app that renders a shared modal host and one that renders none
+at all. `imageUploadHost` and `submitFormWithProgress` gained a matching `store`
+option (default `"modals"`, so existing call sites are unchanged); the crop-photo
+and saving partials already had one.
+
+It is a **separate partial rather than a local on `studio/modals/_host`** for a
+reason worth knowing: this is a non-isolated engine, so an app view at the same
+path shadows the engine's — and `mcritchie-studio` and `turf-monster` both ship
+their own `app/views/studio/modals/_host.html.erb`. A page rendering
+`studio/modals/host` in those apps silently gets the app's fork, which knows
+nothing of a `store:` local, so the page-scoped store is never registered and
+every modal trigger on the page does nothing. `scoped_host` is unforked in every
+app. The living style guide's hand-rolled `dsModals` host can rebase onto it.
+
+Register modals with `current()?.id`, not `current().id` — the outer template
+unmounts one tick after the stack empties, so a bare `.id` throws on close.
+
+**Compatibility.** `Studio::EmailImage.url(key)` keeps its **pre-registry
+contract** — this app's own uploaded image, or `nil`. The two-layer resolution
+lives in the new `resolved_url(key)`. This matters: `turf-monster`'s mailer is
+`Studio::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")`,
+and making `url` resolve to the engine default would have turned that `||` into
+dead code and silently replaced turf-monster's committed branded banner with the
+engine's **placeholder** in live sign-in email. A method whose signature is
+unchanged but whose return value flips from `nil` to a value is not additive.
+
+**Consumer note.** Nothing here is required to upgrade. To adopt: set
+`config.draw_admin_emails_routes = true`, link `admin_emails_path` from the app's
+admin sidebar, register any extra workflows, switch mailers from `url` to
+`resolved_url` where you want the inherited default, and drop any local
+`branded_mailer.html.erb` fork — the engine's copy is app-name-aware through
+`Studio.app_name`.
+
 **The local-review link now signs the reviewer in as someone who can SEE the
 page.** `/_studio/local_review` — the local half of the task board's WAITING
 APPROVAL button — provisions the account before it mints, at the new

data/README.md

@@ -24,6 +24,7 @@ Then `bundle install`. The current release is **v0.6.1**; see [`CHANGELOG.md`](.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls, `studio/banners/impersonation`, and an opt-in `Studio::Impersonation` concern for Act As session conventions.
 - **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
+- **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 
 ## Configuration
 
@@ -195,6 +196,39 @@ the block:
 <% end %>
 ```
 
+**Page-scoped hosts — `studio/modals/scoped_host`.** When a page must bring its
+own modals (because not every consuming app renders a shared host, and the ones
+that do register their own modal set), render a second host on its own Alpine
+store:
+
+```erb
+<%= render "studio/modals/scoped_host", store: "emailModals" do %>
+  <template x-if="$store.emailModals.current()?.id === 'crop-photo'">
+    <%= render "studio/modals/crop_photo", store: "emailModals" %>
+  </template>
+<% end %>
+```
+
+`studio/modals/_crop_photo` and `_saving` take the same `store:` local, and
+`imageUploadHost({ store: "emailModals", ... })` /
+`submitFormWithProgress(form, { store: "emailModals" })` route through it — all
+default to `"modals"`, so existing call sites are unchanged. The engine's
+`/admin/emails` is the live example.
+
+Two things that will bite you:
+
+- **Render `scoped_host`, not `host`.** This is a non-isolated engine, so an app
+  view at the same path shadows the engine's — and `mcritchie-studio` and
+  `turf-monster` both ship their own `app/views/studio/modals/_host.html.erb`.
+  A page rendering `studio/modals/host` in those apps silently gets the app's
+  fork. `scoped_host` is unforked everywhere.
+- **Guard registrations with `current()?.id`.** The outer template unmounts one
+  tick *after* the stack empties, so a bare `.id` throws on every close.
+
+The scoped host takes its animations from `engine-motion.css` rather than an
+inline copy, so a consumer bundling that layer gets the same spring as the shared
+host.
+
 Store API (`Alpine.store('modals')`):
 
 | Call | Behavior |
@@ -268,6 +302,153 @@ The legacy string locals (`balance_html`, `extra_icons_html`, `div2_html` —
 pre-rendered HTML injected via `raw`) are deprecated but still honored when the
 matching slot is absent, so existing call sites render unchanged.
 
+## Transactional emails
+
+Every consuming app can render the same admin page — **`/admin/emails`** —
+listing each transactional email it sends with the banner riding at the top of
+that email, and whether that banner is the **inherited default** or an
+**app-owned override**. Supersedes the old `/admin/email_images`, which is
+deprecated but still renders for one release.
+
+**The page is opt-in:**
+
+```ruby
+# config/initializers/studio.rb
+config.draw_admin_emails_routes = true
+```
+
+Off by default because `turf-monster` already owns `/admin/emails` and both of
+its helper names; drawing them there raises at route-load and kills every route
+in the app. The gate covers only the page — the registry and the inherited
+defaults are always on.
+
+### The catalog
+
+A registered email carries a key, a label, a description, what **type** it is,
+how to build a **live preview** of it, and its banner image. The engine
+pre-registers the two every Studio app sends, so a new app inherits both without
+declaring anything:
+
+| Key | Label |
+|-----|-------|
+| `magic_link` | Magic-link sign-in |
+| `email_change_confirmation` | Email change confirmation |
+
+A host adds its own workflows from an initializer, mirroring
+`Studio::ModelPage.register`:
+
+```ruby
+# config/initializers/studio_emails.rb
+Rails.application.config.to_prepare do
+  Studio::EmailCatalog.register("winnings",
+    label: "Contest winnings",
+    description: "Sent when a player wins a contest.",
+    type: :transactional,                                  # or :marketing
+    preview: -> { ContestMailer.winnings(Entry.where.not(rank: nil).first) })
+
+  Studio::EmailCatalog.register("wallet_export", label: "Wallet export")
+end
+```
+
+Every keyword is optional, and omitting one on a re-register **keeps** the
+existing value — attach a preview to an inherited email, or relabel it, without
+restating its artwork. An unknown `type` falls back to `:transactional` rather
+than raising.
+
+> `Studio::EmailImage` is the old name for this module and still works as a
+> delegating shim. It is deprecated; prefer `Studio::EmailCatalog`.
+
+### Live preview
+
+`preview:` is any callable returning a `Mail`. It powers `/admin/emails/:key`,
+which renders the real email in an iframe from `/admin/emails/:key/raw`.
+
+Builders run **only** on that page — listing the emails never executes one — and
+every call is contained. A builder that raises yields no preview, records why,
+and shows the reason in the frame. One broken builder costs one preview, not the
+manager. That matters because a builder runs against whatever sample data an
+environment happens to hold, which is exactly the thing that rots.
+
+Re-registering an inherited key updates it in place and keeps its position, so
+relabeling `magic_link` does not reorder the page or drop its default artwork.
+
+### Resolution — inherit, then own
+
+```
+Studio::EmailCatalog.resolved_url(:magic_link)
+  1. this app's ImageCache row  (its own S3 bucket)   -> app-owned override
+  2. the engine's default gem asset                   -> inherited default
+  3. nil                                              -> sends bannerless
+```
+
+Note the method: **`resolved_url` walks all three layers; `url` returns only
+layer 1** (this app's own image, or nil). That split is deliberate — it keeps
+every caller written before the registry behaving exactly as it did. A mailer
+that already falls back on its own, `url(:magic_link) || own_banner`, must stay
+on `url`; moving it to `resolved_url` makes that fallback unreachable and swaps
+the app's committed artwork for the engine's default.
+
+Defaults **ride the gem** (`app/assets/images/emails/*`), so a brand-new app with
+an empty bucket sends branded 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 `image_caches` row — which is exactly "the asset now belongs
+to this app". Every app has its own bucket and table, so an override never leaks
+between apps.
+
+Three accessors, and picking the wrong one changes what real people receive:
+
+| Call | Returns | Use for |
+|---|---|---|
+| `url(key)` | this app's **own** image, or `nil` | the pre-registry contract; a host doing its own `\|\| fallback` |
+| `resolved_url(key)` | own → inherited default → `nil`, **absolute** | mailers |
+| `preview_url(key)` | own → inherited default (root-relative) | the admin page |
+
+`url` deliberately does **not** resolve to the default. `turf-monster`'s mailer
+reads `Studio::EmailCatalog.url(:magic_link) || email_banner_url("magic-link-banner.jpg")`
+— making `url` resolve would turn that `||` into dead code and swap its committed
+branded banner for the engine placeholder in live email.
+
+```ruby
+class UserMailer < ApplicationMailer
+  layout "branded_mailer"
+
+  def magic_link(email, token)
+    @banner_url = Studio::EmailCatalog.resolved_url(:magic_link) # nil renders bannerless
+    # ...
+  end
+end
+```
+
+Do **not** fork `layouts/branded_mailer.html.erb` — the engine's copy is
+app-name-aware through `Studio.app_name`.
+
+### Sharing a bucket — `s3_key_prefix`
+
+Uploads need `Studio.s3_bucket_prefix`. A satellite app that has no bucket of its
+own can share an existing one under its own key namespace:
+
+```ruby
+config.s3_bucket_prefix = "mcritchie-studio"
+config.s3_key_prefix    = "mcritchie-industries/"
+# -> s3://mcritchie-studio-dev/mcritchie-industries/email_banners/...
+```
+
+`Studio::S3` applies the prefix to every operation, so callers keep passing
+logical keys and never see it. Unset (the default) leaves keys byte-identical to
+what every already-shipped app wrote.
+
+An app with **no** bucket configured does not error — `/admin/emails` renders
+read-only, showing the inherited defaults it is genuinely sending and naming the
+one setting that turns uploads on.
+
+### Linking it
+
+Add it to the app's admin sidebar section:
+
+```ruby
+{ label: "Emails", href: admin_emails_path, emoji: "✉️", desc: "Transactional email banners" }
+```
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.
@@ -275,18 +456,24 @@ This is a non-isolated engine -- app views at the same path automatically overri
 ## Releasing
 
 Engine releases use semantic versions and are published to RubyGems. The full
-operator checklist lives in [`docs/RELEASE.md`](./docs/RELEASE.md).
-
-Short form:
-
-1. Update [`CHANGELOG.md`](./CHANGELOG.md) and `lib/studio/version.rb`.
-2. Run `bin/release-check --build`.
-3. Publish the gem only after explicit approval.
-4. Tag the release after RubyGems accepts the gem.
-5. In each consumer app, run `bundle update studio-engine`, verify the lockfile,
-   and run app smoke checks.
-
-**Semver guide**
+checklist — split by whether you are building or conducting the release — lives
+in [`docs/RELEASE.md`](./docs/RELEASE.md).
+
+**Building an engine change?** Do **not** edit `lib/studio/version.rb`. The
+release owns the version, and McRitchie Studio's `bin/dor-check` refuses any PR
+that touches that file. Update [`CHANGELOG.md`](./CHANGELOG.md) under
+`Unreleased` (that is *not* gated), run `bin/release-check --build`, and open
+your PR into `accepted`. That is the whole of your part.
+
+**Conducting the release?** Commit the computed version — with `Gemfile.lock`,
+which pins the engine's own path-gem version — directly onto `accepted`, then
+run `bin/release prepare` from mcritchie-studio; it publishes, tags, and bumps
+each consumer's lock. Details and the exact commands are in
+[`docs/RELEASE.md`](./docs/RELEASE.md).
+
+**Semver guide** — the release *derives* the bump from its members (a `breaking`
+risk tag → major, a `feature` → minor, otherwise patch), so this is what those
+levels mean, not a menu to pick from:
 - **PATCH**: bug fix; no API change. Consumers can update the gem with zero diff elsewhere.
 - **MINOR**: backward-compatible feature add. Consumers may opt in to new APIs.
 - **MAJOR**: breaking change. Consumers will need code changes alongside the tag bump.

data/app/controllers/studio/email_images_controller.rb

@@ -1,20 +1,55 @@
 module Studio
-  # Admin page to manage the banner image on transactional emails (Studio::
-  # EmailImage). One managed variant today (magic_link); the registry is the
-  # extension point. Shared by every app — surfaced from each app's admin hub.
+  # DEPRECATED — superseded by Studio::EmailsController (/admin/emails), which
+  # shows every registered email with its live image, says whether that image is
+  # the inherited default or app-owned, and uploads through the crop modal.
+  #
+  # Kept alive for ONE release on purpose, not by neglect. consumer-ci.yml checks
+  # out each consumer repo with no `ref:` — i.e. its DEFAULT BRANCH — and runs
+  # that suite against the engine PR. mcritchie-studio and turf-monster both have
+  # tests on `main` that drive this page and its admin_email_image_path helper,
+  # so deleting it here would redden their lanes from the moment the PR opens,
+  # and nothing inside the engine PR could fix it: the consumer PRs would have to
+  # travel accepted -> release -> main in BOTH apps before this could go green.
+  #
+  # So the retirement is staged: this release adds /admin/emails and leaves this
+  # page working; each app's adoption task moves its link and its tests; a later
+  # engine minor deletes this file, its view, and its two routes once no
+  # consumer's main references them.
+  #
+  # It is not frozen in its broken state, though — see #index.
   class EmailImagesController < ApplicationController
     before_action :require_admin
 
     MAX_BYTES = 8.megabytes
 
     def index
-      @variants = Studio::EmailImage.variants
+      @variants = Studio::EmailCatalog.variants
     end
 
+    # The canonical page this one is being retired in favour of, or nil when this
+    # app has not drawn it. Rendered as a banner at the top of the old view so an
+    # admin who lands here by a stale link is walked forward.
+    #
+    # The nil case is REAL, not defensive padding: /admin/emails is opt-in
+    # (Studio.draw_admin_emails_routes, default off because turf-monster owns the
+    # name), so on any app that has not opted in the helper does not exist and a
+    # bare call raises NameError — which 500s this page. Consumer CI caught
+    # exactly that on mcritchie-studio.
+    #
+    # Asks the ROUTER rather than the config flag: the flag is read at route-draw
+    # time, so a host that flips it afterwards would still have no route, and the
+    # router is the thing that actually knows.
+    def successor_path
+      return nil unless Rails.application.routes.named_routes.key?(:admin_emails)
+
+      admin_emails_path
+    end
+    helper_method :successor_path
+
     # PATCH /admin/email_images/:variant — upload/replace a banner.
     def update
       variant = params[:variant].to_s
-      return head :not_found unless Studio::EmailImage.known?(variant)
+      return head :not_found unless Studio::EmailCatalog.known?(variant)
 
       file = params[:image]
       unless valid_image?(file)
@@ -23,8 +58,8 @@ module Studio
       end
 
       rescue_and_log do
-        Studio::EmailImage.store(variant, io: file, content_type: file.content_type)
-        redirect_to admin_email_images_path, notice: "#{Studio::EmailImage.label(variant)} banner updated."
+        Studio::EmailCatalog.store(variant, io: file, content_type: file.content_type)
+        redirect_to admin_email_images_path, notice: "#{Studio::EmailCatalog.label(variant)} banner updated."
       end
     rescue StandardError
       redirect_to admin_email_images_path, alert: "Couldn't save the image. Please try again.", status: :see_other