studio-engine 0.132.0 → 0.133.0

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

@@ -5,7 +5,9 @@
      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.
+     view gets, under its trick name (config/studio_tricks.yml): Spinner, Skeleton,
+     Progress Bar, Typing Dots, Busy Button, Overlay, Pull Refresh, Infinite Scroll.
+     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
@@ -16,18 +18,13 @@
   # 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 %>
+    <%= render layout: "style/specimen", locals: { trick: "spinner" } do %>
       <div data-loader-specimen="spinner" class="flex items-center gap-4">
         <%= studio_loader style: :spinner %>
         <%= studio_loader style: :spinner, size: 32 %>
@@ -35,40 +32,28 @@
       </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 %>
+    <%= render layout: "style/specimen", locals: { trick: "skeleton" } 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 %>
+    <%= render layout: "style/specimen", locals: { trick: "progress_bar" } 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 %>
+    <%= render layout: "style/specimen", locals: { trick: "typing_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 %>
+    <%= render layout: "style/specimen", locals: { trick: "busy_button" } 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">
@@ -81,10 +66,7 @@
       </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 %>
+    <%= render layout: "style/specimen", locals: { trick: "overlay" } 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)">
@@ -93,10 +75,7 @@
       </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 %>
+    <%= render layout: "style/specimen", locals: { trick: "pull_refresh" } 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">
@@ -106,10 +85,7 @@
       </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 %>
+    <%= render layout: "style/specimen", locals: { trick: "infinite_scroll" } do %>
       <div data-loader-specimen="infinite" class="w-full">
         <%= render "style/loaders_feed_page", page: 1, feed_path: feed_path %>
       </div>

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

@@ -14,8 +14,8 @@
      card behind ours. So this section owns a tiny, self-contained store + overlay
      and registers all specimen content itself.
 
-     Groups: Auth (the engine-owned FRAGMENTS an app's own sign-in card is built
-     from — the engine ships no auth card), Eligibility and entry (the
+     Groups: Auth (the engine's standard sign-in card, studio/auth/_sign_in_modal,
+     in demo mode), Eligibility and entry (the
      app-supplied-policy age-gate DOB primitive, gated by Studio.feature?(:age_gate)),
      Profile (crop / upload, opened
      through studio/cropper_assets), Web3 (wallet-connect and web3-step-up now
@@ -97,7 +97,8 @@
   # THE AUTH METHOD-TOGGLE DEFAULTS USED TO LIVE HERE (ml_default / g_default /
   # w_default / auth_toggles) and are gone with the card they configured. They
   # belonged to style/modals/_auth, a MIRROR of turf-monster's sign-in modal,
-  # retired on 2026-09-09. The engine ships no auth card to configure.
+  # retired on 2026-09-09. The engine's own card (studio/auth/_sign_in_modal,
+  # 2026-11-06) has no toggles: its specimen runs it in demo mode as shipped.
   #
   # The rule they were built to enforce OUTLIVES them and is worth keeping: a
   # TRIGGER must carry at least the gate its target's REGISTRATION carries, or
@@ -202,17 +203,15 @@
       <div class="bg-surface rounded-xl border border-subtle shadow-2xl p-6 w-full"
            :class="$store.dsModals.cardClasses()">
 
-        <%# --- Auth fragments --- %>
-        <%# NOT an auth card. The engine owns no sign-in modal — each app cards
-            its own on its own host section (turf-monster: style/host/_modals).
-            These two register the PIECES every app's auth card is built from,
-            which had no specimen until style/modals/_auth, a mirror of turf's
-            card, was retired on 2026-09-09 and took their only render with it. %>
-        <template x-if="$store.dsModals.current().id === 'ds-email-field'">
-          <div><%= render "style/modals/ds_email_field" %></div>
-        </template>
-        <template x-if="$store.dsModals.current().id === 'ds-resend-footer'">
-          <div><%= render "style/modals/ds_resend_footer" %></div>
+        <%# --- Auth --- %>
+        <%# The engine's standard sign-in card (studio/auth/_sign_in_modal), the
+            REAL partial in demo mode: Google and Send post nothing, and the
+            link-sent step and resend cooldown play. It folds in the two pieces
+            that used to be carded alone here, studio/modals/shared/_email_field
+            and studio/modals/auth/_resend_footer (Alex McRitchie, 2026-11-06:
+            "this should use the standard auth component with Google and Email"). %>
+        <template x-if="$store.dsModals.current().id === 'ds-sign-in'">
+          <div><%= render "studio/auth/sign_in_modal", modal_store: "dsModals", demo: true %></div>
         </template>
 
         <%# --- Onboarding step (its card now lives in Profile) --- %>
@@ -452,36 +451,27 @@
   <section id="modals-auth" class="space-y-5">
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">Auth</h3>
-      <p class="text-muted text-sm">The engine ships no sign-in card, only these pieces.</p>
+      <p class="text-muted text-sm">The engine's standard sign-in card: Google, or, email magic link.</p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-      <%# email field — the one piece every app's auth card renders. %>
       <%= render layout: "style/modal_specimen", locals: {
-            label:     "Email field",
-            reference: %(the modal family's email input (studio/modals/shared/_email_field) — a themed <input type="email"> that either posts through its own `name` or feeds an enclosing x-model, with locals name/id/value/placeholder/required/autocomplete/autofocus/input_class/x_model/x_ref/disabled_expr/validator. THE `validator` LOCAL IS A FORK, NOT A FLAG: off, the partial is self-contained and the SERVER stays the only boundary; on, it wraps itself in x-data="emailValidator()" and paints a right-edge spinner/check/X that only works if the CONSUMER ships that factory, so passing it without one yields an Alpine scope error and a dead indicator. The specimen draws both faces side by side; this guide ships no emailValidator, which is why the second indicator stays blank. Open with $store.dsModals.open('ds-email-field')),
-            open_expr: "$store.dsModals.open('ds-email-field')",
-            glow_when: ds_glow.call("ds-email-field") } do %>
+            label:     "Sign in",
+            reference: %(the engine's standard sign-in card as a modal (studio/auth/_sign_in_modal; the page form is studio/auth/_sign_in_card) — Google, then "or", then the email magic link, and on send the link-sent step with the shared resend footer (studio/modals/auth/_resend_footer) under the shared email field (studio/modals/shared/_email_field). Locals: heading, subheading (default "Sign in to" the app name), return_to (kept to an in-app path, rides both Google and the magic link), preamble and extras (partials above Google and after it, for age attestation or a Solana wallet button), google, magic_link, modal_store, demo. Real use posts Google to /auth/google_oauth2 (button_to POST, Turbo off) and the email to POST /magic_link. THIS SPECIMEN IS demo: true, SO NOTHING POSTS: Google is an inert button, Send waits on a timer, and the resend cooldown is 5s instead of 60s. Open with $store.dsModals.open('ds-sign-in')),
+            open_expr: "$store.dsModals.open('ds-sign-in')",
+            glow_when: ds_glow.call("ds-sign-in") } do %>
         <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 space-y-2">
-          <span class="block h-1.5 w-12 rounded" style="background: var(--color-text); opacity: .18"></span>
-          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
-          <span class="flex items-center h-6 w-full rounded border px-1.5" style="border-color: var(--color-border-strong)">
-            <span class="block h-1.5 flex-1 rounded" style="background: var(--color-text); opacity: .12"></span>
-            <span class="block w-3 h-3 rounded-full ml-1" style="background: var(--color-success); opacity: .55"></span>
+          <span class="block h-2 w-20 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="flex items-center justify-center gap-1 h-6 w-full rounded border" style="border-color: var(--color-border-strong)">
+            <span class="block w-2.5 h-2.5 rounded-full" style="background: conic-gradient(#EA4335 0 25%, #FBBC05 0 50%, #34A853 0 75%, #4285F4 0)"></span>
+            <span class="block h-1.5 w-12 rounded" style="background: var(--color-text); opacity: .2"></span>
           </span>
-        </div>
-      <% end %>
-
-      <%# resend footer — the piece both link-sent steps share. %>
-      <%= render layout: "style/modal_specimen", locals: {
-            label:     "Resend footer",
-            reference: %(the magic-link resend footer (studio/modals/auth/_resend_footer) — the resend link, its error line and the Close beneath it, shared by an auth card's magic-link-sent and magic-link-resent steps because the two are identical, which is why it was extracted. IT RESOLVES FROM AN ENCLOSING x-data, NOT A STORE: it reads props.submitting, props.resendCooldown and props.resendError and calls resendMagicLink(), so a scope supplying none of them fails SILENTLY — nothing errors, the link simply never enables and the cooldown never counts. The specimen supplies a stand-in host so all three states are reachable, and shortens the cooldown from production's 60s to 5s because the partial does not own the duration, the host does. Open with $store.dsModals.open('ds-resend-footer')),
-            open_expr: "$store.dsModals.open('ds-resend-footer')",
-            glow_when: ds_glow.call("ds-resend-footer") } do %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
-          <div class="text-2xl leading-none">📬</div>
-          <span class="block h-1.5 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .12"></span>
-          <span class="block h-1.5 w-16 mx-auto rounded" style="background: var(--color-primary); opacity: .7"></span>
-          <span class="block h-1.5 w-10 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="flex items-center gap-1.5">
+            <span class="block h-px flex-1" style="background: var(--color-border-strong)"></span>
+            <span class="block h-1 w-2 rounded" style="background: var(--color-text); opacity: .25"></span>
+            <span class="block h-px flex-1" style="background: var(--color-border-strong)"></span>
+          </span>
+          <span class="block h-6 w-full rounded border" style="border-color: var(--color-border-strong)"></span>
+          <span class="block h-5 w-full rounded" style="background: var(--color-primary)"></span>
         </div>
       <% end %>
     </div>

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

@@ -17,22 +17,15 @@
 <%
   media_style = "background-image: repeating-linear-gradient(135deg, var(--color-primary) 0 18px, var(--color-accent) 18px 36px, var(--color-warning) 36px 54px, var(--color-success) 54px 72px)"
 
+  # Each specimen names its trick (config/studio_tricks.yml): Scrim, Tint, Shade, and
+  # the Scrim's soft and strong variants, which each keep a stage of their own so the
+  # lab can grade every wash on its own panel.
   specimens = [
-    { key: "theme",  tone: nil,           scrim: "scrim",
-      klass: ".scrim",
-      note:  "Theme-aware: a tint in light mode, a shade in dark." },
-    { key: "tint",   tone: "scrim-tint",  scrim: "scrim",
-      klass: ".scrim-tint .scrim",
-      note:  "Forced tint, in either theme. Dark ink." },
-    { key: "shade",  tone: "scrim-shade", scrim: "scrim",
-      klass: ".scrim-shade .scrim",
-      note:  "Forced shade, in either theme. Light ink." },
-    { key: "soft",   tone: nil,           scrim: "scrim scrim-soft",
-      klass: ".scrim .scrim-soft",
-      note:  "A lighter wash: more of the media shows." },
-    { key: "strong", tone: nil,           scrim: "scrim scrim-strong",
-      klass: ".scrim .scrim-strong",
-      note:  "A heavier wash, for long or small text." }
+    { key: "theme",  tone: nil,           scrim: "scrim",              trick: "scrim" },
+    { key: "tint",   tone: "scrim-tint",  scrim: "scrim",              trick: "tint" },
+    { key: "shade",  tone: "scrim-shade", scrim: "scrim",              trick: "shade" },
+    { key: "soft",   tone: nil,           scrim: "scrim scrim-soft",   trick: "scrim", variant: "soft" },
+    { key: "strong", tone: nil,           scrim: "scrim scrim-strong", trick: "scrim", variant: "strong" }
   ]
 %>
 <section id="scrims" class="space-y-5" data-scrim-group>
@@ -42,16 +35,13 @@
   </div>
   <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
     <% specimens.each do |s| %>
-      <% tone_attr = s[:tone] ? %( class="#{s[:tone]} relative ...") : %( class="relative ...") %>
-      <%= render layout: "style/specimen",
-            locals: { klass: s[:klass],
-                      usage: %(<section#{tone_attr}>\n  <img class="absolute inset-0 ..." src="...">\n  <div class="#{s[:scrim]} absolute inset-0"></div>\n  <div class="relative z-10">\n    <h2 class="scrim-ink">Headline</h2>\n    <p class="scrim-ink-muted">Subtitle</p>\n  </div>\n</section>) } do %>
+      <%= render layout: "style/specimen", locals: { trick: s[:trick], variant: s[:variant] } do %>
         <div class="relative w-full max-w-xs h-36 rounded-lg overflow-hidden <%= s[:tone] %>" data-scrim-specimen="<%= s[:key] %>">
           <div class="absolute inset-0" style="<%= media_style %>" aria-hidden="true"></div>
           <div class="<%= s[:scrim] %> absolute inset-0" data-scrim-wash></div>
           <div class="relative z-10 h-full flex flex-col items-center justify-center gap-1 px-4 text-center">
             <p class="scrim-ink text-lg font-extrabold" data-scrim-ink>Solutions For Business</p>
-            <p class="scrim-ink-muted text-sm" data-scrim-ink-muted><%= s[:note] %></p>
+            <p class="scrim-ink-muted text-sm" data-scrim-ink-muted><%= Studio::Tricks.fetch(s[:trick], s[:variant]).note %></p>
           </div>
         </div>
       <% end %>

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

@@ -2,13 +2,13 @@
      The primitives a public site ends with: the footer, its map, and the Google
      Calendar booking frame, popup and link (docs/SITE_FOOTER.md,
      docs/BOOKING.md). Each card
-     gives the helper to call; the preview below them is the real footer partial,
+     names its trick and the helper to call; the preview below them is the real footer partial,
      rendered with THIS app's facts when it has declared any and with a sample
      when it has not, so the group is never empty.
 
      The booking frame is DRAWN, not embedded: a style guide should not ask
      Google for a calendar every time an admin scrolls past. Its two states, whole
-     and cropped, are quarter-scale drawings of a made-up schedule (a 720px page
+     and cropped, share the Booking Frame card: quarter-scale drawings of a made-up schedule (a 720px page
      whose box runs from 200 to 600), cropped by the same arithmetic the real
      wrapper uses (Studio::Booking.crop). No real schedule's numbers are here. %>
 <%
@@ -47,16 +47,12 @@
   </div>
 
   <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-    <%= render layout: "style/specimen",
-          locals: { klass: "studio_site_footer",
-                    usage: %(studio_site_footer   # one line, at the end of the layout body) } do %>
+    <%= render layout: "style/specimen", locals: { trick: "site_footer" } do %>
       <p class="text-sm text-secondary text-center">Previewed below.</p>
     <% end %>
 
     <%= render layout: "style/specimen",
-          locals: { klass: "studio_booking_link",
-                    disabled: !booking, disabled_label: "no booking_url",
-                    usage: %(studio_booking_link "Schedule a call", class: "btn btn-primary") } do %>
+          locals: { trick: "booking_link", disabled: !booking, disabled_label: "no booking_url" } do %>
       <% if booking %>
         <%= studio_booking_link "Schedule a call", class: "btn btn-primary" %>
       <% else %>
@@ -64,16 +60,12 @@
       <% end %>
     <% end %>
 
-    <% [ [ "studio_booking_frame", nil, "whole",
-           %(studio_booking_frame   # whole at rest: the default, and crop: false),
-           "Whole at rest, the default." ],
-         [ "config.booking_crop", sample_crop, "cropped",
-           %(config.booking_crop = { top: 200, bottom: 600, frame_height: 720 }   # bin/booking-crop-measure prints yours),
-           "Cropped to the slot picker at rest." ]
-       ].each do |klass, crop, state, usage, caption| %>
-      <%= render layout: "style/specimen",
-            locals: { klass: klass, disabled: !booking, disabled_label: "no booking_url", usage: usage } do %>
-        <div class="w-full space-y-3" data-booking-specimen="<%= state %>">
+    <%= render layout: "style/specimen",
+          locals: { trick: "booking_frame", disabled: !booking, disabled_label: "no booking_url" } do %>
+      <% [ [ nil, "whole", "Whole at rest, the default." ],
+           [ sample_crop, "cropped", "Cropped to the slot picker at rest." ]
+         ].each do |crop, state, caption| %>
+        <div class="space-y-3" data-booking-specimen="<%= state %>">
           <div style="margin-inline: auto; width: 11rem; overflow: hidden; background: #fff; border-radius: .5rem; border: 1px solid rgb(127 127 127 / .35); height: <%= ((crop ? crop[:window] : 720) * scale).round %>px;">
             <div style="margin-top: -<%= ((crop ? crop[:offset] : 0) * scale).round %>px;">
               <% sample_page.each do |label, from, to, box| %>

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

@@ -1,13 +1,15 @@
 <%#  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 and a copyable usage snippet; one Copy per card (the
-               snippet's, else the class name's)
+     Reusable chrome around ONE primitive, named so Alex McRitchie can say it to an
+     agent ("add a Sheen"):
+       stage - the rendered primitive (yielded from the caller block), with its
+               variants side by side when the card folds them in
+       label - the trick's name, a one-line note and its class or helper, read from
+               config/studio_tricks.yml by key (style/_trick_label), with one Copy
+               that copies the agent line, never a markup snippet
      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.
+       trick          (String, required) - the registry key (config/studio_tricks.yml).
+       variant        (String, optional) - a variant with a card of its own
+                       ("Loader · orbit"); the card is then named for the variant.
        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
@@ -30,7 +32,7 @@
   # utilities and lift the opacity a touch so the trigger reads as tappable.
   inner_cls = openable ? "opacity-60 grayscale" : "opacity-40 grayscale select-none pointer-events-none"
 %>
-<article class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %>" <%= 'aria-disabled="true"'.html_safe if disabled %>>
+<article class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %>" <%= tag.attributes(data: { trick: local_assigns.fetch(:trick), trick_variant: local_assigns[:variant] }, aria: { disabled: ("true" if disabled) }) %>>
   <div class="relative flex flex-1 flex-wrap items-center justify-center gap-4 p-6 bg-surface-alt min-h-32">
     <% if disabled %>
       <span class="absolute top-2 right-2 badge z-10" style="color: var(--color-warning); border-color: var(--color-warning)"><%= disabled_label %></span>
@@ -39,37 +41,7 @@
       <%= yield %>
     <% end %>
   </div>
-  <div class="border-t border-subtle p-3 space-y-2">
-    <% 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>
-      <% 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>
-    <% 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-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"
-                @click="navigator.clipboard?.writeText($refs.snippet.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-          <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-        </button>
-      </div>
-    <% end %>
+  <div class="border-t border-subtle p-3">
+    <%= render "style/trick_label", trick: local_assigns.fetch(:trick), variant: local_assigns[:variant] %>
   </div>
 </article>

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

@@ -28,20 +28,6 @@
       cards: [{ id: "ses-email-backend", zone: "shipped", title: "SES email backend", repo: "mcritchie", who: "ST" }] }
   ]
 
-  # Copy-paste-for-an-agent usage. Built by array-join, NOT a heredoc: a heredoc as
-  # the last expression of an ERB scriptlet trips Erubi, and literal ERB tags in the
-  # body would close the tag. Plain render() calls read clearly for an agent.
-  board_usage_snippet = [
-    "# the board; it needs nothing else on the page:",
-    'render "studio/board/board",',
-    "  columns: @columns,            # [{ key:, label:, cards:, badge_class: }]",
-    '  card_partial: "tasks/task_card",',
-    "  reorder_url: tasks_reorder_path,        # POST { slugs: [...], zone: }",
-    '  move_url: "/tasks/:id.json",            # PATCH { task: { stage: } }',
-    '  move_param: { resource: "task", attr: "stage" },',
-    '  live_channel: "deployments"'
-  ].join("\n")
-
   # The static reference palette below (unchanged): each column maps to a stage-*
   # badge scheme.
   board_columns = [
@@ -84,14 +70,10 @@
           move_param: { resource: "task", attr: "stage" },
           group: "studio-board-demo",
           empty_label: "Drop tasks here" %>
-    <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="boardUsage"><%= board_usage_snippet %></code></pre>
-      <button type="button"
-              class="btn btn-neutral btn-sm absolute top-2 right-2"
-              aria-label="Copy usage snippet"
-              @click="navigator.clipboard?.writeText($refs.boardUsage.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-        <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-      </button>
+    <%# Its name, not a snippet (config/studio_tricks.yml): an agent reads the locals
+        from studio/board/_board's header. %>
+    <div class="card p-3" data-trick="board">
+      <%= render "style/trick_label", trick: "board" %>
     </div>
   </div>
 

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

@@ -0,0 +1,33 @@
+<%#  A trick's name, note and token, with one Copy (config/studio_tricks.yml).
+     The name is the heading because it is what a person says to an agent ("add a
+     Sheen"); the token is what the agent writes, so it sits under it, small and
+     muted. Copy puts the agent line on the clipboard: the name and the token,
+     variants included (Studio::Tricks.agent_line). No markup snippet: an agent can
+     read the markup from the engine, and only the name has to travel by word.
+     locals:
+       trick   (String, required) - the registry key.
+       variant (String, optional) - one variant's own label. %>
+<% t = Studio::Tricks.fetch(trick, local_assigns[:variant]) %>
+<div class="flex items-start justify-between gap-3" x-data="{ copied: false }">
+  <div class="min-w-0 flex-1 space-y-1">
+    <h4 class="type-h4 text-heading" data-trick-name><%= t.name %></h4>
+    <p class="text-sm text-body" data-trick-note><%= t.note %></p>
+    <code class="block font-mono text-2xs text-muted break-words" data-trick-token><%= t.token %></code>
+    <% if t.variants.any? %>
+      <%# The variants by name, so "Sheen · loop" is on the card and not only on the
+          clipboard. %>
+      <ul class="space-y-0.5" data-trick-variants>
+        <% t.variants.each do |v| %>
+          <li class="text-2xs leading-snug"><span class="text-body font-semibold" data-trick-variant-name><%= v.name %></span> <code class="font-mono text-muted break-words"><%= v.token %></code></li>
+        <% end %>
+      </ul>
+    <% end %>
+  </div>
+  <button type="button"
+          class="btn btn-neutral btn-sm shrink-0"
+          aria-label="Copy the name for an agent"
+          data-trick-copy="<%= Studio::Tricks.agent_line(trick, local_assigns[:variant]) %>"
+          @click="navigator.clipboard?.writeText($el.dataset.trickCopy); copied = true; setTimeout(() => copied = false, 1200)">
+    <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
+  </button>
+</div>