studio-engine 0.122.0 → 0.124.0

data/app/javascript/studio/agent_chat_voice.js

@@ -0,0 +1,318 @@
+// studio/agent_chat_voice: hold to talk in the shared agent chat's composer
+// (studio/agent_chat/_voice; docs/AGENT_CHAT.md, "Talking by voice").
+//
+// THE FLOW, for one take the engine recorder hands over
+// (studio:voice-recorder:take {blob, mimeType, durationMs}):
+//
+//   1. embed it ON THIS DEVICE when the page names an embedder (the person has
+//      a saved voice; data-agent-chat-voice-embedder is the /profile voice row's
+//      own config), with studio/voice_profile's embedderFor. Any failure, or a
+//      model slower than EMBED_WAIT_MS, sends the take without a vector: the
+//      server then answers "Someone new" (check no_embedding), never an error.
+//   2. POST it to /voice/takes (multipart, X-CSRF-Token), which answers
+//      {text, speaker, score, identified, check, duration_ms} and keeps nothing.
+//   3. send `text` to the chat's own form action with `voice` {check, score,
+//      duration_ms} and hand the turn to the chat (its public refresh hook,
+//      studio:agent-chat:refresh), so the turn and the typing line appear. The
+//      browser never sends a name: the server names the speaker, and the line
+//      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.
+//
+// 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
+// being turned into words waits its turn, in order, and the line says so.
+//
+// It imports nothing at load (studio/voice_profile, and the model behind it, only
+// when a person with a saved voice talks), so test/javascript/agent_chat_voice.test.mjs
+// loads it as a data: module.
+
+export const EMBED_WAIT_MS = 8000
+
+export const MESSAGES = {
+  listening: "Listening...",
+  transcribing: "Turning that into words...",
+  queued: "Got that one too. It's next.",
+  sending: (name) => `Sending to ${name}...`,
+  sent: (speaker) => `Sent. Spoken by ${speaker}.`,
+  sentPlain: "Sent.",
+  silent: (label) => `I couldn't hear anything${label ? ` from ${label}` : ""}. Check your microphone and hold to talk again.`,
+  noSpeech: "I couldn't hear any words in that. Check your microphone and try again.",
+  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.",
+  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.",
+  notSent: (name) => `Couldn't send that to ${name}. Your words are in the box; press send to try again.`
+}
+
+// "Try again in 40 seconds." from a Retry-After header or a retry_after field.
+export function retryHint(seconds) {
+  const n = Math.round(Number(seconds))
+  if (!Number.isFinite(n) || n <= 0) return ""
+  if (n < 60) return ` Try again in ${n} second${n === 1 ? "" : "s"}.`
+  const minutes = Math.ceil(n / 60)
+  return ` Try again in ${minutes} minute${minutes === 1 ? "" : "s"}.`
+}
+
+// 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 (status === 429) {
+    return { state: "rate_limited", message: MESSAGES.rateLimited + retryHint(retryAfter ?? (body && body.retry_after)) }
+  }
+  if (status === 422 && body && body.reason === "no_speech") return { state: "no_speech", message: said || MESSAGES.noSpeech }
+  if (status === 503 && body && body.reason === "not_configured") return { state: "not_configured", message: said || MESSAGES.notConfigured }
+  if (status === 503) return { state: "failed", message: said || MESSAGES.unavailable }
+  if ([403, 413, 415, 422].includes(status)) return { state: "refused", message: said || MESSAGES.failed }
+  return { state: "failed", message: MESSAGES.failed }
+}
+
+// The message's `voice`, from a 200 answer: what the take measured, never a name.
+export function voiceMetadata(answer = {}) {
+  const score = typeof answer.score === "number" && Number.isFinite(answer.score) ? answer.score : null
+  const duration = Number.isInteger(answer.duration_ms) ? answer.duration_ms : null
+  return { check: String(answer.check || "no_embedding"), score, duration_ms: duration }
+}
+
+// The multipart body POST /voice/takes reads (docs/VOICE_TRANSCRIPTION.md).
+export function takeForm(detail, { embedding = null, model = null } = {}, FormDataClass = globalThis.FormData) {
+  const form = new FormDataClass()
+  form.append("voice[audio]", detail.blob, "take")
+  if (detail.mimeType) form.append("voice[mime_type]", detail.mimeType)
+  form.append("voice[duration_ms]", String(Math.max(1, Math.round(Number(detail.durationMs) || 0))))
+  if (Array.isArray(embedding) && embedding.length && model) {
+    form.append("voice[embedding]", JSON.stringify(embedding))
+    form.append("voice[model]", model)
+  }
+  return form
+}
+
+export function parseEmbedder(text) {
+  if (!text) return null
+  try {
+    const config = JSON.parse(text)
+    return config && config.name && config.id ? config : null
+  } catch (_) {
+    return null
+  }
+}
+
+// The words in the box, after anything already there: a person's draft is theirs.
+export function wordsInBox(current, text) {
+  return current && current.trim() ? `${current.trimEnd()}\n${text}` : text
+}
+
+// The page's token (csrf_meta_tags), else the chat form's. In that order: the
+// meta tag's is good for any action, and the form's is per-form under
+// load_defaults 8.1, bound to POST /agent_chat/messages, so POST /voice/takes
+// refuses it.
+export function csrfToken(form, doc = globalThis.document) {
+  const meta = doc && doc.querySelector("meta[name='csrf-token']")
+  const content = meta && meta.getAttribute("content")
+  if (content) return content
+  const field = form && form.querySelector("input[name='authenticity_token']")
+  return field && field.value ? field.value : null
+}
+
+// Resolves to `promise`'s value, or `fallback` once `ms` have passed.
+export function within(promise, ms, fallback = null, setTimer = (fn, t) => globalThis.setTimeout(fn, t)) {
+  return Promise.race([promise, new Promise((resolve) => setTimer(() => resolve(fallback), ms))])
+}
+
+async function readJson(response) {
+  try { return await response.json() } catch (_) { return {} }
+}
+
+// Mounts one voice section, which sits inside the chat's form. Returns
+// { takeArrived, destroy } for tests.
+export function mountAgentChatVoice(root, {
+  fetch: fetcher = (...args) => globalThis.fetch(...args),
+  doc = globalThis.document,
+  loadEmbedder = async (config) => {
+    const { embedderFor } = await import("studio/voice_profile")
+    return embedderFor(config)
+  },
+  setTimer = (fn, ms) => globalThis.setTimeout(fn, ms),
+  FormDataClass = globalThis.FormData,
+  CustomEventClass = globalThis.CustomEvent
+} = {}) {
+  const status = root.querySelector("[data-agent-chat-voice-status]")
+  const form = root.closest("[data-agent-chat-form]")
+  const chat = root.closest("[data-agent-chat-soul]")
+  const name = root.dataset.agentChatVoiceName || "the agent"
+  const soul = root.dataset.agentChatVoiceSoul
+  const embedders = new Map()
+  const waiting = []
+  let working = false
+  let alive = true
+
+  function say(state, message) {
+    root.dataset.agentChatVoiceState = state
+    if (status) status.textContent = message || ""
+  }
+
+  function embedder() {
+    const config = parseEmbedder(root.getAttribute("data-agent-chat-voice-embedder"))
+    if (!config) return Promise.resolve(null)
+    if (!embedders.has(config.id)) {
+      const loading = Promise.resolve().then(() => loadEmbedder(config)).catch(() => null)
+      embedders.set(config.id, loading)
+      loading.then((loaded) => { if (!loaded) embedders.delete(config.id) })
+    }
+    return embedders.get(config.id)
+  }
+
+  async function embed(blob) {
+    try {
+      const loaded = await within(embedder(), EMBED_WAIT_MS, null, setTimer)
+      if (!loaded) return {}
+      const vector = await within(loaded.embed(blob), EMBED_WAIT_MS, null, setTimer)
+      return Array.isArray(vector) && vector.length ? { embedding: vector, model: loaded.id } : {}
+    } catch (_) {
+      return {}
+    }
+  }
+
+  function keepWords(text) {
+    const input = form && form.querySelector("[data-agent-chat-input]")
+    if (input) input.value = wordsInBox(input.value, text)
+  }
+
+  function headers(extra = {}) {
+    const token = csrfToken(form, doc)
+    return { Accept: "application/json", ...extra, ...(token ? { "X-CSRF-Token": token } : {}) }
+  }
+
+  async function send(answer) {
+    if (!form) {
+      say("failed", MESSAGES.notSent(name))
+      return
+    }
+    say("sending", MESSAGES.sending(name))
+    let response
+    try {
+      response = await fetcher(form.getAttribute("action"), {
+        method: "POST", headers: headers({ "Content-Type": "application/json" }), credentials: "same-origin",
+        body: JSON.stringify({ soul, text: answer.text, voice: voiceMetadata(answer) })
+      })
+    } catch (_) {
+      keepWords(answer.text)
+      say("failed", MESSAGES.notSent(name))
+      return
+    }
+    const data = await readJson(response)
+    if (response.status === 201 && data.turn) {
+      // The speaker the server kept, which is what the agent is told.
+      const kept = data.voice && typeof data.voice.speaker === "string" ? data.voice.speaker : null
+      say("sent", kept ? MESSAGES.sent(kept) : MESSAGES.sentPlain)
+      if (chat) chat.dispatchEvent(new CustomEventClass("studio:agent-chat:refresh", { detail: { turn: data.turn } }))
+      return
+    }
+    keepWords(answer.text)
+    const reason = typeof data.error === "string" && data.error ? `${data.error} ` : ""
+    say(response.status === 429 ? "rate_limited" : "failed", `${reason}${MESSAGES.notSent(name)}`)
+  }
+
+  async function handleTake(detail) {
+    say("transcribing", MESSAGES.transcribing)
+    const vector = await embed(detail.blob)
+    let response
+    try {
+      response = await fetcher(root.dataset.agentChatVoiceTakesUrl || "/voice/takes", {
+        method: "POST", headers: headers(), credentials: "same-origin", body: takeForm(detail, vector, FormDataClass)
+      })
+    } catch (_) {
+      say("failed", MESSAGES.offline)
+      return
+    }
+    const body = await readJson(response)
+    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)
+      return
+    }
+    await send(body)
+  }
+
+  // One take at a time, in the order they were spoken. Resolves when the queue
+  // has drained, so a test can await it.
+  async function takeArrived(detail) {
+    if (working) {
+      waiting.push(detail)
+      say("queued", MESSAGES.queued)
+      return
+    }
+    working = true
+    try {
+      let next = detail
+      while (next && alive) {
+        await handleTake(next)
+        next = waiting.shift()
+      }
+    } finally {
+      working = false
+    }
+  }
+
+  function onTake(event) {
+    if (event.detail && event.detail.blob) takeArrived(event.detail)
+  }
+
+  // The one line for a silent take, naming the microphone (the recorder's own
+  // line for it is hidden in the composer, studio/agent_chat/_voice).
+  function onSilent(event) {
+    say("silent", MESSAGES.silent(event.detail && event.detail.microphone && event.detail.microphone.label))
+  }
+
+  // The recorder's state, on the one line: a new hold replaces whatever the last
+  // take left there ("Sent.", a refusal). A take still in hand speaks over it
+  // when it lands. Starting the model download here gets it ready while the
+  // person is still talking.
+  function onState(event) {
+    const next = event.detail && event.detail.state
+    if (next === "starting") {
+      say("idle", "")
+    } else if (next === "recording") {
+      say("listening", MESSAGES.listening)
+      embedder().then((loaded) => loaded && loaded.warm && loaded.warm()).catch(() => {})
+    } else if (root.dataset.agentChatVoiceState === "listening") {
+      say(working ? "transcribing" : "idle", working ? MESSAGES.transcribing : "")
+    }
+  }
+
+  // "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) {
+    const text = event.detail && event.detail.text
+    if (text) say("listening", text)
+    // Heard after the quiet hint: the recorder's "heard" is blank here, so this takes
+    // "I can't hear anything yet" back. No write when the line already says it.
+    else if (root.dataset.agentChatVoiceState === "listening" && status && status.textContent !== MESSAGES.listening) say("listening", MESSAGES.listening)
+  }
+
+  // A Turbo restore brings back whatever the line last said, with no take behind it.
+  say("idle", "")
+
+  root.addEventListener("studio:voice-recorder:take", onTake)
+  root.addEventListener("studio:voice-recorder:silent", onSilent)
+  root.addEventListener("studio:voice-recorder:state", onState)
+  root.addEventListener("studio:voice-recorder:hint", onHint)
+
+  return {
+    takeArrived,
+    destroy() {
+      alive = false
+      root.removeEventListener("studio:voice-recorder:take", onTake)
+      root.removeEventListener("studio:voice-recorder:silent", onSilent)
+      root.removeEventListener("studio:voice-recorder:state", onState)
+      root.removeEventListener("studio:voice-recorder:hint", onHint)
+    }
+  }
+}

data/app/javascript/studio/alpine_shims.js

@@ -25,7 +25,7 @@ import {
 } from "studio/head_chrome"
 import { studioBoard, loadSortable, sortableShim } from "studio/board"
 import { levelingActionModal } from "studio/leveling_activity"
-import { themeEditor, dsThemeEditor } from "studio/theme_editor"
+import { dsThemeEditor } from "studio/theme_editor"
 import { emailBannerEditor, emailRecipients } from "studio/email_banner"
 
 // x-data="navCollapse()": the hub's own header. A host that defines its own
@@ -60,9 +60,7 @@ export function installAlpineShims() {
   // it. SortableJS replaces this object when it arrives; a page that loads its
   // own copy (turf-monster's slate page) replaces it the same way.
   if (!window.Sortable) window.Sortable = sortableShim(() => loadSortable())
-  // x-data="themeEditor({...})" (theme_settings/edit) and
   // x-data="dsThemeEditor({...})" (style/_theme). Alpine passes the seed alone.
-  if (!window.themeEditor) window.themeEditor = (seed) => themeEditor(seed)
   if (!window.dsThemeEditor) window.dsThemeEditor = (seed) => dsThemeEditor(seed)
   // x-data="emailBannerEditor({...})" (studio/emails/show) and
   // x-data="emailRecipients({...})" (studio/emails/index).

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

@@ -0,0 +1,17 @@
+// agent-chat-voice: hold to talk in the shared agent chat's composer
+// (studio/agent_chat/_voice), on the engine's Stimulus application (studio/stimulus
+// registers it lazily, the first time a page renders the mic). The take's journey
+// is studio/agent_chat_voice.
+import { Controller } from "@hotwired/stimulus"
+import { mountAgentChatVoice } from "studio/agent_chat_voice"
+
+export default class extends Controller {
+  connect() {
+    this.voice = mountAgentChatVoice(this.element)
+  }
+
+  disconnect() {
+    if (this.voice) this.voice.destroy()
+    this.voice = null
+  }
+}

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

@@ -0,0 +1,63 @@
+// copy-text: one click puts a value on the clipboard, and says so. It sits on the
+// element around the control (studio/marketing_kit/_kit):
+//
+//   <div data-studio-controller="copy-text" data-copy-text-text-value="#8E82FE">
+//     <button type="button" data-studio-action="click->copy-text#copy">...</button>
+//     <span role="status" data-copy-text-target="status"></span>
+//   </div>
+//
+// The status is written only after the browser answers, so "Copied" is never
+// shown for a copy that failed. navigator.clipboard exists only in a secure
+// context and may refuse; the older selection copy then gets one try.
+import { Controller } from "@hotwired/stimulus"
+
+const SHOWN_MS = 1600
+
+// True when `text` reached the clipboard. It never rejects.
+export async function copyToClipboard(text, nav = navigator, doc = document) {
+  try {
+    await nav.clipboard.writeText(text)
+    return true
+  } catch {
+    return selectionCopy(text, doc)
+  }
+}
+
+function selectionCopy(text, doc) {
+  const field = doc.createElement("textarea")
+  field.value = text
+  field.setAttribute("readonly", "")
+  field.style.position = "fixed"
+  field.style.opacity = "0"
+  doc.body.appendChild(field)
+  try {
+    field.select()
+    return doc.execCommand("copy")
+  } catch {
+    return false
+  } finally {
+    field.remove()
+  }
+}
+
+export default class extends Controller {
+  static targets = ["status"]
+  static values = {
+    text: String,
+    copied: { type: String, default: "Copied" },
+    failed: { type: String, default: "Could not copy" }
+  }
+
+  async copy() {
+    const copied = await copyToClipboard(this.textValue)
+    if (!this.hasStatusTarget) return
+
+    this.statusTarget.textContent = copied ? this.copiedValue : this.failedValue
+    clearTimeout(this.timer)
+    this.timer = setTimeout(() => { this.statusTarget.textContent = "" }, SHOWN_MS)
+  }
+
+  disconnect() {
+    clearTimeout(this.timer)
+  }
+}

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

@@ -0,0 +1,60 @@
+// page-header: says when studio/_page_header is stuck, marks which ends of its
+// tabs hide a tab, and shows the open tab on a narrow screen. It sits on the row's
+// sentinel, so the row keeps its data-studio-controller for the page's own.
+//
+//   <div class="page-header-sentinel" data-studio-controller="page-header"></div>
+//   <nav class="page-header sticky" data-pin="page">...</nav>
+//
+// A lazy controller (studio/stimulus): only a page with the row fetches it. The
+// row's tabs are links, so they work without it. If it fails to load, the sentinel
+// carries data-studio-controller-failed and engine.css gives the row its bar at
+// all times, so a stuck row never lays a transparent title over the page.
+import { Controller } from "@hotwired/stimulus"
+import { hiddenEnds, isStuck, revealBy } from "studio/page_header"
+
+export default class extends Controller {
+  connect() {
+    this.row = this.element.nextElementSibling
+    if (!this.row) return
+    this.tabs = this.row.querySelector(".page-header-tabs")
+    this.schedule = this.schedule.bind(this)
+    window.addEventListener("scroll", this.schedule, { passive: true })
+    window.addEventListener("resize", this.schedule, { passive: true })
+    this.tabs?.addEventListener("scroll", this.schedule, { passive: true })
+    this.revealOpenTab()
+    this.sync()
+  }
+
+  disconnect() {
+    window.removeEventListener("scroll", this.schedule)
+    window.removeEventListener("resize", this.schedule)
+    this.tabs?.removeEventListener("scroll", this.schedule)
+    if (this.frame) cancelAnimationFrame(this.frame)
+    this.frame = null
+  }
+
+  schedule() {
+    if (this.frame) return
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null
+      this.sync()
+    })
+  }
+
+  sync() {
+    const stuck = isStuck(this.row.getBoundingClientRect().top, this.element.getBoundingClientRect().top)
+    const ends = this.tabs ? hiddenEnds(this.tabs) : null
+
+    this.row.toggleAttribute("data-stuck", stuck)
+    if (!ends) return
+    this.tabs.toggleAttribute("data-fade-start", ends.start)
+    this.tabs.toggleAttribute("data-fade-end", ends.end)
+  }
+
+  // Moves the tabs only: scrollIntoView would also move the page.
+  revealOpenTab() {
+    const open = this.tabs?.querySelector("[aria-current]")
+    if (!open) return
+    this.tabs.scrollLeft += revealBy(this.tabs.getBoundingClientRect(), open.getBoundingClientRect())
+  }
+}

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

@@ -0,0 +1,80 @@
+// style-section-nav: the style guide's sticky row (style/index). Its tabs follow
+// the section the reader is in, by scroll and by a tab's own jump.
+//
+//   <nav data-studio-controller="style-section-nav">
+//     <div data-style-section-nav-target="scroller">
+//       <a href="#theme" data-style-section-nav-target="link">Theme</a>
+//
+// Registered by studio/style_guide, which only the style guide loads.
+import { Controller } from "@hotwired/stimulus"
+import { activeIndex } from "studio/style_section_nav"
+
+const ACTIVE = "btn-primary"
+const REST = "btn-neutral"
+// A jump lands a section by its scroll-margin (--nav-h + 5rem), read while the
+// header may still be tall; the header then collapses, so the row rises and the
+// section does not. The full margin keeps the clicked section past the line,
+// with the collapse's height to spare, for any later scroll or resize.
+const LINE_SLACK = 80
+
+export default class extends Controller {
+  static targets = ["link", "scroller"]
+
+  connect() {
+    this.schedule = this.schedule.bind(this)
+    window.addEventListener("scroll", this.schedule, { passive: true })
+    window.addEventListener("resize", this.schedule)
+    this.sync()
+  }
+
+  disconnect() {
+    window.removeEventListener("scroll", this.schedule)
+    window.removeEventListener("resize", this.schedule)
+    if (this.frame) cancelAnimationFrame(this.frame)
+    this.frame = null
+  }
+
+  schedule() {
+    if (this.frame) return
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null
+      this.sync()
+    })
+  }
+
+  sync() {
+    const links = this.linkTargets
+    const tops = links.map((link) => {
+      const section = document.getElementById(link.getAttribute("href").slice(1))
+      return section ? section.getBoundingClientRect().top : Infinity
+    })
+    const line = this.element.getBoundingClientRect().bottom + LINE_SLACK
+    const page = document.documentElement
+    const atPageEnd = page.scrollTop > 0 && window.innerHeight + page.scrollTop >= page.scrollHeight - 2
+    this.highlight(links[activeIndex(tops, line, atPageEnd)])
+  }
+
+  highlight(current) {
+    if (!current || current === this.current) return
+    this.current = current
+    this.linkTargets.forEach((link) => {
+      const on = link === current
+      link.classList.toggle(ACTIVE, on)
+      link.classList.toggle(REST, !on)
+      if (on) link.setAttribute("aria-current", "true")
+      else link.removeAttribute("aria-current")
+    })
+    this.reveal(current)
+  }
+
+  // Keeps the active tab in view on a narrow screen. Moves the row only:
+  // scrollIntoView would also move the page the reader is scrolling.
+  reveal(link) {
+    if (!this.hasScrollerTarget) return
+    const row = this.scrollerTarget
+    const box = row.getBoundingClientRect()
+    const tab = link.getBoundingClientRect()
+    if (tab.left < box.left) row.scrollLeft -= box.left - tab.left + 32
+    else if (tab.right > box.right) row.scrollLeft += tab.right - box.right + 32
+  }
+}

data/app/javascript/studio/microphone_chip.js

@@ -325,6 +325,7 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
     if (!target.closest) return
     // A click on the backdrop lands on the dialog element itself.
     if (dialog && target === dialog) { dialog.close(); return }
+    if (dialog && target.closest("[data-microphone-help-close]")) { dialog.close(); return }
     const option = target.closest("[data-microphone-option]")
     if (option && root.contains(option)) { pick(option); return }
     if (target.closest("[data-microphone-help-link]")) {

data/app/javascript/studio/page_header.js

@@ -0,0 +1,24 @@
+// studio/page_header: the page header's two measurements, as pure functions. It
+// imports nothing; test/javascript/page_header.test.mjs loads it as a data: module.
+
+// A sticky row is stuck once it has left its place in the flow. restTop is that
+// place, measured by the sentinel beside it. The half pixel is rounding: at rest
+// the two tops differ by a fraction at most, and a stuck row by at least a pixel.
+export function isStuck(rowTop, restTop) {
+  return rowTop - restTop > 0.5
+}
+
+// Which ends of the tabs hide a tab, so a fade marks only an end with more to see.
+export function hiddenEnds({ scrollLeft, clientWidth, scrollWidth }) {
+  return {
+    start: scrollLeft > 1,
+    end: scrollLeft + clientWidth < scrollWidth - 1
+  }
+}
+
+// How far the tabs must scroll to show a tab, clear of the fade. 0 if it shows.
+export function revealBy(box, tab, margin = 32) {
+  if (tab.left < box.left) return tab.left - box.left - margin
+  if (tab.right > box.right) return tab.right - box.right + margin
+  return 0
+}