studio-engine 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9febc9d4cd408725e94cd7cbd481b698f8653ec08f79f94dd3b77e7a79140a1b
-  data.tar.gz: 39512b32582a5ca68c10271a320aad6e27f67a084ce39a0cf0405b2afd9a7839
+  metadata.gz: 7518a662f1e6ef4a2abcad98a5ebfbdff27726ec1eaf63a8d3a3ec11d83c778d
+  data.tar.gz: 76a89614b473c19998c98176a2f4b55d89cede2d79c744278f3e4e2eaaa4c21c
 SHA512:
-  metadata.gz: 0a4cee970e8b66de10c44d6f953419d186b69406fcab64d9ed1a418a2038482223aa75cb72e356c528aabf269368b49f1f24ec7bad7d0b0f33a108982b7b02db
-  data.tar.gz: 755b20e0bdd55e28163bfb53bd5029ac150efec66796c91633336a5e3c0187a8a9aefc5dd33b1f8dab89a8edb8d502b734ed3999caf4b4197562eb77e8fe614e
+  metadata.gz: b241dba69f4bae51b29afb449a40e041243a8a79620eef8bcf202e6a038a290262ba67600c09fe2f6e0e49636af3c2ea1c35cab8b6f3f131dd35f2d2aa08bc1d
+  data.tar.gz: 8d328e360a347df68e72c6f3d53a820462963c8c8a55f5e88c2226d9da1a152a0b3a847230436ae2f22416d4160452a723dfdcfd4e6029d6dcf1a63368c1a5b1

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.13.0 — 2026-07-19
+
+### Added
+
+- **Engine-shipped component CSS** — `.card`/`.btn*`/`.badge`/`.input-field`/`.empty-state` + `text-2xs`/`text-3xs` preset tokens; consumers adopt with `@import "../builds/tailwind/studio_engine";` (docs/NEW_APP_SETUP.md section 13).
+- **De-forked UI primitives** — the modal host upstreams Turf's animated host (inline keyframes, `window.ModalAnimations` registry, `enterAnim`/`exitAnim` props, directional `swap()`/`advance()`; API superset of the old host — behavioral deltas listed in the README), and `components/user_nav` gains partial slots (`balance_slot`/`extra_icons_slot`/`div2_slot`) with the legacy `*_html` string locals still honored.
+
+### Fixed
+
+- **Theme invariants scan class attributes, not prose** — the used-classes
+  invariant extracts `class="..."` / `class: "..."` contents before tokenizing,
+  so a comment mentioning a `card-*`/`btn-*` token no longer trips it; the
+  theme-var invariant now asserts per mode (dark AND light) instead of the
+  union, so a var emitted in only one mode cannot pass.
+- **Modal host review fixes** — `cardClasses()` no longer clobbers registry
+  `slide` animations (the directional swap flags are guarded, so
+  `enterAnim`/`exitAnim: "slide"` resolve to real classes instead of a frozen
+  220ms snap); the README's behavioral-delta wording is corrected; and a
+  node-executed store suite hardens the rendered modal store (cardClasses
+  resolution, registry merge, animated close timing, swap races, late registry
+  replacement).
+- **Consumer checkout fetches full history** — the consumer-CI checkout uses
+  `fetch-depth: 0` so the hub's e2e quarantine ratchet can resolve
+  `origin/release` (the default depth-1 single-ref checkout left the baseline
+  ref unresolvable, which is red by design).
+
 ## 0.12.1 — 2026-07-11
 
 ### Fixed

data/Gemfile

@@ -9,6 +9,12 @@ gemspec
 # XSLT / xmlC14NExecute). This gem still does NOT declare nokogiri as a runtime
 # dependency — it arrives via Rails in the consuming app. Tracked in
 # SECURITY-AUDIT-2026-05-17.md.
+#
+# It is also not declared as a test dependency, but test/views/user_nav_test.rb
+# now requires it directly to walk rendered markup. That resolves today because
+# actionview pulls it in via rails-dom-testing; if that ever stops being true
+# the suite fails loudly with a LoadError rather than silently skipping, so
+# declare it here at that point rather than pre-emptively pinning it.
 
 group :development, :test do
   # SQLite drives the test/dummy Rails app's in-memory database (see

data/README.md

@@ -125,6 +125,97 @@ slide between two emoji on hover and keyboard focus. The CSS ships through
 <% end %>
 ```
 
+### Modal host
+
+`studio/modals/_host.html.erb` is the single shared shell for every modal. It
+owns the backdrop, scroll lock, escape + click-outside dismissal, ARIA dialog
+role, mount/unmount animations, and bfcache/Turbo snapshot cleanup. Animation
+keyframes ship inline in the partial — consumers need no extra CSS.
+
+Render it once near the end of the layout `<body>`, registering each modal in
+the block:
+
+```erb
+<%= render "studio/modals/host" do %>
+  <template x-if="$store.modals.current().id === 'crop-photo'">
+    <%= render "studio/modals/crop_photo" %>
+  </template>
+<% end %>
+```
+
+Store API (`Alpine.store('modals')`):
+
+| Call | Behavior |
+|------|----------|
+| `open(id, props, opts)` | Push a modal onto the stack. `opts.replace: true` swaps the top entry with a directional slide. |
+| `swap(id, props, opts)` | Sugar for `open(id, props, { replace: true })`. `opts.direction: 'back'` mirrors the slide. |
+| `advance(propsPatch, opts)` | Patch the current entry's props with the same directional slide, without replacing the stack entry — for steps inside one modal whose outer `x-data` scope must survive. |
+| `close()` | Animated close of the current modal (no-op if already closing). |
+| `closeAll()` | Instant, unanimated clear (used by navigation cleanup). |
+| `closeAllDismissible()` | Clears all modals except those opened with `dismissible: false`. |
+| `isOpen(id)` / `current()` | Introspection. |
+
+Recognized props: `dismissible: false` disables escape/click-outside dismissal
+(e.g. an in-flight transaction); `enterAnim` / `exitAnim` pick a named
+animation from the registry (`'pop'` default, `'shake'`, `'slide'`).
+
+`window.ModalAnimations` is the animation registry — each key maps a CSS class
+to its duration. To add a custom animation, define `window.ModalAnimations`
+**before** the host renders with your extra keys (they merge over the engine
+defaults) and ship the matching CSS class in the app stylesheet:
+
+```html
+<script>
+  window.ModalAnimations = { enter: { wobble: { cls: 'my-modal-wobble', ms: 400 } } };
+</script>
+```
+
+Prefer an inline script placed before the host render, as above. A module that
+loads after the host (e.g. via importmap) and assigns `window.ModalAnimations`
+**replaces** the merged registry rather than extending it — the host guards
+against this (unknown keys and gutted registries fall back to the built-in
+`'pop'`), but your other custom keys are lost unless the late script merges
+into the existing object instead of assigning over it.
+
+`window.StudioModals.holdAtLeast(ms)` returns a thenable that resolves no
+sooner than `ms` after creation — stamp it when a processing view becomes
+visible so fast operations don't flash the spinner.
+
+**Behavioral deltas vs the previous engine host (0.12 and earlier).** The
+store's API surface is a superset, but three behaviors changed, and a consumer
+deleting its shadow copy inherits them — regression-test these paths rather
+than assuming drop-in equivalence:
+
+- `close()` is now **asynchronous**: the entry animates out and is spliced
+  after its exit animation's registered duration (previously an immediate
+  `pop()`).
+- `close()` **no-ops while the current entry is already closing** — a double
+  `close()` inside the animation window now pops ONE stacked entry, not two —
+  and `close()` on an empty stack no longer runs `_sync()`.
+- `open(id, props, { replace: true })` (and `swap()`) is now **asynchronous**:
+  the replacement lands after the 220ms slide-out (previously an immediate
+  top-of-stack assignment).
+
+### User nav slots
+
+`components/_user_nav.html.erb` renders the right-side navbar user section.
+Apps customize it through partial slots — each an optional local naming a
+partial (String path, or `{ partial:, locals: }`):
+
+- `balance_slot` — balance display at the start of the top row
+- `extra_icons_slot` — app icon buttons before the admin gear + theme toggle
+- `div2_slot` — replaces the default second row (wallet address + level bar)
+
+```erb
+<%= render "components/user_nav",
+      balance_slot: "components/wallet_balance",
+      div2_slot: { partial: "components/seeds_bar", locals: { compact: true } } %>
+```
+
+The legacy string locals (`balance_html`, `extra_icons_html`, `div2_html` —
+pre-rendered HTML injected via `raw`) are deprecated but still honored when the
+matching slot is absent, so existing call sites render unchanged.
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.

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

@@ -0,0 +1,146 @@
+/*
+  studio-engine component classes — the shared UI component layer.
+
+  The engine's partials emit .card / .badge / .input-field / .empty-state /
+  .btn* and this file is where those classes are DEFINED. Consumers adopt with
+  ONE line in app/assets/tailwind/application.css (after `@import "tailwindcss";`):
+
+      @import "../builds/tailwind/studio_engine";
+
+  tailwindcss-rails auto-generates that entry point on every build/watch
+  (or manually: `bin/rails tailwindcss:engines`) because this file lives at the
+  Rails-engines contract path: app/assets/tailwind/<engine_name>/engine.css.
+
+  Requirements:
+  - Tailwind v4 (this file uses @utility, so classes sort/override correctly
+    in the utilities layer and take variants like `md:card`).
+  - The consumer's tailwind config spreads the engine preset
+    (tailwind/studio.tailwind.config.js) — it defines the surface / heading /
+    subtle / primary token utilities @apply'd below.
+
+  Colors resolve through the 7-role theme CSS custom properties (--color-cta,
+  --color-surface, ...) emitted by studio_theme_css_tag, so themed apps restyle
+  these components automatically in dark AND light mode.
+
+  Canonical source: these definitions were lifted verbatim from
+  mcritchie-studio app/assets/tailwind/application.css (the hub versions win
+  where per-app copies drifted). Keep the two in sync until the consumers drop
+  their local copies for this import.
+*/
+
+/* -- Surfaces -------------------------------------------------------------- */
+
+@utility card {
+  @apply bg-surface rounded-xl border border-subtle;
+}
+
+@utility card-hover {
+  @apply bg-surface rounded-xl border border-subtle hover:border-primary-700/50 hover:shadow-lg hover:shadow-primary-900/10 transition;
+}
+
+@utility empty-state {
+  @apply bg-surface rounded-xl border border-subtle p-8 text-center;
+}
+
+@utility json-debug {
+  @apply bg-inset rounded-xl border border-subtle p-4 overflow-x-auto;
+}
+
+/* -- Text + form ----------------------------------------------------------- */
+
+@utility badge {
+  @apply inline-flex items-center px-2 py-0.5 rounded-sm text-xs font-medium border;
+}
+
+@utility label-upper {
+  @apply text-xs text-muted uppercase tracking-wider;
+}
+
+@utility input-field {
+  @apply w-full bg-surface-alt border border-strong rounded-lg px-4 py-3 text-heading focus:border-primary focus:outline-hidden;
+}
+
+/* -- Button system (standardized across all Studio apps) ------------------- */
+
+@utility btn {
+  @apply inline-flex items-center justify-center font-bold rounded-lg transition px-6 py-2 text-sm disabled:opacity-50 disabled:cursor-not-allowed;
+  &:focus-visible {
+    outline: 2px solid color-mix(in srgb, var(--color-cta) 70%, transparent);
+    outline-offset: 2px;
+  }
+}
+
+@utility btn-primary {
+  @apply text-white;
+  background-color: var(--color-cta);
+  &:hover {
+    background-color: var(--color-cta-hover);
+  }
+}
+
+/* NOTE: btn-secondary and btn-success compile to IDENTICAL declarations (both
+   sit on var(--color-success)) — an intentional hub-canonical alias, kept as
+   two names so existing markup in every consumer keeps working. */
+@utility btn-secondary {
+  @apply text-white;
+  background-color: var(--color-success);
+  &:hover {
+    filter: brightness(0.9);
+  }
+}
+
+@utility btn-outline {
+  @apply bg-transparent border text-heading;
+  border-color: var(--color-cta);
+  &:hover {
+    @apply text-white;
+    background-color: var(--color-cta);
+  }
+}
+
+@utility btn-danger {
+  @apply text-white;
+  background-color: var(--color-danger);
+  &:hover {
+    filter: brightness(0.9);
+  }
+}
+
+@utility btn-warning {
+  @apply text-white;
+  background-color: var(--color-warning);
+  &:hover {
+    filter: brightness(0.9);
+  }
+}
+
+@utility btn-success {
+  @apply text-white;
+  background-color: var(--color-success);
+  &:hover {
+    filter: brightness(0.9);
+  }
+}
+
+@utility btn-google {
+  @apply bg-white border border-strong shadow-xs;
+  color: #374151;
+  &:hover {
+    @apply bg-gray-50;
+  }
+}
+
+@utility btn-neutral {
+  @apply bg-surface-alt text-heading border border-strong;
+  &:hover {
+    @apply bg-surface;
+  }
+}
+
+@utility btn-sm {
+  @apply px-3 py-1.5 text-xs;
+}
+
+@utility btn-lg {
+  @apply px-8 py-3 text-base rounded-xl shadow-sm;
+}

data/app/views/components/_user_nav.html.erb

@@ -1,26 +1,61 @@
 <%# Shared right-side navbar user section.
-    Locals (all optional):
-      balance_html     — raw HTML for balance display (e.g. Turf Monster wallet balance)
-      extra_icons_html — raw HTML for app-specific icon buttons (e.g. refresh button)
-      show_logout_link — boolean, show explicit "Log out" link (Studio uses this)
-      div2_html        — raw HTML to replace default Div 2 (e.g. Turf Monster seeds bar)
+
+    Slot locals (all optional). Each slot names a partial to render in
+    that position — a String partial path, or a Hash of
+    { partial: "path", locals: { ... } } when the partial needs locals:
+      balance_slot     — balance display, rendered at the start of the
+                         top row (e.g. a wallet balance link)
+      extra_icons_slot — app-specific icon buttons, rendered before the
+                         admin gear + theme toggle
+      div2_slot        — replaces the default second row (the wallet
+                         address + level progress bar) entirely
+                         (e.g. a seeds bar)
+
+    Other locals:
+      show_logout_link — boolean, show explicit "Log out" link in the
+                         second row (Studio uses this)
+
+    Legacy string locals (deprecated): balance_html, extra_icons_html,
+    div2_html — pre-rendered HTML injected via raw. Still honored when
+    the matching slot local is absent, so existing call sites render
+    unchanged. Prefer the slot locals for new work; they go through the
+    normal partial pipeline instead of trusting a raw string.
 %>
+<% balance_slot     ||= nil %>
+<% extra_icons_slot ||= nil %>
+<% div2_slot        ||= nil %>
 <% balance_html     ||= nil %>
 <% extra_icons_html ||= nil %>
 <% show_logout_link ||= false %>
 <% div2_html        ||= nil %>
+<%# Slot resolution: the slot local wins when both a slot and its legacy
+    string are passed. Returns nil when neither is present. %>
+<% studio_nav_slot = lambda do |slot, legacy_html|
+     if slot.is_a?(Hash)
+       render slot[:partial], **slot.fetch(:locals, {})
+     elsif slot.present?
+       render slot.to_s
+     elsif legacy_html.present?
+       raw legacy_html
+     end
+   end %>
 
 <div class="flex gap-2">
   <% if logged_in? %>
     <%# Left column: Div 1 + Div 2 stacked %>
-    <div class="flex-1">
-      <%# Div 1 (Bigger): balance + icons + username %>
+    <%# min-w-0 belongs HERE, on the flex item of the outer row. A flex item
+        defaults to min-width auto, so without it this column refuses to
+        shrink below its content and the username overflows instead of
+        truncating. Div 1 below is a block child of this column, not a flex
+        item of the outer row, so min-w-0 there has no effect on shrinking.
+        The username link truncates on its own: overflow-hidden gives it an
+        automatic minimum size of zero inside Div 1. %>
+    <div class="flex-1 min-w-0">
+      <%# Div 1 (Bigger): balance + icons + username. %>
       <div class="flex items-center gap-2 leading-none" :style="'padding: 0 6px;' + ($store.devMode ? 'background: cornflowerblue;' : '')">
-        <% if balance_html.present? %>
-          <%= raw balance_html %>
-        <% end %>
+        <%= studio_nav_slot.call(balance_slot, balance_html) %>
         <div class="flex items-center gap-2 ml-auto self-end">
-          <%= raw extra_icons_html %>
+          <%= studio_nav_slot.call(extra_icons_slot, extra_icons_html) %>
           <%= render "components/admin_dropdown" %>
           <%= render "components/theme_toggle_morph" %>
         </div>
@@ -29,96 +64,102 @@
           <%= current_user.display_name %>
         <% end %>
       </div>
-      <%# Div 2 (Smaller): wallet address (left) + level (right) with progress bar %>
-      <% server_level = current_user.respond_to?(:level) && current_user.level.present? ? current_user.level : nil %>
-      <div x-data="{
-             barWidth: 0,
-             displayLevel: <%= server_level || 1 %>,
-             leveledUp: false,
-             init() {
-               var self = this;
-               var data = this.getSeedsData();
-               if (data) {
-                 self.displayLevel = data.level;
-                 setTimeout(function() { self.barWidth = data.progress; }, 150);
-               }
-             },
-             getSeedsData() {
-               try {
-                 var raw = localStorage.getItem('seedsNavbar');
-                 if (!raw) return null;
-                 return JSON.parse(raw);
-               } catch(e) { return null; }
-             },
-             replayLevel() {
-               var self = this;
-               var data = this.getSeedsData();
-               var finalPct = data ? data.progress : self.barWidth;
-               self.displayLevel = Math.max(1, self.displayLevel - 1);
-               self.barWidth = 60;
-               setTimeout(function() { self.barWidth = 100; }, 300);
-               setTimeout(function() { self.displayLevel += 1; self.leveledUp = true; }, 1500);
-               setTimeout(function() { self.leveledUp = false; self.barWidth = 0; }, 2800);
-               setTimeout(function() { self.barWidth = finalPct; }, 3000);
-             },
-             handleSeedsUpdate(d) {
-               var self = this;
-               if (d.levelUp) {
-                 self.barWidth = d.oldPct;
+      <% div2_content = studio_nav_slot.call(div2_slot, div2_html) %>
+      <% if div2_content.present? %>
+        <%# Div 2 replaced by the consumer's slot (div2_slot or legacy div2_html). %>
+        <%= div2_content %>
+      <% else %>
+        <%# Div 2 (Smaller): wallet address (left) + level (right) with progress bar %>
+        <% server_level = current_user.respond_to?(:level) && current_user.level.present? ? current_user.level : nil %>
+        <div x-data="{
+               barWidth: 0,
+               displayLevel: <%= server_level || 1 %>,
+               leveledUp: false,
+               init() {
+                 var self = this;
+                 var data = this.getSeedsData();
+                 if (data) {
+                   self.displayLevel = data.level;
+                   setTimeout(function() { self.barWidth = data.progress; }, 150);
+                 }
+               },
+               getSeedsData() {
+                 try {
+                   var raw = localStorage.getItem('seedsNavbar');
+                   if (!raw) return null;
+                   return JSON.parse(raw);
+                 } catch(e) { return null; }
+               },
+               replayLevel() {
+                 var self = this;
+                 var data = this.getSeedsData();
+                 var finalPct = data ? data.progress : self.barWidth;
+                 self.displayLevel = Math.max(1, self.displayLevel - 1);
+                 self.barWidth = 60;
                  setTimeout(function() { self.barWidth = 100; }, 300);
-                 setTimeout(function() { self.displayLevel = d.newLevel; self.leveledUp = true; }, 1500);
+                 setTimeout(function() { self.displayLevel += 1; self.leveledUp = true; }, 1500);
                  setTimeout(function() { self.leveledUp = false; self.barWidth = 0; }, 2800);
-                 setTimeout(function() { self.barWidth = d.progress; }, 3000);
-               } else {
-                 self.displayLevel = d.level;
-                 self.barWidth = d.progress;
+                 setTimeout(function() { self.barWidth = finalPct; }, 3000);
+               },
+               handleSeedsUpdate(d) {
+                 var self = this;
+                 if (d.levelUp) {
+                   self.barWidth = d.oldPct;
+                   setTimeout(function() { self.barWidth = 100; }, 300);
+                   setTimeout(function() { self.displayLevel = d.newLevel; self.leveledUp = true; }, 1500);
+                   setTimeout(function() { self.leveledUp = false; self.barWidth = 0; }, 2800);
+                   setTimeout(function() { self.barWidth = d.progress; }, 3000);
+                 } else {
+                   self.displayLevel = d.level;
+                   self.barWidth = d.progress;
+                 }
                }
-             }
-           }"
-           @navbar-replay-level.window="replayLevel()"
-           @navbar-seeds-update.window="handleSeedsUpdate($event.detail)"
-           class="relative mt-0.5" style="height: 14px;">
-        <%# Fill bar %>
-        <div class="absolute inset-y-0 left-0 rounded z-0" style="background: var(--color-cta); transition: width 1.2s cubic-bezier(0.16, 1, 0.3, 1);" :style="{ width: barWidth + '%' }"></div>
-        <%# Text layer 1: muted (visible outside bar) %>
-        <div class="absolute inset-0 flex items-center justify-between px-1.5 font-mono text-muted z-[1] nav-bar-text">
-          <span>
-            <% if current_user.respond_to?(:truncated_solana) && current_user.try(:solana_connected?) %>
-              <%= current_user.truncated_solana %>
+             }"
+             @navbar-replay-level.window="replayLevel()"
+             @navbar-seeds-update.window="handleSeedsUpdate($event.detail)"
+             class="relative mt-0.5" style="height: 14px;">
+          <%# Fill bar %>
+          <div class="absolute inset-y-0 left-0 rounded z-0" style="background: var(--color-cta); transition: width 1.2s cubic-bezier(0.16, 1, 0.3, 1);" :style="{ width: barWidth + '%' }"></div>
+          <%# Text layer 1: muted (visible outside bar) %>
+          <div class="absolute inset-0 flex items-center justify-between px-1.5 font-mono text-muted z-[1] nav-bar-text">
+            <span>
+              <% if current_user.respond_to?(:truncated_solana) && current_user.try(:solana_connected?) %>
+                <%= current_user.truncated_solana %>
+              <% end %>
+            </span>
+            <% if server_level %>
+              <span :class="leveledUp && 'nav-level-pop'" x-text="'Level ' + displayLevel">Level <%= server_level %></span>
+            <% elsif show_logout_link %>
+              <%= link_to "Log out", logout_path, class: "font-mono text-muted no-underline nav-bar-text" %>
             <% end %>
-          </span>
-          <% if server_level %>
-            <span :class="leveledUp && 'nav-level-pop'" x-text="'Level ' + displayLevel">Level <%= server_level %></span>
-          <% elsif show_logout_link %>
-            <%= link_to "Log out", logout_path, class: "font-mono text-muted no-underline nav-bar-text" %>
-          <% end %>
-        </div>
-        <%# Text layer 2: white (clip-path reveals where bar covers) %>
-        <div class="absolute inset-0 flex items-center justify-between px-1.5 font-mono text-white z-[2] nav-bar-text" :style="{ 'clip-path': 'inset(0 ' + (100 - barWidth) + '% 0 0)' }">
-          <span>
-            <% if current_user.respond_to?(:truncated_solana) && current_user.try(:solana_connected?) %>
-              <%= current_user.truncated_solana %>
+          </div>
+          <%# Text layer 2: white (clip-path reveals where bar covers) %>
+          <div class="absolute inset-0 flex items-center justify-between px-1.5 font-mono text-white z-[2] nav-bar-text" :style="{ 'clip-path': 'inset(0 ' + (100 - barWidth) + '% 0 0)' }">
+            <span>
+              <% if current_user.respond_to?(:truncated_solana) && current_user.try(:solana_connected?) %>
+                <%= current_user.truncated_solana %>
+              <% end %>
+            </span>
+            <% if server_level %>
+              <span :class="leveledUp && 'nav-level-pop'" x-text="'Level ' + displayLevel">Level <%= server_level %></span>
+            <% elsif show_logout_link %>
+              <%= link_to "Log out", logout_path, class: "font-mono text-white no-underline nav-bar-text" %>
             <% end %>
-          </span>
-          <% if server_level %>
-            <span :class="leveledUp && 'nav-level-pop'" x-text="'Level ' + displayLevel">Level <%= server_level %></span>
-          <% elsif show_logout_link %>
-            <%= link_to "Log out", logout_path, class: "font-mono text-white no-underline nav-bar-text" %>
-          <% end %>
+          </div>
         </div>
-      </div>
-      <style>
-        @keyframes navLevelPop {
-          0% { transform: scale(1); }
-          15% { transform: scale(1.5); }
-          35% { transform: scale(1.2); }
-          50% { transform: scale(1.4); }
-          70% { transform: scale(1.1); }
-          100% { transform: scale(1); }
-        }
-        .nav-level-pop { animation: navLevelPop 0.8s cubic-bezier(0.34, 1.56, 0.64, 1); }
-        .nav-bar-text { font-size: 10px; }
-      </style>
+        <style>
+          @keyframes navLevelPop {
+            0% { transform: scale(1); }
+            15% { transform: scale(1.5); }
+            35% { transform: scale(1.2); }
+            50% { transform: scale(1.4); }
+            70% { transform: scale(1.1); }
+            100% { transform: scale(1); }
+          }
+          .nav-level-pop { animation: navLevelPop 0.8s cubic-bezier(0.34, 1.56, 0.64, 1); }
+          .nav-bar-text { font-size: 10px; }
+        </style>
+      <% end %>
     </div>
     <%# Div 3 (Avatar): spans both rows %>
     <% account_link = defined?(account_path) ? account_path : "#" %>

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

@@ -1,12 +1,15 @@
 <%#
   Modal host. Single shared shell for any modal that opens through
   Alpine.store('modals'). Owns the backdrop, scroll lock (via
-  modal-open on body), escape key, click-outside, transitions, and
-  ARIA dialog role. Bundles the scroll-lock CSS, bfcache and Turbo
-  Drive snapshot cleanup, store registration, and the
-  window.StudioModals.holdAtLeast(ms) helper. See the gem README for
-  the consumer integration example and API reference; documentation
-  intentionally kept brief here.
+  modal-open on body), escape key, click-outside, ARIA dialog role,
+  mount and unmount animations, the per-modal animation registry
+  (window.ModalAnimations), directional swap() and advance() slides
+  for multi-step flows, bfcache and Turbo Drive snapshot cleanup,
+  store registration, and the window.StudioModals.holdAtLeast(ms)
+  helper. The animation keyframes ship inline in the style block
+  below, so consumers need no extra CSS to get the full behavior.
+  Consumer integration example and API reference: the "Modal host"
+  section of the gem README.
 %>
 <style>
   /* Scroll lock applied by $store.modals._sync() when the stack is non-empty.
@@ -21,6 +24,126 @@
     from { transform: scaleX(1); }
     to   { transform: scaleX(0); }
   }
+
+  /* === Modal mount / unmount animations =================================
+     Bound by the host below via the .modal-card-{mount,unmount} and
+     .modal-backdrop-{mount,unmount} classes. The card open/close use
+     multi-keyframe spring-y curves so the modal POPS in with a small
+     overshoot and POPS out with a tiny anticipation windup before
+     falling — much more present than a plain ease. Backdrop stays on a
+     clean fade (a bouncing backdrop reads as a bug, not polish).
+
+     Durations: the modal-card-out keyframe stays at 220ms to match
+     CLOSE_ANIM_MS in the host's store — that's the timeout before the
+     entry is spliced off the stack. Bump CLOSE_ANIM_MS if you lengthen
+     this.
+
+     Re-skinning: don't fight these classes from an app stylesheet (this
+     inline block sits later in the document, so it wins ties). Instead
+     register a NEW animation — one entry in window.ModalAnimations plus
+     one class in the app's CSS — and open modals with that key. */
+
+  @keyframes modal-card-in {
+    0%   { opacity: 0; transform: scale(0.86) translateY(12px); }
+    55%  { opacity: 1; transform: scale(1.04) translateY(-3px); } /* overshoot */
+    80%  {              transform: scale(0.99) translateY(1px);  } /* small undershoot */
+    100% { opacity: 1; transform: scale(1) translateY(0);        } /* settle */
+  }
+  @keyframes modal-card-out {
+    0%   { opacity: 1; transform: scale(1) translateY(0);         }
+    25%  { opacity: 1; transform: scale(1.03) translateY(-2px);   } /* windup */
+    100% { opacity: 0; transform: scale(0.92) translateY(4px);    } /* fall */
+  }
+  @keyframes modal-backdrop-in {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+  @keyframes modal-backdrop-out {
+    from { opacity: 1; }
+    to   { opacity: 0; }
+  }
+
+  /* Bounce ease the spring; the keyframes already do most of the work,
+     the easing just smooths the segments between them. */
+  .modal-card-mount       { animation: modal-card-in     320ms cubic-bezier(0.34, 1.4, 0.5, 1) both; }
+  .modal-card-unmount     { animation: modal-card-out    220ms cubic-bezier(0.6, -0.2, 0.7, 0.4) forwards; }
+  .modal-backdrop-mount   { animation: modal-backdrop-in 180ms ease-out both; }
+  .modal-backdrop-unmount { animation: modal-backdrop-out 200ms ease-in forwards; }
+
+  /* Named entrance animation: "shake" — a "not quite yet" nope. The card
+     scales/fades in fast (first ~22%) then does a damped horizontal
+     wobble that settles to center, reading as "you can't do that just
+     yet." Wired via the ModalAnimations registry below: open a modal
+     with { enterAnim: 'shake' } to use it. Duration here MUST match
+     ModalAnimations.enter.shake.ms (600). */
+  @keyframes modal-card-shake-in {
+    0%   { opacity: 0; transform: scale(0.92) translateX(0);   }
+    22%  { opacity: 1; transform: scale(1)    translateX(-11px); }
+    37%  {             transform: scale(1)    translateX(9px);   }
+    52%  {             transform: scale(1)    translateX(-7px);  }
+    67%  {             transform: scale(1)    translateX(5px);   }
+    82%  {             transform: scale(1)    translateX(-3px);  }
+    100% { opacity: 1; transform: scale(1)    translateX(0);    }
+  }
+  .modal-card-shake-in { animation: modal-card-shake-in 600ms cubic-bezier(0.36, 0.07, 0.19, 0.97) both; }
+
+  /* Inter-modal swap animations — directional slide for forward-flow feel.
+     The leaving modal slides off to the right + fades; the new one enters
+     from the left. Pairs with $store.modals.swap() (or open(_, _,
+     { replace: true })) — the store flips _swappingOut on the leaving
+     entry, waits CLOSE_ANIM_MS, then flips _swappingIn on the entering
+     entry. Total swap duration ~440ms (220 out + 220 in). */
+  @keyframes modal-card-slide-out-right {
+    from { opacity: 1; transform: translateX(0) scale(1); }
+    to   { opacity: 0; transform: translateX(48px) scale(0.98); }
+  }
+  @keyframes modal-card-slide-in-left {
+    from { opacity: 0; transform: translateX(-48px) scale(0.98); }
+    to   { opacity: 1; transform: translateX(0) scale(1); }
+  }
+  .modal-card-swap-out { animation: modal-card-slide-out-right 220ms cubic-bezier(0.4, 0, 1, 1) forwards; }
+  .modal-card-swap-in  { animation: modal-card-slide-in-left   220ms cubic-bezier(0, 0, 0.2, 1) both; }
+
+  /* Back-direction pair — current step slides off stage-LEFT, next slides
+     in from the RIGHT. Mirror of the forward pair above; together they
+     give wizard nav a directional language (forward = right, back = left)
+     so the user's spatial model of "where the previous step lives" is
+     preserved. Trigger: $store.modals.advance(patch, { direction: 'back' })
+     or swap(id, props, { direction: 'back' }). */
+  @keyframes modal-card-slide-out-left {
+    from { opacity: 1; transform: translateX(0) scale(1); }
+    to   { opacity: 0; transform: translateX(-48px) scale(0.98); }
+  }
+  @keyframes modal-card-slide-in-right {
+    from { opacity: 0; transform: translateX(48px) scale(0.98); }
+    to   { opacity: 1; transform: translateX(0) scale(1); }
+  }
+  .modal-card-swap-out-back { animation: modal-card-slide-out-left 220ms cubic-bezier(0.4, 0, 1, 1) forwards; }
+  .modal-card-swap-in-back  { animation: modal-card-slide-in-right 220ms cubic-bezier(0, 0, 0.2, 1) both; }
+
+  /* Honor reduced-motion preferences — drop the spring/slide motion,
+     just fade fast. Vestibular safety. */
+  @media (prefers-reduced-motion: reduce) {
+    .modal-card-mount,
+    .modal-card-unmount,
+    .modal-card-shake-in,
+    .modal-card-swap-out,
+    .modal-card-swap-in,
+    .modal-card-swap-out-back,
+    .modal-card-swap-in-back,
+    .modal-backdrop-mount,
+    .modal-backdrop-unmount {
+      animation-duration: 80ms;
+      animation-timing-function: linear;
+    }
+    @keyframes modal-card-shake-in { from { opacity: 0; } to { opacity: 1; } }
+    @keyframes modal-card-in  { from { opacity: 0; } to { opacity: 1; } }
+    @keyframes modal-card-out { from { opacity: 1; } to { opacity: 0; } }
+    @keyframes modal-card-slide-out-right { from { opacity: 1; } to { opacity: 0; } }
+    @keyframes modal-card-slide-in-left   { from { opacity: 0; } to { opacity: 1; } }
+    @keyframes modal-card-slide-out-left  { from { opacity: 1; } to { opacity: 0; } }
+    @keyframes modal-card-slide-in-right  { from { opacity: 0; } to { opacity: 1; } }
+  }
 </style>
 
 <script>
@@ -43,40 +166,237 @@
       };
     };
 
+    // === Modal animation registry ======================================
+    //
+    // The single place to define + tune named entrance / exit animations
+    // for the modal card. Each key maps to a CSS class (the defaults ship
+    // in the inline style block above) plus its duration in ms (the store
+    // waits this long before splicing a closing entry off the stack, so
+    // the exit keyframe plays to completion before the DOM unmounts).
+    //
+    // Pass a key into any open() call via props.enterAnim / props.exitAnim:
+    //
+    //   $store.modals.open('foo', { enterAnim: 'shake' })  // shake in, default pop out
+    //   $store.modals.open('bar', { exitAnim: 'slide' })   // default pop in, slide out
+    //
+    // Omitted → the modal uses 'pop' (spring bounce in / fall out).
+    //
+    // Consumer extension point: define window.ModalAnimations BEFORE this
+    // script runs (e.g. in a <script> above the host render) with extra
+    // keys per channel — app entries are merged OVER the engine defaults,
+    // so adding a custom animation never requires redefining pop/shake/
+    // slide. Each custom key needs one registry entry here + one CSS
+    // class in the app's stylesheet. To re-skin a modal's entrance, just
+    // change the enterAnim it's opened with — no host edits needed.
+    //
+    // NB: this is independent of the directional swap()/advance() slide,
+    // which is a separate in-flow transition mechanism (see below) and
+    // always uses the modal-card-swap-* classes regardless of these keys.
+    var animDefaults = {
+      enter: {
+        pop:   { cls: 'modal-card-mount',    ms: 320 },  // default — spring bounce in
+        shake: { cls: 'modal-card-shake-in', ms: 600 },  // "not quite yet" nope
+        slide: { cls: 'modal-card-swap-in',  ms: 220 }   // slide in from the left
+      },
+      exit: {
+        pop:   { cls: 'modal-card-unmount',  ms: 220 },  // default — anticipation + fall
+        slide: { cls: 'modal-card-swap-out', ms: 220 }   // slide out to the right
+      }
+    };
+    var animOverrides = window.ModalAnimations || {};
+    window.ModalAnimations = {
+      enter: Object.assign({}, animDefaults.enter, animOverrides.enter || {}),
+      exit:  Object.assign({}, animDefaults.exit,  animOverrides.exit  || {})
+    };
+    // Late-binding guard: read window.ModalAnimations at CALL time, and
+    // never return undefined. A consumer script that loads after this one
+    // (e.g. an importmap module) may REPLACE the merged registry object
+    // wholesale; without the animDefaults fallback a lookup miss would
+    // make close() throw on .ms and leave the modal stuck open. Unknown
+    // keys and gutted registries fall back to the built-in 'pop'.
+    function modalAnim(channel, key) {
+      var table = (window.ModalAnimations && window.ModalAnimations[channel]) || {};
+      return table[key] || table.pop || animDefaults[channel].pop;
+    }
+
     // === Alpine.store('modals') — the stack ============================
     //
     // Idempotent registration (return early if already registered) so
     // consumer apps can include the host more than once without
     // double-init.
+    //
+    // CLOSE_ANIM_MS: keep in sync with the modal-card-unmount + modal-
+    // backdrop-unmount keyframes in the inline style block above. When
+    // close() is called, we set _closing on the entry so the host can
+    // swap in the unmount classes, then actually splice the stack after
+    // this many ms so the animation plays before the DOM unmounts. If
+    // you change the keyframe durations there, bump this to match.
+    var CLOSE_ANIM_MS = 220;
+    var SWAP_IN_MS    = 220;
+
     document.addEventListener('alpine:init', function() {
       if (Alpine.store('modals')) return;
       Alpine.store('modals', {
         stack: [],
+        // open(id, props, opts)
+        //   opts.replace: true  → swap the top entry with this one. When a
+        //     non-closing modal is currently visible, the swap is a directional
+        //     slide — current modal exits stage-right (modal-card-swap-out)
+        //     and the new one enters stage-left (modal-card-swap-in). Gives
+        //     a "forward progress" feel for wizards / multi-step flows.
+        //     Defaults to a plain mount animation when the stack is empty.
+        //   opts.replace: false (default) → push on top of the stack. Stacking
+        //     semantics — when the new one closes, the previous is revealed
+        //     underneath (e.g. crop-photo on top of profile).
+        // SWAP_IN_MS must match the modal-card-swap-in animation duration in
+        // the inline style block above; we clear the flag after that so a
+        // fresh open() doesn't re-trigger the slide.
         open: function(id, props, opts) {
           props = props || {};
           opts  = opts  || {};
+          var self = this;
+
           if (opts.replace && this.stack.length > 0) {
+            var current = this.current();
+            if (current && !current._closing) {
+              // Phase 1: mark leaving entry with _swappingOut + _closing so
+              // the :class binding swaps in the slide-out keyframe (instead
+              // of the default scale-pop modal-card-unmount) for CLOSE_ANIM_MS.
+              // _swapDir picks which slide direction (forward = exit right,
+              // back = exit left); the same flag carries onto the new entry
+              // below so slide-in mirrors slide-out.
+              var dir = (opts.direction === 'back') ? 'back' : 'forward';
+              current._swapDir = dir;
+              current._swappingOut = true;
+              current._closing = true;
+              setTimeout(function() {
+                // Phase 2: stack swap. New entry carries _swappingIn + the
+                // same _swapDir so the host's :class binding picks the
+                // matching slide-in keyframe. If the marked entry vanished
+                // during the slide-out window (another swap() hot-swapped
+                // it, or a close raced us), DROP this stale replacement —
+                // pushing it would resurrect a modal the user already
+                // navigated past (two swap() calls within CLOSE_ANIM_MS
+                // used to leave both on the stack). Mirrors close()'s
+                // stale-entry guard.
+                var idx = self.stack.indexOf(current);
+                if (idx < 0) return;
+                var newEntry = { id: id, props: props, _swappingIn: true, _swapDir: dir };
+                self.stack[idx] = newEntry;
+                self._sync();
+                // Phase 3: clear the swap-in flag + direction after the
+                // slide finishes so a future close() runs the unmount
+                // keyframe cleanly. _settled latches so the host's
+                // :class binding doesn't snap modal-card-mount back on
+                // (which would re-fire the bounce-in keyframe from
+                // opacity:0 and look like a flash mid-settle).
+                setTimeout(function() {
+                  newEntry._swappingIn = false;
+                  newEntry._swapDir = null;
+                  newEntry._settled = true;
+                }, SWAP_IN_MS);
+              }, CLOSE_ANIM_MS);
+              return;
+            }
+            // Already mid-close — just hot-swap so we don't double up timers.
             this.stack[this.stack.length - 1] = { id: id, props: props };
           } else {
             this.stack.push({ id: id, props: props });
           }
           this._sync();
         },
+        // Sugar — `swap('foo', props)` ≡ `open('foo', props, { replace: true })`.
+        // Pass opts through so callers can request a back-direction slide
+        // on a cross-modal handoff if the new modal is semantically
+        // upstream of the current one (e.g. "return to home modal").
+        swap: function(id, props, opts) {
+          return this.open(id, props, Object.assign({ replace: true }, opts || {}));
+        },
+        // advance(propsPatch, opts) — patch the current entry's props
+        // WITH the same directional slide as swap(), but WITHOUT
+        // replacing the stack entry. Use this for in-flow step
+        // transitions inside one modal (e.g. picker → waiting →
+        // confirming) where the modal's outer x-data scope (form
+        // state, watchers, factories) needs to survive the transition.
+        // swap() drops a fresh entry into the stack which re-evaluates
+        // the registered <template x-if="id===...">  — fine for
+        // cross-modal handoffs, but heavy for "same modal, next step."
+        // advance() is the lightweight cousin.
+        //
+        // opts.direction: 'forward' (default — current exits right, next
+        //   enters from left; reads as "moving ahead in the flow")
+        //   or 'back' (mirrored — current exits left, next enters from
+        //   right; reads as "returning to the previous step"). Pair
+        //   forward calls with back calls on their inverse buttons so
+        //   the user's spatial model of the wizard stays consistent.
+        //
+        // Timing mirrors swap():
+        //   t=0      → flip _swappingOut, outer card slides off (CLOSE_ANIM_MS)
+        //   t=220ms  → patch props, flip _swappingIn, card slides in
+        //   t=440ms  → clear _swappingIn + _swapDir so the next open/
+        //              close uses default mount/unmount keyframes
+        //
+        // Guards: no-op if no current entry, or if the entry is already
+        // closing or mid-swap (prevents double-clicks from stacking timers).
+        advance: function(propsPatch, opts) {
+          opts = opts || {};
+          var cur = this.current();
+          if (!cur || cur._closing || cur._swappingOut) return;
+          var self = this;
+          cur._swapDir = (opts.direction === 'back') ? 'back' : 'forward';
+          cur._swappingOut = true;
+          setTimeout(function() {
+            // Re-resolve in case the stack mutated during the slide-out
+            // window. If our entry got popped (e.g. user hit Escape mid-
+            // animation), bail rather than splat props onto a stale ref.
+            if (self.stack.indexOf(cur) < 0) return;
+            if (propsPatch) Object.assign(cur.props, propsPatch);
+            cur._swappingOut = false;
+            cur._swappingIn = true;
+            setTimeout(function() {
+              cur._swappingIn = false;
+              cur._swapDir = null;
+              cur._settled = true;
+            }, SWAP_IN_MS);
+          }, CLOSE_ANIM_MS);
+        },
         close: function() {
-          this.stack.pop();
-          this._sync();
+          var self = this;
+          var entry = this.current();
+          if (!entry || entry._closing) return;  // empty stack or already closing
+          // Flip _closing → Alpine reactivity adds the modal-card-unmount
+          // and modal-backdrop-unmount classes via the :class bindings on
+          // the host. Wait for the animation to play, then splice THIS
+          // specific entry from the stack (not pop() — the top might have
+          // changed if another open() ran during the close window). The
+          // splice delay tracks the entry's chosen exit animation
+          // (props.exitAnim → registry ms) so a longer custom exit
+          // keyframe plays fully before the DOM unmounts; defaults to
+          // the 'pop' fall (220ms).
+          entry._closing = true;
+          setTimeout(function() {
+            var idx = self.stack.indexOf(entry);
+            if (idx >= 0) {
+              self.stack.splice(idx, 1);
+              self._sync();
+            }
+          }, modalAnim('exit', entry.props && entry.props.exitAnim).ms);
         },
         closeAll: function() {
+          // No animation — used by Turbo before-cache + bfcache cleanup
+          // where the user is navigating away and we just need the DOM
+          // clean immediately.
           this.stack = [];
           this._sync();
         },
         // Drops every modal whose props don't explicitly opt out of dismissal
         // (i.e. dismissible: false). Used by the bfcache + Turbo snapshot
-        // cleanup below so an in-flight on-chain TX modal — which sets
-        // dismissible: false precisely to forbid losing its UI mid-flight —
-        // survives a back/forward navigation. Celebratory modals (default
-        // dismissible: true) are still cleared so users don't return to a
-        // stale "Success!" card.
+        // cleanup below so a modal guarding an in-flight operation (e.g. an
+        // on-chain TX) — which sets dismissible: false precisely to forbid
+        // losing its UI mid-flight — survives a back/forward navigation;
+        // the still-in-flight JS promise resolves against a non-empty
+        // stack. Celebratory modals (default dismissible: true) are still
+        // cleared so users don't return to a stale "Success!" card.
         closeAllDismissible: function() {
           this.stack = this.stack.filter(function(modal) {
             return modal.props && modal.props.dismissible === false;
@@ -92,6 +412,45 @@
         current: function() {
           return this.stack.length ? this.stack[this.stack.length - 1] : null;
         },
+        // cardClasses() — the animation class set for the visible card.
+        // Resolves the entry's enter/exit animation keys (props.enterAnim
+        // / props.exitAnim) through the ModalAnimations registry, while
+        // keeping the directional swap-* classes (the in-flow slide) as
+        // fixed names. Lifecycle → class:
+        //   fresh mount  → enter key class  (default 'pop' → modal-card-mount)
+        //   closing      → exit key class   (default 'pop' → modal-card-unmount)
+        //   swap/advance → modal-card-swap-{in,out}[-back]
+        // The mount class is gated on !_settled (so a completed swap doesn't
+        // re-fire the bounce) and !_closing (so close shows ONLY the exit
+        // keyframe, not both stacked).
+        cardClasses: function() {
+          var c = this.current();
+          if (!c) return {};
+          var o = {};
+          if (!c._settled && !c._swappingIn && !c._swappingOut && !c._closing) {
+            o[modalAnim('enter', c.props && c.props.enterAnim).cls] = true;
+          }
+          if (c._closing && !c._swappingOut) {
+            o[modalAnim('exit', c.props && c.props.exitAnim).cls] = true;
+          }
+          // The registry's 'slide' entries resolve to the SAME class names
+          // as the fixed directional flags below (enter.slide is
+          // modal-card-swap-in, exit.slide is modal-card-swap-out). Never
+          // reassign a key the enter/exit resolution above already set —
+          // an unconditional assignment here clobbered those keys to
+          // false, so enterAnim/exitAnim 'slide' produced NO class and
+          // the exit sat motionless for the splice delay, then snapped.
+          var swapFlags = {
+            'modal-card-swap-in':       !!(c._swappingIn  && c._swapDir !== 'back'),
+            'modal-card-swap-out':      !!(c._swappingOut && c._swapDir !== 'back'),
+            'modal-card-swap-in-back':  !!(c._swappingIn  && c._swapDir === 'back'),
+            'modal-card-swap-out-back': !!(c._swappingOut && c._swapDir === 'back')
+          };
+          for (var flag in swapFlags) {
+            if (!(flag in o)) o[flag] = swapFlags[flag];
+          }
+          return o;
+        },
         _sync: function() {
           if (this.stack.length) {
             document.body.classList.add('modal-open');
@@ -127,26 +486,42 @@
 </script>
 
 <template x-if="$store.modals.current()">
-  <%# A modal can opt out of escape + click-outside dismissal by setting
-      `dismissible: false` on its props (e.g. processing an on-chain tx
+  <%# Backdrop + card use CSS keyframe animations (NOT Alpine
+      x-transition), all shipped in the inline style block above. On
+      mount, the .modal-backdrop-mount + card mount classes fire fade-in
+      + drop-recoil. On close, the store flips _closing, the :class
+      bindings add the unmount classes, the exit keyframes play, and
+      after the exit duration the store splices the entry from the stack
+      and the whole thing unmounts (now invisible).
+
+      A modal can opt out of escape + click-outside dismissal by setting
+      dismissible: false on its props (e.g. processing an on-chain tx
       where an accidental click would orphan a signed but un-confirmed
       transaction). Defaults to dismissible. %>
-  <div class="fixed inset-0 z-[120] flex items-center justify-center p-4"
+  <div class="fixed inset-0 z-[120] flex items-center justify-center p-4 modal-backdrop-mount"
+       :class="$store.modals.current()?._closing && 'modal-backdrop-unmount'"
        style="background:rgba(0,0,0,0.6)"
        role="dialog"
        aria-modal="true"
        @keydown.escape.window="$store.modals.current() && $store.modals.current().props.dismissible !== false && $store.modals.close()"
-       @click.self="$store.modals.current() && $store.modals.current().props.dismissible !== false && $store.modals.close()"
-       x-transition:enter="transition ease-out duration-200"
-       x-transition:enter-start="opacity-0"
-       x-transition:enter-end="opacity-100"
-       x-transition:leave="transition ease-in duration-150"
-       x-transition:leave-start="opacity-100"
-       x-transition:leave-end="opacity-0">
+       @click.self="$store.modals.current() && $store.modals.current().props.dismissible !== false && $store.modals.close()">
+    <%# Card animation is class-driven (cardClasses() in the store) so it
+        can pick the right keyframe for the current store state. Plain
+        mount/unmount for first open + close, resolved through the
+        ModalAnimations registry (props.enterAnim / props.exitAnim).
+        Swap-out + swap-in for inter-modal transitions triggered by
+        $store.modals.swap() / advance() (or open with { replace: true }).
+        _swapDir picks forward (exit right / enter left — default) vs
+        back (exit left / enter right — opt-in via { direction: 'back' }).
+        The mount class is gated on !_settled so when a swap-in completes
+        the class binding does NOT snap back to the mount class and
+        re-fire the bounce-in keyframe from opacity:0 — without the gate,
+        the card briefly disappears and bounces in again right as the
+        slide finishes, which reads as a flash mid-transition. _settled
+        stays true for the rest of the entry's lifetime so a stale Alpine
+        re-evaluation can't retrigger the bounce. %>
     <div class="bg-surface rounded-xl border border-subtle shadow-2xl p-6 max-w-sm w-full"
-         x-transition:enter="transition ease-out duration-200"
-         x-transition:enter-start="opacity-0 scale-95"
-         x-transition:enter-end="opacity-100 scale-100">
+         :class="$store.modals.cardClasses()">
       <%# Consumer-provided content registrations. Each block typically
           contains a <template x-if="$store.modals.current().id === 'X'">
           render "modals/X" </template>. %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.12.1"
+  VERSION = "0.13.0"
 end

data/tailwind/studio.tailwind.config.js

@@ -9,6 +9,14 @@ module.exports = {
       mono: ['ui-monospace', 'SFMono-Regular', 'monospace'],
     },
     extend: {
+      // Sub-xs type scale for dense UI (badges, meta rows, tick labels).
+      // Bare sizes (no line-height tuple) so text-2xs / text-3xs are drop-in
+      // replacements for the text-[11px] / text-[10px] arbitrary values that
+      // dominate the consumer apps.
+      fontSize: {
+        '2xs': '0.6875rem', // 11px
+        '3xs': '0.625rem',  // 10px
+      },
       colors: {
         // Theme-aware semantic tokens (reference CSS variables)
         page:          'var(--color-page)',

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Alex McRitchie
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -171,6 +172,7 @@ files:
 - app/assets/images/ses-favicon.png
 - app/assets/javascripts/studio/sticky_table_header.js
 - app/assets/stylesheets/studio/sticky_table_header.css
+- app/assets/tailwind/studio_engine/engine.css
 - app/controllers/concerns/solana/session_auth.rb
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/error_handling.rb
@@ -296,6 +298,7 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -310,7 +313,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching