studio-engine 0.130.0 → 0.131.0

data/app/javascript/studio/agent_chat.js

@@ -3,7 +3,7 @@
 // app for it (GET /agent_chat/turns, POST /agent_chat/messages), which proxies.
 //
 // The look is the ERB: each turn is a clone of a <template data-agent-chat-template>
-// (studio/agent_chat/_turn), filled with textContent, never HTML.
+// (studio/agent_chat/_turn), filled with text nodes, never HTML (MARKDOWN below).
 //
 //   LOAD     on connect, the thread's latest turns; a failure shows the offline
 //            notice with Try again (and retries itself, slowly).
@@ -38,6 +38,23 @@
 //            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".
+//   OPENER   data-agent-chat-opener on the section: words the chat sends as the
+//            visitor's first message once its thread has loaded, so the agent
+//            starts answering at once (studio/talk_to_agent sets it as its modal
+//            opens). Sent once per data-agent-chat-opener-key per tab
+//            (sessionStorage): opening the same topic again shows the thread and
+//            sends nothing. A send the app refuses puts the words in the box.
+//            A visitor who sends before the thread loads gets the opener posted
+//            first, then their words; it is never dropped and never sent twice.
+//   MARKDOWN an agent turn's words show a small, safe Markdown subset (bold,
+//            italics, code, http(s) links, lists, line breaks), built as nodes,
+//            never HTML; a visitor's words stay plain text (markdownBlocks).
+//   TYPE-IN  data-agent-chat-reveal="true" on the section: an agent answer that
+//            arrives while the chat is open types itself in (revealPlan, about
+//            REVEAL_CPS characters a second, REVEAL_MIN_MS to REVEAL_MAX_MS), as
+//            the hub's agent_reveal does. The thread loaded on open, and every
+//            answer under prefers-reduced-motion, shows at once. While it types
+//            the log is aria-busy, so a screen reader hears the answer once.
 //
 // It imports nothing, so test/javascript/agent_chat.test.mjs loads it as a
 // data: module; studio/controllers/agent_chat_controller mounts it.
@@ -56,6 +73,11 @@ 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"
+export const OPENER_STORAGE_PREFIX = "studio:agent-chat:opener:"
+export const REVEAL_CPS = 420
+export const REVEAL_MIN_MS = 450
+export const REVEAL_MAX_MS = 2600
+export const REVEAL_FRAME_MS = 32
 const UNSETTLED = new Set(["pending", "typing"])
 
 export function settled(turn) {
@@ -127,6 +149,156 @@ export function csrfToken(form, doc = globalThis.document) {
   return meta ? meta.getAttribute("content") : null
 }
 
+// How a new answer of `length` characters types in: its duration in ms, clamped
+// to REVEAL_MIN_MS..REVEAL_MAX_MS, and how many characters show `elapsed` ms in.
+export function revealPlan(length, elapsed) {
+  const total = Math.max(0, Number(length) || 0)
+  const duration = Math.min(REVEAL_MAX_MS, Math.max(REVEAL_MIN_MS, Math.round((total / REVEAL_CPS) * 1000)))
+  const shown = elapsed >= duration ? total : Math.floor((total * Math.max(0, elapsed)) / duration)
+  return { duration, shown }
+}
+
+// The sessionStorage key an opener is remembered under; null with no key.
+export function openerStorageKey(key) {
+  const name = String(key ?? "").trim()
+  return name ? `${OPENER_STORAGE_PREFIX}${name}` : null
+}
+
+// sessionStorage, or null where the browser refuses it (a private window, a
+// sandboxed frame): the opener is then sent on every open.
+function sessionStore() {
+  try { return globalThis.sessionStorage || null } catch (_error) { return null }
+}
+
+function prefersReducedMotion() {
+  try { return Boolean(globalThis.matchMedia && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches) } catch (_error) { return false }
+}
+
+// MARKDOWN: an agent turn's words as a small, safe subset of Markdown, for agent
+// turns only (a visitor's words stay plain text). markdownBlocks is pure: it turns
+// the words into paragraphs and lists of inline pieces. renderMarkdown builds them
+// as DOM nodes with createElement and text nodes, never as HTML, so any other
+// markup in the words shows as the characters it is.
+//
+//   **bold** __bold__   *italics*   `code`   [label](https://…)
+//   "- ", "* ", "+ " and "1. " lines make a list; a leading "> " is dropped;
+//   any other line break stays a line break.
+//
+// A link's target must be http: or https: (SAFE_LINK); anything else shows as
+// its own text. No _underscore_ italics: snake_case words are common in answers,
+// and the regex stays free of lookbehind, which older Safari cannot parse.
+export const SAFE_LINK = /^https?:\/\/[^\s<>"'`]+$/i
+const INLINE = /\*\*([^\s*](?:[^\n]*?[^\s*])?)\*\*|__([^\s_](?:[^\n]*?[^\s_])?)__|\[([^\]\n]+)\]\(([^()\s]+)\)|`([^`\n]+)`|\*([^*\s](?:[^*\n]*?[^*\s])?)\*/g
+const BULLET = /^\s{0,3}[-*+]\s+(.*)$/
+const NUMBERED = /^\s{0,3}\d{1,3}[.)]\s+(.*)$/
+const QUOTE = /^\s{0,3}>\s?/
+
+export function safeHref(url) {
+  const href = String(url ?? "").trim()
+  if (!SAFE_LINK.test(href)) return null
+  try {
+    const parsed = new URL(href)
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? href : null
+  } catch (_error) { return null }
+}
+
+// Inline pieces: {text} | {strong: [...]} | {em: [...]} | {code} | {link, href}.
+export function markdownInline(text) {
+  const pieces = []
+  const words = String(text ?? "")
+  let at = 0
+  // A fresh regex per call: bold and italics recurse, and a shared /g regex's
+  // lastIndex would jump.
+  const inline = new RegExp(INLINE.source, "g")
+  for (let match = inline.exec(words); match; match = inline.exec(words)) {
+    const [whole, bold, bold2, label, url, code, em] = match
+    let piece = null
+    if (bold != null || bold2 != null) piece = { strong: markdownInline(bold ?? bold2) }
+    else if (label != null) { const href = safeHref(url); if (href) piece = { link: label, href } }
+    else if (code != null) piece = { code }
+    else piece = { em: markdownInline(em) }
+    if (!piece) continue
+    if (match.index > at) pieces.push({ text: words.slice(at, match.index) })
+    pieces.push(piece)
+    at = match.index + whole.length
+  }
+  if (at < words.length) pieces.push({ text: words.slice(at) })
+  return pieces
+}
+
+// Blocks: {lines: [inline, ...]} for a run of text lines, {list: "ul"|"ol", items: [inline, ...]}.
+export function markdownBlocks(text) {
+  const blocks = []
+  for (const raw of String(text ?? "").split(/\r?\n/)) {
+    const line = raw.replace(QUOTE, "")
+    const bullet = line.match(BULLET)
+    const numbered = bullet ? null : line.match(NUMBERED)
+    const kind = bullet ? "ul" : numbered ? "ol" : null
+    const last = blocks.at(-1)
+    if (kind) {
+      const item = markdownInline((bullet || numbered)[1])
+      if (last && last.list === kind) last.items.push(item)
+      else blocks.push({ list: kind, items: [item] })
+    } else if (last && last.lines) {
+      last.lines.push(markdownInline(line))
+    } else {
+      blocks.push({ lines: [markdownInline(line)] })
+    }
+  }
+  return blocks
+}
+
+function inlineNodes(d, pieces) {
+  return pieces.map((piece) => {
+    if (piece.text != null) return d.createTextNode(piece.text)
+    if (piece.code != null) { const el = d.createElement("code"); el.textContent = piece.code; return el }
+    if (piece.link != null) {
+      const el = d.createElement("a")
+      el.setAttribute("href", piece.href)
+      el.setAttribute("target", "_blank")
+      el.setAttribute("rel", "noopener noreferrer nofollow")
+      el.style.textDecoration = "underline"
+      el.textContent = piece.link
+      return el
+    }
+    const el = d.createElement(piece.strong ? "strong" : "em")
+    el.append(...inlineNodes(d, piece.strong || piece.em))
+    return el
+  })
+}
+
+// Fills `el` with the words as Markdown nodes. Where the element cannot build
+// nodes (no document), the words go in as text, as before.
+export function renderMarkdown(el, words, doc = globalThis.document) {
+  const d = (el && el.ownerDocument) || doc
+  if (!el || !d || typeof d.createElement !== "function" || typeof el.replaceChildren !== "function") {
+    if (el) el.textContent = String(words ?? "")
+    return
+  }
+  const nodes = []
+  for (const block of markdownBlocks(words)) {
+    if (block.list) {
+      const list = d.createElement(block.list)
+      list.style.paddingLeft = "1.25rem"
+      list.style.listStyle = block.list === "ul" ? "disc" : "decimal"
+      for (const item of block.items) {
+        const li = d.createElement("li")
+        li.append(...inlineNodes(d, item))
+        list.append(li)
+      }
+      nodes.push(list)
+    } else {
+      // The text keeps its own line breaks (the turn's text is pre-wrap); a list
+      // sits on its own lines, so no break is added next to one.
+      block.lines.forEach((line, index) => {
+        if (index > 0) nodes.push(d.createTextNode("\n"))
+        nodes.push(...inlineNodes(d, line))
+      })
+    }
+  }
+  el.replaceChildren(...nodes)
+}
+
 export function turnsUrl(base, { soul, after, limit = LIMIT }) {
   const params = new URLSearchParams({ soul, limit: String(limit) })
   if (after != null) params.set("after", after)
@@ -139,7 +311,9 @@ export function mountAgentChat(root, {
   now = () => Date.now(),
   setTimer = (fn, ms) => globalThis.setTimeout(fn, ms),
   clearTimer = (id) => globalThis.clearTimeout(id),
-  CustomEventClass = globalThis.CustomEvent
+  CustomEventClass = globalThis.CustomEvent,
+  storage = sessionStore(),
+  reducedMotion = prefersReducedMotion
 } = {}) {
   const $ = (selector) => root.querySelector(selector)
   const log = $("[data-agent-chat-log]")
@@ -154,8 +328,11 @@ export function mountAgentChat(root, {
   const status = $("[data-agent-chat-status]")
   const soul = root.dataset.agentChatSoul
   const name = root.dataset.agentChatName || "The agent"
+  const opener = String(root.dataset.agentChatOpener || "").trim()
+  const openerKey = openerStorageKey(root.dataset.agentChatOpenerKey)
+  const typeIn = root.dataset.agentChatReveal === "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 state = { turns: [], pending: false, waitingSince: null, offline: false, inFlight: false, pollAgain: false, sending: false, timer: null, alive: true, following: true, revealFollowing: true, revealOwed: false, loaded: false, typing: new Map(), openerPhase: "owed", openerPost: null }
 
   const onScroll = () => { state.following = isFollowing(log) }
   log.addEventListener("scroll", onScroll, { passive: true })
@@ -237,7 +414,14 @@ export function mountAgentChat(root, {
       }
       node.dataset.status = turn.status || ""
       const text = node.querySelector("[data-agent-chat-text]")
-      if (text && text.textContent !== String(turn.text ?? "")) text.textContent = String(turn.text ?? "")
+      const words = String(turn.text ?? "")
+      const agent = turn.role === "agent"
+      if (text && state.typing.has(key)) {
+        if (state.typing.get(key).words !== words) { stopTyping(key); showWords(text, words, agent) }
+      } else if (text && shownWords(text, agent) !== words) {
+        if (typeIn && state.loaded && agent && words && !reducedMotion()) startTyping(key, text, words)
+        else showWords(text, words, agent)
+      }
       const failed = node.querySelector("[data-agent-chat-failed]")
       if (failed) failed.hidden = turn.status !== "failed"
       const held = node.querySelector("[data-agent-chat-held]")
@@ -252,6 +436,48 @@ export function mountAgentChat(root, {
     }
   }
 
+  // What a turn's text element shows: an agent's words as Markdown, a visitor's
+  // as text. `shown` remembers the words behind each element, since an agent's
+  // rendered text no longer reads back as its Markdown.
+  const shown = new WeakMap()
+  function showWords(el, words, agent) {
+    shown.set(el, words)
+    if (agent) renderMarkdown(el, words, doc)
+    else el.textContent = words
+  }
+  // An agent turn the page rendered itself (studio/agent_chat/_turn prints raw
+  // words) has no entry, so it is rendered once as Markdown.
+  function shownWords(el, agent) {
+    if (shown.has(el)) return shown.get(el)
+    return agent ? null : el.textContent
+  }
+
+  // TYPE-IN: one answer's words, filled in REVEAL_FRAME_MS steps.
+  function startTyping(key, el, words) {
+    const started = now()
+    const entry = { words, timer: null }
+    state.typing.set(key, entry)
+    showWords(el, "", true)
+    if (log && log.setAttribute) log.setAttribute("aria-busy", "true")
+    const step = () => {
+      if (!state.alive || state.typing.get(key) !== entry) return
+      const { shown: count } = revealPlan(words.length, now() - started)
+      showWords(el, words.slice(0, count), true)
+      if (state.following) toEnd()
+      if (count >= words.length) { stopTyping(key); return }
+      entry.timer = setTimer(step, REVEAL_FRAME_MS)
+    }
+    step()
+  }
+
+  function stopTyping(key) {
+    const entry = state.typing.get(key)
+    if (!entry) return
+    clearTimer(entry.timer)
+    state.typing.delete(key)
+    if (!state.typing.size && log && log.removeAttribute) log.removeAttribute("aria-busy")
+  }
+
   function schedule() {
     if (!state.alive) return
     clearTimer(state.timer)
@@ -276,6 +502,10 @@ export function mountAgentChat(root, {
       state.pending = data.pending === true
       setOffline(false)
       render()
+      if (!state.loaded) {
+        state.loaded = true
+        sendOpener()
+      }
     } catch (_error) {
       setOffline(true)
     } finally {
@@ -315,10 +545,64 @@ export function mountAgentChat(root, {
     refresh(event.detail || {})
   }
 
+  // OPENER: the section's opener, once per key per tab. It goes once the thread
+  // has loaded, or at once, AHEAD of the visitor's words, when they send before the
+  // thread loads (submit). The tab remembers it as its POST starts (so a chat
+  // mounted again mid-flight cannot send it twice) and forgets it if that POST
+  // fails; nothing marks it without posting it. While another send is in flight it
+  // stays owed, unmarked, and the next send carries it first.
+  function sendOpener() {
+    if (!opener || state.openerPhase !== "owed") return state.openerPost || undefined
+    if (openerKey && storage) {
+      try {
+        if (storage.getItem(openerKey)) { state.openerPhase = "done"; return undefined }
+      } catch (_error) { /* a refused store sends it anyway */ }
+    }
+    // The thread already ends with these words from the visitor (another tab
+    // sent them): showing it is enough.
+    const last = state.turns.filter((turn) => turn.role !== "agent").at(-1)
+    if (last && String(last.text ?? "").trim() === opener) { state.openerPhase = "done"; return undefined }
+    if (state.sending) return undefined
+    state.openerPhase = "posting"
+    if (openerKey && storage) {
+      try { storage.setItem(openerKey, "1") } catch (_error) { /* a refused store sends it anyway */ }
+    }
+    state.openerPost = post(opener, { typed: false }).finally(() => {
+      state.openerPhase = "done"
+      state.openerPost = null
+    })
+    return state.openerPost
+  }
+
+  function forgetOpener() {
+    if (!openerKey || !storage) return
+    try { storage.removeItem(openerKey) } catch (_error) { /* nothing to forget */ }
+  }
+
+  // A refused or failed opener goes into the box, after anything already typed,
+  // so the visitor can send it themselves.
+  function keepWords(text) {
+    if (!input) return
+    const typed = (input.value || "").trim()
+    input.value = typed ? `${typed} ${text}` : text
+  }
+
   async function submit(event) {
     if (event) event.preventDefault()
     const text = (input.value || "").trim()
-    if (!text || state.sending) return
+    if (!text) return
+    // The opener goes first, even before the thread has loaded, and a send
+    // waits for an opener already on its way: the visitor's words are never
+    // dropped for it, and they always follow it.
+    if (state.openerPhase === "owed") await sendOpener()
+    if (state.openerPost) await state.openerPost
+    if (state.sending) return
+    await post(text, { typed: true })
+  }
+
+  // One message to the app: the composer's words (typed) or the opener.
+  async function post(text, { typed }) {
+    if (state.sending) return
     state.sending = true
     if (send) send.disabled = true
     showError("")
@@ -333,7 +617,7 @@ export function mountAgentChat(root, {
       let data = {}
       try { data = await response.json() } catch (_e) { data = {} }
       if (response.status === 201 && data.turn) {
-        input.value = ""
+        if (typed) input.value = ""
         state.turns = mergeTurns(state.turns, [data.turn])
         state.pending = data.turn.status !== "held"
         state.following = true
@@ -347,10 +631,12 @@ export function mountAgentChat(root, {
         clearTimer(state.timer)
         state.timer = setTimer(poll, POLL_MS)
       } else {
+        if (!typed) { forgetOpener(); keepWords(text) }
         showError(data.reason === INVALID_TOKEN ? EXPIRED_MESSAGE : data.error || `Couldn't send that to ${name}. Try again.`)
         if (status) status.textContent = ""
       }
     } catch (_error) {
+      if (!typed) { forgetOpener(); keepWords(text) }
       showError(`Can't reach ${name} right now. Your message is still here; try again in a moment.`)
       if (status) status.textContent = ""
     } finally {
@@ -391,9 +677,11 @@ export function mountAgentChat(root, {
     poll,
     refresh,
     submit,
+    sendOpener,
     destroy() {
       state.alive = false
       clearTimer(state.timer)
+      for (const key of Array.from(state.typing.keys())) stopTyping(key)
       log.removeEventListener("scroll", onScroll)
       form && form.removeEventListener("submit", submit)
       input && input.removeEventListener("keydown", onKeydown)

data/app/javascript/studio/carousel.js

@@ -0,0 +1,99 @@
+// studio/carousel: the arithmetic behind studio/_carousel. The track is a native
+// scroll-snap row, so a swipe, a trackpad and a focused link all move it with no
+// script; studio/controllers/carousel_controller only reads where the row is and
+// moves it for the arrows, the dots and the keyboard.
+//
+// A STOP is a place the row can rest: the start of a slide, until the row can
+// scroll no further, and then its end. Six slides three to a view rest at four
+// stops, so the dots past the last stop are hidden.
+//
+// It imports nothing; test/javascript/carousel.test.mjs loads it as a data: module.
+
+// Within this many pixels of an end counts as at it: a zoomed page scrolls in
+// fractions.
+export const TOLERANCE = 2
+
+// Which ends of the row hide a slide.
+export function hiddenEnds({ scrollLeft, clientWidth, scrollWidth }) {
+  const max = Math.max(0, scrollWidth - clientWidth)
+  return { start: scrollLeft > TOLERANCE, end: scrollLeft < max - TOLERANCE }
+}
+
+// The scroll position of each stop, from each slide's offset and the row's
+// furthest scroll. The slides past the last stop share it.
+export function stops(offsets, max) {
+  const reachable = offsets.filter((offset) => offset < max - TOLERANCE)
+  if (reachable.length === offsets.length) return reachable.length ? reachable : [0]
+  return [...reachable, max]
+}
+
+// The stop the row rests at, or is nearest to while it moves.
+export function currentStop(scrollLeft, positions) {
+  if (positions.length === 0) return 0
+  const last = positions.length - 1
+  if (scrollLeft >= positions[last] - TOLERANCE) return last
+
+  let nearest = 0
+  positions.forEach((position, index) => {
+    if (Math.abs(position - scrollLeft) < Math.abs(positions[nearest] - scrollLeft)) nearest = index
+  })
+  return nearest
+}
+
+// How many whole slides a view shows: an arrow moves the row by that many, so
+// the slide that peeked in at the edge is the first one after the press.
+export function perPage(clientWidth, slideWidth, gap) {
+  if (!(slideWidth > 0)) return 1
+  return Math.max(1, Math.floor((clientWidth + gap + TOLERANCE) / (slideWidth + gap)))
+}
+
+// The stop an arrow or a key takes the row to, held to the first and last stop.
+export function targetStop(action, current, page, count) {
+  const last = Math.max(0, count - 1)
+  const to = {
+    prev: current - page,
+    next: current + page,
+    first: 0,
+    last
+  }[action]
+  if (to === undefined) return current
+  return Math.min(last, Math.max(0, to))
+}
+
+// Keys inside these belong to the element, not the row: a form field, and a widget
+// that moves its own selection with the arrow keys.
+export const KEY_OWNERS = [
+  "input", "textarea", "select", "[contenteditable]:not([contenteditable='false'])",
+  "[role='slider']", "[role='spinbutton']", "[role='listbox']", "[role='combobox']",
+  "[role='tablist']", "[role='radiogroup']", "[role='menu']", "[role='menubar']",
+  "[role='grid']", "[role='tree']", "[role='treegrid']", "video", "audio"
+].join(", ")
+
+// Whether a key pressed on `target` is the carousel `region`'s to handle: not
+// when the target sits in a key owner, or in a carousel nested inside this one,
+// which handles its own keys.
+export function ownsKey(target, region, carousel = ".carousel") {
+  if (!target?.closest) return false
+  if (target.closest(KEY_OWNERS)) return false
+  return target.closest(carousel) === region
+}
+
+// The action a key asks for, or null for a key the carousel leaves alone.
+export function keyAction(key) {
+  return { ArrowLeft: "prev", ArrowRight: "next", Home: "first", End: "last" }[key] || null
+}
+
+// The words the status line reads after a move: "Slides 4 to 6 of 9".
+export function positionText(first, shown, total) {
+  const from = first + 1
+  const to = Math.min(total, first + shown)
+  return from === to ? `Slide ${from} of ${total}` : `Slides ${from} to ${to} of ${total}`
+}
+
+// The spotlight's stops: the scroll position that centres each slide, from each
+// slide's offset and width in the track (its padding included), held to the row.
+// Every slide is a stop, so every dot shows and an arrow moves one slide.
+export function centerStops(slides, clientWidth, max) {
+  if (slides.length === 0) return [0]
+  return slides.map(({ left, width }) => Math.min(max, Math.max(0, left + width / 2 - clientWidth / 2)))
+}

data/app/javascript/studio/controllers/carousel_controller.js

@@ -0,0 +1,138 @@
+// carousel: the arrows, dots and keys of studio/_carousel. The track is a native
+// scroll-snap row, so a swipe, a trackpad and a focused link move it with no
+// script; this controller reads where the row rests and moves it on request.
+//
+//   <section class="carousel" data-studio-controller="carousel" ...>
+//     <div class="carousel-track" data-carousel-target="track">slides</div>
+//     <div class="carousel-controls">dots, prev, next</div>
+//   </section>
+//
+// It marks the ends that hide a slide (the edge fade), sets aria-disabled on an
+// arrow at its end, hides the dots past the last stop, and says where the row
+// went in a polite status line, but only after a press: a swipe announces nothing.
+//
+// A lazy controller (studio/stimulus): only a page with a carousel fetches it.
+// Until it connects the controls stay hidden and the row keeps a thin scrollbar,
+// so a carousel whose controller failed is still a row that scrolls.
+//
+// A SPOTLIGHT row (class carousel-spotlight) snaps each slide to the centre: every
+// slide is a stop, an arrow moves one slide, and the slide nearest the centre
+// carries data-current, which the CSS styles where scroll-driven animations are
+// missing and under reduced motion.
+import { centerStops } from "studio/carousel"
+import { Controller } from "@hotwired/stimulus"
+import { currentStop, hiddenEnds, keyAction, ownsKey, perPage, positionText, stops, targetStop } from "studio/carousel"
+
+export default class extends Controller {
+  static targets = ["track", "slide", "prev", "next", "dot", "status"]
+
+  connect() {
+    this.schedule = this.schedule.bind(this)
+    this.trackTarget.addEventListener("scroll", this.schedule, { passive: true })
+    if (typeof ResizeObserver === "function") {
+      this.observer = new ResizeObserver(this.schedule)
+      this.observer.observe(this.trackTarget)
+    }
+    this.element.setAttribute("data-carousel-ready", "")
+    this.sync()
+  }
+
+  disconnect() {
+    this.trackTarget.removeEventListener("scroll", this.schedule)
+    this.observer?.disconnect()
+    if (this.frame) cancelAnimationFrame(this.frame)
+    this.frame = null
+  }
+
+  schedule() {
+    if (this.frame) return
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null
+      this.sync()
+    })
+  }
+
+  measure() {
+    const track = this.trackTarget
+    const slides = this.slideTargets
+    if (this.element.classList.contains("carousel-spotlight")) {
+      const max = Math.max(0, track.scrollWidth - track.clientWidth)
+      const boxes = slides.map((slide) => ({ left: slide.offsetLeft, width: slide.offsetWidth }))
+      return { positions: centerStops(boxes, track.clientWidth, max), page: 1 }
+    }
+    const origin = slides[0]?.offsetLeft || 0
+    const max = Math.max(0, track.scrollWidth - track.clientWidth)
+    const gap = parseFloat(getComputedStyle(track).columnGap) || 0
+    return {
+      positions: stops(slides.map((slide) => slide.offsetLeft - origin), max),
+      page: perPage(track.clientWidth, slides[0]?.offsetWidth, gap)
+    }
+  }
+
+  sync() {
+    const track = this.trackTarget
+    const { positions, page } = this.measure()
+    const ends = hiddenEnds(track)
+
+    this.positions = positions
+    this.page = page
+    this.current = currentStop(track.scrollLeft, positions)
+
+    this.element.toggleAttribute("data-carousel-static", positions.length < 2)
+    track.toggleAttribute("data-fade-start", ends.start)
+    track.toggleAttribute("data-fade-end", ends.end)
+    if (this.hasPrevTarget) this.prevTarget.setAttribute("aria-disabled", String(!ends.start))
+    if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!ends.end))
+    if (this.element.classList.contains("carousel-spotlight")) {
+      this.slideTargets.forEach((slide, index) => slide.toggleAttribute("data-current", index === this.current))
+    }
+    this.dotTargets.forEach((dot, index) => {
+      dot.hidden = index >= positions.length
+      if (index === this.current) dot.setAttribute("aria-current", "true")
+      else dot.removeAttribute("aria-current")
+    })
+  }
+
+  prev() { this.move("prev") }
+
+  next() { this.move("next") }
+
+  goTo(event) {
+    this.sync()
+    this.scrollToStop(Number(event.currentTarget.dataset.carouselIndex))
+  }
+
+  key(event) {
+    // A form field, a widget that owns the arrow keys, or a nested carousel keeps them.
+    if (!ownsKey(event.target, this.element)) return
+    // Alt+Left is Back, Cmd+Left a line start: a held modifier leaves the key alone.
+    if (event.altKey || event.metaKey || event.ctrlKey || event.shiftKey) return
+    const action = keyAction(event.key)
+    if (!action) return
+    event.preventDefault()
+    this.move(action)
+  }
+
+  // A press that goes nowhere (an arrow at its end, Home at the start) scrolls
+  // nothing and says nothing: the status line speaks only when the row moves.
+  move(action) {
+    this.sync()
+    const to = targetStop(action, this.current, this.page, this.positions.length)
+    if (to === this.current) return
+    this.scrollToStop(to)
+  }
+
+  scrollToStop(index) {
+    const left = this.positions[index]
+    if (left === undefined) return
+
+    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+    this.trackTarget.scrollTo({ left, behavior: reduce ? "auto" : "smooth" })
+
+    if (!this.hasStatusTarget) return
+    const total = this.slideTargets.length
+    const last = index === this.positions.length - 1
+    const first = last ? Math.max(0, total - this.page) : index
+    this.statusTarget.textContent = positionText(first, this.page, total)
+  }
+}

data/app/javascript/studio/controllers/infinite_scroll_controller.js

@@ -0,0 +1,17 @@
+// infinite-scroll: the next page of a list loads as its end comes near, on the
+// engine's Stimulus application (studio/stimulus registers it lazily). It sits
+// on studio_infinite_scroll's wrapper. The behaviour is studio/infinite_scroll.
+// If this controller fails to load, "Load more" is still a working link.
+import { Controller } from "@hotwired/stimulus"
+import { watchInfiniteScroll } from "studio/infinite_scroll"
+
+export default class extends Controller {
+  connect() {
+    this.stop = watchInfiniteScroll(this.element, window)
+  }
+
+  disconnect() {
+    if (this.stop) this.stop()
+    this.stop = null
+  }
+}

data/app/javascript/studio/controllers/pull_to_refresh_controller.js

@@ -0,0 +1,18 @@
+// pull-to-refresh: pull the page down from its top to reload it, on phones with
+// touch only (studio/pull_to_refresh decides). On the engine's Stimulus
+// application (studio/stimulus registers it lazily); it sits on
+// studio_pull_to_refresh's wrapper. If it fails to load, nothing on the page
+// depends on it: the browser's own reload still works.
+import { Controller } from "@hotwired/stimulus"
+import { watchPullToRefresh } from "studio/pull_to_refresh"
+
+export default class extends Controller {
+  connect() {
+    this.stop = watchPullToRefresh(this.element, window, document)
+  }
+
+  disconnect() {
+    if (this.stop) this.stop()
+    this.stop = null
+  }
+}