studio-engine 0.129.0 → 0.131.0

data/app/javascript/studio/stimulus.js

@@ -65,9 +65,16 @@ export const schema = {
 // 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 the talk-to-agent modal: its links are real links, and with its
+// controller failed each one opens its href (data-studio-controller-failed="talk-to-agent").
 // 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").
+// So is the carousel: its track is a native scroll row, and one whose controller
+// failed keeps a scrollbar and hides the arrows and dots it cannot drive.
+// So is infinite scroll: a list whose controller failed keeps its "Load more"
+// link, which loads the next page by itself. So is pull to refresh: nothing
+// depends on it, and the browser's own reload still works.
 export const LAZY = {
   "board": () => import("studio/controllers/board_controller"),
   "geo-settings": () => import("studio/controllers/geo_settings_controller"),
@@ -79,11 +86,15 @@ export const LAZY = {
   "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"),
+  "talk-to-agent": () => import("studio/controllers/talk_to_agent_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"),
   "copy-text": () => import("studio/controllers/copy_text_controller"),
-  "page-header": () => import("studio/controllers/page_header_controller")
+  "page-header": () => import("studio/controllers/page_header_controller"),
+  "carousel": () => import("studio/controllers/carousel_controller"),
+  "infinite-scroll": () => import("studio/controllers/infinite_scroll_controller"),
+  "pull-to-refresh": () => import("studio/controllers/pull_to_refresh_controller")
 }
 
 export const application = Application.start(document.documentElement, schema)

data/app/javascript/studio/talk_to_agent.js

@@ -0,0 +1,116 @@
+// studio/talk_to_agent: the talk-to-agent modal (studio/agent_chat/_talk_modal;
+// docs/AGENT_CHAT.md, "Talk to an agent in a modal"). It wraps the shared agent
+// chat, studio/agent_chat, in the page-scoped modal host; it is not a second
+// chat.
+//
+//   LINKS    any element carrying data-studio-talk-to-agent opens the modal:
+//
+//              <a href="/chat" data-studio-talk-to-agent data-talk-soul="alex"
+//                 data-talk-topic="Pro" data-talk-opener="Tell me about Pro.">
+//
+//            The click is taken only when the soul is this modal's, no modifier
+//            key is held and the host's Alpine store is there. Otherwise the
+//            link does what its href says, so a page whose modal failed to load
+//            still reaches the chat.
+//   OPEN     the store opens TALK_MODAL_ID; the panel the host clones in asks
+//            for its chat (PANEL_EVENT), and this module fills it with a fresh
+//            copy of the chat from the partial's <template>, marked with the
+//            link's opener (data-agent-chat-opener, keyed by soul and topic)
+//            and the type-in. studio/agent_chat then loads the thread and sends
+//            the opener, so the agent is answering while the card animates in.
+//   CLOSE    the host drops the panel; the chat's controller disconnects and
+//            stops polling. The thread stays on the hub: the next open shows it.
+//
+// It imports nothing, so test/javascript/talk_to_agent.test.mjs loads it as a
+// data: module; studio/controllers/talk_to_agent_controller mounts it.
+
+export const TALK_SELECTOR = "[data-studio-talk-to-agent]"
+export const TALK_MODAL_ID = "talk-to-agent"
+export const PANEL_EVENT = "studio:talk-to-agent:panel"
+export const TOPIC_MAX = 80
+export const OPENER_MAX = 500
+
+function clean(value, max) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, max)
+}
+
+// What a link asks for: {soul, topic, opener}. The opener defaults to a plain
+// line naming the topic; with no topic and no opener there is nothing to send.
+export function talkFrom(link) {
+  const data = (link && link.dataset) || {}
+  const topic = clean(data.talkTopic, TOPIC_MAX)
+  const opener = clean(data.talkOpener, OPENER_MAX) || (topic ? `I'd like to talk about ${topic}.` : "")
+  return { soul: clean(data.talkSoul, 64), topic, opener }
+}
+
+// The key an opener is sent once under (per tab): the soul and the topic.
+export function openerKey(soul, topic) {
+  return `${soul}:${topic || "general"}`
+}
+
+// Whether this click is the modal's to take: a plain primary click.
+export function plainClick(event) {
+  if (!event) return false
+  if (event.defaultPrevented) return false
+  if (event.button != null && event.button !== 0) return false
+  return !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+}
+
+// The dialog's accessible name and the header's words.
+export function dialogTitle(name, topic) {
+  return topic ? `Talk to ${name} about ${topic}` : `Talk to ${name}`
+}
+
+export function mountTalkToAgent(root, {
+  doc = globalThis.document,
+  store = (name) => (globalThis.Alpine && typeof globalThis.Alpine.store === "function" ? globalThis.Alpine.store(name) : null)
+} = {}) {
+  const soul = root.dataset.talkToAgentSoul
+  const name = root.dataset.talkToAgentName || "the agent"
+  const storeName = root.dataset.talkToAgentStore
+  let current = null
+
+  function onClick(event) {
+    const link = event.target && event.target.closest ? event.target.closest(TALK_SELECTOR) : null
+    if (!link || !plainClick(event)) return
+    const asked = talkFrom(link)
+    if (asked.soul !== soul) return
+    const modals = store(storeName)
+    if (!modals || typeof modals.open !== "function") return
+    event.preventDefault()
+    current = asked
+    modals.open(TALK_MODAL_ID, { title: dialogTitle(name, asked.topic), topic: asked.topic })
+  }
+
+  // The host cloned the panel in: give it a fresh chat for the link that opened it.
+  function onPanel(event) {
+    const panel = event.target
+    const template = root.querySelector("template[data-talk-to-agent-chat]")
+    const slot = panel && panel.querySelector ? panel.querySelector("[data-talk-to-agent-slot]") : null
+    if (!template || !slot || !template.content || !template.content.firstElementChild) return
+    const asked = current || { topic: "", opener: "" }
+    const heading = panel.querySelector("[data-talk-to-agent-title]")
+    if (heading) heading.textContent = dialogTitle(name, asked.topic)
+    const chat = template.content.firstElementChild.cloneNode(true)
+    if (asked.opener) {
+      chat.dataset.agentChatOpener = asked.opener
+      chat.dataset.agentChatOpenerKey = openerKey(soul, asked.topic)
+    }
+    chat.dataset.agentChatReveal = "true"
+    slot.replaceChildren(chat)
+  }
+
+  doc && doc.addEventListener && doc.addEventListener("click", onClick)
+  root.addEventListener(PANEL_EVENT, onPanel)
+  root.dataset.talkToAgentReady = "true"
+
+  return {
+    open(link) { onClick({ target: link, button: 0, preventDefault() {} }) },
+    get current() { return current },
+    destroy() {
+      doc && doc.removeEventListener && doc.removeEventListener("click", onClick)
+      root.removeEventListener(PANEL_EVENT, onPanel)
+      delete root.dataset.talkToAgentReady
+    }
+  }
+}

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

@@ -86,7 +86,7 @@
         line at rest, its description on hover or focus. %>
     <% if geo_live %>
       <%= link_to admin_geo_path,
-            class: "group flex items-center gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset transition",
+            class: "group flex items-center gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink focus-visible:ring-inset transition",
             "data-sidebar-row-described": "",
             "aria-current": (Studio.sidebar_style == :glass && respond_to?(:request) && request&.path == admin_geo_path ? "page" : nil),
             "@click": geo_close do %>
@@ -104,7 +104,7 @@
           omission: the row's whole job in this state is to hand over the string, and
           select-none made it unselectable. role/aria-disabled give a screen reader
           the "unavailable destination" this paints for a sighted eye. %>
-      <span class="flex items-center gap-3 px-4 py-3 text-sm text-muted cursor-not-allowed focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset"
+      <span class="flex items-center gap-3 px-4 py-3 text-sm text-muted cursor-not-allowed focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink focus-visible:ring-inset"
             role="link"
             aria-disabled="true"
             tabindex="0"

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

@@ -79,7 +79,7 @@
         <% target = link[:target].presence %>
         <% line_icon = (studio_icon(link[:icon]) if glass && link[:icon].present?) %>
         <%= link_to link[:href],
-              class: "group flex items-center gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset transition",
+              class: "group flex items-center gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink focus-visible:ring-inset transition",
               target: target,
               rel: target == "_blank" ? "noopener" : nil,
               "data-sidebar-row-described": (link[:desc].present? ? "" : nil),
@@ -158,7 +158,7 @@
   <% if logged_in? %>
     <div class="border-t border-subtle p-2"<% if glass %> data-sidebar-glass-foot<% end %>>
       <%= link_to logout_path,
-            class: "flex items-center gap-3 rounded-md px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 transition",
+            class: "flex items-center gap-3 rounded-md px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink transition",
             "@click": close_action do %>
         <% if glass %><span class="flex-shrink-0" data-sidebar-row-icon><%= studio_icon("log-out") %></span><% else %><span>👋</span><% end %><span>Log out</span>
       <% end %>

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

@@ -10,7 +10,7 @@
 <% sidebar_admin = respond_to?(:admin?) && admin? %>
 <button type="button"
         @click.stop="$store.sidebars.linkTreeOpen = !$store.sidebars.linkTreeOpen"
-        class="<%= extra_classes %> h-9 w-9 items-center justify-center rounded-md text-secondary hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 transition"
+        class="<%= extra_classes %> h-9 w-9 items-center justify-center rounded-md text-secondary hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink transition"
         title="<%= sidebar_admin ? 'Admin Menu' : 'Links' %>"
         aria-label="<%= sidebar_admin ? 'Toggle admin menu' : 'Toggle links menu' %>"
         aria-controls="studio-link-sidebar studio-link-sidebar-mobile"

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

@@ -111,7 +111,7 @@
           <% if close_action.present? %>
             <button type="button"
                     @click="<%= close_action %>"
-                    class="flex items-center justify-center w-8 h-8 rounded-full text-secondary hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 transition"
+                    class="flex items-center justify-center w-8 h-8 rounded-full text-secondary hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-ink transition"
                     aria-label="Close sidebar"
                     data-link-sidebar-close="true"<% if close_hook %> data-sidebar-panel-close="<%= id %>"<% end %>>
               <span class="text-xl leading-none">&times;</span>

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

@@ -26,19 +26,13 @@
            class="input-field pr-10 py-2.5 text-sm placeholder:text-muted"
            :readonly="loading" />
     <div x-show="loading" x-cloak class="absolute right-3 top-1/2 -translate-y-1/2">
-      <svg class="animate-spin h-4 w-4 text-primary" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
-        <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-        <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
-      </svg>
+      <%= studio_loader style: :spinner, size: 16, label: "Searching" %>
     </div>
   </form>
 
   <!-- Loading state -->
   <div x-show="loading" x-cloak class="py-16 text-center">
-    <svg class="animate-spin h-8 w-8 text-primary mx-auto mb-3" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
-      <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-      <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
-    </svg>
+    <div class="mb-3 flex justify-center"><%= studio_loader style: :spinner, size: 32, label: "" %></div>
     <p class="text-muted text-sm">Searching...</p>
   </div>
 

data/app/views/studio/_carousel.html.erb

@@ -0,0 +1,97 @@
+<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil) %>
+<%# THE CAROUSEL: one sideways row of slides, the apps' standard for a set too
+    long to grid. Render it as a layout, so each slide is your own block:
+
+      render layout: "studio/carousel", locals: { label: "Portfolio", items: @apps } do |app|
+        render "apps/card", app: app
+      end
+
+      label        the region's accessible name. Required: a screen reader says
+                   "Portfolio, carousel".
+      items        one slide per item; the block draws it.
+      per_view     whole slides in view on a wide row (1 to 6). A medium row shows
+                   up to two, a phone one, and every width shows a sliver of the
+                   next slide, so a visitor sees there is more.
+      id           the track's id, for the arrows' aria-controls. Defaults from
+                   the label; pass one when two carousels on a page share a label.
+      slide_label  a callable that names a slide from its item. Without one a
+                   slide is "2 of 6".
+      data         data attributes for the region, such as a test hook.
+      class_name   classes for the region, such as its width.
+      style        :standard (slides snap to the start) or :spotlight (the
+                   centred slide is full size and colour, its neighbours smaller,
+                   faded and grey, and the arrows and keys move one slide).
+      caption      a callable that writes a line under a slide from its item.
+                   The spotlight shows it under the centred slide only.
+
+    THE SPOTLIGHT (engine.css, carousel-spotlight) snaps each slide to the centre.
+    Where the browser has scroll-driven animations, each slide's own view timeline
+    scales and fades it as it nears the centre, so the effect follows the finger.
+    Elsewhere the controller marks the centred slide (data-current) and CSS
+    transitions it. Under reduced motion nothing scales: the neighbours are only
+    dimmed.
+
+    THE TRACK IS A NATIVE SCROLL-SNAP ROW (engine.css, carousel). A swipe, a
+    trackpad, a wheel and a focused link move it with no script. The carousel
+    controller (studio/controllers/carousel_controller) adds the edge fade, the
+    arrows, the dots and the keys, and until it connects the controls stay
+    hidden and the row keeps a thin scrollbar. The widths come from container
+    queries on the region, so a carousel in a narrow column lays out as a phone
+    does.
+
+    ACCESSIBLE BY THE APG CAROUSEL PATTERN: a labelled region with
+    aria-roledescription carousel, a focusable track named "<label> slides", each
+    slide a group with aria-roledescription slide and its own label, named arrows
+    that set aria-disabled at an end (not disabled, so focus stays on the arrow),
+    and a polite, atomic status line that speaks only after a press that moves the
+    row. A key pressed in a form field, an arrow-key widget (a slider, a tab list,
+    a listbox...) or a nested carousel stays that element's. %>
+<%
+  per_view = per_view.to_f.clamp(1, 6)
+  per_view = per_view.to_i if per_view == per_view.floor
+  items = items.to_a
+  total = items.size
+  spotlight = case style.to_s
+              when "standard" then false
+              when "spotlight" then true
+              else raise ArgumentError, "studio/carousel style: #{style.inspect} is not :standard or :spotlight"
+              end
+  track_id = id.presence || "carousel-#{label.to_s.parameterize.presence || 'slides'}"
+%>
+<%= tag.section(class: ["carousel", ("carousel-spotlight" if spotlight), class_name].compact.join(" "),
+      role: "region",
+      aria: { roledescription: "carousel", label: label },
+      style: "--carousel-per-view: #{per_view}",
+      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key" }.merge(data)) do %>
+  <%# The track takes focus for the keys, so it carries a name: a group, since a
+      bare div may not be named. %>
+  <div id="<%= track_id %>" class="carousel-track" tabindex="0" role="group"
+       aria-label="<%= label %> slides" data-carousel-target="track">
+    <% items.each_with_index do |item, index| %>
+      <div class="carousel-slide" role="group" aria-roledescription="slide"
+           aria-label="<%= slide_label ? slide_label.call(item) : "#{index + 1} of #{total}" %>"
+           data-carousel-target="slide"><% if spotlight %><div class="carousel-spotlight-body"><%= yield(item) %></div><% else %><%= yield(item) %><% end %><% if caption %><div class="carousel-caption"><%= caption.call(item) %></div><% end %></div>
+    <% end %>
+  </div>
+  <div class="carousel-controls">
+    <div class="carousel-dots" role="group" aria-label="Choose a slide">
+      <% total.times do |index| %>
+        <button type="button" class="carousel-dot" aria-label="Go to slide <%= index + 1 %>"
+                aria-controls="<%= track_id %>"<%= ' aria-current="true"'.html_safe if index.zero? %>
+                data-carousel-target="dot" data-carousel-index="<%= index %>"
+                data-studio-action="click->carousel#goTo"></button>
+      <% end %>
+    </div>
+    <div class="carousel-arrows">
+      <button type="button" class="carousel-button" aria-label="Previous slides" aria-controls="<%= track_id %>"
+              aria-disabled="true" data-carousel-target="prev" data-studio-action="click->carousel#prev">
+        <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12.5 15 7.5 10l5-5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </button>
+      <button type="button" class="carousel-button" aria-label="Next slides" aria-controls="<%= track_id %>"
+              data-carousel-target="next" data-studio-action="click->carousel#next">
+        <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m7.5 5 5 5-5 5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </button>
+    </div>
+  </div>
+  <p class="sr-only" role="status" aria-live="polite" aria-atomic="true" data-carousel-target="status"></p>
+<% end %>

data/app/views/studio/_fizz.html.erb

@@ -0,0 +1,26 @@
+<%#
+  Fizz around any button: bubbles that rise from behind it. Render it as a layout,
+  with the button as the block.
+
+    render layout: "studio/fizz", locals: { seed: "save" } do
+      <button class="btn btn-primary">Save</button>
+    end
+
+  Locals:
+    seed   - the string the bubble table is seeded from, so the scatter is stable
+             for this button and differs from its neighbours
+    level  - :lively (default), which boils at rest and adds a layer on hover, or
+             :calm, which simmers at rest and boils on hover
+    colors - optional palette, up to 18, three per zone (--fizz-c-1..18)
+
+  Decoration only. The hold button keeps its own stack (studio/_hold_button).
+%>
+<% lively = local_assigns.fetch(:level, :lively).to_s == "lively" %>
+<% fizz_style = fizz_stack_style(local_assigns[:colors]) %>
+<span class="fizz-stack<%= " fizz-lively" if lively %>"<% if fizz_style.present? %> style="<%= fizz_style %>"<% end %>>
+  <%= render "studio/fizz_layer", seed: seed, neutral: true %>
+  <% if lively %>
+    <%= render "studio/fizz_layer", seed: "#{seed}~extra", extra: true, neutral: true %>
+  <% end %>
+  <%= yield %>
+</span>

data/app/views/studio/_fizz_layer.html.erb

@@ -7,10 +7,13 @@
             in each other's gaps rather than on top of each other)
     extra - true for the hover-only layer, which rests invisible and fades in
             when the pointer arrives (default: false)
+    neutral - true inside a .fizz-stack (studio/_fizz), a button with no hold, so
+            the layer carries the neutral class names (default: false)
 
   The two layers also split each zone's three colour slots: the resting one
   takes the first, the hover one alternates the second and third.
   Decoration only: aria-hidden here, pointer-events off in CSS.
 %>
 <% extra ||= false %>
-<span class="hold-fizz<%= " hold-fizz-extra" if extra %>" aria-hidden="true"><% fizz_bits(seed, layer: extra ? :hover : :base).each do |bit| %><i class="fizz-bit" style="<%= fizz_bit_style(bit) %>"></i><% end %></span>
+<% neutral ||= false %>
+<span class="<%= neutral ? "fizz-layer" : "hold-fizz" %><%= (neutral ? " fizz-layer-extra" : " hold-fizz-extra") if extra %>" aria-hidden="true"><% fizz_bits(seed, layer: extra ? :hover : :base).each do |bit| %><i class="fizz-bit" style="<%= fizz_bit_style(bit) %>"></i><% end %></span>

data/app/views/studio/_hold_button.html.erb

@@ -74,8 +74,7 @@
 <% fizz_portal = fizz && local_assigns[:fizz_portal] %>
 <%# Static palette (gallery, or any call site with fixed colors). A runtime
     palette rides fizz_bind instead. %>
-<% fizz_style = Array(fizz_colors).first(Studio::FizzHelper::SLOTS)
-                                  .each_with_index.map { |c, i| "--fizz-c-#{i + 1}:#{c}" }.join(";") %>
+<% fizz_style = fizz_stack_style(fizz_colors) %>
 
 <%# The stack exists so the fizz can sit BEHIND the button. Inside the button
     a negative z-index still paints above its own background (the button's

data/app/views/studio/_page_header.html.erb

@@ -1,20 +1,33 @@
-<%# locals: (title:, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, data: {}, row_class: "-mx-4 px-4") %>
-<%# THE PAGE HEADER: the second layer of the triple stack (docs/PAGE_HEADER.md).
-    navbar, then this row, then a table's sticky header, each below the last.
+<%# locals: (title:, crumbs: [], crumb_label: nil, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, links: [], links_label: "More links", data: {}, row_class: "-mx-4 px-4") %>
+<%# THE PAGE HEADER: the second layer of the pinned stack (docs/PAGE_HEADER.md).
+    navbar, then this row, then a section's header (studio/_section_header), then a
+    table's sticky header, each below the last.
 
     AT REST it has no background and no border: a title on the left, tabs on the
     right. ONCE STUCK under the navbar it takes the bar. Its box never changes
     between the two, so a state change moves nothing and republishes nothing.
 
       title         the page's one h1.
+      crumbs        the trail above the title: the page's ancestors, root first, as
+                    [{ label:, href: }]. studio_crumbs builds it from the app's one
+                    parent map (Studio::Crumbs). The trail ends with the page itself,
+                    crumb_label or else the title. Below 40rem the trail gives way to
+                    one link to the parent. Every ancestor link carries
+                    data-page-transition-back, so the page transition plays the
+                    app's move the other way (docs/PAGE_TRANSITIONS.md).
+      crumb_label   the page's own name in the trail, when the title is long.
       meta          short text beside the title, such as the version. Hidden on a
                     phone, where the tabs need the width.
       meta_title    the meta's title attribute.
-      label         the nav's accessible name. A row with tabs needs it.
+      label         the tabs' nav's accessible name. A row with tabs needs it.
       tabs          [{ label:, href:, current:, data: }]. `current` is the
                     aria-current value ("page" or "true"), and blank on the others.
       tabs_data     data attributes for the tabs' scroller.
-      actions_html  a control on the right, for a row with no tabs.
+      actions_html  a control on the right, such as the page's one primary action.
+                    After the tabs, when the row has both.
+      links         the page's other links, [{ label:, href:, current: }], on a line of
+                    their own at the foot of the row, so they stick with it.
+      links_label   that line's accessible name.
       data          data attributes for the row, such as the page's own controller.
       row_class     the bleed. The default fits a container with px-4; pass "" in a
                     container with no gutter of its own.
@@ -26,6 +39,9 @@
     <header> as the navbar, so on a page with no navbar this row would publish as
     --nav-bottom.
 
+    NOR IS IT A LANDMARK. The row is a div; the tabs, the crumbs and the links line
+    are each their own <nav>, side by side, so no landmark nests in another.
+
     IT JOINS THE STACK WITH data-pin="page" AND POSITIONS OFF --pin-page-top, the
     bottom of everything above it. --pin-stack-bottom includes the row's own edge,
     so a row positioned off it would chase itself down the page. Anything below,
@@ -39,11 +55,24 @@
     page's own. So the row carries no top margin: the space above it belongs to its
     container. %>
 <div class="page-header-sentinel" data-studio-controller="page-header" aria-hidden="true"></div>
-<%= content_tag(tabs.any? ? :nav : :div,
-      class: "page-header sticky #{row_class}".strip,
+<%= tag.div(class: "page-header sticky #{row_class}".strip,
       style: "top: var(--pin-page-top, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)",
-      aria: { label: label.presence },
       data: data.merge(pin: "page")) do %>
+  <% if crumbs.any? %>
+    <% parent = crumbs.last %>
+    <div class="page-header-trail">
+      <nav class="page-header-crumbs" aria-label="Breadcrumb">
+        <ol>
+          <% crumbs.each do |crumb| %>
+            <li><%= link_to crumb.fetch(:label), crumb.fetch(:href), class: "page-header-crumb", data: { page_transition_back: "" } %></li>
+          <% end %>
+          <li><span class="page-header-crumb-current" aria-current="page"><%= crumb_label.presence || title %></span></li>
+        </ol>
+      </nav>
+      <%= link_to parent.fetch(:href), class: "page-header-parent", data: { page_transition_back: "" },
+            aria: { label: "Back to #{parent.fetch(:label)}" } do %><span aria-hidden="true">&lsaquo;</span> <%= parent.fetch(:label) %><% end %>
+    </div>
+  <% end %>
   <div class="page-header-lead">
     <h1 class="page-header-title"><%= title %></h1>
     <% if meta.present? %>
@@ -51,17 +80,30 @@
     <% end %>
   </div>
   <% if tabs.any? %>
-    <%= tag.div(class: "page-header-tabs", data: tabs_data) do %>
+    <%= tag.nav(class: "page-header-tabs", aria: { label: label.presence }, data: tabs_data) do %>
+      <%# The glide: one pill, drawn once, that CSS anchors to the tab with aria-current and
+          slides from tab to tab (engine.css, "The gliding pill"). Each tab keeps its own
+          fill where the browser has no anchor positioning. %>
       <div class="page-header-track">
         <% tabs.each do |tab| %>
-          <%= link_to tab.fetch(:label), tab.fetch(:href),
-                class: "btn btn-sm #{tab[:current].present? ? 'btn-primary' : 'btn-neutral'}",
+          <%= link_to tab.fetch(:href),
+                class: "page-header-tab btn btn-sm #{tab[:current].present? ? 'btn-primary' : 'btn-neutral'}",
                 aria: { current: tab[:current].presence },
-                data: tab.fetch(:data, {}) %>
+                data: tab.fetch(:data, {}) do %><span class="page-header-tab-label"><%= tab.fetch(:label) %></span><% end %>
         <% end %>
+        <span class="page-header-glide btn btn-sm btn-primary" aria-hidden="true"></span>
       </div>
     <% end %>
-  <% elsif actions_html.present? %>
+  <% end %>
+  <% if actions_html.present? %>
     <div class="page-header-actions"><%= actions_html %></div>
   <% end %>
+  <% if links.any? %>
+    <nav class="page-header-links" aria-label="<%= links_label %>">
+      <% links.each do |link| %>
+        <%= link_to link.fetch(:label), link.fetch(:href), class: "page-header-link",
+              aria: { current: link[:current].presence }, data: link.fetch(:data, {}) %>
+      <% end %>
+    </nav>
+  <% end %>
 <% end %>

data/app/views/studio/_section_header.html.erb

@@ -0,0 +1,23 @@
+<%# locals: (title:, level: :h2, row_class: "-mx-4 px-4") %>
+<%# THE SECTION HEADER: a section's title that sticks under the rest of the pinned stack
+    until the next section's header takes its place (docs/PAGE_HEADER.md).
+
+    RENDER IT AS THE FIRST DIRECT CHILD OF ITS <section>. A sticky element travels only
+    inside its parent, and that is what gives the swap: inside a wrapper div, it would
+    leave with the wrapper. No backdrop-filter, transform or overflow on an ancestor.
+
+      title      the heading's text. The heading is the sticky element, so an intro can
+                 follow as its next sibling.
+      level      the tag. A page should stick one level only: one bar at a time.
+      row_class  the bleed. The default fits a container with px-4, as the page row's does.
+
+    AT REST a normal title. STUCK it takes the bar. Its box never changes between the two.
+
+    IT JOINS THE STACK WITH data-pin-section, NOT data-pin. Every header on the page shares
+    one layer, `section`, and only the stuck one counts (studio/pinned_stack, stuckSection).
+    So it positions off --pin-section-top, which also stands when none is stuck. Anything
+    under the stack, such as a table's sticky header, sits under it with no edit. %>
+<%= content_tag(level, title,
+      class: "section-header #{row_class}".strip,
+      style: "top: var(--pin-section-top, var(--nav-bottom, var(--nav-h, 0px))); z-index: calc(var(--z-sticky, 30) - 1)",
+      data: { pin_section: "" }) %>

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

@@ -1,4 +1,4 @@
-<%# locals: (soul:, name:, portrait: nil, role: nil, empty: nil, cards: nil, voice: false, voice_copy: nil) %>
+<%# locals: (soul:, name:, portrait: nil, role: nil, empty: nil, cards: nil, voice: false, voice_copy: nil, compact: false) %>
 <%#
   The shared agent chat (docs/AGENT_CHAT.md): one conversation with one agent,
   held by the hub, on any app's page.
@@ -19,6 +19,9 @@
             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).
+  compact   true for a chat inside a card (studio/agent_chat/_talk_modal): no
+            big portrait head (the card has its own), no page padding, and a
+            shorter thread.
 
   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
@@ -32,19 +35,19 @@
 <% 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"
+<section class="<%= compact ? "w-full flex flex-col gap-3 min-w-0" : "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 %>"
          data-agent-chat-messages-url="<%= studio_agent_chat_messages_path %>"
          data-agent-chat-turns-url="<%= studio_agent_chat_turns_path %>">
-  <%= render "studio/agent_chat/header", name: name, portrait: portrait, role: role %>
+  <%= render "studio/agent_chat/header", name: name, portrait: portrait, role: role unless compact %>
   <% if cards.present? %>
     <div class="flex flex-col gap-3 min-w-0" data-agent-chat-cards data-test="agent-chat-cards"><%= cards %></div>
   <% end %>
   <div class="flex flex-col gap-3 min-w-0">
     <%# relative: a turn's sr-only name is absolutely positioned. With no positioned ancestor it escapes this scroller, is not clipped by it, and stretches the document by the thread's whole scrolled height. %>
     <div role="log" aria-live="polite" aria-label="Conversation with <%= name %>"
-         class="relative flex flex-col gap-4 px-1 py-2 overflow-y-auto overscroll-contain max-h-[60vh] min-w-0"
+         class="relative flex flex-col gap-4 px-1 py-2 overflow-y-auto overscroll-contain <%= compact ? "min-h-24 max-h-[45vh]" : "max-h-[60vh]" %> min-w-0"
          data-agent-chat-log data-test="agent-chat-messages">
       <p class="hidden only:block text-center text-secondary text-sm py-6" data-test="agent-chat-empty"><%= empty.presence || "Say hello to #{name}." %></p>
     </div>

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

@@ -0,0 +1,58 @@
+<%# locals: (soul:, name:, portrait: nil, role: nil, store: "studioTalkToAgent") %>
+<%#
+  The talk-to-agent modal (docs/AGENT_CHAT.md, "Talk to an agent in a modal"):
+  the shared agent chat (studio/agent_chat/_chat) in a card on the page-scoped
+  modal host (studio/modals/_scoped_host). Render it ONCE per page, then mark any
+  link with studio_talk_to_agent_link (Studio::AgentChatHelper), or by hand with
+  data-studio-talk-to-agent, data-talk-soul, data-talk-topic and an optional
+  data-talk-opener.
+
+  soul      the agent's slug; must be on Studio.agent_chat_souls.
+  name      the agent's display name.
+  portrait  ready markup for a small round portrait (40px works); nil shows the initial.
+  role      ready markup or text beside the name.
+  store     the Alpine store the host registers; unique on the page, never "modals".
+
+  A click opens the card and studio/talk_to_agent clones the chat out of the
+  <template> below into it, with the link's opener: the chat loads the thread
+  and sends the opener, so the agent is already answering as the card animates
+  in, and each new answer types itself in. The chat is the same one as anywhere
+  else (one thread per person and soul, held by the hub): this partial adds a
+  card and an opener, never a second chat. One page holds one chat, so the page
+  that renders this modal renders no other studio/agent_chat/chat.
+
+  A viewer Studio.agent_chat_allowed refuses gets nothing here, and every link
+  then opens its href. The x-data on the wrapper is load-bearing: the scoped host
+  declares no Alpine scope of its own.
+%>
+<% souls = Studio.agent_chat_soul_list %>
+<% raise ArgumentError, "studio/agent_chat/talk_modal: 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) %>
+<div x-data data-studio-controller="talk-to-agent" data-test="talk-to-agent"
+     data-talk-to-agent-soul="<%= soul %>" data-talk-to-agent-name="<%= name %>" data-talk-to-agent-store="<%= store %>">
+  <%= render "studio/modals/scoped_host", store: store,
+             card_class: "bg-surface rounded-2xl border border-subtle shadow-2xl w-full max-w-lg p-4 sm:p-5" do %>
+    <template x-if="$store.<%= store %>.current()?.id === 'talk-to-agent'">
+      <div class="flex flex-col gap-3 min-w-0" data-talk-to-agent-panel data-test="talk-to-agent-panel"
+           x-init="$nextTick(() => $dispatch('studio:talk-to-agent:panel'))">
+        <div class="flex items-center gap-3 min-w-0">
+          <span class="w-10 h-10 shrink-0 rounded-full overflow-hidden bg-inset border border-subtle flex items-center justify-center text-heading font-bold [&>img]:w-full [&>img]:h-full [&>img]:object-cover" aria-hidden="true">
+            <% if portrait.present? %><%= portrait %><% else %><%= name.to_s.first.to_s.upcase %><% end %>
+          </span>
+          <div class="min-w-0 flex-1">
+            <p class="font-semibold text-heading break-words" data-talk-to-agent-title data-test="talk-to-agent-title">Talk to <%= name %></p>
+            <% if role.present? %><p class="text-xs text-secondary break-words"><%= role %></p><% end %>
+          </div>
+          <button type="button" class="inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-full text-secondary hover:bg-inset hover:text-heading transition-colors" aria-label="Close"
+                  @click="$store.<%= store %>.close()" data-test="talk-to-agent-close">
+            <svg viewBox="0 0 20 20" class="h-4 w-4" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" aria-hidden="true"><path d="M5 5l10 10M15 5L5 15"/></svg>
+          </button>
+        </div>
+        <div class="min-w-0" data-talk-to-agent-slot data-test="talk-to-agent-slot"></div>
+      </div>
+    </template>
+  <% end %>
+  <template data-talk-to-agent-chat><%= render "studio/agent_chat/chat", soul: soul, name: name, portrait: portrait, compact: true,
+                                                empty: "#{name} will answer here in a moment." %></template>
+</div>
+<% end %>