studio-engine 0.128.0 → 0.129.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3abb879eda738b9ebe2d7ba3aa0c7400e4e335eccdf5775c654b8810db8f96e2
-  data.tar.gz: 440cde0469a8d8d8905a7250da40fbd2576e3f9b5a6b9c2a68036368486759cc
+  metadata.gz: ed5be658c4ba3547da2294995bc7c13e7181bccbd5710fd07d84c7fb0af95a2c
+  data.tar.gz: d48d2fbebaee5b7e33a22c16bc2f6d40b1afc161d0dacb6eb42d51a8e36cd4fe
 SHA512:
-  metadata.gz: e73f00423880d25f49324ed5ef4c3c152caf27f7bc144815ea4928242933e675c1e879393bdd2777d40659ddb472ddae8c23eb3ad9f0ae2f3f9e25e04e443033
-  data.tar.gz: '09e30076328185194bbd9773a059c1ee3a984e60e2376ff08aaf0f785ee3888c85e056dbffc38c69fa3477d03adff476beb7832bb60c974d2dc5f010a42fbc5d'
+  metadata.gz: 99e6c74a4c11320449ee3b58d89b56712067f02bc6b2228d602f4ec942b06617b77960e05d8d29dc03dda95e5c92868d4da18bd67922494fbe84abb40b6e308f
+  data.tar.gz: 353b2199a4a651ee65a0d00c448c8273731b9a4bebbb5c5eff97fe97ba57177ae8f1a47ab0fa6d4b9f2f99856c46a8992c62c84d4319db28116b0dd557c05adf

data/CHANGELOG.md

@@ -4,6 +4,51 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.129.0 — 2026-11-05
+
+### Changed
+
+- **The `/admin/style` copy is trimmed.** Each section keeps at most one short sentence of intro,
+  and the notes under specimens are cut the same way. Controls, specimens and error messages are
+  unchanged. The hidden copy-to-agent references on the modal cards are unchanged too. The Tricks
+  section is not part of this trim.
+
+- **A bad or missing CSRF token on a JSON or `Accept: */*` request is now a 422 with no ErrorLog
+  row, on every controller using `Studio::ErrorHandling`.** The catch-all answered JSON 500 and
+  wrote a row. It now answers `422 {error, reason: "invalid_token"}` in every environment, and a
+  test on such a route that asserted `assert_raises(ActionController::InvalidAuthenticityToken)`
+  now asserts the 422. An HTML form is unchanged: the redirect home with its alert, and the row.
+
+### Fixed
+
+- **A theme toggle is one crossfade.** `$store.theme.toggle()` added `theme-transition` for 300ms, and
+  in a host with that rule about 210 elements ran their own 200ms transition while gradients and
+  the page background snapped. It now flips the whole page in one 160ms view transition with no
+  movement. No element runs its own transition, and no named element keeps its own picture. A
+  browser with no view transitions, a reduced-motion reader, and a toggle during a Turbo visit
+  flip at once, and the visit's motion plays on. Under the crossfade the class, the store value
+  and localStorage change together in the transition's callback, so all three still read the old
+  theme for up to a frame after the call: a caller that reads them in the same tick must wait.
+  `toggleTheme` and `storedTheme` are no longer exported, and the store starts from the root's
+  class. `$store.theme.set("dark" | "light")` is the one setter, and `toggle()` stays. The
+  `theme-transition` rule in a host is now dead. Measured on the hub's `/deployments`, signed in,
+  2100 elements, Metal GPU: the largest step between frames fell from 35-65% of the brightness
+  change to 11%, and element transitions started by one toggle from about 1170 to 0.
+  Chromium sends every pointer hit to the root during a view transition, for about 160ms. A pointer
+  that stops in that time can show no `:hover` until it moves again, and a second click on the toggle
+  is dropped. A host spec that toggles and then hovers must wait for `data-theme-flip` to clear.
+
+- **The agent chat at phone width.** Measured at 390x844 and 320x568, light and dark:
+  - No blank tail. A turn's `sr-only` name escaped the log, which had no positioned ancestor,
+    and stretched the document to 1933px where `main` ended at 977px. The log is now
+    `position: relative`.
+  - The newest turn shows above the composer, on load and after a new turn. The page scrolls
+    the thread's end clear of the stuck composer; not for an empty thread, not for a reader
+    scrolled up in the log or the page, and not during a hold, when it waits for the button
+    to be let go.
+  - A stale page says so. A refused token reads "This page has expired" with a reload hint on
+    the voice line and the typed error, and a refused send keeps its words in the box.
+
 ## 0.128.0 — 2026-11-05
 
 ### Fixed

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

@@ -799,6 +799,59 @@ html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-n
 @keyframes pt-unfold-bottom { from { opacity: 0; transform: perspective(1200px) translateY(100%) rotateX(-90deg); } }
 @keyframes pt-unfold-top { from { opacity: 0; transform: perspective(1200px) translateY(-100%) rotateX(90deg); } }
 
+/* -- The theme flip --------------------------------------------------------
+   $store.theme.set (studio/alpine_stores) puts data-theme-flip on the root for one
+   flip. The whole page changes in one crossfade, whatever its size: no element
+   runs its own transition, no named element keeps its own picture, and nothing
+   here moves. !important because a wildcard pseudo-element is weaker than the
+   rules above and than a host's rule for a name. A pointer's click during the
+   crossfade hits the root, not the page (Chromium ignores pointer-events on these
+   pseudo-elements); a key press still reaches the focused toggle. */
+html[data-theme-flip],
+html[data-theme-flip] *,
+html[data-theme-flip] *::before,
+html[data-theme-flip] *::after {
+  transition: none !important;
+}
+
+/* The root keeps its name: it is the one picture. */
+html[data-theme-flip] * {
+  view-transition-name: none !important;
+}
+
+html[data-theme-flip]::view-transition {
+  background: none !important;
+}
+
+html[data-theme-flip]::view-transition-group(*) {
+  animation: none !important;
+}
+
+html[data-theme-flip]::view-transition-old(*),
+html[data-theme-flip]::view-transition-new(*) {
+  mix-blend-mode: plus-lighter !important;
+}
+
+html[data-theme-flip]::view-transition-old(*) {
+  animation: vt-theme-out 160ms linear both !important;
+}
+
+html[data-theme-flip]::view-transition-new(*) {
+  animation: vt-theme-in 160ms linear both !important;
+}
+
+@keyframes vt-theme-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes vt-theme-in {
+  from {
+    opacity: 0;
+  }
+}
+
 /* Turbo's progress bar is the slow-load feedback under no-preview (the old
    page holds until the fresh response). Theme it so every app's bar matches
    its brand instead of Turbo's default. The fallback (#0076ff, Turbo's own

data/app/controllers/concerns/studio/error_handling.rb

@@ -7,6 +7,8 @@ module Studio
     # methods only.
     include Studio::SessionDrift
 
+    INVALID_TOKEN_MESSAGE = "This page has expired. Reload it, then try again."
+
     included do
       # ORDER IS LOAD-BEARING — ActiveSupport::Rescuable resolves handlers with
       # `reverse_each`, so the LAST matching rescue_from registered wins. The
@@ -19,6 +21,7 @@ module Studio
       rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
       # A string, so including this concern does not load the model concern.
       rescue_from "Sluggable::SlugRefused", with: :handle_slug_refused
+      rescue_from ActionController::InvalidAuthenticityToken, with: :handle_invalid_authenticity_token
 
       before_action :require_authentication
       after_action :track_user_session
@@ -271,6 +274,20 @@ module Studio
       end
     end
 
+    # Layer 1: a bad or missing CSRF token on a fetch is a 422 the page can read, with
+    # no ErrorLog row: anyone can send one, and the catch-all answered it 500.
+    #
+    # HTML stays with the catch-all on purpose. Its redirect home hands a stale login or
+    # magic-link form a fresh token and a way on, where public/422.html is a dead end
+    # with no link (Back shows the same stale form). Its row is what the health report
+    # sees when a session config breaks every form at once.
+    def handle_invalid_authenticity_token(exception)
+      respond_to do |format|
+        format.json { render json: { error: INVALID_TOKEN_MESSAGE, reason: "invalid_token" }, status: :unprocessable_entity }
+        format.any { handle_unexpected_error(exception) }
+      end
+    end
+
     # Layer 1: Catch-all for unexpected errors — log + friendly response.
     # Skips logging if rescue_and_log already captured it.
     def handle_unexpected_error(exception)

data/app/javascript/studio/agent_chat.js

@@ -18,6 +18,12 @@
 //            until the app answers 201; a refusal shows its reason above them.
 //   FOLLOW   the thread stays at its end while the reader is within FOLLOW_PX of
 //            it, and always after their own send (the hub's chat_follow rule).
+//   REVEAL   the composer sticks over the window's bottom, so on a short window the
+//            thread's end sits under it. On load and after a new turn the page
+//            scrolls that end clear of the composer, with the same manners as
+//            FOLLOW: not for an empty thread, not for a reader who scrolled the page
+//            up (revealFollowing, until their own send), and never during a hold,
+//            when it waits for the button to be let go.
 //   REFRESH  the public hook for code outside the chat (studio/agent_chat_voice, a
 //            host's own composer): dispatch studio:agent-chat:refresh on the
 //            chat's section, optionally with {detail: {turn}}, a turn the app
@@ -43,6 +49,11 @@ export const IDLE_MS = 30000
 export const OFFLINE_MS = 15000
 export const FOLLOW_PX = 20
 export const LIMIT = 50
+export const REVEAL_GAP_PX = 12
+export const INVALID_TOKEN = "invalid_token"
+export const EXPIRED_MESSAGE = "This page has expired. Copy your message, then reload the page to send it."
+export const RECORDER_STATE_EVENT = "studio:voice-recorder:state"
+const HOLDING = "[data-voice-recorder-state='recording'],[data-voice-recorder-state='starting']"
 export const REFRESH_EVENT = "studio:agent-chat:refresh"
 export const SENT_EVENT = "studio:agent-chat:sent"
 const UNSETTLED = new Set(["pending", "typing"])
@@ -102,6 +113,12 @@ export function isFollowing(log, px = FOLLOW_PX) {
   return log.scrollHeight - log.clientHeight - log.scrollTop <= px
 }
 
+// How many pixels of the thread's end the composer (or the window's bottom) hides;
+// zero or less when it is clear of both. Rects are the elements' own.
+export function coveredPx(endRect, composerRect, windowHeight) {
+  return endRect.bottom - Math.min(composerRect.top, windowHeight)
+}
+
 // The page's authenticity token: the form's own field, else the csrf meta.
 export function csrfToken(form, doc = globalThis.document) {
   const field = form && form.querySelector("input[name='authenticity_token']")
@@ -138,13 +155,57 @@ export function mountAgentChat(root, {
   const soul = root.dataset.agentChatSoul
   const name = root.dataset.agentChatName || "The agent"
 
-  const state = { turns: [], pending: false, waitingSince: null, offline: false, inFlight: false, pollAgain: false, sending: false, timer: null, alive: true, following: true }
+  const state = { turns: [], pending: false, waitingSince: null, offline: false, inFlight: false, pollAgain: false, sending: false, timer: null, alive: true, following: true, revealFollowing: true, revealOwed: false }
 
   const onScroll = () => { state.following = isFollowing(log) }
   log.addEventListener("scroll", onScroll, { passive: true })
 
   function toEnd() { log.scrollTop = log.scrollHeight }
 
+  // The last thing in the thread's column above the composer that is showing.
+  function threadEnd() {
+    return [offlineNote, typing].find((el) => el && el.hidden === false) || log
+  }
+
+  function windowHeight() {
+    return doc && doc.documentElement ? doc.documentElement.clientHeight : 0
+  }
+
+  function covered() {
+    const end = threadEnd()
+    if (!form || !end.getBoundingClientRect || !form.getBoundingClientRect) return 0
+    return coveredPx(end.getBoundingClientRect(), form.getBoundingClientRect(), windowHeight())
+  }
+
+  // scrollIntoView, not window.scrollBy: a host may scroll an inner container. The
+  // margin is what the composer takes off the bottom of the window once it sticks:
+  // its height and its sticky bottom, not its top now, because a composer lower down
+  // the page is not stuck until this scroll has run. Instant, so a host's smooth
+  // scrolling cannot leave the page moving when a hold begins.
+  function revealEnd() {
+    if (root.querySelector(HOLDING)) { state.revealOwed = true; return }
+    state.revealOwed = false
+    if (!state.turns.length || covered() <= 0) return
+    const end = threadEnd()
+    const stuckAt = parseFloat(globalThis.getComputedStyle?.(form).bottom) || 0
+    end.style.scrollMarginBottom = `${form.getBoundingClientRect().height + stuckAt + REVEAL_GAP_PX}px`
+    end.scrollIntoView({ block: "end", behavior: "instant" })
+    end.style.scrollMarginBottom = ""
+  }
+
+  // A scroll of the page or a host's container says whether the reader is still at
+  // the thread's end. The log's own scroll, the box's and the picker's say nothing:
+  // only something that holds the chat can move it. A reveal passes this too, and
+  // ends there.
+  const onPageScroll = (event) => {
+    if (!event.target || !event.target.contains || !event.target.contains(root)) return
+    state.revealFollowing = covered() <= FOLLOW_PX
+  }
+
+  const onRecorderState = () => {
+    if (state.revealOwed && !root.querySelector(HOLDING) && state.following && state.revealFollowing) revealEnd()
+  }
+
   function setOffline(offline) {
     state.offline = offline
     if (offlineNote) offlineNote.hidden = !offline
@@ -185,7 +246,10 @@ export function mountAgentChat(root, {
     const waiting = state.pending || state.turns.some((turn) => !settled(turn))
     if (typing) typing.hidden = !waiting
     if (phase) phase.dataset.phase = typingPhase(state.turns)
-    if (follow) toEnd()
+    if (follow) {
+      toEnd()
+      if (state.revealFollowing) revealEnd()
+    }
   }
 
   function schedule() {
@@ -233,6 +297,7 @@ export function mountAgentChat(root, {
       state.turns = mergeTurns(state.turns, [turn])
       state.pending = turn.status !== "held"
       state.following = true
+      state.revealFollowing = true
       state.waitingSince = now()
       setOffline(false)
       render()
@@ -272,6 +337,7 @@ export function mountAgentChat(root, {
         state.turns = mergeTurns(state.turns, [data.turn])
         state.pending = data.turn.status !== "held"
         state.following = true
+        state.revealFollowing = true
         setOffline(false)
         render()
         toEnd()
@@ -281,7 +347,7 @@ export function mountAgentChat(root, {
         clearTimer(state.timer)
         state.timer = setTimer(poll, POLL_MS)
       } else {
-        showError(data.error || `Couldn't send that to ${name}. Try again.`)
+        showError(data.reason === INVALID_TOKEN ? EXPIRED_MESSAGE : data.error || `Couldn't send that to ${name}. Try again.`)
         if (status) status.textContent = ""
       }
     } catch (_error) {
@@ -313,7 +379,10 @@ export function mountAgentChat(root, {
   input && input.addEventListener("keydown", onKeydown)
   retry && retry.addEventListener("click", onRetry)
   root.addEventListener(REFRESH_EVENT, onRefresh)
+  root.addEventListener(RECORDER_STATE_EVENT, onRecorderState)
   doc && doc.addEventListener && doc.addEventListener("visibilitychange", onVisible)
+  // Scroll events do not bubble; capture hears the page's and any container's.
+  doc && doc.addEventListener && doc.addEventListener("scroll", onPageScroll, { capture: true, passive: true })
   root.dataset.agentChatReady = "true"
   poll()
 
@@ -330,7 +399,9 @@ export function mountAgentChat(root, {
       input && input.removeEventListener("keydown", onKeydown)
       retry && retry.removeEventListener("click", onRetry)
       root.removeEventListener(REFRESH_EVENT, onRefresh)
+      root.removeEventListener(RECORDER_STATE_EVENT, onRecorderState)
       doc && doc.removeEventListener && doc.removeEventListener("visibilitychange", onVisible)
+      doc && doc.removeEventListener && doc.removeEventListener("scroll", onPageScroll, { capture: true })
       delete root.dataset.agentChatReady
     }
   }

data/app/javascript/studio/agent_chat_voice.js

@@ -50,6 +50,8 @@ export const MESSAGES = {
   notConfigured: "Voice isn't set up on this app yet, so I can't hear recordings. Type instead for now.",
   rateLimited: "That's a lot of voice messages in a row. Wait a moment, then hold to talk again.",
   signedOut: "Sign in again to talk.",
+  expired: "This page has expired. Reload it, then hold to talk again.",
+  expiredSend: "This page has expired. Copy your words from the box, then reload the page to send them.",
   unavailable: "I couldn't transcribe that just now. Try again in a moment.",
   failed: "That recording didn't go through. Try again.",
   offline: "Can't reach the server right now. Try again in a moment.",
@@ -65,11 +67,19 @@ export function retryHint(seconds) {
   return ` Try again in ${minutes} minute${minutes === 1 ? "" : "s"}.`
 }
 
+// A refused CSRF token: the engine's own answer (Studio::ErrorHandling), or Rails'
+// {status: 422, error: "Unprocessable Content"} from a host that re-raises it. Retrying
+// on this page can never pass, and Rails' words mean nothing to a person.
+export function tokenRefused(status, body = {}) {
+  return status === 422 && !!body && (body.reason === "invalid_token" || body.status === 422)
+}
+
 // What POST /voice/takes's refusal means on the page: {state, message}.
 // `body` is the parsed JSON (or {}); `retryAfter` the header, if any.
 export function refusalFor(status, body = {}, retryAfter = null) {
   const said = body && typeof body.error === "string" && body.error.trim() ? body.error.trim() : null
   if (status === 401) return { state: "refused", message: MESSAGES.signedOut }
+  if (tokenRefused(status, body)) return { state: "refused", message: MESSAGES.expired }
   if (status === 429) {
     return { state: "rate_limited", message: MESSAGES.rateLimited + retryHint(retryAfter ?? (body && body.retry_after)) }
   }
@@ -235,6 +245,10 @@ export function mountAgentChatVoice(root, {
       return
     }
     keepWords(answer.text)
+    if (tokenRefused(response.status, data)) {
+      say("refused", MESSAGES.expiredSend)
+      return
+    }
     const reason = typeof data.error === "string" && data.error ? `${data.error} ` : ""
     say(response.status === 429 ? "rate_limited" : "failed", `${reason}${MESSAGES.notSent(name)}`)
   }
@@ -255,7 +269,9 @@ export function mountAgentChatVoice(root, {
     if (!response.ok || typeof body.text !== "string" || !body.text.trim()) {
       const retryAfter = response.headers && response.headers.get ? response.headers.get("Retry-After") : null
       const { state, message } = response.ok ? { state: "no_speech", message: MESSAGES.noSpeech } : refusalFor(response.status, body, retryAfter)
-      say(state, message)
+      // A reload clears the box, so words already in it get the copy-first line.
+      const inBox = form && form.querySelector("[data-agent-chat-input]")?.value.trim()
+      say(state, inBox && tokenRefused(response.status, body) ? MESSAGES.expiredSend : message)
       return
     }
     await send(body)

data/app/javascript/studio/alpine_stores.js

@@ -1,5 +1,5 @@
 // studio/alpine_stores: the Alpine stores every host body binds to,
-// $store.theme and $store.devMode, and the theme value and toggle behind them.
+// $store.theme and $store.devMode, and the theme setter behind them.
 //
 // WHY THIS IS ITS OWN ENTRY POINT. Every host's <body> says
 // :class="{ 'dev-mode': $store.devMode }", and the engine's theme toggle reads
@@ -27,36 +27,92 @@
 // inline, nonced script in the head: it must run before the stylesheet paints,
 // which no deferred module can.
 
-// The stored theme, dark unless the reader chose light.
-export function storedTheme(storage) {
-  return storage.getItem('theme') || 'dark'
+// The theme the root's class shows. The store starts here, not from storage: the pre-paint script
+// reads storage by its own rule, and it decides what the reader already sees.
+function classTheme(root) {
+  return root.classList.contains('dark') ? 'dark' : 'light'
 }
 
-// Flips the root's `dark` class under a short transition class, stores the
-// result, and answers it.
-export function toggleTheme(root, storage, later) {
-  root.classList.add('theme-transition')
-  root.classList.toggle('dark')
-  var value = root.classList.contains('dark') ? 'dark' : 'light'
-  storage.setItem('theme', value)
-  later(function () { root.classList.remove('theme-transition') }, 300)
-  return value
+// A visit owns the view transition. A second one would skip Turbo's and cut its motion short, so
+// a toggle during a visit flips at once. data-turbo-visit-direction spans a visit; data-page-transition
+// also spans a full load's arrival (studio/page_transitions).
+function visiting(root) {
+  return root.dataset.turboVisitDirection !== undefined || root.dataset.pageTransition !== undefined
+}
+
+function canCrossfade(env) {
+  if (!env.doc || typeof env.doc.startViewTransition !== 'function') return false
+  if (env.win.matchMedia('(prefers-reduced-motion: reduce)').matches) return false
+  return !visiting(env.root)
+}
+
+// The theme store. set(value) is the one setter: the root class, the store value and localStorage
+// change together, in one step, so they agree at every moment. Under a crossfade that step runs
+// in the transition's callback, after the old picture: for up to a frame after set() all three
+// still read the old theme. The pre-paint script is the one writer that cannot use this: it runs
+// before any module does.
+//
+// data-theme-flip is on the root from before the old picture until the crossfade ends. engine.css
+// reads it: the page is one picture, no element runs its own transition, and the page-transition
+// motions lose. Without a crossfade it stays until the styles of the new theme have been computed.
+export function themeStore(env) {
+  var root = env.root
+  var flips = 0
+  var wanted = null // the theme asked for, while its step has not run
+
+  return {
+    value: classTheme(root),
+    get isDark() { return this.value === 'dark' },
+    set: function (value) {
+      if (value !== 'dark' && value !== 'light') return
+      if (value === wanted) return
+      var self = this
+      var commit = function () {
+        root.classList.toggle('dark', value === 'dark')
+        self.value = value
+        // A full or blocked storage must not throw past the instant path's settle and strand data-theme-flip.
+        try { env.storage.setItem('theme', value) } catch (_) { /* the page still flips; the choice is not kept */ }
+      }
+      // Nothing to show, but the three may have drifted: a host can write the class directly.
+      if (wanted === null && value === classTheme(root)) return commit()
+
+      var mine = ++flips
+      // Only the newest flip acts, so a late callback cannot undo a later choice.
+      var apply = function () {
+        if (mine !== flips) return
+        wanted = null
+        commit()
+      }
+      var settle = function () {
+        if (mine === flips) delete root.dataset.themeFlip
+      }
+      wanted = value
+      root.dataset.themeFlip = ''
+      if (!canCrossfade(env)) {
+        apply()
+        if (env.win) env.win.getComputedStyle(root).color // no transition starts from these styles
+        return env.later(settle, 0)
+      }
+      var transition = env.doc.startViewTransition(apply)
+      // A skipped transition rejects ready; a throw in apply rejects the other two.
+      transition.finished.then(settle, settle)
+      transition.ready.catch(function () {})
+      transition.updateCallbackDone.catch(function () {})
+    },
+    toggle: function () {
+      this.set((wanted || classTheme(root)) === 'dark' ? 'light' : 'dark')
+    }
+  }
 }
 
 // Registers each store Alpine does not already have. env carries what the
-// stores read and write: { storage, root, later }.
+// stores read and write: { storage, root, later, doc, win }.
 export function registerStudioStores(Alpine, env) {
   if (Alpine.store('devMode') === undefined) {
     Alpine.store('devMode', env.storage.getItem('devMode') === 'true')
   }
   if (Alpine.store('theme') === undefined) {
-    Alpine.store('theme', {
-      value: storedTheme(env.storage),
-      get isDark() { return this.value === 'dark' },
-      toggle: function () {
-        this.value = toggleTheme(env.root, env.storage, env.later)
-      }
-    })
+    Alpine.store('theme', themeStore(env))
   }
 }
 
@@ -72,7 +128,9 @@ export function installStudioStores(doc, win) {
     registerStudioStores(win.Alpine, {
       storage: win.localStorage,
       root: doc.documentElement,
-      later: function (fn, ms) { win.setTimeout(fn, ms) }
+      later: function (fn, ms) { win.setTimeout(fn, ms) },
+      doc: doc,
+      win: win
     })
   })
 }

data/app/views/registrations/new.html.erb

@@ -81,9 +81,10 @@
 
       <% if Studio.auth_method?(:google) %>
         <% if email_signup %>
-          <div class="relative my-6">
-            <div class="absolute inset-0 flex items-center"><div class="w-full border-t border-subtle"></div></div>
-            <div class="relative flex justify-center text-sm"><span class="bg-surface px-3 text-secondary">or</span></div>
+          <div class="flex items-center gap-3 my-6 text-sm">
+            <div class="flex-1 border-t border-subtle"></div>
+            <span class="text-secondary">or</span>
+            <div class="flex-1 border-t border-subtle"></div>
           </div>
         <% end %>
 

data/app/views/sessions/new.html.erb

@@ -81,9 +81,10 @@
 
       <% if Studio.auth_method?(:google) %>
         <% if Studio.password_login_available? || Studio.auth_method?(:magic_link) %>
-          <div class="relative my-6">
-            <div class="absolute inset-0 flex items-center"><div class="w-full border-t border-subtle"></div></div>
-            <div class="relative flex justify-center text-sm"><span class="bg-surface px-3 text-secondary">or</span></div>
+          <div class="flex items-center gap-3 my-6 text-sm">
+            <div class="flex-1 border-t border-subtle"></div>
+            <span class="text-secondary">or</span>
+            <div class="flex-1 border-t border-subtle"></div>
           </div>
         <% end %>
 

data/app/views/studio/agent_chat/_chat.html.erb

@@ -42,8 +42,9 @@
     <div class="flex flex-col gap-3 min-w-0" data-agent-chat-cards data-test="agent-chat-cards"><%= cards %></div>
   <% end %>
   <div class="flex flex-col gap-3 min-w-0">
+    <%# relative: a turn's sr-only name is absolutely positioned. With no positioned ancestor it escapes this scroller, is not clipped by it, and stretches the document by the thread's whole scrolled height. %>
     <div role="log" aria-live="polite" aria-label="Conversation with <%= name %>"
-         class="flex flex-col gap-4 px-1 py-2 overflow-y-auto overscroll-contain max-h-[60vh] min-w-0"
+         class="relative flex flex-col gap-4 px-1 py-2 overflow-y-auto overscroll-contain max-h-[60vh] min-w-0"
          data-agent-chat-log data-test="agent-chat-messages">
       <p class="hidden only:block text-center text-secondary text-sm py-6" data-test="agent-chat-empty"><%= empty.presence || "Say hello to #{name}." %></p>
     </div>

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

@@ -8,9 +8,7 @@
 <section id="components" class="space-y-6" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
   <div class="space-y-1">
     <h2 class="type-h3 text-heading">Components</h2>
-    <p class="text-muted text-sm max-w-2xl">
-      The engine's ViewComponent classes, one preview per state, in the component gallery.
-    </p>
+    <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
   </div>
 
   <% if Studio.lookbook_mounted? %>

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

@@ -11,7 +11,7 @@
 <section class="space-y-4" data-test="style-glass">
   <div>
     <h3 class="type-h4 text-heading">Glass</h3>
-    <p class="text-sm text-secondary mt-1">Translucent surfaces and the floating sidebar. Each is opt-in, so an app moves only when it asks.</p>
+    <p class="text-sm text-secondary mt-1">Each one is opt-in per app.</p>
   </div>
   <div class="grid gap-4 md:grid-cols-2">
     <%= render layout: "style/specimen",

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

@@ -94,15 +94,7 @@
          style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
   <div class="space-y-1">
     <h2 class="type-h3 text-heading"><%= Studio.app_name %></h2>
-    <p class="text-muted text-sm max-w-2xl">
-      This app&rsquo;s own modals, contributed by
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">app/views/style/host/_modals.html.erb</code>.
-      Every section above belongs to the engine and is inherited; everything
-      here belongs to <%= Studio.app_name %> and ships with it. These specimens
-      drive the app&rsquo;s <strong>real</strong>
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">$store.modals</code>
-      host, so the card that opens here is the card that opens in production.
-    </p>
+    <p class="text-muted text-sm max-w-2xl">This app&rsquo;s own modals, from <code class="font-mono text-2xs">app/views/style/host/_modals.html.erb</code>.</p>
   </div>
 
   <%# The app's content. Reached only when it resolves - style/index.html.erb

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

@@ -156,15 +156,7 @@
          @age-verified.window="$store.dsModals.open('entry-confirmed', { txSignature: null, lobbyUrl: null, seedsEarned: 0 })">
   <div class="space-y-1">
     <h2 class="type-h3 text-heading">Modals</h2>
-    <p class="text-muted text-sm">
-      The shared modal host and the reusable modal partials, ported from Turf
-      Monster into the engine. Each tile is a <strong>visual representation, not
-      to scale</strong> &mdash; <strong>click a whole card</strong> to open the real
-      modal (Enter/Space work too). The header <strong>Copy</strong> yields an
-      agent-ready reference you can paste into a chat; option <strong>toggles</strong>
-      configure the modal before you open it; and the card that matches the open
-      modal <strong>glows</strong>.
-    </p>
+    <p class="text-muted text-sm">Click a card to open the real modal.</p>
   </div>
 
   <%# ---- The section's own modal host (dsModals) --------------------------
@@ -462,22 +454,7 @@
   <section id="modals-auth" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">Auth</h3>
-      <p class="text-muted text-sm">
-        <strong>The engine ships no sign-in card.</strong> A sign-in modal is a
-        product decision &mdash; which methods, what terms, whose legal copy
-        &mdash; so each app owns its own and cards it on <em>its</em> section of
-        this guide, against the partial that actually renders in production.
-        What the engine owns is the <strong>pieces</strong> that card is built
-        from, and they are below.
-      </p>
-      <p class="text-muted text-sm">
-        Until 2026-09-09 this section held a full auth modal
-        (<code class="font-mono text-2xs">style/modals/_auth</code>). It was a
-        <strong>mirror</strong> of turf-monster&rsquo;s card, and it drifted:
-        reviewing it told you about a copy nobody shipped. It is gone, and these
-        two fragments &mdash; which it happened to be the only renderer of &mdash;
-        now stand on their own.
-      </p>
+      <p class="text-muted text-sm">The engine ships no sign-in card, only these pieces.</p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
       <%# email field — the one piece every app's auth card renders. %>
@@ -524,31 +501,7 @@
   <section id="modals-profile" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">Profile</h3>
-      <p class="text-muted text-sm">
-        Who the account IS &mdash; the name it goes by, the birthday that decides
-        eligibility, and the picture. The first three cards are asked at signup
-        (a host walks them post-auth), the last three are reachable forever from
-        the profile page; all six are engine primitives.
-      </p>
-      <p class="text-muted text-sm">
-        <strong>Birthday and Age gate are one flow, deliberately split into two
-        cards.</strong> The birthday card ASKS; when the answer is too young the
-        age-gate card ANSWERS, carrying a countdown to the day they qualify, a way
-        to watch instead, and a way back to fix a mistyped year. Until 2026-08-24
-        that refusal lived inside the birthday card as red text beside a disabled
-        button &mdash; a state with nothing to press. Open <strong>Birthday</strong>
-        with <strong>Age validation</strong> on and submit any date to walk the
-        handoff; switch the toggle off for the other mode, an app with no age bar
-        that just wants the date.
-      </p>
-      <p class="text-muted text-sm">
-        The avatar modals
-        (<code class="font-mono text-2xs">studio/modals/_crop_photo</code>,
-        <code class="font-mono text-2xs">studio/modals/_image_upload</code>)
-        open live here &mdash;
-        <code class="font-mono text-2xs">studio/cropper_assets</code> is rendered
-        above, so cropper.js loads and the modals mount on this page's host.
-      </p>
+      <p class="text-muted text-sm">The name, birthday and picture cards.</p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
       <%= render layout: "style/modal_specimen", locals: {
@@ -568,11 +521,6 @@
           <%# the skip link that sits under the button, and is also a skip %>
           <span class="block h-1.5 w-14 mx-auto rounded" style="background: var(--color-text); opacity: .25"></span>
         </div>
-        <p class="text-muted text-2xs mt-3">
-          Saving or skipping dispatches
-          <code class="font-mono">ds-onboarding-step-done</code> here rather than
-          the app-level event, so the specimen cannot drive a real chain.
-        </p>
       <% end %>
 
       <%# BIRTHDAY — the ask. ONE card, two modes, because the difference between
@@ -718,28 +666,7 @@
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">leveling off</span>
         <% end %>
       </div>
-      <p class="text-muted text-sm">
-        The profile leveling flow, ported from Turf Monster as ONE primitive
-        (<code class="font-mono text-2xs">studio/modals/blocks/_leveling_activity</code>,
-        with <code class="font-mono text-2xs">_change_username</code> as its username
-        specialization). Walk all four states — <strong>Change Username &rarr; Great
-        Username</strong>, then <strong>Join the Newsletter &rarr; Subscribed!</strong>
-        — each "updated" card opens its modal straight at the success state, just like
-        the Auth cards open a given step. Each card carries its <strong>own Leveling
-        toggle</strong> (like the Auth card's method checkboxes): <strong>checked</strong>
-        is the Turf Monster shape (the seeds bar + Free Entry Token progress),
-        <strong>unchecked</strong> is the McRitchie Studio shape (plain input + Save,
-        then a simple confirmation). Flip a card's toggle, then open it — so you can
-        preview Change Username leveling-on beside Great Username leveling-off. Same
-        modal id either way — the primitive reads
-        <code class="font-mono text-2xs">leveling</code> at runtime, so there is no
-        with/without fork and <strong>no "Quest N of N" counter</strong>. The save is an
-        <strong>app-supplied callback</strong>
-        (<code class="font-mono text-2xs">submit_url</code> + an opaque
-        <code class="font-mono text-2xs">finalize_hook</code> for a wallet step) —
-        <strong>no wallet, signing, or on-chain write lives in the engine</strong>.
-        (These demos resolve locally.)
-      </p>
+      <p class="text-muted text-sm">Each card&rsquo;s toggle switches leveling on or off before you open it.</p>
     </div>
     <%# The walk, left to right: Change Username -> Great Username -> Join Newsletter
         -> Subscribed. The two "updated" cards open the same id at props.celebrate. %>
@@ -872,35 +799,10 @@
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">disabled on this app</span>
         <% end %>
       </div>
-      <p class="text-muted text-sm">
-        The wallet + on-chain modals, ported into the engine and gated by
-        <code class="font-mono text-2xs">Studio.feature?(:web3)</code>. Web3 is
-        <strong><%= web3_on ? "on" : "off" %></strong> here, so these render
-        <%= web3_on ? "live." : "greyed and badged — but STILL openable as a preview." %>
-        <% unless web3_gem %>
-          <strong>This app bundles no solana-studio</strong>, so the three cards it
-          backs &mdash; Connect wallet and the two Sign Wallet states &mdash; are
-          listed for reference but <strong>cannot be opened here</strong>. Nothing
-          registers them, so a trigger would open an empty panel.
-        <% end %>
-        The cards run in the order a player meets them &mdash; <strong>connect a
-        wallet, prove it, spend from it</strong>: Connect wallet &rarr; the two
-        Sign Wallet states &rarr; Entry confirmed. The
-        Connect-wallet picker ships its <strong>Phantom / Solflare / Backpack brand
-        marks inline from the engine</strong>
-        (<code class="font-mono text-2xs">studio/modals/blocks/_wallet_brand_sprite</code>),
-        so every app inherits them with no per-app icon files.
-        The two <strong>Sign Wallet</strong> cards are a different kind of thing
-        from the rest of this section: they render solana-studio's
-        <code class="font-mono text-2xs">solana_studio/modals/_web3_step_up</code>
-        &mdash; the <strong>REAL shared partial a host renders in production</strong>,
-        not a style-guide copy of it &mdash; so what you review here is the
-        shipped card, and it cannot drift from what users see. They also carry the
-        <strong>standard web3 auth button</strong>: a wallet row (brand mark, the
-        wallet&rsquo;s own name, Installed badge, chevron) rather than a filled
-        CTA, glowing via <code class="font-mono text-2xs">pulse-cta</code> because
-        it is the one thing to press.
-      </p>
+      <p class="text-muted text-sm">The wallet and on-chain modals, in the order a player meets them.</p>
+      <% unless web3_gem %>
+        <p class="text-muted text-sm">This app bundles no solana-studio, so the three cards it backs cannot be opened here.</p>
+      <% end %>
     </div>
     <%# ONE ordered run, read left to right as a player meets it: get a wallet,
         prove it, spend from it. This carried three labelled h4 runs for a day
@@ -1042,28 +944,7 @@
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">age gate off</span>
         <% end %>
       </div>
-      <p class="text-muted text-sm">
-        The pre-entry gate and the full entry flow. The age bar is enforced HERE,
-        but its two cards &mdash;
-        <code class="font-mono text-2xs">studio/modals/blocks/_birthday</code> (the
-        ask) and <code class="font-mono text-2xs">_age_gate</code> (the refusal)
-        &mdash; are shown in the <strong>Profile</strong> section, because they are
-        about who the account is. Both are engine primitives gated by
-        <code class="font-mono text-2xs">Studio.feature?(:age_gate)</code>, and their
-        minimum age, jurisdiction label, endpoint, and legal copy are all
-        <strong>app-supplied</strong> (the engine hardcodes no policy).
-      </p>
-      <p class="text-muted text-sm">
-        <strong>The entry flow itself has no specimen here, on purpose.</strong>
-        Packs, pricing, payment rails and every on-chain write are the app&rsquo;s
-        &mdash; the engine owns none of them, and the walked purchase sequence that
-        used to sit in this section was a <strong>mirror</strong> of turf-monster&rsquo;s
-        cards. It drifted, and it demonstrated a payment face that had stopped
-        rendering in production. It was retired on 2026-09-09; turf-monster cards
-        the live flow on its own section of this guide.
-        <strong>What stays is the map below</strong>, because the shape of the flow
-        is the part an app should not have to rediscover.
-      </p>
+      <p class="text-muted text-sm">The app owns the entry flow, so only its map lives here.</p>
       <%# The web2/web3 finding — a real divergence, stated honestly, not invented.
           THIS BOX IS THE SURVIVING HALF of style/modals/_entry_tokens, whose header
           carried the same model in a comment. When that mirror was deleted the
@@ -1071,28 +952,12 @@
           nobody opens — the two sentences about what a token IS, and about who
           signs the mint, came across in that move. %>
       <div class="mt-2 rounded-lg border border-subtle bg-surface p-3 text-xs text-secondary leading-snug">
-        <p class="text-heading font-semibold mb-1">Web2 vs web3 — the honest map</p>
-        <p class="mb-1">
-          The two funding paths <strong>diverge at the front-end and the entry-submit
-          endpoint, then converge</strong>. <strong>Web2</strong> (card / Stripe /
-          Coinflow / PayPal) mints one prepaid entry token per credit on-chain after
-          payment clears, then <strong>consumes</strong> one token to enter.
-          <strong>Web3</strong> (wallet / USDC on-chain) funds USDC directly and
-          <strong>mints no token</strong> &mdash; the mint&nbsp;&rarr;&nbsp;consume prelude
-          is web2-only.
-        </p>
-        <p class="mb-1">
-          An entry token is a <strong>program-owned prepaid entry credit</strong>
-          recorded on-chain as its own account &mdash; <strong>not</strong> a fungible
-          SPL token sitting in the player&rsquo;s wallet, which is the wrong mental
-          model to carry into the code. And the mint is <strong>server-signed once
-          the payment clears</strong>, never on the buyer&rsquo;s click: the two
-          on-chain moments a web2 entry has are that mint and the later consume.
-        </p>
-        <p>
-          Both create the <strong>same on-chain Entry PDA</strong> and resolve to the
-          <strong>same “Entry Confirmed” card</strong>.
-        </p>
+        <p class="text-heading font-semibold mb-1">Web2 vs web3</p>
+        <p class="mb-1">Web2 (card, Stripe, Coinflow, PayPal) mints one prepaid entry token per credit after payment clears, then consumes one to enter.</p>
+        <p class="mb-1">Web3 (wallet, USDC) funds USDC directly and mints no token, so the mint and consume steps are web2-only.</p>
+        <p class="mb-1">An entry token is a program-owned prepaid credit on-chain, not a wallet SPL token.</p>
+        <p class="mb-1">The mint is server-signed once payment clears, never on the buyer&rsquo;s click.</p>
+        <p>Both paths create the same on-chain Entry PDA and end on the same Entry Confirmed card.</p>
       </div>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
@@ -1134,10 +999,6 @@
   <section id="modals-system-status" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">System &amp; status</h3>
-      <p class="text-muted text-sm">
-        The reusable card blocks under <code class="font-mono text-2xs">studio/modals/blocks/</code> &mdash;
-        the studio-canonical processing, success, error, and countdown states.
-      </p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
       <%= render layout: "style/modal_specimen", locals: {
@@ -1284,11 +1145,7 @@
   <section id="modals-templates" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">Templates</h3>
-      <p class="text-muted text-sm">
-        Reusable archetypes under <code class="font-mono text-2xs">studio/modals/templates/</code> &mdash;
-        the copy-from reference cards for a new modal (wizard, form, action,
-        status, success).
-      </p>
+      <p class="text-muted text-sm">Copy from these when you build a new modal.</p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-5">
       <% [
@@ -1325,18 +1182,7 @@
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">disabled on this app</span>
         <% end %>
       </div>
-      <p class="text-muted text-sm">
-        The seeds bar + level-up celebrations, gated by
-        <code class="font-mono text-2xs">Studio.feature?(:leveling)</code> — an
-        app-level setting <strong>independent of :web3</strong> (some apps have
-        Solana but no leveling). Leveling is <strong><%= leveling_on ? "on" : "off" %></strong>
-        here, so these render
-        <%= leveling_on ? "live." : "greyed and badged — but STILL openable as a preview." %>
-        The seed counts, level, and free entry are <strong>app-supplied props</strong>
-        (<code class="font-mono text-2xs">seedsEarned</code>,
-        <code class="font-mono text-2xs">seedsTotal</code>, …) — the engine renders
-        the bar, the app feeds the numbers.
-      </p>
+      <p class="text-muted text-sm">The seeds bar and level-up celebrations.</p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
       <%= render layout: "style/modal_specimen", locals: {
@@ -1396,27 +1242,16 @@
   <section id="modals-motion-registry" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 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>
+      <p class="text-muted text-sm">Every control comes from the live animation registry.</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>
+          Enter
         </h4>
-        <p class="text-secondary text-xs">
-          Opens the demo card with that entrance. Dismiss with Escape, click-outside, or Close.
-        </p>
+        <p class="text-secondary text-xs">Opens the demo card.</p>
         <div id="modal-anim-enter-buttons" class="flex flex-wrap gap-2"></div>
       </div>
 
@@ -1424,18 +1259,15 @@
           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>
+          Leave
         </h4>
-        <p class="text-secondary text-xs">
-          Opens with a plain entrance, then closes itself so the exit keyframe is the star.
-        </p>
+        <p class="text-secondary text-xs">Opens, then closes itself.</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"
@@ -1462,18 +1294,7 @@
   <section id="modals-stack-mechanics" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 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>:
-        <code class="font-mono text-2xs">advance()</code>, dismissibility, the
-        minimum-visible-duration floor, and LIFO stacking. They all run on one
-        throwaway vehicle
-        (<code class="font-mono text-2xs">style/modals/_ds_stack_demo</code>) built
-        from engine blocks &mdash; <strong>the mechanics are the subject, the card
-        is not</strong>. Until 2026-09-09 they ran on a copy of turf-monster&rsquo;s
-        on-chain card, which is how six unrelated demos came to depend on one
-        consumer&rsquo;s markup.
-      </p>
+      <p class="text-muted text-sm">The modal stack&rsquo;s rules, shown on a throwaway card.</p>
     </div>
 
     <div class="grid gap-4 sm:grid-cols-2">
@@ -1485,12 +1306,7 @@
           vehicle carries three faces on one. %>
       <div class="card p-5 space-y-3">
         <h4 class="text-heading font-semibold text-sm">In-flow advance()</h4>
-        <p class="text-secondary text-xs">
-          <code class="font-mono text-2xs">advance(patch)</code> patches the OPEN
-          entry rather than pushing a new one, so the card&rsquo;s Alpine scope
-          survives the transition. Watch the timed pair change a card that never
-          left the stack.
-        </p>
+        <p class="text-secondary text-xs">Patches the open card, so its state survives.</p>
         <div class="flex flex-wrap gap-2">
           <button type="button" class="btn btn-outline btn-sm"
                   data-studio-action="click->style-modals#demo" data-style-modals-name-param="processing">Processing</button>
@@ -1509,10 +1325,7 @@
           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>
+        <p class="text-secondary text-xs">A card with <code class="font-mono text-2xs">dismissible: false</code> ignores Escape and click-outside.</p>
         <div class="flex flex-wrap gap-2">
           <button type="button" class="btn btn-outline btn-sm"
                   data-studio-action="click->style-modals#demo" data-style-modals-name-param="processing">Try Escape (locked)</button>
@@ -1524,10 +1337,7 @@
       <%# The anti-flicker floor from studio/modal_host (window.StudioModals.holdAtLeast). %>
       <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>
+        <p class="text-secondary text-xs">Keeps a fast operation from flashing the spinner.</p>
         <div class="flex flex-wrap gap-2">
           <button type="button" class="btn btn-primary btn-sm"
                   data-studio-action="click->style-modals#demo" data-style-modals-name-param="fastWithHold">Fast op, hold 1500ms</button>
@@ -1539,10 +1349,7 @@
       <%# 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>
+        <p class="text-secondary text-xs">A second <code class="font-mono text-2xs">open()</code> stacks on top, and <code class="font-mono text-2xs">close()</code> pops back.</p>
         <div class="flex flex-wrap gap-2">
           <button type="button" class="btn btn-primary btn-sm"
                   data-studio-action="click->style-modals#demo" data-style-modals-name-param="stackTwo">Open two</button>

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

@@ -38,14 +38,7 @@
 <section id="scrims" class="space-y-5" data-scrim-group>
   <div class="space-y-1">
     <h3 class="type-h4 text-heading">Tints &amp; shades</h3>
-    <p class="text-muted text-sm max-w-2xl">
-      A <strong>shade</strong> lays the dark base over media and light ink reads on it; a
-      <strong>tint</strong> lays the light base over media and dark ink reads on it.
-      <code class="font-mono text-2xs">.scrim</code> picks by theme;
-      <code class="font-mono text-2xs">.scrim-tint</code> / <code class="font-mono text-2xs">.scrim-shade</code>
-      force one. Put the tone on the shared parent so the wash and the
-      <code class="font-mono text-2xs">.scrim-ink</code> text both take it.
-    </p>
+    <p class="text-muted text-sm max-w-2xl">A shade darkens media under light ink, and a tint lightens it under dark ink.</p>
   </div>
   <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
     <% specimens.each do |s| %>

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

@@ -36,12 +36,7 @@
 <section id="site-footer" class="space-y-5" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
   <div class="space-y-1">
     <h3 class="type-h4 text-heading">Site footer and booking</h3>
-    <p class="text-muted text-sm max-w-2xl">
-      One layout line renders the public site's footer from
-      <code class="font-mono text-2xs">config.site_footer</code>; every part is optional. With
-      <code class="font-mono text-2xs">config.booking_url</code> the same pages get Google Calendar's
-      booking page inline, in a popup and on <code class="font-mono text-2xs">/schedule</code>.
-    </p>
+    <p class="text-muted text-sm max-w-2xl">One layout line renders the footer, and <code class="font-mono text-2xs">config.booking_url</code> turns on booking.</p>
     <p class="text-muted text-sm" data-site-footer-status>
       This app:
       footer <strong class="text-body"><%= own_facts ? "declared" : (Studio.site_footer_enabled? ? "default (not declared)" : "off") %></strong> &middot;
@@ -55,10 +50,7 @@
     <%= render layout: "style/specimen",
           locals: { klass: "studio_site_footer",
                     usage: %(studio_site_footer   # one line, at the end of the layout body) } do %>
-      <p class="text-sm text-secondary text-center">
-        The footer, where it should show: every page for a visitor, listed controllers when signed in.
-        Previewed below.
-      </p>
+      <p class="text-sm text-secondary text-center">Previewed below.</p>
     <% end %>
 
     <%= render layout: "style/specimen",
@@ -74,10 +66,10 @@
 
     <% [ [ "studio_booking_frame", nil, "whole",
            %(studio_booking_frame   # whole at rest: the default, and crop: false),
-           "Whole at rest, the default. Google's page as Google draws it: its header, the slot picker, its credit lines." ],
+           "Whole at rest, the default." ],
          [ "config.booking_crop", sample_crop, "cropped",
            %(config.booking_crop = { top: 200, bottom: 600, frame_height: 720 }   # bin/booking-crop-measure prints yours),
-           "Cropped at rest to the slot picker, from numbers measured on the app's own schedule. Opens to the whole page when it is used." ]
+           "Cropped to the slot picker at rest." ]
        ].each do |klass, crop, state, usage, caption| %>
       <%= render layout: "style/specimen",
             locals: { klass: klass, disabled: !booking, disabled_label: "no booking_url", usage: usage } do %>

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

@@ -66,14 +66,7 @@
 <section id="tasks" class="space-y-8" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
   <div class="space-y-1">
     <h2 class="type-h3 text-heading">Tasks</h2>
-    <p class="text-muted text-sm max-w-2xl">
-      The shared board primitive that every board builds from &mdash; columns, cards, the
-      <code class="font-mono text-2xs">stage-*</code> badge palette, and the drag / optimistic
-      move + reorder. McRitchie Studio's <code class="font-mono text-2xs">/deployments</code> board is
-      the top-of-line; the specimen below is the <strong>real</strong>
-      <code class="font-mono text-2xs">studio/board/board</code> primitive in
-      <code class="font-mono text-2xs">demo: true</code> mode &mdash; drag a card, no save.
-    </p>
+    <p class="text-muted text-sm max-w-2xl">The real board primitive in demo mode, so a drag saves nothing.</p>
   </div>
 
   <%# ---- The LIVE primitive (demo mode) --------------------------------- %>
@@ -81,7 +74,7 @@
   <div class="space-y-3">
     <div class="flex items-center gap-2">
       <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">Live</span>
-      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; demo &mdash; drag a card between columns</p>
+      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; demo</p>
     </div>
     <%= render "studio/board/board",
           demo: true,
@@ -120,7 +113,7 @@
               data-test="chrome-archived-toggle">
         <span x-text="state.showArchived ? 'Hide archived' : 'Show archived'">Show archived</span>
       </button>
-      <span class="label-upper"><code class="font-mono text-2xs">header_slot</code> chrome &middot; binds to <code class="font-mono text-2xs">state.showArchived</code> &mdash; no outer wrapper</span>
+      <span class="label-upper"><code class="font-mono text-2xs">header_slot</code> &middot; binds to <code class="font-mono text-2xs">state.showArchived</code></span>
     </div>
   <% end %>
   <% chrome_kickoff = capture do %>
@@ -150,7 +143,7 @@
   <div class="space-y-3">
     <div class="flex items-center gap-2">
       <span class="badge" style="color: var(--color-primary); border-color: var(--color-primary)">Enriched</span>
-      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; 0.28.0 chrome &mdash; coloured counts, toggle-able column, archive re-parent</p>
+      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; coloured counts, toggle-able column, archive re-parent</p>
     </div>
     <%= render "studio/board/board",
           demo: true,
@@ -200,7 +193,7 @@
   <div class="space-y-3">
     <div class="flex items-center gap-2">
       <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">Grid + Lock</span>
-      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; DG (0.29.0) &mdash; two-level side&rarr;position grid, reorder within a lane, &#128274; pinned starters stay put</p>
+      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; two-level grid, reorder within a lane, &#128274; pinned starters</p>
     </div>
     <%= render "studio/board/board",
           demo: true,
@@ -246,17 +239,13 @@
 
   <%# ---- The stage palette ---------------------------------------------- %>
   <div class="space-y-3">
-    <p class="label-upper">Stage palette — the pipeline spine</p>
+    <p class="label-upper">Stage palette</p>
     <div class="flex flex-wrap gap-2">
       <% %w[stage-fresh stage-shaping stage-structured stage-refined stage-cohered stage-shipped stage-closed].each do |stage| %>
         <span data-stage="<%= stage %>"><%= render "components/badge", text: stage.sub("stage-", ""), scheme: stage %></span>
       <% end %>
     </div>
-    <p class="text-muted text-xs">
-      Seven stage roles from <code class="font-mono text-2xs">components/_badge</code>. Every pipeline
-      (tasks, deployments, and any future board) draws its columns from this one palette, so a card
-      reads the same wherever it lives.
-    </p>
+    <p class="text-muted text-xs">Every pipeline draws its columns from this palette.</p>
   </div>
 
   <%# ---- Standard vs custom -------------------------------------------- %>
@@ -267,12 +256,12 @@
         <p class="text-heading font-semibold text-sm">What every board inherits</p>
       </div>
       <ul class="text-secondary text-sm space-y-1 list-disc list-inside">
-        <li>Column layout + horizontal scroll with faded edges</li>
-        <li>The <code class="font-mono text-2xs">stage-*</code> badge palette + count chips (colour via <code class="font-mono text-2xs">count_class</code>)</li>
-        <li>Card chrome (<code class="font-mono text-2xs">.card</code>) and the drag / rank handle</li>
+        <li>Column layout and horizontal scroll</li>
+        <li>The <code class="font-mono text-2xs">stage-*</code> badges and count chips</li>
+        <li>Card chrome and the drag handle</li>
         <li>Empty-column drop state</li>
-        <li>Chrome-state home (<code class="font-mono text-2xs">board_state</code> + <code class="font-mono text-2xs">header_slot</code>) &mdash; filters/toggles without an outer wrapper</li>
-        <li>Toggle-able columns (<code class="font-mono text-2xs">show_expr</code>), a kickoff slot, and archive re-parent (<code class="font-mono text-2xs">archive_zone</code>)</li>
+        <li>Filters and toggles with no outer wrapper</li>
+        <li>Toggle-able columns, a kickoff slot and archive re-parent</li>
       </ul>
     </div>
     <div class="card p-5 space-y-2">
@@ -282,9 +271,9 @@
       </div>
       <ul class="text-secondary text-sm space-y-1 list-disc list-inside">
         <li>Which stages become columns</li>
-        <li>The card body — fields, chips, avatars, live timers</li>
-        <li>Filter/toggle logic + header actions, composed onto the shared chrome state</li>
-        <li>Live-update wiring (Turbo Streams on the deploy board)</li>
+        <li>The card body</li>
+        <li>Filter logic and header actions</li>
+        <li>Live updates</li>
       </ul>
     </div>
   </div>

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

@@ -58,11 +58,7 @@
   <div class="flex flex-wrap items-start justify-between gap-3">
     <div class="space-y-1">
       <h2 class="type-h3 text-heading">Theme</h2>
-      <p class="text-muted text-sm max-w-2xl">
-        The color foundation. The 7-role system, editable here. Edits preview live; Save writes them
-        and Regenerate clears the theme cache. Both persist <strong>in place</strong> — the page never
-        leaves. Every specimen on this page restyles from these roles.
-      </p>
+      <p class="text-muted text-sm max-w-2xl">Every specimen on this page restyles from these 7 color roles.</p>
     </div>
     <form action="/admin/theme/regenerate" method="post" accept-charset="UTF-8" @submit.prevent="regenerate($event)">
       <% if csrf_ok %>
@@ -108,7 +104,6 @@
         <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>" autocomplete="off">
       <% end %>
       <h3 class="type-h4 text-heading">Role colors</h3>
-      <p class="text-muted text-sm">Every specimen on this page reads these through its CSS variable, so it follows the app and its light or dark mode.</p>
 
       <% roles.each do |role| %>
         <% db_col = db_col_for.call(role) %>
@@ -164,7 +159,6 @@
       <%= render "style/type_ladder" %>
     <div class="space-y-3" x-show="edited" x-cloak data-test="style-theme-preview">
       <p class="label-upper">Preview</p>
-      <p class="text-muted text-sm">A live dark/light mock — it tracks the editor as you type, before you save.</p>
       <div class="grid gap-3 sm:grid-cols-2">
         <div class="rounded-xl border border-subtle overflow-hidden">
           <div class="px-3 py-1.5 bg-surface-alt"><span class="text-2xs font-bold uppercase tracking-wider text-secondary">Dark</span></div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.128.0"
+  VERSION = "0.129.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.128.0
+  version: 0.129.0
 platform: ruby
 authors:
 - Alex McRitchie