studio-engine 0.127.0 → 0.128.0

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

@@ -24,6 +24,12 @@
 //            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".
 //
@@ -38,6 +44,7 @@ export const OFFLINE_MS = 15000
 export const FOLLOW_PX = 20
 export const LIMIT = 50
 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) {
@@ -114,7 +121,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]")
@@ -171,6 +179,8 @@ 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
@@ -221,7 +231,7 @@ 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.waitingSince = now()
       setOffline(false)
@@ -260,12 +270,13 @@ 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
         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)

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}...`,
@@ -157,6 +164,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)
@@ -278,15 +298,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 +340,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 +350,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/loader.js

@@ -9,6 +9,15 @@
 //                 data-studio-loader-overlay, outlasts the overlay's data-delay
 //                 ms; hidden when the page arrives. Its role=status label is
 //                 announced: the overlay never marks itself aria-busy.
+//   the pace      one standard for every app: a visit under data-delay ms shows no
+//                 overlay and waits for nothing; once the overlay of a visit has
+//                 shown, it stays data-min-show ms. Turbo's hook for a pause,
+//                 turbo:before-render, comes AFTER a view transition took the old
+//                 page's picture, with rendering paused, so a hold there would
+//                 freeze the loader and carry it out in that picture. So the wait
+//                 is on the response, ahead of all of that: see holdVisitResponse.
+//   the door      a host need not render the overlay. layouts/studio/_head carries
+//                 it in a <template>, and this module adds it to the body at need.
 //   pending       a button holding studio_loader_pending. Turbo marks a
 //                 submitting form aria-busy itself; for a form Turbo does not
 //                 drive, the submitter is marked here, and cleared on pagehide
@@ -20,10 +29,13 @@
 //                 clears at once, on turbo:reload.
 //   the API       window.StudioLoader.show(caption) / hide() for any other long
 //                 wait, and setPercent(el, n) for a loader drawn with percent:.
+//                 hide() is immediate. It ends any wait, because the caller owns
+//                 that moment, and a caller's show() has no minimum.
 //
 // The logic is exported for test/javascript/loader.test.mjs.
 
 export var DEFAULT_DELAY_MS = 350
+export var DEFAULT_MIN_SHOW_MS = 750
 export var MAX_WAIT_MS = 15000
 
 // Only a visit the user started earns the overlay: a click or Turbo.visit
@@ -39,6 +51,11 @@ export function overlayDelay(overlay) {
   return value >= 0 ? value : DEFAULT_DELAY_MS
 }
 
+export function overlayMinShow(overlay) {
+  var value = overlay ? parseInt(overlay.getAttribute('data-min-show'), 10) : NaN
+  return value >= 0 ? value : DEFAULT_MIN_SHOW_MS
+}
+
 // The percent a caller handed setPercent, clamped to a number in 0..100.
 export function clampPercent(value) {
   var n = Number(value)
@@ -58,6 +75,97 @@ function findOverlay(doc) {
 var pendingTimer = null
 var capTimer = null
 var autoShown = false
+var shownAt = null
+var deferredHide = null
+var releaseHold = null
+var visitSignal = null
+
+// The host's own overlay, else the one layouts/studio/_head carries. Added once:
+// querySelector cannot see into a <template>.
+function ensureOverlay(doc) {
+  var overlay = findOverlay(doc)
+  if (overlay || !doc.body) return overlay
+  var template = doc.querySelector('template[data-studio-loader-overlay-template]')
+  if (!template) return null
+  doc.body.appendChild(doc.importNode(template.content, true))
+  return findOverlay(doc)
+}
+
+// What is left of the minimum for an overlay a visit showed. Zero for one that is
+// not showing, and for one a caller opened with show().
+export function minShowLeft(overlay, now) {
+  if (!overlay || overlay.hidden || shownAt === null) return 0
+  return Math.max(0, overlayMinShow(overlay) - (now - shownAt))
+}
+
+// A page that must stay its own document answers this way. Turbo loads it again by
+// a full load, so this response paints nothing, and a wait here would only delay it.
+export function answersWithFullLoad(html) {
+  return /<meta[^>]*(turbo-visit-control[^>]*reload|reload[^>]*turbo-visit-control)/i.test(html || '')
+}
+
+export function noteVisitRequest(event, doc) {
+  if (event.target === doc.documentElement) visitSignal = event.detail.fetchOptions.signal
+}
+
+function endHold() {
+  if (releaseHold) releaseHold()
+}
+
+// Turbo reads response.responseHTML, and only then records the response, caches the
+// page and opens its view transition. So this is the last moment the page is live
+// with the response in hand. The rest of the minimum runs here and the overlay goes,
+// so the old picture has no overlay in it. It always ends: at the timer, at hide(),
+// or at the next visit. A later hold (the transition's wait for images) comes after
+// this one has ended, inside the render, so neither can cut the other short. Turbo
+// renders even a cancelled visit's response, so that HTML never goes: a Back must win.
+//
+// Only a visit's own good HTML waits. A frame, a form and a prefetch have another
+// target. A failure and a download pass straight through.
+export function holdVisitResponse(event, doc) {
+  doc = doc || document
+  if (event.target !== doc.documentElement) return false
+  clearTimeout(pendingTimer)
+  pendingTimer = null
+  var response = event.detail && event.detail.fetchResponse
+  // A body that fails after its headers rejects here, and Turbo fires nothing for it.
+  if (response) Promise.resolve(response.responseHTML).catch(function () { hide(doc) })
+  if (!response || !response.succeeded || !response.isHTML) return false
+  var overlay = findOverlay(doc)
+  if (minShowLeft(overlay, Date.now()) <= 0) return false
+  var signal = visitSignal
+  var held = Promise.resolve(response.responseHTML).then(function (html) {
+    if (answersWithFullLoad(html)) return html
+    var left = minShowLeft(overlay, Date.now())
+    if (left <= 0) return html
+    return new Promise(function (resolve) {
+      var done = function (value) { if (!signal || !signal.aborted) resolve(value) }
+      var timer = setTimeout(function () {
+        releaseHold = null
+        hide(doc)
+        done(html)
+      }, left)
+      releaseHold = function () {
+        clearTimeout(timer)
+        releaseHold = null
+        done(html)
+      }
+    })
+  })
+  Object.defineProperty(response, 'responseHTML', { configurable: true, value: held })
+  return true
+}
+
+// A form's overlay ends with its submit, and no render waits on it, so this only
+// keeps the overlay up for the rest of its minimum.
+export function hideAfterMinimum(doc) {
+  doc = doc || document
+  var left = minShowLeft(findOverlay(doc), Date.now())
+  if (left <= 0) return hide(doc)
+  clearTimeout(deferredHide)
+  deferredHide = setTimeout(function () { hide(doc) }, left)
+  return true
+}
 
 // The overlay's status is a live region; rewriting its label after the overlay
 // unhides makes a screen reader say it, where text already present when a
@@ -77,8 +185,11 @@ export function show(caption, doc) {
   doc = doc || document
   clearTimeout(pendingTimer)
   pendingTimer = null
+  clearTimeout(deferredHide)
+  deferredHide = null
   autoShown = false
-  var overlay = findOverlay(doc)
+  shownAt = null
+  var overlay = ensureOverlay(doc)
   if (!overlay) return false
   var line = overlay.querySelector('[data-studio-loader-caption]')
   if (line) line.textContent = caption || ''
@@ -94,6 +205,10 @@ export function hide(doc) {
   doc = doc || document
   clearTimeout(pendingTimer)
   pendingTimer = null
+  clearTimeout(deferredHide)
+  deferredHide = null
+  shownAt = null
+  endHold()
   var overlay = findOverlay(doc)
   if (!overlay) return false
   overlay.removeAttribute('data-state')
@@ -134,10 +249,14 @@ function armCap(doc) {
 // slow Turbo visit keeps its overlay until the page arrives.
 export function showSoon(caption, doc) {
   doc = doc || document
-  var overlay = findOverlay(doc)
+  var overlay = ensureOverlay(doc)
   if (!overlay || !overlay.hidden) return
   clearTimeout(pendingTimer)
-  pendingTimer = setTimeout(function () { show(caption, doc); autoShown = true }, overlayDelay(overlay))
+  pendingTimer = setTimeout(function () {
+    show(caption, doc)
+    autoShown = true
+    shownAt = Date.now()
+  }, overlayDelay(overlay))
 }
 
 export function markBusy(button, doc) {
@@ -168,7 +287,13 @@ export function installStudioLoader(doc) {
   if (installed) return
   installed = true
 
-  doc.addEventListener('turbo:visit', function (event) { if (userVisit(event)) showSoon('', doc) })
+  doc.addEventListener('turbo:visit', function (event) {
+    // The response a hold still waits on belongs to a visit that is over.
+    endHold()
+    if (userVisit(event)) showSoon('', doc)
+  })
+  doc.addEventListener('turbo:before-fetch-request', function (event) { noteVisitRequest(event, doc) })
+  doc.addEventListener('turbo:before-fetch-response', function (event) { holdVisitResponse(event, doc) })
   // turbo:reload: the response was not HTML (a download), or the visit failed,
   // and Turbo hands the URL to the browser; no page may ever replace this one.
   ;['turbo:load', 'turbo:render', 'turbo:before-cache', 'turbo:fetch-request-error', 'turbo:frame-load', 'turbo:reload'].forEach(function (name) {
@@ -189,7 +314,7 @@ export function installStudioLoader(doc) {
   })
   doc.addEventListener('turbo:submit-end', function (event) {
     var form = event.target
-    if (form && form.hasAttribute && form.hasAttribute('data-studio-loader-overlay')) hide(doc)
+    if (form && form.hasAttribute && form.hasAttribute('data-studio-loader-overlay')) hideAfterMinimum(doc)
   })
 
   // A form Turbo does not drive navigates away on its own; mark the button and,

data/app/javascript/studio/microphone_chip.js

@@ -55,6 +55,7 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
   let silentLabel = null
   let lastTakeSilent = false
   let helpSession = null
+  let keysDown = new Set()
   let permission = null
   let destroyed = false
 
@@ -296,6 +297,7 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
     root.dataset.microphoneHelp = kind
 
     if (dialog.open) return
+    keysDown = new Set()
     helpSession = { returnFocus: returnTo || doc.activeElement, done: false }
     if (typeof dialog.showModal === "function") dialog.showModal()
     else dialog.setAttribute("open", "")
@@ -318,6 +320,20 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
     if (target) target.focus()
   }
 
+  // A key held on the talk button when a refusal opens the dialog lands on Close, the
+  // focused button: its repeats would press Close (Enter), and its keyup would finish
+  // the press (Space). Only a key pressed since the dialog opened counts. Mouse and
+  // touch are not keys, and Esc is not one of these two.
+  function onDialogKey(event) {
+    if (event.key !== " " && event.key !== "Enter") return
+    if (event.type === "keydown") {
+      if (event.repeat) event.preventDefault()
+      else keysDown.add(event.key)
+    } else if (!keysDown.delete(event.key)) {
+      event.preventDefault()
+    }
+  }
+
   // ---- Wiring --------------------------------------------------------------
 
   function onClick(event) {
@@ -342,6 +358,8 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
     if (event.key !== "Escape") return
     if (dialog && dialog.contains(event.target)) return
     if (!panel || panel.hidden) return
+    // The list's Esc, not a modal's or a page's around the chip.
+    event.stopPropagation()
     closePanel()
     if (chip) chip.focus()
   }
@@ -352,7 +370,11 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
   listeners.forEach(([name, fn]) => win.addEventListener(name, fn))
   root.addEventListener("click", onClick)
   root.addEventListener("keydown", onKey)
-  if (dialog) dialog.addEventListener("close", onDialogClose)
+  if (dialog) {
+    dialog.addEventListener("close", onDialogClose)
+    dialog.addEventListener("keydown", onDialogKey, true)
+    dialog.addEventListener("keyup", onDialogKey, true)
+  }
   if (media && media.addEventListener) media.addEventListener("devicechange", onDeviceChange)
   watchPermission()
   refresh()
@@ -365,7 +387,11 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
       listeners.forEach(([name, fn]) => win.removeEventListener(name, fn))
       root.removeEventListener("click", onClick)
       root.removeEventListener("keydown", onKey)
-      if (dialog) dialog.removeEventListener("close", onDialogClose)
+      if (dialog) {
+        dialog.removeEventListener("close", onDialogClose)
+        dialog.removeEventListener("keydown", onDialogKey, true)
+        dialog.removeEventListener("keyup", onDialogKey, true)
+      }
       if (media && media.removeEventListener) media.removeEventListener("devicechange", onDeviceChange)
       if (permission) permission.onchange = null
       if (dialog && dialog.open) dialog.close()

data/app/javascript/studio/page_transitions.js

@@ -1,5 +1,5 @@
-// studio/page_transitions: the app-to-app page transition (Studio.page_transition_direction,
-// docs/PAGE_TRANSITIONS.md). Loaded by its own tag in layouts/studio/_head, only with the
+// studio/page_transitions: the app-to-app page transition (Studio.page_transition_direction and
+// Studio.page_transition_style, docs/PAGE_TRANSITIONS.md). Loaded by its own tag in layouts/studio/_head, only with the
 // setting on. It names a style on <html>, and engine.css draws it. It imports nothing.
 //
 // Turbo calls document.startViewTransition BEFORE turbo:before-render, and the browser takes
@@ -8,17 +8,20 @@
 // turbo:visit and from the response, never first at before-render.
 //
 // A full load is the other path to the same look. The new document draws the motion, so the old
-// one only plans it: at pageswap it names what it holds, draws the style here, and leaves it for
+// one only plans it: at pageswap it names what it holds, reads the style here, and leaves it for
 // studio/page_transition_reveal, the classic script that applies it at pagereveal.
 //
 // The effects are from the Codrops Page Transitions demo; the keyframes were written fresh.
 
-export const DIRECTIONS = Object.freeze({
-  left: Object.freeze(["fade-left", "unfold-right"]),
-  right: Object.freeze(["fade-right", "unfold-left"]),
-  top: Object.freeze(["fade-top", "unfold-bottom"]),
-  bottom: Object.freeze(["fade-bottom", "unfold-top"]),
+// The move each pair of settings plays: the first key is Studio.page_transition_style, the second
+// is Studio.page_transition_direction. An unfold is named for the way the new page turns, which
+// is the opposite of the way the page leaves.
+export const STYLES = Object.freeze({
+  slide: Object.freeze({ left: "slide-left", right: "slide-right", top: "slide-top", bottom: "slide-bottom" }),
+  unfold: Object.freeze({ left: "unfold-right", right: "unfold-left", top: "unfold-bottom", bottom: "unfold-top" }),
 })
+// Mirrors the default in lib/studio.rb, for a page with no style meta.
+export const DEFAULT_STYLE = "slide"
 
 // A same-page visit (a refresh, a poll, the second half of a redirect): the transition still
 // runs, and draws nothing.
@@ -29,31 +32,31 @@ export const FULL_LOAD_STYLE_KEY = "studio-page-transition-style"
 const MAX_READY_IMAGES = 12
 const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"
 
-export function pickStyle(direction, random = Math.random) {
-  if (!Object.hasOwn(DIRECTIONS, direction)) return null
-  const pair = DIRECTIONS[direction]
-  return pair[Math.floor(random() * pair.length)]
+export function styleFor(direction, style) {
+  const moves = STYLES[Object.hasOwn(STYLES, style) ? style : DEFAULT_STYLE]
+  return Object.hasOwn(moves, direction) ? moves[direction] : null
 }
 
 // The style for one visit, STILL, or null to leave the swap alone (the engine's fade plays,
 // and a morph between two pages stands). An advance visit to the same path can bring a new
 // page, as a launch panel does when it gives way to the chat at its own address, so a name
 // the two share still morphs. A refresh replaces, and stays silent.
-export function planVisit({ direction, from, to, transitions, sharedName, advance }, random = Math.random) {
-  if (!transitions || !from || !to || !Object.hasOwn(DIRECTIONS, direction)) return null
+export function planVisit({ direction, style, from, to, transitions, sharedName, advance }) {
+  const move = styleFor(direction, style)
+  if (!transitions || !from || !to || !move) return null
   if (from === to) return advance && sharedName ? null : STILL
-  return sharedName ? null : pickStyle(direction, random)
+  return sharedName ? null : move
 }
 
 // The style a full load should play, or null for a plain load: planVisit's own rule, so the
 // two paths cannot differ. No morph, since the old page cannot read the new page's names
 // before its picture, and a browser with no activation entry has nothing to compare.
-export function planFullLoad({ direction, from, activation }, random = Math.random) {
+export function planFullLoad({ direction, style, from, activation }) {
   const url = activation && activation.entry && activation.entry.url
   if (!url) return null
   const to = new URL(url).pathname
-  const style = planVisit({ direction, from, to, transitions: true, sharedName: false }, random)
-  return style === STILL ? null : style
+  const move = planVisit({ direction, style, from, to, transitions: true, sharedName: false })
+  return move === STILL ? null : move
 }
 
 // Hands the style to the next document. Storage can refuse, and then the load is plain.
@@ -129,6 +132,11 @@ function readDirection(doc) {
   return meta ? meta.content : null
 }
 
+function readStyle(doc) {
+  const meta = doc.querySelector('meta[name="page-transition-style"]')
+  return meta ? meta.content : null
+}
+
 let installed = false
 
 export function installPageTransitions(doc) {
@@ -193,6 +201,7 @@ export function installPageTransitions(doc) {
     const sharedName = shareName(morphNames(doc), names)
     const style = planVisit({
       direction: readDirection(doc),
+      style: readStyle(doc),
       from,
       to: target,
       transitions: !!doc.startViewTransition && !win.matchMedia(REDUCED_MOTION).matches,
@@ -235,7 +244,7 @@ export function installPageTransitions(doc) {
   // The last moment on the old document. The browser takes its picture after this.
   win.addEventListener("pageswap", (event) => {
     const transition = event.viewTransition
-    const style = transition && planFullLoad({ direction: readDirection(doc), from, activation: event.activation })
+    const style = transition && planFullLoad({ direction: readDirection(doc), style: readStyle(doc), from, activation: event.activation })
     const left = leaveStyle(win, style)
     if (!transition) return
     if (!left) {