studio-engine 0.122.0 → 0.124.0

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/_tricks.html.erb

@@ -72,6 +72,41 @@
     </div>
   </section>
 
+  <!-- Page header -->
+  <section class="space-y-5" data-page-header-specimen>
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Page header</h3>
+      <p class="text-muted text-sm">
+        <code class="font-mono text-2xs">studio/_page_header</code>: the title, optional meta beside
+        it and optional tabs on the right. This page's own title row is one: scroll to see it take the bar.
+        It joins the pinned stack, so a table's sticky header sits under it: navbar, page row, table
+        header, each below the last. The rule is in <code class="font-mono text-2xs">docs/PAGE_HEADER.md</code>.
+      </p>
+    </div>
+    <div class="grid gap-4 lg:grid-cols-2">
+      <%# The classes alone, not the partial: the partial's row is sticky, joins the
+          pinned stack and holds the page's h1, and a page has one of each. %>
+      <% [["At rest", {}], ["Stuck", { stuck: "" }]].each do |state, data| %>
+        <%= render layout: "style/specimen",
+              locals: { klass: "studio/_page_header (#{state.downcase})",
+                        usage: %(<%= render "studio/page_header",\n      title: "Models", meta: "v1.2.3", label: "Models",\n      tabs: [{ label: "Users", href: users_path, current: "page" }, { label: "Teams", href: teams_path }] %\>) } do %>
+          <%= tag.div(class: "page-header w-full px-4", data: data) do %>
+            <div class="page-header-lead">
+              <p class="page-header-title">Models</p>
+              <p class="page-header-meta label-upper">v1.2.3</p>
+            </div>
+            <div class="page-header-tabs">
+              <div class="page-header-track">
+                <a href="#tricks" class="btn btn-sm btn-primary">Users</a>
+                <a href="#tricks" class="btn btn-sm btn-neutral">Teams</a>
+              </div>
+            </div>
+          <% end %>
+        <% end %>
+      <% end %>
+    </div>
+  </section>
+
   <!-- Surfaces, text and form -->
   <section class="space-y-5">
     <div class="space-y-1">

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 page header 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
@@ -53,38 +53,25 @@
     ["components", "Components"]
   ]
 %>
-<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>
+<div class="max-w-6xl mx-auto px-4 pt-6 pb-16">
+  <%# The page's title and its section tabs: studio/_page_header, the row of the
+      triple stack (docs/PAGE_HEADER.md). It sits at --z-sticky, above --z-raised,
+      so the live hold button's portal bubbles scroll under it rather than over it.
 
-  <%# 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>
-        <% end %>
-      </div>
-    </div>
-  </nav>
+      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. %>
+  <%= render "studio/page_header",
+        title: "Style",
+        meta: "v#{Studio::VERSION}",
+        meta_title: "studio-engine",
+        label: "Style guide sections",
+        data: { studio_controller: "style-section-nav" },
+        tabs_data: { style_section_nav_target: "scroller" },
+        tabs: sections.each_with_index.map { |(anchor, label), index|
+          { label: label, href: "##{anchor}", current: (index.zero? ? "true" : nil),
+            data: { style_section_nav_target: "link" } }
+        } %>
 
   <div class="space-y-16 pt-10">
     <%= render "style/theme" %>

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

@@ -53,6 +53,9 @@ It prints only what the engine knows to be true of the app:
   when a GET reaches it and its path needs no arguments. A host with neither
   gets the © line alone.
 
+- **A Marketing Kit link**, when the app has the page: every app that calls
+  `Studio.routes` does ([The marketing kit](#the-marketing-kit)).
+
 It has no address, no map, no phone, no email, no tagline, no social row and no
 link columns, and the page names no Leaflet. The engine cannot know those, and
 a guessed link is a dead one. For any of them, add a location (below) or
@@ -150,8 +153,9 @@ Leave `config.site_footer` unset and the same app gets
 [the default footer](#the-default-footer), its name read from `config.app_name`
 since there is no site-identity table to ask.
 
-Do not call `Studio.routes(self)`: everything it draws (sign-in, admin, error
-logs) needs a database. The app also needs an asset pipeline (Propshaft or
+Do not call `Studio.routes(self)`: what it draws (sign-in, admin, error logs)
+needs a database. The one route that does not is the marketing kit's, which such
+an app can draw alone ([The marketing kit](#the-marketing-kit)). The app also needs an asset pipeline (Propshaft or
 Sprockets), as every Rails 8 app has, and a mapping of the theme tokens onto its
 own palette (see [Colours](#colours)).
 
@@ -200,6 +204,7 @@ Every key is optional. A missing key removes its part of the footer.
 | `columns` | Link columns under bold headings. A column may carry a width hint: `[ "Contact", links, { width: 1.5 } ]` | Brand only |
 | `legal` | The centred line above the © | The © alone |
 | `booking` | `{ label:, title: }` for the popup's heading and the frame's accessible name | "Schedule a call", and "Schedule a call with <name>" |
+| `marketing_kit` | `false` removes the footer's link to the kit ([The marketing kit](#the-marketing-kit)) | The link, on an app with the page |
 
 Rows may be tuples, as above, or hashes (`{ label:, href: }`, `{ heading:, links: }`,
 `{ label:, icon:, url: }`). The rules a row can carry:
@@ -319,6 +324,136 @@ 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 marketing kit
+
+Every app has a public page at `/marketing-kit`, with its logos, colours and
+typefaces, and the footer links it. Neither needs a line of setup.
+
+**The page.** `Studio.routes` draws it by default, with no sign-in. The route's
+helper is `studio_marketing_kit_path`.
+
+| Setting | Meaning | Unset |
+|---------|---------|-------|
+| `config.draw_marketing_kit_routes` | `false` draws no page, and with no page the footer links none | `true` |
+| `config.marketing_kit` | The kit: a Hash, or a callable taking the view | Derived from the theme (below) |
+
+```ruby
+# config/initializers/studio.rb
+config.marketing_kit = {
+  tagline:   "Everything, by example",
+  logos:     [ { title: "Icon", light: { png: "/brand/icon-light.png", svg: "/brand/icon-light.svg" },
+                                dark:  { png: "/brand/icon-dark.png",  svg: "/brand/icon-dark.svg" } } ],
+  palette:   [ { name: "Ink", hex: "#1A1535" } ],
+  typefaces: [ { role: "Headings", family: "Montserrat", weight: 800, name: "Montserrat ExtraBold" } ]
+}
+```
+
+Every key is optional, and each key stands alone: a kit that declares only
+`tagline:` still derives its logos and colours. `logos: []` shows none. `name:`
+overrides the site name in the page's first line.
+
+| Key | With no declaration |
+|-----|---------------------|
+| `logos` | `config.navbar_wordmark` and the footer's `lockup`, each with its two tones, then one logo for each entry in `config.theme_logos` but the favicon. A theme entry names one file, so the rest is looked for beside it: a `-light`/`-dark` or `_light`/`_dark` sibling. A name with no tone in it is the light artwork. Every file's other format (`.png`, `.svg`) is looked for too |
+| `palette` | The colours the app paints: its `/admin/theme` values over `Studio.theme_config` (primary, dark, light, success, warning, danger, accent) |
+| `typefaces` | None. The engine cannot know them, so the section is gone |
+| `tagline` | None |
+
+- **`light` is the artwork for a light background**, and `dark` for a dark one.
+- **A logo offers "Download Light" and "Download Dark".** Each downloads the PNG when
+  there is one, else the SVG. Make the PNG transparent. The tile shows the SVG when
+  there is one. Only PNG and SVG are offered.
+- **A file that is not there is not an error.** Each file is looked for before it is
+  linked, in `public/` and, for a name with no leading `/`, in the asset pipeline. A
+  tone with no file has no tile and no link. A logo with no file has no card. An
+  `http(s)` URL is taken at its word and is not fetched, so a dead one shows a broken
+  image; a browser downloads a cross-origin file only if that host says so.
+- **A colour copies on one click**, on the chip, the name or the hex, and shows
+  "Copied" on the chip. It runs from the lazy `copy-text` controller
+  (`studio/controllers/copy_text_controller`). Only a real hex is printed.
+- **A tile's image carries `?kit`.** A host may repaint its own logo by the image's
+  exact `src` on a dark page, as the hub's `.dark img[src="/brand/icon-light.svg"]`
+  does, and that would turn a light tile's artwork dark. The download keeps the plain URL.
+- **A callable that raises** shows locally. In production it is logged once and the
+  page shows what derives from the theme.
+
+**A host's own page wins.** A GET route of the path `/marketing-kit` beats the
+engine's, whichever side of `Studio.routes` it is drawn on. Drawn before, the engine
+draws nothing; drawn after, the engine's route yields at request time. So the hub
+keeps its page until it adopts this one.
+
+**Sign-in.** `Studio::MarketingKitController` inherits the host's
+`ApplicationController` for its layout and skips each gate it knows by name
+(`HOST_GATES`): `require_authentication`, the hub's `require_admin_wall`,
+`require_admin`, `require_login`, `authenticate_user!` and
+`require_profile_completion`. A gate of another name needs one line:
+
+```ruby
+# config/initializers/studio.rb
+Rails.application.config.to_prepare do
+  Studio::MarketingKitController.skip_before_action :my_gate, raise: false
+end
+```
+
+A host whose test suite walks its route table sees `studio/marketing_kit#show` as a
+public page; list it wherever that suite lists them.
+
+**An app with no database** does not call `Studio.routes`, so it has no page and its
+footer links none. To have both, draw the one route. The page reads no table and no
+session:
+
+```ruby
+# config/routes.rb
+Studio.marketing_kit_routes(self)
+```
+
+**The footer link** is "Marketing Kit", in the brand block, under the tagline and the
+email. Every viewer who sees the footer sees it, on every app with the page, with
+nothing declared. It is not in a link column or on the legal line, so an app's columns
+and legal line stay exactly what it wrote.
+
+- An app that already links the page in a column or on the legal line keeps its own
+  row and gets no second link. The comparison is on the path, so a query or a trailing
+  `/` still counts.
+- `marketing_kit: false` in the facts shows no link.
+- A signed-in viewer sees the footer on the page itself, as on the booking page.
+
+To render the kit in a page of your own:
+`render "studio/marketing_kit/kit", kit: Studio.marketing_kit_for(self)`.
+
+## 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
@@ -445,6 +580,7 @@ These class names are stable, and an app may style against them:
 | `.ftr-link`, `.ftr-link-solid`, `.ftr-link-disabled` | A link; an address kept on one line; a "coming soon" label. `--ftr-link-ink` on `.ftr` is the link colour |
 | `.ftr-location`, `.ftr-location-title`, `.ftr-address` | The Location band |
 | `.ftr-legal`, `.ftr-copyright` | The legal line and the © line |
+| `.ftr-kit` | The Marketing Kit link's line in the brand block |
 | `.ftr-map` | The map |
 | `.ftr-lockup`, `.ftr-lockup-light`, `.ftr-lockup-dark` | The lockup's images; `--ftr-lockup-height` on `.ftr` is its height |
 
@@ -494,5 +630,13 @@ link. Those rules are more specific than the engine's and still apply.
   line inside its column at each, and the line heights. These lab pages load Turbo, so the map's remount after a Turbo visit is
   covered.
 
+- `test/lib/studio/marketing_kit_test.rb`: what a kit resolves to, derived and
+  declared, and that a missing file or a malformed row costs nothing.
+- `test/integration/marketing_kit_test.rb`: the page through a real signed-out
+  request in a host that gates every controller, the footer link and its no-double
+  rule, and a host route of the same path winning from either side.
+- `e2e/marketing_kit.spec.js`: the hex on the clipboard, the confirmation, the
+  refused copy, and the downloads, in a browser.
+
 `/admin/style` shows the footer under Tricks, with this app's own facts, or a
 sample when it has declared none (the default footer or `false`).

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.