studio-engine 0.69.5 → 0.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ac04785253cb277ef70cd1d6398b81718e223adc7e300c1a19329183a88be5
-  data.tar.gz: 01c13c3974eb5da7887fc82e77f3526eb50af53a3e590b993a7602914e8daa81
+  metadata.gz: b84ed97df94f71d6135899621e982649f6c80b41d5821b12842ab5c0e6d47ce7
+  data.tar.gz: 2b1af46db99092b30d9049d2afbbefa9cc810878bcbc376d9e04f780cc6e7a05
 SHA512:
-  metadata.gz: db96cbe447a67732cc7d2babc54f605071ccd9e3d77d20da4fb7486c5e89f5354e21dc34066757ec7bde7f66fb7fb08e257a15c364753d3a98f34ea8065df25b
-  data.tar.gz: f8a47251bf78b0c3bab42dfc743565c2dba66502f6f204516718144cd9506a5206bf6342b7ce496fa12f6f67a34727dc8fc7cbc5e03529ce5d3ab1e3727b4761
+  metadata.gz: 294aa380598143d9f79592e2b0e62bab038dbb886b374ce765ff9fdf0da349e460049ae284e397f234647f3b9dfdea24263cd8ed31bf74bbe00d1e14e1bbf49f
+  data.tar.gz: d119392c02adb20753485b0b6efcaf01e3c3f3ea0aa26f9b5e36fe1f3de3fb4df77ede836f0a79ec937bd556ad14a9317078fa25f028d890e27f531e74ad8f37

data/CHANGELOG.md

@@ -6,6 +6,76 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **The living style guide grows a HOST SECTION seam.** `/admin/style` rendered
+  four hard-coded engine sections (Theme, Modals, Tricks, Tasks) with no way for
+  a consuming app to contribute one of its own. An app now defines
+  **`app/views/style/host/_modals.html.erb`** and the guide grows a fifth
+  section for that app's own modals, between Modals and Tricks, plus its pill in
+  the sticky section nav. Found by the same three-term
+  `lookup_context.exists?("modals", ["style/host"], true)` the modal host uses
+  for `modals/_host_extras` — one convention in this codebase, not two — so
+  defining the file IS the registration: no initializer, no locals, no list to
+  append to.
+
+  **The gem keeps dictating the structure.** `style/_host.html.erb` renders the
+  section element, the `#host-modals` anchor, the heading (`Studio.app_name`),
+  the intro line and the Alpine scope; the app supplies specimens only. An app
+  that ships no such partial gets **nothing** — no pill, no heading, no
+  container — and that is asserted as a whole-document comparison rather than a
+  handful of refutes: the page an app WITH a section gets, minus that section
+  and its pill, must equal the page a base app gets. Five of the six apps
+  mounting this engine will ship no host section, and their page is unchanged.
+
+  **A host specimen drives `$store.modals`, not `dsModals`, and the distinction
+  is the whole point.** The guide's own Modals section needs a page-scoped store
+  because its specimens are the ENGINE's ids, which an app's layout host has no
+  registration for — pushing one there paints an empty card behind the specimen.
+  An app's own ids ARE registered in its layout host, so a host section opens
+  the **real** production card with no mirror, no second registration list and
+  no iframe. The doc comment on `style/_host.html.erb` is the consumer contract
+  and says so outright, because a reader who assumes `dsModals` builds that
+  mirror instead — a second copy of every card, free to drift from the one the
+  app ships, which is the opposite of what a living style guide is for.
+
+  **The seam ships no host section itself.** The first consumer is
+  turf-monster's own `style/host/_modals`, which lands as its own task.
+- **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 +91,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 +160,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/README.md

@@ -449,6 +449,48 @@ than assuming drop-in equivalence:
   the replacement lands after the 220ms slide-out (previously an immediate
   top-of-stack assignment).
 
+### Style guide — your app's own section
+
+`/admin/style` is the engine's living style guide, and every section on it is
+the engine's: Theme, Modals, Tricks, Tasks. An app grows a **fifth section, its
+own**, by defining one partial:
+
+```erb
+<%# app/views/style/host/_modals.html.erb %>
+<div class="card p-4 space-y-3">
+  <p class="label-upper">Wallet setup</p>
+  <button type="button" class="btn btn-primary btn-sm"
+          @click="$store.modals.open('wallet-setup', { returnUrl: window.location.href })">
+    Open
+  </button>
+</div>
+```
+
+That is the whole registration — the same optional-partial convention as
+`modals/_host_extras`, resolved by the same three-term `lookup_context.exists?`.
+An app that ships no such file gets no section, no heading, and no nav pill; its
+page is byte-for-byte what it was.
+
+**The gem keeps dictating the structure.** It renders the section element, the
+`#host-modals` anchor, the heading (your `Studio.app_name`), the intro line, and
+the sticky nav pill, and it places the section between Modals and Tricks. Your
+partial supplies specimens only — no `<section>`, no `<h2>`, nothing to register
+in a nav.
+
+**Drive `$store.modals`, not `dsModals`.** The guide's own Modals section stands
+up a page-scoped store because its specimens are the *engine's* ids, and pushing
+an id your layout host has never registered opens that host onto an empty card.
+Your own ids are already registered there, so
+`$store.modals.open(id, props)` renders the **real** card, in production chrome,
+with production behavior. There is nothing to mirror and no second registration
+list to keep in sync — building one is the mistake this note exists to prevent.
+This assumes your layout mounts the shared host. Not every consuming app does
+(see "Page-scoped hosts" above); where none is mounted `$store.modals` is
+undefined, so mount `studio/modals/host` before writing a trigger.
+
+Full contract, including what the partial may assume: the doc comment at the top
+of `app/views/style/_host.html.erb`.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

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/_host.html.erb

@@ -0,0 +1,111 @@
+<%#  The HOST section of the living style guide (admin/style).
+
+     THE ONE SEAM a consuming app has for growing its own specimens onto this
+     page. Every other section on this page is the gem's. This one is the app's,
+     and the gem still dictates its structure: the section element, the anchor,
+     the heading, the intro line, and the nav pill above are all rendered HERE,
+     from the engine. The app supplies content only.
+
+     "Host" means the CONSUMING APP, the same sense it carries in the modal
+     host's own seam (modals/_host_extras). It does NOT mean the modal-host
+     shell, which is studio/modals/_host - a different file and a different
+     meaning of the word.
+
+
+     THE CONTRACT - what a consuming app writes
+     ------------------------------------------
+     Define ONE partial in the app:
+
+         app/views/style/host/_modals.html.erb
+
+     That is the whole registration. There is no initializer, no locals, no
+     list to append to, and nothing to render from the app's own layout. The
+     guide finds the partial by CONVENTION, exactly the way the modal host
+     finds modals/_host_extras:
+
+         lookup_context.exists?("modals", ["style/host"], true)
+
+     - the same three-term form: name, prefixes, partial. That call lives in
+     style/index.html.erb, which owns it because the sticky section nav needs
+     the same answer the render does. An app that ships no such partial gets no
+     pill, no heading, no container, and no bytes: the guide is unchanged.
+
+     WHY THIS PATH. A directory (style/host/) rather than a flat name in the
+     gem's own style/ prefix, because the gem already ships style/_modals,
+     style/_theme, style/_tricks and style/_tasks - an app file dropped beside
+     them shadows a section by name, and the failure is silent. Nothing of the
+     gem's lives under style/host/, so an app cannot collide with the engine
+     there. Naming the partial for the SECTION it contributes (modals) rather
+     than for the seam leaves room for a later style/host/_tricks without
+     renaming what is already shipped.
+
+
+     WHAT THE PARTIAL MAY ASSUME
+     ---------------------------
+     - It renders INSIDE this section element, already anchored, spaced and
+       headed. So it supplies cards and prose only: no section tag of its own,
+       no h2, no scroll-margin, no nav entry.
+     - The engine component layer (engine.css) and motion layer
+       (engine-motion.css) are loaded, so card, btn, badge, label-upper, the
+       role tokens and the motion/effect primitives all style for real.
+     - Alpine is running and this section carries an x-data scope, so a
+       specimen can use x-on / at-click bindings directly. A plain onclick
+       calling Alpine.store works too.
+     - NOT that a shared modal host exists. Only an app whose layout renders
+       studio/modals/host has Alpine.store("modals") at all: mcritchie-studio
+       and turf-monster mount it; acquisition-studio, mcritchie-industries and
+       moms-app render none (the same split README's "Page-scoped hosts" and
+       studio/emails/index.html.erb already name). On an app with no shared
+       host $store.modals is UNDEFINED and a trigger throws on click, so mount
+       studio/modals/host in the layout first - or give the page its own host
+       with studio/modals/scoped_host and drive that instead.
+
+
+     WHICH STORE IT DRIVES - read this before writing a trigger
+     ----------------------------------------------------------
+     Drive the app's REAL store:
+
+         $store.modals.open(id, props)
+
+     NOT dsModals. dsModals is the page-scoped host that the gem's own Modals
+     section above stands up, and copying it here is the one wrong turn this
+     seam invites.
+
+     The gem's section needs dsModals for a reason that does NOT apply to an
+     app's own modals. Its specimens are the ENGINE's ids, and an app's layout
+     host registers only that app's ids under an unconditional template x-if on
+     the current modal. Pushing a NOVEL id onto the app's store would open that
+     host onto a card it has no registration for, painting an EMPTY panel behind
+     the specimen. So the gem's section owns a private store and registers all
+     of its specimen content itself.
+
+     An app's own modal ids are already registered in that app's layout host.
+     Push one onto $store.modals and the real host renders the real card - the
+     production card, in production chrome, with production behaviour. There is
+     nothing to mirror, no second registration list to keep in sync, and no
+     iframe. Turf Monster's /admin/modals gallery has driven the real store from
+     a plain button this way since it was built; this seam is that same move,
+     given a home on the guide.
+
+     A reader who assumes dsModals will build a mirror instead: a second copy of
+     every card, free to drift from the one the app actually ships, which is the
+     opposite of what a living style guide is for. %>
+<section id="host-modals" class="space-y-8" x-data="{}"
+         style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+  <div class="space-y-1">
+    <h2 class="text-2xl font-bold text-heading"><%= Studio.app_name %></h2>
+    <p class="text-muted text-sm max-w-2xl">
+      This app&rsquo;s own modals, contributed by
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">app/views/style/host/_modals.html.erb</code>.
+      Every section above belongs to the engine and is inherited; everything
+      here belongs to <%= Studio.app_name %> and ships with it. These specimens
+      drive the app&rsquo;s <strong>real</strong>
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">$store.modals</code>
+      host, so the card that opens here is the card that opens in production.
+    </p>
+  </div>
+
+  <%# The app's content. Reached only when it resolves - style/index.html.erb
+      owns that guard, because the section nav needs the same answer. %>
+  <%= render "style/host/modals" %>
+</section>

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/app/views/style/index.html.erb

@@ -3,22 +3,48 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Four sections, reached by the sticky section nav below and rendered as
-     sibling partials: Theme is the landing section (the color foundation - it
+     Four ENGINE sections, reached by the sticky section nav below and rendered
+     as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the folded-in /admin/theme editor, and the
      live preview), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
      copy-paste-for-an-agent snippets), and Tasks (the shared board primitive).
 
+     A FIFTH section is the host app's own, and appears only on an app that asks
+     for it: define app/views/style/host/_modals.html.erb in the consuming app
+     and the guide grows a section (and a nav pill) for that app's own modals,
+     between Modals and Tricks. The gem still renders the section chrome; the app
+     supplies the specimens. Full contract, including which modal store a host
+     specimen drives and why it is not the one the Modals section uses:
+     app/views/style/_host.html.erb.
+
      Specimens use ONLY the engine's own classes (engine.css component layer plus
      engine-motion.css motion/effect/leveling layer), so a consumer that bundles
      engine.css and imports engine-motion.css styles them for real. The primitive
      CSS is NOT inlined here - the consumer's Tailwind build provides it. Page
      chrome uses the engine's own .card / .label-upper / theme tokens. %>
 <%
+  # THE HOST SECTION SEAM. A consuming app grows its OWN modal specimens onto
+  # this page by defining app/views/style/host/_modals.html.erb. Found by the
+  # same three-term lookup_context.exists?(name, prefixes, partial) the modal
+  # host uses for modals/_host_extras (studio/modals/_host.html.erb) - one
+  # convention in this codebase, not two.
+  #
+  # Resolved ONCE, here, because two places need the same answer: the sticky
+  # section nav below and the render further down. An app that ships no such
+  # partial gets no pill, no heading and no container - the page is what it was.
+  # The section chrome and the consumer contract live in style/_host.html.erb.
+  host_modals = lookup_context.exists?("modals", ["style/host"], true)
+
   sections = [
     ["theme",  "Theme"],
-    ["modals", "Modals"],
+    ["modals", "Modals"]
+  ]
+  # Adjacent to Modals, not appended: this page groups by SUBJECT, and a host's
+  # own modals are the same subject as the engine's. Labelled with the app's own
+  # name, so the pill says whose section it is.
+  sections << ["host-modals", Studio.app_name] if host_modals
+  sections += [
     ["tricks", "Tricks"],
     ["tasks",  "Tasks"]
   ]
@@ -54,6 +80,9 @@
   <div class="space-y-16 pt-10">
     <%= render "style/theme" %>
     <%= render "style/modals" %>
+    <% if host_modals %>
+      <%= render "style/host" %>
+    <% end %>
     <%= render "style/tricks" %>
     <%= render "style/tasks" %>
   </div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.69.5"
+  VERSION = "0.71.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.71.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
@@ -509,6 +509,7 @@ files:
 - app/views/studio/profiles/_save_controls.html.erb
 - app/views/studio/profiles/edit.html.erb
 - app/views/studio/profiles/show.html.erb
+- app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb