studio-engine 0.25.1 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d87b5711dd0833ea78e20b6f3174dd57e5cc3b0311e56f962e8954a408943963
-  data.tar.gz: 81708f5604bdebaa3f08504169e4bf1a55ba8ea9d8856f04594dbe49295d553c
+  metadata.gz: 3fefcb19f5cf631e4e1515bf0b113fb33167cb1173f039a0777038aac5173d57
+  data.tar.gz: f203c29195b71e945a055bcfa60ad58f0d1aea16fe2ce60e84de4de1993d62ec
 SHA512:
-  metadata.gz: b3ffce4a4ba6b91444902123ee106f9f88fec2be0606d69f310ff464bfe336ca444de94f85c2c81873feb335080e2a9fc01390ff48df7f87977e645e0c3397ac
-  data.tar.gz: 6584381c67a206525171c7195ded0999f8ce20ad896196aa8259b116e450c7db2a23ed95193dcb8281e49f57f09c5010817ce67e127bcc3d10c517ca4a67ca16
+  metadata.gz: d790f97aede359baf45915bbde14fef29cea6779a0866159a3b5f1dc5a396d24951d7ba3d796e4523e0dc17489319375929e8b3e2741ca9b7c569dd5f9dac91e
+  data.tar.gz: 25a54c2e44ad2e29608afe72fcf6b7dc8028fe28c47bd92e582e041b282f7f4e2b70ba5eb3468f4d8edb083f3d1fe185c340c135678b9a0a0556bfbab601a98b

data/CHANGELOG.md

@@ -2,6 +2,137 @@
 
 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.27.0 — 2026-07-28
+
+**Two coordinated modal flows on the `/admin/style` Design System page — a walked
+"Web3 Contest" wallet → on-chain flow and an extended "Contest entry & eligibility"
+flow — plus a reusable minimum-visible-duration convention for load modals.** All
+specimens are DEMO chrome (`demo: true`, no real signing); the engine gains only
+view/chrome primitives and keeps custodial keys, wallet/multisig signing,
+`Solana::Config`, and every on-chain write app-side.
+
+### Added
+
+- **Minimum-visible-duration convention** — `studio/modals/_load_convention`
+  ships `window.StudioModals.holdAtLeast(minMs)` + a standard
+  `MIN_LOAD_MS` (1400) as a SINGLE definition, rendered by both the shared modal
+  host (`studio/modals/_host`, which drops its inline copy) and the style page.
+  A load spinner holds for at least `min_duration`, longer if the real async runs
+  longer — `resolveAt = max(min_duration, actual_completion)`; in demo mode
+  `min_duration` doubles as the auto-resolve timer. `_processing_card` gains
+  `min_duration` + `resolve_expr` locals so a demo load card self-advances.
+- **Web3 Contest** section (renamed from "Web3") — a walked flow with
+  glow-follows-the-flow continuity: Connect Wallet → Processing on-chain
+  transaction → On-chain success. The Processing card is a load modal with a demo
+  success/error toggle (unchecked resolves to success, checked to error), both
+  resolved states built. Picking a wallet swaps to Processing, which auto-resolves
+  after the min-load duration.
+- **Contest entry & eligibility** section (renamed from "Eligibility & entry",
+  moved directly under Web3 Contest) — the entry flow extended to
+  Entry tokens → Payment processing → Entry Tokens Minted → Contest enter
+  processing → Contest entered, with the glow following the step machine. Keeps
+  the Age gate + Entry tokens cards. The section states the honest web2/web3 map:
+  the token mint is web2-only (web3 funds USDC on-chain directly, no token); the
+  paths diverge at the funding front-end and the entry-submit endpoint, then
+  converge on the same on-chain Entry PDA and the same "Entry Confirmed" card.
+
+### Changed
+
+- **`studio/modals/_host`** — the `holdAtLeast` helper now lives in the shared
+  `_load_convention` partial (same API, byte-identical behavior) so the host and
+  the DS page share one definition instead of drifting copies.
+- **`style/modals/_entry_tokens`** — the confirming step uses the min-load
+  convention instead of a hardcoded timeout, and the step machine gains
+  `entering` + `entered` so hold-to-confirm walks through the on-chain consume to
+  the shared Entry Confirmed finish.
+- **`style/modals/_onchain_tx`** — a processing modal opened with `demoResolve`
+  auto-resolves to success (or error when `demoError`) after the min-load
+  duration, honoring the convention.
+- The Modals-section glow helper discriminates the on-chain-tx `state` and a
+  configurable step default, so the glow tracks a walked flow across modal ids.
+
+## 0.26.1 — 2026-07-28
+
+**Fix the `/admin/style` Design System page breaking when reached via Turbo Drive
+navigation (the admin sidebar "Design System" link).** Reached by a direct page
+load the page was fine; reached by an in-app Turbo visit its modals would not open
+on a card click and EVERY specimen glow ring lit at once. Both symptoms were one
+cause: the page-scoped `dsModals` (and `dsSolanaModal`) Alpine store was registered
+ONLY inside a `document.addEventListener('alpine:init', …)` handler in the page
+body. Alpine loads via a deferred CDN `<script>` in the engine head and fires
+`alpine:init` exactly once, on the first full-document load; Turbo Drive advance
+visits swap `<body>` without reloading that head script, so `alpine:init` never
+fires again — and because the registration lives only in the `/admin/style` body,
+it was absent during that one `alpine:init`. The specimen cards' `x-data` still
+re-initialize on the Turbo body swap (Alpine's MutationObserver), so their
+`@click="$store.dsModals.open(…)"`, `:style` glow bindings, and the host's
+`<template x-if="$store.dsModals.current()…">` all evaluated against an undefined
+store and threw `Cannot read properties of undefined (reading 'current')` — no
+modal opened, and the throwing `:style` wiped each card's static inline
+`--studio-team-glow-opacity: 0`, so the CSS default of `1` relit all rings.
+
+### Fixed
+
+- **`style/_modals`** — the `dsModals` + `dsSolanaModal` registration is now a
+  named `registerDsModals()` invoked through the same dual-guard the engine
+  already uses for `studio/modals/_image_upload`'s `cropPhotoModal`:
+  `if (window.Alpine) registerDsModals(); else document.addEventListener('alpine:init', registerDsModals);`.
+  On a Turbo visit Alpine has already started, so the store registers immediately
+  (the body script re-runs on every Turbo render) and `$store.dsModals` is defined
+  before the cards' bindings evaluate; on a first load Alpine has not booted yet,
+  so it still defers to `alpine:init`. The `if (Alpine.store('dsModals')) return;`
+  idempotency guard is unchanged, so a later `alpine:init` is a no-op. No consumer
+  change is required — `/admin/style` is an engine page.
+- **Docs** — `style/_modal_specimen`'s fail-closed comment now records that the
+  static inline `--studio-team-glow-opacity: 0` guards the ring only while
+  `$store.dsModals` is DEFINED (a throwing `:style` wipes the inline value) — the
+  refinement of 0.24.1's "regardless of Alpine timing" claim that this bug exposed.
+
+### Swept
+
+- Audited every engine `Alpine.store(...)` / `Alpine.data(...)` registration for
+  the same Turbo-visit fragility. `dsModals`/`dsSolanaModal` (`style/_modals`) was
+  the only page-scoped registration missing the guard. `studio/modals/_image_upload`
+  (`cropPhotoModal`) already carries it; the shared modal host (`studio/modals/_host`
+  → `modals`) and the theme/devMode stores (`layouts/studio/_head`) are app-wide
+  bootstrap rendered on the first full load, so their single `alpine:init`
+  registration persists across Turbo visits (verified: `$store.modals` stays
+  defined after a Turbo nav).
+
+## 0.26.0 — 2026-07-28
+
+**The engine navbar pins itself under smooth-load, and the smooth-load CSS is
+fully engine-owned.** Since 0.24 the `vt-pinned-header` pin was opt-in but the
+engine's own `layouts/_navbar` never carried it, so a host that wanted the
+pinned-header transition had to SHADOW the whole partial just to add one class
+(acquisition-studio did exactly that — the known override-drift trap). The
+navbar now self-pins when `Studio.smooth_load` is on, and the engine also ships
+the `studio-header` cross-fade suppression that mcritchie-studio and
+turf-monster had been carrying app-side as a bridge. **Consumer cleanup this
+version unlocks:** acquisition-studio deletes its entire
+`app/views/layouts/_navbar.html.erb` override; mcritchie-studio and
+turf-monster delete their app-side `::view-transition-old(studio-header)` /
+`::view-transition-new(studio-header) { animation: none; }` bridge blocks.
+
+### Changed
+
+- **`layouts/_navbar`** — the sticky header adds `vt-pinned-header` itself when
+  `Studio.smooth_load` is on, non-preview branch ONLY (preview renders can
+  repeat per page, and a duplicate `view-transition-name` silently disables
+  every transition). With the flag off nothing extra renders, so a plain gem
+  bump changes no opted-out app.
+- **`engine.css`** — new `::view-transition-old(studio-header)` /
+  `::view-transition-new(studio-header) { animation: none; }` rule beside the
+  smooth-load block: it suppresses the UA-default ~250ms plus-lighter
+  cross-fade between the header's two snapshots, which double-drew the wordmark
+  and buttons on any navigation from a scrolled page (collapsed header →
+  expanded at top). Lifts the identical bridge rule the hub and turf-monster
+  carried app-side.
+- **`engine.css`** — `.turbo-progress-bar` background becomes
+  `var(--color-cta, #0076ff)`: the fallback (Turbo's own default blue) keeps
+  the bar visible in a layout that never renders the runtime theme block
+  (`studio_theme_css_tag`), where `--color-cta` is unset.
+
 ## 0.25.1 — 2026-07-28
 
 **Fix the Profile Leveling save-close regression 0.25.0 introduced.** The 0.25.0
@@ -110,6 +241,12 @@ follows the step machine), so this surfaced as a flash-of-all-glow on load.
   unchanged. The `engine-motion.css` `.studio-team-glow` default is untouched
   (the always-on Tricks demos depend on it).
 
+  > **Refined in 0.26.1:** "regardless of Alpine timing" holds only while
+  > `$store.dsModals` is defined. On a Turbo Drive visit the store went
+  > unregistered, the reactive `:style` threw, and Alpine wiped this inline
+  > default — relighting every ring. 0.26.1 dual-guards the store registration so
+  > it survives Turbo visits, restoring the fail-closed guarantee.
+
 ## 0.24.0 — 2026-07-28
 
 The **smooth-load convention**, opt-in per app. Pages materialize behind the

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

@@ -221,12 +221,28 @@
   view-transition-name: studio-header;
 }
 
+/* Suppress the UA default on the pinned header's own group: without this the
+   browser runs its ~250ms plus-lighter cross-fade between the header's old and
+   new snapshots, and on any navigation from a scrolled page (collapsed header
+   → expanded at top) the wordmark and buttons draw TWICE, offset by the height
+   delta, until the blend settles. animation: none shows the incoming header
+   immediately while the group box still morphs its height. Engine-owned as of
+   0.26.0 — this lifts the identical bridge rule mcritchie-studio and
+   turf-monster carried app-side; consumers delete their copies when adopting
+   this version. */
+::view-transition-old(studio-header),
+::view-transition-new(studio-header) {
+  animation: none;
+}
+
 /* 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. */
+   its brand instead of Turbo's default. The fallback (#0076ff, Turbo's own
+   default blue) keeps the bar visible in a layout that never renders the
+   runtime theme block (studio_theme_css_tag), where --color-cta is unset. */
 .turbo-progress-bar {
   height: 3px;
-  background: var(--color-cta);
+  background: var(--color-cta, #0076ff);
 }
 
 /* Reduced motion: keep the single-render swap, drop the choreography. Also

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

@@ -8,6 +8,14 @@
 %>
 <% show_user = local_assigns.fetch(:show_logged_in, logged_in?) %>
 <% is_preview = local_assigns.fetch(:preview, false) %>
+<%# Smooth-load self-pin (engine 0.26): when the app opts into Studio.smooth_load,
+    the sticky header names itself as the shared view-transition group
+    (vt-pinned-header) so page content transitions beneath a navbar that stays
+    put — hosts no longer shadow this partial just to add the class. Non-preview
+    branch ONLY: preview renders can repeat per page, and a duplicate
+    view-transition-name silently disables every transition. With the flag off,
+    nothing extra renders. %>
+<% pin_header = Studio.smooth_load && !is_preview %>
 <% balance_html = local_assigns.fetch(:balance_html, nil) %>
 <% extra_icons_html = local_assigns.fetch(:extra_icons_html, nil) %>
 <% show_logout_link = local_assigns.fetch(:show_logout_link, false) %>
@@ -19,7 +27,7 @@
 %>
 
 <header x-data="{ scrolled: false }" <%= '@scroll.window="scrolled = scrolled ? (window.scrollY > 5) : (window.scrollY > 60)"'.html_safe unless is_preview %>
-        class="<%= is_preview ? 'bg-page' : 'sticky top-0 z-50 bg-page transition-shadow duration-300' %>"
+        class="<%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 z-50 bg-page transition-shadow duration-300" %>"
         :class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'">
   <style>
     .user-nav-col { width: 14rem; }

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

@@ -153,24 +153,6 @@
 
 <script>
   (function() {
-    // === StudioModals helpers ===========================================
-    //
-    // holdAtLeast(ms) — pair with the _processing_card block. Stamp the
-    // moment a loading view becomes visible, then await the minimum
-    // before swapping to success so the spinner doesn't flash past the
-    // user when the operation finishes fast.
-    window.StudioModals = window.StudioModals || {};
-    window.StudioModals.holdAtLeast = function(minMs) {
-      var startedAt = Date.now();
-      return {
-        then: function(callback) {
-          var remaining = Math.max(0, minMs - (Date.now() - startedAt));
-          if (remaining === 0) { callback(); return; }
-          setTimeout(callback, remaining);
-        }
-      };
-    };
-
     // === Modal animation registry ======================================
     //
     // The single place to define + tune named entrance / exit animations
@@ -490,6 +472,14 @@
   })();
 </script>
 
+<%# The minimum-visible-duration convention (window.StudioModals.holdAtLeast +
+    MIN_LOAD_MS) — the SINGLE source, shared with the /admin/style demo page.
+    Pair it with the _processing_card block so a load spinner never flashes past
+    the user. Rendered AFTER the store <script> above so the store stays the
+    host's first <script> (a Node behavior harness extracts that first script).
+    See studio/modals/_load_convention for the full contract. %>
+<%= render "studio/modals/load_convention" %>
+
 <template x-if="$store.modals.current()">
   <%# Backdrop + card use CSS keyframe animations (NOT Alpine
       x-transition), all shipped in the inline style block above. On

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

@@ -0,0 +1,55 @@
+<%#
+  Minimum-visible-duration convention for load / processing modals.
+
+  A load modal shows its spinner for AT LEAST a minimum duration so it never
+  flashes past the user (registering "did anything happen?" instead of
+  "processing → done"), but LONGER whenever the real async takes longer:
+
+      resolveAt = max(min_duration, actual_completion)
+
+  This ships the convention on window.StudioModals, defined ONCE here and
+  rendered by BOTH the shared modal host (studio/modals/_host) and the living
+  style guide (style/_modals) — so every consumer app and the /admin/style demo
+  page share a single definition:
+
+    MIN_LOAD_MS  — the standard default minimum (1400 ms). A caller may pass its
+                   own, but reach for this so every load modal feels consistent.
+
+    holdAtLeast(minMs) — returns a thenable whose .then(cb) fires cb at
+                   max(minMs, elapsed-since-this-call). Two usages:
+
+                     REAL async — stamp the moment the loading view appears, then
+                     resolve in the async completion, so a slow op is never cut
+                     short and a fast one still honors the spinner:
+                       var hold = StudioModals.holdAtLeast(StudioModals.MIN_LOAD_MS);
+                       doWork().then(function () { hold.then(showSuccess); });
+
+                     DEMO (no real work) — call .then immediately and minMs
+                     DOUBLES as the auto-resolve timer: the demo advances after
+                     min_duration exactly:
+                       StudioModals.holdAtLeast(StudioModals.MIN_LOAD_MS).then(advance);
+
+  Idempotent (|| guards): never clobber a definition an app already shipped, and
+  safe to render more than once on a page.
+%>
+<script>
+  (function () {
+    window.StudioModals = window.StudioModals || {};
+    // Standard minimum-visible duration for a load spinner, in ms. ~1200–1500
+    // reads as "processing → done"; below ~1s the spinner flashes and reads as a
+    // glitch. Callers may override per-modal, but default to this for consistency.
+    window.StudioModals.MIN_LOAD_MS = window.StudioModals.MIN_LOAD_MS || 1400;
+    // holdAtLeast(minMs).then(cb) — cb fires at max(minMs, elapsed-since-call).
+    // Stamp the moment a loading view becomes visible; the anti-flicker floor.
+    window.StudioModals.holdAtLeast = window.StudioModals.holdAtLeast || function (minMs) {
+      var startedAt = Date.now();
+      return {
+        then: function (callback) {
+          var remaining = Math.max(0, minMs - (Date.now() - startedAt));
+          if (remaining === 0) { callback(); return; }
+          setTimeout(callback, remaining);
+        }
+      };
+    };
+  })();
+</script>

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

@@ -2,10 +2,17 @@
     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>.
 
-    Local: store — Alpine store name backing the title read. Default "modals".
-    The living style guide passes store: "dsModals" for its page-scoped host. %>
+    Locals:
+      store        — Alpine store name backing the title read. Default "modals".
+                     The living style guide passes store: "dsModals".
+      resolve_expr — optional demo auto-resolve (min-load convention). The real
+                     Turbo submit drives the spinner and closes on completion, so
+                     apps omit this; the /admin/style demo passes an expression
+                     (e.g. close) so the specimen self-terminates after min_duration
+                     instead of spinning forever. %>
 <% saving_store = local_assigns.fetch(:store, "modals") %>
 <div>
   <%= render "studio/modals/blocks/processing_card",
-        title_key: "$store.#{saving_store}.current()?.props?.title || 'Saving…'" %>
+        title_key: "$store.#{saving_store}.current()?.props?.title || 'Saving…'",
+        resolve_expr: local_assigns[:resolve_expr] %>
 </div>

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

@@ -1,10 +1,16 @@
 <%#
   Reusable processing / loading card. Spinner + title + optional message.
-  Pair with window.StudioModals.holdAtLeast(ms) on the caller side to
-  enforce a minimum visible duration — without that the spinner can
-  flash by when the operation finishes faster than ~1s and the user
-  registers "did anything happen?" instead of "ok, processing →
-  success".
+
+  Minimum-visible-duration convention (studio/modals/_load_convention):
+  a load spinner must show for AT LEAST a floor, but longer if the real async
+  runs longer — resolveAt = max(min_duration, actual_completion) — so it never
+  flashes past the user ("did anything happen?") yet never cuts a slow op short.
+  Two ways to honor it:
+    • REAL async — the caller stamps window.StudioModals.holdAtLeast(min_duration)
+      when this card appears, then resolves in its completion callback.
+    • DEMO / auto-resolve — pass `resolve_expr`: this card self-schedules that
+      Alpine expression after `min_duration` (min_duration doubles as the demo's
+      auto-resolve timer), via the same holdAtLeast floor.
 
   Locals — pass static strings OR `_key` variants for Alpine-driven
   text that updates as state mutates (e.g. live store reads):
@@ -15,6 +21,10 @@
     size:          spinner size — 'sm', 'md' (default), 'lg'
     color:         color token for the spinner — 'primary' (default),
                    'success', 'warning'
+    min_duration:  minimum visible ms (default 1400, mirrors
+                   StudioModals.MIN_LOAD_MS). The convention's floor.
+    resolve_expr:  Alpine expression run after min_duration to advance the flow
+                   (demo auto-resolve). Omit for a real spinner the caller drives.
 
   One of `title` or `title_key` is required.
 %>
@@ -27,8 +37,12 @@
     'lg' => 'w-16 h-16 border-4'
   }
   spinner_class = sizes[size] || sizes['md']
+  # min_duration mirrors StudioModals.MIN_LOAD_MS (the JS default) so the Ruby and
+  # JS sides of the convention agree on the same floor.
+  min_duration = local_assigns[:min_duration] || 1400
+  resolve_expr = local_assigns[:resolve_expr]
 %>
-<div class="text-center py-6">
+<div class="text-center py-6"<%= " x-data=\"{}\" x-init=\"window.StudioModals.holdAtLeast(#{min_duration}).then(() => { #{resolve_expr} })\"".html_safe if resolve_expr %>>
   <div class="mx-auto <%= spinner_class %> rounded-full border-<%= color %>/30 border-t-<%= color %> animate-spin mb-5"></div>
   <% if local_assigns[:title_key] %>
     <p class="text-base font-bold text-heading mb-1" x-text="<%= title_key %>"></p>

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

@@ -59,7 +59,14 @@
          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. %>
+         :style then drives 0 to 0.95 with the 0.4s cross-fade. Keep BOTH.
+         CAVEAT: this fail-closed default holds only while $store.dsModals is
+         DEFINED. glow_when dereferences the store; if the store is missing the
+         reactive :style THROWS, and Alpine's style bind wipes this inline value
+         on the way, so the CSS default of 1 relights every ring. That is exactly
+         the Turbo-nav store gap fixed in 0.26.1 (style/_modals dual-guards the
+         dsModals registration so it survives Turbo visits, not just first load).
+         So the guarantee is: static inline 0 PLUS a registered dsModals. %>
      <% 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 %>"

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

@@ -42,18 +42,22 @@
 
   # Active-card glow-match expression builder: yields an Alpine boolean that is
   # true when $store.dsModals.current() is THIS specimen's modal. It discriminates
-  # by sub-state so two specimens that open the SAME modal id still glow the right
-  # card: `step:` for the auth step machine, and `crop:` for the two crop-photo
-  # 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, celebrate: nil|
+  # by sub-state so specimens that open the SAME modal id still glow the right
+  # card, and so the glow FOLLOWS a walked flow as the step machine advances:
+  #   step:         the auth / entry-tokens step machine (step_default is the
+  #                 modal's own default step — 'credentials' for auth, 'picker'
+  #                 for entry-tokens).
+  #   state:        the on-chain-tx state (processing / success / error) — lets the
+  #                 glow track Connect Wallet -> Processing -> On-chain success.
+  #   crop:         the two crop-photo variants (:picker vs :crop), on props.cropReady.
+  #   celebrate:    the input specimen (form) vs the "updated" (celebrate) specimen
+  #                 of the SAME leveling modal id.
+  ds_glow = lambda do |id, step: nil, step_default: "credentials", crop: nil, celebrate: nil, state: nil|
     cur  = "$store.dsModals.current()"
     expr = "#{cur} && #{cur}.id === '#{id}'"
-    expr += " && (#{cur}.props.step || 'credentials') === '#{step}'" if step
+    expr += " && (#{cur}.props.step || '#{step_default}') === '#{step}'" if step
+    expr += " && #{cur}.props.state === '#{state}'" if state
     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
@@ -107,7 +111,10 @@
         isAvailable: function () { return false; }
       };
 
-      document.addEventListener('alpine:init', function () {
+      // Register the page-scoped dsModals + dsSolanaModal stores. Named (not an
+      // inline alpine:init callback) so the dual-guard at the end can invoke it
+      // directly on a Turbo visit, when alpine:init will not fire again.
+      function registerDsModals() {
         if (Alpine.store('dsModals')) return;
 
         // Enter/exit animation registry — keys map to a CSS class (engine-
@@ -244,10 +251,29 @@
           get ctaLabel()        { return this._read('ctaLabel', ''); },
           get ctaHref()         { return this._read('ctaHref', ''); }
         });
-      });
+      }
+
+      // Alpine's deferred CDN <script> fires alpine:init exactly ONCE, on the
+      // first full-document load. Turbo Drive advance visits swap the document
+      // body without reloading that head script, so alpine:init never fires
+      // again — and
+      // because this dsModals registration lives ONLY in the /admin/style body,
+      // it was absent during that one alpine:init. Registering here on the
+      // Turbo-visit path (Alpine already started) keeps $store.dsModals defined,
+      // so the specimen cards' @click / :style / <template x-if> don't throw.
+      // Mirrors studio/modals/_image_upload's cropPhotoModal guard.
+      if (window.Alpine) { registerDsModals(); }
+      else { document.addEventListener('alpine:init', registerDsModals); }
     })();
   </script>
 
+  <%# The minimum-visible-duration convention (window.StudioModals.holdAtLeast +
+      MIN_LOAD_MS) — the SAME single definition the shared modal host renders, so
+      the demo load modals here (payment/entry processing, on-chain tx, saving)
+      honor resolveAt = max(min_duration, actual) and auto-resolve after
+      min_duration in demo mode. A consumer app already has it via the host. %>
+  <%= render "studio/modals/load_convention" %>
+
   <%# Cropper.js + the cropPhotoModal factory — makes the Profile crop / upload
       modals openable on this page (loads cropper.js via <script defer> and
       defines the factory inline; no importmap change). %>
@@ -295,8 +321,11 @@
         <template x-if="$store.dsModals.current().id === 'crop-photo'">
           <div><%= render "studio/modals/crop_photo", store: "dsModals" %></div>
         </template>
+        <%# saving — the demo passes resolve_expr so the spinner self-terminates
+            after min_duration (a real app's Turbo submit drives + closes it). %>
         <template x-if="$store.dsModals.current().id === 'saving'">
-          <div><%= render "studio/modals/saving", store: "dsModals" %></div>
+          <div><%= render "studio/modals/saving", store: "dsModals",
+                    resolve_expr: "$store.dsModals.close()" %></div>
         </template>
 
         <%# --- Web3 --- %>
@@ -320,9 +349,12 @@
         </template>
 
         <%# --- System and status (reusable card blocks) --- %>
+        <%# ds-processing demos the min-duration convention on the canonical block:
+            resolve_expr auto-swaps to the success card after min_duration. %>
         <template x-if="$store.dsModals.current().id === 'ds-processing'">
           <div><%= render "studio/modals/blocks/processing_card",
-                    title: "Confirming entry", message: "Talking to the server…" %></div>
+                    title: "Confirming entry", message: "Talking to the server…",
+                    resolve_expr: "$store.dsModals.swap('ds-success')" %></div>
         </template>
         <template x-if="$store.dsModals.current().id === 'ds-success'">
           <div><%= render "studio/modals/blocks/success_card",
@@ -508,68 +540,6 @@
     </div>
   </section>
 
-  <%# ===================================================================== %>
-  <%# 1b. ELIGIBILITY + ENTRY %>
-  <%# ===================================================================== %>
-  <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">Eligibility &amp; entry</h3>
-        <% if age_gate_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">age gate on</span>
-        <% else %>
-          <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">age gate off</span>
-        <% end %>
-      </div>
-      <p class="text-muted text-sm">
-        The pre-entry gate and the entry-purchase flow. The <strong>age gate</strong>
-        (<code class="font-mono text-2xs">studio/modals/blocks/_age_verify</code>) is a
-        NEW engine primitive gated by
-        <code class="font-mono text-2xs">Studio.feature?(:age_gate)</code> &mdash; a DOB
-        modal whose minimum age, jurisdiction label, endpoint, and legal copy are all
-        <strong>app-supplied</strong> (the engine hardcodes no policy). It is the heavier
-        sibling of the <code class="font-mono text-2xs">shared/_age_attestation</code>
-        checkbox inside Sign in above &mdash; <strong>run one or the other</strong>. The
-        <strong>entry-tokens</strong> flow is <strong>app-specific</strong> (payments
-        product): documented here composing engine chrome, but the packs, rails, and
-        the on-chain mint stay app-owned.
-      </p>
-    </div>
-    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-      <%# Age gate — engine primitive, gated on :age_gate (disabled-but-present). %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Age gate (DOB)",
-            reference: %(the "Age gate" DOB modal (studio-engine studio/modals/blocks/_age_verify) — a NEW engine primitive; the app supplies min_age / state / submit_url / fine_print and the engine hardcodes no legal policy. In this demo, Confirm & Continue advances to the Entry tokens purchase (page-level dsModals wiring on the primitive's 'age-verified' hook; the primitive's real submit posts to submit_url). Open with $store.dsModals.open('age-verify')),
-            open_expr: "$store.dsModals.open('age-verify')",
-            glow_when: ds_glow.call("age-verify"),
-            disabled: !age_gate_on, openable: true, disabled_label: "age gate off" } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2 text-center">
-          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
-          <div class="grid grid-cols-3 gap-1">
-            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
-            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
-            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
-          </div>
-          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
-        </div>
-      <% end %>
-
-      <%# Entry tokens — app-specific flow, documented (not capability-gated). %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Entry tokens",
-            reference: %(the "Entry tokens" purchase flow (app-specific — documented in the engine style guide composing studio/modals/blocks chrome). The packs, pricing, rails, and on-chain mint stay app-owned. Open with $store.dsModals.open('entry-tokens', { step: 'picker' })),
-            open_expr: "$store.dsModals.open('entry-tokens', { step: 'picker' })",
-            glow_when: ds_glow.call("entry-tokens") } 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-20 mx-auto 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-6 w-full rounded border" style="border-color: var(--color-primary)"></span>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-        </div>
-      <% end %>
-    </div>
-  </section>
-
   <%# ===================================================================== %>
   <%# 2. PROFILE — crop / upload, live via cropper_assets %>
   <%# ===================================================================== %>
@@ -751,12 +721,13 @@
   </section>
 
   <%# ===================================================================== %>
-  <%# 4. WEB3 — gated by Studio.feature?(:web3); off = disabled-but-present-yet-openable %>
+  <%# 2. WEB3 CONTEST — the walked wallet -> on-chain flow (glow follows it). %>
+  <%# Gated by :web3; off = disabled-but-present-yet-openable. %>
   <%# ===================================================================== %>
   <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">Web3</h3>
+        <h3 class="text-xl font-bold text-heading">Web3 Contest</h3>
         <% if web3_on %>
           <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">enabled on this app</span>
         <% else %>
@@ -764,21 +735,31 @@
         <% end %>
       </div>
       <p class="text-muted text-sm">
-        Wallet + on-chain modals, ported into the engine and gated by
+        The wallet + on-chain modals, ported into the engine and gated by
         <code class="font-mono text-2xs">Studio.feature?(:web3)</code>. Web3 is
         <strong><%= web3_on ? "on" : "off" %></strong> here, so these render
         <%= web3_on ? "live." : "greyed and badged — but STILL openable as a preview." %>
-        The Connect-wallet picker ships its <strong>Phantom / Solflare / Backpack
-        brand marks inline from the engine</strong>
+        The first three cards are a <strong>walked flow</strong> &mdash;
+        <strong>Connect Wallet &rarr; Processing on-chain transaction &rarr; On-chain
+        success</strong> &mdash; and the live card <strong>glows</strong>, following the
+        flow as it advances (open Connect Wallet and pick a wallet to watch it walk).
+        The <strong>Processing</strong> card is a load modal: its
+        <strong>success/error toggle</strong> chooses whether it resolves to success
+        or the error state, after the <strong>minimum-visible duration</strong>
+        (<code class="font-mono text-2xs">studio/modals/_load_convention</code>). The
+        Connect-wallet picker ships its <strong>Phantom / Solflare / Backpack brand
+        marks inline from the engine</strong>
         (<code class="font-mono text-2xs">studio/modals/blocks/_wallet_brand_sprite</code>),
         so every app inherits them with no per-app icon files.
       </p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%# 1. Connect wallet — the walk's entry; picking a wallet swaps to Processing. %>
       <%= render layout: "style/modal_specimen", locals: {
             label:     "Connect wallet",
-            reference: %(the Web3 "Connect wallet" picker (studio-engine style/modals/_wallet_connect) — open with $store.dsModals.open('wallet-connect')),
+            reference: %(the Web3 Contest "Connect wallet" picker (studio-engine style/modals/_wallet_connect) — the walk's entry: picking a wallet runs a brief connecting state then swaps to the on-chain Processing modal. Open with $store.dsModals.open('wallet-connect')),
             open_expr: "$store.dsModals.open('wallet-connect')",
+            glow_when: ds_glow.call("wallet-connect"),
             disabled: !web3_on, openable: true } 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-20 rounded" style="background: var(--color-text); opacity: .18"></span>
@@ -787,10 +768,14 @@
         </div>
       <% end %>
 
+      <%# 2. Processing — the load modal; the success/error toggle picks the resolution. %>
       <%= render layout: "style/modal_specimen", locals: {
-            label:     "On-chain tx · processing",
-            reference: %(the Web3 "On-chain tx" modal, processing state (style/modals/_onchain_tx via $store.dsSolanaModal) — open with $store.dsModals.open('onchain-tx', { state: 'processing', title: 'Confirming on-chain', message: 'Waiting for the wallet signature…' })),
-            open_expr: "$store.dsModals.open('onchain-tx', { state: 'processing', title: 'Confirming on-chain', message: 'Waiting for the wallet signature…' })",
+            label:     "Processing on-chain tx",
+            reference: %(the Web3 Contest "Processing" on-chain load modal (style/modals/_onchain_tx via $store.dsSolanaModal) — holds the spinner at least MIN_LOAD_MS, then auto-resolves to success (or the error state when the toggle is set). Open with $store.dsModals.open('onchain-tx', { state: 'processing', demoResolve: true, demoError: false })),
+            card_data: "opts: { demoError: false }",
+            toggles:   [{ model: "opts.demoError", label: "Resolve to error" }],
+            open_expr: "$store.dsModals.open('onchain-tx', { state: 'processing', title: 'Confirming on-chain', message: 'Waiting for the wallet signature…', demoResolve: true, demoError: opts.demoError })",
+            glow_when: ds_glow.call("onchain-tx", state: "processing"),
             disabled: !web3_on, openable: 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="loading-dots mx-auto"><span></span><span></span><span></span></div>
@@ -798,10 +783,12 @@
         </div>
       <% end %>
 
+      <%# 3. On-chain success — the resolved success end-state (the walk's finish). %>
       <%= render layout: "style/modal_specimen", locals: {
-            label:     "On-chain tx · success",
-            reference: %(the Web3 "On-chain tx" modal, generic-success state (style/modals/_onchain_tx + studio/modals/blocks/_onchain_success) — open with $store.dsModals.open('onchain-tx', { state: 'success', txSignature: '…', successTitle: 'Mint complete' })),
+            label:     "On-chain success",
+            reference: %(the Web3 Contest "On-chain success" state (style/modals/_onchain_tx + studio/modals/blocks/_onchain_success) — the resolved success card the walk lands on. Open with $store.dsModals.open('onchain-tx', { state: 'success', txSignature: '…', successTitle: 'Mint complete' })),
             open_expr: "$store.dsModals.open('onchain-tx', { state: 'success', txSignature: '5xTrDemoSignature1234567890', successTitle: 'Mint complete', successSubtitle: 'Your on-chain action confirmed.', ctaLabel: 'View wallet', ctaHref: null })",
+            glow_when: ds_glow.call("onchain-tx", state: "success"),
             disabled: !web3_on, openable: 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)">
@@ -811,10 +798,12 @@
         </div>
       <% end %>
 
+      <%# On-chain error — the resolved error end-state (the toggle's other branch). %>
       <%= render layout: "style/modal_specimen", locals: {
-            label:     "On-chain tx · error",
-            reference: %(the Web3 "On-chain tx" modal, error state (style/modals/_onchain_tx) — open with $store.dsModals.open('onchain-tx', { state: 'error', title: "Couldn't confirm", errorMessage: 'The transaction was rejected. Give it another try.' })),
+            label:     "On-chain error",
+            reference: %(the Web3 Contest "On-chain error" state (style/modals/_onchain_tx) — the resolved error card the Processing toggle resolves to. Open with $store.dsModals.open('onchain-tx', { state: 'error', title: "Couldn't confirm", errorMessage: 'The transaction was rejected. Give it another try.' })),
             open_expr: "$store.dsModals.open('onchain-tx', { state: 'error', title: 'Could not confirm', errorMessage: 'The transaction was rejected. Give it another try.' })",
+            glow_when: ds_glow.call("onchain-tx", state: "error"),
             disabled: !web3_on, openable: 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>
@@ -822,9 +811,10 @@
         </div>
       <% end %>
 
+      <%# Wallet deposit — standalone top-up card (not part of the walk). %>
       <%= render layout: "style/modal_specimen", locals: {
             label:     "Wallet deposit",
-            reference: %(the Web3 "Wallet deposit" top-up card (style/modals/_wallet_deposit) — open with $store.dsModals.open('wallet-deposit', { neededCents: 500, usdcCents: 120, usdtCents: 0, address: 'Fo1L5…' })),
+            reference: %(the Web3 Contest "Wallet deposit" top-up card (style/modals/_wallet_deposit) — open with $store.dsModals.open('wallet-deposit', { neededCents: 500, usdcCents: 120, usdtCents: 0, address: 'Fo1L5…' })),
             open_expr: "$store.dsModals.open('wallet-deposit', { neededCents: 500, usdcCents: 120, usdtCents: 0, address: 'Fo1L5demoWALLETaddr9xQ2' })",
             disabled: !web3_on, openable: true } do %>
         <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
@@ -840,7 +830,7 @@
           Rewards below (gated by :leveling). %>
       <%= render layout: "style/modal_specimen", locals: {
             label:     "Entry confirmed",
-            reference: %(the Web3 "Entry confirmed" celebration (studio/modals/blocks/_entry_confirmed, composed via _success_card's yield — branded tx link + heading + drain CTA; the seeds bar is gated off by :leveling and stays hidden here) — open with $store.dsModals.open('entry-confirmed', { txSignature: '…', lobbyUrl: null, seedsEarned: 0 })),
+            reference: %(the Web3 Contest "Entry confirmed" celebration (studio/modals/blocks/_entry_confirmed, composed via _success_card's yield — branded tx link + heading + drain CTA; the seeds bar is gated off by :leveling and stays hidden here) — open with $store.dsModals.open('entry-confirmed', { txSignature: '…', lobbyUrl: null, seedsEarned: 0 })),
             open_expr: "$store.dsModals.open('entry-confirmed', { txSignature: '5xTrDemoSignature1234567890abcXYZ', lobbyUrl: null, seedsEarned: 0, seedsTotal: 40 })",
             disabled: !web3_on, openable: true } do %>
         <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
@@ -855,6 +845,144 @@
     </div>
   </section>
 
+  <%# ===================================================================== %>
+  <%# 3. CONTEST ENTRY & ELIGIBILITY — moved directly under Web3 Contest. The %>
+  <%# walked entry flow (glow follows), plus the honest web2/web3 map. %>
+  <%# ===================================================================== %>
+  <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">Contest entry &amp; eligibility</h3>
+        <% if age_gate_on %>
+          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">age gate on</span>
+        <% else %>
+          <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">age gate off</span>
+        <% end %>
+      </div>
+      <p class="text-muted text-sm">
+        The pre-entry gate and the full entry flow. The <strong>age gate</strong>
+        (<code class="font-mono text-2xs">studio/modals/blocks/_age_verify</code>) is an
+        engine primitive gated by
+        <code class="font-mono text-2xs">Studio.feature?(:age_gate)</code> &mdash; a DOB
+        modal whose minimum age, jurisdiction label, endpoint, and legal copy are all
+        <strong>app-supplied</strong> (the engine hardcodes no policy). The entry flow is
+        a <strong>walked sequence</strong> &mdash; <strong>Entry tokens &rarr; Payment
+        processing &rarr; Entry Tokens Minted &rarr; Contest enter processing &rarr;
+        Contest entered</strong> &mdash; and the live card <strong>glows</strong>,
+        following the step machine (the two load steps honor the same min-duration
+        convention as Web3 Contest above).
+      </p>
+      <%# The web2/web3 finding — a real divergence, stated honestly, not invented. %>
+      <div class="mt-2 rounded-lg border border-subtle bg-surface p-3 text-xs text-secondary leading-snug">
+        <p class="text-heading font-semibold mb-1">Web2 vs web3 — the honest map</p>
+        <p class="mb-1">
+          The two funding paths <strong>diverge at the front-end and the entry-submit
+          endpoint, then converge</strong>. <strong>Web2</strong> (card / Stripe /
+          Coinflow / PayPal) mints one prepaid entry token per credit on-chain after
+          payment clears, then <strong>consumes</strong> one token to enter.
+          <strong>Web3</strong> (wallet / USDC on-chain) funds USDC directly and
+          <strong>mints no token</strong> &mdash; the mint&nbsp;&rarr;&nbsp;consume prelude
+          is web2-only.
+        </p>
+        <p>
+          Both create the <strong>same on-chain Entry PDA</strong> and resolve to the
+          <strong>same “Entry Confirmed” card</strong>. The walk below demos the web2
+          path end-to-end; web3 skips the mint and joins at
+          <strong>enter&nbsp;&rarr;&nbsp;entered</strong>.
+        </p>
+      </div>
+    </div>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%# Age gate — engine primitive, gated on :age_gate (disabled-but-present). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Age gate (DOB)",
+            reference: %(the "Age gate" DOB modal (studio-engine studio/modals/blocks/_age_verify) — an engine primitive; the app supplies min_age / state / submit_url / fine_print and the engine hardcodes no legal policy. In this demo, Confirm & Continue advances to the Entry tokens purchase (page-level dsModals wiring on the primitive's 'age-verified' hook; the primitive's real submit posts to submit_url). Open with $store.dsModals.open('age-verify')),
+            open_expr: "$store.dsModals.open('age-verify')",
+            glow_when: ds_glow.call("age-verify"),
+            disabled: !age_gate_on, openable: true, disabled_label: "age gate off" } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2 text-center">
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <div class="grid grid-cols-3 gap-1">
+            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
+            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
+            <span class="h-6 rounded border" style="border-color: var(--color-border-strong)"></span>
+          </div>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# 1. Entry tokens — the picker (walk's entry). Picking a pack advances. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Entry tokens",
+            reference: %(the "Entry tokens" picker (app-specific — documented composing studio/modals/blocks chrome). The packs, pricing, rails, and on-chain mint stay app-owned. Picking a pack walks Payment processing -> Minted -> enter -> entered. Open with $store.dsModals.open('entry-tokens', { step: 'picker' })),
+            open_expr: "$store.dsModals.open('entry-tokens', { step: 'picker' })",
+            glow_when: ds_glow.call("entry-tokens", step: "picker", step_default: "picker") } 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-20 mx-auto 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-6 w-full rounded border" style="border-color: var(--color-primary)"></span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+        </div>
+      <% end %>
+
+      <%# 2. Payment processing — the mint-at-purchase load step (web2). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Payment processing",
+            reference: %(the "Payment processing" step (entry-tokens step 'confirming') — "Confirming your purchase…" over "Payment cleared — a server job mints one prepaid entry credit per token on-chain." A load modal; honors the min-duration convention then auto-advances to Entry Tokens Minted. Open with $store.dsModals.open('entry-tokens', { step: 'confirming', mintedCount: 3, mintedBalance: '3' })),
+            open_expr: "$store.dsModals.open('entry-tokens', { step: 'confirming', mintedCount: 3, mintedBalance: '3' })",
+            glow_when: ds_glow.call("entry-tokens", step: "confirming", step_default: "picker") } 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="loading-dots mx-auto"><span></span><span></span><span></span></div>
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-1.5 w-16 mx-auto rounded" style="background: var(--color-text); opacity: .12"></span>
+        </div>
+      <% end %>
+
+      <%# 3. Entry Tokens Minted — ready to consume at entry (hold to confirm). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Entry Tokens Minted",
+            reference: %(the "Entry Tokens Minted" step (entry-tokens step 'minted') — "You now have N available." Holding to confirm consumes one token on-chain to create the contest entry (advances to Contest enter processing). Open with $store.dsModals.open('entry-tokens', { step: 'minted', mintedCount: 3, mintedBalance: '3' })),
+            open_expr: "$store.dsModals.open('entry-tokens', { step: 'minted', mintedCount: 3, mintedBalance: '3' })",
+            glow_when: ds_glow.call("entry-tokens", step: "minted", step_default: "picker") } 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-primary) 15%, transparent)">
+            <span class="text-sm font-bold" style="color: var(--color-primary)">3</span>
+          </div>
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%# 4. Contest enter processing — the on-chain consume load step. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Contest enter processing",
+            reference: %(the "Contest enter processing" step (entry-tokens step 'entering') — "Confirming your entry…" over "Consuming one token on-chain to create your contest entry." A load modal; honors the min-duration convention then auto-advances to Contest entered. Open with $store.dsModals.open('entry-tokens', { step: 'entering' })),
+            open_expr: "$store.dsModals.open('entry-tokens', { step: 'entering' })",
+            glow_when: ds_glow.call("entry-tokens", step: "entering", step_default: "picker") } 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="loading-dots mx-auto"><span></span><span></span><span></span></div>
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-1.5 w-16 mx-auto rounded" style="background: var(--color-text); opacity: .12"></span>
+        </div>
+      <% end %>
+
+      <%# 5. Contest entered — the shared Entry Confirmed finish (web2 + web3 converge). %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Contest entered",
+            reference: %(the "Contest entered" success (entry-tokens step 'entered') — "Good Luck / Entry Confirmed" with the branded on-chain tx link and a Contest Lobby CTA. The SAME finish both web2 and web3 entries converge on. Open with $store.dsModals.open('entry-tokens', { step: 'entered', txSignature: '…' })),
+            open_expr: "$store.dsModals.open('entry-tokens', { step: 'entered', txSignature: '5xTrDemoEntrySignature1234567890abc' })",
+            glow_when: ds_glow.call("entry-tokens", step: "entered", step_default: "picker") } 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>
+          <span class="block h-2 w-20 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-4 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+    </div>
+  </section>
+
   <%# ===================================================================== %>
   <%# 5. SYSTEM AND STATUS (reusable card blocks) %>
   <%# ===================================================================== %>

data/app/views/style/modals/_entry_tokens.html.erb

@@ -1,20 +1,30 @@
 <%#
-  Living style guide specimen — the entry-token purchase flow. This documents an
-  APP-SPECIFIC flow (Turf Monster's "Get Entry Tokens"); the engine deliberately
-  does NOT own the packs, pricing, or payment rails. The specimen composes only
-  engine CHROME (studio/modals/blocks/shell, card_header, progress_pill) and
-  represents the packs as an illustrative demo — the app owns the payment logic
-  and the on-chain mint.
+  Living style guide specimen — the contest entry & eligibility flow. This
+  documents an APP-SPECIFIC flow (Turf Monster's "Get Entry Tokens" → enter);
+  the engine deliberately does NOT own the packs, pricing, payment rails, or any
+  on-chain write. The specimen composes only engine CHROME (studio/modals/blocks/
+  shell, card_header, progress_pill, solana_tx_link) and represents the packs and
+  the on-chain moments as an illustrative demo — the app owns the money + signing.
 
   Opened on the page-scoped dsModals host with an internal step machine on
-  props.step: picker -> confirming -> minted. Single-root templates throughout.
+  props.step, the full web2 walk:
 
-  On-chain model (documented, not owned here): an entry token is a PROGRAM-OWNED
-  prepaid entry credit recorded on-chain (a per-token account), NOT a fungible
-  SPL token held in the user's wallet. Two distinct on-chain moments: (1) MINT at
-  purchase, server-signed after the payment clears — not on the buyer's click;
-  (2) CONSUME at entry, when the app's hold-to-confirm gesture spends one token to
-  create the contest entry.
+    picker -> confirming -> minted -> entering -> entered
+
+  Single-root templates throughout. The two load steps (confirming, entering)
+  honor the minimum-visible-duration convention (studio/modals/_load_convention):
+  the spinner holds at least MIN_LOAD_MS, then auto-advances (demo mode) —
+  resolveAt = max(min_duration, actual_completion).
+
+  On-chain model (documented, not owned here). An entry token is a PROGRAM-OWNED
+  prepaid entry credit recorded on-chain (a per-token account), NOT a fungible SPL
+  token in the user's wallet. WEB2 (card / Stripe / Coinflow / PayPal) has two
+  on-chain moments: (1) MINT at purchase, server-signed after the payment clears —
+  not on the buyer's click; (2) CONSUME at entry, when the hold-to-confirm gesture
+  spends one token to create the contest entry. WEB3 (wallet / USDC on-chain)
+  funds USDC directly and mints NO token — so the mint→consume prelude is
+  web2-only. Both paths converge at the SAME on-chain Entry PDA and the SAME
+  "Entry Confirmed" card.
 %>
 <%
   # Illustrative packs only — a real app reads these from its own config
@@ -29,10 +39,20 @@
        get props() { var c = Alpine.store('dsModals').current(); return (c && c.props) || {}; },
        buy(count, balance) {
          Alpine.store('dsModals').advance({ step: 'confirming', mintedCount: count, mintedBalance: balance });
-         setTimeout(function () {
+       },
+       confirmEntry() {
+         Alpine.store('dsModals').advance({ step: 'entering' });
+       },
+       // Demo auto-resolve honoring the min-load convention: hold the spinner at
+       // least MIN_LOAD_MS, then advance — but only while this modal is still on
+       // the given step (guards against an early close / manual advance).
+       autoAdvance(fromStep, patch) {
+         window.StudioModals.holdAtLeast(window.StudioModals.MIN_LOAD_MS).then(function () {
            var c = Alpine.store('dsModals').current();
-           if (c && c.id === 'entry-tokens') Alpine.store('dsModals').advance({ step: 'minted' });
-         }, 1300);
+           if (c && c.id === 'entry-tokens' && c.props.step === fromStep) {
+             Alpine.store('dsModals').advance(patch);
+           }
+         });
        }
      }" class="relative">
 
@@ -68,36 +88,52 @@
         <% end %>
       </div>
 
-      <%# Rails — token-funded only. The picker documents which rails mint tokens.
-          The USDC-direct path is intentionally NOT a pack here (it's a separate
-          rail that transfers USDC and mints no token). %>
+      <%# Rails — which funding path mints tokens vs funds an entry directly. %>
       <div class="mt-4 flex flex-wrap items-center justify-center gap-x-4 gap-y-1 text-xs text-muted">
         <span>Pay by card</span>
         <span aria-hidden="true">&middot;</span>
         <span>PayPal / Venmo</span>
+        <span aria-hidden="true">&middot;</span>
+        <span>Coinflow</span>
       </div>
-      <p class="text-center text-2xs text-muted mt-1">USDC-direct entry is a separate rail — it funds an entry with no token.</p>
+      <p class="text-center text-2xs text-muted mt-1">
+        These are the <strong>web2</strong> rails — they mint prepaid entry tokens.
+        The <strong>web3</strong> path funds USDC on-chain directly and mints no token.
+      </p>
 
-      <%# The seam callout — what the engine owns vs what the app owns. %>
+      <%# The seam callout — what the engine owns vs the app, plus the honest
+          web2/web3 map (a real divergence, not invented). %>
       <div class="mt-4 rounded-lg border border-subtle bg-surface p-3 text-2xs text-secondary leading-snug">
         <p class="text-heading font-semibold mb-1">App-specific flow, engine chrome</p>
+        <p class="mb-2">
+          The engine supplies only the shell, header, progress pill, and tx link. The
+          packs, pricing, payment rails, and every on-chain write are
+          <strong>app-owned</strong> — this specimen represents them as a demo. On-chain,
+          an entry token is a <strong>prepaid entry credit recorded on-chain</strong>
+          (a per-token account), not a wallet-held token.
+        </p>
+        <p class="text-heading font-semibold mb-1">Web2 vs web3 — where they diverge and converge</p>
         <p class="mb-1">
-          The engine supplies only the shell, header, and progress pill. The packs,
-          pricing, payment rails, and the on-chain mint are <strong>app-owned</strong> —
-          this specimen represents them as a demo.
+          <strong>Web2</strong> (card / Stripe / Coinflow / PayPal): a server job mints
+          one prepaid entry credit per token on-chain once payment clears, then
+          hold-to-confirm <strong>consumes</strong> one token to create the entry.
+        </p>
+        <p class="mb-1">
+          <strong>Web3</strong> (wallet / USDC on-chain): funds USDC directly and
+          <strong>mints no token</strong> — the mint → consume prelude is web2-only.
         </p>
         <p>
-          On-chain, an entry token is a <strong>prepaid entry credit recorded on-chain</strong>
-          (not a transferable token held in your wallet): minted server-side once payment
-          clears, then <strong>consumed</strong> when the app's hold-to-confirm creates the entry.
+          Both paths converge on the <strong>same on-chain Entry PDA</strong> and the
+          <strong>same “Entry Confirmed” card</strong> — divergent funding front-end,
+          one shared entry → entered finish.
         </p>
       </div>
     </div>
   </template>
 
-  <%# ===== CONFIRMING (mint-at-purchase) ===== %>
+  <%# ===== CONFIRMING (payment processing — mint-at-purchase) ===== %>
   <template x-if="props.step === 'confirming'">
-    <div x-init="setTimeout(function () { var c = Alpine.store('dsModals').current(); if (c && c.id === 'entry-tokens') Alpine.store('dsModals').advance({ step: 'minted' }); }, 1300)">
+    <div x-init="autoAdvance('confirming', { step: 'minted' })">
       <%= render "studio/modals/blocks/card_header",
             spinner: true,
             title: "Confirming your purchase…",
@@ -114,10 +150,39 @@
         You now have <span class="font-bold text-primary font-mono" x-text="props.mintedBalance"></span> available.
       <% end %>
       <p class="text-xs text-secondary text-center mb-4 leading-snug">
-        In the app, holding to confirm now <strong>consumes one token on-chain</strong> to
-        create your contest entry, then resolves to the shared Entry Confirmed card.
+        Holding to confirm now <strong>consumes one token on-chain</strong> to create
+        your contest entry.
       </p>
-      <button @click="$store.dsModals.close()" class="btn btn-primary btn-lg w-full">Done</button>
+      <button @click="confirmEntry()" class="btn btn-primary btn-lg w-full">Hold to Confirm Entry</button>
+      <button @click="$store.dsModals.close()"
+              class="block mx-auto mt-3 text-xs text-secondary hover:text-heading underline underline-offset-2">
+        I&rsquo;ll confirm later
+      </button>
+    </div>
+  </template>
+
+  <%# ===== ENTERING (contest enter processing — the on-chain consume) ===== %>
+  <template x-if="props.step === 'entering'">
+    <div x-init="autoAdvance('entering', { step: 'entered', txSignature: '5xTrDemoEntrySignature1234567890abc' })">
+      <%= render "studio/modals/blocks/card_header",
+            spinner: true,
+            title: "Confirming your entry…",
+            subtitle: "Consuming one token on-chain to create your contest entry." %>
+    </div>
+  </template>
+
+  <%# ===== ENTERED (contest entered — the shared Entry Confirmed finish) ===== %>
+  <template x-if="props.step === 'entered'">
+    <div>
+      <%= render "studio/modals/blocks/card_header",
+            size: :lg, icon_color: 'primary',
+            title: "Good Luck", subtitle: "Entry Confirmed" %>
+      <%= render "studio/modals/blocks/solana_tx_link", tx_signature_key: "props.txSignature" %>
+      <button @click="$store.dsModals.close()" class="btn btn-primary btn-lg w-full">Contest Lobby &#x2694;&#xFE0F;</button>
+      <button @click="$store.dsModals.close()"
+              class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+        Dismiss
+      </button>
     </div>
   </template>
 </div>

data/app/views/style/modals/_onchain_tx.html.erb

@@ -24,6 +24,30 @@
              }, 100);
            }
          });
+         // Demo auto-resolve (min-load convention): a processing modal opened with
+         // demoResolve holds its spinner at least MIN_LOAD_MS, then advances to
+         // success — or to error when demoError is set (the Processing specimen's
+         // success/error toggle). Guarded to the still-open, still-processing modal.
+         var entry = Alpine.store('dsModals').current();
+         if (!entry || entry.id !== 'onchain-tx' || !entry.props ||
+             entry.props.state !== 'processing' || !entry.props.demoResolve) return;
+         var minMs = entry.props.minDuration ||
+                     (window.StudioModals && window.StudioModals.MIN_LOAD_MS) || 1400;
+         window.StudioModals.holdAtLeast(minMs).then(function () {
+           var cur = Alpine.store('dsModals').current();
+           if (!cur || cur.id !== 'onchain-tx' || cur.props.state !== 'processing') return;
+           if (entry.props.demoError) {
+             Alpine.store('dsModals').advance({ state: 'error',
+               title: 'Could not confirm',
+               errorMessage: 'The transaction was rejected. Give it another try.' });
+           } else {
+             Alpine.store('dsModals').advance({ state: 'success',
+               txSignature: '5xTrDemoSignature1234567890abcXYZ',
+               successTitle: 'Mint complete',
+               successSubtitle: 'Your on-chain action confirmed.',
+               ctaLabel: 'View wallet', ctaHref: null });
+           }
+         });
        }
      }">
 

data/app/views/style/modals/_wallet_connect.html.erb

@@ -60,7 +60,18 @@
          if (!this.attested()) return;
          this.connecting = true; this.picking = name; this.error = '';
          var self = this;
-         setTimeout(function () { self.connecting = false; self.picking = ''; Alpine.store('dsModals').close(); }, 1100);
+         // DEMO walk continuity: a picked wallet runs a brief connecting state,
+         // then swaps to the on-chain tx modal in its processing state, which
+         // auto-resolves to on-chain success (demoResolve). So the glow follows
+         // Connect Wallet -> Processing -> On-chain success. (No real connect.)
+         setTimeout(function () {
+           self.connecting = false; self.picking = '';
+           Alpine.store('dsModals').swap('onchain-tx', {
+             state: 'processing', demoResolve: true, demoError: false,
+             title: 'Confirming on-chain',
+             message: 'Waiting for the wallet signature…'
+           });
+         }, 1100);
        },
        deepLink() {
          if (!this.attested()) return;

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.25.1"
+  VERSION = "0.27.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.25.1
+  version: 0.27.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -273,6 +273,7 @@ files:
 - app/views/studio/modals/_crop_photo.html.erb
 - app/views/studio/modals/_host.html.erb
 - app/views/studio/modals/_image_upload.html.erb
+- app/views/studio/modals/_load_convention.html.erb
 - app/views/studio/modals/_saving.html.erb
 - app/views/studio/modals/auth/_resend_footer.html.erb
 - app/views/studio/modals/blocks/_age_verify.html.erb