studio-engine 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c692fc135af1ba83c08b27398c875bc547ae07bbcc492540ffd83250fccf680
-  data.tar.gz: 891c561fe2bef1386137af4fbbc22547f38613efe8bd373bf6ec31894086feef
+  metadata.gz: dc5fc673a7b9d072c93f482c90919c0f26836bd5e90194691ca30b5beb7c22d4
+  data.tar.gz: 9cbedec8a84b9619061217f90bceadbd51485e691351233bb67af6f03231b76e
 SHA512:
-  metadata.gz: 9cb8bb03d5adeec99336b5fab4d28b29c57be8686ca2afef58932ce866c321fe44f6ab0123609e6845151f938ab28790685bda6b9b21815ef3a3594d6c589921
-  data.tar.gz: 2c3be4aadf2a88d7838dab26b27c4a22604268138bba818f0b82890774f7bc5b81424d53a645d3fcc5ebf59a8f10197a9b37bd9cd44246c988d8dca3dfd2cd62
+  metadata.gz: '088bca3db79b1ad97d52bf2478aa08518a6139e73c700cc63d30903c1d31e4fddb391213c2061cd0711d0d5656a7115e53dd10817b094271c459543133e36ea7'
+  data.tar.gz: 96eb836f896ed9a12dd8c71a308178aa112387bc40f266323dad82db726df9698a4881ff4450c7fa7ce9f42d61cf1bcab9ca80a88940f243891e1cfe0307f3d0

data/CHANGELOG.md

@@ -2,8 +2,161 @@
 
 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.
 
+## 0.37.0 — 2026-08-10
+
+### Added
+- Standard transactional email primitive with a registry-backed catalog, and the
+  email preview folded into that registry.
+
+### 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::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).
 
 ## 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,129 @@ 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 registry
+
+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:
+
+| 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::EmailImage.register("winnings", label: "Contest winnings",
+                              description: "Sent when a player wins a contest.")
+  Studio::EmailImage.register("wallet_export", label: "Wallet export")
+end
+```
+
+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)
+  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::EmailImage.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::EmailImage.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.

data/app/controllers/studio/email_images_controller.rb

@@ -1,7 +1,22 @@
 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
 
@@ -11,6 +26,26 @@ module Studio
       @variants = Studio::EmailImage.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

data/app/controllers/studio/emails_controller.rb

@@ -0,0 +1,85 @@
+module Studio
+  # /admin/emails — the standard transactional-email page every Studio app gets,
+  # modelled on the living style guide (/admin/style): a plain host-inherited
+  # 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
+  # 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.
+  #
+  # An app whose host never set Studio.s3_bucket_prefix cannot store an override.
+  # That is a read-only page, not an error: uploads_available? gates the write
+  # actions and the view explains why, so the page still shows what each email
+  # is currently sending.
+  class EmailsController < ApplicationController
+    before_action :require_admin
+    before_action :load_entry, only: %i[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?
+    end
+
+    # PATCH /admin/emails/:key — upload/replace this app's own banner.
+    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."
+        return redirect_to admin_emails_path, alert: message, status: :see_other
+      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
+      end
+    rescue StandardError
+      redirect_to admin_emails_path, alert: "Couldn't save the image. 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
+      # rescue_and_log, like #update: destroy is a WRITE path (it drops an
+      # ImageCache row and deletes the S3 object behind it), and the bare rescue
+      # below turns any failure into a friendly alert. Without the log that
+      # failure is invisible — the admin sees "try again" and nothing reaches
+      # ErrorLog to say why.
+      rescue_and_log do
+        reverted = Studio::EmailImage.revert(@key)
+        notice = if reverted
+                   "#{Studio::EmailImage.label(@key)} reverted to the inherited default."
+                 else
+                   "#{Studio::EmailImage.label(@key)} was already using the inherited default."
+                 end
+        redirect_to admin_emails_path, notice: notice, status: :see_other
+      end
+    rescue StandardError
+      redirect_to admin_emails_path, alert: "Couldn't revert the image. Please try again.", status: :see_other
+    end
+
+    private
+
+    def load_entry
+      @key = params[:key].to_s
+      head :not_found unless Studio::EmailImage.known?(@key)
+    end
+
+    def require_uploads
+      return if Studio::EmailImage.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
+
+    def valid_image?(file)
+      file.respond_to?(:content_type) &&
+        file.content_type.to_s.start_with?("image/") &&
+        file.respond_to?(:size) && file.size.to_i.positive? && file.size <= MAX_BYTES
+    end
+  end
+end

data/app/mailers/user_mailer.rb

@@ -21,7 +21,10 @@ class UserMailer < ApplicationMailer
     @app_name   = Studio.app_name
     @email      = email
     @magic_url  = magic_link_url_for(token)
-    @banner_url = Studio::EmailImage.url(:magic_link) # admin-managed; nil renders bannerless
+    # 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_alt = "Your #{@app_name} sign-in link"
     mail(to: email, subject: "Your #{@app_name} sign-in link")
   end