studio-engine 0.122.0 → 0.123.0

data/lib/studio/agent_chat.rb

@@ -16,8 +16,8 @@ module Studio
   #
   # THE CONTRACT (.agents/epics/agent-chat-primitive.md, "Contract"):
   #
-  #   POST /api/v1/agent_chat/messages  soul, text, person, ip
-  #        201 {turn} · 422 {error} · 429 capped · 404 soul has no web chat
+  #   POST /api/v1/agent_chat/messages  soul, text, person, ip, voice (optional)
+  #        201 {turn, voice} · 422 {error} · 429 capped · 404 soul has no web chat
   #   GET  /api/v1/agent_chat/turns     soul, person, after, limit (<= 50)
   #        200 {turns: [...], pending: bool}
   #
@@ -27,6 +27,11 @@ module Studio
   # {id, role: "user"|"agent", text, created_at, status} with status
   # pending|typing|answered|failed.
   #
+  # `voice` marks a spoken message: {check, score, duration_ms}, what POST
+  # /voice/takes answered for the take (voice_param). NEVER A NAME: the hub
+  # names the speaker itself (the verified person's own name when check is
+  # "matched", else "Someone new") and may answer what it kept as `voice`.
+  #
   # AUTHENTICATION is the APP's own bearer credential (Studio.agent_chat_token,
   # else ENV["AGENT_CHAT_TOKEN"]), never a user's. It is sent only over TLS: a
   # plain-http hub URL is refused unless its host is this machine (a developer
@@ -83,6 +88,31 @@ module Studio
     MAX_TEXT_LENGTH = 4_000
     # A hub answer larger than this is not a chat answer.
     MAX_BODY_BYTES = 1_048_576
+    # The words beside the microphone, approved by Alex McRitchie on 2026-11-01.
+    # Verbatim here and on an app's privacy page, from this one constant.
+    VOICE_PRIVACY = "When you speak to an agent, your recording is sent to OpenAI to turn it " \
+                    "into text, then deleted. We never keep the audio."
+
+    # The hold-to-talk button's words per recorder state (merged over
+    # Studio::VoiceCapture::RECORDER_COPY). The recorder says nothing while it
+    # records: the chat's own status line says "Listening...", so the button does
+    # not move under a held finger when the line appears.
+    VOICE_RECORDER_COPY = {
+      "idle" => { "button" => "Hold to talk" },
+      "recording" => { "button" => "Let go to send", "status" => "", "heard" => "" },
+      "captured" => { "button" => "Hold to talk", "status" => "" },
+      "silent" => { "button" => "Hold to talk" },
+      "failed" => { "button" => "Hold to try again" },
+      "denied" => { "button" => "Hold to talk" },
+      "unsupported" => { "button" => "Hold to talk" }
+    }.freeze
+
+    # The microphone chip's first words (the engine's say "tap Record").
+    VOICE_CHIP_COPY = {
+      "prompt" => { "chip" => "Microphone: hold to talk to allow",
+                    "note" => "Hold the talk button once and allow the microphone. Then you can pick one here." }
+    }.freeze
+
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
     NETWORK_ERRORS = [
       Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error,
@@ -93,13 +123,49 @@ module Studio
     class << self
       # Stores one message from `person` to `soul` and answers its turn (a Hash
       # with string keys). Raises a Studio::AgentChat::Error.
-      def post_message(soul:, text:, person:, ip: nil)
-        body = { soul: soul.to_s, text: text.to_s, person: person_param(person), ip: ip.to_s.presence }.compact
+      #
+      # `voice` marks it as spoken (voice_param). When the hub answers what it
+      # kept, the returned Hash also carries it under "voice".
+      def post_message(soul:, text:, person:, ip: nil, voice: nil)
+        body = { soul: soul.to_s, text: text.to_s, person: person_param(person), ip: ip.to_s.presence,
+                 voice: voice_param(voice) }.compact
         payload = request(:post, MESSAGES_PATH, body: body)
         turn = payload.is_a?(Hash) && payload["turn"].is_a?(Hash) ? payload["turn"] : payload
         raise Unavailable.new("the hub answered with no turn", status: 201) unless turn.is_a?(Hash)
 
-        turn
+        kept = payload["voice"] if payload.is_a?(Hash)
+        kept.is_a?(Hash) ? turn.merge("voice" => kept) : turn
+      end
+
+      # The words of the chat's voice option: {"privacy", "recorder", "chip"},
+      # the `overrides` (voice_copy: on studio/agent_chat/chat) over the defaults.
+      # A blank privacy line is the default one: the line is never just dropped.
+      def voice_copy(overrides = nil)
+        words = (overrides || {}).to_h.transform_keys(&:to_s)
+        {
+          "privacy" => words["privacy"].presence || VOICE_PRIVACY,
+          "recorder" => Studio::VoiceCapture.merge(VOICE_RECORDER_COPY, words["recorder"]),
+          "chip" => Studio::VoiceCapture.merge(VOICE_CHIP_COPY, words["chip"])
+        }
+      end
+
+      # What a message's `voice` may say to the hub, as the hub reads it: `check`
+      # is one of the engine's own (else Invalid), `score` a cosine (-1..1, 4
+      # places) or nil, `duration_ms` 1..MAX_DURATION_MS or nil. Everything else,
+      # a browser-chosen name above all, stops here. nil or "" is a typed message.
+      def voice_param(voice)
+        return nil if voice.nil? || voice == ""
+
+        voice = voice.to_unsafe_h if voice.respond_to?(:to_unsafe_h)
+        raise Invalid.new("voice must be {check, score, duration_ms}", status: 422) unless voice.is_a?(Hash)
+
+        voice = voice.transform_keys(&:to_s)
+        check = voice["check"].to_s
+        unless Studio::VoiceTranscription::CHECKS.include?(check)
+          raise Invalid.new("voice.check is not one the engine answers", status: 422)
+        end
+
+        { check: check, score: voice_score(voice["score"]), duration_ms: voice_duration(voice["duration_ms"]) }
       end
 
       # The thread's turns after `after` (a turn id; nil for the latest), and
@@ -118,6 +184,18 @@ module Studio
 
       private
 
+      def voice_score(raw)
+        return nil unless raw.is_a?(Numeric) || raw.is_a?(String)
+
+        value = Float(raw, exception: false)
+        value&.finite? ? value.clamp(-1.0, 1.0).round(4) : nil
+      end
+
+      def voice_duration(raw)
+        value = raw.to_s.match?(/\A\d{1,9}\z/) ? raw.to_s.to_i : nil
+        value&.between?(1, Studio::VoiceTranscription::MAX_DURATION_MS) ? value : nil
+      end
+
       # {email:}, {anon_token:}, or both: a signed-in post that still holds the
       # visitor's anon token sends both, and the hub folds that anonymous thread
       # into the person's.

data/lib/studio/site_footer.rb

@@ -170,7 +170,8 @@ module Studio
     #   booking_path: the booking page's path (Studio.booking_path_for), or nil
     #   address:      Studio.site_footer_address: the address of facts that
     #                 carry none of their own
-    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil)
+    #   chat:         the Chat entry's [label, path] (`chat_row`), or nil
+    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil, chat: nil)
       raw = declared.respond_to?(:call) ? declared.call(view) : declared
       return nil if raw.nil? || raw == false
 
@@ -189,7 +190,7 @@ module Studio
         email: text(facts[:email]),
         address: address_for(facts, address),
         social: Array(facts[:social]).filter_map { |row| social(row) },
-        columns: Array(facts[:columns]).filter_map { |row| column(row, booking_path) },
+        columns: with_chat(Array(facts[:columns]).filter_map { |row| column(row, booking_path) }, chat),
         legal: Array(facts[:legal]).filter_map { |row| link(row, booking_path) },
         booking_label: text(booking[:label]) || DEFAULT_BOOKING_LABEL,
         booking_title: text(booking[:title])
@@ -374,6 +375,48 @@ module Studio
       { heading: heading, links: links, width: column_width(options[:width]) }
     end
 
+    # The column the standard Chat entry joins, made if the app has none.
+    CONTACT_HEADING = "Contact"
+
+    # The Chat entry for this viewer as a [label, path] row, or nil: no path
+    # means the app has no chat, and `allowed` (a callable taking the viewer, nil
+    # when signed out) can hide it, e.g. admins only while testing. A hook that
+    # raises hides the entry and logs; the footer is on every page, and a link
+    # meant for a few must not show because its gate broke.
+    def chat_row(view, path:, label: nil, allowed: nil)
+      href = path.respond_to?(:call) ? path.call(view) : path
+      return nil if text(href).nil?
+      return nil unless chat_allowed?(view, allowed)
+
+      [text(label) || "Chat", href]
+    end
+
+    def chat_allowed?(view, allowed)
+      return true if allowed.nil?
+
+      user = view.respond_to?(:current_user) ? view.current_user : nil
+      (allowed.respond_to?(:call) ? allowed.call(user) : allowed) ? true : false
+    rescue StandardError => error
+      SiteFooter.reporter.call("[studio.site_footer] site_footer_chat_allowed raised #{error.class}: the Chat link is hidden")
+      false
+    end
+
+    # `columns` with the Chat entry last in the Contact column (any case), which
+    # is added at the end if there is none. A refused href adds nothing, and an
+    # app that already links the same path keeps its own row.
+    def with_chat(columns, chat)
+      row = chat && link(chat)
+      return columns if row.nil? || row[:href].nil?
+
+      at = columns.index { |column| column[:heading].to_s.casecmp?(CONTACT_HEADING) }
+      return columns + [{ heading: CONTACT_HEADING, links: [row], width: nil }] if at.nil?
+      return columns if columns[at][:links].any? { |known| known[:href] == row[:href] }
+
+      columns.each_with_index.map do |column, index|
+        index == at ? column.merge(links: column[:links] + [row]) : column
+      end
+    end
+
     # A column's width hint, or nil for the default share. Anything that is not a
     # number between MIN_COLUMN_WIDTH and MAX_COLUMN_WIDTH is no hint.
     MIN_COLUMN_WIDTH = 0.5

data/lib/studio/ui_primitives.rb

@@ -10,8 +10,10 @@ module Studio
         align-items: center;
         justify-content: center;
         vertical-align: middle;
-        width: 1.5rem;
-        height: 1.25rem;
+        /* In em so a larger glyph fits: at text-lg on a 16px scale a fixed 1.25rem
+           box clipped 4px off a 24px emoji. The floor keeps the navbar size. */
+        width: max(1.5rem, 1.25em);
+        height: max(1.25rem, 1.25em);
         overflow: hidden;
       }
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.122.0"
+  VERSION = "0.123.0"
 end

data/lib/studio.rb

@@ -1471,7 +1471,7 @@ module Studio
   mattr_accessor :agent_chat_souls,   default: []
   mattr_accessor :agent_chat_hub_url, default: "https://mcritchie.studio"
   # The app's bearer credential for the hub. Leave nil to read
-  # ENV["AGENT_CHAT_TOKEN"] (1Password apps.<slug>.agent-chat).
+  # ENV["AGENT_CHAT_TOKEN"] (1Password agent-chat.<slug>.applications).
   mattr_accessor :agent_chat_token,   default: nil
   # Which signed-in users the hub may know by email. An email the user only
   # CLAIMS (the profile page saves a new address and clears email_verified_at;
@@ -1486,6 +1486,50 @@ module Studio
     Array(agent_chat_souls).map { |soul| soul.to_s.strip }.reject(&:empty?).uniq
   end
 
+  # Who may use the chat at all: a callable taking the user, nil when signed out.
+  # The server's gate, not only the look: Studio::AgentChatsController answers a
+  # refused viewer 403 on both calls before any hub call, and the chat partial
+  # renders nothing for them. The footer's Chat link follows it too unless
+  # site_footer_chat_allowed is set, so one setting covers both. Default: everyone
+  # (a public chat). While testing:
+  #
+  #   config.agent_chat_allowed = ->(user) { user&.admin? }
+  mattr_accessor :agent_chat_allowed, default: ->(_user) { true }
+
+  # The one reading of Studio.agent_chat_allowed. A hook that raises answers false
+  # and logs: `user.admin?` on a signed-out visitor closes the chat, never opens it.
+  def self.agent_chat_allowed?(user)
+    hook = agent_chat_allowed
+    (hook.respond_to?(:call) ? hook.call(user) : hook) ? true : false
+  rescue StandardError => e
+    Rails.logger&.warn("[studio] agent_chat_allowed raised #{e.class}: treated as not allowed") if defined?(Rails.logger)
+    false
+  end
+
+  # Who may talk by voice (docs/AGENT_CHAT.md, "Talking by voice"): a callable
+  # taking the signed-in user. It decides who sees the chat's microphone, who
+  # may post a take to POST /voice/takes (each one is a paid vendor call), and
+  # whether the proxy forwards a message's `voice`. A signed-out visitor is
+  # never asked about: no user, no voice. While testing, an app narrows it:
+  #
+  #   config.voice_chat_allowed = ->(user) { user.admin? }
+  #
+  # A user Studio.agent_chat_allowed refuses may not talk either, whatever this says.
+  mattr_accessor :voice_chat_allowed, default: ->(user) { user.present? }
+
+  # The one reading of Studio.voice_chat_allowed. False for no user, and for a user
+  # the chat itself refuses, whatever the hook says. A hook that raises answers false and logs: the safe answer on a
+  # paid, sign-in-only control, and a page never falls over because of it.
+  def self.voice_chat_allowed?(user)
+    return false if user.nil? || !agent_chat_allowed?(user)
+
+    hook = voice_chat_allowed
+    (hook.respond_to?(:call) ? hook.call(user) : hook) ? true : false
+  rescue StandardError => e
+    Rails.logger&.warn("[studio] voice_chat_allowed raised #{e.class}: treated as not allowed") if defined?(Rails.logger)
+    false
+  end
+
   class S3ConfigError < StandardError; end
 
   # Whether to validate the host app's User model at boot. See docs/USER_CONTRACT.md.
@@ -1733,6 +1777,20 @@ module Studio
     SidebarSections.resolve(sidebar_sections, view)
   end
 
+  # The standard Chat entry in the footer's Contact column (docs/SITE_FOOTER.md,
+  # "The Chat link"). OFF until the app names a path: no path, no entry.
+  #
+  #   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
+  #
+  # site_footer_chat_allowed takes the viewer, nil when signed out; a hook that
+  # raises hides the entry and logs (SiteFooter.chat_row). Unset, the link follows
+  # Studio.agent_chat_allowed, so the link shows to whom the chat answers.
+  mattr_accessor :site_footer_chat_path, default: nil
+  mattr_accessor :site_footer_chat_label, default: "Chat"
+  mattr_accessor :site_footer_chat_allowed, default: nil
+
   # The site footer's facts resolved for a view (lib/studio/site_footer.rb), or
   # nil when the app turned the footer off (or its own callable answered nil).
   # Unset, the facts are the default footer's. The name defaults to the site
@@ -1744,7 +1802,10 @@ module Studio
 
     declared = site_footer.nil? ? SiteFooter.default_facts(view, routes: host_route_set) : site_footer
     SiteFooter.resolve(declared, view, name: site_identity[:title], logo: logo_for("Footer Logo"),
-                                       booking_path: booking_path_for(view), address: site_footer_address)
+                                       booking_path: booking_path_for(view), address: site_footer_address,
+                                       chat: SiteFooter.chat_row(view, path: site_footer_chat_path,
+                                                                       label: site_footer_chat_label,
+                                                                       allowed: site_footer_chat_allowed.nil? ? agent_chat_allowed : site_footer_chat_allowed))
   end
 
   # The host's route set, for the default footer's legal links. nil outside a
@@ -2051,11 +2112,8 @@ module Studio
         get "schedule", to: "studio/bookings#show", as: :studio_booking
       end
 
-      # The living style guide. Canonical at /admin/style (StyleController#index);
-      # /admin/design_system redirects here but KEEPS its admin_design_system_path
-      # helper so a shipped host sidebar link on the old helper still resolves.
+      # The living style guide (StyleController#index).
       get   "admin/style",            to: "style#index",               as: :admin_style
-      get   "admin/design_system",    to: redirect("/admin/style"),    as: :admin_design_system
 
       # The component gallery: Lookbook over the engine's ViewComponent previews.
       # The router refuses anyone but a signed-in admin, so a visitor and a

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.122.0
+  version: 0.123.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-01 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -477,6 +477,7 @@ files:
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
+- app/helpers/studio/agent_chat_helper.rb
 - app/helpers/studio/at_time_helper.rb
 - app/helpers/studio/fizz_helper.rb
 - app/helpers/studio/geo_helper.rb
@@ -489,6 +490,7 @@ files:
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/javascript/studio/agent_chat.js
+- app/javascript/studio/agent_chat_voice.js
 - app/javascript/studio/alpine_scopes.js
 - app/javascript/studio/alpine_shims.js
 - app/javascript/studio/alpine_stores.js
@@ -498,6 +500,7 @@ files:
 - app/javascript/studio/booking.js
 - app/javascript/studio/confirm_interstitial.js
 - app/javascript/studio/controllers/agent_chat_controller.js
+- app/javascript/studio/controllers/agent_chat_voice_controller.js
 - app/javascript/studio/controllers/board_controller.js
 - app/javascript/studio/controllers/booking_controller.js
 - app/javascript/studio/controllers/email_banner_scale_controller.js
@@ -512,6 +515,7 @@ files:
 - app/javascript/studio/controllers/modal_host_controller.js
 - app/javascript/studio/controllers/nav_collapse_controller.js
 - app/javascript/studio/controllers/style_modals_controller.js
+- app/javascript/studio/controllers/style_section_nav_controller.js
 - app/javascript/studio/controllers/survey_controller.js
 - app/javascript/studio/controllers/toast_controller.js
 - app/javascript/studio/controllers/voice_profile_controller.js
@@ -548,6 +552,7 @@ files:
 - app/javascript/studio/studio_confetti.js
 - app/javascript/studio/style_guide.js
 - app/javascript/studio/style_modals.js
+- app/javascript/studio/style_section_nav.js
 - app/javascript/studio/survey.js
 - app/javascript/studio/theme_editor.js
 - app/javascript/studio/toast.js
@@ -581,6 +586,7 @@ files:
 - app/models/studio/model_page.rb
 - app/models/studio/site_identity.rb
 - app/models/studio/survey_response.rb
+- app/models/studio/user_session.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
 - app/services/studio/banner.rb
@@ -631,8 +637,8 @@ files:
 - app/views/studio/_leveling_activity_assets.html.erb
 - app/views/studio/_session_stamp.html.erb
 - app/views/studio/admin_models/_arenas_table.html.erb
+- app/views/studio/admin_models/_sessions_table.html.erb
 - app/views/studio/admin_models/_teams_table.html.erb
-- app/views/studio/admin_models/index.html.erb
 - app/views/studio/admin_models/show.html.erb
 - app/views/studio/admin_surveys/index.html.erb
 - app/views/studio/admin_surveys/show.html.erb
@@ -641,6 +647,7 @@ files:
 - app/views/studio/agent_chat/_header.html.erb
 - app/views/studio/agent_chat/_turn.html.erb
 - app/views/studio/agent_chat/_typing.html.erb
+- app/views/studio/agent_chat/_voice.html.erb
 - app/views/studio/banners/_app_banner.html.erb
 - app/views/studio/banners/_button.html.erb
 - app/views/studio/banners/_dev_mode_button.html.erb
@@ -796,7 +803,6 @@ files:
 - app/views/style/modals/_unsubscribe_confirm.html.erb
 - app/views/style/modals/_wallet_connect.html.erb
 - app/views/style/modals/_wallet_connect_slot.html.erb
-- app/views/theme_settings/edit.html.erb
 - app/views/user_mailer/magic_link.html.erb
 - app/views/user_mailer/magic_link.text.erb
 - config/importmap.rb
@@ -821,6 +827,7 @@ files:
 - db/migrate/20261008120000_add_recording_to_studio_knowledge_docs.rb
 - db/migrate/20261010120000_add_stored_in_to_image_caches.rb
 - db/migrate/20261029120000_add_voice_profile_to_users.rb
+- db/migrate/20261103120000_create_studio_user_sessions.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb

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

@@ -1,31 +0,0 @@
-<% content_for(:title, "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 QA</p>
-      <h1 class="text-heading text-2xl font-bold mt-1">Models</h1>
-      <p class="text-muted text-sm mt-1">Ten-row snapshots for records that need quick inspection.</p>
-    </div>
-    <%= link_to "Back to dashboard", admin_dashboard_path, class: "btn btn-outline" %>
-  </header>
-
-  <div class="space-y-5">
-    <% @sections.each do |section| %>
-      <section id="model-<%= section.fetch(:key) %>" class="card overflow-hidden">
-        <div class="px-4 py-4 border-b border-subtle flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
-          <div>
-            <h2 class="text-heading text-lg font-semibold"><%= section.fetch(:label) %></h2>
-            <p class="text-xs text-muted"><%= section.fetch(:description) %></p>
-          </div>
-          <div class="flex items-center gap-3">
-            <span class="text-xs text-muted">Showing <%= section.fetch(:records).size %> of <%= section.fetch(:count) %></span>
-            <%= link_to "View all", admin_model_path(section.fetch(:key)), class: "text-xs text-primary hover:underline" %>
-          </div>
-        </div>
-
-        <%= render admin_models_table_partial(section.fetch(:key)), records: section.fetch(:records) %>
-      </section>
-    <% end %>
-  </div>
-</div>