studio-engine 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e37d3038ae5d72bbd0829247f562aa744960458dc9e54faa73c38fc1a2adcb83
-  data.tar.gz: a74cb5455f9977009b3499981dec577bb7df9782a5ab2f08a2bda92fe9cbe9c5
+  metadata.gz: ecc09d648e749381eed240dbdf6290e6899bfff776a08a8cf76e8cf6fde5da35
+  data.tar.gz: bfa162a9a1078281ce421fcc9dcb4b3741fc30ab8bc9147b8eedbd7cee9a825b
 SHA512:
-  metadata.gz: 45ecd0d11aef5443dc5342013e39124b52ecf67b46261b096e45a57b088a22335e5ce7c1b58f894c0878888cd1dc087b886f76e7ed15875ec08759222a52ae74
-  data.tar.gz: 2e1b9c6dd268214317af8a93aa27bf49e1aa2ebff4e487010a81fd5f332ee261a0d1011fb636cbd9577dd3300c23ba0b1edc6e40e7b56366d83c7314d40a0636
+  metadata.gz: d1cc7ce640975c429a0f85ea08cdc66037506efa681995128ad4a3ab76bf0894d1e60bf4738c3d52bc85a2625ea6ee21b60a420b3eef98af56008f0de33f92d5
+  data.tar.gz: fd4465c53f2591ff8031fcebee0ce81dfa7acc1113a934b98983a761ad54a2a9a6d4dff8c8b6b1c41b7c8947166f36d69dbf4da182c7e8713b4eb986c79ee6f3

data/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.25.0 — 2026-07-28
+
+**Profile Leveling** — the `/admin/style` "Leveling activities" section is rebuilt
+into a single toggle-driven "Profile Leveling" flow, and the with-leveling /
+without-leveling FORK is killed. Previously each activity shipped as TWO modal
+ids (`change-username` + `change-username-plain`, `quest-activity` +
+`quest-activity-plain`), because the primitive read `leveling` from a Ruby local
+at render time. Now the primitive reads `leveling` at RUNTIME from the modal
+store's `props.leveling`, so ONE id per activity flips the Turf Monster shape
+(the seeds celebration + Free Entry Token progress) ↔ the McRitchie Studio shape
+(plain input + Save, then a simple confirmation) live as its per-card leveling
+toggle moves.
+
+### Changed
+
+- **`studio/modals/blocks/_leveling_activity`** — three views now, all ALWAYS
+  rendered and gated by the reactive `leveling` getter instead of dropped at ERB
+  time: the **form** (`!celebrate`), the **seeds celebration**
+  (`celebrate && leveling`, TM), and a **plain confirmation**
+  (`celebrate && !leveling`, MS). The `leveling` local becomes the render-time
+  fallback only. **The "Quest N of N" counter pill is removed** — the profile
+  modals do not carry one. **The "Level N" pill is also dropped** from the
+  celebration (no consumer used it); the seeds bar stays. All existing seams
+  are preserved unchanged (`submit_url`, `finalize_hook`, `saved_event`,
+  `modal_store`, `demo`, seeds/level props), so Turf Monster's live usage and the
+  opaque save-callback contract are unaffected (TM ships no `props.leveling` and
+  keeps its `:leveling`-capability default).
+- **`studio/_leveling_activity_assets`** (factory) — `leveling` is a runtime getter
+  reading `props.leveling` off the modal store (falling back to `_levelingDefault`);
+  an `init` hook opens the modal directly at the updated state via `props.celebrate`
+  (the "updated" cards open the same id pre-advanced, like the Auth step cards);
+  `_finishSaved` always advances to the updated state (the view gate picks
+  celebration vs plain confirmation) AND mirrors `celebrate` onto the live store
+  `props.celebrate`, so the active-card **glow follows the flow** — it transfers
+  from the input card to the updated card as the modal advances, exactly like the
+  Auth glow follows `props.step`. In **demo** mode the app-facing saved event is
+  suppressed, so a host app's follow-on handler (e.g. Turf Monster's
+  `quest-success` on `studio:username-saved`) can't stack a second modal over the
+  demo's own celebrate view.
+- **`/admin/style`** — "Leveling activities" → **"Profile Leveling"**: **each
+  specimen card carries its OWN `Leveling` toggle** (like the Auth card's method
+  checkboxes), flipping THAT card between the Turf Monster and McRitchie Studio
+  shape at open — so you can preview Change Username leveling-on beside Great
+  Username leveling-off. The section walks **four** cards — **Change Username →
+  Great Username**, then **Join the Newsletter → Subscribed!** — each "updated"
+  card opening its modal straight at the success state, mirroring Turf Monster's
+  real copy, seeds, and Free Entry Token progress. No quest counter, no Level pill.
+
+### Added
+
+- **`_leveling_activity` locals** (all optional, additive): `consent_label` (a
+  consent checkbox that gates the action — the newsletter join), `confirm_subtitle`
+  (subtext on the MS-shape plain confirmation), `next_label` / `next_open` (a
+  "Next Quest" button that walks to the next activity), and `demo_seeds_earned` /
+  `demo_seeds_total` (style-guide-only seed payload tuning).
+
+## 0.24.1 — 2026-07-28
+
+Bug fix — the **`/admin/style` specimen glow failed OPEN**. Every glow-capable
+specimen card (`style/_modal_specimen`) carries the `.studio-team-glow` class
+statically, and the "only the active card glows" behavior rode entirely on a
+reactive Alpine `:style` overriding the primitive's CSS default of
+`--studio-team-glow-opacity: 1` (visible) down to `0`. Before Alpine hydrates —
+or if it never loads — all 13 reactive-glow cards (Auth, Eligibility, Profile,
+Leveling) painted their ring at once. The steady state was correct (the glow
+follows the step machine), so this surfaced as a flash-of-all-glow on load.
+
+### Fixed
+
+- **`style/_modal_specimen`** now renders a **static inline
+  `style="--studio-team-glow-opacity: 0"`** on the glow wrapper beside the
+  reactive `:style`, so the ring is OFF at first paint (fail-closed) regardless
+  of Alpine timing. The reactive binding still drives `0 ↔ 0.95` with the 0.4s
+  cross-fade, so the active-card glow and its slide between step cards are
+  unchanged. The `engine-motion.css` `.studio-team-glow` default is untouched
+  (the always-on Tricks demos depend on it).
+
+## 0.24.0 — 2026-07-28
+
+The **smooth-load convention**, opt-in per app. Pages materialize behind the
+current one and present themselves with a view transition — navigation renders
+exactly once, with no stale-preview flash. Modifies an existing primitive:
+`layouts/studio/_head` gains the convention partial and a configurable nav
+spinner minimum.
+
+**One ungated visual change on the bump, opt-in or not:** `.turbo-progress-bar`
+in `engine.css` restyles every consumer's Turbo progress bar from Turbo's
+default blue to the app's theme CTA color (3px, `var(--color-cta)` — defined in
+both themes by the theme resolver, and the rule wins Turbo's injected-first
+stylesheet cascade). Everything else is inert until an app sets
+`Studio.smooth_load = true`.
+
+### Added
+
+- **Smooth-load convention (opt-in)** — `Studio.smooth_load` (default OFF)
+  renders `layouts/studio/_smooth_load` from `_head`: the `view-transition`
+  meta (Turbo 8 wraps page swaps in `document.startViewTransition`) plus
+  `turbo-cache-control: no-preview`, so the next page materializes behind the
+  current one and presents itself — navigation renders exactly once. An app
+  with known multi-second pages should fix those before opting in (no-preview
+  holds the old page until the fresh response arrives).
+- **`Studio.nav_spinner_min_ms`** — the nav spinner's minimum display time,
+  previously hardcoded to 2500 in `_head`. Default unchanged (2500); smooth-load
+  apps typically drop it to ~300 so fast loads never linger on a spinner.
+- **Smooth-load CSS in `engine.css`** — root fade-out / rise-in view-transition
+  keyframes (inert until the metas render), the `.vt-pinned-header` opt-in
+  utility (exactly one per page — a duplicate `view-transition-name` silently
+  disables the transition), the theme-colored `.turbo-progress-bar` noted
+  above, and a `prefers-reduced-motion` kill switch app e2e suites can lean on
+  (`reducedMotion: "reduce"`).
+
+### Fixed
+
+- **`rescue_from` order in `Studio::ErrorHandling`** — `RecordNotFound` now
+  resolves to `handle_not_found` (Rescuable matches last-registered first, so
+  the catch-all must register first). A missing record renders a real 404 from
+  `public/404.html` and **creates no ErrorLog row**; previously it was shadowed
+  by the catch-all, logged as an unexpected error, and soft-404'd (302 to root)
+  in production HTML. Per-host behavior changes only as each app bumps to this
+  release.
+
 ## 0.23.0 — 2026-07-28
 
 Phase D, slice 1 — the **board primitive**. The three near-identical McRitchie

data/README.md

@@ -42,6 +42,16 @@ Studio.configure do |config|
   )
   config.theme_primary = "#4BAF50"   # Override default violet
   config.theme_logos = ["logo.svg"]
+
+  # Smooth-load convention (default OFF). Renders the view-transition +
+  # no-preview metas: Turbo page swaps materialize behind the current page and
+  # present with a view transition, exactly one render per navigation. Fix any
+  # multi-second pages BEFORE opting in — no-preview holds the old page until
+  # the fresh response arrives.
+  config.smooth_load = true
+  # Nav spinner minimum display (default 2500). Smooth-load apps typically
+  # drop to ~300; keep the high floor if multi-second ops ride the spinner.
+  config.nav_spinner_min_ms = 300
 end
 ```
 
@@ -114,6 +124,18 @@ privileges while impersonating.
 
 ## UI Primitives
 
+### Smooth-load header pin — `.vt-pinned-header`
+
+When `Studio.smooth_load` is on, put `vt-pinned-header` on the app's sticky
+header: it gets its own named view-transition group, so page content
+transitions beneath a navbar that stays put (or smoothly morphs heights).
+**Exactly one element per page** — a duplicate `view-transition-name` makes
+the browser silently skip the whole transition, with no error and no animation.
+
+```erb
+<header class="sticky top-0 vt-pinned-header ...">
+```
+
 Render `components/emoji_swap` inside a link or button with the `group` class to
 slide between two emoji on hover and keyboard focus. The CSS ships through
 `studio_theme_css_tag`, including a reduced-motion fade fallback.

data/app/assets/tailwind/studio_engine/engine.css

@@ -180,3 +180,62 @@
 @utility btn-lg {
   @apply px-8 py-3 text-base rounded-xl shadow-sm;
 }
+
+/* -- Smooth-load convention ------------------------------------------------
+   Paired with layouts/studio/_smooth_load.html.erb (the Studio.smooth_load
+   metas that opt Turbo into document.startViewTransition). These rules are
+   inert until an app renders those metas, so shipping them in the auto-bundled
+   layer costs nothing. The outgoing page fades while the incoming one rises in
+   underneath — quick enough to read as polish, not as a wait. */
+::view-transition-old(root) {
+  animation: vt-page-out 160ms cubic-bezier(0.4, 0, 1, 1) both;
+}
+
+::view-transition-new(root) {
+  animation: vt-page-in 220ms cubic-bezier(0, 0, 0.2, 1) both;
+}
+
+@keyframes vt-page-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes vt-page-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* Opt-in header pin: put this on the app's sticky header so it gets its own
+   named transition group, lifted out of the root snapshot — page content
+   transitions beneath a navbar that stays put (or smoothly morphs heights).
+   EXACTLY ONE element per page: a duplicate view-transition-name makes the
+   browser silently skip the whole transition. */
+@utility vt-pinned-header {
+  view-transition-name: studio-header;
+}
+
+/* Turbo's progress bar is the slow-load feedback under no-preview (the old
+   page holds until the fresh response). Theme it so every app's bar matches
+   its brand instead of Turbo's default. */
+.turbo-progress-bar {
+  height: 3px;
+  background: var(--color-cta);
+}
+
+/* Reduced motion: keep the single-render swap, drop the choreography. Also
+   what the apps' e2e suites lean on (reducedMotion: "reduce") for stable
+   clicks. */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}

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

@@ -3,8 +3,15 @@ module Studio
     extend ActiveSupport::Concern
 
     included do
-      rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      # ORDER IS LOAD-BEARING — ActiveSupport::Rescuable resolves handlers with
+      # `reverse_each`, so the LAST matching rescue_from registered wins. The
+      # catch-all must therefore be declared FIRST and the specific handlers
+      # after it, or StandardError shadows every one of them: RecordNotFound
+      # rendered "Something went wrong" and wrote an ErrorLog row on every 404,
+      # fleet-wide, while handle_not_found sat unreachable. Add new specific
+      # handlers BELOW this line, never above it.
       rescue_from StandardError, with: :handle_unexpected_error
+      rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
 
       before_action :require_authentication
 
@@ -195,12 +202,33 @@ module Studio
       raise e
     end
 
-    # Layer 1: Catch-all for RecordNotFound — 404 redirect, no logging.
+    # Layer 1: RecordNotFound — Rails' own 404, never an ErrorLog row.
+    #
+    # This handler exists for exactly ONE reason: to stop `handle_unexpected_error`
+    # from claiming a RecordNotFound and writing an ErrorLog row for it. It
+    # deliberately renders NOTHING and re-raises, which hands the exception to
+    # `ActionDispatch::PublicExceptions` — the same path an app with no rescue_from
+    # at all takes. Registering the handler and re-raising is therefore not a
+    # no-op: matching here is what keeps the catch-all's `create_error_log` from
+    # running (a raise inside a rescue_from handler propagates out; Rescuable does
+    # not re-dispatch it into another handler).
+    #
+    # Why nothing is rendered here. The method was unreachable from the initial
+    # commit until the rescue_from order was fixed (see the note in `included`),
+    # so whatever it did had never actually run — consumers have been served
+    # Rails' standard 404 all along. Anything rendered here would therefore be a
+    # NEW fleet-wide behaviour, not a restoration: an earlier attempt at this fix
+    # rendered public/404.html and silently flipped `Accept: */*` clients (curl,
+    # uptime monitors, crawlers, link previewers) from `404 text/html` to
+    # `404 application/json`, changed the JSON body shape, and dropped the
+    # DebugExceptions backtrace in development. Re-raising keeps every one of
+    # those intact, along with `public/404.<locale>.html` and any
+    # `config.exceptions_app` a host configures.
+    #
+    # The bug being fixed is the ErrorLog pollution and the "Something went wrong"
+    # copy — never the status code, the format, or the body.
     def handle_not_found(exception)
-      respond_to do |format|
-        format.html { redirect_to root_path, alert: "Not found" }
-        format.json { render json: { error: "Not found" }, status: :not_found }
-      end
+      raise exception
     end
 
     # Layer 1: Catch-all for unexpected errors — log + friendly response.

data/app/views/layouts/studio/_head.html.erb

@@ -10,6 +10,7 @@
 <meta name="apple-mobile-web-app-capable" content="yes">
 <%= csrf_meta_tags %>
 <%= csp_meta_tag %>
+<%= render "layouts/studio/smooth_load" %>
 <link rel="icon" type="image/png" href="/favicon.png">
 
 <%= yield :head %>
@@ -46,9 +47,10 @@
 </script>
 <script>
   // Nav spinner — scale morph between theme toggle and loading spinner
-  // Minimum display time prevents quick flashes
+  // Minimum display time prevents quick flashes; per-app via
+  // Studio.nav_spinner_min_ms (smooth-load apps drop it to ~300).
   window._navSpinnerShownAt = 0;
-  window._navSpinnerMinMs = 2500;
+  window._navSpinnerMinMs = <%= Studio.nav_spinner_min_ms.to_i %>;
   window.showNavSpinner = function() {
     window._navSpinnerShownAt = Date.now();
     document.querySelectorAll('.nav-toggle-icon').forEach(function(e) { e.style.opacity = '0'; e.style.transform = 'scale(0) rotate(90deg)'; });

data/app/views/layouts/studio/_smooth_load.html.erb

@@ -0,0 +1,15 @@
+<%# Smooth-load convention (opt-in via Studio.smooth_load) — the next page
+    materializes behind the current one, then presents itself. Turbo 8 sees the
+    view-transition meta and wraps its body swap in document.startViewTransition;
+    browsers without support get the instant swap. no-preview stops application
+    visits from painting a stale cache snapshot before the fresh response — the
+    current page holds until the new one is ready, so navigation renders exactly
+    once. Restoration visits (back/forward) still restore instantly from cache.
+    Transition styling ships in engine.css ("Smooth-load convention" block);
+    pin an app's sticky header with the .vt-pinned-header utility (exactly one
+    element per page — a duplicate view-transition-name silently disables the
+    whole transition). %>
+<% if Studio.smooth_load %>
+  <meta name="view-transition" content="same-origin">
+  <meta name="turbo-cache-control" content="no-preview">
+<% end %>

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

@@ -38,9 +38,20 @@
     savedEvent    DOM event dispatched on success, carrying the app payload, so
                   the app can run its own follow-on. Default "studio:activity-saved".
     store         Alpine modal store name backing close(). Default "modals".
-    leveling      true shows the seeds celebration on success (a UI flourish).
-    demo          style-guide preview: resolve locally, skip the network POST.
+    leveling      the render-time DEFAULT for the seeds celebration. The live
+                  value is read at RUNTIME from the modal store's current
+                  props.leveling (this.leveling getter), so one modal id flips
+                  TM (celebration) <-> MS (plain save) as a toggle moves; when
+                  props omits it (TM's live path) the default stands.
+    hasConsent    true renders a consent checkbox that gates the action until
+                  ticked (the newsletter join).
+    demo          style-guide preview: resolve locally, skip the network POST, and
+                  suppress the app-facing saved event (so a host app's follow-on
+                  handler can't stack a second modal over the demo's own state).
     seedsPerLevel seeds per level for the celebration bar. Default 100.
+    demoSeedsEarned / demoSeedsTotal  demo-only seed payload (defaults to a
+                  level-crossing 30 / seedsPerLevel) so each activity's
+                  celebration can showcase a chosen state.
 %>
 <script>
   (function () {
@@ -57,9 +68,17 @@
         finalizeHook: opts.finalizeHook || "",
         savedEvent: opts.savedEvent || "studio:activity-saved",
         store: opts.store || "modals",
-        leveling: !!opts.leveling,
+        // leveling is a RUNTIME getter (below) reading props.leveling off the modal
+        // store, so ONE modal id flips TM <-> MS shape live as a section toggle
+        // moves. _levelingDefault is the render-time fallback (TM ships no
+        // props.leveling and relies on its :leveling capability default).
+        _levelingDefault: !!opts.leveling,
+        hasConsent: !!opts.hasConsent,
+        consent: false,
         demo: !!opts.demo,
         seedsPerLevel: parseInt(opts.seedsPerLevel, 10) || 100,
+        demoSeedsEarned: parseInt(opts.demoSeedsEarned, 10),
+        demoSeedsTotal: parseInt(opts.demoSeedsTotal, 10),
         saving: false,
         error: "",
         saved: false,
@@ -68,9 +87,42 @@
         seedsEarned: 0,
         seedsTotal: 0,
 
+        // Open directly AT the updated/celebrate state — the specimen's "updated"
+        // cards (Great Username / Subscribed!) open the same modal id pre-advanced,
+        // exactly like the Auth cards open a given step. props.celebrate mounts the
+        // modal already saved, with the seed payload the celebration animates from.
+        // leveling (a getter) then decides at runtime whether that state renders the
+        // seeds celebration (TM) or the plain confirmation (MS).
+        init: function () {
+          var s = (window.Alpine && Alpine.store) ? Alpine.store(this.store) : null;
+          var cur = (s && typeof s.current === "function") ? s.current() : null;
+          var p = (cur && cur.props) || {};
+          if (p.celebrate) {
+            this.seedsEarned = parseInt(p.seedsEarned, 10) || 0;
+            this.seedsTotal = parseInt(p.seedsTotal, 10) || 0;
+            this.saved = true;
+            this.celebrate = true;
+          }
+        },
+
+        // leveling — resolved at RUNTIME from the modal store's current props, so a
+        // single modal id flips TM (seeds/level/quest) <-> MS (plain save) live as
+        // the section's leveling toggle moves. Falls back to the render-time default
+        // when props does not set it (TM's live path), so existing callers are
+        // unaffected.
+        get leveling() {
+          var s = (window.Alpine && Alpine.store) ? Alpine.store(this.store) : null;
+          var cur = (s && typeof s.current === "function") ? s.current() : null;
+          var p = cur && cur.props;
+          if (p && typeof p.leveling === "boolean") return p.leveling;
+          return this._levelingDefault;
+        },
+
         // Actionable while there is a real change to save (input activities) or
-        // until the one-shot action has fired (no-field activities).
+        // until the one-shot action has fired (no-field activities). A consent
+        // checkbox (the newsletter join) additionally gates the action until ticked.
         get changed() {
+          if (this.hasConsent && !this.consent) return false;
           if (!this.hasInput) return !this.saved;
           var v = (this.value || "").trim();
           if (v.length < this.minLength) return false;
@@ -78,6 +130,13 @@
         },
 
         _dispatch: function (payload) {
+          // In demo mode (the /admin/style preview) do NOT fire the app-facing
+          // saved event: the host app may listen for it and open its OWN follow-on
+          // modal (e.g. Turf Monster swaps to 'quest-success' on
+          // 'studio:username-saved'), which would stack a SECOND modal over the
+          // demo's own celebrate view — the reported duplicate. The demo resolves
+          // locally and is self-contained, so it must not drive real app follow-ons.
+          if (this.demo) return;
           try {
             window.dispatchEvent(new CustomEvent(this.savedEvent, { detail: payload || {} }));
           } catch (e) {}
@@ -90,11 +149,26 @@
           this.progressLabel = "";
           if (this.hasInput) this.original = (this.value || "").trim();
           this._dispatch(payload);
-          if (this.leveling) {
-            this.seedsEarned = parseInt(payload.seeds_earned, 10) || 0;
-            this.seedsTotal = parseInt(payload.seeds_total, 10) || 0;
-            this.celebrate = true;
-          }
+          // Always advance to the updated state; the view gate (celebrate &&
+          // leveling vs celebrate && !leveling) picks the seeds celebration (TM)
+          // or the plain confirmation (MS). Seeds are set either way — only the
+          // leveling view reads them.
+          this.seedsEarned = parseInt(payload.seeds_earned, 10) || 0;
+          this.seedsTotal = parseInt(payload.seeds_total, 10) || 0;
+          this.celebrate = true;
+          // Reflect the advance onto the store's LIVE current props so the specimen
+          // glow (which reads props.celebrate) transfers from the input card to the
+          // updated card — exactly like the Auth glow follows props.step as its
+          // machine advances. Without this, the glow stays on the input card.
+          this._syncCelebrate(true);
+        },
+
+        // Mirror the component's celebrate onto the current modal store entry's
+        // props, the reactive source the specimen glow_when reads.
+        _syncCelebrate: function (value) {
+          var s = (window.Alpine && Alpine.store) ? Alpine.store(this.store) : null;
+          var cur = (s && typeof s.current === "function") ? s.current() : null;
+          if (cur && cur.props) cur.props.celebrate = !!value;
         },
 
         _post: function (url, body) {
@@ -115,10 +189,14 @@
           this.error = "";
           var self = this;
           if (this.demo) {
-            // Style-guide preview: no backend. Resolve to a level-crossing payload
-            // so the leveling celebration demonstrates its full flourish.
+            // Style-guide preview: no backend. Resolve to a per-activity seed
+            // payload (defaulting to a level-crossing one) so the celebration
+            // demonstrates its flourish — Username stays at Level 1 (+25), the
+            // Newsletter crosses a level to reveal the Free Entry Token line.
+            var de = isNaN(self.demoSeedsEarned) ? 30 : self.demoSeedsEarned;
+            var dt = isNaN(self.demoSeedsTotal) ? self.seedsPerLevel : self.demoSeedsTotal;
             setTimeout(function () {
-              self._finishSaved({ seeds_earned: 30, seeds_total: self.seedsPerLevel });
+              self._finishSaved({ seeds_earned: de, seeds_total: dt });
             }, 600);
             return;
           }

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

@@ -40,7 +40,7 @@
     saved_event:        "studio:username-saved",
     icon_emoji:         "🌱",
     celebrate_title:    "Great Username",
-    celebrate_subtitle: "Nice — you earned seeds for updating your profile. Keep completing quests to earn a Free Entry."
+    celebrate_subtitle: "Nice — you earned 25 seeds by completing a quest. Complete more quests to earn a Free Entry Token."
   )
 %>
 <%= render "studio/modals/blocks/leveling_activity", username_locals %>

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

@@ -1,16 +1,23 @@
 <%#
-  Leveling-activity modal — the engine primitive behind TM's quest/leveling
+  Leveling-activity modal — the engine primitive behind TM's profile-leveling
   activities (change username, join newsletter, and the rest). ONE primitive,
-  TWO modes, decided by the app's :leveling capability:
+  three views (form / seeds celebration / plain confirm), TWO modes decided by the
+  app's :leveling capability:
 
-    leveling ON  — the full quest framing: a "Quest N of N" pill, and on success
-                   the seeds celebration (progress bar + level-up + Free Entry).
-    leveling OFF — the plain action modal: just the action + Save, and a Saved
-                   state on success. No quest pill, no seeds. (This is the
-                   McRitchie-Studio shape: MS has no leveling, TM does.)
+    leveling ON  — the action, then on success the seeds celebration: a "Level N"
+                   pill + the seeds progress bar (level-up + Free Entry Token).
+    leveling OFF — the plain action, then a simple confirmation on success (a
+                   "Saved" / "Subscribed" card). No Level pill, no seeds. (This is
+                   the McRitchie-Studio shape: MS has no leveling, TM does.)
 
-  Same primitive; the flag decides. The leveling chrome (quest pill, seeds bar) is
-  engine-owned UI — it is NOT on-chain.
+  There is NO "Quest N of N" counter — the profile modals do not carry one.
+
+  Same primitive; the flag decides — and it decides at RUNTIME. The leveling chrome
+  (Level pill, seeds celebration) is ALWAYS rendered and gated by the reactive
+  leveling getter (which reads props.leveling off the modal store, falling back to
+  this local), so ONE modal id flips TM <-> MS live as a toggle moves — no more
+  `-plain` duplicate ids. The leveling chrome is engine-owned UI — it is NOT
+  on-chain.
 
   CRITICAL BOUNDARY — UI ONLY. There is NO wallet, signing, key, or on-chain write
   anywhere in this primitive. The actual save is an APP-SUPPLIED callback: the
@@ -36,17 +43,27 @@
     finalize_hook (String) — window async fn name for the step (omit if none).
     saved_event   (String) — DOM event dispatched on success. Default
                   "studio:activity-saved".
-    quest_label   (String) — the "Quest N of N" pill text (leveling only).
     icon_emoji    (String) — celebration glyph. Default "🌱".
     celebrate_title    (String) — celebration headline. Default "Activity complete".
     celebrate_subtitle (String) — celebration subtext.
     free_entry_label   (String) — level-up reward line. Default "Free Entry Earned 🎟️".
     seeds_per_level    (Integer) — seeds per level. Default 100.
-    leveling      (Boolean) — override the :leveling gate. Defaults to
-                  Studio.feature?(:leveling); the style guide passes both to show
-                  each mode.
+    leveling      (Boolean) — the RENDER-TIME DEFAULT for the :leveling gate
+                  (defaults to Studio.feature?(:leveling)). The LIVE value is read
+                  at runtime from the modal store's props.leveling, so a single
+                  modal id flips TM <-> MS as a toggle moves.
+    consent_label (String) — render a consent checkbox that gates the action until
+                  ticked (the newsletter join). Omit for no checkbox.
+    confirm_subtitle (String) — subtext on the MS-shape (leveling off) plain
+                  confirmation. Omit = none.
+    next_label / next_open — an optional "Next Quest" button on the celebration;
+                  next_open is a developer-authored Alpine expression (e.g. swap to
+                  the next activity). Both required to render the button.
+    demo_seeds_earned / demo_seeds_total — style-guide-only seed payload for the
+                  demo save (defaults to a level-crossing 30 / seeds_per_level).
     modal_store   (String) — Alpine store name backing close(). Default "modals".
-    demo          (Boolean) — style-guide preview: resolve locally, no POST.
+    demo          (Boolean) — style-guide preview: resolve locally, no POST, and
+                  no app-facing saved event (no host follow-on can stack a modal).
 
   Single root element (the modal host mounts this through its own template x-if).
 %>
@@ -68,7 +85,6 @@
   finalize_url       = local_assigns.fetch(:finalize_url, "")
   finalize_hook      = local_assigns.fetch(:finalize_hook, "")
   saved_event        = local_assigns.fetch(:saved_event, "studio:activity-saved")
-  quest_label        = local_assigns.fetch(:quest_label, nil)
   icon_emoji         = local_assigns.fetch(:icon_emoji, "🌱")
   celebrate_title    = local_assigns.fetch(:celebrate_title, "Activity complete")
   celebrate_subtitle = local_assigns.fetch(:celebrate_subtitle, "Nice — you earned seeds. Keep completing quests to earn a Free Entry.")
@@ -77,6 +93,17 @@
   leveling           = local_assigns.fetch(:leveling, Studio.feature?(:leveling))
   modal_store        = local_assigns.fetch(:modal_store, "modals")
   demo               = local_assigns.fetch(:demo, false)
+  # consent_label — render a consent checkbox that gates the action (newsletter
+  # join). next_label / next_open — an optional "Next Quest" button in the
+  # celebration (next_open is a developer-authored Alpine expression). demo_seeds_*
+  # — style-guide-only tuning.
+  consent_label      = local_assigns.fetch(:consent_label, nil)
+  next_label         = local_assigns.fetch(:next_label, nil)
+  next_open          = local_assigns[:next_open].presence&.to_s&.html_safe
+  # confirm_subtitle — the MS-shape (leveling off) plain-confirmation subtext.
+  confirm_subtitle   = local_assigns.fetch(:confirm_subtitle, nil)
+  demo_seeds_earned  = local_assigns.fetch(:demo_seeds_earned, nil)
+  demo_seeds_total   = local_assigns.fetch(:demo_seeds_total, nil)
 %>
 <div x-data="levelingActionModal({
        hasInput: <%= input ? 'true' : 'false' %>,
@@ -88,20 +115,17 @@
        savedEvent: '<%= j saved_event %>',
        store: '<%= j modal_store %>',
        leveling: <%= leveling ? 'true' : 'false' %>,
+       hasConsent: <%= consent_label.present? ? 'true' : 'false' %>,
        demo: <%= demo ? 'true' : 'false' %>,
-       seedsPerLevel: <%= seeds_per_level.to_i %>
+       seedsPerLevel: <%= seeds_per_level.to_i %>,
+       demoSeedsEarned: <%= demo_seeds_earned.present? ? demo_seeds_earned.to_i : 'null' %>,
+       demoSeedsTotal: <%= demo_seeds_total.present? ? demo_seeds_total.to_i : 'null' %>
      })">
 
   <%# FORM VIEW — the action. Single root inside the template. %>
   <template x-if="!celebrate">
     <div>
       <%= render layout: "studio/modals/blocks/shell", locals: { title: title, modal_store: modal_store } do %>
-        <% if leveling && quest_label.present? %>
-          <div class="mb-3">
-            <span class="inline-block text-[10px] font-semibold uppercase tracking-wide text-primary bg-primary/10 px-2 py-0.5 rounded-full whitespace-nowrap"><%= quest_label %></span>
-          </div>
-        <% end %>
-
         <% if description.present? %>
           <p class="text-sm text-muted mb-4"><%= description %></p>
         <% end %>
@@ -120,6 +144,12 @@
                    <%= "title=\"#{pattern_title}\"".html_safe if pattern_title.present? %>
                    autofocus>
           <% end %>
+          <% if consent_label.present? %>
+            <label class="flex items-center gap-2 text-xs text-secondary select-none cursor-pointer">
+              <input type="checkbox" x-model="consent" class="rounded border-subtle text-primary cursor-pointer">
+              <span><%= consent_label %></span>
+            </label>
+          <% end %>
           <button type="submit" class="btn btn-primary btn-lg w-full" :disabled="saving || !changed">
             <span x-show="!saving" x-text="changed ? '<%= j cta_label %>' : '<%= j saved_label %>'"><%= cta_label %></span>
             <span x-show="saving" class="inline-flex items-center justify-center gap-2" style="display: none;">
@@ -132,28 +162,48 @@
     </div>
   </template>
 
-  <%# CELEBRATION VIEW — leveling ONLY. Rendered at ERB time only when leveling is
-      on, so a leveling-off modal ships NO seeds chrome at all (not merely
-      unmounted). Mounts once celebrate flips true so the seeds bar animates from
-      the freshly-saved payload. Single root. %>
-  <% if leveling %>
-    <template x-if="celebrate">
-      <div>
-        <%= render "studio/modals/blocks/card_header",
-              size: :lg, icon_emoji: icon_emoji,
-              title: celebrate_title, subtitle: celebrate_subtitle %>
+  <%# CELEBRATION VIEW — leveling-only chrome. ALWAYS rendered now (so a runtime
+      leveling toggle can reveal it); the x-if gates on BOTH celebrate AND the
+      reactive leveling getter, so an MS-shape modal (leveling off) shows the plain
+      saved state and never this. Mounts once celebrate flips true so the seeds bar
+      animates from the freshly-saved payload. Single root. %>
+  <template x-if="celebrate && leveling">
+    <div>
+      <%= render "studio/modals/blocks/card_header",
+            size: :lg, icon_emoji: icon_emoji,
+            title: celebrate_title, subtitle: celebrate_subtitle %>
 
-        <div class="mb-5">
-          <%= render "studio/modals/blocks/seeds_bar",
-                seeds_earned_key: "seedsEarned", seeds_total_key: "seedsTotal",
-                seeds_per_level: seeds_per_level, free_entry_label: free_entry_label %>
-        </div>
+      <div class="mb-5">
+        <%= render "studio/modals/blocks/seeds_bar",
+              seeds_earned_key: "seedsEarned", seeds_total_key: "seedsTotal",
+              seeds_per_level: seeds_per_level, free_entry_label: free_entry_label %>
+      </div>
 
-        <button type="button" @click="$store.<%= modal_store %>.close()"
-                class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
-          Close
+      <% if next_label.present? && next_open.present? %>
+        <button type="button" @click="<%= next_open %>" class="btn btn-primary btn-lg w-full">
+          <%= next_label %>
         </button>
-      </div>
-    </template>
-  <% end %>
+      <% end %>
+      <button type="button" @click="$store.<%= modal_store %>.close()"
+              class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+        Close
+      </button>
+    </div>
+  </template>
+
+  <%# PLAIN CONFIRM VIEW — the MS shape (leveling off) after an update: a simple
+      confirmation, NO seeds / Level / celebration chrome. Gated celebrate &&
+      !leveling, so the single leveling toggle flips this <-> the seeds celebration
+      above, live. Single root. %>
+  <template x-if="celebrate && !leveling">
+    <div>
+      <%= render "studio/modals/blocks/card_header",
+            size: :lg, icon_color: "success",
+            title: saved_label, subtitle: confirm_subtitle %>
+      <button type="button" @click="$store.<%= modal_store %>.close()"
+              class="btn btn-primary btn-lg w-full">
+        Done
+      </button>
+    </div>
+  </template>
 </div>

data/app/views/style/_modal_specimen.html.erb

@@ -55,7 +55,12 @@
     height via the grid's default align-items: stretch). %>
 <div class="relative h-full<%= " studio-team-glow rounded-xl" if glow_when %>"
      x-data="<%= card_x_data %>"
-     <% if glow_when %>:style="{ '--studio-team-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
+     <%# Fail-closed default: a STATIC inline 0 out-specifies the primitive's CSS
+         default (--studio-team-glow-opacity of 1) so the ring is OFF at first
+         paint, BEFORE Alpine hydrates the reactive :style below. Without it every
+         glow card shows its ring until Alpine boots (the fail-open flash). The
+         :style then drives 0 to 0.95 with the 0.4s cross-fade. Keep BOTH. %>
+     <% if glow_when %>style="--studio-team-glow-opacity: 0" :style="{ '--studio-team-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
   <article
       class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %><%= " cursor-pointer" if clickable %>"
       <%= 'aria-disabled="true"'.html_safe if disabled %>

data/app/views/style/_modals.html.erb

@@ -47,11 +47,14 @@
   # variants (:picker vs :crop). The crop sub-state rides props.cropReady — the
   # crop factory sets it true when the cropper mounts (on a direct image OR after
   # an in-modal pick), so the glow moves picker -> cropper as the flow advances.
-  ds_glow = lambda do |id, step: nil, crop: nil|
+  ds_glow = lambda do |id, step: nil, crop: nil, celebrate: nil|
     cur  = "$store.dsModals.current()"
     expr = "#{cur} && #{cur}.id === '#{id}'"
     expr += " && (#{cur}.props.step || 'credentials') === '#{step}'" if step
     expr += (crop == :crop ? " && !!#{cur}.props.cropReady" : " && !#{cur}.props.cropReady") unless crop.nil?
+    # celebrate discriminates the input specimen (form) from the "updated" specimen
+    # (celebrate) of the SAME leveling modal id, mirroring the step/crop sub-states.
+    expr += (celebrate ? " && !!#{cur}.props.celebrate" : " && !#{cur}.props.celebrate") unless celebrate.nil?
     expr
   end
 %>
@@ -256,7 +259,7 @@
   <%= render "studio/age_verify_assets" %>
 
   <%# levelingActionModal factory — page level (never inside the overlay template,
-      where a cloned script would not run) so the change-username + quest-activity
+      where a cloned script would not run) so the change-username + join-newsletter
       specimens open live. A consumer app renders this in its layout the same way. %>
   <%= render "studio/leveling_activity_assets" %>
 
@@ -381,47 +384,46 @@
                     subtitle: "You leveled up! A Free Entry lands in your account soon. Keep leveling for more." %></div>
         </template>
 
-        <%# --- Leveling activities: change username + quest activity --- %>
-        <%# Each id renders the SAME engine primitive with an EXPLICIT leveling:
-            flag, so BOTH modes stay visible here regardless of this app's real
-            :leveling setting. All demo:true — the save resolves locally (no
-            backend), and the on-chain-accurate copy is passed as an app-authored
-            description (the engine default stays neutral). %>
+        <%# --- Profile Leveling: change username + join newsletter --- %>
+        <%# ONE id per activity — opened at the form OR (with props.celebrate) at the
+            "updated" state, exactly like the Auth cards open a given step. The
+            primitive reads props.leveling at RUNTIME, so each card's own Leveling
+            toggle flips TM (the seeds celebration) <-> MS (plain confirmation) at
+            open — no more `-plain` twins, and no "Quest N of N" counter. All
+            demo:true (the save resolves locally); the on-chain-accurate copy is an
+            app-authored description (the engine default stays neutral). The two
+            activities walk in sequence via the celebration's "Next Quest"
+            (Username -> Newsletter -> close). %>
         <template x-if="$store.dsModals.current().id === 'change-username'">
           <div><%= render "studio/modals/blocks/change_username",
                     modal_store: "dsModals", demo: true, leveling: true,
                     current_username: "turfmonster",
                     submit_url: "#demo-change-username",
                     description: "Your username is stored on-chain. Changes are saved via your managed wallet.",
-                    quest_label: "Quest 1 of 4" %></div>
+                    cta_label: "Save", saved_label: "Saved",
+                    demo_seeds_earned: 25, demo_seeds_total: 25,
+                    free_entry_label: "Free Entry Token 🎟️",
+                    confirm_subtitle: "Your username has been updated.",
+                    next_label: "Next Quest",
+                    next_open: "$store.dsModals.swap('join-newsletter', { demo: true, leveling: true })" %></div>
         </template>
-        <template x-if="$store.dsModals.current().id === 'change-username-plain'">
-          <div><%= render "studio/modals/blocks/change_username",
-                    modal_store: "dsModals", demo: true, leveling: false,
-                    current_username: "mcritchie",
-                    submit_url: "#demo-change-username",
-                    description: "Choose the name shown across your account." %></div>
-        </template>
-        <template x-if="$store.dsModals.current().id === 'quest-activity'">
+        <template x-if="$store.dsModals.current().id === 'join-newsletter'">
           <div><%= render "studio/modals/blocks/leveling_activity",
                     modal_store: "dsModals", demo: true, leveling: true,
-                    submit_url: "#demo-quest",
+                    submit_url: "#demo-newsletter",
                     title: "Join the Newsletter",
-                    description: "Sports news and contest updates — complete the quest for seeds.",
-                    input: true, input_type: "email", placeholder: "you@example.com",
+                    description: "Sports news and contest updates — and 25 seeds for joining.",
+                    input: false,
+                    consent_label: "Email me sports news and contest updates.",
                     cta_label: "Subscribe", saved_label: "Subscribed", saving_label: "Subscribing…",
-                    quest_label: "Quest 2 of 4",
-                    icon_emoji: "📬", celebrate_title: "You're in",
-                    celebrate_subtitle: "Nice — you earned seeds for joining. Keep completing quests to earn a Free Entry." %></div>
-        </template>
-        <template x-if="$store.dsModals.current().id === 'quest-activity-plain'">
-          <div><%= render "studio/modals/blocks/leveling_activity",
-                    modal_store: "dsModals", demo: true, leveling: false,
-                    submit_url: "#demo-quest",
-                    title: "Join the Newsletter",
-                    description: "Sports news and contest updates.",
-                    input: true, input_type: "email", placeholder: "you@example.com",
-                    cta_label: "Subscribe", saved_label: "Subscribed", saving_label: "Subscribing…" %></div>
+                    icon_emoji: "🌱",
+                    celebrate_title: "Subscribed!",
+                    celebrate_subtitle: "You're on the list. We'll keep the sports news and contest updates coming.",
+                    demo_seeds_earned: 25, demo_seeds_total: 100,
+                    free_entry_label: "Free Entry Token 🎟️",
+                    confirm_subtitle: "You're on the list.",
+                    next_label: "Next Quest",
+                    next_open: "$store.dsModals.close()" %></div>
         </template>
 
       </div>
@@ -630,7 +632,126 @@
   </section>
 
   <%# ===================================================================== %>
-  <%# 3. WEB3 — gated by Studio.feature?(:web3); off = disabled-but-present-yet-openable %>
+  <%# 3. PROFILE LEVELING — change username + join newsletter (per-card toggles) %>
+  <%# ===================================================================== %>
+  <%# Each specimen card carries its OWN Leveling toggle (like the Auth "Sign in"
+      card's method checkboxes) — the card's opts.leveling flows into its open() as
+      props.leveling, so the card opens at the TM shape (checked, the default) or the
+      MS shape (unchecked). Independent per card: preview Change Username leveling-on
+      beside Great Username leveling-off. ONE primitive, ONE id per activity, no
+      "Quest N of N" counter — the with/without fork is gone. The two "updated"
+      cards open the same modal id straight at the celebrate state (props.celebrate),
+      exactly like the Auth cards open a given step. %>
+  <section class="space-y-5">
+    <div class="space-y-1">
+      <div class="flex flex-wrap items-center gap-3">
+        <h3 class="text-xl font-bold text-heading">Profile Leveling</h3>
+        <% if leveling_on %>
+          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">leveling on</span>
+        <% else %>
+          <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">leveling off</span>
+        <% end %>
+      </div>
+      <p class="text-muted text-sm">
+        The profile leveling flow, ported from Turf Monster as ONE primitive
+        (<code class="font-mono text-2xs">studio/modals/blocks/_leveling_activity</code>,
+        with <code class="font-mono text-2xs">_change_username</code> as its username
+        specialization). Walk all four states — <strong>Change Username &rarr; Great
+        Username</strong>, then <strong>Join the Newsletter &rarr; Subscribed!</strong>
+        — each "updated" card opens its modal straight at the success state, just like
+        the Auth cards open a given step. Each card carries its <strong>own Leveling
+        toggle</strong> (like the Auth card's method checkboxes): <strong>checked</strong>
+        is the Turf Monster shape (the seeds bar + Free Entry Token progress),
+        <strong>unchecked</strong> is the McRitchie Studio shape (plain input + Save,
+        then a simple confirmation). Flip a card's toggle, then open it — so you can
+        preview Change Username leveling-on beside Great Username leveling-off. Same
+        modal id either way — the primitive reads
+        <code class="font-mono text-2xs">leveling</code> at runtime, so there is no
+        with/without fork and <strong>no "Quest N of N" counter</strong>. The save is an
+        <strong>app-supplied callback</strong>
+        (<code class="font-mono text-2xs">submit_url</code> + an opaque
+        <code class="font-mono text-2xs">finalize_hook</code> for a wallet step) —
+        <strong>no wallet, signing, or on-chain write lives in the engine</strong>.
+        (These demos resolve locally.)
+      </p>
+    </div>
+    <%# The walk, left to right: Change Username -> Great Username -> Join Newsletter
+        -> Subscribed. The two "updated" cards open the same id at props.celebrate. %>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+      <%# 1. Change Username — the input (form) state. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Change Username",
+            reference: %(the Profile Leveling "Change Username" activity (studio-engine studio/modals/blocks/_change_username) — the input state. Reads leveling at runtime; the on-chain save is an app-supplied callback (submit_url + an opaque finalize_hook), the engine is UI only. Open with $store.dsModals.open('change-username', { demo: true, leveling: true })),
+            card_data: "opts: { leveling: true }",
+            toggles:   [{ model: "opts.leveling", label: "Leveling" }],
+            open_expr: "$store.dsModals.open('change-username', { demo: true, leveling: opts.leveling })",
+            glow_when: ds_glow.call("change-username", celebrate: false) } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <span class="block h-2 w-16 rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# 2. Great Username — the updated (celebrate) state, opened directly. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Great Username",
+            reference: %(the Profile Leveling "Great Username" updated state (studio/modals/blocks/_change_username opened at props.celebrate) — leveling ON shows the seeds celebration (plus 25, Free Entry Token) + Next Quest; leveling OFF shows the plain "Saved" confirmation. Toggle this card's Leveling checkbox to switch, then open. Open with $store.dsModals.open('change-username', { demo: true, leveling: true, celebrate: true, seedsEarned: 25, seedsTotal: 25 })),
+            card_data: "opts: { leveling: true }",
+            toggles:   [{ model: "opts.leveling", label: "Leveling" }],
+            open_expr: "$store.dsModals.open('change-username', { demo: true, leveling: opts.leveling, celebrate: true, seedsEarned: 25, seedsTotal: 25 })",
+            glow_when: ds_glow.call("change-username", celebrate: true) } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
+          <div class="text-2xl leading-none">🌱</div>
+          <div x-show="opts.leveling" class="flex gap-1">
+            <span class="flex-1 h-2 rounded" style="background: var(--color-cta)"></span>
+            <span class="flex-1 h-2 rounded" style="background: var(--color-cta); opacity:.5"></span>
+            <span class="flex-1 h-2 rounded" style="background: var(--color-text); opacity:.12"></span>
+          </div>
+          <span class="block h-1.5 w-20 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+        </div>
+      <% end %>
+
+      <%# 3. Join the Newsletter — the input state (consent checkbox + Subscribe). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Join Newsletter",
+            reference: %(the Profile Leveling "Join the Newsletter" activity (studio-engine studio/modals/blocks/_leveling_activity) — the input state: a consent checkbox + Subscribe. Reads leveling at runtime. Open with $store.dsModals.open('join-newsletter', { demo: true, leveling: true })),
+            card_data: "opts: { leveling: true }",
+            toggles:   [{ model: "opts.leveling", label: "Leveling" }],
+            open_expr: "$store.dsModals.open('join-newsletter', { demo: true, leveling: opts.leveling })",
+            glow_when: ds_glow.call("join-newsletter", celebrate: false) } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
+          <span class="text-lg leading-none">📬</span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# 4. Subscribed! — the updated (celebrate) state, opened directly. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Subscribed!",
+            reference: %(the Profile Leveling "Subscribed!" updated state (studio/modals/blocks/_leveling_activity opened at props.celebrate) — leveling ON shows the seeds celebration (Free Entry Token) + Next Quest; leveling OFF shows the plain "Subscribed" confirmation. Toggle this card's Leveling checkbox to switch, then open. Open with $store.dsModals.open('join-newsletter', { demo: true, leveling: true, celebrate: true, seedsEarned: 25, seedsTotal: 100 })),
+            card_data: "opts: { leveling: true }",
+            toggles:   [{ model: "opts.leveling", label: "Leveling" }],
+            open_expr: "$store.dsModals.open('join-newsletter', { demo: true, leveling: opts.leveling, celebrate: true, seedsEarned: 25, seedsTotal: 100 })",
+            glow_when: ds_glow.call("join-newsletter", celebrate: true) } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
+          <div class="mx-auto w-7 h-7 rounded-full flex items-center justify-center" style="background: color-mix(in srgb, var(--color-success) 15%, transparent)">
+            <svg class="w-4 h-4" style="color: var(--color-success)" 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>
+          <div x-show="opts.leveling" class="flex gap-1">
+            <span class="flex-1 h-2 rounded" style="background: var(--color-cta)"></span>
+            <span class="flex-1 h-2 rounded" style="background: var(--color-cta); opacity:.6"></span>
+            <span class="flex-1 h-2 rounded" style="background: var(--color-cta); opacity:.3"></span>
+          </div>
+          <span class="block h-1.5 w-20 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+        </div>
+      <% end %>
+    </div>
+  </section>
+
+  <%# ===================================================================== %>
+  <%# 4. WEB3 — gated by Studio.feature?(:web3); off = disabled-but-present-yet-openable %>
   <%# ===================================================================== %>
   <section class="space-y-5">
     <div class="space-y-1">
@@ -735,7 +856,7 @@
   </section>
 
   <%# ===================================================================== %>
-  <%# 4. SYSTEM AND STATUS (reusable card blocks) %>
+  <%# 5. SYSTEM AND STATUS (reusable card blocks) %>
   <%# ===================================================================== %>
   <section class="space-y-5">
     <div class="space-y-1">
@@ -797,7 +918,7 @@
   </section>
 
   <%# ===================================================================== %>
-  <%# 5. TEMPLATES (copy-from archetypes) %>
+  <%# 6. TEMPLATES (copy-from archetypes) %>
   <%# ===================================================================== %>
   <section class="space-y-5">
     <div class="space-y-1">
@@ -831,7 +952,7 @@
   </section>
 
   <%# ===================================================================== %>
-  <%# 6. REWARDS / leveling (gated by Studio.feature?(:leveling)) %>
+  <%# 7. REWARDS / leveling (gated by Studio.feature?(:leveling)) %>
   <%# ===================================================================== %>
   <section class="space-y-5">
     <div class="space-y-1">
@@ -908,96 +1029,4 @@
     </div>
   </section>
 
-  <%# ===================================================================== %>
-  <%# 7. LEVELING ACTIVITIES — change username + quest activities %>
-  <%# ===================================================================== %>
-  <section class="space-y-5">
-    <div class="space-y-1">
-      <div class="flex flex-wrap items-center gap-3">
-        <h3 class="text-xl font-bold text-heading">Leveling activities</h3>
-        <% if leveling_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">leveling on</span>
-        <% else %>
-          <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">leveling off</span>
-        <% end %>
-      </div>
-      <p class="text-muted text-sm">
-        The quest/leveling action modals
-        (<code class="font-mono text-2xs">studio/modals/blocks/_change_username</code>,
-        <code class="font-mono text-2xs">studio/modals/blocks/_leveling_activity</code>),
-        migrated from Turf Monster. ONE primitive, <strong>two modes</strong>, decided
-        by <code class="font-mono text-2xs">Studio.feature?(:leveling)</code>:
-        <strong>leveling on</strong> adds the quest pill + the seeds level-up
-        celebration; <strong>leveling off</strong> is the plain action modal (just
-        the input + Save + a Saved state — the McRitchie Studio shape). Each modal is
-        shown <strong>both ways</strong> below (the specimens pass an explicit
-        <code class="font-mono text-2xs">leveling:</code> so both render regardless of
-        this app's flag). The actual save is an <strong>app-supplied callback</strong>:
-        the modal POSTs to <code class="font-mono text-2xs">submit_url</code> and, for
-        an app that needs a wallet step, delegates it opaquely to an app-supplied
-        <code class="font-mono text-2xs">finalize_hook</code> — <strong>no wallet,
-        signing, or on-chain write lives in the engine</strong>. (These demos resolve
-        the save locally.)
-      </p>
-    </div>
-    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-      <%# Change username — leveling ON: quest pill + seeds celebration on save. %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Change username (leveling)",
-            reference: %(the "Change username" modal WITH leveling (studio-engine studio/modals/blocks/_change_username, leveling: true) — quest pill + seeds level-up celebration on save. The on-chain save is an app-supplied callback (submit_url + an opaque finalize_hook); the engine is UI only. Open with $store.dsModals.open('change-username')),
-            open_expr: "$store.dsModals.open('change-username')",
-            glow_when: ds_glow.call("change-username") } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
-          <div class="flex items-center justify-between gap-2">
-            <span class="block h-2 w-16 rounded" style="background: var(--color-text); opacity: .18"></span>
-            <span class="text-[8px] font-semibold uppercase rounded-full px-1.5 py-0.5" style="color: var(--color-primary); background: color-mix(in srgb, var(--color-primary) 12%, transparent)">Quest 1/4</span>
-          </div>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
-        </div>
-      <% end %>
-
-      <%# Change username — leveling OFF: the plain MS-style action + Save. %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Change username (plain)",
-            reference: %(the "Change username" modal WITHOUT leveling (studio-engine studio/modals/blocks/_change_username, leveling: false) — the plain McRitchie Studio shape: input + Save, then a Saved state. No quest pill, no seeds. Same primitive, flag off. Open with $store.dsModals.open('change-username-plain')),
-            open_expr: "$store.dsModals.open('change-username-plain')",
-            glow_when: ds_glow.call("change-username-plain") } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
-          <span class="block h-2 w-16 rounded" style="background: var(--color-text); opacity: .18"></span>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
-        </div>
-      <% end %>
-
-      <%# Quest activity — leveling ON: generic quest (newsletter join) + seeds. %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Quest activity (leveling)",
-            reference: %(a generic quest activity WITH leveling (studio-engine studio/modals/blocks/_leveling_activity, leveling: true) — here a "Join the Newsletter" quest: quest pill + seeds celebration on complete. Covers join-newsletter / send-message and the rest as ONE parameterized primitive. Open with $store.dsModals.open('quest-activity')),
-            open_expr: "$store.dsModals.open('quest-activity')",
-            glow_when: ds_glow.call("quest-activity") } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
-          <div class="flex items-center justify-between gap-2">
-            <span class="text-lg leading-none">📬</span>
-            <span class="text-[8px] font-semibold uppercase rounded-full px-1.5 py-0.5" style="color: var(--color-primary); background: color-mix(in srgb, var(--color-primary) 12%, transparent)">Quest 2/4</span>
-          </div>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
-        </div>
-      <% end %>
-
-      <%# Quest activity — leveling OFF: the plain action (no quest, no seeds). %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Quest activity (plain)",
-            reference: %(the SAME generic activity WITHOUT leveling (studio-engine studio/modals/blocks/_leveling_activity, leveling: false) — a plain "Join the Newsletter" action: input + Subscribe, then Subscribed. No quest pill, no seeds. Open with $store.dsModals.open('quest-activity-plain')),
-            open_expr: "$store.dsModals.open('quest-activity-plain')",
-            glow_when: ds_glow.call("quest-activity-plain") } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
-          <span class="text-lg leading-none">📬</span>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
-        </div>
-      <% end %>
-    </div>
-  </section>
 </section>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.23.0"
+  VERSION = "0.25.0"
 end

data/lib/studio.rb

@@ -25,6 +25,20 @@ module Studio
   mattr_accessor :theme_logos,         default: []
   mattr_accessor :sticky_table_headers, default: false
 
+  # ---- Smooth-load convention ---------------------------------------------
+  # Opt-in per app: renders the view-transition + no-preview metas so Turbo 8
+  # page swaps materialize behind the current page and present with a view
+  # transition (layouts/studio/_smooth_load). OFF by default — an app with
+  # known multi-second pages should fix those before opting in, because
+  # no-preview holds the old page until the fresh response arrives.
+  mattr_accessor :smooth_load,          default: false
+
+  # Minimum ms the nav spinner stays visible once shown (_head.html.erb).
+  # Apps wrapping multi-second operations in the spinner (e.g. Solana RPC)
+  # keep the high default to avoid flicker; smooth-load apps typically drop
+  # this to ~300 so fast loads never linger on a spinner.
+  mattr_accessor :nav_spinner_min_ms,   default: 2500
+
   # ---- Authentication ------------------------------------------------------
   # Which sign-in methods this app offers. The shared login/signup views render
   # a button/field per enabled method (gate with Studio.auth_method?). Order is

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -242,6 +242,7 @@ files:
 - app/views/layouts/branded_mailer.html.erb
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.html.erb
+- app/views/layouts/studio/_smooth_load.html.erb
 - app/views/magic_links/confirm.html.erb
 - app/views/navbar/show.html.erb
 - app/views/registrations/new.html.erb