studio-engine 0.17.0 → 0.19.0

data/app/controllers/magic_links_controller.rb

@@ -15,6 +15,7 @@
 # sign_in_existing / sign_up_new building blocks.
 class MagicLinksController < ApplicationController
   include Studio::LinkConsumption
+  include Studio::MagicLinkIssuing
 
   skip_before_action :require_authentication
   layout false, only: :confirm
@@ -57,18 +58,8 @@ class MagicLinksController < ApplicationController
     redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
   end
 
-  private
-
-  # 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
-  end
+  # issue_magic_link (mint in the configured store) comes from
+  # Studio::MagicLinkIssuing, shared with UserMailer — which builds the URL that
+  # consumes it — so the mint and its landing URL cannot drift apart.
+  # sign_in_existing / sign_up_new / safe_path come from Studio::LinkConsumption.
 end

data/app/controllers/studio/local_emails_controller.rb

@@ -23,7 +23,7 @@ module Studio
     private
 
     def require_local_development!
-      head :not_found if Rails.env.production? || !request.local?
+      head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
     end
 
     def delivery_records

data/app/controllers/studio/local_reviews_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Studio
+  # GET /_studio/local_review?email=<who>&return_to=<path> — the LOCAL half of
+  # the task board's WAITING APPROVAL button.
+  #
+  # Why it must live here, on the local app. A magic link signs the recipient
+  # into the app that MINTED it: the token is a row (or a signed blob) in that
+  # app's own store, and Studio::LinkToken.sanitize_path keeps `return_to` a
+  # same-origin PATH. So a link minted by the production board can only ever
+  # land on production — no matter what host the path belongs to. The board
+  # therefore stops minting and REDIRECTS here, to the local server named by the
+  # task's local_url, which mints in its own database and lands the operator
+  # signed-in on the page under review.
+  #
+  # It mints for whatever email it is handed, unauthenticated — so it is bound
+  # to the same floor as the local email inbox (Studio::LocalEmailsController):
+  # never in production, and only for a loopback request. That is the same
+  # exposure the inbox already carries, which hands every captured sign-in link
+  # to any local reader. It is a development desk convenience; it is not a
+  # sign-in path.
+  class LocalReviewsController < ApplicationController
+    include Studio::MagicLinkIssuing
+
+    skip_before_action :require_authentication, raise: false
+
+    before_action :require_local_development!
+
+    def show
+      email = Studio::LinkToken.normalize_email(params[:email])
+      return redirect_to(login_path, alert: MISSING_EMAIL) unless email.match?(URI::MailTo::EMAIL_REGEXP)
+
+      # return_to is passed through raw: BOTH stores sanitize it to a same-origin
+      # path on the way in (Studio::Link.create_magic_link and MagicLink.generate
+      # each call Studio::LinkToken.sanitize_path). Re-sanitizing here would be a
+      # second spelling of a rule that already has one owner — and a mutation run
+      # confirmed it guards nothing the store does not already guard.
+      token = issue_magic_link(email, params[:return_to])
+      redirect_to magic_link_url_for(token), allow_other_host: false
+    end
+
+    private
+
+    MISSING_EMAIL = "Add ?email=<your address> to mint a local review link."
+
+    def require_local_development!
+      head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
+    end
+  end
+end

data/app/controllers/style_controller.rb

@@ -0,0 +1,25 @@
+# The living style guide — a single admin-gated page (/admin/style) that renders
+# the engine's shared UI primitives (buttons, surfaces, the seven motion
+# primitives, the leveling badges, and the theme role tokens) live in the host
+# app's theme. Mirrors ThemeSettingsController: a plain host-inherited controller,
+# gated by `require_admin` from the already-included Studio::ErrorHandling concern.
+# The view is a bare content wrapper that renders inside each host's
+# application.html.erb, so it inherits that app's navbar + theme automatically.
+#
+# Reached at /admin/style (helper admin_style_path). The legacy /admin/design_system
+# route redirects here and keeps its admin_design_system_path helper resolving, so a
+# shipped host sidebar link that still points at the old helper keeps working.
+class StyleController < ApplicationController
+  before_action :require_admin
+
+  # Load the live theme so the Theme section (the landing section, folded in from
+  # /admin/theme) shows this app's saved colors + the CSRF-protected editor.
+  # Best-effort: the section renders from Studio.theme_config defaults when no
+  # ThemeSetting row exists, so a load hiccup must not take the whole page down.
+  def index
+    @theme_setting  = ThemeSetting.current if defined?(ThemeSetting)
+    @theme_defaults = Studio.theme_config  if Studio.respond_to?(:theme_config)
+  rescue StandardError => e
+    Rails.logger.warn("[style] theme preload skipped: #{e.message}")
+  end
+end

data/app/mailers/user_mailer.rb

@@ -1,4 +1,10 @@
 class UserMailer < ApplicationMailer
+  # magic_link_url_for — the URL that consumes the token, matched to
+  # Studio.magic_link_store. Shared with the issuers that MINT the token
+  # (MagicLinksController, Studio::LocalReviewsController) so the two halves
+  # cannot drift apart.
+  include Studio::MagicLinkIssuing
+
   # 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"
@@ -18,13 +24,4 @@ class UserMailer < ApplicationMailer
     @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/views/studio/modals/_crop_photo.html.erb

@@ -21,8 +21,12 @@
 
   Single root: lives inside the host's <template x-if>, so only the outer
   div is the top-level element here.
+
+  Local: store — Alpine store name this modal is mounted in. Default "modals".
+  The living style guide passes store: "dsModals" for its page-scoped host.
 %>
-<div x-data="cropPhotoModal()">
+<% crop_store = local_assigns.fetch(:store, "modals") %>
+<div x-data="cropPhotoModal({ store: '<%= crop_store %>' })">
   <h3 class="text-heading font-bold text-lg text-center mb-4">Crop Photo</h3>
 
   <template x-if="error">

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

@@ -8,6 +8,11 @@
   store registration, and the window.StudioModals.holdAtLeast(ms)
   helper. The animation keyframes ship inline in the style block
   below, so consumers need no extra CSS to get the full behavior.
+  A canonical copy of the SAME keyframes also lives in the shared
+  motion layer (app/assets/tailwind/studio_engine/engine-motion.css)
+  for pages that drive a modal host WITHOUT rendering this partial —
+  e.g. the living style guide's page-scoped dsModals host. The two are
+  byte-identical; keep them in sync if you retune a curve or duration.
   Consumer integration example and API reference: the "Modal host"
   section of the gem README.
 %>

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

@@ -26,6 +26,11 @@
   function cropPhotoModal(opts) {
     opts = opts || {};
     return {
+      // Which Alpine store this modal is mounted in. Defaults to 'modals' (the
+      // shared host); the living style guide passes { store: 'dsModals' } so the
+      // crop-photo modal opens on its page-scoped host without colliding with
+      // the app-level shared host.
+      _storeName: opts.store || 'modals',
       cropper: null,
       imageUrl: null,
       fromParent: false,
@@ -46,7 +51,7 @@
       dispatch: false,
 
       init() {
-        var current = this.$store.modals.current();
+        var current = this.$store[this._storeName].current();
         var props = (current && current.props) || {};
         if (props.aspectRatio) this.aspectRatio = props.aspectRatio;
         if (props.maxWidth) this.maxWidth = props.maxWidth;
@@ -77,8 +82,14 @@
           });
           // Cropping in progress — lock the modal (no click-outside / escape) so
           // an accidental click doesn't discard the crop. Cancel still works.
-          var cur = self.$store.modals.current();
-          if (cur && cur.props) cur.props.dismissible = false;
+          // Also reflect the crop sub-state onto the store entry (cropReady) so
+          // an external observer can tell the picker state apart from the crop
+          // state — the modal's own `imageUrl` is LOCAL x-data and never lands on
+          // props, so props alone can't distinguish them. The living style guide
+          // reads this to move its active-card glow from the Image Upload card to
+          // the Crop Photo card the moment an image is loaded (picker -> cropper).
+          var cur = self.$store[self._storeName].current();
+          if (cur && cur.props) { cur.props.dismissible = false; cur.props.cropReady = true; }
         });
       },
 
@@ -112,7 +123,7 @@
 
       cancel() {
         if (this.cropper) { this.cropper.destroy(); this.cropper = null; }
-        this.$store.modals.close();
+        this.$store[this._storeName].close();
       },
 
       confirm() {
@@ -134,7 +145,7 @@
           // dispatch mode: the opener's host owns the post-confirm flow
           // (processing modal -> success toast), so don't pop the stack here.
           // fromParent (no dispatch): close the modal now.
-          if (!self.dispatch) self.$store.modals.close();
+          if (!self.dispatch) self.$store[self._storeName].close();
         }, "image/png");
       }
     };

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

@@ -1,7 +1,11 @@
 <%# Generic "saving" loading card, opened by window.submitFormWithProgress with
     a { title } prop while a Turbo form uploads. Register it in your modal-host
-    block alongside crop-photo. Single root for the host's <template x-if>. %>
+    block alongside crop-photo. Single root for the host's <template x-if>.
+
+    Local: store — Alpine store name backing the title read. Default "modals".
+    The living style guide passes store: "dsModals" for its page-scoped host. %>
+<% saving_store = local_assigns.fetch(:store, "modals") %>
 <div>
   <%= render "studio/modals/blocks/processing_card",
-        title_key: "$store.modals.current()?.props?.title || 'Saving…'" %>
+        title_key: "$store.#{saving_store}.current()?.props?.title || 'Saving…'" %>
 </div>

data/app/views/studio/modals/auth/_resend_footer.html.erb

@@ -0,0 +1,25 @@
+<%#
+  Resend-link + error + Close footer, shared by the auth modal's
+  magic-link-sent and magic-link-resent steps (identical in both). Ported from
+  turf-monster. Rendered INSIDE each step's root <div> (so the parent
+  <template x-if>'s single-root rule is unaffected) and within the auth modal's
+  x-data scope, so props.* and resendMagicLink() resolve from the host
+  component. Resend is a LINK; disabled during an in-flight resend and the 60s
+  cooldown, which it counts down inline. Keep this free of double-quotes and
+  backticks inside the Alpine expressions.
+
+  Locals:
+    modal_store — Alpine store name backing close(). Default "modals".
+%>
+<%
+  modal_store = local_assigns.fetch(:modal_store, "modals")
+%>
+<button @click="resendMagicLink()" :disabled="props.submitting === 'magic-link' || (props.resendCooldown || 0) > 0"
+        class="block mx-auto text-sm text-primary hover:text-primary-300 underline underline-offset-2 disabled:opacity-50 disabled:no-underline">
+  <span class="inline-flex items-center justify-center gap-1.5">
+    <span x-show="props.submitting === 'magic-link'" class="spinner" aria-hidden="true"></span>
+    <span x-text="props.submitting === 'magic-link' ? 'Resending…' : ((props.resendCooldown || 0) > 0 ? ('Resend available in ' + props.resendCooldown + 's') : 'Resend link')"></span>
+  </span>
+</button>
+<p x-show="props.resendError" x-cloak class="text-xs text-red-400 mt-3 text-center" x-text="props.resendError"></p>
+<button @click="$store.<%= modal_store %>.close()" class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">Close</button>

data/app/views/studio/modals/blocks/_card_header.html.erb

@@ -0,0 +1,83 @@
+<%#
+  Shared modal card header — icon pill + title + subtext. Owns the visual top
+  of every success / confirmation / status modal so the header style stays
+  aligned across the family. Each callsite slots its own action area (button,
+  link, hold button) BELOW this header. Ported from turf-monster into the engine
+  (studio-engine v0.18) so the shared modal blocks live in one place.
+
+  Locals (all optional except title/title_key):
+    title:          static title string
+    title_key:      Alpine expression for the title (x-text). Priority over title.
+    subtitle:       static subtext string
+    subtitle_key:   Alpine expression for the subtext (x-text). Priority over subtitle.
+    icon_color:     color token for the default check — 'primary' (default),
+                    'success', 'warning', 'mint'.
+    icon_emoji:     large emoji (text-5xl, no pill) instead of the default check.
+    icon_emoji_key: Alpine expression returning the emoji (x-text). Priority
+                    over icon_emoji.
+    icon:           :error — X mark in a red pill (hard error states).
+                    :external_tab — diagonal arrow pill (action in another tab).
+    spinner:        truthy — three bouncing dots instead of the check pill,
+                    for processing / loading states.
+    size:           :md (default) OR :lg (celebration end-state, text-3xl title).
+
+  Block: if given, the block's content replaces the subtitle area. Explicit
+  subtitle locals are checked BEFORE block_given? — a partial's block_given? can
+  read TRUE off the layout yield even with no block passed (see the engine's
+  Rails-partial block_given? note), so lead with the locals.
+%>
+<%
+  icon_color = local_assigns[:icon_color] || 'primary'
+  size       = local_assigns[:size] || :md
+  pill_class = size == :lg ? 'w-14 h-14' : 'w-12 h-12'
+  svg_class  = size == :lg ? 'w-7 h-7'   : 'w-6 h-6'
+  title_cls  = size == :lg ? 'text-3xl font-bold text-heading mb-2' : 'text-lg font-bold text-heading mb-2'
+  sub_cls    = size == :lg ? 'text-sm text-secondary mb-4'          : 'text-xs text-secondary mb-5'
+%>
+<div class="text-center">
+  <% if local_assigns[:spinner] %>
+    <div class="mx-auto <%= pill_class %> flex items-center justify-center mb-4">
+      <div class="loading-dots">
+        <span></span>
+        <span></span>
+        <span></span>
+      </div>
+    </div>
+  <% elsif local_assigns[:icon] == :error %>
+    <div class="mx-auto <%= pill_class %> rounded-full bg-red-500/15 flex items-center justify-center mb-4">
+      <svg class="<%= svg_class %> text-red-400" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12"/>
+      </svg>
+    </div>
+  <% elsif local_assigns[:icon] == :external_tab %>
+    <div class="mx-auto <%= pill_class %> rounded-full bg-<%= icon_color %>/15 flex items-center justify-center mb-4">
+      <svg class="<%= svg_class %> text-<%= icon_color %>" fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M4.5 19.5l15-15m0 0H8.25m11.25 0v11.25"/>
+      </svg>
+    </div>
+  <% elsif local_assigns[:icon_emoji_key] %>
+    <div class="text-5xl mb-4 leading-none" x-text="<%= icon_emoji_key %>"></div>
+  <% elsif local_assigns[:icon_emoji] %>
+    <div class="text-5xl mb-4 leading-none"><%= icon_emoji %></div>
+  <% else %>
+    <div class="mx-auto <%= pill_class %> rounded-full bg-<%= icon_color %>/15 flex items-center justify-center mb-4">
+      <svg class="<%= svg_class %> text-<%= icon_color %>" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/>
+      </svg>
+    </div>
+  <% end %>
+
+  <% if local_assigns[:title_key] %>
+    <h3 class="<%= title_cls %>" x-text="<%= title_key %>"></h3>
+  <% elsif local_assigns[:title] %>
+    <h3 class="<%= title_cls %>"><%= title %></h3>
+  <% end %>
+
+  <% if local_assigns[:subtitle_key] %>
+    <p class="<%= sub_cls %>" x-text="<%= subtitle_key %>"></p>
+  <% elsif local_assigns[:subtitle] %>
+    <p class="<%= sub_cls %>"><%= subtitle %></p>
+  <% elsif block_given? %>
+    <p class="<%= sub_cls %>"><%= yield %></p>
+  <% end %>
+</div>

data/app/views/studio/modals/blocks/_cta_redirect.html.erb

@@ -0,0 +1,73 @@
+<%#
+  Primary CTA with a drain animation that auto-redirects when the countdown
+  hits zero. Used on celebration cards where the user is leaving the modal
+  anyway — the drain is both a progress bar AND a click-now affordance. Ported
+  from turf-monster.
+
+  The drain always plays. The redirect is gated:
+    - URL truthy → drains, then window.location = URL
+    - URL null   → drains; timer fires a no-op, a click falls through to
+                   closing the modal (so a gallery preview stays alive).
+
+  Locals (optional except href_key):
+    href_key         — Alpine expression: the destination URL or null. Re-read
+                       inside the timer fire so callers can lazy-resolve.
+    label_html       — Button label HTML. Default "Continue".
+    label_key        — Alpine expression returning the label (x-text). Priority
+                       over label_html.
+    duration_seconds — Drain + redirect timer in seconds. Default 5.
+    modal_store      — Alpine store name backing close(). Default "modals".
+
+  Co-located x-data self-manages the timer. Keep the x-data free of
+  double-quotes and backticks — it is a double-quoted HTML attribute.
+%>
+<%
+  href_key         = local_assigns.fetch(:href_key)
+  label_html       = local_assigns.fetch(:label_html, "Continue")
+  duration_seconds = local_assigns.fetch(:duration_seconds, 5)
+  modal_store      = local_assigns.fetch(:modal_store, "modals")
+%>
+<div x-data="{
+       _redirectTimer: null,
+       redirecting: false,
+       go(url) {
+         if (!url) return false;
+         this.redirecting = true;
+         try { window.location.href = url; } catch (_) {}
+         return true;
+       },
+       init() {
+         var self = this;
+         self._redirectTimer = setTimeout(function () {
+           self._redirectTimer = null;
+           self.go(<%= href_key %>);
+         }, <%= duration_seconds * 1000 %>);
+       },
+       destroy() {
+         if (this._redirectTimer) { clearTimeout(this._redirectTimer); this._redirectTimer = null; }
+       }
+     }">
+  <a :href="(<%= href_key %>) || '#'"
+     @click="
+       if (redirecting) { $event.preventDefault(); return; }
+       if ($event.metaKey || $event.ctrlKey || $event.shiftKey) return;
+       $event.preventDefault();
+       var u = (<%= href_key %>);
+       if (u) { go(u); } else { $store.<%= modal_store %>.close(); }
+     "
+     :class="redirecting ? 'pointer-events-none' : ''"
+     :aria-disabled="redirecting ? 'true' : 'false'"
+     class="btn btn-primary btn-lg w-full relative overflow-hidden no-underline">
+    <div class="absolute inset-0 pointer-events-none origin-left"
+         x-show="!redirecting"
+         style="background: rgba(255,255,255,0.18); animation: studio-modal-drain <%= duration_seconds %>s linear forwards;"></div>
+    <% if local_assigns[:label_key] %>
+      <span class="relative z-10" x-show="!redirecting" x-text="<%= label_key %>"></span>
+    <% else %>
+      <span class="relative z-10" x-show="!redirecting"><%= label_html.html_safe %></span>
+    <% end %>
+    <span class="relative z-10 inline-flex items-center justify-center" x-show="redirecting" x-cloak>
+      <span class="spinner" style="--spinner-color: currentColor" aria-hidden="true"></span>
+    </span>
+  </a>
+</div>

data/app/views/studio/modals/blocks/_onchain_success.html.erb

@@ -0,0 +1,52 @@
+<%#
+  Generic on-chain transaction success card — the default-fallback success
+  state for any Solana transaction that isn't a domain-specific celebration
+  (faucet mint, on-chain rename, contest creation). Ported from turf-monster.
+
+  Same visual spine as a rich entry card (card_header at :lg with the primary
+  check pill + branded Solana tx link) MINUS the enrichments: no seeds bar, no
+  level-up, no auto-redirect drain. The CTA is a plain optional link; when no
+  cta label/href is supplied the card degrades to just the Dismiss link.
+
+  Single root: content lives in one <div> so Alpine's <template x-if> clones it
+  whole.
+
+  Locals:
+    tx_signature_key — Alpine expression returning the tx hash (link mounts when truthy)
+    title_key        — Alpine expression returning the headline
+    subtitle_key     — Alpine expression returning the sub-headline
+    cta_label_key    — Alpine expression returning the CTA label (button mounts when truthy)
+    cta_href_key     — Alpine expression returning the CTA href
+    cluster_param    — explorer cluster query, forwarded to solana_tx_link. Default "".
+    modal_store      — Alpine store name backing close(). Default "modals".
+%>
+<%
+  tx_signature_key = local_assigns.fetch(:tx_signature_key)
+  title_key        = local_assigns.fetch(:title_key)
+  subtitle_key     = local_assigns.fetch(:subtitle_key)
+  cta_label_key    = local_assigns.fetch(:cta_label_key)
+  cta_href_key     = local_assigns.fetch(:cta_href_key)
+  cluster_param    = local_assigns.fetch(:cluster_param, "")
+  modal_store      = local_assigns.fetch(:modal_store, "modals")
+%>
+<div>
+  <%= render "studio/modals/blocks/card_header",
+        size: :lg,
+        icon_color: 'primary',
+        title_key:    title_key,
+        subtitle_key: subtitle_key %>
+
+  <%= render "studio/modals/blocks/solana_tx_link",
+        tx_signature_key: tx_signature_key, cluster_param: cluster_param %>
+
+  <template x-if="(<%= cta_label_key %>)">
+    <a :href="(<%= cta_href_key %>) || '#'"
+       class="btn btn-primary btn-lg w-full no-underline"
+       x-text="<%= cta_label_key %>"></a>
+  </template>
+
+  <button @click="$store.<%= modal_store %>.close()"
+          class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+    Dismiss
+  </button>
+</div>

data/app/views/studio/modals/blocks/_progress_pill.html.erb

@@ -0,0 +1,23 @@
+<%#
+  Segmented progress pill — N rounded bars in a row, the first `current`
+  filled in primary, the rest muted outlines. Drops into any wizard-style modal
+  step to show position in a multi-step flow. Ported from turf-monster.
+
+  Locals:
+    current — 1-indexed step number to fill up to (current: 2, total: 3 fills
+              2/3). Required.
+    total   — total segment count. Default 3.
+%>
+<%
+  current = local_assigns.fetch(:current)
+  total   = local_assigns.fetch(:total, 3)
+%>
+<div class="flex items-center justify-center gap-1.5 mx-auto max-w-[200px] mb-4">
+  <% total.times do |i| %>
+    <% if (i + 1) <= current %>
+      <div class="h-1.5 flex-1 rounded-full bg-primary"></div>
+    <% else %>
+      <div class="h-1.5 flex-1 rounded-full bg-inset border border-subtle"></div>
+    <% end %>
+  <% end %>
+</div>

data/app/views/studio/modals/blocks/_shell.html.erb

@@ -0,0 +1,35 @@
+<%#
+  Shared modal shell — opt-in convenience wrapper for a title row + close ×.
+  Ported from turf-monster. Wrap content with:
+    render layout: "studio/modals/blocks/shell", locals: { title: "…" } do … end
+
+  Locals (all optional):
+    title       — top-row title string.
+    dismissible — default true; suppress the close button when false. (The host
+                  gates escape + click-outside on props.dismissible at open()
+                  time, not this flag.)
+    modal_store — Alpine store name backing close(). Default "modals".
+%>
+<%
+  shell_title       = local_assigns[:title]
+  shell_dismissible = local_assigns.fetch(:dismissible, true)
+  modal_store       = local_assigns.fetch(:modal_store, "modals")
+%>
+<div>
+  <% if shell_title || shell_dismissible %>
+    <div class="flex items-start justify-between gap-3 -mt-2 -mr-2 mb-3">
+      <% if shell_title %>
+        <h3 class="text-heading font-bold text-lg leading-tight pt-1"><%= shell_title %></h3>
+      <% else %>
+        <span></span>
+      <% end %>
+      <% if shell_dismissible %>
+        <button type="button" @click="$store.<%= modal_store %>.close()"
+                class="text-secondary hover:text-heading text-xl leading-none flex-shrink-0"
+                aria-label="Close">&times;</button>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%= yield %>
+</div>

data/app/views/studio/modals/blocks/_solana_tx_link.html.erb

@@ -0,0 +1,42 @@
+<%#
+  Branded Solana explorer tx link — gradient Solana mark + truncated signature
+  + external-link glyph in a subtle bordered pill. Shared by the on-chain
+  success cards (studio/modals/blocks/_onchain_success and a consumer's entry
+  card). Mounts only when the signature expression is truthy. Ported from
+  turf-monster; the cluster query is a plain local so the engine partial carries
+  no Solana::Config dependency.
+
+  Only one success card is ever in the DOM at a time, so the fixed gradient id
+  is collision-safe.
+
+  Locals:
+    tx_signature_key — Alpine expression returning the Solana tx hash. Required.
+    cluster_param    — appended to the explorer URL (e.g. "?cluster=devnet").
+                       Default "" (mainnet).
+%>
+<%
+  tx_signature_key = local_assigns.fetch(:tx_signature_key)
+  cluster_param    = local_assigns.fetch(:cluster_param, "")
+%>
+<template x-if="(<%= tx_signature_key %>)">
+  <div class="text-center mb-3 -mt-1">
+    <a :href="'https://explorer.solana.com/tx/' + (<%= tx_signature_key %>) + '<%= cluster_param %>'"
+       target="_blank" rel="noopener"
+       class="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg border border-subtle hover:border-primary/50 transition group no-underline"
+       style="background: rgb(var(--color-primary-500-rgb) / 0.06);">
+      <svg width="14" height="11" viewBox="0 0 397 311" fill="none">
+        <defs><linearGradient id="tx-solana-grad" x1="361" y1="-9" x2="153" y2="389" gradientUnits="userSpaceOnUse">
+          <stop offset="0" stop-color="#00FFA3"/><stop offset="1" stop-color="#DC1FFF"/>
+        </linearGradient></defs>
+        <path d="M65 234c2-2 6-4 9-4h317c6 0 9 7 5 11l-63 63c-2 2-6 4-9 4H6c-6 0-9-7-5-11l64-63z" fill="url(#tx-solana-grad)"/>
+        <path d="M65 4c2-2 6-4 9-4h317c6 0 9 7 5 11l-63 63c-2 2-6 4-9 4H6c-6 0-9-7-5-11L65 4z" fill="url(#tx-solana-grad)"/>
+        <path d="M333 119c-2-2-6-4-9-4H7c-6 0-9 7-5 11l63 63c2 2 6 4 9 4h317c6 0 9-7 5-11l-63-63z" fill="url(#tx-solana-grad)"/>
+      </svg>
+      <span class="font-mono text-[11px] text-secondary group-hover:text-primary transition"
+            x-text="(<%= tx_signature_key %>) ? ((<%= tx_signature_key %>).substring(0, 16) + '…') : ''"></span>
+      <svg class="w-3 h-3 text-muted group-hover:text-primary transition" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"/>
+      </svg>
+    </a>
+  </div>
+</template>

data/app/views/studio/modals/shared/_age_attestation.html.erb

@@ -0,0 +1,34 @@
+<%#
+  Legal-age attestation checkbox — underwriting compliance for skill-based
+  contests. Ported from turf-monster into the engine. Binds x-model into the
+  caller's Alpine scope; the caller gates its CTAs on that property. The SERVER
+  is the real boundary — every signup endpoint rejects new account creation
+  without the attestation.
+
+  Unlike the turf-monster original, this engine partial does NOT self-gate on an
+  AppFlags flag — a consumer that wants the attestation renders it; one that
+  doesn't simply omits the render. Callers that omit it initialize their
+  ageAttested Alpine state to true so every CTA gate passes.
+
+  Locals (all optional):
+    x_model     — Alpine model target (default "ageAttested")
+    error_model — Alpine error-flag target (default "ageError")
+%>
+<%
+  x_model     = local_assigns.fetch(:x_model, "ageAttested")
+  error_model = local_assigns.fetch(:error_model, "ageError")
+%>
+<div>
+  <label class="flex items-start gap-2.5 text-xs text-secondary leading-snug cursor-pointer select-none">
+    <input type="checkbox" x-model="<%= x_model %>" @change="<%= error_model %> = false"
+           data-age-attestation
+           class="mt-0.5 w-4 h-4 shrink-0 rounded accent-primary cursor-pointer">
+    <span>
+      I confirm I am of legal age to participate in skill-based contests in my
+      state (18+ in most states; 19+ in AL/NE; 21+ in IA/MA/VA).
+    </span>
+  </label>
+  <p x-show="<%= error_model %>" x-cloak class="text-xs text-red-400 mt-1.5 ml-6">
+    Please confirm you are of legal age to continue.
+  </p>
+</div>