studio-engine 0.69.4 → 0.70.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d0b8a6c255a4f9e18d6a3a588abefdd7dd5d54a3801deb9b52eb99da2d78fe
-  data.tar.gz: 3467bf1af09d79805053d721c1d0d6028fd0c5b0f806c94d6a2cdc7864f048f1
+  metadata.gz: f1c217135776ee0fcd67dd4ed2e9a72f1aedf5260ac23cfc23615ab83754133a
+  data.tar.gz: 42878ae8f85ed0c911b99c940e3c5094ca7329fed4bbb727ebfa4466bba99dfb
 SHA512:
-  metadata.gz: 3fd8ea14026738113f2348ea267b2cde306afa6a37d1b37dbf23e426013cb632be62164413e64516893f913e9f8a1618559ef326187e328001d6effceffe4187
-  data.tar.gz: 1498813d632e019fc574a6467e87fa73965f0e018001c845cac52a22d21443cfad8426e50a94ec9d37e874a6f1d059770dd97696665141853fb2a9c458b97242
+  metadata.gz: d72745a5c54559b745fc0fefe1ac1c45b3921efeccbe5769f3b1da5ceaa1e11463c317984847fc1300fb0387610c33c4f0c7504e279871630f5535db563c935e
+  data.tar.gz: 16be22a876c99c848169a2dcd551593ff4b8c377427acd9d84c04bf732847d261422c79d9b7f30397bf8b04c2d13a894999cc542a95bb1037f9deeaea0c5c32a

data/CHANGELOG.md

@@ -6,6 +6,43 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **A `required` mode on the shared first-name card.**
+  `studio/modals/onboarding/_first_name` grows one local. `required: true`
+  renders the card with BOTH skip affordances gone — the "Skip for now" button
+  is not emitted at all, and the × merely CLOSES and is labelled `Close` — and
+  swaps the sub-copy to the audience being gated. Default `false`, so the
+  post-auth chain card McRitchie Studio renders today does not move.
+
+  **IT IS FOR A HOST THAT GATES SOMETHING ON THE NAME.** turf-monster's entry
+  gate opens this card as the first validation of hold-to-confirm, and that gate
+  reads the stored COLUMN — so a recorded skip buys the user nothing and the
+  Skip link is a door painted on a wall, promising a way past a wall that does
+  not move.
+
+  **IT IS DELIBERATELY NOT A TRAP.** Closing stays reachable, because abandoning
+  the flow and slipping past the gate are two different things: the × still
+  dismisses the card, it just stops calling `skip()` and stops claiming it did.
+  A `required` that also removed the × would satisfy every "hides the skip"
+  reading and be a worse card, so the two are asserted as a PAIR.
+
+  **RESOLVED SERVER-SIDE, not through an Alpine `x-show`** — the source this was
+  ported from hides its skip button reactively, which leaves a button that must
+  not exist sitting in the DOM and clickable for as long as Alpine has not
+  mounted, and there for good if it never does. `required` is known at render
+  time, so the button is simply never emitted.
+
+  The default render is asserted **byte-for-byte identical** to `required:
+  false`, which is what pins the existing consumer. Mutation-checked 5/5:
+  flipping the default, un-hiding the skip button, making the × always skip,
+  freezing the label, and freezing the sub-copy each turn the suite red on a
+  different test.
+
+  This was the LAST mode turf-monster's own 240-line `modals/_onboarding` had
+  that the gem did not, so that copy can be deleted next release. A host wanting
+  both modes mounts two `<template x-if>` ids rather than branching one at
+  runtime — which is how the two cards already differ in copy, not just in
+  affordances.
+
 - **Knowledge coverage view** — `/admin/knowledge/coverage` +
   `Studio::KnowledgeExpectation`: the "what SHOULD exist" half of the
   knowledge layer. Expectations carry an entity, folder, provenance
@@ -21,6 +58,41 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   `Studio.draw_knowledge_routes` opt-in. Built for the Commercial Welding
   65-item diligence tracker; app-agnostic like the rest of the layer.
 
+- **The style guide grows the two modal simulators that review ENGINE
+  behaviour** — `#modals-motion-registry` ("Enter & leave animations") and
+  `#modals-stack-mechanics` ("Stack behaviour") in `style/_modals`. Both are
+  ported from turf-monster's `/admin/modals` gallery, which is being deleted:
+  the rest of that page was consumer showroom, but these two exercised engine
+  mechanics — the `window.ModalAnimations` registry, and the modal stack's
+  dismissibility / `holdAtLeast` / LIFO rules — and would have gone with it.
+
+  The motion section BUILDS ITS CONTROLS FROM THE LIVE REGISTRY at load
+  (a button and a dropdown option per registered key, per channel), so
+  registering a new animation surfaces it on the guide with no edit to the
+  page. That is the property the section exists for, and
+  `test/views/style_guide_modal_simulator_test.rb` pins it from both sides:
+  the containers must ship EMPTY, and the build must enumerate
+  `window.ModalAnimations` rather than a local literal.
+
+  The stack demos drive `$store.dsModals` and the guide's own `onchain-tx`
+  specimen directly. **One demo did not come across: "error with recovery."**
+  turf's `setRecovery(label, fn, { phantom })` is a method on that app's
+  legacy compatibility proxy and renders a recovery button on ITS `_onchain_tx`
+  card; the engine specimen's error state is `blocks/_card_header` plus a plain
+  Close, with no recovery affordance. Porting it would have meant designing a
+  new block into a shipped partial, so it was dropped rather than shimmed —
+  roughly half the ported demos drove that proxy, and none of them reference it
+  now (asserted).
+
+  **Both sections are graded in a browser**, because neither is observable from
+  the response bytes: `e2e/style_modal_simulators.spec.js` (7 specs) drives a new
+  `/lab/style_modals` lab page, which mounts the shared modal host exactly as a
+  consumer layout does — without it `window.ModalAnimations` is undefined, the
+  build produces no controls, and "the controls match the registry" would be
+  vacuously true at `0 == 0`. Each spec was verified RED against its own defect
+  reintroduced, with the lab server restarted between runs. The lane contract
+  moves 116 → 123 (`config/e2e_lane.yml`), re-derived with the lister.
+
 ### Changed
 
 - **`Gemfile.lock` resolves solana-studio 0.5.7, and a gate now keeps it there.** The lock had sat on **0.5.3 for four patch releases** while BOTH consumers shipped 0.5.7 (turf-monster `~> 0.5.3`, mcritchie-studio `~> 0.5`). Nothing was red and nothing could have been: engine CI installs with `bundler-cache: true`, so it resolves from the lock and never fresh — the drift does not self-correct and never surfaces as flakiness. It matters because `test/views/style_web3_specimens_test.rb` exists to prove "the style guide renders the REAL gem cards" and reads them off whatever the LOCK resolved; four versions behind, that guard certifies a card no consumer receives. It still passes — only its MEANING changes. MEASURED on this span, the gem's whole `app/` tree was byte-identical 0.5.3 → 0.5.7 (only `CHANGELOG.md`, `README.md` and `version.rb` differ), so this instance cost nothing, which is exactly why it went four releases unnoticed.
@@ -55,6 +127,73 @@ 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
+  name and people type a full one, so "Bartholomew Fitzwilliam
+  Montgomery-Smythe" (41 characters) stored 40 of them and handed the account
+  back its own surname misspelled, **"Montgomery-Smyth"**, on every surface
+  `name` feeds.
+
+  **ONE CONSTANT WAS ANSWERING TWO QUESTIONS**, which is why neither call site
+  looked wrong. `/profile` applies the same number PER FIELD (`normalized_name`,
+  once to each of its two inputs); onboarding applied it to first name PLUS
+  surname in one string. The fix NAMES the second question rather than
+  re-scoping the first: **`Studio::FULL_NAME_MAX_LENGTH`**, the whole-answer
+  cap, `(FIRST_NAME_MAX_LENGTH * 2) + 1` = **81**. It is DERIVED, not picked —
+  first(40) + a space + last(40) is the longest answer whose two halves BOTH
+  still fit the per-field cap, so onboarding can never accept a name `/profile`
+  would silently shorten on the next save, which is the drift the shared
+  constant existed to prevent. `FIRST_NAME_MAX_LENGTH` keeps its value and its
+  meaning, and `test/integration/profile_name_field_caps_test.rb` now proves
+  that by sending BOTH fields over-long in one request and reading two 40s back
+  — a single-field assertion cannot tell "per field" from "per whole name".
+
+  **PAST THE CAP IT REFUSES INSTEAD OF TRUNCATING** (422 + `{ error: … }`,
+  rendered inline by the modal). `.first(cap)` on a name is not a cap but a
+  rewrite: it accepted the answer, stored something nobody typed, and reported
+  success — and raising the number alone would only move that cliff one
+  character further out. Two independent rules, because the whole answer becomes
+  `name` while each half becomes its own column: the answer must fit the
+  whole-answer cap, and each derived half must fit the per-field cap (a single
+  60-character word passes the first and would still land a `first_name`
+  `/profile` shortens). The onboarding input's `maxlength` default was a LITERAL
+  `40` — a third copy of the per-field number, on the one field that receives a
+  whole name — and now reads `FULL_NAME_MAX_LENGTH`, so the browser bound and
+  the server bound cannot drift.
+
+  **NEITHER CAP IS A COLUMN CEILING.** Measured 2026-09-06 across all six
+  consumer databases (mcritchie-studio, turf-monster, mcritchie-industries;
+  production and QA): `name`, `first_name` and `last_name` are unbounded
+  `character varying` — `character_maximum_length` NULL, no CHECK constraint, no
+  model length validation. Raising the bound cannot trade a silent truncation
+  for a raised error at any value, so this is a product decision start to
+  finish.
+
+  **NO DATA REPAIR SHIPS.** Re-measured for THIS defect on the same six
+  databases: **zero rows** carry a `name`, `first_name` or `last_name` at or
+  over 40 characters, and the longest `name` in the fleet is 27 (control:
+  5 / 6 / 46 / 15 / 4 / 4 users scanned, `max(length(name))` non-null in every
+  one). Nothing was truncated in production, so there is nothing to repair — and
+  a row whose halves disagree with its `name` because of a `/profile` edit must
+  never be auto-repaired anyway.
+
 - **Onboarding no longer stores a two-word answer as the whole first name.**
   `Studio::OnboardingController#first_name` writes with `update_columns`, which
   skips callbacks — so the host's `before_save :set_name_parts` never ran and
@@ -72,10 +211,16 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   `test/integration/onboarding_name_parts_test.rb` carries that as a live
   control (`update!` moves `pat-pat@example.com` → `ada-lovelace-pat@…`), not as
   a claim. `last_name` is written only where the column exists: the engine's own
-  standard-columns migration does not carry it, so mcritchie-industries,
-  moms-app and acquisition-studio would otherwise have taken a
-  `MissingAttributeError` 500 on every hyphen-free two-word answer
-  (`test/integration/onboarding_thin_host_test.rb`).
+  standard-columns migration does not carry it, so a host that opts into these
+  routes before it runs that column would otherwise take a
+  `MissingAttributeError` 500 on every two-word answer
+  (`test/integration/onboarding_thin_host_test.rb`). **Corrected 2026-09-06:**
+  an earlier version of this entry named mcritchie-industries, moms-app and
+  acquisition-studio as apps that would have taken that 500. They carry no
+  `last_name`, but they do not mount these endpoints at all —
+  `Studio.draw_onboarding_routes` defaults to false and only mcritchie-studio
+  and turf-monster set it true, and both of those HAVE the column. The guard is
+  a standing one for the next host to opt in, not a live save.
   NO DATA REPAIR SHIPS: measured 2026-09-05 across both production databases
   (mcritchie-studio 5 users, turf-monster 43) and both QA ones, **zero rows**
   carry a space in `first_name`. Repairing rows whose halves merely disagree

data/app/controllers/studio/onboarding_controller.rb

@@ -23,22 +23,40 @@ module Studio
     # Both actions are for the freshly signed-in user, so authentication is the
     # host's default require_authentication — no skip_before_action here.
 
-    # The shared cap (Studio::FIRST_NAME_MAX_LENGTH). Kept under the old name
-    # here because it is referenced from outside this class; what changed is that
-    # it is no longer a SECOND definition of the same number. /profile writes the
-    # same column and now reads the same constant.
+    # The PER-FIELD cap (Studio::FIRST_NAME_MAX_LENGTH) — what one derived half
+    # may be. Kept under the old name here because it is referenced from outside
+    # this class; what changed is that it is no longer a SECOND definition of
+    # the same number. /profile writes the same columns and reads the same
+    # constant.
     MAX_FIRST_NAME = Studio::FIRST_NAME_MAX_LENGTH
 
+    # The WHOLE-ANSWER cap (Studio::FULL_NAME_MAX_LENGTH) — what this endpoint
+    # actually bounds. It is a different question from the one above and now has
+    # a different name: the field asks for a name and people type a full one, so
+    # the string arriving here is first name PLUS surname, and measuring it with
+    # the per-field number stored 40 characters of a 41-character name and
+    # handed the account back a misspelled surname.
+    MAX_FULL_NAME = Studio::FULL_NAME_MAX_LENGTH
+
     # POST /onboarding/first_name
     #
     # Writes users.first_name, and backfills `name` when it is blank so the
     # display-name chain has something better than an email prefix to show.
     def first_name
-      value = params[:first_name].to_s.strip.gsub(/\s+/, " ").first(MAX_FIRST_NAME)
+      value = params[:first_name].to_s.strip.gsub(/\s+/, " ")
 
       if value.blank?
-        return render json: { ok: false, error: "Enter your first name, or skip for now." },
-                      status: :unprocessable_entity
+        return refuse("Enter your first name, or skip for now.")
+      end
+
+      # DERIVE FIRST, THEN GUARD, THEN WRITE. The halves are what the length
+      # rules are about, so they are computed once and both the guard and the
+      # write read the same hash — a guard measuring a second derivation could
+      # pass over values the write then stored.
+      attrs = name_columns(value)
+
+      if (message = length_refusal(value, attrs))
+        return refuse(message)
       end
 
       rescue_and_log(target: current_user) do
@@ -63,7 +81,7 @@ module Studio
         # never self-healed, because set_name_parts is gated on `name_changed?`
         # and no later save sees a name change. So the derivation comes to the
         # writer instead: Studio::NameParts is the same rule the callback runs.
-        attrs = name_columns(value)
+        # (`attrs` was derived above, so the guard and this write cannot disagree.)
         attrs[:name] = value if current_user.name.blank?
         current_user.update_columns(attrs)
 
@@ -86,6 +104,50 @@ module Studio
 
     private
 
+    # The one refusal shape both guards answer with. The modal renders `error`
+    # inline and leaves the field filled, so a refusal here is a correction the
+    # person can act on rather than a dead end.
+    def refuse(message)
+      render json: { ok: false, error: message }, status: :unprocessable_entity
+    end
+
+    # WHY THIS REFUSES INSTEAD OF TRUNCATING, which is the product decision this
+    # endpoint used to make silently and badly.
+    #
+    # `.first(cap)` on a name is not a cap, it is a rewrite: it accepted the
+    # answer, stored something the person never typed, and reported success.
+    # "Bartholomew Fitzwilliam Montgomery-Smythe" came back as
+    # "…Montgomery-Smyth" — plausible enough to miss, which is the worst kind of
+    # wrong for a name. Raising the number alone only moves that cliff one
+    # character further out; a bound that rewrites its input is the defect at
+    # any value. So the bound goes up (MAX_FULL_NAME now fits a real full name)
+    # AND anything past it is refused with a sentence saying so.
+    #
+    # BOTH LENGTHS ARE CHECKED, and they are independent rather than redundant.
+    # The whole answer becomes `name`; each half becomes its own column that
+    # /profile caps separately. A single 60-character word passes the first rule
+    # and would still land a `first_name` /profile silently shortens on the next
+    # save — the very drift the two constants exist to prevent — so the halves
+    # are measured too.
+    #
+    # UNREACHABLE FROM THE MODAL, ON PURPOSE. The partial's input carries the
+    # same MAX_FULL_NAME as its maxlength, so the browser stops a typist first.
+    # This is the server being the real bound, for a direct POST or for a host
+    # that passes a larger `max_length` local.
+    #
+    # Returns the message to refuse with, or nil to proceed.
+    def length_refusal(value, attrs)
+      if value.length > MAX_FULL_NAME
+        return "Please shorten that to #{MAX_FULL_NAME} characters or fewer."
+      end
+
+      if attrs.values.compact.any? { |part| part.length > MAX_FIRST_NAME }
+        return "Please keep each name to #{MAX_FIRST_NAME} characters or fewer."
+      end
+
+      nil
+    end
+
     # The name halves to write, derived exactly as the host's set_name_parts
     # would derive them from the same string.
     #

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

@@ -12,10 +12,23 @@
   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 40; the server stays the real bound)
+    max_length  — (default Studio::FULL_NAME_MAX_LENGTH; the server stays the
+                  real bound, and it REFUSES past that rather than truncating,
+                  so a host raising this makes the endpoint answer 422 rather
+                  than store a name nobody typed)
     progress    — [current, total] to render the segmented pill, or nil for none
     modal_store — Alpine store name (default "modals"; the living style guide
                   mounts its own page-scoped host and passes "dsModals")
@@ -37,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, 40)
+  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) || {}; },
@@ -98,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 %>
@@ -131,8 +161,13 @@
     </button>
   </form>
 
-  <button type="button" @click="skip()" :disabled="submitting"
-          class="mt-3 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
-    Skip for now
-  </button>
+  <%# Gone entirely when required — see the × above for why offering it there
+      would promise a way past a wall that does not move. Omitted rather than
+      hidden, for the same reason the × is resolved server-side. %>
+  <% unless required %>
+    <button type="button" @click="skip()" :disabled="submitting"
+            class="mt-3 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Skip for now
+    </button>
+  <% end %>
 </div>

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

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

data/lib/studio/version.rb

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

data/lib/studio.rb

@@ -407,17 +407,46 @@ module Studio
   # later session may ask again. That is the whole reason this is not a column.
   FIRST_NAME_SKIP_SESSION_KEY = :onboarding_skipped_first_name
 
-  # How long a first name may be. ONE constant because users.first_name is
-  # written from TWO surfaces — the onboarding step (seconds after signup) and
-  # /profile (any time after) — and rendered by a third, the profile form's
-  # maxlength. Two independently-correct caps that disagreed would let onboarding
-  # accept a name /profile then refused to save, a bug with no obvious owner.
+  # How long ONE name field may be — users.first_name, and users.last_name where
+  # a host carries it. PER FIELD, which is the only thing this number has ever
+  # measured: /profile caps each of the two inputs with it, and the profile
+  # form's maxlength renders it. Two independently-correct caps that disagreed
+  # would let one surface accept a name another then refused to save, a bug with
+  # no obvious owner.
   #
   # Keeping it here rather than on either controller also keeps the VIEW off a
   # controller constant: the form needs the number, and a view reaching into
   # Studio::ProfilesController to get it would couple the two for no reason.
   FIRST_NAME_MAX_LENGTH = 40
 
+  # How long a WHOLE typed answer may be — one string holding a full name, which
+  # the onboarding step stores as users.name and SPLITS into the two halves
+  # above (Studio::NameParts).
+  #
+  # A SECOND CONSTANT BECAUSE THIS IS A SECOND QUESTION. Onboarding asked the
+  # per-field number for a whole-answer bound, and the two readings were both
+  # defensible at their own call site: "Bartholomew Fitzwilliam
+  # Montgomery-Smythe" is 41 characters, so it stored 40 and handed the account
+  # back its own surname misspelled — "Montgomery-Smyth". Nothing was wrong in
+  # either controller alone; the number was answering two questions with one
+  # value. Giving the whole-answer bound its own name makes that borrow
+  # unwriteable rather than merely discouraged.
+  #
+  # DERIVED, NOT PICKED. It is the longest answer whose two halves BOTH still
+  # fit the per-field cap — first(40) + a space + last(40) — so onboarding can
+  # never accept a name /profile would later shorten, which is the drift
+  # FIRST_NAME_MAX_LENGTH exists to prevent. Raising the per-field cap moves
+  # this one with it, by construction.
+  #
+  # NOT BOUNDED BY THE COLUMN. Measured 2026-09-06 across all six consumer
+  # databases (mcritchie-studio, turf-monster and mcritchie-industries, prod and
+  # QA): every one of `name`, `first_name` and `last_name` is an unbounded
+  # `character varying` — character_maximum_length NULL, no CHECK constraint, no
+  # model length validation. So this cap is a product decision start to finish,
+  # not a column ceiling, and raising it cannot trade a truncation for a
+  # PG::StringDataRightTruncation.
+  FULL_NAME_MAX_LENGTH = (FIRST_NAME_MAX_LENGTH * 2) + 1
+
   # The shared rule for "does this account still owe us a first name?" — the one
   # piece of onboarding logic every app agrees on. Hosts compose it into their own
   # flow rather than re-deriving it (turf's OnboardingFlow calls straight through).

metadata

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