studio-engine 0.129.0 → 0.131.0

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

@@ -1,5 +1,5 @@
 <%# locals: (turn:, name:) %>
-<%# One turn of the chat (studio/agent_chat/_chat), from a hub turn {id, role, text, status}, identified by its id AND role (data-turn-key "<id>:<role>"): the hub answers one message row as a user turn and an agent turn sharing the row's id. The page renders it twice, blank, as the <template>s studio/agent_chat clones; a host may also render real turns with it. The visitor's words sit in a right-hand bubble; the agent's are plain text across the thread (as the hub's agent-reply), its name kept for a screen reader. Text only, never HTML: the script sets textContent. A failed turn says so. A held one (stored, no automatic answer coming) says that, and never asks for a resend. %>
+<%# One turn of the chat (studio/agent_chat/_chat), from a hub turn {id, role, text, status}, identified by its id AND role (data-turn-key "<id>:<role>"): the hub answers one message row as a user turn and an agent turn sharing the row's id. The page renders it twice, blank, as the <template>s studio/agent_chat clones; a host may also render real turns with it. The visitor's words sit in a right-hand bubble; the agent's are plain text across the thread (as the hub's agent-reply), its name kept for a screen reader. Never HTML: the script sets a visitor's words as text and builds an agent's small Markdown subset as nodes (studio/agent_chat, MARKDOWN). This partial renders a real turn's words as text. A failed turn says so. A held one (stored, no automatic answer coming) says that, and never asks for a resend. %>
 <% agent = turn["role"].to_s == "agent" %>
 <% status = turn["status"].to_s %>
 <div class="flex flex-col gap-2 min-w-0" data-agent-chat-turn data-role="<%= agent ? "agent" : "user" %>"

data/app/views/studio/loader/_infinite_scroll.html.erb

@@ -0,0 +1,42 @@
+<%# locals: (id:, page:, next_url:, more_label:, end_label:, announce:, items:, html: {}) %>
+<%#
+  Infinite scroll (Studio::LoaderHelper#studio_infinite_scroll, docs/LOADER.md).
+  Every page renders this whole wrapper, so a page opened with no script is a
+  complete page. Page 2 and later put their items in the frame the page before
+  left for them; Turbo lifts just that frame out of the response, and the frame
+  takes no box (display: contents), so the items join the list in place.
+
+  The next page's frame holds an ordinary link. A click loads the frame; with no
+  script it opens the page. studio/infinite_scroll clicks it early, as the frame
+  nears the viewport, and says on the status line how many items came.
+%>
+<%
+  extra = html.dup
+  data = (extra.delete(:data) || {}).merge(studio_controller: "infinite-scroll",
+                                           infinite_scroll_announce: announce,
+                                           infinite_scroll_end: end_label)
+  classes = [ "studio-infinite-scroll", extra.delete(:class) ].compact.join(" ")
+  body = capture do
+    concat items
+    if next_url
+      concat(content_tag("turbo-frame", id: studio_infinite_scroll_frame_id(id, page + 1),
+                         class: "studio-infinite-scroll-next", data: { infinite_scroll_next: "" }) do
+        tag.div(class: "studio-infinite-scroll-more") do
+          link_to(next_url, class: "btn btn-secondary", data: { infinite_scroll_more: "" }) do
+            safe_join([ tag.span(more_label), studio_loader_pending(style: :spinner, size: 16) ])
+          end
+        end
+      end)
+    elsif end_label.present?
+      concat tag.p(end_label, class: "studio-infinite-scroll-end", data: { infinite_scroll_done: "" })
+    end
+  end
+%>
+<%= tag.div(id: id, class: classes, data: data, **extra) do %>
+  <% if page > 1 %>
+    <%= content_tag("turbo-frame", body, id: studio_infinite_scroll_frame_id(id, page)) %>
+  <% else %>
+    <%= body %>
+  <% end %>
+  <p class="sr-only" role="status" aria-live="polite" data-infinite-scroll-status></p>
+<% end %>

data/app/views/studio/loader/_loader.html.erb

@@ -7,6 +7,12 @@
 
   A pending loader sits inside a button: hidden from assistive tech (the button
   carries aria-busy) and from sight until the button or its form is busy.
+
+  The plain styles (spinner, dots, bar) draw no icon. They wrap the engine's
+  canonical motion primitives (.spinner, .loading-dots, .progress-meter), so the
+  family and those classes are one set of rules. A bar is a progressbar: its
+  label is its name, and a percent is its value; with none it sweeps and has no
+  value, which is how an indeterminate progressbar reads.
 %>
 <%
   extra = html.dup
@@ -28,9 +34,14 @@
       tag.img(src: icon, alt: "", class: css, draggable: "false", decoding: "async")
     end
   end
-  aria = pending ? { hidden: "true" } : { live: "polite" }
+  bar = style == :bar
+  role = pending ? nil : (bar ? "progressbar" : "status")
+  aria = if pending then { hidden: "true" }
+         elsif bar then { label: label.presence || "Loading", valuemin: 0, valuemax: 100, valuenow: (percent && (percent % 1).zero? ? percent.to_i : percent) }.compact
+         else { live: "polite" }
+         end
 %>
-<%= tag.span(class: classes, role: (pending ? nil : "status"), aria: aria, data: data, style: vars.join("; "), **extra) do %>
+<%= tag.span(class: classes, role: role, aria: aria, data: data, style: vars.join("; "), **extra) do %>
   <% case style %>
   <% when :breathe %>
     <span class="studio-loader-halo" aria-hidden="true"></span>
@@ -62,6 +73,12 @@
         <% end %>
       <% end %>
     </svg>
+  <% when :spinner %>
+    <span class="spinner" aria-hidden="true"></span>
+  <% when :dots %>
+    <span class="loading-dots" aria-hidden="true"><span></span><span></span><span></span></span>
+  <% when :bar %>
+    <span class="progress-meter<%= " progress-meter--indeterminate" if percent.nil? %>" aria-hidden="true"><span class="progress-meter-fill"></span></span>
   <% when :sparkle %>
     <%= draw_icon.call %>
     <svg class="studio-loader-art" viewBox="<%= art[:view_box] %>" aria-hidden="true">
@@ -71,5 +88,5 @@
       <% end %>
     </svg>
   <% end %>
-  <% unless pending || label.blank? %><span class="sr-only"><%= label %></span><% end %>
+  <% unless pending || bar || label.blank? %><span class="sr-only"><%= label %></span><% end %>
 <% end %>

data/app/views/studio/loader/_pull_to_refresh.html.erb

@@ -0,0 +1,20 @@
+<%# locals: (frame:, label:, body:, html: {}) %>
+<%#
+  Pull to refresh (Studio::LoaderHelper#studio_pull_to_refresh, docs/LOADER.md).
+  The indicator is hidden until a finger pulls; studio/pull_to_refresh arms only
+  on a phone-width touch screen, so elsewhere this is a plain wrapper. The
+  status line says the label while a refresh runs.
+%>
+<%
+  extra = html.dup
+  data = (extra.delete(:data) || {}).merge(studio_controller: "pull-to-refresh", pull_to_refresh_label: label)
+  data[:pull_to_refresh_frame] = frame if frame.present?
+  classes = [ "studio-pull-refresh", extra.delete(:class) ].compact.join(" ")
+%>
+<%= tag.div(class: classes, data: data, **extra) do %>
+  <span class="studio-pull-refresh-indicator" aria-hidden="true" hidden>
+    <span class="spinner studio-pull-refresh-spinner" style="--spinner-size: 1.25rem; --spinner-color: currentColor; --spinner-track: color-mix(in srgb, currentColor 22%, transparent)"></span>
+  </span>
+  <p class="sr-only" role="status" data-pull-to-refresh-status></p>
+  <%= body %>
+<% end %>

data/app/views/studio/loader/_skeleton.html.erb

@@ -0,0 +1,37 @@
+<%# locals: (kind:, count:, lines:, label:, html: {}) %>
+<%#
+  A skeleton (Studio::LoaderHelper#studio_skeleton, docs/LOADER.md): grey shapes
+  of the content to come. The wrapper is aria-busy, so assistive tech knows the
+  region is not ready; each item is aria-hidden, since a shape means nothing
+  read aloud. One line of screen-reader text names the wait. The shimmer is
+  engine-motion.css ("Loader family"), and stops under reduced motion.
+%>
+<%
+  extra = html.dup
+  data = (extra.delete(:data) || {}).merge(skeleton: kind.to_s)
+  classes = [ "studio-skeleton", extra.delete(:class) ].compact.join(" ")
+  draw_lines = lambda do |total|
+    safe_join(Array.new(total) { |i| tag.span(class: "studio-skeleton-bone", data: { bone: "line" }, style: "--studio-skeleton-width: #{studio_skeleton_width(i, total)}") })
+  end
+%>
+<%= tag.div(class: classes, aria: { busy: "true" }, data: data, **extra) do %>
+  <% if label.present? %><span class="sr-only"><%= label %></span><% end %>
+  <% count.times do %>
+    <div class="studio-skeleton-item" data-skeleton-kind="<%= kind %>" aria-hidden="true">
+      <% case kind %>
+      <% when :avatar %>
+        <span class="studio-skeleton-bone" data-bone="avatar"></span>
+        <span class="studio-skeleton-lines"><%= draw_lines.call([ lines, 1 ].max) %></span>
+      <% when :card %>
+        <span class="studio-skeleton-bone" data-bone="media"></span>
+        <span class="studio-skeleton-bone" data-bone="title"></span>
+        <%= draw_lines.call(lines) %>
+      <% when :media %>
+        <span class="studio-skeleton-bone" data-bone="media"></span>
+        <%= draw_lines.call(lines) %>
+      <% else %>
+        <%= draw_lines.call([ lines, 1 ].max) %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

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

@@ -5,11 +5,9 @@
     An app that does not draw the gallery here (lookbook not in its bundle, or
     production without Studio.lookbook_in_production) says so instead of linking
     to a 404. -%>
-<section id="components" class="space-y-6" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Components</h2>
-    <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
-  </div>
+<section id="components" class="section-target space-y-6">
+  <%= render "studio/section_header", title: "Components" %>
+  <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
 
   <% if Studio.lookbook_mounted? %>
     <ul class="grid gap-4 sm:grid-cols-2" data-component-previews>

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

@@ -90,12 +90,9 @@
      A reader who assumes dsModals will build a mirror instead: a second copy of
      every card, free to drift from the one the app actually ships, which is the
      opposite of what a living style guide is for. %>
-<section id="host-modals" class="space-y-8" x-data="{}"
-         style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading"><%= Studio.app_name %></h2>
-    <p class="text-muted text-sm max-w-2xl">This app&rsquo;s own modals, from <code class="font-mono text-2xs">app/views/style/host/_modals.html.erb</code>.</p>
-  </div>
+<section id="host-modals" class="section-target space-y-8" x-data="{}">
+  <%= render "studio/section_header", title: Studio.app_name %>
+  <p class="text-muted text-sm max-w-2xl">This app&rsquo;s own modals, from <code class="font-mono text-2xs">app/views/style/host/_modals.html.erb</code>.</p>
 
   <%# The app's content. Reached only when it resolves - style/index.html.erb
       owns that guard, because the section nav needs the same answer. %>

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

@@ -0,0 +1,118 @@
+<%#  Loaders section of the living style guide (admin/style).
+
+     The eight ways a page says "wait", one specimen each, in the order of the
+     reel Alex McRitchie shared (task engine-loader-family): spinner, skeleton,
+     progress bar, pulsing dots, button loader, full-screen loader, pull to
+     refresh, infinite scroll. Every specimen is the engine's own helper
+     (Studio::LoaderHelper, docs/LOADER.md), so what is on this page is what a
+     view gets. The branded styles themselves are under Tricks.
+
+     The infinite-scroll specimen is live: its pages come from feed_path, the
+     admin-only demo feed (StyleController#loaders_feed) unless a caller names
+     another. Pull to refresh is drawn still: it arms only on a phone with touch,
+     at the top of a page. %>
+<%
+  # A view rendered without the app's routes (a test's bare ActionView) gets the
+  # path Studio.routes draws.
+  feed_path = local_assigns[:feed_path] ||
+              (respond_to?(:admin_style_loaders_feed_path) ? admin_style_loaders_feed_path : "/admin/style/loaders_feed")
+  erb = ->(code) { "<" + "%= " + code + " %" + ">" }
+  erb_end = "<" + "% end %" + ">"
+%>
+<section id="loaders" class="section-target space-y-6" data-style-loaders>
+  <%= render "studio/section_header", title: "Loaders" %>
+  <p class="text-muted text-sm max-w-2xl">Eight ways to say wait. Match the loader to the wait.</p>
+
+  <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_loader style: :spinner",
+                    note: "A small ring for a short wait beside text or in a control.",
+                    usage: erb.call("studio_loader style: :spinner") } do %>
+      <div data-loader-specimen="spinner" class="flex items-center gap-4">
+        <%= studio_loader style: :spinner %>
+        <%= studio_loader style: :spinner, size: 32 %>
+        <span class="inline-flex items-center gap-2 text-sm text-body"><%= studio_loader style: :spinner, size: 16, label: "Checking" %>Checking</span>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_skeleton :avatar / :card / :lines / :media",
+                    note: "Grey shapes of the content to come, so the page keeps its layout.",
+                    usage: [erb.call("studio_skeleton :avatar, count: 3"), erb.call('studio_skeleton :card, count: 3, class: "sm:grid-cols-3"')].join("\n") } do %>
+      <div data-loader-specimen="skeleton" class="grid w-full gap-4">
+        <%= studio_skeleton :avatar, count: 2, label: "Loading people" %>
+        <%= studio_skeleton :lines, lines: 2, label: "Loading notes" %>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_loader style: :bar, percent:",
+                    note: "A bar for a wait you can measure; with no percent it sweeps.",
+                    usage: [erb.call("studio_loader style: :bar, percent: 62"), erb.call("studio_loader style: :bar"), 'StudioLoader.setPercent(el, 80)'].join("\n") } do %>
+      <div data-loader-specimen="bar" class="grid w-full gap-4">
+        <%= studio_loader style: :bar, percent: 62, label: "Uploading" %>
+        <%= studio_loader style: :bar, label: "Importing" %>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_loader style: :dots",
+                    note: "Three dots for a reply on its way, such as a chat answer.",
+                    usage: erb.call("studio_loader style: :dots") } do %>
+      <div data-loader-specimen="dots" class="flex items-center gap-6">
+        <%= studio_loader style: :dots %>
+        <span class="inline-flex items-center gap-2 rounded-2xl bg-inset px-3 py-2 text-sm text-body"><%= studio_loader style: :dots, size: 24, label: "Alex is typing" %></span>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_loader_pending (inside a button)",
+                    note: "The button keeps its place and shows that it is working.",
+                    usage: ["<button class=\"btn btn-primary\">", "  <span data-loader-idle>Save</span>", "  #{erb.call('studio_loader_pending style: :spinner')}", "  <span data-loader-busy>Saving…</span>", "</button>"].join("\n") } do %>
+      <div data-loader-specimen="button" class="flex flex-wrap items-center gap-3" x-data="{ busy: false }">
+        <button type="button" class="btn btn-primary" x-bind:aria-busy="busy ? 'true' : 'false'" aria-busy="false"
+                x-on:click="busy = true; setTimeout(() => busy = false, 2000)" data-test="style-loader-save">
+          <span data-loader-idle>Save</span>
+          <%= studio_loader_pending style: :spinner %><span data-loader-busy>Saving…</span>
+        </button>
+        <button type="button" class="btn btn-secondary" aria-busy="true" tabindex="-1">
+          <%= studio_loader_pending %><span class="ml-2">Saving…</span>
+        </button>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_loader_overlay (full screen)",
+                    note: "The branded overlay, for a page that takes longer than 350ms.",
+                    usage: ['window.StudioLoader.show("Caption")', "window.StudioLoader.hide()"].join("\n") } do %>
+      <div data-loader-specimen="overlay">
+        <button type="button" class="btn btn-secondary" data-test="style-loaders-overlay"
+                x-data x-on:click="window.StudioLoader && window.StudioLoader.show('Loading your page…'); setTimeout(() => window.StudioLoader && window.StudioLoader.hide(), 2000)">
+          Show it for 2 seconds
+        </button>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_pull_to_refresh (phones only)",
+                    note: "On a phone, pull down from the top of the page to reload it.",
+                    usage: [erb.call('studio_pull_to_refresh frame: "feed" do'), "  ...", erb_end].join("\n") } do %>
+      <%# Drawn still, mid-refresh: this wrapper has no controller, so it never arms. %>
+      <div data-loader-specimen="pull" class="studio-pull-refresh w-40 h-40 overflow-hidden rounded-2xl border border-subtle bg-surface pt-20 px-3" data-pull-state="refreshing">
+        <span class="studio-pull-refresh-indicator" aria-hidden="true">
+          <span class="spinner studio-pull-refresh-spinner" style="--spinner-size: 1.25rem; --spinner-color: currentColor; --spinner-track: color-mix(in srgb, currentColor 22%, transparent)"></span>
+        </span>
+        <%= studio_skeleton :lines, lines: 3, label: "" %>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_infinite_scroll id:, page:, next_url:",
+                    note: "The next page loads as the list's end comes near, and Load more stays.",
+                    usage: [erb.call('studio_infinite_scroll id: "posts", page: @page, next_url: @next_url do'), "  ...one page of items...", erb_end].join("\n") } do %>
+      <div data-loader-specimen="infinite" class="w-full">
+        <%= render "style/loaders_feed_page", page: 1, feed_path: feed_path %>
+      </div>
+    <% end %>
+  </div>
+</section>

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

@@ -0,0 +1,16 @@
+<%# locals: (page:, feed_path:) %>
+<%# One page of the Loaders section's live infinite-scroll specimen: four demo
+    items a page, three pages. The section renders page 1; the demo feed renders
+    the rest (StyleController#loaders_feed), and Turbo lifts each one into the
+    frame the page before left for it. %>
+<%
+  pages = Studio::Loader::DEMO_FEED_PAGES
+  per_page = Studio::Loader::DEMO_FEED_PER_PAGE
+  next_url = page < pages ? "#{feed_path}?page=#{page + 1}" : nil
+%>
+<%= studio_infinite_scroll id: "style-loaders-feed", page: page, next_url: next_url,
+      announce: "%{count} more items loaded", class: "grid grid-cols-2 gap-2" do %>
+  <% ((page - 1) * per_page + 1).upto(page * per_page) do |n| %>
+    <div class="rounded-lg bg-inset px-3 py-2 text-sm text-body" data-feed-item>Item <%= n %></div>
+  <% end %>
+<% end %>

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

@@ -9,11 +9,11 @@
          page when chatting (item 1).
        - an optional row of option toggles lets the user configure the modal
          before opening; their clicks/keys do NOT bubble to the card open (item 2).
-       - an optional active-card GLOW (.studio-team-glow) that reactively lights
+       - an optional active-card GLOW (.edge-rotate-glow) that reactively lights
          when this card represents the currently-open modal + step, and slides to
          the next card as the step machine advances (items 5/6). The glow rides an
          un-clipped wrapper (the card itself is overflow-hidden), mirroring TM's
-         holo-wrap / holo-card split, and fades via --studio-team-glow-opacity so
+         holo-wrap / holo-card split, and fades via --edge-rotate-glow-opacity so
          it transitions smoothly between cards.
 
      Locals:
@@ -53,10 +53,10 @@
 <%# Wrapper — carries the active-card glow (un-clipped) + the shared x-data. %>
 <%# h-full so the card stretches to its grid row's tallest (per-row equal
     height via the grid's default align-items: stretch). %>
-<div class="relative h-full<%= " studio-team-glow rounded-xl" if glow_when %>"
+<div class="relative h-full<%= " edge-rotate-glow rounded-xl" if glow_when %>"
      x-data="<%= card_x_data %>"
      <%# Fail-closed default: a STATIC inline 0 out-specifies the primitive's CSS
-         default (--studio-team-glow-opacity of 1) so the ring is OFF at first
+         default (--edge-rotate-glow-opacity of 1) so the ring is OFF at first
          paint, BEFORE Alpine hydrates the reactive :style below. Without it every
          glow card shows its ring until Alpine boots (the fail-open flash). The
          :style then drives 0 to 0.95 with the 0.4s cross-fade. Keep BOTH.
@@ -67,7 +67,7 @@
          the Turbo-nav store gap fixed in 0.26.1 (style/_modals dual-guards the
          dsModals registration so it survives Turbo visits, not just first load).
          So the guarantee is: static inline 0 PLUS a registered dsModals. %>
-     <% if glow_when %>style="--studio-team-glow-opacity: 0" :style="{ '--studio-team-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
+     <% if glow_when %>style="--edge-rotate-glow-opacity: 0" :style="{ '--edge-rotate-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
   <article
       class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %><%= " cursor-pointer" if clickable %>"
       <%= 'aria-disabled="true"'.html_safe if disabled %>

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

@@ -150,14 +150,12 @@
     target moved. The engine primitive is untouched; its real submit still posts
     to the app-supplied submit_url. Kept on the section (always mounted) so it
     fires even as the age-gate card closes. %>
-<section id="modals" class="space-y-10" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)"
+<section id="modals" class="section-target space-y-10"
          data-studio-controller="style-modals"
          x-data="{}" @ds-modal-close.window="$store.dsModals.close()"
          @age-verified.window="$store.dsModals.open('entry-confirmed', { txSignature: null, lobbyUrl: null, seedsEarned: 0 })">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Modals</h2>
-    <p class="text-muted text-sm">Click a card to open the real modal.</p>
-  </div>
+  <%= render "studio/section_header", title: "Modals" %>
+  <p class="text-muted text-sm">Click a card to open the real modal.</p>
 
   <%# ---- The section's own modal host (dsModals) --------------------------
       $store.dsModals is the engine's modal stack under the guide's own name:
@@ -1169,6 +1167,18 @@
     </div>
   </section>
 
+  <%# ===================================================================== %>
+  <%# 6b. TALK TO AN AGENT (studio/agent_chat/_talk_modal). No live specimen:
+      the card holds the app's real agent chat, which needs a soul on
+      Studio.agent_chat_souls and the hub behind it (docs/AGENT_CHAT.md). %>
+  <%# ===================================================================== %>
+  <section id="modals-agent-chat" class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="type-h4 text-heading">Talk to an agent</h3>
+      <p class="text-muted text-sm" data-test="style-talk-to-agent">Render <code class="font-mono text-2xs">studio/agent_chat/talk_modal</code> once and mark any link with <code class="font-mono text-2xs">studio_talk_to_agent_link</code>: a click opens the agent's chat in a card, and the agent starts answering the link's opener as the card opens.</p>
+    </div>
+  </section>
+
   <%# ===================================================================== %>
   <%# 7. REWARDS / leveling (gated by Studio.feature?(:leveling)) %>
   <%# ===================================================================== %>

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

@@ -33,7 +33,7 @@
   sample_page  = [ [ "Google's header", 0, 200, false ], [ "Select an appointment time", 200, 600, true ],
                    [ "Google's credit lines", 600, 720, false ] ]
 %>
-<section id="site-footer" class="space-y-5" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+<section id="site-footer" class="section-subtarget space-y-5">
   <div class="space-y-1">
     <h3 class="type-h4 text-heading">Site footer and booking</h3>
     <p class="text-muted text-sm max-w-2xl">One layout line renders the footer, and <code class="font-mono text-2xs">config.booking_url</code> turns on booking.</p>

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

@@ -1,11 +1,13 @@
 <%#  Specimen card for the living style guide (admin/style).
      Reusable chrome around ONE primitive, framed for copy-paste-for-an-agent:
        stage - the rendered primitive (yielded from the caller block)
-       meta  - its class name (prominent + one-click copy) and a copyable usage snippet
+       meta  - its class name and a copyable usage snippet; one Copy per card (the
+               snippet's, else the class name's)
      locals:
        klass          (String, required) - the class label, shown prominently with a
                        copy button so an agent can grab the exact class list.
        usage          (String, optional) - a copyable usage snippet.
+       note           (String, optional) - one short sentence on what it does.
        disabled       (Boolean, optional) - render "disabled but present": the
                        primitive stays visible + previewable but is muted/greyed
                        and flagged, for a capability the host app has turned off
@@ -38,20 +40,29 @@
     <% end %>
   </div>
   <div class="border-t border-subtle p-3 space-y-2">
-    <%# Class name — prominent, with a one-click copy so an agent can grab it. %>
+    <% if local_assigns[:note].present? %>
+      <p class="text-sm text-body"><%= local_assigns[:note] %></p>
+    <% end %>
+    <%# ONE Copy per card. With a usage snippet, the snippet's Copy is the one: it holds
+        the class too. Without one, the class name carries the Copy. %>
+    <% snippet = local_assigns[:usage] %>
     <div class="flex items-start justify-between gap-2" x-data="{ copied: false }">
       <code x-ref="klass" class="font-mono text-xs font-bold text-heading break-all leading-relaxed flex-1 min-w-0"><%= local_assigns[:klass] %></code>
-      <button type="button"
-              class="btn btn-neutral btn-sm shrink-0"
-              aria-label="Copy class name"
-              @click="navigator.clipboard?.writeText($refs.klass.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-        <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-      </button>
+      <% unless snippet.present? %>
+        <button type="button"
+                class="btn btn-neutral btn-sm shrink-0"
+                aria-label="Copy class name"
+                @click="navigator.clipboard?.writeText($refs.klass.innerText); copied = true; setTimeout(() => copied = false, 1200)">
+          <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
+        </button>
+      <% end %>
     </div>
-    <% snippet = local_assigns[:usage] %>
     <% if snippet.present? %>
+      <%# The code wraps inside its box, and pr-24 keeps every line clear of the Copy
+          button, "Copied" included: 74px with its inset on macOS, 3px wider in CI's
+          Linux fonts, so pr-20 was not enough. %>
       <div class="relative" x-data="{ copied: false }">
-        <pre class="bg-inset text-body text-2xs rounded-lg px-3 py-2 pr-16 overflow-x-auto"><code x-ref="snippet"><%= snippet %></code></pre>
+        <pre class="bg-inset text-body text-2xs rounded-lg px-3 py-2 pr-24 whitespace-pre-wrap break-words"><code x-ref="snippet"><%= snippet %></code></pre>
         <button type="button"
                 class="btn btn-neutral btn-sm absolute top-2 right-2"
                 aria-label="Copy usage snippet"

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

@@ -63,11 +63,9 @@
     "stage-shipped"    => [{ title: "SES email backend",    repo: "mcritchie",     who: "ST" }]
   }
 %>
-<section id="tasks" class="space-y-8" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Tasks</h2>
-    <p class="text-muted text-sm max-w-2xl">The real board primitive in demo mode, so a drag saves nothing.</p>
-  </div>
+<section id="tasks" class="section-target space-y-8">
+  <%= render "studio/section_header", title: "Tasks" %>
+  <p class="text-muted text-sm max-w-2xl">The real board primitive in demo mode, so a drag saves nothing.</p>
 
   <%# ---- The LIVE primitive (demo mode) --------------------------------- %>
   <%# demo: true → drag animates + toasts locally, nothing POSTs. %>

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

@@ -53,11 +53,11 @@
 
   csrf_ok = respond_to?(:protect_against_forgery?) && protect_against_forgery?
 %>
-<section id="theme" class="space-y-8" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)"
+<section id="theme" class="section-target space-y-8"
          x-data="dsThemeEditor(<%= seed_colors.to_json %>)">
+  <%= render "studio/section_header", title: "Theme" %>
   <div class="flex flex-wrap items-start justify-between gap-3">
     <div class="space-y-1">
-      <h2 class="type-h3 text-heading">Theme</h2>
       <p class="text-muted text-sm max-w-2xl">Every specimen on this page restyles from these 7 color roles.</p>
     </div>
     <form action="/admin/theme/regenerate" method="post" accept-charset="UTF-8" @submit.prevent="regenerate($event)">