studio-engine 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 251aa22a7a41f33e6cab5a4f1f1c38a714aa4a14f2f4b08567c27340e1563f24
-  data.tar.gz: 2f8b5ec4901d403c1ffdaf42dee430c69f1c31625c926e8deb43c021a41eb6a9
+  metadata.gz: 31ed2941026e5bf0114872ba16dd7a9b94b1a472d5407ff82ec604ba2e659962
+  data.tar.gz: 1fda4b1328315323b8afcee644a68acc8678e756762a88b289ea10e0fc46a6cf
 SHA512:
-  metadata.gz: 1c8fa01470ce96a17550dac1d2d70db086b1acf0c6f6ed97a8b31679f2f3559dbb8549687bb79e806b2148a058ab700154bc330f4b94eb6b4216480fb0831d67
-  data.tar.gz: 4ae572b5cadc0734b1ef69a8d0ec0d4331c57f3545be08e850dcd2b0d53c0f6d30d5e1b2d287a65542d46dec4b1d803cad6611471f24c533143118daa0fc75b4
+  metadata.gz: 6431e1dafbd0a614e1c0a6abe25004ab3888a3d1e7c263ab97d7883e10bcedde60da03f16c98b262d9926173749343b00c33d6a5580db9fc299c8b1b355a9665
+  data.tar.gz: 7513d2735c2535ed520530eab4adc0b1ce60de617488e4fa934e43beb31ef330e7e49c8837e3310aa92467559dbabf714fab43b81d86a0d52cebce8f85674e35

data/CHANGELOG.md

@@ -4,6 +4,52 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.9.0 — 2026-06-23
+
+### Added
+- **`Studio::Enumeral`** — a shared, DB-backed enumeration table for the whole
+  ecosystem. Every "list of fixed, labeled, colored values" (Pokémon types first;
+  statuses/tiers/roles later) is rows in ONE `studio_enumerals` table, grouped by
+  `category`: a stable machine `key`, a human `label`, a `color` hex, a display
+  `position`, a sparse `rank` (gappy 100/200/… domain ranking — e.g. most-common
+  first — distinct from display order), and `metadata` (jsonb) for
+  category-specific extras. Class helpers `catalog`, `lookup`, `color_map` (one
+  query → `{ key => color }`), `color_for(category, key, fallback:)`, and a
+  metadata-backed `emoji` reader + `emoji_map` (decorative glyphs live in
+  `metadata`, not a column); scopes `ordered` / `by_rank`; `available?` degrades
+  to empty when the table isn't installed. Shipped by the gem like `Studio::Link` /
+  `Studio::EmailDelivery` — reference migration `create_studio_enumerals`
+  installed per app (copy into `db/migrate`). No behavior is attached: a consumer
+  adopts a new category by seeding rows, no code change.
+
+## 0.8.0 — 2026-06-21
+
+### Added
+- **`Studio::Link` + unified `/l/<token>`** — one short-token model + entry point
+  for both single-use, expiring **magic_link**s and reusable, non-expiring
+  **referral** links. Polymorphic `linkable` (optional), `metadata` jsonb (email/
+  return_to/target/age_attested off the wire), nullable `expires_at`, atomic
+  single-use consume. `Studio::LinkToken` holds the pure token/kind/sanitizer
+  logic (unit-tested without a DB); `Studio::LinksController` dispatches by kind
+  (magic → scanner-safe confirm + POST consume; referral → attribution cookie +
+  redirect). `Studio::LinkConsumption` concern shares sign-in/sign-up. Reference
+  migration `create_studio_links` (installed per app like `studio_email_deliveries`).
+- **`Studio.magic_link_store`** (`:signed` default | `:database`) and
+  **`Studio.draw_link_routes`** flags. `:database` mints `Studio::Link`s and
+  emails the short `/l/<token>` (vs the legacy `/magic_link/<MessageVerifier>`);
+  fully back-compatible — the default leaves existing consumers untouched.
+- **Branded mailer** lifted into the engine: `layouts/branded_mailer` + a branded
+  `UserMailer#magic_link` body (theme-colored button, banner-aware). Apps with
+  their own `UserMailer`/`branded_mailer` still win.
+- **`Studio::EmailImage`** + **`/admin/email_images`** (admin-gated) — manage the
+  banner image on transactional emails (magic-link now; per-variant registry is
+  the extension point). Backed by `Studio::S3` + an owner-less `ImageCache` row
+  (permanent public URL, nil-safe pre-upload).
+
+### Changed
+- `ImageCache#owner` is now optional (+ reference migration to drop the owner
+  `NOT NULL`), so app-global images (e.g. email banners) can be cached.
+
 ## v0.7.0 (2026-06-20)
 
 ### Added

data/app/controllers/concerns/studio/link_consumption.rb

@@ -0,0 +1,52 @@
+module Studio
+  # Shared create-or-login building blocks for the magic-link / link consume
+  # controllers (MagicLinksController + Studio::LinksController). `result` is
+  # anything responding to #email and #return_to — the legacy MagicLink::Result
+  # OR a Studio::Link — so both token schemes reuse this. Apps that override the
+  # link controllers (e.g. turf-monster's contest landing) include it too.
+  #
+  # Relies on the host ApplicationController contract from Studio::ErrorHandling:
+  # set_app_session, rescue_and_log, current_user, plus root_path / login_path.
+  module LinkConsumption
+    extend ActiveSupport::Concern
+
+    private
+
+    def sign_in_existing(user, result)
+      set_app_session(user)
+      # Clicking the link proves email ownership, so verify any account that
+      # reached here without it (e.g. a Google/wallet-only signup).
+      user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at) && user.email_verified_at.blank?
+      redirect_to(safe_path(result.return_to) || root_path, notice: "Signed in. Welcome back!")
+    end
+
+    # Build → configure_new_user → save!. No password — email auth is link-only.
+    def sign_up_new(result)
+      user = User.new(email: result.email)
+      Studio.configure_new_user.call(user)
+      rescue_and_log(target: user) do
+        user.save!
+        user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at)
+        set_app_session(user)
+        redirect_to(safe_path(result.return_to) || root_path, notice: Studio.welcome_message.call(user))
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Two valid tokens for the same brand-new email consumed near-simultaneously
+      # both miss find_by and race to save!; the loser hits the unique index.
+      # Benign — the account now exists, so just log the winner in.
+      existing = User.find_by(email: result.email)
+      return sign_in_existing(existing, result) if existing
+
+      redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+    rescue StandardError => e
+      Rails.logger.error("[Studio::LinkConsumption#sign_up_new] signup failed #{e.class}: #{e.message}")
+      redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+    end
+
+    # Only same-origin absolute paths survive; everything else collapses to nil.
+    def safe_path(path)
+      p = path.to_s
+      p.start_with?("/") && !p.start_with?("//") ? p : nil
+    end
+  end
+end

data/app/controllers/magic_links_controller.rb

@@ -14,6 +14,8 @@
 # OVERRIDE this controller in the app and reuse the MagicLink service + the
 # sign_in_existing / sign_up_new building blocks.
 class MagicLinksController < ApplicationController
+  include Studio::LinkConsumption
+
   skip_before_action :require_authentication
   layout false, only: :confirm
 
@@ -23,7 +25,7 @@ class MagicLinksController < ApplicationController
   def create
     email = params[:email].to_s.strip.downcase
     if email.match?(URI::MailTo::EMAIL_REGEXP)
-      token = MagicLink.generate(email: email, return_to: safe_path(params[:return_to]))
+      token = issue_magic_link(email, safe_path(params[:return_to]))
       Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
     end
     respond_to do |format|
@@ -57,38 +59,16 @@ class MagicLinksController < ApplicationController
 
   private
 
-  def sign_in_existing(user, result)
-    set_app_session(user)
-    user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at) && user.email_verified_at.blank?
-    redirect_to(safe_path(result.return_to) || root_path, notice: "Signed in. Welcome back!")
-  end
-
-  # Build → configure_new_user → save!. There is no password — email auth is
-  # magic-link only (the password_digest column, if present, stays dormant).
-  def sign_up_new(result)
-    user = User.new(email: result.email)
-    Studio.configure_new_user.call(user)
-    rescue_and_log(target: user) do
-      user.save!
-      user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at)
-      set_app_session(user)
-      redirect_to(safe_path(result.return_to) || root_path, notice: Studio.welcome_message.call(user))
+  # Mint a token in the configured store. Default :signed keeps the legacy
+  # stateless MessageVerifier link (URL: /magic_link/<token>); :database mints a
+  # Studio::Link row (URL: /l/<token>) — the short, unified scheme. The mailer
+  # builds the matching URL (see UserMailer#magic_link). sign_in_existing /
+  # sign_up_new / safe_path come from Studio::LinkConsumption.
+  def issue_magic_link(email, return_to)
+    if Studio.magic_link_store == :database
+      Studio::Link.create_magic_link(email: email, return_to: return_to).token
+    else
+      MagicLink.generate(email: email, return_to: return_to)
     end
-  rescue ActiveRecord::RecordNotUnique
-    # Two valid tokens for the same brand-new email consumed near-simultaneously
-    # both miss find_by and race to save!; the loser hits the unique index.
-    # Benign — the account now exists, so just log the winner in.
-    existing = User.find_by(email: result.email)
-    return sign_in_existing(existing, result) if existing
-
-    redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
-  rescue StandardError => e
-    Rails.logger.error("[MagicLinksController#consume] signup failed #{e.class}: #{e.message}")
-    redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
-  end
-
-  def safe_path(path)
-    p = path.to_s
-    p.start_with?("/") && !p.start_with?("//") ? p : nil
   end
 end

data/app/controllers/studio/email_images_controller.rb

@@ -0,0 +1,41 @@
+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.
+  class EmailImagesController < ApplicationController
+    before_action :require_admin
+
+    MAX_BYTES = 8.megabytes
+
+    def index
+      @variants = Studio::EmailImage.variants
+    end
+
+    # 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)
+
+      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_email_images_path, alert: message, status: :see_other
+      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."
+      end
+    rescue StandardError
+      redirect_to admin_email_images_path, alert: "Couldn't save the image. Please try again.", status: :see_other
+    end
+
+    private
+
+    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/controllers/studio/links_controller.rb

@@ -0,0 +1,65 @@
+module Studio
+  # The unified short-token link entry point — GET/POST /l/<token>. Dispatches by
+  # Studio::Link#kind:
+  #
+  #   magic_link → scanner-safe confirm interstitial (GET, inert) that auto-POSTs
+  #                to #consume, the ONLY place the single-use token is burned +
+  #                the recipient is signed in / signed up.
+  #   referral   → idempotent: capture attribution into a cookie + redirect to
+  #                the link's target (or root). Reusable + safe to prefetch, so
+  #                GET does the work (no POST step).
+  #
+  # Namespaced (not top-level Links) because mcritchie-studio already owns a
+  # public /links linktree (top-level LinksController). Apps needing richer
+  # post-consume routing (contest landing, picks rehydration, age-gate) define
+  # their own Studio::LinksController and reuse Studio::Link + the
+  # Studio::LinkConsumption building blocks.
+  class LinksController < ApplicationController
+    include Studio::LinkConsumption
+
+    skip_before_action :require_authentication
+    layout false, only: :show
+
+    # GET /l/:token
+    def show
+      response.set_header("Referrer-Policy", "strict-origin")
+      @link = Studio::Link.find_by(token: params[:token])
+
+      case @link&.kind
+      when "magic_link"
+        @token = params[:token]
+        render :confirm
+      when "referral"
+        capture_referral(@link)
+        redirect_to(@link.target || root_path)
+      else
+        redirect_to login_path, alert: "That link is invalid or has expired. Request a fresh one below."
+      end
+    end
+
+    # POST /l/:token — authoritative magic-link consume. Only magic_link kinds are
+    # consumable here; referral links are reusable and handled entirely on GET.
+    def consume
+      response.set_header("Referrer-Policy", "strict-origin")
+      link = Studio::Link.find_by(token: params[:token])
+      raise Studio::Link::InvalidToken, "not a magic link" unless link&.kind == "magic_link"
+
+      link.consume! # burns the single-use token; raises if already used / expired
+      user = User.find_by(email: link.email)
+      user ? sign_in_existing(user, link) : sign_up_new(link)
+    rescue Studio::Link::InvalidToken
+      redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
+    end
+
+    private
+
+    # Attribution rides in a cookie the app reads at signup (same :reference
+    # cookie the legacy ?ref= capture used). Value = the inviter's stable handle
+    # (slug) when available, else the link token. Capped to 64 chars.
+    def capture_referral(link)
+      inviter = link.linkable
+      ref = (inviter.respond_to?(:slug) && inviter.slug.presence) || link.token
+      cookies[:reference] = { value: ref.to_s.first(64), expires: 30.days, same_site: :lax }
+    end
+  end
+end

data/app/controllers/studio/local_emails_controller.rb

@@ -84,7 +84,11 @@ module Studio
       path =
         case record.email_key
         when /#magic_link\z/
-          "/magic_link/#{ERB::Util.url_encode(token)}"
+          # /l/<token> only when the app actually emails /l (Studio::Link store +
+          # /l routes drawn); otherwise the legacy /magic_link/<token> — covers the
+          # signed store AND apps like turf-monster that keep their own /magic_link.
+          base = Studio.magic_link_via_l_route? ? "/l" : "/magic_link"
+          "#{base}/#{ERB::Util.url_encode(token)}"
         when /#email_verification\z/
           "/email_verification/#{ERB::Util.url_encode(token)}"
         when /#wallet_export\z/

data/app/mailers/user_mailer.rb

@@ -1,4 +1,8 @@
 class UserMailer < ApplicationMailer
+  # Branded shell (banner + card) for engine-sent UserMailer emails. An app with
+  # its own UserMailer + branded_mailer layout (e.g. turf-monster) overrides both.
+  layout "branded_mailer"
+
   # Passwordless sign-in link. `email` is a raw string (the recipient may not
   # have an account yet). Token is a signed MagicLink payload (email + return_to
   # + jti, single-use). Clicking the link logs the recipient in or creates their
@@ -7,8 +11,20 @@ class UserMailer < ApplicationMailer
   # Engine GENERIC base. An app needing richer copy (e.g. turf-monster's
   # contest-aware variant) defines its own UserMailer, which wins.
   def magic_link(email, token)
-    @app_name  = Studio.app_name
-    @magic_url = magic_link_url(token: token)
+    @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
+    @banner_alt = "Your #{@app_name} sign-in link"
     mail(to: email, subject: "Your #{@app_name} sign-in link")
   end
+
+  private
+
+  # Match the emailed URL to Studio.magic_link_store: the short /l/<token> for
+  # the :database scheme, the legacy /magic_link/<token> for :signed. The
+  # request side (MagicLinksController#issue_magic_link) mints the matching token.
+  def magic_link_url_for(token)
+    Studio.magic_link_via_l_route? ? link_url(token: token) : magic_link_url(token: token)
+  end
 end

data/app/models/image_cache.rb

@@ -1,5 +1,9 @@
 class ImageCache < ApplicationRecord
-  belongs_to :owner, polymorphic: true
+  # 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-
+  # 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
 
   validates :purpose, :variant, :s3_key, presence: true
   validates :s3_key, uniqueness: true

data/app/models/studio/enumeral.rb

@@ -0,0 +1,85 @@
+module Studio
+  # A shared, DB-backed enumeration table for the whole ecosystem. Every "list of
+  # fixed, labeled, colored values" — Pokémon types (its first use), and later
+  # statuses, tiers, roles, … — is just rows in ONE studio_enumerals table,
+  # grouped by `category`. Each row is identity + presentation: a stable machine
+  # `key` ("fire"), a human `label` ("Fire"), a `color` hex ("#EE8130"), and a
+  # `position` for ordering within its category. `metadata` (jsonb) carries any
+  # category-specific extras off the columns.
+  #
+  # Shipped by the gem like Studio::Link / Studio::EmailDelivery: the model lives
+  # here, the table lives in each consumer app (copy the reference migration into
+  # db/migrate). No behavior is attached — it is pure reference data the apps
+  # read, so a consumer adopts a new category by seeding rows, no code change.
+  class Enumeral < ApplicationRecord
+    self.table_name = "studio_enumerals"
+
+    HEX = /\A#(?:\h{3}|\h{6})\z/
+
+    validates :category, presence: true
+    validates :key, presence: true,
+                    uniqueness: { scope: :category, case_sensitive: false }
+    validates :color, format: { with: HEX, message: "must be a hex color like #EE8130" },
+                      allow_blank: true
+
+    scope :in_category, ->(category) { where(category: category.to_s) }
+    scope :ordered,     -> { order(:position, :key) }
+    # By `rank` (a sparse 100/200/… domain ranking), nulls last — for categories
+    # ordered by something other than display position, e.g. most-common-first.
+    scope :by_rank,     -> { order(:rank) }
+
+    class << self
+      # True only when the table is actually migrated in this app's DB, so a
+      # consumer that hasn't installed the migration degrades to "empty" instead
+      # of crashing (mirrors Studio::EmailDelivery.available?).
+      def available?
+        connection.data_source_exists?(table_name)
+      rescue ActiveRecord::ActiveRecordError, NoMethodError
+        false
+      end
+
+      # The ordered list of a category's enumerals — the relation a view iterates
+      # (one query). Returns an empty relation when the table isn't installed yet,
+      # so callers can `.each` safely pre-migration.
+      def catalog(category)
+        return none unless available?
+
+        in_category(category).ordered
+      end
+
+      # The single enumeral for (category, key), or nil.
+      def lookup(category, key)
+        return nil unless available?
+
+        in_category(category).find_by(key: key.to_s)
+      end
+
+      # { key => color } for a category in ONE query — the shape a view wants:
+      # build it once, then look up each cell with no extra queries (avoids an
+      # N+1 when rendering many rows, e.g. the /pokemon type badges).
+      def color_map(category)
+        catalog(category).pluck(:key, :color).to_h
+      end
+
+      # Just the color for a single (category, key), with an optional fallback
+      # when the key is unknown or the table isn't installed yet.
+      def color_for(category, key, fallback: nil)
+        return fallback unless available?
+
+        in_category(category).where(key: key.to_s).limit(1).pick(:color) || fallback
+      end
+
+      # { key => emoji } for a category in ONE query — the metadata sibling of
+      # color_map, for decorative glyphs kept in `metadata` rather than a column.
+      def emoji_map(category)
+        catalog(category).pluck(:key, :metadata).to_h { |key, meta| [key, meta && meta["emoji"]] }
+      end
+    end
+
+    # A decorative glyph for the value, kept in `metadata` (not a column) since
+    # it's a presentation extra — e.g. a Pokémon type's emoji. Nil when unset.
+    def emoji
+      metadata && metadata["emoji"]
+    end
+  end
+end

data/app/models/studio/link.rb

@@ -0,0 +1,144 @@
+module Studio
+  # One table, one /l/<token> entry point, for every short-token link the apps
+  # hand out: single-use, expiring **magic_link**s and reusable, non-expiring
+  # **referral** links. `kind` selects the behavior; `metadata` (jsonb) carries
+  # the kind-specific payload (email, return_to, target, age_attested) OFF the
+  # wire so the URL is just the short random token.
+  #
+  # Generalizes turf-monster's app-local MagicLink model: adds a polymorphic
+  # `linkable` owner (the inviting User for referrals; left nil for a magic link
+  # to a not-yet-existent email — that email rides in metadata) and the `kind`
+  # discriminator. Replaces the engine's stateless MessageVerifier MagicLink
+  # service for mcritchie-studio so both apps share one short-token scheme.
+  #
+  # Like Studio::EmailDelivery, the table lives in each consumer app (copy the
+  # reference migration in db/migrate); this model is shipped by the gem.
+  class Link < ApplicationRecord
+    self.table_name = "studio_links"
+
+    class InvalidToken < StandardError; end
+
+    belongs_to :linkable, polymorphic: true, optional: true
+
+    validates :kind, inclusion: { in: Studio::LinkToken::KINDS }
+    validates :token, presence: true, uniqueness: true
+
+    scope :magic_links, -> { where(kind: "magic_link") }
+    scope :referrals,   -> { where(kind: "referral") }
+    scope :unconsumed,  -> { where(consumed_at: nil) }
+    scope :live,        -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+
+    class << self
+      # --- minting -----------------------------------------------------------
+
+      # A single-use sign-in/sign-up link. The email rides in metadata (not the
+      # URL, not a column) per the create-or-login flow — the account may not
+      # exist yet. `ttl` defaults to the app's Studio.magic_link_ttl.
+      def create_magic_link(email:, return_to: nil, age_attested: false, linkable: nil, ttl: nil)
+        ttl ||= Studio.magic_link_ttl
+        mint!(
+          kind: "magic_link",
+          linkable: linkable,
+          expires_at: ttl.from_now,
+          metadata: {
+            "email"        => Studio::LinkToken.normalize_email(email),
+            "return_to"    => Studio::LinkToken.sanitize_path(return_to),
+            "age_attested" => !!age_attested
+          }.compact
+        )
+      end
+
+      # A user's referral link is stable + reusable, keyed by its landing target
+      # so sharing contest A vs B yields distinct (but each stable) links — both
+      # crediting the same inviter. `target` is an optional same-origin path the
+      # referral redirects to (e.g. a specific contest).
+      def referral_for(linkable, target: nil)
+        wanted = Studio::LinkToken.sanitize_path(target)
+        referrals.where(linkable: linkable).live.detect { |link| link.target == wanted } ||
+          mint!(
+            kind: "referral",
+            linkable: linkable,
+            expires_at: nil,
+            metadata: { "target" => wanted }.compact
+          )
+      end
+
+      # Find by token + burn-if-single-use in one call. Raises InvalidToken for
+      # unknown / expired / already-used links. Returns the live Link.
+      def consume!(token)
+        link = find_by(token: token.to_s)
+        raise InvalidToken, "unknown link" unless link
+
+        link.consume!
+      end
+
+      private
+
+      # create! with a fresh random token, retrying the (astronomically rare)
+      # unique-index collision a couple of times before surfacing the error.
+      def mint!(attrs)
+        3.times do
+          return create!(attrs.merge(token: Studio::LinkToken.generate))
+        rescue ActiveRecord::RecordNotUnique
+          next
+        end
+        create!(attrs.merge(token: Studio::LinkToken.generate))
+      end
+    end
+
+    # --- consumption ---------------------------------------------------------
+
+    # Single-use kinds (magic_link) are atomically burned: only the first caller
+    # flips consumed_at, so a replay / double-submit loses the race and is
+    # rejected. Reusable kinds (referral) only check expiry. Returns self.
+    def consume!
+      if single_use?
+        burned = self.class.unconsumed
+                     .where(id: id)
+                     .where("expires_at IS NULL OR expires_at > ?", Time.current)
+                     .update_all(consumed_at: Time.current)
+        raise InvalidToken, "link already used or expired" if burned.zero?
+
+        self.consumed_at = Time.current
+      elsif expired?
+        raise InvalidToken, "link expired"
+      end
+      self
+    end
+
+    def single_use?
+      Studio::LinkToken.single_use?(kind)
+    end
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def consumed?
+      consumed_at.present?
+    end
+
+    def live?
+      !expired? && !(single_use? && consumed?)
+    end
+
+    # --- metadata readers (sanitized on the way out) -------------------------
+
+    def email
+      metadata && metadata["email"]
+    end
+
+    def return_to
+      Studio::LinkToken.sanitize_path(metadata && metadata["return_to"])
+    end
+
+    def target
+      Studio::LinkToken.sanitize_path(metadata && metadata["target"])
+    end
+
+    def age_attested
+      !!(metadata && metadata["age_attested"])
+    end
+    alias_method :age_attested?, :age_attested
+  end
+end

data/app/services/studio/email_image.rb

@@ -0,0 +1,85 @@
+module Studio
+  # Admin-managed banner images for transactional emails. One image per "variant"
+  # (the email type), uploaded to S3 with a stable PUBLIC url via Studio::S3 and
+  # tracked by an owner-less ImageCache row (purpose "email_banner"). The branded
+  # mailer resolves the current banner with .url; the admin email-image page
+  # writes it with .store.
+  #
+  # VARIANTS is the registry — magic_link now; adding an entry is all it takes to
+  # admin-manage another email's header image (the "extensible" part of the
+  # magic-link-now-extensible scope).
+  module EmailImage
+    PURPOSE = "email_banner".freeze
+
+    # variant => human label, in admin display order.
+    VARIANTS = {
+      "magic_link" => "Magic-link sign-in"
+    }.freeze
+
+    module_function
+
+    def variants
+      VARIANTS
+    end
+
+    def label(variant)
+      VARIANTS[variant.to_s] || variant.to_s.humanize
+    end
+
+    def known?(variant)
+      VARIANTS.key?(variant.to_s)
+    end
+
+    # The ImageCache row for this variant, or nil (no banner uploaded / table not
+    # installed yet). Nil-safe so the mailer renders bannerless before any upload.
+    def record(variant)
+      return nil unless table_ready?
+
+      ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: variant.to_s)
+    end
+
+    # Permanent public S3 url for the current banner, or nil.
+    def url(variant)
+      record(variant)&.url
+    end
+
+    # Upload bytes to S3 + upsert the ImageCache row (replacing any prior object).
+    # Returns the ::ImageCache. Raises on failure after cleaning up the new object.
+    def store(variant, io:, content_type: nil)
+      key = "email_banners/#{variant}-#{SecureRandom.hex(4)}#{ext_for(content_type)}"
+      Studio::S3.upload(key: key, body: io.read, content_type: content_type,
+                        cache_control: "public, max-age=300")
+      record = ::ImageCache.find_or_initialize_by(owner: nil, purpose: PURPOSE, variant: variant.to_s)
+      previous = record.s3_key
+      record.update!(s3_key: key)
+      delete_object(previous) if previous.present? && previous != key
+      record
+    rescue StandardError
+      delete_object(key)
+      raise
+    end
+
+    # Reference ImageCache directly so Zeitwerk autoloads it — defined?() does NOT
+    # trigger autoload, so it would read "undefined" for a not-yet-loaded const.
+    def table_ready?
+      ::ImageCache.table_exists?
+    rescue NameError, ActiveRecord::ActiveRecordError
+      false
+    end
+
+    def ext_for(content_type)
+      case content_type.to_s
+      when %r{png}    then ".png"
+      when %r{jpe?g}  then ".jpg"
+      when %r{webp}   then ".webp"
+      else ".png"
+      end
+    end
+
+    def delete_object(key)
+      Studio::S3.delete(key: key)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/views/layouts/branded_mailer.html.erb

@@ -0,0 +1,31 @@
+<%#
+  Shared branded transactional email shell. A full-bleed banner (set @banner_url,
+  e.g. from Studio::EmailImage.url(:magic_link)) sits flush at the top and sets
+  the 600px width; each email view supplies the body via yield. Bannerless is
+  fine — the card still renders. Lifted from turf-monster so every Studio app
+  shares one branded look. An app can override by defining its own
+  layouts/branded_mailer.html.erb.
+%>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="margin:0;padding:24px 0;background:#f4f5f7;">
+  <tr>
+    <td align="center" style="padding:0 12px;">
+      <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" style="width:600px;max-width:600px;background:#ffffff;border-radius:14px;overflow:hidden;box-shadow:0 1px 4px rgba(15,23,42,0.08);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
+
+        <% if @banner_url.present? %>
+          <tr>
+            <td style="padding:0;line-height:0;">
+              <img src="<%= @banner_url %>" width="600" alt="<%= @banner_alt || Studio.app_name %>"
+                   style="display:block;width:100%;max-width:600px;height:auto;border:0;" />
+            </td>
+          </tr>
+        <% end %>
+
+        <tr>
+          <td style="padding:32px 36px 36px;color:#2f3a2c;">
+            <%= yield %>
+          </td>
+        </tr>
+      </table>
+    </td>
+  </tr>
+</table>

data/app/views/magic_links/confirm.html.erb

@@ -1,96 +1,2 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width,initial-scale=1">
-    <%= csrf_meta_tags %>
-    <title>Signing you in - <%= Studio.app_name %></title>
-    <style>
-      @keyframes magic-spin { to { transform: rotate(360deg); } }
-
-      * { box-sizing: border-box; }
-
-      body {
-        margin: 0;
-        min-height: 100vh;
-        display: grid;
-        place-items: center;
-        color: #f8fafc;
-        background: <%= Studio.theme_dark %>;
-        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-      }
-
-      main { width: min(100% - 32px, 420px); text-align: center; }
-
-      .magic-spinner {
-        width: 88px;
-        height: 88px;
-        margin: 0 auto;
-        border-radius: 9999px;
-        border: 8px solid rgba(255, 255, 255, 0.14);
-        border-top-color: <%= Studio.theme_success %>;
-        animation: magic-spin 0.8s linear infinite;
-      }
-
-      .magic-fallback {
-        display: none;
-        margin-top: 2rem;
-        color: rgba(248, 250, 252, 0.8);
-      }
-
-      .magic-fallback p { margin: 0 0 1rem; font-size: 15px; }
-
-      .magic-submit {
-        display: inline-block;
-        max-width: 100%;
-        padding: 14px 34px;
-        border: 0;
-        border-radius: 8px;
-        color: #ffffff;
-        background: <%= Studio.theme_success %>;
-        font: inherit;
-        font-size: 16px;
-        font-weight: 700;
-        cursor: pointer;
-      }
-    </style>
-  </head>
-  <body>
-    <main>
-      <div class="magic-spinner" role="status" aria-label="Signing you in"></div>
-
-      <div id="magic-fallback" class="magic-fallback">
-        <p>Taking longer than expected?</p>
-        <%= button_to magic_link_consume_path(token: @token),
-              method: :post,
-              form: { id: "magic-consume-form", data: { turbo: "false" } },
-              class: "magic-submit" do %>
-          Sign in to <%= Studio.app_name %>
-        <% end %>
-      </div>
-    </main>
-
-    <noscript>
-      <style>
-        #magic-fallback { display: block !important; }
-        .magic-spinner { display: none; }
-      </style>
-    </noscript>
-
-    <script>
-      (function () {
-        var form = document.getElementById("magic-consume-form");
-        if (form && !form.dataset.autoSubmitted) {
-          form.dataset.autoSubmitted = "1";
-          if (typeof form.requestSubmit === "function") form.requestSubmit();
-          else form.submit();
-        }
-
-        setTimeout(function () {
-          var fallback = document.getElementById("magic-fallback");
-          if (fallback) fallback.style.display = "block";
-        }, 4000);
-      })();
-    </script>
-  </body>
-</html>
+<%# Legacy /magic_link/:token interstitial. Shared body in studio/_confirm_interstitial. %>
+<%= render "studio/confirm_interstitial", consume_path: magic_link_consume_path(token: @token) %>

data/app/views/studio/_confirm_interstitial.html.erb

@@ -0,0 +1,105 @@
+<%#
+  Shared scanner-safe sign-in interstitial. The GET that renders this is inert;
+  the page auto-POSTs the CSRF-protected form to `consume_path` (the only place
+  a single-use token is burned). Used by both MagicLinksController#confirm
+  (consume_path: magic_link_consume_path) and Studio::LinksController#show
+  (consume_path: link_consume_path). Rendered with layout false (full document).
+
+  Local: consume_path — the POST target that burns the token + signs in.
+%>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <title>Signing you in - <%= Studio.app_name %></title>
+    <style>
+      @keyframes magic-spin { to { transform: rotate(360deg); } }
+
+      * { box-sizing: border-box; }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        color: #f8fafc;
+        background: <%= Studio.theme_dark %>;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+
+      main { width: min(100% - 32px, 420px); text-align: center; }
+
+      .magic-spinner {
+        width: 88px;
+        height: 88px;
+        margin: 0 auto;
+        border-radius: 9999px;
+        border: 8px solid rgba(255, 255, 255, 0.14);
+        border-top-color: <%= Studio.theme_success %>;
+        animation: magic-spin 0.8s linear infinite;
+      }
+
+      .magic-fallback {
+        display: none;
+        margin-top: 2rem;
+        color: rgba(248, 250, 252, 0.8);
+      }
+
+      .magic-fallback p { margin: 0 0 1rem; font-size: 15px; }
+
+      .magic-submit {
+        display: inline-block;
+        max-width: 100%;
+        padding: 14px 34px;
+        border: 0;
+        border-radius: 8px;
+        color: #ffffff;
+        background: <%= Studio.theme_success %>;
+        font: inherit;
+        font-size: 16px;
+        font-weight: 700;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="magic-spinner" role="status" aria-label="Signing you in"></div>
+
+      <div id="magic-fallback" class="magic-fallback">
+        <p>Taking longer than expected?</p>
+        <%= button_to consume_path,
+              method: :post,
+              form: { id: "magic-consume-form", data: { turbo: "false" } },
+              class: "magic-submit" do %>
+          Sign in to <%= Studio.app_name %>
+        <% end %>
+      </div>
+    </main>
+
+    <noscript>
+      <style>
+        #magic-fallback { display: block !important; }
+        .magic-spinner { display: none; }
+      </style>
+    </noscript>
+
+    <script>
+      (function () {
+        var form = document.getElementById("magic-consume-form");
+        if (form && !form.dataset.autoSubmitted) {
+          form.dataset.autoSubmitted = "1";
+          if (typeof form.requestSubmit === "function") form.requestSubmit();
+          else form.submit();
+        }
+
+        setTimeout(function () {
+          var fallback = document.getElementById("magic-fallback");
+          if (fallback) fallback.style.display = "block";
+        }, 4000);
+      })();
+    </script>
+  </body>
+</html>

data/app/views/studio/email_images/index.html.erb

@@ -0,0 +1,41 @@
+<% content_for(:title) { "Email images" } %>
+<div class="max-w-2xl mx-auto px-4 py-8">
+  <header class="mb-6">
+    <h1 class="text-2xl font-bold">Email images</h1>
+    <p class="text-sm text-muted mt-1">
+      The banner shown at the top of branded transactional emails. Recommended
+      width 600px (it's displayed full-bleed at the top of the email card).
+    </p>
+  </header>
+
+  <% flash.each do |type, message| %>
+    <div class="mb-4 rounded-lg px-4 py-3 text-sm <%= type.to_s == "alert" ? "bg-danger/10 text-danger" : "bg-success/10 text-success" %>">
+      <%= message %>
+    </div>
+  <% end %>
+
+  <div class="space-y-6">
+    <% @variants.each do |variant, label| %>
+      <% current_url = Studio::EmailImage.url(variant) %>
+      <section class="rounded-xl border border-subtle p-5">
+        <h2 class="font-semibold mb-3"><%= label %></h2>
+
+        <div class="rounded-lg overflow-hidden border border-subtle mb-3" style="aspect-ratio: 600 / 240; background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));">
+          <% if current_url %>
+            <%= image_tag current_url, class: "w-full h-full object-cover", alt: "#{label} email banner" %>
+          <% else %>
+            <div class="w-full h-full flex items-center justify-center text-xs text-white/80 text-center px-4">
+              No image yet — emails send without a banner until you upload one.
+            </div>
+          <% end %>
+        </div>
+
+        <%= form_with url: admin_email_image_path(variant), method: :patch, html: { multipart: true }, class: "flex flex-wrap items-center gap-3" do %>
+          <%= file_field_tag :image, accept: "image/png,image/jpeg,image/webp",
+                class: "text-sm file:mr-3 file:rounded-md file:border-0 file:bg-primary file:px-3 file:py-1.5 file:text-white file:cursor-pointer" %>
+          <%= submit_tag(current_url ? "Replace image" : "Upload image", class: "btn btn-primary btn-sm") %>
+        <% end %>
+      </section>
+    <% end %>
+  </div>
+</div>

data/app/views/studio/links/confirm.html.erb

@@ -0,0 +1,2 @@
+<%# /l/:token magic-link interstitial. Shared body in studio/_confirm_interstitial. %>
+<%= render "studio/confirm_interstitial", consume_path: link_consume_path(token: @token) %>

data/app/views/user_mailer/magic_link.html.erb

@@ -1,14 +1,29 @@
-<h1>Your sign-in link</h1>
+<%# Body only — branded_mailer supplies the banner + card. Uses the theme success
+    color for the button so it matches each app. %>
+<h1 style="margin:0 0 18px;font-size:22px;line-height:1.3;color:#1f2a1c;">Your sign-in link</h1>
 
-<p>Tap the button below to sign in to <%= @app_name %>. If you don't have an
-   account yet, we'll create one for you — no password needed:</p>
+<p style="margin:0 0 24px;font-size:16px;line-height:1.6;color:#3f4a3c;">
+  Tap the button below to sign in to <strong style="color:#1f2a1c;"><%= @app_name %></strong> — no password needed.
+  If you don't have an account yet, we'll create one for you.
+</p>
 
-<p><%= link_to "Sign in to #{@app_name}", @magic_url %></p>
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" align="center" style="margin:0 auto;">
+  <tr><td align="center" bgcolor="<%= Studio.theme_success %>" style="border-radius:10px;">
+    <a href="<%= @magic_url %>" style="display:inline-block;padding:16px 40px;font-size:17px;font-weight:700;color:#ffffff;text-decoration:none;border-radius:10px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">Sign in to <%= @app_name %> 🪄</a>
+  </td></tr>
+</table>
 
-<p>If the button doesn't work, copy and paste this URL into your browser:</p>
-<p><%= @magic_url %></p>
+<p style="margin:28px 0 0;font-size:13px;line-height:1.5;color:#6b756a;text-align:center;">
+  This link is for <strong style="color:#2f3a2c;"><%= @email %></strong> and expires in <%= Studio.magic_link_ttl.in_minutes.round %> minutes — it can only be used once.
+</p>
 
-<p>Open this link on this device to finish. It expires shortly and can only be
-   used once. If you didn't request it, you can safely ignore this message.</p>
+<p style="margin:24px 0 0;font-size:12px;line-height:1.4;color:#8a948a;text-align:center;">
+  Button not working? Copy and paste this link:<br>
+  <a href="<%= @magic_url %>" style="font-size:9px;line-height:1.3;color:<%= Studio.theme_success %>;word-break:break-all;"><%= @magic_url %></a>
+</p>
 
-<p>— <%= @app_name %></p>
+<p style="margin:28px 0 0;font-size:12px;line-height:1.5;color:#8a948a;text-align:center;">
+  Didn't request this? You can safely ignore this email.
+</p>
+
+<p style="margin:20px 0 0;font-size:13px;color:#6b756a;text-align:center;">— <%= @app_name %></p>

data/db/migrate/20260620000001_create_studio_links.rb

@@ -0,0 +1,27 @@
+# Reference migration for the Studio::Link model. Like the engine's
+# studio_email_deliveries migration, each consumer app installs its own copy of
+# this into db/migrate (the adoption tasks do that) so the table is created in
+# the app's database.
+class CreateStudioLinks < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_links do |t|
+      t.string :token, null: false
+      t.string :kind, null: false
+      # Polymorphic owner — the inviting User for referrals; nil for a magic
+      # link to a not-yet-existent email (that email rides in metadata).
+      t.references :linkable, polymorphic: true, index: false
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :expires_at
+      t.datetime :consumed_at
+
+      t.timestamps
+    end
+
+    add_index :studio_links, :token, unique: true
+    add_index :studio_links, :kind
+    # Covers both "this owner's links" and "this owner's referral" lookups
+    # (referral_for) via the leading columns.
+    add_index :studio_links, [:linkable_type, :linkable_id, :kind],
+              name: "idx_studio_links_owner_kind"
+  end
+end

data/db/migrate/20260620000002_allow_null_image_cache_owner.rb

@@ -0,0 +1,9 @@
+# Lets ImageCache cache app-GLOBAL images (no owning record) — e.g. Studio::
+# EmailImage stores the admin-managed email banners owner-less. Reference
+# migration; each consumer app installs its own copy (the table is app-owned).
+class AllowNullImageCacheOwner < ActiveRecord::Migration[7.2]
+  def change
+    change_column_null :image_caches, :owner_type, true
+    change_column_null :image_caches, :owner_id, true
+  end
+end

data/db/migrate/20260623130000_create_studio_enumerals.rb

@@ -0,0 +1,30 @@
+# Reference migration for the Studio::Enumeral model. Like the engine's
+# studio_links / studio_email_deliveries migrations, each consumer app installs
+# its own copy of this into db/migrate so the table is created in the app's
+# database (the model is shipped by the gem; the table lives per app).
+class CreateStudioEnumerals < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_enumerals do |t|
+      # `category` groups a fixed set of values (e.g. "pokemon_type"); `key` is
+      # the stable machine value within it (e.g. "fire"). label/color/position
+      # are presentation; metadata (jsonb) carries any category-specific extras.
+      t.string  :category, null: false
+      t.string  :key,      null: false
+      t.string  :label
+      t.string  :color
+      t.integer :position, null: false, default: 0
+      # A sparse, gappy ordinal (100, 200, …) for a domain ranking distinct from
+      # display `position` — e.g. Pokémon types ranked most-common → least-common.
+      # The gaps leave room to insert a value between two ranks without
+      # renumbering. Nullable: not every enumeral is ranked.
+      t.integer :rank
+      t.jsonb   :metadata, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :studio_enumerals, [:category, :key], unique: true
+    add_index :studio_enumerals, [:category, :position]
+    add_index :studio_enumerals, [:category, :rank]
+  end
+end

data/lib/studio/link_token.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Studio
+  # Pure-Ruby helpers behind the Studio::Link model — token minting, the kind
+  # rules, and the input sanitizers. Kept free of ActiveRecord so it loads (and
+  # unit-tests) without a database, mirroring the other lib/studio/*.rb pure
+  # classes. The AR model (app/models/studio/link.rb) delegates to this.
+  module LinkToken
+    # The kinds of link that share the studio_links table + the /l/<token>
+    # entry point.
+    #   magic_link — single-use, short-lived passwordless sign-in / sign-up
+    #   referral   — reusable, non-expiring share link owned by a User
+    KINDS = %w[magic_link referral].freeze
+
+    # Kinds burned on first successful consume. Referral links are reusable, so
+    # they are deliberately NOT single-use.
+    SINGLE_USE_KINDS = %w[magic_link].freeze
+
+    # 96 bits of entropy → ~16 URL-safe chars (e.g. "PP-PDbEj5V3-aNh4"). Short
+    # enough to keep the URL clean, far too large to brute-force — especially
+    # for single-use, expiring magic links. Matches turf-monster's proven format.
+    TOKEN_BYTES = 12
+
+    module_function
+
+    # A fresh URL-safe token. urlsafe_base64 emits only [A-Za-z0-9_-], so the
+    # token satisfies the %r{[^/]+} route constraint and survives URL generation
+    # without extra encoding.
+    def generate
+      SecureRandom.urlsafe_base64(TOKEN_BYTES)
+    end
+
+    def kind?(kind)
+      KINDS.include?(kind.to_s)
+    end
+
+    def single_use?(kind)
+      SINGLE_USE_KINDS.include?(kind.to_s)
+    end
+
+    def normalize_email(email)
+      email.to_s.strip.downcase
+    end
+
+    # Only same-origin absolute paths survive; protocol-relative ("//evil"),
+    # absolute URLs, and blanks collapse to nil so callers fall back to a safe
+    # default redirect. Mirrors the MagicLink service's sanitizer.
+    def sanitize_path(path)
+      p = path.to_s
+      p.start_with?("/") && !p.start_with?("//") ? p : nil
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/studio.rb

@@ -6,6 +6,7 @@ require "studio/ui_primitives"
 require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
+require "studio/link_token"
 require "studio/email"
 require "studio/email_smoke"
 require "studio/mail_transport"
@@ -35,12 +36,26 @@ module Studio
   mattr_accessor :magic_link_ttl,        default: 15.minutes
   mattr_accessor :magic_link_token_name, default: "magic_link_v1"
 
+  # Where magic-link tokens are stored / which URL scheme they use.
+  #   :signed   (default) — stateless MessageVerifier MagicLink service; URL is
+  #             /magic_link/<long token>. No table needed. Back-compat default.
+  #   :database — a Studio::Link row; URL is the short /l/<token>. Requires the
+  #             studio_links table (install the reference migration). The
+  #             unified scheme both apps move to.
+  mattr_accessor :magic_link_store, default: :signed
+
   # Whether Studio.routes draws the magic_link + solana wallet routes. An app that
   # already defines its own auth routes (e.g. turf-monster, which has battle-tested
   # magic_link/solana routes + extras) sets this false to avoid duplicate route
   # NAMES at boot, keeping its own routes intact. New consumers leave it true.
   mattr_accessor :draw_auth_routes, default: true
 
+  # Whether Studio.routes draws the unified /l/<token> link routes
+  # (Studio::LinksController — magic-link confirm/consume + referral redirect).
+  # Default true; an app wanting its own /l handling sets this false and draws
+  # its own routes (it can still reuse Studio::Link + Studio::LinkConsumption).
+  mattr_accessor :draw_link_routes, default: true
+
   # 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.
@@ -135,6 +150,15 @@ module Studio
     auth_methods.include?(method.to_sym)
   end
 
+  # True when the emailed/inbox magic-link URL is the short /l/<token> — i.e.
+  # magic links are Studio::Link rows AND this app draws the /l routes. False =
+  # the legacy /magic_link/<token> path: the :signed store, OR an app on the
+  # :database store that keeps its own /magic_link route (e.g. turf-monster,
+  # whose /l is already its landing-page namespace).
+  def self.magic_link_via_l_route?
+    magic_link_store == :database && draw_link_routes
+  end
+
   def self.local_email_capture?
     return false if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
     return !!local_email_capture unless local_email_capture.nil?
@@ -247,6 +271,19 @@ module Studio
              constraints: { token: %r{[^/]+} }
       end
 
+      # Unified short-token links — /l/<token> for magic sign-in links + referral
+      # links (Studio::Link). Studio::LinksController dispatches by kind: a
+      # magic_link renders the scanner-safe confirm interstitial then POSTs to
+      # consume; a referral captures attribution + redirects. Helpers: link_path
+      # / link_url(token:) and link_consume_path. Drawn for every consumer
+      # (including draw_auth_routes=false apps) unless draw_link_routes is off.
+      if Studio.draw_link_routes
+        get  "l/:token", to: "studio/links#show",    as: :link,
+             constraints: { token: %r{[^/]+} }
+        post "l/:token", to: "studio/links#consume", as: :link_consume,
+             constraints: { token: %r{[^/]+} }
+      end
+
       # Solana / Phantom wallet sign-in (nonce challenge + signature verify).
       # The browser posts to these literal paths from the shared Connect-Wallet
       # flow; app-specific surfaces (mobile deep-link callback, account-linking,
@@ -263,6 +300,13 @@ module Studio
       patch "admin/theme",            to: "theme_settings#update",     as: :admin_theme_update
       post  "admin/theme/regenerate", to: "theme_settings#regenerate", as: :admin_theme_regenerate
       get   "admin/schema",           to: "schema#index",              as: :admin_schema
+
+      # 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.
+      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,
+            constraints: { variant: /[a-z_]+/ }
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-20 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -148,6 +148,7 @@ files:
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/error_handling.rb
 - app/controllers/concerns/studio/impersonation.rb
+- app/controllers/concerns/studio/link_consumption.rb
 - app/controllers/error_logs_controller.rb
 - app/controllers/magic_links_controller.rb
 - app/controllers/navbar_controller.rb
@@ -156,6 +157,8 @@ files:
 - app/controllers/schema_controller.rb
 - app/controllers/sessions_controller.rb
 - app/controllers/solana_sessions_controller.rb
+- app/controllers/studio/email_images_controller.rb
+- app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
@@ -171,9 +174,12 @@ files:
 - app/models/image_cache.rb
 - app/models/session_context.rb
 - app/models/studio/email_delivery.rb
+- app/models/studio/enumeral.rb
+- app/models/studio/link.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
 - app/services/magic_link.rb
+- app/services/studio/email_image.rb
 - app/views/components/_admin_dropdown.html.erb
 - app/views/components/_avatar.html.erb
 - app/views/components/_avatar_cropper.html.erb
@@ -192,6 +198,7 @@ files:
 - app/views/error_logs/index.html.erb
 - app/views/error_logs/show.html.erb
 - app/views/layouts/_navbar.html.erb
+- app/views/layouts/branded_mailer.html.erb
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.html.erb
 - app/views/magic_links/confirm.html.erb
@@ -200,6 +207,7 @@ files:
 - app/views/schema/index.html.erb
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
+- app/views/studio/_confirm_interstitial.html.erb
 - app/views/studio/_cropper_assets.html.erb
 - app/views/studio/admin_models/_arenas_table.html.erb
 - app/views/studio/admin_models/_teams_table.html.erb
@@ -211,6 +219,8 @@ files:
 - app/views/studio/banners/_email_status_button.html.erb
 - app/views/studio/banners/_environment.html.erb
 - app/views/studio/banners/_impersonation.html.erb
+- app/views/studio/email_images/index.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
 - app/views/studio/modals/_host.html.erb
@@ -224,6 +234,9 @@ files:
 - app/views/user_mailer/magic_link.html.erb
 - app/views/user_mailer/magic_link.text.erb
 - db/migrate/20260614000000_create_studio_email_deliveries.rb
+- db/migrate/20260620000001_create_studio_links.rb
+- db/migrate/20260620000002_allow_null_image_cache_owner.rb
+- db/migrate/20260623130000_create_studio_enumerals.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/color_scale.rb
@@ -231,6 +244,7 @@ files:
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
 - lib/studio/image_cache.rb
+- lib/studio/link_token.rb
 - lib/studio/mail_transport.rb
 - lib/studio/s3.rb
 - lib/studio/theme_resolver.rb