studio-engine 0.69.5 → 0.70.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ac04785253cb277ef70cd1d6398b81718e223adc7e300c1a19329183a88be5
-  data.tar.gz: 01c13c3974eb5da7887fc82e77f3526eb50af53a3e590b993a7602914e8daa81
+  metadata.gz: f1c217135776ee0fcd67dd4ed2e9a72f1aedf5260ac23cfc23615ab83754133a
+  data.tar.gz: 42878ae8f85ed0c911b99c940e3c5094ca7329fed4bbb727ebfa4466bba99dfb
 SHA512:
-  metadata.gz: db96cbe447a67732cc7d2babc54f605071ccd9e3d77d20da4fb7486c5e89f5354e21dc34066757ec7bde7f66fb7fb08e257a15c364753d3a98f34ea8065df25b
-  data.tar.gz: f8a47251bf78b0c3bab42dfc743565c2dba66502f6f204516718144cd9506a5206bf6342b7ce496fa12f6f67a34727dc8fc7cbc5e03529ce5d3ab1e3727b4761
+  metadata.gz: d72745a5c54559b745fc0fefe1ac1c45b3921efeccbe5769f3b1da5ceaa1e11463c317984847fc1300fb0387610c33c4f0c7504e279871630f5535db563c935e
+  data.tar.gz: 16be22a876c99c848169a2dcd551593ff4b8c377427acd9d84c04bf732847d261422c79d9b7f30397bf8b04c2d13a894999cc542a95bb1037f9deeaea0c5c32a

data/CHANGELOG.md

@@ -6,6 +6,43 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **A `required` mode on the shared first-name card.**
+  `studio/modals/onboarding/_first_name` grows one local. `required: true`
+  renders the card with BOTH skip affordances gone — the "Skip for now" button
+  is not emitted at all, and the × merely CLOSES and is labelled `Close` — and
+  swaps the sub-copy to the audience being gated. Default `false`, so the
+  post-auth chain card McRitchie Studio renders today does not move.
+
+  **IT IS FOR A HOST THAT GATES SOMETHING ON THE NAME.** turf-monster's entry
+  gate opens this card as the first validation of hold-to-confirm, and that gate
+  reads the stored COLUMN — so a recorded skip buys the user nothing and the
+  Skip link is a door painted on a wall, promising a way past a wall that does
+  not move.
+
+  **IT IS DELIBERATELY NOT A TRAP.** Closing stays reachable, because abandoning
+  the flow and slipping past the gate are two different things: the × still
+  dismisses the card, it just stops calling `skip()` and stops claiming it did.
+  A `required` that also removed the × would satisfy every "hides the skip"
+  reading and be a worse card, so the two are asserted as a PAIR.
+
+  **RESOLVED SERVER-SIDE, not through an Alpine `x-show`** — the source this was
+  ported from hides its skip button reactively, which leaves a button that must
+  not exist sitting in the DOM and clickable for as long as Alpine has not
+  mounted, and there for good if it never does. `required` is known at render
+  time, so the button is simply never emitted.
+
+  The default render is asserted **byte-for-byte identical** to `required:
+  false`, which is what pins the existing consumer. Mutation-checked 5/5:
+  flipping the default, un-hiding the skip button, making the × always skip,
+  freezing the label, and freezing the sub-copy each turn the suite red on a
+  different test.
+
+  This was the LAST mode turf-monster's own 240-line `modals/_onboarding` had
+  that the gem did not, so that copy can be deleted next release. A host wanting
+  both modes mounts two `<template x-if>` ids rather than branching one at
+  runtime — which is how the two cards already differ in copy, not just in
+  affordances.
+
 - **Knowledge coverage view** — `/admin/knowledge/coverage` +
   `Studio::KnowledgeExpectation`: the "what SHOULD exist" half of the
   knowledge layer. Expectations carry an entity, folder, provenance
@@ -21,6 +58,41 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   `Studio.draw_knowledge_routes` opt-in. Built for the Commercial Welding
   65-item diligence tracker; app-agnostic like the rest of the layer.
 
+- **The style guide grows the two modal simulators that review ENGINE
+  behaviour** — `#modals-motion-registry` ("Enter & leave animations") and
+  `#modals-stack-mechanics` ("Stack behaviour") in `style/_modals`. Both are
+  ported from turf-monster's `/admin/modals` gallery, which is being deleted:
+  the rest of that page was consumer showroom, but these two exercised engine
+  mechanics — the `window.ModalAnimations` registry, and the modal stack's
+  dismissibility / `holdAtLeast` / LIFO rules — and would have gone with it.
+
+  The motion section BUILDS ITS CONTROLS FROM THE LIVE REGISTRY at load
+  (a button and a dropdown option per registered key, per channel), so
+  registering a new animation surfaces it on the guide with no edit to the
+  page. That is the property the section exists for, and
+  `test/views/style_guide_modal_simulator_test.rb` pins it from both sides:
+  the containers must ship EMPTY, and the build must enumerate
+  `window.ModalAnimations` rather than a local literal.
+
+  The stack demos drive `$store.dsModals` and the guide's own `onchain-tx`
+  specimen directly. **One demo did not come across: "error with recovery."**
+  turf's `setRecovery(label, fn, { phantom })` is a method on that app's
+  legacy compatibility proxy and renders a recovery button on ITS `_onchain_tx`
+  card; the engine specimen's error state is `blocks/_card_header` plus a plain
+  Close, with no recovery affordance. Porting it would have meant designing a
+  new block into a shipped partial, so it was dropped rather than shimmed —
+  roughly half the ported demos drove that proxy, and none of them reference it
+  now (asserted).
+
+  **Both sections are graded in a browser**, because neither is observable from
+  the response bytes: `e2e/style_modal_simulators.spec.js` (7 specs) drives a new
+  `/lab/style_modals` lab page, which mounts the shared modal host exactly as a
+  consumer layout does — without it `window.ModalAnimations` is undefined, the
+  build produces no controls, and "the controls match the registry" would be
+  vacuously true at `0 == 0`. Each spec was verified RED against its own defect
+  reintroduced, with the lab server restarted between runs. The lane contract
+  moves 116 → 123 (`config/e2e_lane.yml`), re-derived with the lister.
+
 ### Changed
 
 - **`Gemfile.lock` resolves solana-studio 0.5.7, and a gate now keeps it there.** The lock had sat on **0.5.3 for four patch releases** while BOTH consumers shipped 0.5.7 (turf-monster `~> 0.5.3`, mcritchie-studio `~> 0.5`). Nothing was red and nothing could have been: engine CI installs with `bundler-cache: true`, so it resolves from the lock and never fresh — the drift does not self-correct and never surfaces as flakiness. It matters because `test/views/style_web3_specimens_test.rb` exists to prove "the style guide renders the REAL gem cards" and reads them off whatever the LOCK resolved; four versions behind, that guard certifies a card no consumer receives. It still passes — only its MEANING changes. MEASURED on this span, the gem's whole `app/` tree was byte-identical 0.5.3 → 0.5.7 (only `CHANGELOG.md`, `README.md` and `version.rb` differ), so this instance cost nothing, which is exactly why it went four releases unnoticed.
@@ -55,6 +127,22 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **The style guide's page-scoped modal store now resolves animations through
+  the LIVE registry, so the guide can no longer disagree with itself.**
+  `style/_modals`' `dsModals` carried a hard-coded COPY of the animation table
+  while the new simulator builds its controls from `window.ModalAnimations`.
+  The two agreed today, which is exactly why this was invisible — but a
+  consumer registering a key would have grown a control from the registry that
+  the store then resolved back to `pop`: the button said "shake", the card
+  popped, and nothing reported the gap. Its `modalAnim` now reads
+  `window.ModalAnimations` at CALL time with the same late-binding guard the
+  shared host uses (unknown keys and a gutted registry still fall back to
+  `pop`, so a miss can never throw on `.ms` and strand a modal open); the local
+  table remains only as the fallback for a guide rendered without the host.
+  MEASURED in a browser both ways: registering a new key at runtime surfaces a
+  control AND plays it, and with this fix reverted the same key surfaces a
+  control that plays `modal-card-mount`.
+
 - **Onboarding no longer truncates a surname to fit a first name's cap.**
   `Studio::OnboardingController#first_name` measured the WHOLE typed answer with
   `Studio::FIRST_NAME_MAX_LENGTH` — the PER-FIELD cap, 40. The field asks for a

data/app/views/studio/modals/onboarding/_first_name.html.erb

@@ -12,8 +12,18 @@
   Locals (all optional, defaults via local_assigns.fetch):
     submit_path — POST target for the name (default "/onboarding/first_name")
     skip_path   — POST target for the skip  (default "/onboarding/skip_first_name")
+    required    — hide the SKIP affordances (default false, which keeps today's
+                  skippable card). The × then merely CLOSES and is labelled
+                  Close, and the "Skip for now" button is not rendered. For a
+                  host that GATES something on the name: offering to skip would
+                  promise a way past a wall that does not move. Closing stays
+                  available — a required step abandons the flow, it never traps
+                  the user in it.
     heading     — (default "What should we call you?")
-    subtext     — the one-line why (default speaks about emails)
+    subtext     — the one-line why (default speaks about emails; the DEFAULT
+                  follows `required`, because a card that cannot be skipped is
+                  talking to a different audience — a host that passes its own
+                  subtext still wins)
     placeholder — (default "Alex")
     max_length  — (default Studio::FULL_NAME_MAX_LENGTH; the server stays the
                   real bound, and it REFUSES past that rather than truncating,
@@ -40,15 +50,27 @@
 <%
   submit_path = local_assigns.fetch(:submit_path, "/onboarding/first_name")
   skip_path   = local_assigns.fetch(:skip_path, "/onboarding/skip_first_name")
+  required    = local_assigns.fetch(:required, false)
   heading     = local_assigns.fetch(:heading, "What should we call you?")
-  subtext     = local_assigns.fetch(:subtext,
-                  "Just your first name — we use it to address you in emails.")
+  default_subtext = if required
+                      "One last thing — just your first name, so we can address you in emails."
+                    else
+                      "Just your first name — we use it to address you in emails."
+                    end
+  subtext     = local_assigns.fetch(:subtext, default_subtext)
   placeholder = local_assigns.fetch(:placeholder, "Alex")
   max_length  = local_assigns.fetch(:max_length, Studio::FULL_NAME_MAX_LENGTH)
   progress    = local_assigns.fetch(:progress, nil)
   modal_store = local_assigns.fetch(:modal_store, "modals")
   done_event  = local_assigns.fetch(:done_event, "onboarding-step-done")
   field_id    = local_assigns.fetch(:id, "onboarding-first-name")
+  # The × mirrors the skip affordance it sits beside: it SKIPS while the step is
+  # skippable, and merely CLOSES once it is required. Resolved here rather than in
+  # an Alpine expression because `required` is known at render time — and a skip
+  # button hidden with x-show is still in the DOM, and still clickable, for as
+  # long as Alpine has not mounted.
+  dismiss_action = required ? "$store.#{modal_store}.close()" : "skip()"
+  dismiss_label  = required ? "Close" : "Skip"
 %>
 <div x-data="{
        get props() { var c = $store.<%= modal_store %>.current(); return (c && c.props) || {}; },
@@ -101,10 +123,15 @@
     <h3 class="text-heading font-bold text-lg leading-tight text-center pt-1"><%= heading %></h3>
     <%# The × SKIPS rather than merely closing: this lands seconds after signup,
         and a close that silently abandons the chain is how a host ends up with a
-        step nobody can answer again. %>
-    <button @click="skip()"
+        step nobody can answer again.
+
+        When the host passes required: true it merely CLOSES, and says so. That
+        step is gating something the host will not let through without a name, so
+        recording a skip would promise a way past a wall that does not move.
+        Closing still works — it abandons the flow rather than slipping past it. %>
+    <button @click="<%= dismiss_action %>"
             class="absolute top-0 right-0 -mr-2 text-secondary hover:text-heading text-xl leading-none"
-            aria-label="Skip">&times;</button>
+            aria-label="<%= dismiss_label %>">&times;</button>
   </div>
   <% if progress %>
     <%= render "studio/modals/blocks/progress_pill", current: progress.first, total: progress.last %>
@@ -134,8 +161,13 @@
     </button>
   </form>
 
-  <button type="button" @click="skip()" :disabled="submitting"
-          class="mt-3 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
-    Skip for now
-  </button>
+  <%# Gone entirely when required — see the × above for why offering it there
+      would promise a way past a wall that does not move. Omitted rather than
+      hidden, for the same reason the × is resolved server-side. %>
+  <% unless required %>
+    <button type="button" @click="skip()" :disabled="submitting"
+            class="mt-3 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Skip for now
+    </button>
+  <% end %>
 </div>

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

@@ -211,7 +211,20 @@
         // slide uses the modal-card-swap-* classes regardless of these keys.
         var CLOSE_ANIM_MS = 220;
         var SWAP_IN_MS    = 220;
-        var Anim = {
+
+        // THE LIVE REGISTRY IS window.ModalAnimations, NOT THIS TABLE. This is a
+        // fallback only, for the case where the guide renders without the shared
+        // host (studio/modals/_host) that publishes the registry — both consumer
+        // layouts mount it, so in practice the lookup below always finds it.
+        //
+        // It used to be a hard-coded local copy, and that made the Enter/Leave
+        // simulator below a LIAR: the simulator builds its controls from the live
+        // registry, so a newly registered animation grew a button here while the
+        // store silently resolved the unknown key back to 'pop'. The control said
+        // "shake", the card popped, and nothing reported the gap. Reading the
+        // registry at CALL time is what makes a registered animation actually
+        // playable on this page.
+        var ANIM_FALLBACK = {
           enter: {
             pop:   { cls: 'modal-card-mount',    ms: 320 },
             shake: { cls: 'modal-card-shake-in', ms: 600 },
@@ -222,9 +235,13 @@
             slide: { cls: 'modal-card-swap-out', ms: 220 }
           }
         };
+        // Same late-binding guard, and for the same reason, as the host's own
+        // modalAnim: never return undefined. A miss would throw on .ms in close()
+        // and strand the modal open, so an unknown key falls back to 'pop'.
         function modalAnim(channel, key) {
-          var table = Anim[channel] || {};
-          return table[key] || table.pop;
+          var table = (window.ModalAnimations && window.ModalAnimations[channel]) ||
+                      ANIM_FALLBACK[channel];
+          return table[key] || table.pop || ANIM_FALLBACK[channel].pop;
         }
 
         Alpine.store('dsModals', {
@@ -766,7 +783,7 @@
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
       <%= render layout: "style/modal_specimen", locals: {
             label:     "First name",
-            reference: %(the shared onboarding first-name step (studio-engine studio/modals/onboarding/_first_name) — open with $store.dsModals.open('onboarding-first-name'). Posts to submit_path/skip_path (defaults /onboarding/first_name and /onboarding/skip_first_name) and dispatches its done_event with the steps the SERVER says remain),
+            reference: %(the shared onboarding first-name step (studio-engine studio/modals/onboarding/_first_name) — open with $store.dsModals.open('onboarding-first-name'). Posts to submit_path/skip_path (defaults /onboarding/first_name and /onboarding/skip_first_name) and dispatches its done_event with the steps the SERVER says remain. A host that GATES on the name passes required: true, which drops BOTH skip affordances and leaves the × merely closing — this specimen shows the default, skippable card),
             open_expr: "$store.dsModals.open('onboarding-first-name')",
             glow_when: ds_glow.call("onboarding-first-name")
           } do %>
@@ -1914,4 +1931,355 @@
     </div>
   </section>
 
+  <%# ===================================================================== %>
+  <%# 8. MOTION REGISTRY (the enter / leave animation simulator) %>
+  <%# ===================================================================== %>
+  <section id="modals-motion-registry" class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Enter &amp; leave animations</h3>
+      <p class="text-muted text-sm">
+        The per-modal entrance/exit registry &mdash;
+        <code class="font-mono text-2xs">window.ModalAnimations</code>, published by
+        <code class="font-mono text-2xs">studio/modals/_host</code>. Any modal opens with
+        <code class="font-mono text-2xs">open(id, { enterAnim, exitAnim })</code>; omit either
+        and it uses <code class="font-mono text-2xs">pop</code>. Every control below is
+        <strong class="text-heading font-semibold">generated from the live registry</strong>,
+        so registering a new animation surfaces it here with no edit to this page. Demo card:
+        <code class="font-mono text-2xs">email-change-pending</code>.
+      </p>
+    </div>
+
+    <div class="grid gap-4 sm:grid-cols-2">
+      <%# One control per registered ENTER key, built by the script below. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">
+          Enter <span class="text-muted text-xs font-normal">&mdash; watch it arrive</span>
+        </h4>
+        <p class="text-secondary text-xs">
+          Opens the demo card with that entrance. Dismiss with Escape, click-outside, or Close.
+        </p>
+        <div id="modal-anim-enter-buttons" class="flex flex-wrap gap-2"></div>
+      </div>
+
+      <%# One control per registered EXIT key: opens with a plain entrance, then
+          auto-closes a beat later so the exit keyframe is what you watch. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">
+          Leave <span class="text-muted text-xs font-normal">&mdash; watch it dismiss</span>
+        </h4>
+        <p class="text-secondary text-xs">
+          Opens with a plain entrance, then closes itself so the exit keyframe is the star.
+        </p>
+        <div id="modal-anim-exit-buttons" class="flex flex-wrap gap-2"></div>
+      </div>
+
+      <%# The full matrix: any entrance crossed with any exit. %>
+      <div class="card p-5 space-y-3 sm:col-span-2">
+        <h4 class="text-heading font-semibold text-sm">Combine</h4>
+        <p class="text-secondary text-xs">Pick any entrance and exit, then run the round trip.</p>
+        <div class="flex flex-wrap items-end gap-3">
+          <label class="text-xs text-secondary">Enter
+            <select id="modal-anim-enter-select"
+                    class="block mt-1 text-sm bg-inset border border-subtle rounded px-2 py-1 text-heading"></select>
+          </label>
+          <label class="text-xs text-secondary">Leave
+            <select id="modal-anim-exit-select"
+                    class="block mt-1 text-sm bg-inset border border-subtle rounded px-2 py-1 text-heading"></select>
+          </label>
+          <button type="button" class="btn btn-primary btn-sm"
+                  onclick="dsModalDemos.animOpenSelected()">Open</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.animRoundTripSelected()">Open, then auto-close</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  @click="$store.dsModals.close()">Close</button>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <%# ===================================================================== %>
+  <%# 9. STACK MECHANICS (dismissibility, hold-at-least, LIFO stacking) %>
+  <%# ===================================================================== %>
+  <section id="modals-stack-mechanics" class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Stack behaviour</h3>
+      <p class="text-muted text-sm">
+        The engine modal-stack mechanics, poked at directly on
+        <code class="font-mono text-2xs">$store.dsModals</code>: the on-chain TX card states,
+        dismissibility, the minimum-visible-duration floor, and LIFO stacking.
+      </p>
+    </div>
+
+    <div class="grid gap-4 sm:grid-cols-2">
+      <%# The three states of style/modals/_onchain_tx. The two static buttons open
+          the card AT a state; the two timed buttons drive the transition through
+          the store's advance(), which is the in-flow step primitive. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">On-chain TX states</h4>
+        <p class="text-secondary text-xs">
+          Engine <code class="font-mono text-2xs">blocks/_card_header</code> and
+          <code class="font-mono text-2xs">blocks/_onchain_success</code>. The timed pair
+          transitions a live card with
+          <code class="font-mono text-2xs">advance()</code>.
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.processing()">Processing</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.success()">Success</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.error()">Error</button>
+          <button type="button" class="btn btn-primary btn-sm"
+                  onclick="dsModalDemos.processThenSuccess()">Processing to success (3s)</button>
+          <button type="button" class="btn btn-primary btn-sm"
+                  onclick="dsModalDemos.processThenError()">Processing to error (3s)</button>
+        </div>
+      </div>
+
+      <%# dismissible: false is what a pending transaction sets so a stray Escape
+          cannot orphan an in-flight signature. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">Dismissibility</h4>
+        <p class="text-secondary text-xs">
+          A processing card passes <code class="font-mono text-2xs">dismissible: false</code>, so
+          Escape and click-outside are both suppressed until it resolves.
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.processing()">Try Escape (locked)</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.dismissible()">Dismissible processing</button>
+        </div>
+      </div>
+
+      <%# The anti-flicker floor from studio/modals/_load_convention. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">Hold at least</h4>
+        <p class="text-secondary text-xs">
+          <code class="font-mono text-2xs">StudioModals.holdAtLeast(ms)</code> keeps a fast
+          operation from flashing the spinner. Run both and watch the difference.
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <button type="button" class="btn btn-primary btn-sm"
+                  onclick="dsModalDemos.fastWithHold()">Fast op, hold 1500ms</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  onclick="dsModalDemos.fastNoHold()">Fast op, no hold (flashes)</button>
+        </div>
+      </div>
+
+      <%# LIFO: open pushes, close pops back to what was underneath. %>
+      <div class="card p-5 space-y-3">
+        <h4 class="text-heading font-semibold text-sm">Stacking</h4>
+        <p class="text-secondary text-xs">
+          LIFO &mdash; a second <code class="font-mono text-2xs">open()</code> pushes the first
+          card behind it, and <code class="font-mono text-2xs">close()</code> pops back to it.
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <button type="button" class="btn btn-primary btn-sm"
+                  onclick="dsModalDemos.stackTwo()">Open two</button>
+          <button type="button" class="btn btn-outline btn-sm"
+                  @click="$store.dsModals.closeAll()">closeAll()</button>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <%# ---- Demo drivers for the two sections above -------------------------
+      Deliberately NOT an Alpine component: these are multi-step sequences with
+      timers, and an x-data scope would be cloned per specimen card. One global
+      namespace, defined after the markup it drives so the control containers
+      exist when the registry build runs.
+
+      THE STORE IS dsModals. turf-monster's version of this page drove roughly
+      half of these through its legacy solana-modal compatibility proxy, a store
+      this engine does not ship; every demo here goes through the page-scoped
+      store and the onchain-tx specimen directly instead. The exact spelling of
+      that legacy store name is deliberately absent from this file, because
+      style_guide_modal_simulator_test scans the source for it. %>
+  <script>
+    window.dsModalDemos = (function () {
+      var SAMPLE_TX = '5xTrDemoSignature1234567890abcXYZ';
+
+      function store() { return Alpine.store('dsModals'); }
+
+      // Open the onchain-tx specimen. The defaults mirror a real pending
+      // transaction, INCLUDING dismissible: false — the demos that want an
+      // escapable card override it explicitly.
+      function openTx(props) {
+        store().open('onchain-tx', Object.assign({
+          state: 'processing',
+          title: 'Submitting entry',
+          message: 'Awaiting wallet signature',
+          dismissible: false
+        }, props || {}));
+      }
+
+      // In-flow state change on the card that is already open. advance() patches
+      // props WITHOUT replacing the stack entry, so the specimen's x-data scope
+      // survives the transition. Guarded to a still-open onchain-tx card: a timer
+      // that fires after the user closed it must do nothing rather than patch
+      // whatever card happens to be on top now.
+      function advanceTx(patch) {
+        var cur = store().current();
+        if (!cur || cur.id !== 'onchain-tx' || cur._closing) return;
+        store().advance(patch);
+      }
+
+      var SUCCESS = {
+        state: 'success',
+        txSignature: SAMPLE_TX,
+        successTitle: 'Entry confirmed',
+        successSubtitle: 'Your entry is confirmed on-chain.',
+        ctaLabel: 'View wallet',
+        ctaHref: null,
+        dismissible: true
+      };
+      var FAILURE = {
+        state: 'error',
+        title: 'Submission failed',
+        errorMessage: 'Transaction simulation failed: insufficient SOL for rent.',
+        dismissible: true
+      };
+
+      // === Enter / leave simulator =====================================
+      // The demo vehicle is the always-registered email-change-pending card, so
+      // only the motion varies between runs.
+      var ANIM_DEMO_ID    = 'email-change-pending';
+      var ANIM_DEMO_PROPS = { currentEmail: 'you@example.com', newEmail: 'new@example.com' };
+
+      function animOpen(enterAnim, exitAnim) {
+        store().open(ANIM_DEMO_ID, Object.assign({}, ANIM_DEMO_PROPS, {
+          enterAnim: enterAnim, exitAnim: exitAnim
+        }));
+      }
+
+      // Open, let the entrance settle, then close so the chosen EXIT keyframe is
+      // what you watch. The hold is the entrance's own registry duration plus a
+      // beat, read from the live registry rather than assumed.
+      function animRoundTrip(enterAnim, exitAnim) {
+        animOpen(enterAnim, exitAnim);
+        var reg = window.ModalAnimations || { enter: {}, exit: {} };
+        var enterMs = ((reg.enter[enterAnim] || {}).ms) || 320;
+        setTimeout(function () { store().close(); }, enterMs + 700);
+      }
+
+      function el(id) { return document.getElementById(id); }
+
+      // Build the quick buttons and the dropdown options FROM THE LIVE REGISTRY.
+      // This is the property the section exists to demonstrate: a newly
+      // registered animation key grows a control here with no edit to this file.
+      // Idempotent — it clears each container first, so re-running on a Turbo
+      // visit cannot double the controls.
+      function buildAnimControls() {
+        var reg = window.ModalAnimations || { enter: {}, exit: {} };
+
+        var label = function (key) {
+          return key.charAt(0).toUpperCase() + key.slice(1) + (key === 'pop' ? ' (default)' : '');
+        };
+        var addOption = function (sel, key) {
+          if (!sel) return;
+          var o = document.createElement('option');
+          o.value = key;
+          o.textContent = label(key);
+          if (key === 'pop') o.selected = true;
+          sel.appendChild(o);
+        };
+        var addButton = function (container, key, onClick, suffix) {
+          if (!container) return;
+          var b = document.createElement('button');
+          b.type = 'button';
+          b.className = 'btn btn-outline btn-sm';
+          b.textContent = label(key) + (suffix || '');
+          b.onclick = onClick;
+          container.appendChild(b);
+        };
+
+        var enterBtns = el('modal-anim-enter-buttons');
+        var exitBtns  = el('modal-anim-exit-buttons');
+        var enterSel  = el('modal-anim-enter-select');
+        var exitSel   = el('modal-anim-exit-select');
+
+        [enterBtns, exitBtns, enterSel, exitSel].forEach(function (node) {
+          if (node) node.innerHTML = '';
+        });
+
+        Object.keys(reg.enter || {}).forEach(function (key) {
+          addButton(enterBtns, key, function () { animOpen(key, 'pop'); }, ' ↗');
+          addOption(enterSel, key);
+        });
+        Object.keys(reg.exit || {}).forEach(function (key) {
+          addButton(exitBtns, key, function () { animRoundTrip('pop', key); });
+          addOption(exitSel, key);
+        });
+      }
+
+      // WHEN TO BUILD. window.ModalAnimations is published by the shared host's
+      // inline script, which a host layout may render AFTER this one — so the
+      // build waits for the rest of the body either way:
+      //   full load   — DOMContentLoaded, the host script has run by then;
+      //   Turbo visit — DOMContentLoaded already fired and never fires again, so
+      //                 fall through to a macrotask, which runs after the body
+      //                 swap finishes inserting its scripts.
+      // turbo:load covers the remaining visits; the build is idempotent, so the
+      // overlap between these paths is redundant work and nothing worse.
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', buildAnimControls);
+      } else {
+        setTimeout(buildAnimControls, 0);
+      }
+      if (!window.__dsAnimControlsBound) {
+        window.__dsAnimControlsBound = true;
+        document.addEventListener('turbo:load', buildAnimControls);
+      }
+
+      return {
+        // Stack behaviour
+        processing: function () { openTx({}); },
+        success:    function () { openTx(SUCCESS); },
+        error:      function () { openTx(FAILURE); },
+        processThenSuccess: function () {
+          openTx({ message: 'Awaiting RPC confirmation' });
+          setTimeout(function () { advanceTx(SUCCESS); }, 3000);
+        },
+        processThenError: function () {
+          openTx({ message: 'Awaiting RPC confirmation' });
+          setTimeout(function () { advanceTx(FAILURE); }, 3000);
+        },
+        dismissible: function () {
+          openTx({
+            dismissible: true,
+            title: 'Dismissible processing',
+            message: 'Escape and click-outside both close this one.'
+          });
+        },
+        fastWithHold: function () {
+          openTx({ title: 'Fast operation', message: 'Holding the spinner for at least 1500ms' });
+          window.StudioModals.holdAtLeast(1500).then(function () { advanceTx(SUCCESS); });
+        },
+        fastNoHold: function () {
+          openTx({ title: 'Fast operation', message: 'No hold, so this flashes past' });
+          setTimeout(function () { advanceTx(SUCCESS); }, 50);
+        },
+        stackTwo: function () {
+          openTx({
+            dismissible: true,
+            title: 'Bottom of the stack',
+            message: 'A second card is about to push in front of this one.'
+          });
+          setTimeout(function () {
+            store().open(ANIM_DEMO_ID, ANIM_DEMO_PROPS);
+          }, 700);
+        },
+
+        // Enter / leave simulator
+        animOpenSelected: function () {
+          animOpen(el('modal-anim-enter-select').value, el('modal-anim-exit-select').value);
+        },
+        animRoundTripSelected: function () {
+          animRoundTrip(el('modal-anim-enter-select').value, el('modal-anim-exit-select').value);
+        }
+      };
+    })();
+  </script>
+
 </section>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.69.5"
+  VERSION = "0.70.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.69.5
+  version: 0.70.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails