studio-engine 0.122.0 → 0.124.0

data/app/javascript/studio/page_transitions.js

@@ -0,0 +1,181 @@
+// 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
+// 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
+// the old page's picture before Turbo's callback runs. So what the old picture holds is
+// settled ahead of the visit: the held banner stack and the morph names are decided here on
+// turbo:visit and from the response, never first at before-render.
+//
+// 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"]),
+})
+
+// A same-page visit (a refresh, a poll): the transition still runs, and draws nothing.
+export const STILL = "still"
+export const READY_CAP_MS = 500
+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)]
+}
+
+// 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).
+export function planVisit({ direction, from, to, transitions, sharedName }, random = Math.random) {
+  if (!transitions || !from || !to || !Object.hasOwn(DIRECTIONS, direction)) return null
+  if (from === to) return STILL
+  return sharedName ? null : pickStyle(direction, random)
+}
+
+// A slow image must not hold a click: past the cap the swap goes ahead.
+export function withCap(promise, ms, timer = setTimeout) {
+  return Promise.race([promise, new Promise((done) => timer(done, ms))])
+}
+
+export function morphNames(root) {
+  return new Set([...root.querySelectorAll("[data-vt-morph]")].map((el) => el.getAttribute("data-vt-morph")))
+}
+
+export function shareName(here, there) {
+  return !!there && [...here].some((name) => there.has(name))
+}
+
+// Exactly one element takes the stack's view-transition name, however many a page renders:
+// a duplicate name silently cancels the whole transition.
+export function markHeld(root) {
+  const stack = root.querySelector(".studio-bar-stack")
+  if (stack) stack.setAttribute("data-vt-held", "")
+}
+
+export function eagerImages(body) {
+  return [...body.querySelectorAll("img")]
+    .filter((img) => img.getAttribute("loading") !== "lazy" && (img.getAttribute("src") || img.getAttribute("srcset")))
+    .slice(0, MAX_READY_IMAGES)
+}
+
+// The incoming body is inert, so each image is copied here to load, <picture> and all, so
+// the browser chooses the same source. Marked decoding=sync, the real one paints at once.
+function loadImage(doc, img) {
+  img.decoding = "sync"
+  const source = img.closest("picture") || img
+  const copy = doc.importNode(source, true)
+  const loader = copy.tagName === "IMG" ? copy : copy.querySelector("img")
+  return loader.decode().catch(() => {})
+}
+
+function readyForSwap(doc, body) {
+  const fonts = doc.fonts ? doc.fonts.ready.catch(() => {}) : null
+  // At least one tick, so Turf's one-tick hold for its snapshot stays honest.
+  const tick = new Promise((done) => setTimeout(done, 0))
+  return Promise.all([...eagerImages(body).map((img) => loadImage(doc, img)), fonts, tick])
+}
+
+// Turbo's resume is a promise's resolve, so the FIRST caller starts the render. Another
+// listener's short hold (Turf's turbo_snapshot_cache resumes on a timeout of 0) would cut
+// this wait to nothing, so a listener that runs after this one gets a resume that does
+// nothing, and this wait releases the render. It always does: cap, failure or success.
+export function holdRender(event, wait, cap = READY_CAP_MS) {
+  const resume = event.detail && event.detail.resume
+  if (typeof resume !== "function") return false
+  event.preventDefault()
+  event.detail.resume = () => {}
+  const release = () => resume()
+  withCap(Promise.resolve().then(wait), cap).then(release, release)
+  return true
+}
+
+function readDirection(doc) {
+  const meta = doc.querySelector('meta[name="page-transition-direction"]')
+  return meta ? meta.content : null
+}
+
+let installed = false
+
+export function installPageTransitions(doc) {
+  if (installed || !readDirection(doc)) return false
+  installed = true
+
+  const win = doc.defaultView
+  const root = doc.documentElement
+  const known = new Map()
+  let from = win.location.pathname
+  let target = null
+
+  const nameTheMorph = (shared) => {
+    if (shared) root.dataset.pageTransitionMorph = ""
+    else delete root.dataset.pageTransitionMorph
+  }
+  const predict = (names) => nameTheMorph(target !== from && shareName(morphNames(doc), names))
+
+  root.dataset.pageTransitionDirection = readDirection(doc)
+  markHeld(doc)
+  known.set(from, morphNames(doc))
+
+  doc.addEventListener("turbo:visit", (event) => {
+    root.dataset.pageTransitionVisit = ""
+    target = new URL(event.detail.url).pathname
+    predict(known.get(target))
+  })
+
+  // A page never visited: read its names from the response, ahead of the old page's picture.
+  // Only a page with names of its own can share one, so every other page skips the parse.
+  doc.addEventListener("turbo:before-fetch-response", (event) => {
+    if (event.target && event.target.tagName === "TURBO-FRAME") return
+    if (!morphNames(doc).size) return
+    const { fetchResponse } = event.detail
+    Promise.resolve(fetchResponse.responseHTML).then((html) => {
+      if (!html) return
+      const names = morphNames(new win.DOMParser().parseFromString(html, "text/html"))
+      const path = new URL(fetchResponse.response.url).pathname
+      known.set(path, names)
+      if (target && (path === target || fetchResponse.redirected)) predict(names)
+    }).catch(() => {})
+  })
+
+  // In capture, so the hold is in place before any other listener takes Turbo's resume.
+  doc.addEventListener("turbo:before-render", (event) => {
+    const { newBody } = event.detail
+    markHeld(newBody)
+    const names = morphNames(newBody)
+    if (target) known.set(target, names)
+    const sharedName = shareName(morphNames(doc), names)
+    const style = planVisit({
+      direction: readDirection(doc),
+      from,
+      to: target,
+      transitions: !!doc.startViewTransition && !win.matchMedia(REDUCED_MOTION).matches,
+      sharedName,
+    })
+    nameTheMorph(sharedName && style !== STILL)
+    if (style) root.dataset.pageTransition = style
+    else delete root.dataset.pageTransition
+    if (style && style !== STILL) holdRender(event, () => readyForSwap(doc, newBody))
+  }, { capture: true })
+
+  // Turbo fires this after the transition has finished.
+  doc.addEventListener("turbo:load", () => {
+    from = win.location.pathname
+    target = null
+    known.set(from, morphNames(doc))
+    delete root.dataset.pageTransition
+    delete root.dataset.pageTransitionVisit
+    nameTheMorph(false)
+  })
+
+  // A visit that never renders: the stack must not keep its name at rest.
+  for (const name of ["turbo:fetch-request-error", "turbo:reload"]) {
+    doc.addEventListener(name, () => { delete root.dataset.pageTransitionVisit })
+  }
+  return true
+}
+
+if (typeof document !== "undefined") installPageTransitions(document)

data/app/javascript/studio/pinned_stack.js

@@ -141,6 +141,17 @@ export function measurePin(el, name, legacy, timeline) {
   return { el: el, name: name, legacy: legacy, h: el.offsetHeight - band, bottom: Math.max(0, r.bottom) };
 }
 
+// WHERE AN ADOPTED HEADER GOES: its place in the document, since order is
+// document order (composed). Appended, it read as below every layer, so a layer
+// under it (studio/_page_header) composed a top of 0 and pinned over it.
+export function documentIndex(list, el) {
+  var FOLLOWING = 4; // Node.DOCUMENT_POSITION_FOLLOWING
+  for (var i = 0; i < list.length; i++) {
+    if (el.compareDocumentPosition(list[i].el) & FOLLOWING) return i;
+  }
+  return list.length;
+}
+
 // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
 //
 // This used to build a `pins` array once and hold each element by reference
@@ -179,7 +190,7 @@ export function readStack() {
   // contest board and mcritchie-studio's heartbeat CSS all read — would
   // never publish at all. Both live consumers own their header, so it is
   // adopted as a pin even when it does not ask to be.
-  if (header && !headerPinned) list.push(measurePin(header, 'nav', true, timeline));
+  if (header && !headerPinned) list.splice(documentIndex(list, header), 0, measurePin(header, 'nav', true, timeline));
   return {
     pins: list,
     stack: timeline ? pinnedAt(list) : composed(list),

data/app/javascript/studio/stimulus.js

@@ -63,6 +63,11 @@ export const schema = {
 // So are the voice capture pair (docs/VOICE_CAPTURE.md): a chip whose controller
 // failed still shows its prompt line, and a recorder whose controller failed
 // says recording did not load (data-studio-controller-failed="voice-recorder").
+// So is the chat's mic: a mic whose controller failed says voice did not load,
+// and the box still types (data-studio-controller-failed="agent-chat-voice").
+// So is copy-text: a colour whose controller failed still shows its hex to select.
+// So is the page header: its tabs are links, and a row whose controller failed
+// keeps its bar at all times (data-studio-controller-failed="page-header").
 export const LAZY = {
   "board": () => import("studio/controllers/board_controller"),
   "geo-settings": () => import("studio/controllers/geo_settings_controller"),
@@ -73,9 +78,12 @@ export const LAZY = {
   "survey": () => import("studio/controllers/survey_controller"),
   "knowledge-transcript": () => import("studio/controllers/knowledge_transcript_controller"),
   "agent-chat": () => import("studio/controllers/agent_chat_controller"),
+  "agent-chat-voice": () => import("studio/controllers/agent_chat_voice_controller"),
   "voice-profile": () => import("studio/controllers/voice_profile_controller"),
   "microphone-chip": () => import("studio/controllers/microphone_chip_controller"),
-  "voice-recorder": () => import("studio/controllers/voice_recorder_controller")
+  "voice-recorder": () => import("studio/controllers/voice_recorder_controller"),
+  "copy-text": () => import("studio/controllers/copy_text_controller"),
+  "page-header": () => import("studio/controllers/page_header_controller")
 }
 
 export const application = Application.start(document.documentElement, schema)

data/app/javascript/studio/style_guide.js

@@ -9,5 +9,7 @@
 // demos the moment the page is up finds them there.
 import { application } from "studio/stimulus"
 import StyleModalsController from "studio/controllers/style_modals_controller"
+import StyleSectionNavController from "studio/controllers/style_section_nav_controller"
 
 application.register("style-modals", StyleModalsController)
+application.register("style-section-nav", StyleSectionNavController)

data/app/javascript/studio/style_section_nav.js

@@ -0,0 +1,16 @@
+// studio/style_section_nav: which section of the style guide the reader is in.
+// It imports nothing; test/javascript/style_section_nav.test.mjs loads it as a
+// data: module.
+//
+// `tops` is each section's top in viewport pixels, in page order. A section is
+// current once its top reaches the bottom of the sticky row (`line`). Before
+// the first one reaches it, the first is current. At the end of the page the
+// last is current, because a short last section can never reach the line.
+export function activeIndex(tops, line, atPageEnd = false) {
+  if (tops.length === 0) return -1
+  if (atPageEnd) return tops.length - 1
+
+  let active = 0
+  tops.forEach((top, index) => { if (top <= line) active = index })
+  return active
+}

data/app/javascript/studio/theme_editor.js

@@ -1,72 +1,18 @@
-// studio/theme_editor: the two live-preview theme editors, as the Alpine
-// factories their templates bind.
+// studio/theme_editor: the live-preview theme editor, as the Alpine factory its
+// template binds.
 //
-//   themeEditor(colors)    theme_settings/edit, the standalone /admin/theme page
 //   dsThemeEditor(seed)    style/_theme, the Theme section of the style guide
 //
-// Both are seeded with the server-resolved role colours and write the themeable
+// It is seeded with the server-resolved role colours and writes the themeable
 // role variables on the document as the operator types, so every specimen on
 // the page restyles at once. The inputs still carry the real values.
 //
-// studio/alpine_shims publishes both as window globals before Alpine starts,
-// because x-data="themeEditor(...)" is evaluated the moment Alpine does.
+// studio/alpine_shims publishes it as a window global before Alpine starts,
+// because x-data="dsThemeEditor(...)" is evaluated the moment Alpine does.
 //
 // It imports nothing; test/javascript/theme_editor.test.mjs loads it as a
 // data: module.
 
-// The seven roles the standalone editor edits, in the order it lists them.
-export const ROLES = ["primary", "success", "accent", "warning", "danger", "dark", "light"]
-
-// A typed colour as #rrggbb: a missing # is added and a 3-digit hex is doubled.
-// Answers null for anything that is not a 3- or 6-digit hex.
-export function normalizeHex(value) {
-  let hex = String(value == null ? "" : value).trim()
-  if (!hex.startsWith("#")) hex = "#" + hex
-  if (/^#[0-9a-fA-F]{3}$/.test(hex)) {
-    hex = "#" + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3]
-  }
-  return /^#[0-9a-fA-F]{6}$/.test(hex) ? hex : null
-}
-
-// `hex` (#rrggbb) moved `amount` (0..1) of the way to white.
-export function lightenColor(hex, amount) {
-  hex = hex.replace("#", "")
-  const r = parseInt(hex.substring(0, 2), 16)
-  const g = parseInt(hex.substring(2, 4), 16)
-  const b = parseInt(hex.substring(4, 6), 16)
-  const nr = Math.round(r + (255 - r) * amount)
-  const ng = Math.round(g + (255 - g) * amount)
-  const nb = Math.round(b + (255 - b) * amount)
-  return "#" + [nr, ng, nb].map((c) => c.toString(16).padStart(2, "0")).join("")
-}
-
-// The standalone editor's colours: every role present, blank when the server
-// resolved none.
-export function seededColors(seed) {
-  const colors = {}
-  ROLES.forEach((role) => { colors[role] = (seed && seed[role]) || "" })
-  return colors
-}
-
-// What the standalone editor writes on the root for `colors`, as
-// [property, value] pairs; a null value removes the property.
-//
-// btn-warning and btn-danger paint --color-<role>-fill first (the resolver
-// emits it for the engine defaults), so a typed colour sets it too or the
-// specimens keep the default fill. A cleared colour drops the override.
-export function previewProperties(colors) {
-  const properties = [
-    ["--color-cta", colors.primary],
-    ["--color-success", colors.success],
-    ["--color-warning", colors.warning || "#FF7C47"],
-    ["--color-danger", colors.danger || "#EF4444"]
-  ]
-  for (const role of ["warning", "danger"]) {
-    properties.push([`--color-${role}-fill`, colors[role] ? colors[role] : null])
-  }
-  return properties
-}
-
 // What the style guide's editor writes on the root for `colors`. It sets only
 // what has a value and removes nothing.
 export function stylePreviewProperties(colors) {
@@ -87,52 +33,6 @@ function applyProperties(style, properties) {
   }
 }
 
-// x-data="themeEditor({...})": theme_settings/edit.
-export function themeEditor(seed) {
-  return {
-    colors: seededColors(seed),
-
-    resetColor(role, defaultVal) {
-      this.colors[role] = defaultVal
-      this.updatePreview()
-    },
-
-    normalizeHex(role) {
-      const hex = normalizeHex(this.colors[role])
-      if (hex) this.colors[role] = hex
-      this.updatePreview()
-    },
-
-    // Live CSS variables on the document, for immediate feedback.
-    updatePreview() {
-      applyProperties(document.documentElement.style, previewProperties(this.colors))
-    },
-
-    darkPreviewStyle() {
-      return { backgroundColor: this.colors.dark, borderRadius: "0" }
-    },
-
-    darkSurfaceStyle() {
-      return {
-        backgroundColor: this.lightenColor(this.colors.dark, 0.3),
-        border: "1px solid rgba(255,255,255,0.1)"
-      }
-    },
-
-    lightPreviewStyle() {
-      return { backgroundColor: this.colors.light, borderRadius: "0" }
-    },
-
-    lightSurfaceStyle() {
-      return { backgroundColor: "#ffffff", border: "1px solid #e2e8f0" }
-    },
-
-    lightenColor(hex, amount) {
-      return lightenColor(hex, amount)
-    }
-  }
-}
-
 // The method a form really sends, and its body without Rails' _method override.
 // The editor's form carries _method=patch, and sending the real method means
 // nothing depends on Rack::MethodOverride parsing a multipart fetch body.
@@ -170,7 +70,7 @@ export function failureReason(response) {
 //
 // SAVE IN PLACE. Save and Regenerate submit by fetch and stay on the style
 // guide: the form's @submit.prevent stops the browser navigating to
-// /admin/theme, the live preview persists, and the outcome is a toast (the
+// its save endpoint, the live preview persists, and the outcome is a toast (the
 // engine's `toast` window event). The form's own POST still works when Alpine
 // never loads.
 export function dsThemeEditor(seed) {

data/app/javascript/studio/voice_recorder.js

@@ -22,6 +22,7 @@
 //   studio:voice-recorder:take    detail { blob, mimeType, durationMs, peakRms, microphone: { label, deviceId } }
 //   studio:voice-recorder:silent  detail { durationMs, microphone }  (nothing heard: no blob is handed over)
 //   studio:voice-recorder:state   detail { state }
+//   studio:voice-recorder:hint    detail { kind, text }  (kind "heard" or "quiet", while it records)
 // and, on window, studio/microphone's EVENTS, which the chip listens to.
 //
 // MODES: "toggle" (tap to start, tap to stop) or "hold" (press and hold to
@@ -34,7 +35,8 @@ import { createLevelMeter, SILENCE_RMS } from "studio/level_meter"
 export const EVENTS = {
   take: "studio:voice-recorder:take",
   silent: "studio:voice-recorder:silent",
-  state: "studio:voice-recorder:state"
+  state: "studio:voice-recorder:state",
+  hint: "studio:voice-recorder:hint"
 }
 
 // What to ask MediaRecorder for, in order: webm/opus on Chrome and Firefox,
@@ -125,6 +127,7 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
   let microphone = { label: "", deviceId: null }
   let hinted = null
   let stopWanted = false
+  let keyHeld = false
   let destroyed = false
 
   function setState(next, message = null) {
@@ -159,10 +162,11 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
   }
 
   function hint(kind) {
-    if (state !== "recording" || hinted === kind || !copy.recording[kind]) return
+    if (state !== "recording" || hinted === kind || copy.recording[kind] == null) return
     hinted = kind
     const status = one("[data-voice-recorder-status]")
     if (status) status.textContent = copy.recording[kind]
+    root.dispatchEvent(new win.CustomEvent(EVENTS.hint, { bubbles: true, detail: { kind, text: copy.recording[kind] } }))
   }
 
   function onSample(rms) {
@@ -302,6 +306,9 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
     if (mode !== "hold") return
     const button = event.target.closest && event.target.closest("[data-voice-recorder-button]")
     if (!button || !root.contains(button)) return
+    // Only the main button holds: a right-click (or a Mac's control-click) is a
+    // context menu, not a take. Touch and pen report button 0.
+    if (event.button || event.ctrlKey) return
     event.preventDefault()
     if (button.setPointerCapture && event.pointerId != null) {
       try { button.setPointerCapture(event.pointerId) } catch (_) { /* a synthetic pointer */ }
@@ -318,12 +325,24 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
     if (mode !== "hold" || event.repeat || ![" ", "Enter"].includes(event.key)) return
     if (!event.target.closest || !event.target.closest("[data-voice-recorder-button]")) return
     event.preventDefault()
+    keyHeld = true
     start()
   }
 
   function onKeyUp(event) {
     if (mode !== "hold" || ![" ", "Enter"].includes(event.key)) return
     event.preventDefault()
+    keyHeld = false
+    onPointerUp()
+  }
+
+  // A key held on the button when focus leaves it (Tab, another window): its
+  // keyup lands elsewhere and never reaches here, and the microphone would stay
+  // live to the max_ms cap and send a take on its own. A pointer hold is captured,
+  // so it has its own pointerup.
+  function onFocusOut() {
+    if (!keyHeld) return
+    keyHeld = false
     onPointerUp()
   }
 
@@ -333,6 +352,7 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
   root.addEventListener("pointercancel", onPointerUp)
   root.addEventListener("keydown", onKeyDown)
   root.addEventListener("keyup", onKeyUp)
+  root.addEventListener("focusout", onFocusOut)
   root.dataset.voiceRecorderMode = mode
   paintLevel(0)
   if (supported()) setState("idle")
@@ -352,6 +372,7 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
       root.removeEventListener("pointercancel", onPointerUp)
       root.removeEventListener("keydown", onKeyDown)
       root.removeEventListener("keyup", onKeyUp)
+      root.removeEventListener("focusout", onFocusOut)
       if (recorder && recorder.state !== "inactive") {
         try { recorder.stop() } catch (_) { /* already stopped */ }
       }

data/app/models/studio/user_session.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Studio
+  # One signed-in browser session: who, whether they were an admin, when it
+  # started and when it was last seen. It is a cached record for the app's own
+  # dashboard, kept on purpose without an IP, a user agent or a path.
+  #
+  # A new row starts after IDLE without a request. An open row is written at most
+  # once per THROTTLE, and the cookie remembers when, so a request inside that
+  # window runs no query at all.
+  #
+  # Nil-safe, because the table comes from a migration the host runs: an app that
+  # has not run it records nothing and serves as before.
+  class UserSession < ApplicationRecord
+    self.table_name = "studio_user_sessions"
+
+    IDLE = 30.minutes
+    THROTTLE = 5.minutes
+
+    belongs_to :user, class_name: "::User", optional: true
+
+    scope :recent, -> { order(last_seen_at: :desc) }
+    scope :non_admin, -> { where(admin: false) }
+
+    # Per app, like Studio.session_key: apps on the hub's shared cookie
+    # (STUDIO_SSO_SHARED_COOKIE) must not read each other's mark.
+    def self.cookie_key = :"#{Studio.session_key}_session_mark"
+
+    # Off under test unless a test asks: the row a first request writes would count in
+
+    # every host's query-budget test, which measures the page and not this.
+
+    cattr_accessor :record_in_test, default: false
+
+
+    def self.recording?
+
+      !Rails.env.test? || record_in_test
+
+    end
+
+
+    def self.available?
+      connection.data_source_exists?(table_name)
+    rescue ActiveRecord::ActiveRecordError, NoMethodError
+      false
+    end
+
+    # Records this request for `user`, reading and writing `store` (the session).
+    # Answers the row it wrote, or nil. Never raises: a request must not fail
+    # because its bookkeeping did.
+    def self.track(store, user, now: Time.current)
+      return if user.nil? || !recording?
+
+      mark = store[cookie_key]
+      mark = mark.to_h.transform_keys(&:to_s) if mark.respond_to?(:to_h)
+      same_user = mark.is_a?(Hash) && mark["user"] == user.id
+      seen = same_user ? Time.zone.at(mark["at"].to_i) : nil
+      return if seen && seen > now - THROTTLE
+      return unless available?
+
+      row = same_user && seen > now - IDLE ? find_by(id: mark["id"], user_id: user.id) : nil
+      if row
+        row.update_columns(last_seen_at: now)
+      else
+        admin = user.respond_to?(:admin?) && user.admin?
+        row = create!(user_id: user.id, admin: admin ? true : false, started_at: now, last_seen_at: now)
+      end
+      store[cookie_key] = { "id" => row.id, "user" => user.id, "at" => now.to_i }
+      row
+    rescue StandardError => e
+      Rails.logger&.warn("[user_session] #{e.class}: #{e.message}")
+      nil
+    end
+  end
+end

data/app/models/theme_setting.rb

@@ -9,6 +9,9 @@ class ThemeSetting < ApplicationRecord
   end
 
   validates :app_name, presence: true, uniqueness: true
+  # Every page's head runs these through Studio::ColorScale, which reads six hex
+  # digits. A saved "#abc" would answer 500 on every page, the editor included.
+  validates(*ROLES.map { |role| db_column_for(role) }, format: { with: /\A#\h{6}\z/, message: "must be a #rrggbb colour" }, allow_blank: true)
 
   # Returns the ThemeSetting for the current app, or a new unsaved instance.
   def self.current

data/app/views/components/_link_sidebar.html.erb

@@ -6,6 +6,9 @@
     this automatically when sections are declared. %>
 <% sections = studio_sidebar_sections %>
 <% sidebar_admin = respond_to?(:admin?) && admin? %>
+<%# A signed-out visitor's panel has no title: its links say what it is. It keeps its
+    accessible name (aria_label) and its close button. %>
+<% sidebar_title = if sidebar_admin then "Admin Menu" elsif respond_to?(:logged_in?) && logged_in? then "Links" end %>
 <% close_action = "$store.sidebars.linkTreeOpen = false" %>
 
 <style>
@@ -113,7 +116,7 @@
 
 <%= render "components/sidebar_panel",
       id: "studio-link-sidebar",
-      title: sidebar_admin ? "Admin Menu" : "Links",
+      title: sidebar_title,
       open: "$store.sidebars.linkTreeOpen",
       body_html: body_html,
       footer_html: footer_html,
@@ -126,7 +129,7 @@
 
 <%= render "components/sidebar_panel",
       id: "studio-link-sidebar-mobile",
-      title: sidebar_admin ? "Admin Menu" : "Links",
+      title: sidebar_title,
       open: "$store.sidebars.linkTreeOpen",
       body_html: body_html,
       footer_html: footer_html,

data/app/views/components/_user_nav.html.erb

@@ -5,8 +5,8 @@
     { partial: "path", locals: { ... } } when the partial needs locals:
       balance_slot     — balance display, rendered at the start of the
                          top row (e.g. a wallet balance link)
-      extra_icons_slot — app-specific icon buttons, rendered before the
-                         admin gear + theme toggle
+      extra_icons_slot — app-specific icon buttons, rendered between the
+                         theme toggle and the admin gear
       div2_slot        — replaces the default second row (the wallet
                          address + level progress bar) entirely
                          (e.g. a seeds bar)
@@ -329,13 +329,14 @@
     <div data-nav-avatar-badge><%= studio_navbar_slot_tag(avatar_badge) %></div>
     <% end %>
   <% else %>
+    <%# The signed-in rail's order: the theme toggle, then the gear. Desktop
+        only, as above: the phone row carries the toggle below md. %>
+    <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <% if menu_trigger %>
     <span class="hidden md:block" data-nav-menu-trigger><%= studio_navbar_slot_tag(menu_trigger) %></span>
     <% else %>
     <%= render "components/admin_dropdown", display_class: "hidden md:block" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
     <% end %>
-    <%# Desktop only, as above: the phone row carries the toggle below md. %>
-    <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <div class="flex items-center gap-3 ml-auto">
       <%= link_to Studio.sign_in_label, login_path, class: "text-heading hover:text-primary text-sm font-semibold transition" %>
       <%= link_to "Sign up", signup_path, class: "btn btn-primary btn-sm" %>