studio-engine 0.36.0 → 0.38.0

data/app/views/studio/modals/_scoped_host.html.erb

@@ -0,0 +1,195 @@
+<%#
+  PAGE-SCOPED modal host — a self-contained modal shell mounted on its OWN
+  Alpine store, for a page that must bring its own modals rather than rely on
+  the app's shared host.
+
+  Why this exists as a separate partial rather than a local on
+  studio/modals/_host: this is a NON-ISOLATED engine, so an app view at the same
+  path SHADOWS the engine's. `mcritchie-studio` and `turf-monster` both ship
+  their own app/views/studio/modals/_host.html.erb — older, simpler copies that
+  know nothing of a store: local. A page rendering "studio/modals/host" in those
+  apps silently gets the fork, and its page-scoped store is never registered.
+  This partial's path is unforked in every app, so it renders the engine's code
+  everywhere. (The living style guide hand-rolled the same thing inline for the
+  same reason; it can rebase onto this later.)
+
+  Two independent problems it solves at once:
+
+    1. Apps that DO have a shared host (mcritchie-studio, turf-monster) register
+       their own modal set. A page needing crop-photo would have to ask every
+       app to add it.
+    2. Apps that have NO host at all (mcritchie-industries, moms-app) would have
+       nowhere to open a modal from.
+
+  Both go away when the page owns its host.
+
+  Animations come from the shared motion layer
+  (app/assets/tailwind/studio_engine/engine-motion.css) — the .modal-card-* and
+  .modal-backdrop-* classes — rather than an inline copy, so this stays small.
+  A consumer that does not bundle engine-motion.css still gets a working modal,
+  just without the spring.
+
+  Locals:
+    store      — REQUIRED. Alpine store name, e.g. "emailModals". Must be unique
+                 on the page; never "modals" (that is the shared host's).
+    card_class — optional card sizing/skin override. Default is the shared
+                 host's max-w-sm card.
+
+  Usage: render this partial with a block, exactly like the shared host, and put
+  one `template x-if` per modal id inside it — see app/views/studio/emails/
+  index.html.erb for the live call site. Guard each registration with optional
+  chaining (`current()?.id`): the outer template unmounts one tick AFTER the
+  stack empties, so a bare `.id` throws on every close.
+
+  (No inline ERB example here on purpose. An ERB comment ends at its FIRST "%" +
+  ">", so an example containing one silently closes the comment and dumps the
+  rest of it onto the page as visible text. That shipped once.)
+%>
+<%
+  scoped_store = local_assigns.fetch(:store)
+  card_class   = local_assigns.fetch(:card_class,
+                   "bg-surface rounded-xl border border-subtle shadow-2xl p-6 max-w-sm w-full")
+%>
+<style>
+  /* Scroll lock, applied by the store's _sync() while the stack is non-empty.
+     Shipped here too because an app with no shared host never defines it. */
+  body.modal-open { overflow: hidden; }
+</style>
+
+<script>
+  (function() {
+    var STORE_NAME    = '<%= scoped_store %>';
+    // Keep in sync with .modal-card-unmount in engine-motion.css — the entry is
+    // spliced off the stack only after the exit animation has played.
+    var CLOSE_ANIM_MS = 220;
+
+    // window.StudioModals.holdAtLeast(ms) — the minimum-visible-duration
+    // convention shared with the app-level host, so a spinner can't flash past
+    // the user. Defined defensively: this page may be the only host on it.
+    window.StudioModals = window.StudioModals || {};
+    window.StudioModals.holdAtLeast = window.StudioModals.holdAtLeast || function(minMs) {
+      var startedAt = Date.now();
+      return {
+        then: function(callback) {
+          var remaining = Math.max(0, minMs - (Date.now() - startedAt));
+          if (remaining === 0) { callback(); return; }
+          setTimeout(callback, remaining);
+        }
+      };
+    };
+
+    // Named, so the dual-guard below can call it directly on a Turbo visit.
+    // Alpine's deferred script fires alpine:init exactly ONCE per full document
+    // load; this registration lives in a PAGE BODY, so it was absent during that
+    // one init. Without the guard, a Turbo Drive visit to this page leaves the
+    // store undefined and every x-data on it throws.
+    function registerScopedStore() {
+      if (Alpine.store(STORE_NAME)) return;
+
+      Alpine.store(STORE_NAME, {
+        stack: [],
+
+        // open(id, props, opts) — opts.replace swaps the top entry in place
+        // (what submitFormWithProgress does to turn crop-photo into saving).
+        open: function(id, props, opts) {
+          props = props || {};
+          opts  = opts  || {};
+          var entry = { id: id, props: props };
+
+          if (opts.replace && this.stack.length > 0) {
+            this.stack.splice(this.stack.length - 1, 1, entry);
+          } else {
+            this.stack.push(entry);
+          }
+          this._sync();
+        },
+
+        swap: function(id, props, opts) {
+          opts = opts || {};
+          opts.replace = true;
+          this.open(id, props, opts);
+        },
+
+        // Flip _closing so the exit animation plays, then splice.
+        close: function() {
+          var entry = this.current();
+          if (!entry) return;
+
+          var self = this;
+          entry._closing = true;
+          setTimeout(function() {
+            var index = self.stack.indexOf(entry);
+            if (index !== -1) self.stack.splice(index, 1);
+            self._sync();
+          }, CLOSE_ANIM_MS);
+        },
+
+        closeAll: function() {
+          this.stack = [];
+          this._sync();
+        },
+
+        // Keeps dismissible: false entries — a still-in-flight upload must not
+        // silently lose the card its promise will resolve against.
+        closeAllDismissible: function() {
+          this.stack = this.stack.filter(function(entry) {
+            return entry.props && entry.props.dismissible === false;
+          });
+          this._sync();
+        },
+
+        isOpen: function(id) {
+          return this.stack.some(function(entry) { return entry.id === id; });
+        },
+
+        current: function() {
+          return this.stack.length ? this.stack[this.stack.length - 1] : null;
+        },
+
+        // Mount on open, unmount while closing. _settled pins the entry after
+        // its first render so a stale Alpine re-evaluation cannot re-fire the
+        // bounce-in keyframe mid-life (which reads as a flash).
+        cardClasses: function() {
+          var entry = this.current();
+          if (!entry) return '';
+          if (entry._closing) return 'modal-card-unmount';
+          if (!entry._settled) { entry._settled = true; }
+          return 'modal-card-mount';
+        },
+
+        _sync: function() {
+          document.body.classList.toggle('modal-open', this.stack.length > 0);
+        }
+      });
+    }
+
+    if (window.Alpine) { registerScopedStore(); }
+    else { document.addEventListener('alpine:init', registerScopedStore); }
+
+    // bfcache + Turbo snapshot cleanup, so a modal left open does not reappear
+    // on a back navigation.
+    function clearStaleScopedModals() {
+      if (!window.Alpine || !Alpine.store) return;
+
+      var store = Alpine.store(STORE_NAME);
+      if (store && typeof store.closeAllDismissible === 'function') store.closeAllDismissible();
+    }
+    window.addEventListener('pageshow', function(e) { if (e.persisted) clearStaleScopedModals(); });
+    document.addEventListener('turbo:before-cache', clearStaleScopedModals);
+  })();
+</script>
+
+<template x-if="$store.<%= scoped_store %>.current()">
+  <div class="fixed inset-0 z-[120] flex items-center justify-center p-4 modal-backdrop-mount"
+       :class="$store.<%= scoped_store %>.current()?._closing && 'modal-backdrop-unmount'"
+       style="background:rgba(0,0,0,0.6)"
+       role="dialog"
+       aria-modal="true"
+       @keydown.escape.window="$store.<%= scoped_store %>.current() && $store.<%= scoped_store %>.current().props.dismissible !== false && $store.<%= scoped_store %>.close()"
+       @click.self="$store.<%= scoped_store %>.current() && $store.<%= scoped_store %>.current().props.dismissible !== false && $store.<%= scoped_store %>.close()">
+    <div class="<%= card_class %>" :class="$store.<%= scoped_store %>.cardClasses()">
+      <%# Consumer-provided registrations — one <template x-if> per modal id. %>
+      <%= yield if block_given? %>
+    </div>
+  </div>
+</template>

data/lib/studio/engine.rb

@@ -47,6 +47,26 @@ module Studio
         studio/studio_confetti.js
         studio/sortable.js
       ]
+
+      # The INHERITED default email banners (Studio::EmailImage). They ride the
+      # gem so a brand-new app sends branded email on day one with an empty S3
+      # bucket. Enumerated from disk rather than listed by hand so adding a
+      # default is a one-file change. Sprockets hosts (mcritchie-studio,
+      # turf-monster) need the explicit precompile entry; propshaft hosts
+      # (mcritchie-industries, moms-app) serve everything on config.assets.paths
+      # and ignore this list.
+      # Named on the CLASS, not bare: an initializer block is instance_exec'd on
+      # an Engine INSTANCE, where a bare call resolves to nothing and boots red.
+      app.config.assets.precompile += Studio::Engine.default_email_banner_logical_paths
+    end
+
+    # Logical asset paths ("emails/magic-link.png") for every default banner the
+    # gem ships.
+    def self.default_email_banner_logical_paths
+      Dir[File.expand_path("../../app/assets/images/emails/*", __dir__)]
+        .select { |path| File.file?(path) }
+        .map { |path| "emails/#{File.basename(path)}" }
+        .sort
     end
 
     rake_tasks do

data/lib/studio/s3.rb

@@ -5,7 +5,7 @@ module Studio
 
     class << self
       def upload(key:, body:, content_type: nil, cache_control: nil)
-        opts = { bucket: bucket, key: key, body: body }
+        opts = { bucket: bucket, key: full_key(key), body: body }
         opts[:content_type] = content_type if content_type
         opts[:cache_control] = cache_control if cache_control
         client.put_object(**opts)
@@ -13,32 +13,34 @@ module Studio
       end
 
       def download(key:)
-        client.get_object(bucket: bucket, key: key).body.read
+        client.get_object(bucket: bucket, key: full_key(key)).body.read
       end
 
       def url(key:)
-        "https://#{bucket}.s3.#{region}.amazonaws.com/#{key}"
+        "https://#{bucket}.s3.#{region}.amazonaws.com/#{full_key(key)}"
       end
 
       def signed_url(key:, expires_in: 3600)
         require "aws-sdk-s3"
-        Aws::S3::Presigner.new(client: client).presigned_url(:get_object, bucket: bucket, key: key, expires_in: expires_in)
+        Aws::S3::Presigner.new(client: client).presigned_url(:get_object, bucket: bucket, key: full_key(key), expires_in: expires_in)
       end
 
       def exists?(key:)
-        client.head_object(bucket: bucket, key: key)
+        client.head_object(bucket: bucket, key: full_key(key))
         true
       rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
         false
       end
 
       def delete(key:)
-        client.delete_object(bucket: bucket, key: key)
+        client.delete_object(bucket: bucket, key: full_key(key))
       end
 
+      # Returns LOGICAL keys (the app's key namespace stripped back off), so a
+      # caller can feed any result straight back into download/delete/url.
       def list(prefix: nil, max: 1000)
-        resp = client.list_objects_v2(bucket: bucket, prefix: prefix, max_keys: max)
-        resp.contents.map(&:key)
+        resp = client.list_objects_v2(bucket: bucket, prefix: full_key(prefix), max_keys: max)
+        resp.contents.map { |object| logical_key(object.key) }
       end
 
       def bucket
@@ -47,6 +49,40 @@ module Studio
         "#{prefix}-#{environment}"
       end
 
+      # Whether this app can touch object storage at all. Callers that must
+      # degrade rather than 500 (the /admin/emails uploader on an app whose
+      # bucket was never provisioned) ask this instead of rescuing NotConfigured.
+      def configured?
+        bucket
+        true
+      rescue NotConfigured
+        false
+      end
+
+      # Studio.s3_key_prefix, normalized to "" or "something/". The namespace a
+      # satellite app lives under when it shares another app's bucket.
+      def key_prefix
+        prefix = Studio.s3_key_prefix.to_s
+        return "" if prefix.empty?
+
+        prefix.end_with?("/") ? prefix : "#{prefix}/"
+      end
+
+      # Logical key -> the real object key in the bucket.
+      def full_key(key)
+        return key if key.nil?
+
+        "#{key_prefix}#{key}"
+      end
+
+      # The real object key -> logical key (inverse of full_key).
+      def logical_key(key)
+        prefix = key_prefix
+        return key if prefix.empty? || !key.to_s.start_with?(prefix)
+
+        key.to_s.delete_prefix(prefix)
+      end
+
       def region
         Studio.s3_region
       end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.36.0"
+  VERSION = "0.38.0"
 end

data/lib/studio.rb

@@ -129,6 +129,18 @@ module Studio
   # its own routes (it can still reuse Studio::Link + Studio::LinkConsumption).
   mattr_accessor :draw_link_routes, default: true
 
+  # Draw the shared transactional-email page at /admin/emails
+  # (Studio::EmailsController). OFF by default because the path AND its helper
+  # names (admin_emails_path / admin_email_path) are already taken in
+  # turf-monster, where drawing them raises at route-load and kills every route
+  # in the app. A host opts in from config/initializers/studio.rb:
+  #
+  #   config.draw_admin_emails_routes = true
+  #
+  # Gates only the PAGE. Studio::EmailImage's registry and its inherited-default
+  # resolution are always on, so an app sends branded email either way.
+  mattr_accessor :draw_admin_emails_routes, default: false
+
   # Optional admin Act As / impersonation session conventions. Consumers that
   # include Studio::Impersonation get current_user layered over true_user with
   # these session keys, but still own authorization, audit logging, and routes.
@@ -206,6 +218,19 @@ module Studio
   mattr_accessor :s3_bucket_prefix, default: nil
   mattr_accessor :s3_region,        default: "us-east-2"
 
+  # Optional key namespace INSIDE the bucket, so a satellite app can share an
+  # existing bucket instead of provisioning its own pair. Set it and every key a
+  # caller passes to Studio::S3 is stored/read under that prefix — callers keep
+  # passing logical keys ("email_banners/magic_link-ab12.jpg") and never see it:
+  #
+  #   config.s3_bucket_prefix = "mcritchie-studio"
+  #   config.s3_key_prefix    = "mcritchie-industries/"
+  #   # -> s3://mcritchie-studio-dev/mcritchie-industries/email_banners/...
+  #
+  # Default nil = no namespace, so every already-shipped app's keys are unchanged.
+  # A trailing slash is added if you leave it off.
+  mattr_accessor :s3_key_prefix, default: nil
+
   class S3ConfigError < StandardError; end
 
   # Whether to validate the host app's User model at boot. See docs/USER_CONTRACT.md.
@@ -505,11 +530,57 @@ module Studio
       get   "admin/style",            to: "style#index",               as: :admin_style
       get   "admin/design_system",    to: redirect("/admin/style"),    as: :admin_design_system
 
-      # Admin-managed transactional-email banner images (Studio::EmailImage).
-      # index lists each managed email variant + its current banner; update
-      # uploads a replacement. Surfaced from each app's admin hub.
+      # The standard transactional-email page. Canonical at /admin/emails
+      # (Studio::EmailsController): index lists every registered email with its
+      # live banner and whether that banner is inherited or app-owned; update
+      # stores this app's own override; destroy drops it back to the inherited
+      # default. Surfaced from each app's admin sidebar.
+      #
+      # /admin/email_images redirects here but KEEPS its admin_email_images_path
+      # helper, so a shipped host sidebar link on the old helper still resolves
+      # (same treatment as /admin/design_system -> /admin/style).
+      # OPT-IN, and it has to be. turf-monster ALREADY owns /admin/emails —
+      # `namespace :admin { get "emails", as: :emails }` (its EmailCatalog
+      # manager) — which claims the SAME path and the SAME helper names,
+      # admin_emails_path and admin_email_path. Drawing these unconditionally
+      # raises `ArgumentError: Invalid route name, already in use: 'admin_emails'`
+      # while turf-monster's own routes.rb is loading, which takes down its
+      # ENTIRE route set (every admin_*_path in the app goes undefined) — not a
+      # shadowed page, a dead app. Confirmed on consumer CI, PR #86.
+      #
+      # A host cannot opt out of something that breaks it before its config is
+      # read, and consumer CI runs each consumer's `main` — so default-on cannot
+      # be fixed from inside the engine. Default-off, and each app's adoption
+      # task turns it on. Flip the default once no consumer's main owns the name.
+      #
+      # This gates only the PAGE. The registry and the two-layer image resolution
+      # are always on, and the engine's own UserMailer already calls
+      # Studio::EmailImage.resolved_url — so an app is branded on day one whether
+      # or not it draws the page.
+      if Studio.draw_admin_emails_routes
+        get    "admin/emails",          to: "studio/emails#index", as: :admin_emails
+        # /raw is drawn BEFORE /:key so "raw" is never captured as a key.
+        get    "admin/emails/:key/raw", to: "studio/emails#raw",   as: :admin_email_raw,
+               constraints: { key: /[a-z0-9_]+/ }
+        get    "admin/emails/:key",     to: "studio/emails#show",  as: :admin_email,
+               constraints: { key: /[a-z0-9_]+/ }
+        # Same path, same helper (admin_email_path) — a named route only needs
+        # to be declared once per name, and these share the show route's URL.
+        patch  "admin/emails/:key",     to: "studio/emails#update",
+               constraints: { key: /[a-z0-9_]+/ }
+        delete "admin/emails/:key",     to: "studio/emails#destroy",
+               constraints: { key: /[a-z0-9_]+/ }
+      end
+
+      # DEPRECATED, kept for ONE release. Not a redirect: consumer-ci.yml runs
+      # each consumer's DEFAULT-BRANCH suite against this engine, and both
+      # mcritchie-studio and turf-monster have tests on `main` that GET this page
+      # and PATCH through admin_email_image_path. Redirecting (or deleting) here
+      # reddens their lanes the moment the PR opens, and no change inside the
+      # engine PR can fix it. Each app's adoption task moves its link + tests; a
+      # later engine minor deletes these two routes with the controller and view.
       get   "admin/email_images",          to: "studio/email_images#index",  as: :admin_email_images
-      patch "admin/email_images/:variant", to: "studio/email_images#update",  as: :admin_email_image,
+      patch "admin/email_images/:variant", to: "studio/email_images#update", as: :admin_email_image,
             constraints: { variant: /[a-z_]+/ }
 
       # Model-page protocol (v1) — a reusable per-record inspector. Drawn into

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.38.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -168,6 +168,8 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- app/assets/images/emails/email-change-confirmation.png
+- app/assets/images/emails/magic-link.png
 - app/assets/images/resend-favicon.png
 - app/assets/images/ses-favicon.png
 - app/assets/javascripts/studio/canvas_confetti.js
@@ -193,6 +195,7 @@ files:
 - app/controllers/sessions_controller.rb
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/email_images_controller.rb
+- app/controllers/studio/emails_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/studio/local_reviews_controller.rb
@@ -220,6 +223,7 @@ files:
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
+- app/services/studio/email_catalog.rb
 - app/services/studio/email_image.rb
 - app/views/components/_admin_dropdown.html.erb
 - app/views/components/_avatar.html.erb
@@ -271,6 +275,9 @@ files:
 - app/views/studio/board/_card_shell.html.erb
 - app/views/studio/board/_column.html.erb
 - app/views/studio/email_images/index.html.erb
+- app/views/studio/emails/_row.html.erb
+- app/views/studio/emails/index.html.erb
+- app/views/studio/emails/show.html.erb
 - app/views/studio/links/confirm.html.erb
 - app/views/studio/local_emails/index.html.erb
 - app/views/studio/modals/_crop_photo.html.erb
@@ -278,6 +285,7 @@ files:
 - app/views/studio/modals/_image_upload.html.erb
 - app/views/studio/modals/_load_convention.html.erb
 - app/views/studio/modals/_saving.html.erb
+- app/views/studio/modals/_scoped_host.html.erb
 - app/views/studio/modals/auth/_resend_footer.html.erb
 - app/views/studio/modals/blocks/_age_verify.html.erb
 - app/views/studio/modals/blocks/_card_header.html.erb