studio-engine 0.46.0 → 0.47.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 026c018bce499134d15e23ca2f9101e05da752380be210e5c6136babbac97a5a
-  data.tar.gz: ff33bee4cbe01664a9f2385716107d0a7319e0b267cc9a1f6c4a47e0555c4c5a
+  metadata.gz: 90659c9a1e1cd62a432e47529501574cca5f7a217f48b6f0eaf0990198150636
+  data.tar.gz: 23435ace6999ecb78b5ad57c2a7c90cf8da64cee0415feb1d5a2fd82f65d4470
 SHA512:
-  metadata.gz: 25dedda1d9c8f5c7cc2f485cfcea80e94ce3446952029015d5e53ab1dd41fdbfd014dc1c1251f9c637ab7fbd3605b7aa50e0593e4d4e85b1a81c6349536dd7ea
-  data.tar.gz: 8f71ee45ddf77e12851991857aff2a72bfe3082719b7505c16b8fc7cd08d17c5bf502c07af2393aa315c22146067ef63af1d275d9566d327193d9fa935a94a72
+  metadata.gz: 5c964c5081845ae99315fe62fe98fde0969255d779537524aeb0abbde5b8ceb5fab3ee98c5771471c992b3628021e35e6b42a5f91dc5909bbb3601fd9dabbe1d
+  data.tar.gz: 8c1e90e63006085ef8745ba6a5d1e06b004e09e4c74c523780be2ae9f7e024b3b426aa228dc22eeea683459820a3a9a079720d27e8c8905e90c4796999595d2d

data/CHANGELOG.md

@@ -35,6 +35,60 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **`$store.modals.isLive(id)` — "is this card up?", the question `isOpen` cannot
+  answer.** `close()` flips `_closing` immediately and splices the entry only
+  after the exit animation, so for that whole ~220ms window `isOpen(id)` reports
+  a card that is already leaving the screen as open. Every consumer guard that
+  means *don't open this twice* wants the opposite answer, and turf-monster had
+  hand-rolled the same `_closing`-aware `.some()` over `.stack` to get it.
+
+  `isLive(id)` returns true when a card with that id is on the stack **and not on
+  its way out**. It also accepts an array — `isLive(['onboarding', 'age-verify',
+  'wallet-setup'])` — so a caller can ask "is any card of this flow still up?"
+  without reaching into `.stack` and re-deriving the lifecycle rule. Shipped on
+  both the shared host and the page-scoped host.
+
+  **`isOpen(id)` is unchanged.** It still answers "on the stack, in any state",
+  which is what a caller asking "is the DOM node still mounted" depends on. This
+  is additive; no existing call site changes behavior. The proposal on the task
+  was `isOpen(id, { ignoreClosing: true })`, rejected because it reads as a double
+  negative at the call site (*is it open, ignoring that it is closing*) and
+  because two genuinely different questions are clearer as two names than as one
+  name with a mode flag.
+
+  The asymmetry to know, and the reason this is not simply "not animating":
+
+  | Transition | Flags on the entry | `isOpen` | `isLive` |
+  |---|---|---|---|
+  | `open()` | — | true | **true** |
+  | `close()` | `_closing` | true | **false** |
+  | `swap()`, leaving entry | `_swappingOut` + `_closing` | true | **false** |
+  | `advance()` | `_swappingOut` only | true | **true** |
+  | spliced / never opened | — | false | **false** |
+
+  `advance()` slides the SAME card between steps of its own flow, so it sets
+  `_swappingOut` and nothing else. `isLive` therefore tests `_closing` alone and
+  never consults `_swappingOut`: conflating the two reports a card as gone in the
+  middle of a step transition, which is how an in-flow hand-off starts looking to
+  a caller like a dismissal. Both halves are pinned by tests that execute the
+  store under node (`test/views/modal_host_store_behavior_test.rb`) — dropping the
+  `_closing` check and conflating it with `_swappingOut` redden *different*
+  assertions.
+
+  **Consumers that fork the host do not get this from a version bump.**
+  `mcritchie-studio` and `turf-monster` both ship their own
+  `app/views/studio/modals/_host.html.erb`, and a non-isolated engine lets the app
+  copy shadow the gem's. Those apps pick `isLive` up only by porting it into their
+  fork or by retiring the fork; `studio/modals/scoped_host` is unforked everywhere
+  and carries it today. turf-monster's two hand-rolled scans — the onboarding
+  chain driver's `open()` guard (`layouts/application.html.erb`) and
+  `selectionBoard#showWalletSetupModal` (`contests/_turf_totals_board.html.erb`)
+  — can then collapse onto this primitive, as can its two remaining bare
+  `isOpen()` idempotence guards (`app/javascript/solana_stores.js` for
+  `wallet-changed`, `cdp/returns/show.html.erb` for `cdp-ramp`), which are the
+  exact defect `isLive` exists to prevent. A turf-side follow-up, not part of
+  this change.
+
 - **The standard user profile columns — and the engine's first migration against
   a host-owned table.** Every other engine migration creates a `studio_*` table
   the engine owns outright; `users` belongs to the host. That boundary is crossed

data/README.md

@@ -258,6 +258,14 @@ The scoped host takes its animations from `engine-motion.css` rather than an
 inline copy, so a consumer bundling that layer gets the same spring as the shared
 host.
 
+It carries the store API below with three deliberate differences: there is no
+`advance()`; `swap()` replaces the top entry immediately rather than running the
+shared host's directional slide — so no entry is ever left mid-transition; and it
+does not read the `window.ModalAnimations` registry, so the `enterAnim` /
+`exitAnim` props documented under the table are ignored and the exit always plays
+the 220ms unmount from `engine-motion.css`. `isOpen` and `isLive` behave
+identically on both.
+
 Store API (`Alpine.store('modals')`):
 
 | Call | Behavior |
@@ -268,7 +276,17 @@ Store API (`Alpine.store('modals')`):
 | `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. |
+| `isOpen(id)` / `current()` | Introspection. `isOpen` is true while a card is ON THE STACK — including the whole exit animation, because `close()` flips `_closing` at once and splices only after it. |
+| `isLive(id)` / `isLive([id, …])` | True when a card with that id is up and **not on its way out**. Pass an array to ask about a set of ids ("is any card of this flow still up?"). |
+
+**`isOpen` or `isLive`?** A guard that means "don't open this twice" almost
+always wants `isLive`. `isOpen` stays true for the ~220ms exit window, so an
+idempotence check built on it refuses to reopen a card the user just dismissed.
+The one asymmetry worth knowing: `advance()` slides the *same* card between
+steps of its own flow and sets only `_swappingOut`, so a mid-advance card is
+still **live** — only `close()` and the outgoing half of a `swap()` set
+`_closing`. `isLive` tests `_closing` alone, deliberately; conflating it with
+`_swappingOut` makes an in-flow hand-off look like a dismissal.
 
 Recognized props: `dismissible: false` disables escape/click-outside dismissal
 (e.g. an in-flight transaction); `enterAnim` / `exitAnim` pick a named

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

@@ -390,12 +390,51 @@
           });
           this._sync();
         },
+        // isOpen(id) — is a card with this id ON THE STACK, in any
+        // lifecycle state? A card mid-close still counts: close() flips
+        // _closing at once and splices only after the exit animation, so
+        // this answers TRUE for that whole exit window. Unchanged — callers
+        // asking "is the DOM node still mounted" depend on exactly this.
+        // If you mean "is it still up", you want isLive() below.
         isOpen: function(id) {
           for (var i = 0; i < this.stack.length; i++) {
             if (this.stack[i].id === id) return true;
           }
           return false;
         },
+        // isLive(id) / isLive([id, ...]) — is a card with this id on the
+        // stack and NOT on its way out? This is what a "don't open it
+        // twice" guard actually means, and it is the question isOpen
+        // cannot answer.
+        //
+        // The difference is a TIMING one, and the asymmetry is load-bearing:
+        //
+        //   close()               entry gets _closing, and is spliced
+        //                         CLOSE_ANIM_MS later. isOpen stays TRUE for
+        //                         that window; isLive is FALSE immediately.
+        //   swap() / open(...,    the LEAVING entry gets _swappingOut AND
+        //   { replace: true })    _closing — a different card is taking the
+        //                         screen, so it is not live either.
+        //   advance()             the entry gets _swappingOut and NOTHING
+        //                         else. Same card, same id, sliding between
+        //                         steps of its own flow. It stays LIVE.
+        //
+        // So this tests _closing ALONE and deliberately never consults
+        // _swappingOut. Conflating the two reports a card as gone in the
+        // middle of a step transition, which is how an in-flow hand-off
+        // starts looking to a caller like a dismissal.
+        //
+        // Accepts an array so a caller can ask about a SET of ids ("is any
+        // card belonging to this flow still up?") without reaching into
+        // .stack and re-deriving the lifecycle rule for itself.
+        isLive: function(id) {
+          var ids = Array.isArray(id) ? id : [id];
+          for (var i = 0; i < this.stack.length; i++) {
+            var entry = this.stack[i];
+            if (entry && !entry._closing && ids.indexOf(entry.id) !== -1) return true;
+          }
+          return false;
+        },
         current: function() {
           return this.stack.length ? this.stack[this.stack.length - 1] : null;
         },

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

@@ -138,10 +138,26 @@
           this._sync();
         },
 
+        // isOpen(id) — on the stack in ANY lifecycle state, including a card
+        // mid-close (close() flips _closing at once and splices only after
+        // CLOSE_ANIM_MS). isLive() below is the "still up" question.
         isOpen: function(id) {
           return this.stack.some(function(entry) { return entry.id === id; });
         },
 
+        // isLive(id) / isLive([id, ...]) — on the stack and NOT on its way
+        // out. Mirrors the shared host's primitive so a page-scoped store
+        // answers the same question the same way; see studio/modals/_host
+        // for the full lifecycle rationale. Tests _closing ALONE: a leaving
+        // swap() entry carries _swappingOut AND _closing, so _swappingOut on
+        // its own must never count as leaving.
+        isLive: function(id) {
+          var ids = Array.isArray(id) ? id : [id];
+          return this.stack.some(function(entry) {
+            return entry && !entry._closing && ids.indexOf(entry.id) !== -1;
+          });
+        },
+
         current: function() {
           return this.stack.length ? this.stack[this.stack.length - 1] : null;
         },

data/db/migrate/20260813220000_add_standard_user_profile_columns.rb

@@ -34,8 +34,37 @@
 # belong to Studio::IpLocations — the column is just where it lands. It holds
 # IP-derived location data, which is personal data in most jurisdictions; the
 # 50-entry cap there bounds it, and no app writes to it until it opts in.
+# ON THE DOWN: this migration REFUSES to reverse, deliberately.
+#
+# `up` is idempotent by design — every add is `if_not_exists`, precisely so it can
+# run against apps that already disagree. That guard is what makes it safe going
+# in, and it is exactly what makes an honest `down` impossible: the migration
+# records NOTHING about which columns it actually created on this host.
+#
+# So a `down` cannot tell "I added this" from "the host has had it since 2024":
+#
+#   - mcritchie-studio owned `users.first_name` BEFORE this ran.
+#   - turf-monster owned `users.first_name` AND `users.birth_year`.
+#   - mcritchie-industries owned none of the five.
+#
+# The two apps the `up` was careful not to touch are the two a `DROP COLUMN`
+# would rob. Rails' auto-inverse does precisely that: `INVERT_METHODS` maps
+# `add_column` to `remove_column` and passes the same options through, and
+# `remove_column` honours only `if_exists`. A stray `if_not_exists:` there is
+# silently DISCARDED rather than raising.
+#
+# `if_exists` is NOT the fix, and it is worth saying why since it is the reflex:
+# it asks "does this column exist?" — and on those two apps it does. That is the
+# whole hazard. `if_exists` only protects a SECOND rollback, after the data is
+# already gone.
+#
+# Refusing turns silent data loss into a loud, actionable error. An operator who
+# genuinely wants these columns gone can drop the ones they know they own, by
+# hand, with the schema in front of them.
 class AddStandardUserProfileColumns < ActiveRecord::Migration[7.2]
-  def change
+  COLUMNS = %i[first_name birth_day birth_month birth_year ip_locations].freeze
+
+  def up
     # An app that has no users table (the engine's dummy, and any future
     # consumer that names its accounts something else) is simply skipped.
     return unless table_exists?(:users)
@@ -48,4 +77,22 @@ class AddStandardUserProfileColumns < ActiveRecord::Migration[7.2]
 
     add_column :users, :ip_locations, :jsonb, default: [], null: false, if_not_exists: true
   end
+
+  def down
+    # Nothing was added, so nothing is owed — an app without `users` never ran
+    # the `up` body either, and reversing that is genuinely a no-op.
+    return unless table_exists?(:users)
+
+    raise ActiveRecord::IrreversibleMigration, <<~MSG
+      AddStandardUserProfileColumns cannot be reversed safely.
+
+      Its `up` adds #{COLUMNS.join(", ")} with `if_not_exists`, so it does not
+      know which of them it created on this host and which the host already
+      owned. Dropping them all would destroy host-owned data (mcritchie-studio
+      owned first_name; turf-monster owned first_name and birth_year).
+
+      If you truly want a column gone, drop the ones you know this app did not
+      own before the migration, by hand, in their own migration.
+    MSG
+  end
 end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.46.0"
+  VERSION = "0.47.1"
 end

metadata

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