studio-engine 0.127.0 → 0.129.0

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/controllers/studio/surveys_controller.rb

@@ -32,11 +32,15 @@ module Studio
       return render(json: { error: "unknown question" }, status: :not_found) unless question
 
       response = open_response!
-      return render(json: { error: "already complete" }, status: :conflict) unless response
+      return render_already_complete unless response
 
       ok, error = rescue_survey_write(response) { response.record_answer(question, params[:value]) }
       if ok
         render json: { saved: true, key: question.key, answered: response.answers.keys & @survey.keys }
+      elsif response.completed?
+        # A submit completed it after this request found it open: the same answer
+        # as the branch above, never a validation error for the visitor to read.
+        render_already_complete
       else
         render json: { saved: false, error: error }, status: :unprocessable_entity
       end
@@ -48,6 +52,10 @@ module Studio
 
       submitted = submitted_answers
       @errors = {}
+      completed = false
+      # One transaction, so record_answer's row lock holds from the first answer to
+      # the completion and a late autosave cannot change an answer between the two.
+      # The hook runs after the commit.
       Studio::SurveyResponse.transaction do
         @survey.questions.each do |question|
           next unless submitted.key?(question.key)
@@ -55,10 +63,11 @@ module Studio
           ok, error = response.record_answer(question, submitted[question.key])
           @errors[question.key] = error unless ok
         end
+        response.missing_required(@survey).each { |key| @errors[key] ||= "This one is required." }
+        completed = @errors.empty? && response.complete!(@survey)
       end
-      response.missing_required(@survey).each { |key| @errors[key] ||= "This one is required." }
 
-      if @errors.empty? && response.complete!(@survey)
+      if completed
         run_completed_hook(response)
         redirect_to studio_survey_thanks_path(@survey.slug), status: :see_other
       elsif response.completed?
@@ -77,6 +86,10 @@ module Studio
 
     private
 
+    def render_already_complete
+      render json: { error: "already complete" }, status: :conflict
+    end
+
     def load_survey
       @survey = Studio.survey(params[:slug])
       render :not_found, status: :not_found unless @survey

data/app/helpers/studio/loader_helper.rb

@@ -60,8 +60,8 @@ module Studio
     # and busy button after `max_wait` ms, so a response that became a download
     # never leaves them up; a Turbo visit is never capped.
     # Any studio_loader option (style:, icon:, art:) passes through.
-    def studio_loader_overlay(label: "Loading", delay: 350, max_wait: 15_000, size: 96, **options)
-      render "studio/loader/overlay", label: label, delay: delay.to_i, max_wait: max_wait.to_i, size: size, options: options
+    def studio_loader_overlay(label: "Loading", delay: Studio::Loader::OVERLAY_DELAY_MS, min_show: Studio::Loader::OVERLAY_MIN_SHOW_MS, max_wait: 15_000, size: 96, **options)
+      render "studio/loader/overlay", label: label, delay: delay.to_i, min_show: min_show.to_i, max_wait: max_wait.to_i, size: size, options: options
     end
 
     def studio_loader_size(size)

data/app/helpers/studio_icon_helper.rb

@@ -0,0 +1,10 @@
+# studio_icon("rocket", size: 18): one line icon as inline SVG in currentColor, so it takes
+# its color from the text around it and needs no asset request under a strict CSP. The set
+# is Studio::Icons. An unknown name renders nothing (nil), so a caller can fall back:
+#
+#   studio_icon(link[:icon]) || link[:emoji]
+module StudioIconHelper
+  def studio_icon(name, size: 18, class: nil)
+    Studio::Icons.svg(name, size: size, css_class: binding.local_variable_get(:class))&.html_safe
+  end
+end

data/app/javascript/studio/agent_chat.js

@@ -18,12 +18,24 @@
 //            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
 //            just answered. The turn shows at once, the chat follows it, and it
 //            polls now; a poll already in flight is followed by one more, so a
 //            refresh is never swallowed.
+//   SENT     a typed send the app took dispatches studio:agent-chat:sent on the
+//            chat's section, {detail: {turn}}; studio/agent_chat_voice clears its
+//            old line on it.
+//   HELD     a turn the hub holds (status "held": stored, no automatic answer is
+//            coming) is settled and says so, and never asks for a resend. A hub
+//            that still reports it as "failed" gets the failed line.
 //   TYPING   the typing line shows while the hub says an answer is pending:
 //            "thinking", then "typing" once a turn's status is "typing".
 //
@@ -37,7 +49,13 @@ 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"])
 
 export function settled(turn) {
@@ -95,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']")
@@ -114,7 +138,8 @@ export function mountAgentChat(root, {
   doc = globalThis.document,
   now = () => Date.now(),
   setTimer = (fn, ms) => globalThis.setTimeout(fn, ms),
-  clearTimer = (id) => globalThis.clearTimeout(id)
+  clearTimer = (id) => globalThis.clearTimeout(id),
+  CustomEventClass = globalThis.CustomEvent
 } = {}) {
   const $ = (selector) => root.querySelector(selector)
   const log = $("[data-agent-chat-log]")
@@ -130,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
@@ -171,11 +240,16 @@ export function mountAgentChat(root, {
       if (text && text.textContent !== String(turn.text ?? "")) text.textContent = String(turn.text ?? "")
       const failed = node.querySelector("[data-agent-chat-failed]")
       if (failed) failed.hidden = turn.status !== "failed"
+      const held = node.querySelector("[data-agent-chat-held]")
+      if (held) held.hidden = turn.status !== "held"
     }
     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() {
@@ -221,8 +295,9 @@ export function mountAgentChat(root, {
     if (!state.alive) return undefined
     if (turn) {
       state.turns = mergeTurns(state.turns, [turn])
-      state.pending = true
+      state.pending = turn.status !== "held"
       state.following = true
+      state.revealFollowing = true
       state.waitingSince = now()
       setOffline(false)
       render()
@@ -260,17 +335,19 @@ export function mountAgentChat(root, {
       if (response.status === 201 && data.turn) {
         input.value = ""
         state.turns = mergeTurns(state.turns, [data.turn])
-        state.pending = true
+        state.pending = data.turn.status !== "held"
         state.following = true
+        state.revealFollowing = true
         setOffline(false)
         render()
         toEnd()
         if (status) status.textContent = "Sent."
+        root.dispatchEvent(new CustomEventClass(SENT_EVENT, { detail: { turn: data.turn } }))
         state.waitingSince = now()
         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) {
@@ -302,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()
 
@@ -319,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

@@ -18,8 +18,14 @@
 //      says who it kept.
 //
 // Every refusal is a line in [data-agent-chat-voice-status] (set as text) and a
-// state on data-agent-chat-voice-state: listening, transcribing, queued, sending,
-// sent, silent, no_speech, not_configured, rate_limited, refused, failed.
+// state on data-agent-chat-voice-state: listening, tapped, transcribing, queued,
+// sending, sent, silent, no_speech, not_configured, rate_limited, refused, failed.
+//
+// THE HELD BUTTON DOES NOT MOVE. The line sits above the button and the recorder's
+// own line is hidden here, so this one line says everything. _voice reserves its
+// quiet-hint height, and holdLine fixes its height for the length of a hold: an old
+// line clearing under the finger cannot pull the button down, and a take landing
+// during a hold cannot push it up.
 //
 // NO WORDS ARE LOST. A transcript that could not be sent goes in the chat's box,
 // after anything already typed there. A take that lands while another is still
@@ -33,6 +39,7 @@ export const EMBED_WAIT_MS = 8000
 
 export const MESSAGES = {
   listening: "Listening...",
+  tapped: "Hold the button while you talk, then let go.",
   transcribing: "Turning that into words...",
   queued: "Got that one too. It's next.",
   sending: (name) => `Sending to ${name}...`,
@@ -43,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.",
@@ -58,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)) }
   }
@@ -157,6 +174,19 @@ export function mountAgentChatVoice(root, {
     if (status) status.textContent = message || ""
   }
 
+  // Takes the line's height before it changes, and hands it back with no argument.
+  function holdLine(holding) {
+    if (!status || !status.style) return
+    status.style.height = holding && status.offsetHeight ? `${status.offsetHeight}px` : ""
+    status.style.overflow = holding && status.offsetHeight ? "hidden" : ""
+  }
+
+  // What the recorder just said on its own line, which _voice hides here.
+  function recorderLine(fallback) {
+    const line = root.querySelector("[data-voice-recorder-status]")
+    return (line && line.textContent) || fallback
+  }
+
   function embedder() {
     const config = parseEmbedder(root.getAttribute("data-agent-chat-voice-embedder"))
     if (!config) return Promise.resolve(null)
@@ -215,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)}`)
   }
@@ -235,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)
@@ -278,15 +314,31 @@ export function mountAgentChatVoice(root, {
   function onState(event) {
     const next = event.detail && event.detail.state
     if (next === "starting") {
+      holdLine(true)
       say("idle", "")
-    } else if (next === "recording") {
+      return
+    }
+    if (next === "recording") {
       say("listening", MESSAGES.listening)
       embedder().then((loaded) => loaded && loaded.warm && loaded.warm()).catch(() => {})
-    } else if (root.dataset.agentChatVoiceState === "listening") {
+      return
+    }
+    holdLine(false)
+    if (next === "tapped") say("tapped", recorderLine(MESSAGES.tapped))
+    else if (next === "failed") say("failed", recorderLine(MESSAGES.failed))
+    else if (next === "denied") say("refused", recorderLine(MESSAGES.failed))
+    else if (root.dataset.agentChatVoiceState === "listening") {
       say(working ? "transcribing" : "idle", working ? MESSAGES.transcribing : "")
     }
   }
 
+  // A later typed send (studio/agent_chat): "Sent. Spoken by ..." is about a take
+  // the thread has moved past. A take still in hand, or a hold, keeps its own line.
+  function onTypedSend() {
+    if (working || root.dataset.agentChatVoiceState === "listening") return
+    say("idle", "")
+  }
+
   // "I can't hear anything yet" on the one line: the recorder's own line is hidden
   // in the composer while it records, so a held button never moves for it.
   function onHint(event) {
@@ -304,6 +356,7 @@ export function mountAgentChatVoice(root, {
   root.addEventListener("studio:voice-recorder:silent", onSilent)
   root.addEventListener("studio:voice-recorder:state", onState)
   root.addEventListener("studio:voice-recorder:hint", onHint)
+  if (chat && chat.addEventListener) chat.addEventListener("studio:agent-chat:sent", onTypedSend)
 
   return {
     takeArrived,
@@ -313,6 +366,7 @@ export function mountAgentChatVoice(root, {
       root.removeEventListener("studio:voice-recorder:silent", onSilent)
       root.removeEventListener("studio:voice-recorder:state", onState)
       root.removeEventListener("studio:voice-recorder:hint", onHint)
+      if (chat && chat.removeEventListener) chat.removeEventListener("studio:agent-chat:sent", onTypedSend)
     }
   }
 }

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
     })
   })
 }