studio-engine 0.37.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc5fc673a7b9d072c93f482c90919c0f26836bd5e90194691ca30b5beb7c22d4
-  data.tar.gz: 9cbedec8a84b9619061217f90bceadbd51485e691351233bb67af6f03231b76e
+  metadata.gz: d497957db77f7b61823d1d12422672bf4339d71381163b79a6c42d705abf3492
+  data.tar.gz: e31717daca9b7722e4b9e87d44a507d9ec8c8055421e192bb3de78aa31175542
 SHA512:
-  metadata.gz: '088bca3db79b1ad97d52bf2478aa08518a6139e73c700cc63d30903c1d31e4fddb391213c2061cd0711d0d5656a7115e53dd10817b094271c459543133e36ea7'
-  data.tar.gz: 96eb836f896ed9a12dd8c71a308178aa112387bc40f266323dad82db726df9698a4881ff4450c7fa7ce9f42d61cf1bcab9ca80a88940f243891e1cfe0307f3d0
+  metadata.gz: 6f75c493e66ebae0fd31571d237fa6a4f1546e9c50143382a4f54bfe88d5614c1f582af6d758cafe93ffc47b744b01d875a280de92823012bf224f028859627d
+  data.tar.gz: dfa14e14dbe5796816a0247bd965da477b69e27e8c81750f554e1d2d497fbf486da5d14f1ae900aa26b28dcfe22c14a51f2e83ead2089d98f9667b0142d43b6d

data/CHANGELOG.md

@@ -2,11 +2,68 @@
 
 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, and the
-  email preview folded into that registry.
+- 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

data/README.md

@@ -24,7 +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::EmailImage` registry + 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).
+- **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
 
@@ -322,11 +322,12 @@ 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 registry
+### The catalog
 
-A registered email is mostly symbolic of a workflow — a key, a label, a
-description. The only real asset is its image. The engine pre-registers the two
-every Studio app sends, so a new app inherits both without declaring anything:
+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 |
 |-----|-------|
@@ -339,19 +340,42 @@ A host adds its own workflows from an initializer, mirroring
 ```ruby
 # config/initializers/studio_emails.rb
 Rails.application.config.to_prepare do
-  Studio::EmailImage.register("winnings", label: "Contest winnings",
-                              description: "Sent when a player wins a contest.")
-  Studio::EmailImage.register("wallet_export", label: "Wallet export")
+  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::EmailImage.resolved_url(:magic_link)
+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
@@ -380,7 +404,7 @@ Three accessors, and picking the wrong one changes what real people receive:
 | `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::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")`
+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.
 
@@ -389,7 +413,7 @@ class UserMailer < ApplicationMailer
   layout "branded_mailer"
 
   def magic_link(email, token)
-    @banner_url = Studio::EmailImage.resolved_url(:magic_link) # nil renders bannerless
+    @banner_url = Studio::EmailCatalog.resolved_url(:magic_link) # nil renders bannerless
     # ...
   end
 end
@@ -432,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

@@ -23,7 +23,7 @@ module Studio
     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
@@ -49,7 +49,7 @@ module Studio
     # 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)
@@ -58,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

data/app/controllers/studio/emails_controller.rb

@@ -4,7 +4,7 @@ module Studio
   # controller whose view is a bare content wrapper, so it renders inside each
   # host's application layout and picks up that app's navbar and theme.
   #
-  # It lists Studio::EmailImage's registry — one row per registered email, each
+  # It lists Studio::EmailCatalog's registry — one row per registered email, each
   # showing its live banner and whether that banner is the INHERITED engine
   # default or an APP-OWNED override — and writes an override through the shared
   # crop modal. Replaces /admin/email_images, which now redirects here.
@@ -15,14 +15,37 @@ module Studio
   # is currently sending.
   class EmailsController < ApplicationController
     before_action :require_admin
-    before_action :load_entry, only: %i[update destroy]
+    before_action :load_entry, only: %i[show raw update destroy]
     before_action :require_uploads, only: %i[update destroy]
 
     MAX_BYTES = 8.megabytes
 
     def index
-      @entries = Studio::EmailImage.entries
-      @uploads_available = Studio::EmailImage.uploads_available?
+      @entries = Studio::EmailCatalog.entries
+      @uploads_available = Studio::EmailCatalog.uploads_available?
+    end
+
+    # GET /admin/emails/:key — one email: its banner, its type, and a live
+    # preview built from the host's sample data.
+    def show
+      @entry = Studio::EmailCatalog.entry(@key)
+      @subject = Studio::EmailCatalog.preview_subject(@key)
+      @preview_error = Studio::EmailCatalog.preview_error(@key)
+      @uploads_available = Studio::EmailCatalog.uploads_available?
+    end
+
+    # GET /admin/emails/:key/raw — the rendered email itself, as the iframe
+    # source on #show. Layout-less on purpose: this response IS the email.
+    #
+    # A preview builder is host code run against whatever sample data this
+    # environment happens to hold, so it is expected to fail sometimes. It
+    # renders the failure as a readable page inside the iframe rather than
+    # 500ing, so one broken builder costs one preview, not the manager.
+    def raw
+      html = Studio::EmailCatalog.preview_html(@key)
+      return render(html: preview_unavailable_html.html_safe, layout: false) if html.nil?
+
+      render html: html.html_safe, layout: false
     end
 
     # PATCH /admin/emails/:key — upload/replace this app's own banner.
@@ -34,8 +57,8 @@ module Studio
       end
 
       rescue_and_log do
-        Studio::EmailImage.store(@key, io: file, content_type: file.content_type)
-        redirect_to admin_emails_path, notice: "#{Studio::EmailImage.label(@key)} banner updated.", status: :see_other
+        Studio::EmailCatalog.store(@key, io: file, content_type: file.content_type)
+        redirect_to admin_emails_path, notice: "#{Studio::EmailCatalog.label(@key)} banner updated.", status: :see_other
       end
     rescue StandardError
       redirect_to admin_emails_path, alert: "Couldn't save the image. Please try again.", status: :see_other
@@ -50,11 +73,11 @@ module Studio
       # failure is invisible — the admin sees "try again" and nothing reaches
       # ErrorLog to say why.
       rescue_and_log do
-        reverted = Studio::EmailImage.revert(@key)
+        reverted = Studio::EmailCatalog.revert(@key)
         notice = if reverted
-                   "#{Studio::EmailImage.label(@key)} reverted to the inherited default."
+                   "#{Studio::EmailCatalog.label(@key)} reverted to the inherited default."
                  else
-                   "#{Studio::EmailImage.label(@key)} was already using the inherited default."
+                   "#{Studio::EmailCatalog.label(@key)} was already using the inherited default."
                  end
         redirect_to admin_emails_path, notice: notice, status: :see_other
       end
@@ -66,16 +89,37 @@ module Studio
 
     def load_entry
       @key = params[:key].to_s
-      head :not_found unless Studio::EmailImage.known?(@key)
+      head :not_found unless Studio::EmailCatalog.known?(@key)
     end
 
     def require_uploads
-      return if Studio::EmailImage.uploads_available?
+      return if Studio::EmailCatalog.uploads_available?
 
       redirect_to admin_emails_path, status: :see_other,
                   alert: "This app has no object storage configured, so email images can't be changed here yet."
     end
 
+    # Shown INSIDE the preview iframe when the builder is missing or raised.
+    # Deliberately plain inline HTML: the iframe is its own document and does not
+    # inherit the host app's stylesheet.
+    def preview_unavailable_html
+      reason = Studio::EmailCatalog.preview_error(@key)
+      message = if reason
+                  "This email's preview builder raised:<br><code style=\"color:#b91c1c\">" \
+                    "#{ERB::Util.html_escape(reason)}</code>"
+                else
+                  "No preview is registered for this email. Add a <code>preview:</code> " \
+                    "callable when registering it to see it rendered here."
+                end
+
+      <<~HTML
+        <!doctype html>
+        <html><body style="margin:0;padding:32px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#334155;background:#f8fafc;">
+          <p style="font-size:14px;line-height:1.6;max-width:52ch;">#{message}</p>
+        </body></html>
+      HTML
+    end
+
     def valid_image?(file)
       file.respond_to?(:content_type) &&
         file.content_type.to_s.start_with?("image/") &&

data/app/mailers/user_mailer.rb

@@ -24,7 +24,7 @@ class UserMailer < ApplicationMailer
     # resolved_url, not url: this app's own upload if it has one, otherwise the
     # engine's default banner — which is what makes a brand-new app's sign-in
     # email branded on day one. nil renders bannerless.
-    @banner_url = Studio::EmailImage.resolved_url(:magic_link)
+    @banner_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")
   end

data/app/models/image_cache.rb

@@ -1,6 +1,6 @@
 class ImageCache < ApplicationRecord
   # Optional so app-GLOBAL images (no owning record) can be cached too — e.g.
-  # Studio::EmailImage stores the admin-managed email banners owner-less. Per-
+  # Studio::EmailCatalog stores the admin-managed email banners owner-less. Per-
   # record images (athlete/coach headshots) still set an owner; the
   # variant-uniqueness scope below keeps both shapes distinct.
   belongs_to :owner, polymorphic: true, optional: true