studio-engine 0.5.9 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cba132c4901014fde9dfb1404661065d526eebf7c3db40f29198413bf6aee994
-  data.tar.gz: 676040a89d09f62b86f3bf25ffa8a07418d9976900377e8dbdab0c8088194687
+  metadata.gz: '0817243bffbcd834fd5a3d8f593a420b12d8fba691c48337b68e6661ebbe5d7c'
+  data.tar.gz: 5328f4a61db1c6c8965a0291bf0573a1e71b9e83b29e8eafe0a974b5208a0487
 SHA512:
-  metadata.gz: c33acfe1016923235e9de220b719922b9885b4da918205004b18337722d07c17f2077a67d5fe7074c48202cd01cb193fc49fe0669bcf9ea02dd0325362a6a1a2
-  data.tar.gz: cbe15ef16f573cba78e7bf494da84b68e144f0cd0790695f8393f5d37a022ec37e6b1562a6be5babeab53eed61f35c8fd7f4fa544b60e540d2ab337f1a0dc3cd
+  metadata.gz: 642c7e82c5576ed3565091922473f6da39d3ab5388d5affb5d6c4a7dda9be7f037dda006e5ead66f61ba711701ad0fbd7cb0038227d102e7fc962a22c0fb888d
+  data.tar.gz: 8457efd67516bc2bcb42bc440cf6ff628c9153be16d0064bb8d3998f21d4c9a4f96e6b15a6978c08d8aa97d0f965a94a368f1a5df734589d4a08b61af60a2e7b

data/CHANGELOG.md

@@ -4,6 +4,27 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## v0.5.10 (2026-06-15)
+
+### Added
+- **`Studio::AdminModels`** shared controller concern plus shared admin model
+  index/show shells and teams/arenas table partials. Consumer apps define their
+  model registry and scopes locally, while shared pagination, team sorting,
+  sport emoji display, team JSON modal payloads, and model page framing live in
+  the engine.
+- **Shared operator primitives** under `studio/banners/*` for non-production
+  environment banners, the shared banner button, Dev Mode controls, email
+  connector status, and admin impersonation banners. Consumers can render
+  `studio/banners/environment` and `studio/banners/impersonation`.
+- **`Studio::Impersonation`** opt-in concern for Act As session conventions:
+  `true_user`, `impersonated_user`, `impersonating?`,
+  `start_impersonation_session`, and `clear_impersonation_session`. Consumer
+  apps still own authorization, audit logging, routes, and app-specific safety
+  rules.
+- **`StudioEmailDeliveryHelper#email_delivery_banner_details`** returns the
+  structured connector, provider icon, send/capture state, and tooltip used by
+  the shared email status button.
+
 ## v0.5.9 (2026-06-14)
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Shared Rails engine for McRitchie apps. Provides authentication, error handling,
 gem "studio-engine", "~> 0.5"
 ```
 
-Then `bundle install`. The current release is **v0.5.9**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+Then `bundle install`. The current release is **v0.5.10**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
 
 > Published to RubyGems as of v0.4.0 (2026-05-17). New installs should use the RubyGems form, which the consumer Rails apps (`mcritchie-studio`, `turf-monster`) already use.
 
@@ -20,6 +20,7 @@ Then `bundle install`. The current release is **v0.5.9**; see [`CHANGELOG.md`](.
 - **Authentication**: Passwordless magic-link auth, optional password auth, Google OAuth via OmniAuth, Solana wallet sign-in, and optional one-way SSO patterns
 - **Error handling**: `Studio::ErrorHandling` concern with `rescue_and_log`, `ErrorLog` model with `capture!`, error log viewer at `/error_logs`
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
+- **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
 
@@ -68,6 +69,48 @@ This draws the enabled auth routes (`/login`, `/signup`, `/logout`, magic-link r
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
+## Non-Production Banners
+
+Consumer layouts can render the shared environment banner inside their sticky
+header:
+
+```erb
+<%= render "studio/banners/environment", devnet: false %>
+```
+
+The environment banner includes:
+
+- a Dev Mode toggle button backed by `Alpine.store("devMode")`
+- an Email status button that links to `/_studio/local_emails`
+- a send/capture signal plus SES/Resend/unknown connector icon
+
+Apps with admin Act As / impersonation state can render the matching banner
+with their own users and return route:
+
+```erb
+<%= render "studio/banners/impersonation",
+           impersonated_user: current_user,
+           admin_user: true_user,
+           stop_path: admin_stop_impersonating_path %>
+```
+
+The engine also provides an optional `Studio::Impersonation` concern for the
+session convention:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Studio::ErrorHandling
+  include Studio::Impersonation
+end
+```
+
+The concern adds `true_user`, `impersonated_user`, `impersonating?`,
+`start_impersonation_session(target_user, actor:)`, and
+`clear_impersonation_session`. Consumer apps still own the authorization rule,
+audit log, enter/exit controller actions, and any app-specific safeguards such
+as binding session-token checks to `true_user` or disabling wallet-only
+privileges while impersonating.
+
 ## 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/concerns/studio/admin_models.rb

@@ -0,0 +1,122 @@
+module Studio
+  module AdminModels
+    extend ActiveSupport::Concern
+
+    PREVIEW_LIMIT = 10
+    PER_PAGE = 25
+    TEAM_SORTS = {
+      "team" => "LOWER(teams.name)",
+      "sport" => "LOWER(COALESCE(teams.sport, ''))",
+      "league" => "LOWER(COALESCE(teams.league, ''))"
+    }.freeze
+    SHARED_TABLE_KEYS = %w[teams arenas].freeze
+
+    included do
+      before_action :set_model_config, only: :show
+      helper_method :team_sort_url, :team_sort_indicator, :team_sport_emoji,
+                    :team_record_json, :admin_models_table_partial
+    end
+
+    def index
+      @sections = admin_model_configs.map do |key, config|
+        scope = admin_model_scope_for(key)
+        {
+          key: key,
+          label: config.fetch(:label),
+          description: config.fetch(:description),
+          count: scope.count,
+          records: scope.limit(PREVIEW_LIMIT)
+        }
+      end
+
+      render "studio/admin_models/index"
+    end
+
+    def show
+      @page = [params[:page].to_i, 1].max
+      @total_count = @scope.count
+      @total_pages = [(@total_count.to_f / PER_PAGE).ceil, 1].max
+      @records = @scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE)
+
+      render "studio/admin_models/show"
+    end
+
+    private
+
+    def set_model_config
+      @key = params[:key].to_s
+      @config = admin_model_configs.fetch(@key) { raise ActiveRecord::RecordNotFound }
+      @scope = admin_model_scope_for(@key)
+    end
+
+    def admin_model_configs
+      self.class::MODELS
+    end
+
+    def admin_model_scope_for(_key)
+      raise NotImplementedError, "#{self.class.name} must implement #admin_model_scope_for"
+    end
+
+    def team_sort_key
+      TEAM_SORTS.key?(params[:sort].to_s) ? params[:sort].to_s : "team"
+    end
+
+    def team_sort_direction
+      params[:direction].to_s == "desc" ? "desc" : "asc"
+    end
+
+    def team_sort_order
+      direction = team_sort_direction == "desc" ? "DESC" : "ASC"
+      expression = TEAM_SORTS.fetch(team_sort_key)
+      Arel.sql("#{expression} #{direction}, LOWER(teams.name) ASC")
+    end
+
+    def team_sort_url(key)
+      query = request.query_parameters.merge(
+        "sort" => key,
+        "direction" => team_sort_key == key && team_sort_direction == "asc" ? "desc" : "asc"
+      )
+      query.delete("page")
+
+      "#{request.path}?#{query.to_query}"
+    end
+
+    def team_sort_indicator(key)
+      return "" unless team_sort_key == key
+
+      team_sort_direction
+    end
+
+    def team_sport_emoji(team)
+      case team.sport.to_s
+      when "football" then "🏈"
+      when "soccer" then "⚽"
+      when "basketball" then "🏀"
+      when "baseball" then "⚾"
+      when "hockey" then "🏒"
+      else "•"
+      end
+    end
+
+    def team_record_json(team)
+      payload = team.attributes.merge("mascot" => team.mascot)
+      payload["home_arena"] = team.home_arena&.attributes if team.respond_to?(:home_arena)
+
+      JSON.pretty_generate(payload)
+    end
+
+    def admin_models_table_partial(key)
+      shared_table_keys = if self.class.const_defined?(:SHARED_TABLE_KEYS, false)
+        self.class::SHARED_TABLE_KEYS
+      else
+        SHARED_TABLE_KEYS
+      end
+
+      if shared_table_keys.map(&:to_s).include?(key.to_s)
+        "studio/admin_models/#{key}_table"
+      else
+        "admin/models/#{key}_table"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+require "time"
+
+module Studio
+  module Impersonation
+    extend ActiveSupport::Concern
+
+    included do
+      if respond_to?(:helper_method)
+        helper_method :true_user, :impersonated_user, :impersonating?, :impersonation_started_at
+      end
+    end
+
+    private
+
+    # The real session owner. While acting as another user, this remains the
+    # admin/operator account whose session token should be verified.
+    def true_user
+      return @true_user if defined?(@true_user)
+
+      @true_user = User.find_by(id: session[Studio.session_key])
+    end
+
+    # The currently visible user. Consumers with extra wallet or privilege state
+    # can override this and still call true_user/impersonating? from the concern.
+    def current_user
+      return @current_user if defined?(@current_user)
+
+      @current_user = impersonating? ? impersonated_user : true_user
+    end
+
+    def impersonated_user
+      return @impersonated_user if defined?(@impersonated_user)
+
+      @impersonated_user = User.find_by(id: session[Studio.impersonation_target_session_key])
+    end
+
+    def impersonating?
+      return @impersonating if defined?(@impersonating)
+
+      @impersonating = compute_impersonating?
+    end
+
+    def start_impersonation_session(target_user, actor: true_user)
+      session[Studio.impersonation_actor_session_key] = actor.id
+      session[Studio.impersonation_target_session_key] = target_user.id
+      session[Studio.impersonation_started_at_session_key] = Time.current.iso8601
+      reset_impersonation_memoization
+    end
+
+    def clear_impersonation_session
+      session.delete(Studio.impersonation_actor_session_key)
+      session.delete(Studio.impersonation_target_session_key)
+      session.delete(Studio.impersonation_started_at_session_key)
+      reset_impersonation_memoization
+    end
+
+    def impersonation_started_at
+      raw = session[Studio.impersonation_started_at_session_key]
+      return nil if raw.blank?
+
+      return raw if raw.is_a?(Time)
+
+      zone = Time.zone if Time.respond_to?(:zone)
+      zone ? zone.parse(raw.to_s) : Time.parse(raw.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def compute_impersonating?
+      return false if session[Studio.impersonation_target_session_key].blank?
+      return false unless true_user&.respond_to?(:admin?) && true_user.admin?
+      return false unless impersonation_started_at
+      return false if impersonation_started_at < Studio.impersonation_max_minutes.to_i.minutes.ago
+
+      target = impersonated_user
+      target.present? &&
+        (!target.respond_to?(:admin?) || !target.admin?) &&
+        target.id != true_user.id
+    rescue StandardError
+      false
+    end
+
+    def reset_impersonation_memoization
+      remove_instance_variable(:@current_user) if defined?(@current_user)
+      remove_instance_variable(:@true_user) if defined?(@true_user)
+      remove_instance_variable(:@impersonated_user) if defined?(@impersonated_user)
+      remove_instance_variable(:@impersonating) if defined?(@impersonating)
+    end
+  end
+end

data/app/helpers/studio_email_delivery_helper.rb

@@ -2,12 +2,29 @@ module StudioEmailDeliveryHelper
   NON_DELIVERING_EMAIL_METHODS = %w[test file].freeze
 
   def email_delivery_banner_status
+    details = email_delivery_banner_details
+
+    "EMAIL SEND #{details.fetch(:sends_email)} · #{details.fetch(:transport)}"
+  end
+
+  def email_delivery_banner_details
     delivery_method = studio_email_delivery_method
     capture_enabled = Studio.local_email_capture?
     sends_email = studio_email_perform_deliveries? && !capture_enabled &&
                   !NON_DELIVERING_EMAIL_METHODS.include?(delivery_method)
+    transport = email_delivery_transport_label(delivery_method, capture_enabled)
+    connector = email_delivery_connector(delivery_method, transport)
 
-    "EMAIL SEND #{sends_email} · #{email_delivery_transport_label(delivery_method, capture_enabled)}"
+    {
+      connector: connector,
+      connector_label: email_delivery_connector_label(connector),
+      email_state: sends_email ? "Sending" : "Captured",
+      provider_icon: email_delivery_provider_icon(connector),
+      sends_email: sends_email,
+      status_icon: sends_email ? "✅" : "❌",
+      tooltip: "Connector: #{email_delivery_connector_label(connector)} · Emails: #{sends_email ? "Sending" : "Captured"}",
+      transport: transport
+    }
   end
 
   def email_delivery_transport_label(delivery_method = studio_email_delivery_method,
@@ -21,6 +38,29 @@ module StudioEmailDeliveryHelper
 
   private
 
+  def email_delivery_connector(delivery_method, transport)
+    return "ses" if Studio.ses_transport_ready?
+    return "resend" if delivery_method == "resend"
+    return transport if %w[ses resend].include?(transport)
+
+    nil
+  end
+
+  def email_delivery_connector_label(connector)
+    case connector
+    when "ses" then "SES"
+    when "resend" then "Resend"
+    else "Unknown"
+    end
+  end
+
+  def email_delivery_provider_icon(connector)
+    case connector
+    when "ses" then "ses-favicon.png"
+    when "resend" then "resend-favicon.png"
+    end
+  end
+
   def studio_email_delivery_method
     return "unknown" unless defined?(ActionMailer)
 

data/app/views/studio/admin_models/_arenas_table.html.erb

@@ -0,0 +1,43 @@
+<%# locals: (records:) %>
+<div class="overflow-x-auto">
+  <table id="models-arenas-table" class="w-full min-w-[940px] text-sm">
+    <thead class="bg-surface-alt text-muted text-xs uppercase tracking-wide">
+      <tr>
+        <th class="px-4 py-3 text-left font-semibold">Arena</th>
+        <th class="px-4 py-3 text-left font-semibold">Address</th>
+        <th class="px-4 py-3 text-left font-semibold">Location</th>
+        <th class="px-4 py-3 text-left font-semibold">Home Teams</th>
+        <th class="px-4 py-3 text-left font-semibold">Timezone</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-subtle">
+      <% records.each do |arena| %>
+        <tr class="hover:bg-surface-alt/60 transition">
+          <td class="px-4 py-3">
+            <div class="font-semibold text-heading truncate"><%= arena.name %></div>
+            <div class="text-xs text-muted font-mono truncate"><%= arena.slug %></div>
+          </td>
+          <td class="px-4 py-3 text-muted"><%= arena.address.presence || "-" %></td>
+          <td class="px-4 py-3 text-muted">
+            <%= [arena.location, arena.country].compact_blank.join(" / ").presence || "-" %>
+          </td>
+          <td class="px-4 py-3 text-muted">
+            <% if arena.home_teams.any? %>
+              <%= arena.home_teams.map(&:short_name).join(", ") %>
+            <% else %>
+              <span class="inline-flex items-center px-2 py-1 rounded text-[11px] font-bold uppercase bg-surface-alt text-secondary">
+                schedule-only
+              </span>
+            <% end %>
+          </td>
+          <td class="px-4 py-3 text-muted font-mono text-xs"><%= arena.timezone.presence || "-" %></td>
+        </tr>
+      <% end %>
+      <% if records.empty? %>
+        <tr>
+          <td colspan="5" class="px-4 py-10 text-center text-muted">No arenas found.</td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/studio/admin_models/_teams_table.html.erb

@@ -0,0 +1,112 @@
+<%# locals: (records:) %>
+<div class="overflow-x-auto">
+  <table id="models-teams-table" class="w-full min-w-[1040px] text-sm">
+    <thead class="bg-surface-alt text-muted text-xs uppercase tracking-wide">
+      <tr>
+        <th class="px-4 py-3 text-left font-semibold">
+          <%= link_to team_sort_url("team"), class: "inline-flex items-center gap-1 hover:text-heading" do %>
+            <span>Team</span>
+            <% if team_sort_indicator("team").present? %>
+              <span class="text-[10px] lowercase"><%= team_sort_indicator("team") %></span>
+            <% end %>
+          <% end %>
+        </th>
+        <th class="w-16 px-2 py-3 text-center font-semibold">
+          <%= link_to team_sort_url("sport"), class: "inline-flex items-center justify-center gap-1 hover:text-heading" do %>
+            <span>Sport</span>
+            <% if team_sort_indicator("sport").present? %>
+              <span class="text-[10px] lowercase"><%= team_sort_indicator("sport") %></span>
+            <% end %>
+          <% end %>
+        </th>
+        <th class="px-4 py-3 text-left font-semibold">
+          <%= link_to team_sort_url("league"), class: "inline-flex items-center gap-1 hover:text-heading" do %>
+            <span>League</span>
+            <% if team_sort_indicator("league").present? %>
+              <span class="text-[10px] lowercase"><%= team_sort_indicator("league") %></span>
+            <% end %>
+          <% end %>
+        </th>
+        <th class="px-4 py-3 text-left font-semibold">Conference / Division</th>
+        <th class="px-4 py-3 text-left font-semibold">Location</th>
+        <th class="px-4 py-3 text-left font-semibold">Home Arena</th>
+        <th class="px-4 py-3 text-left font-semibold">Logo</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-subtle">
+      <% records.each do |team| %>
+        <tr class="hover:bg-surface-alt/60 transition">
+          <td class="px-4 py-3">
+            <div x-data="{ open: false }">
+              <button type="button"
+                      data-team-json-trigger="<%= team.slug %>"
+                      class="w-full flex items-center gap-3 text-left rounded hover:text-primary focus:outline-none focus:ring-2 focus:ring-primary/40"
+                      aria-label="Open JSON for <%= team.name %>"
+                      @click="open = true">
+                <span class="text-xl flex-shrink-0"><%= team.emoji.presence || "*" %></span>
+                <span class="min-w-0">
+                  <span class="block font-semibold text-heading truncate"><%= team.name %></span>
+                  <span class="block text-xs text-muted font-mono truncate"><%= team.short_name %> / <%= team.slug %></span>
+                </span>
+              </button>
+
+              <template x-teleport="body">
+                <div x-show="open"
+                     x-cloak
+                     class="fixed inset-0 z-[130] flex items-center justify-center bg-black/70 p-4"
+                     role="dialog"
+                     aria-modal="true"
+                     aria-label="<%= team.name %> JSON"
+                     @keydown.escape.window="open = false"
+                     @click.self="open = false">
+                  <div class="w-full max-w-3xl rounded-lg border border-strong bg-surface shadow-2xl">
+                    <div class="flex items-center justify-between gap-4 border-b border-subtle px-4 py-3">
+                      <div class="min-w-0">
+                        <h3 class="text-heading font-semibold truncate"><%= team.name %></h3>
+                        <p class="text-xs text-muted font-mono truncate"><%= team.slug %></p>
+                      </div>
+                      <button type="button" class="btn btn-outline btn-sm" @click="open = false">Close</button>
+                    </div>
+                    <pre class="max-h-[75vh] overflow-auto bg-inset p-4 text-xs text-secondary"><%= team_record_json(team) %></pre>
+                  </div>
+                </div>
+              </template>
+            </div>
+          </td>
+          <td class="w-16 px-2 py-3 text-center">
+            <span class="inline-flex w-8 items-center justify-center text-lg leading-none"
+                  title="<%= team.sport.presence || "unknown sport" %>">
+              <%= team_sport_emoji(team) %>
+            </span>
+          </td>
+          <td class="px-4 py-3">
+            <span class="inline-flex items-center px-2 py-1 rounded text-[11px] font-bold uppercase bg-surface-alt text-secondary">
+              <%= team.league.presence || "-" %>
+            </span>
+          </td>
+          <td class="px-4 py-3 text-muted">
+            <%= [team.conference, team.division].compact_blank.join(" / ").presence || "-" %>
+          </td>
+          <td class="px-4 py-3 text-muted"><%= team.location.presence || "-" %></td>
+          <td class="px-4 py-3 text-muted"><%= team.home_arena&.name || "-" %></td>
+          <td class="px-4 py-3 text-muted">
+            <% logo_path = team.respond_to?(:logo_path) ? team.logo_path : nil %>
+            <% logo_url = team.respond_to?(:logo_url) ? team.logo_url : nil %>
+            <% logo_source = team.respond_to?(:logo_source) ? team.logo_source : nil %>
+            <% if logo_path.present? || logo_url.present? %>
+              <div class="max-w-[180px] truncate font-mono text-xs"><%= logo_path.presence || logo_url %></div>
+              <div class="text-[11px] text-muted"><%= logo_source.presence || "source pending" %></div>
+            <% else %>
+              <span class="text-xs text-muted">not set</span>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+      <% if records.empty? %>
+        <tr>
+          <td colspan="7" class="px-4 py-10 text-center text-muted">No teams found.</td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

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

@@ -0,0 +1,31 @@
+<% content_for(:title, "Models - Admin") %>
+
+<div class="max-w-7xl mx-auto px-4 py-8 space-y-6">
+  <header class="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
+    <div>
+      <p class="text-xs text-muted uppercase tracking-wide font-semibold">Admin QA</p>
+      <h1 class="text-heading text-2xl font-bold mt-1">Models</h1>
+      <p class="text-muted text-sm mt-1">Ten-row snapshots for records that need quick inspection.</p>
+    </div>
+    <%= link_to "Back to dashboard", admin_dashboard_path, class: "btn btn-outline" %>
+  </header>
+
+  <div class="space-y-5">
+    <% @sections.each do |section| %>
+      <section id="model-<%= section.fetch(:key) %>" class="card overflow-hidden">
+        <div class="px-4 py-4 border-b border-subtle flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div>
+            <h2 class="text-heading text-lg font-semibold"><%= section.fetch(:label) %></h2>
+            <p class="text-xs text-muted"><%= section.fetch(:description) %></p>
+          </div>
+          <div class="flex items-center gap-3">
+            <span class="text-xs text-muted">Showing <%= section.fetch(:records).size %> of <%= section.fetch(:count) %></span>
+            <%= link_to "View all", admin_model_path(section.fetch(:key)), class: "text-xs text-primary hover:underline" %>
+          </div>
+        </div>
+
+        <%= render admin_models_table_partial(section.fetch(:key)), records: section.fetch(:records) %>
+      </section>
+    <% end %>
+  </div>
+</div>

data/app/views/studio/admin_models/show.html.erb

@@ -0,0 +1,37 @@
+<% content_for(:title, "#{@config.fetch(:label)} - Models - Admin") %>
+
+<div class="max-w-7xl mx-auto px-4 py-8 space-y-6">
+  <header class="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
+    <div>
+      <p class="text-xs text-muted uppercase tracking-wide font-semibold">Admin Models</p>
+      <h1 class="text-heading text-2xl font-bold mt-1"><%= @config.fetch(:label) %></h1>
+      <p class="text-muted text-sm mt-1">
+        <%= @config.fetch(:description) %>.
+        Page <%= @page %> of <%= @total_pages %>, <%= @total_count %> total.
+      </p>
+    </div>
+    <%= link_to "Back to models", admin_models_path, class: "btn btn-outline" %>
+  </header>
+
+  <section class="card overflow-hidden">
+    <%= render admin_models_table_partial(@key), records: @records %>
+  </section>
+
+  <nav class="flex items-center justify-between gap-3" aria-label="<%= @config.fetch(:label) %> pagination">
+    <% if @page > 1 %>
+      <%= link_to "Previous", admin_model_path(@key, page: @page - 1), class: "btn btn-outline" %>
+    <% else %>
+      <span class="btn btn-outline opacity-50 pointer-events-none">Previous</span>
+    <% end %>
+
+    <span class="text-xs text-muted">
+      Showing <%= @records.size %> records on page <%= @page %>
+    </span>
+
+    <% if @page < @total_pages %>
+      <%= link_to "Next", admin_model_path(@key, page: @page + 1), class: "btn btn-outline" %>
+    <% else %>
+      <span class="btn btn-outline opacity-50 pointer-events-none">Next</span>
+    <% end %>
+  </nav>
+</div>

data/app/views/studio/banners/_app_banner.html.erb

@@ -0,0 +1,35 @@
+<%
+  tone = local_assigns.fetch(:tone, :environment).to_sym
+  density = local_assigns.fetch(:density, :normal).to_sym
+  message = local_assigns.fetch(:message)
+  actions = local_assigns[:actions]
+
+  tones = {
+    environment: {
+      background: "linear-gradient(90deg, #9d174d 0%, #f72585 100%)",
+      color: "#ffffff",
+      shadow: "0 2px 8px rgba(0,0,0,0.25)"
+    },
+    impersonation: {
+      background: "linear-gradient(90deg, #b91c1c 0%, #d97706 100%)",
+      color: "#ffffff",
+      shadow: "0 2px 8px rgba(0,0,0,0.25)"
+    }
+  }
+
+  density_styles = {
+    compact: "font-size:12px; font-weight:700; padding:2px 12px;",
+    normal: "font-size:14px; font-weight:700; padding:8px 16px;"
+  }
+
+  style = tones.fetch(tone)
+%>
+
+<div class="w-full" style="background:<%= style.fetch(:background) %>; color:<%= style.fetch(:color) %>; box-shadow:<%= style.fetch(:shadow) %>;">
+  <div class="max-w-7xl mx-auto flex items-center justify-between gap-3" style="<%= density_styles.fetch(density) %>">
+    <span class="min-w-0 truncate"><%= message %></span>
+    <% if actions.present? %>
+      <div class="shrink-0 flex items-center gap-2"><%= actions %></div>
+    <% end %>
+  </div>
+</div>

data/app/views/studio/banners/_button.html.erb

@@ -0,0 +1,89 @@
+<%
+  label = local_assigns[:label]
+  content = local_assigns[:content] || label
+  href = local_assigns[:href]
+  as = local_assigns.fetch(:as, href.present? ? :link : :button).to_sym
+  method = local_assigns[:method]
+  tooltip = local_assigns[:tooltip]
+  aria_label = local_assigns[:aria_label] || tooltip || label.to_s
+  variant = local_assigns.fetch(:variant, :outline).to_sym
+  hover_text_color = local_assigns.fetch(:hover_text_color, "#be185d")
+
+  base_class = "group relative inline-flex items-center font-semibold rounded px-3 py-1 whitespace-nowrap gap-2 focus-visible:outline focus-visible:outline-2 focus-visible:outline-white/90"
+  classes = [base_class, local_assigns[:class]].compact.join(" ")
+
+  tooltip_show = tooltip.present? ? "var t=this.querySelector('[data-studio-banner-tooltip]'); if(t){t.style.opacity='1';}" : ""
+  tooltip_hide = tooltip.present? ? "var t=this.querySelector('[data-studio-banner-tooltip]'); if(t){t.style.opacity='0';}" : ""
+
+  if variant == :solid
+    default_background = local_assigns.fetch(:background, "#ffffff")
+    default_border = local_assigns.fetch(:border_color, "#ffffff")
+    default_color = local_assigns.fetch(:text_color, hover_text_color)
+    hover_background = local_assigns.fetch(:hover_background, "#fff7ed")
+    hover_border = local_assigns.fetch(:hover_border_color, hover_background)
+    hover_color = local_assigns.fetch(:hover_text_color, default_color)
+  else
+    default_background = "transparent"
+    default_border = "rgba(255,255,255,0.9)"
+    default_color = "#ffffff"
+    hover_background = "#ffffff"
+    hover_border = "#ffffff"
+    hover_color = hover_text_color
+  end
+
+  base_style = [
+    "appearance:none",
+    "background:#{default_background}",
+    "border:1px solid #{default_border}",
+    "color:#{default_color}",
+    "cursor:pointer",
+    "font:inherit",
+    "font-weight:700",
+    "text-decoration:none",
+    "position:relative",
+    "transition:background-color 150ms ease, color 150ms ease, border-color 150ms ease"
+  ].join("; ")
+
+  show_styles = "this.style.background='#{hover_background}'; this.style.borderColor='#{hover_border}'; this.style.color='#{hover_color}';#{tooltip_show}"
+  hide_styles = "this.style.background='#{default_background}'; this.style.borderColor='#{default_border}'; this.style.color='#{default_color}';#{tooltip_hide}"
+
+  attrs = {
+    class: classes,
+    style: base_style,
+    title: tooltip,
+    "aria-label": aria_label.presence,
+    onmouseover: show_styles,
+    onmouseout: hide_styles,
+    onfocus: show_styles,
+    onblur: hide_styles
+  }.compact
+
+  attrs[:"@click"] = local_assigns[:alpine_click] if local_assigns[:alpine_click].present?
+
+  if tooltip.present?
+    tooltip_content = capture do
+%>
+      <span data-studio-banner-tooltip
+            class="pointer-events-none absolute right-0 top-full z-[140] mt-2 w-max max-w-[260px] rounded bg-white px-3 py-2 text-xs font-semibold text-slate-900 opacity-0 shadow-lg ring-1 ring-black/10 transition-opacity duration-150 group-hover:opacity-100 group-focus-visible:opacity-100"
+            style="position:absolute; right:0; top:100%; z-index:140; margin-top:8px; max-width:260px; width:max-content; border-radius:4px; background:#ffffff; color:#111827; padding:8px 12px; font-size:12px; font-weight:700; line-height:1.2; opacity:0; pointer-events:none; box-shadow:0 8px 18px rgba(0,0,0,0.18); transition:opacity 150ms ease;">
+        <%= tooltip %>
+      </span>
+<%
+    end
+  end
+%>
+
+<% if as == :button %>
+  <%= button_tag attrs.merge(type: "button") do %>
+    <%= content %><%= tooltip_content if tooltip.present? %>
+  <% end %>
+<% elsif method.present? %>
+  <%= button_to href,
+                attrs.merge(method: method, form_class: local_assigns.fetch(:form_class, "shrink-0")) do %>
+    <%= content %><%= tooltip_content if tooltip.present? %>
+  <% end %>
+<% else %>
+  <%= link_to href, attrs do %>
+    <%= content %><%= tooltip_content if tooltip.present? %>
+  <% end %>
+<% end %>

data/app/views/studio/banners/_dev_mode_button.html.erb

@@ -0,0 +1,4 @@
+<%= render "studio/banners/button",
+           as: :button,
+           label: "DEV MODE",
+           alpine_click: "$store.devMode = !$store.devMode; localStorage.setItem('devMode', $store.devMode)" %>

data/app/views/studio/banners/_email_status_button.html.erb

@@ -0,0 +1,23 @@
+<% details = email_delivery_banner_details %>
+
+<% content = capture do %>
+  <span>Email</span>
+  <span aria-hidden="true"><%= details.fetch(:status_icon) %></span>
+  <% if details[:provider_icon].present? %>
+    <%= image_tag details.fetch(:provider_icon),
+                  alt: "",
+                  "aria-hidden": true,
+                  width: 20,
+                  height: 20,
+                  class: "rounded",
+                  style: "width:20px; height:20px; object-fit:cover;" %>
+  <% else %>
+    <span aria-hidden="true">❓</span>
+  <% end %>
+<% end %>
+
+<%= render "studio/banners/button",
+           href: "/_studio/local_emails",
+           label: "Email",
+           content: content,
+           tooltip: details.fetch(:tooltip) %>

data/app/views/studio/banners/_environment.html.erb

@@ -0,0 +1,18 @@
+<%
+  environment_label = local_assigns.fetch(:environment_label, "#{Rails.env.capitalize} Environment")
+  devnet = local_assigns.fetch(:devnet, false)
+%>
+
+<% actions = capture do %>
+  <% if devnet %>
+    <span class="rounded" style="font-size:10px; font-weight:700; padding:1px 6px; background:rgba(0,0,0,0.2);">DEVNET</span>
+  <% end %>
+  <%= render "studio/banners/dev_mode_button" %>
+  <%= render "studio/banners/email_status_button" %>
+<% end %>
+
+<%= render "studio/banners/app_banner",
+           tone: :environment,
+           density: :normal,
+           message: environment_label,
+           actions: actions %>

data/app/views/studio/banners/_impersonation.html.erb

@@ -0,0 +1,24 @@
+<%
+  impersonated_user = local_assigns.fetch(:impersonated_user)
+  admin_user = local_assigns.fetch(:admin_user)
+  stop_path = local_assigns.fetch(:stop_path)
+%>
+
+<% message = capture do %>
+  Logged in as <strong><%= impersonated_user.display_name %></strong><span class="hidden sm:inline" style="opacity:0.85;"> - admin impersonation</span>
+<% end %>
+<% actions = capture do %>
+  <%= render "studio/banners/button",
+             href: stop_path,
+             method: :delete,
+             variant: :solid,
+             label: "Return to #{admin_user.display_name}",
+             text_color: "#b91c1c",
+             hover_text_color: "#b91c1c" %>
+<% end %>
+
+<%= render "studio/banners/app_banner",
+           tone: :impersonation,
+           density: :normal,
+           message: message,
+           actions: actions %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.5.9"
+  VERSION = "0.5.10"
 end

data/lib/studio.rb

@@ -39,6 +39,14 @@ module Studio
   # NAMES at boot, keeping its own routes intact. New consumers leave it true.
   mattr_accessor :draw_auth_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.
+  mattr_accessor :impersonation_target_session_key, default: :impersonated_user_id
+  mattr_accessor :impersonation_actor_session_key,  default: :true_admin_id
+  mattr_accessor :impersonation_started_at_session_key, default: :impersonation_started_at
+  mattr_accessor :impersonation_max_minutes, default: 30
+
   # Default From: for engine-sent mail (magic links). Apps set this to their
   # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.5.9
+  version: 0.5.10
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -140,8 +139,12 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- app/assets/images/resend-favicon.png
+- app/assets/images/ses-favicon.png
 - app/controllers/concerns/solana/session_auth.rb
+- app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/error_handling.rb
+- app/controllers/concerns/studio/impersonation.rb
 - app/controllers/error_logs_controller.rb
 - app/controllers/magic_links_controller.rb
 - app/controllers/navbar_controller.rb
@@ -193,6 +196,16 @@ files:
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.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
+- app/views/studio/admin_models/index.html.erb
+- app/views/studio/admin_models/show.html.erb
+- app/views/studio/banners/_app_banner.html.erb
+- app/views/studio/banners/_button.html.erb
+- app/views/studio/banners/_dev_mode_button.html.erb
+- 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/local_emails/index.html.erb
 - app/views/studio/modals/_crop_photo.html.erb
 - app/views/studio/modals/_host.html.erb
@@ -230,7 +243,6 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -245,8 +257,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching