studio-engine 0.122.0 → 0.123.0

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/studio/admin_models/_sessions_table.html.erb

@@ -0,0 +1,28 @@
+<%# locals: (records:) %>
+<div class="overflow-x-auto">
+  <table id="models-sessions-table" class="w-full min-w-[640px] text-sm">
+    <thead class="bg-surface-alt text-muted text-xs uppercase tracking-wide">
+      <tr>
+        <th class="px-4 py-3 text-left font-semibold">User</th>
+        <th class="px-4 py-3 text-left font-semibold">Started</th>
+        <th class="px-4 py-3 text-left font-semibold">Last seen</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-subtle">
+      <% records.each do |row| %>
+        <tr>
+          <td class="px-4 py-3">
+            <% user = row.user %>
+            <span class="font-semibold text-heading"><%= user ? (user.email.presence || user.try(:display_name).presence || "User ##{user.id}") : "Deleted user" %></span>
+            <% if row.admin %><span class="ml-2 label-upper">admin</span><% end %>
+          </td>
+          <td class="px-4 py-3 text-muted whitespace-nowrap"><%= time_ago_in_words(row.started_at) %> ago</td>
+          <td class="px-4 py-3 text-muted whitespace-nowrap"><%= time_ago_in_words(row.last_seen_at) %> ago</td>
+        </tr>
+      <% end %>
+      <% if records.empty? %>
+        <tr><td colspan="3" class="px-4 py-6 text-muted">No sessions yet.</td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/studio/admin_models/show.html.erb

@@ -1,17 +1,28 @@
 <% content_for(:title, "#{@config.fetch(:label)} - Models - Admin") %>
 
-<div class="max-w-7xl mx-auto px-4 py-8 space-y-6">
-  <header class="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
-    <div>
-      <p class="text-xs text-muted uppercase tracking-wide font-semibold">Admin Models</p>
-      <h1 class="text-heading text-2xl font-bold mt-1"><%= @config.fetch(:label) %></h1>
-      <p class="text-muted text-sm mt-1">
-        <%= @config.fetch(:description) %>.
-        Page <%= @page %> of <%= @total_pages %>, <%= @total_count %> total.
-      </p>
+<div class="max-w-7xl mx-auto px-4 pb-8 space-y-6">
+  <%# The title and a tab per model, one sticky row, as on /admin/style. A tab is a
+      link, so the open one is the page's own model. %>
+  <nav class="sticky -mx-4 mt-6 px-4 py-2 bg-surface border-y border-subtle flex items-center gap-2"
+       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)"
+       aria-label="Models">
+    <h1 class="text-xl font-bold text-heading shrink-0">Models</h1>
+    <div class="overflow-x-auto min-w-0 flex-1">
+      <div class="flex items-center gap-2 min-w-max pl-4">
+        <% admin_model_configs.each do |key, config| %>
+          <% open = key.to_s == @key %>
+          <%= link_to config.fetch(:label), admin_model_path(key),
+                class: "btn btn-sm #{open ? 'btn-primary' : 'btn-neutral'}",
+                aria: { current: (open ? "page" : nil) } %>
+        <% end %>
+      </div>
     </div>
-    <%= link_to "Back to models", admin_models_path, class: "btn btn-outline" %>
-  </header>
+  </nav>
+
+  <p class="text-muted text-sm">
+    <%= @config.fetch(:description) %>.
+    Page <%= @page %> of <%= @total_pages %>, <%= @total_count %> total.
+  </p>
 
   <section class="card overflow-hidden">
     <%= render admin_models_table_partial(@key), records: @records %>

data/app/views/studio/agent_chat/_chat.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (soul:, name:, portrait: nil, role: nil, empty: nil, cards: nil) %>
+<%# locals: (soul:, name:, portrait: nil, role: nil, empty: nil, cards: nil, voice: false, voice_copy: nil) %>
 <%#
   The shared agent chat (docs/AGENT_CHAT.md): one conversation with one agent,
   held by the hub, on any app's page.
@@ -13,15 +13,25 @@
   cards     THE CARD SLOT: ready markup shown between the header and the
             thread (/build's intake cards). A local, never a bare yield: a
             partial rendered without a block yields the LAYOUT's body.
+  voice     true puts hold to talk in the composer's mic slot, with the privacy
+            line under it. It still shows only where the app turned takes on
+            (Studio.voice_transcription) and only to a user
+            Studio.voice_chat_allowed lets talk; never to a signed-out visitor.
+  voice_copy  the words: { privacy:, recorder:, chip: }, each optional, over the
+            defaults (Studio::AgentChat.voice_copy).
 
   Top to bottom, as the hub's /build: the portrait and name, the card slot, the
   thread, the typing line, the offline notice and the composer. The thread is
   drawn by studio/agent_chat (the "agent-chat" controller, loaded lazily) from
   the two <template>s below, which are studio/agent_chat/_turn: the look lives
   here, in ERB, and the script only fills it. ONE PAGE HOLDS ONE CHAT.
+
+  A viewer Studio.agent_chat_allowed refuses gets nothing here: the proxy would
+  answer them 403 on every poll.
 %>
 <% souls = Studio.agent_chat_soul_list %>
 <% raise ArgumentError, "studio/agent_chat/chat: soul #{soul.inspect} is not in Studio.agent_chat_souls (#{souls.inspect})" unless souls.include?(soul.to_s) %>
+<% if Studio.agent_chat_allowed?(studio_agent_chat_viewer) %>
 <section class="w-full max-w-3xl mx-auto px-4 pt-4 sm:pt-8 flex flex-col gap-6 min-w-0"
          data-studio-controller="agent-chat" data-test="agent-chat"
          data-agent-chat-soul="<%= soul %>" data-agent-chat-name="<%= name %>"
@@ -45,8 +55,13 @@
       <p class="text-sm text-body min-w-0">Can't reach <%= name %> right now. Your messages are safe; try again in a moment.</p>
       <button type="button" class="btn btn-secondary btn-sm shrink-0" data-agent-chat-retry data-test="agent-chat-retry">Try again</button>
     </div>
-    <%= render "studio/agent_chat/form", soul: soul, name: name %>
+    <% mic = render("studio/agent_chat/voice", soul: soul, name: name, copy: voice_copy) if voice && studio_agent_chat_voice? %>
+    <%= render "studio/agent_chat/form", soul: soul, name: name, mic: mic %>
+    <% if mic %>
+      <p class="px-3 text-center text-xs text-secondary break-words" data-test="agent-chat-voice-privacy"><%= Studio::AgentChat.voice_copy(voice_copy)["privacy"] %></p>
+    <% end %>
   </div>
   <template data-agent-chat-template="user"><%= render "studio/agent_chat/turn", turn: { "role" => "user" }, name: name %></template>
   <template data-agent-chat-template="agent"><%= render "studio/agent_chat/turn", turn: { "role" => "agent" }, name: name %></template>
 </section>
+<% end %>

data/app/views/studio/agent_chat/_form.html.erb

@@ -1,5 +1,5 @@
-<%# locals: (soul:, name:) %>
-<%# The chat's composer (studio/agent_chat/_chat), as the hub's agent_chats/_form: the text over a round send button at its bottom right, sticky at the window's bottom. Enter sends; Shift+Enter is a new line (studio/agent_chat). It posts to POST /agent_chat/messages with the page's authenticity token (form_with adds it; the script sends it as X-CSRF-Token). A send that fails keeps the words in the box and says why above them. %>
+<%# locals: (soul:, name:, mic: nil) %>
+<%# The chat's composer (studio/agent_chat/_chat), as the hub's agent_chats/_form: the text over a round send button at its bottom right, sticky at the window's bottom. Enter sends; Shift+Enter is a new line (studio/agent_chat). It posts to POST /agent_chat/messages with the page's authenticity token (form_with adds it; the script sends it as X-CSRF-Token). A send that fails keeps the words in the box and says why above them. `mic` is the mic slot: ready markup under the box (studio/agent_chat/_voice), nothing without it. %>
 <%= form_with url: studio_agent_chat_messages_path, method: :post, local: true,
               html: { style: "view-transition-name: agent-composer;" },
               class: "sticky bottom-3 z-10 rounded-3xl border border-subtle bg-surface shadow-lg focus-within:border-primary transition-colors p-2 flex flex-col gap-2",
@@ -20,4 +20,5 @@
       </svg>
     </button>
   </div>
+  <%= mic %>
 <% end %>

data/app/views/studio/agent_chat/_voice.html.erb

@@ -0,0 +1,54 @@
+<%# locals: (soul:, name:, copy: nil) %>
+<%# Hold to talk, in the composer's mic slot (studio/agent_chat/_form;
+    docs/AGENT_CHAT.md, "Talking by voice"). The engine's microphone chip and
+    recorder capture the take; studio/agent_chat_voice (the lazy
+    "agent-chat-voice" controller) embeds it on this device when the page names
+    an embedder, posts it to POST /voice/takes and sends the words to the chat.
+    No audio is kept. Status lines are set as text.
+
+    Scoped CSS for the reason studio/voice/_styles gives: it must render in an
+    app whose Tailwind build never saw this file. The status line keeps its one
+    line even when empty, so a one-line status coming or going under a held finger
+    does not move the button. Two things still can at 390px outside a stuck composer,
+    and the pointer stays captured through both: the quiet hint wrapping to two lines,
+    and the chip's prompt shortening on the first hold. %>
+<% words = Studio::AgentChat.voice_copy(copy) %>
+<style>
+  .studio-agent-voice { display: grid; gap: .25rem; padding: 0 .25rem .25rem; min-width: 0; }
+  .studio-agent-voice-status { min-height: 1.25rem; margin: 0; padding: 0 .5rem; font-size: .875rem; line-height: 1.25rem; overflow-wrap: anywhere;
+    color: var(--color-text-body, inherit); }
+  .studio-agent-voice-failed { display: none; margin: 0; padding: 0 .5rem; font-size: .8125rem; color: var(--color-text-secondary, inherit); }
+  [data-studio-controller-failed~="agent-chat-voice"] > .studio-agent-voice-failed { display: block; }
+  /* One row where both fit; on a phone the chip takes the first line and the
+     talk button the whole of the second. */
+  .studio-agent-voice-row { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem; min-width: 0; }
+  .studio-agent-voice-row .studio-mic { display: contents; }
+  .studio-agent-voice-row .studio-mic-chip { flex: 1 1 14rem; min-width: 0; }
+  .studio-agent-voice-row .studio-mic-panel { flex: 1 0 100%; max-width: none; order: 3; }
+  .studio-agent-voice-row .studio-mic-failed { flex: 1 0 100%; order: 4; }
+  .studio-agent-voice-row .studio-recorder { flex: 1 1 10rem; min-width: 0; flex-flow: row wrap; justify-content: flex-end; gap: .5rem; }
+  .studio-agent-voice-row .studio-recorder-button { flex: 1 1 10rem; min-width: 0; padding: .625rem 1rem; }
+  .studio-agent-voice-row .studio-recorder-timer { display: none; }
+  .studio-agent-voice-row [data-voice-recorder-state="recording"] .studio-recorder-timer { display: inline; }
+  .studio-agent-voice-row .studio-recorder-status { flex: 1 0 100%; min-height: 0; max-width: none; font-size: .875rem; }
+  /* The chat's status line speaks for these three; a second live line would say
+     them twice, and its coming and going would move a held button. */
+  .studio-agent-voice-row .studio-recorder-status:empty,
+  .studio-agent-voice-row [data-voice-recorder-state="recording"] .studio-recorder-status,
+  .studio-agent-voice-row [data-voice-recorder-state="silent"] .studio-recorder-status { display: none; }
+  .studio-agent-voice-row .studio-recorder-failed { flex: 1 0 100%; }
+</style>
+<div class="studio-agent-voice" role="group" aria-label="Talk to <%= name %>"
+     data-studio-controller="agent-chat-voice" data-agent-chat-voice data-test="agent-chat-voice"
+     data-agent-chat-voice-state="idle"
+     data-agent-chat-voice-soul="<%= soul %>" data-agent-chat-voice-name="<%= name %>"
+     data-agent-chat-voice-takes-url="<%= studio_voice_takes_path %>"
+     <%= tag.attributes("data-agent-chat-voice-embedder": studio_agent_chat_embedder(studio_agent_chat_viewer)) %>>
+  <p class="studio-agent-voice-status" role="status" aria-live="polite"
+     data-agent-chat-voice-status data-test="agent-chat-voice-status"></p>
+  <div class="studio-agent-voice-row">
+    <%= render "studio/voice/microphone_chip", copy: words["chip"] %>
+    <%= render "studio/voice/recorder", id: "#{soul}-voice-recorder", mode: "hold", copy: words["recorder"] %>
+  </div>
+  <p class="studio-agent-voice-failed">Voice didn't load on this page. Reload to try again, or type instead.</p>
+</div>

data/app/views/studio/voice/_microphone_help.html.erb

@@ -58,8 +58,11 @@
 
     <p class="studio-mic-help-other" data-microphone-help-other hidden><%= help.fetch("other") %></p>
 
-    <form method="dialog" class="studio-mic-help-actions">
-      <button type="submit" class="btn btn-primary studio-mic-help-close" data-microphone-help-close><%= help.fetch("close") %></button>
-    </form>
+    <%# A button, never <form method="dialog">: this chip can sit inside a form (the
+        chat's composer), where the parser drops a nested form and Close would
+        submit the outer one. studio/microphone_chip closes the dialog. %>
+    <div class="studio-mic-help-actions">
+      <button type="button" class="btn btn-primary studio-mic-help-close" data-microphone-help-close><%= help.fetch("close") %></button>
+    </div>
   </div>
 </dialog>

data/app/views/style/_theme.html.erb

@@ -1,13 +1,12 @@
 <%#  Theme section of the living style guide (admin/style) — the LANDING section.
-     Theme owns "the colors": it leads with the 7 role tokens/swatches (moved here
-     from the Tricks section), then folds in the /admin/theme editor as a second
-     entry point and a live dark/light preview.
-
-     Save-in-place: unlike the standalone /admin/theme page (which redirects to
-     itself on save), THIS section intercepts Save + Regenerate and submits them
-     via fetch — the page never navigates away, the live preview stays put, and
-     the outcome is a toast. The fetch asks for JSON and the controller answers
-     it 204 once it has written; the standalone page's redirect is unchanged.
+     Theme owns "the colors": it leads with the 7 role tokens/swatches, then the
+     editor with a live dark/light preview, then the logos, the semantic tokens and
+     the type. GET /admin/theme redirects here.
+     
+     Save-in-place: this section intercepts Save + Regenerate and submits them via
+     fetch, so the page never navigates away, the live preview stays put, and the
+     outcome is a toast. The fetch asks for JSON and the controller answers it 204
+     once it has written.
      The editor is studio/theme_editor's dsThemeEditor factory, which
      studio/alpine_shims publishes.
 
@@ -63,8 +62,7 @@
     <div class="space-y-1">
       <h2 class="text-2xl font-bold text-heading">Theme</h2>
       <p class="text-muted text-sm max-w-2xl">
-        The color foundation. The 7-role system, editable here and at
-        <code class="font-mono text-2xs">/admin/theme</code>. Edits preview live; Save writes them
+        The color foundation. The 7-role system, editable here. Edits preview live; Save writes them
         and Regenerate clears the theme cache. Both persist <strong>in place</strong> — the page never
         leaves. Every specimen on this page restyles from these roles.
       </p>
@@ -171,4 +169,69 @@
       </div>
     </div>
   </div>
-</section>
+  
+  <% logos = Studio.respond_to?(:theme_logos) ? Array(Studio.theme_logos) : [] %>
+  <% if logos.any? %>
+    <div class="space-y-3">
+      <p class="label-upper">Logos</p>
+      <div class="grid gap-4 grid-cols-2 md:grid-cols-5">
+        <% logos.each do |logo| %>
+          <% file = logo.is_a?(Hash) ? logo[:file] : logo %>
+          <% title = logo.is_a?(Hash) ? logo[:title] : file %>
+          <div class="card p-4 space-y-3">
+            <p class="text-sm text-heading font-medium"><%= title %></p>
+            <div class="flex items-center justify-center w-20 h-20 rounded-lg" style="background-color: #ddd; background-image: linear-gradient(45deg, #777 25%, transparent 25%, transparent 75%, #777 75%), linear-gradient(45deg, #777 25%, transparent 25%, transparent 75%, #777 75%); background-size: 12px 12px; background-position: 0 0, 6px 6px;">
+              <img src="/<%= file %>" alt="<%= title %>" class="max-w-16 max-h-16 rounded">
+            </div>
+            <code class="font-mono text-2xs text-muted break-all"><%= file %></code>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  <% end %>
+  
+  <%# Semantic tokens: the utilities a page paints with, under the role colours. %>
+  <div class="space-y-3">
+    <p class="label-upper">Semantic tokens</p>
+    <div class="grid gap-3 grid-cols-2 md:grid-cols-5">
+      <% [["Page", "bg-page", :bg], ["Surface", "bg-surface", :bg], ["Surface Alt", "bg-surface-alt", :bg], ["Inset", "bg-inset", :bg],
+          ["Heading", "text-heading", :text], ["Body", "text-body", :text], ["Secondary", "text-secondary", :text], ["Muted", "text-muted", :text],
+          ["Border", "border-subtle", :border], ["Border Strong", "border-strong", :border]].each do |name, utility, kind| %>
+        <div class="card p-3 flex items-center gap-3">
+          <% case kind
+             when :bg %>
+            <div class="w-8 h-8 rounded-full border border-subtle shrink-0 <%= utility %>"></div>
+          <% when :text %>
+            <div class="w-8 h-8 rounded-full border border-subtle shrink-0 bg-surface flex items-center justify-center">
+              <span class="text-sm font-bold <%= utility %>">A</span>
+            </div>
+          <% else %>
+            <div class="w-8 h-8 rounded-full shrink-0 border-2 bg-transparent <%= utility %>"></div>
+          <% end %>
+          <div class="min-w-0">
+            <p class="text-heading text-sm font-semibold truncate"><%= name %></p>
+            <code class="font-mono text-2xs text-muted truncate block"><%= utility %></code>
+          </div>
+        </div>
+      <% end %>
+    </div>
+  </div>
+  
+  <%# Type in this app's own font, named by role: the font itself is the host's. %>
+  <div class="space-y-3">
+    <p class="label-upper">Typography</p>
+    <div class="card p-6 space-y-4">
+      <p class="text-heading text-3xl font-extrabold">Heading</p>
+      <p class="text-heading text-xl font-bold">Subheading</p>
+      <p class="text-body text-base">Body text. The quick brown fox jumps over the lazy dog.</p>
+      <p class="text-secondary text-sm">Secondary text. Additional context and metadata.</p>
+      <p class="text-muted text-xs">Muted text. Timestamps, hints and fine print.</p>
+      <hr class="border-subtle">
+      <div class="flex flex-wrap gap-4">
+        <% [400, 500, 600, 700, 800, 900].each do |weight| %>
+          <span class="text-heading text-lg" style="font-weight: <%= weight %>"><%= weight %></span>
+        <% end %>
+      </div>
+    </div>
+  </div>
+  </section>

data/app/views/style/index.html.erb

@@ -3,10 +3,10 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Five ENGINE sections, reached by the sticky section nav below and rendered
+     Five ENGINE sections, reached by the sticky title row below and rendered
      as sibling partials: Theme is the landing section (the color foundation - it
-     owns the role tokens/swatches, the folded-in /admin/theme editor, and the
-     live preview), then Modals (the shared host + engine card blocks), Tricks
+     owns the role tokens/swatches, the theme editor, the live preview, and the
+     logos and type), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
      copy-paste-for-an-agent snippets), Tasks (the shared board primitive), and
      Components (the ViewComponent previews, linking into the gallery at
@@ -54,36 +54,34 @@
   ]
 %>
 <div class="max-w-6xl mx-auto px-4 pb-16">
-  <header class="space-y-2 pt-8 pb-6">
-    <p class="label-upper">studio-engine &middot; v<%= Studio::VERSION %></p>
-    <h1 class="text-3xl font-bold text-heading">Style</h1>
-    <p class="text-body max-w-2xl">
-      A living gallery of the shared UI primitives, rendered live in this app's
-      theme. Everything below is styled by the engine's own
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">engine.css</code>
-      and
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">engine-motion.css</code>
-      layers - toggle this app between light and dark and every specimen follows.
-    </p>
-  </header>
-
-  <%# Section nav — sticky under the whole pinned stack (--pin-stack-bottom; then
-      --nav-bottom and --nav-h for a host on an older publisher; then 0). Not --nav-h first: that
-      is the header's HEIGHT, and chrome stacked above the header would sit over
-      the nav by its own height. A pill per
-      section; the row scrolls horizontally on narrow screens, its edges softened
-      by the .fade-edge-x primitive. Order leads with Theme (the color foundation).
-      It sits at --z-sticky, above --z-raised, so the live hold button's portal
-      bubbles scroll under it rather than over it. %>
-  <nav class="sticky -mx-4 px-4 py-3 bg-surface border-y border-subtle"
-       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)" aria-label="Style guide sections">
-    <div class="fade-edge-x overflow-x-auto">
-      <div class="flex items-center gap-2 min-w-max">
-        <% sections.each do |anchor, label| %>
-          <a href="#<%= anchor %>" class="btn btn-neutral btn-sm"><%= label %></a>
+  <%# The page's title and its section tabs, one sticky row under the whole pinned
+      stack (--pin-stack-bottom; then --nav-bottom and --nav-h for a host on an
+      older publisher; then 0). Not --nav-h first: that is the header's HEIGHT,
+      and chrome stacked above the header would sit over the row by its own
+      height. The tabs scroll sideways on a narrow screen, softened by
+      .fade-edge-x; px-8 matches its 2rem fade, so a tab at rest is not faded.
+      The row sits at --z-sticky, above --z-raised, so the live hold button's
+      portal bubbles scroll under it rather than over it.
+  
+      The style-section-nav controller moves the highlight as the page scrolls
+      (studio/style_section_nav). Theme starts active, so the first paint is
+      right before the module loads. %>
+  <nav class="sticky -mx-4 mt-6 px-4 py-2 bg-surface border-y border-subtle flex items-center gap-2"
+       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)"
+       aria-label="Style guide sections"
+       data-studio-controller="style-section-nav">
+    <h1 class="text-xl font-bold text-heading shrink-0">Style</h1>
+    <div class="fade-edge-x overflow-x-auto min-w-0 flex-1" data-style-section-nav-target="scroller">
+      <div class="flex items-center gap-2 min-w-max px-8">
+        <% sections.each_with_index do |(anchor, label), index| %>
+          <a href="#<%= anchor %>"
+             class="btn btn-sm <%= index.zero? ? "btn-primary" : "btn-neutral" %>"
+             <%= 'aria-current="true"'.html_safe if index.zero? %>
+             data-style-section-nav-target="link"><%= label %></a>
         <% end %>
       </div>
     </div>
+    <p class="label-upper shrink-0 hidden md:block" title="studio-engine">v<%= Studio::VERSION %></p>
   </nav>
 
   <div class="space-y-16 pt-10">

data/db/migrate/20261103120000_create_studio_user_sessions.rb

@@ -0,0 +1,16 @@
+# One row per signed-in browser session (Studio::UserSession). A small, cached
+# record every app keeps the same way. No foreign key: a host's users table is
+# its own, and a deleted user's sessions may stay as counts.
+class CreateStudioUserSessions < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_user_sessions do |t|
+      t.bigint :user_id, null: false
+      t.boolean :admin, null: false, default: false
+      t.datetime :started_at, null: false
+      t.datetime :last_seen_at, null: false
+      t.timestamps
+      t.index :user_id
+      t.index :last_seen_at
+    end
+  end
+end

data/docs/SITE_FOOTER.md

@@ -319,6 +319,39 @@ config.site_footer = ->(view) {
   only with a lockup (`studio/site_footer/_lockup_assets`). An engine older
   than the fact ignores the key, so a host can declare it before it upgrades.
 
+## The Chat link
+
+The standard way to reach an app's agent chat ([`AGENT_CHAT.md`](AGENT_CHAT.md)):
+a plain link at the end of the column headed **Contact** (any case), or a new
+Contact column at the end if the facts have none. An app that sets nothing sees
+no change.
+
+```ruby
+config.site_footer_chat_path = "/chat"             # or ->(view) { view.chat_path }
+# config.site_footer_chat_label = "Chat"           # the default
+# config.site_footer_chat_allowed = ->(user) { user&.admin? }  # default: Studio.agent_chat_allowed
+```
+
+| Setting | Meaning | Unset |
+|---------|---------|-------|
+| `site_footer_chat_path` | A path, or a callable taking the view (route helpers do not exist yet in an initializer). It answers nil to show no link on this page | No link |
+| `site_footer_chat_label` | The link's words | "Chat" |
+| `site_footer_chat_allowed` | A callable taking the viewer: `current_user`, **nil when signed out**, so write `user&.admin?` | `Studio.agent_chat_allowed` (everyone, by default) |
+
+- The link looks and behaves as any other column link (`_link.html.erb`). An href
+  the footer refuses (`javascript:`) adds nothing, and a Contact column that
+  already links the same path keeps its own row and label.
+- A hook that raises hides the link and reports once through
+  `Studio::SiteFooter.reporter`, so `user.admin?` on a signed-out viewer shows the
+  link to no one and costs no page. Write `user&.admin?` all the same.
+- **Hiding the link is not a gate.** `Studio.agent_chat_allowed` is
+  ([`AGENT_CHAT.md`](AGENT_CHAT.md), "Who may use it"); set that one, and the link
+  follows it.
+- **An admin-only link needs a page that shows the footer to a signed-in viewer.**
+  A signed-in viewer sees the footer only on `site_footer_controllers` (see
+  *Where it shows*), so list the pages your admins will look at.
+- Never cache the footer across viewers while the link is limited.
+
 ## Where it shows
 
 `studio_site_footer` asks `config.site_footer_visible`, one callable that