studio-engine 0.130.0 → 0.131.0

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

@@ -1167,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/_specimen.html.erb

@@ -1,7 +1,8 @@
 <%#  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.
@@ -42,20 +43,26 @@
     <% if local_assigns[:note].present? %>
       <p class="text-sm text-body"><%= local_assigns[:note] %></p>
     <% end %>
-    <%# Class name — prominent, with a one-click copy so an agent can grab it. %>
+    <%# 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/_tricks.html.erb

@@ -85,6 +85,13 @@
         <button type="button" class="btn btn-primary studio-border-glow">Save</button>
       <% end %>
 
+      <%= render layout: "style/specimen",
+            locals: { klass: ".studio-border-glow--clear",
+                      note: "The same rainbow ring and halo on a clear button.",
+                      usage: %(<button class="btn studio-border-glow studio-border-glow--clear">Save</button>) } do %>
+        <button type="button" class="btn studio-border-glow studio-border-glow--clear" data-border-glow-clear>Save</button>
+      <% end %>
+
       <%= render layout: "style/specimen",
             locals: { klass: ".sheen .sheen--loop",
                       note: "Adds a band of light that sweeps across the button.",
@@ -168,7 +175,7 @@
   <section class="space-y-5" data-page-header-specimen>
     <div class="space-y-1">
       <h3 class="type-h4 text-heading">Page header</h3>
-      <p class="text-muted text-sm"><code class="font-mono text-2xs">studio/_page_header</code> is the title row, with optional meta and tabs.</p>
+      <p class="text-muted text-sm"><code class="font-mono text-2xs">studio/_page_header</code>: crumbs above the title, tabs on the right, other links under it; the open pill glides.</p>
     </div>
     <div class="grid gap-4 lg:grid-cols-2">
       <%# The classes alone, not the partial: the partial's row is sticky, joins the
@@ -176,8 +183,18 @@
       <% [["At rest", {}], ["Stuck", { stuck: "" }]].each do |state, data| %>
         <%= render layout: "style/specimen",
               locals: { klass: "studio/_page_header (#{state.downcase})",
-                        usage: %(<%= render "studio/page_header",\n      title: "Models", meta: "v1.2.3", label: "Models",\n      tabs: [{ label: "Users", href: users_path, current: "page" }, { label: "Teams", href: teams_path }] %\>) } do %>
+                        usage: %(<%= render "studio/page_header",\n      title: "Models", meta: "v1.2.3", label: "Models",\n      crumbs: studio_crumbs(parent: :admin),\n      tabs: [{ label: "Users", href: users_path, current: "page" }, { label: "Teams", href: teams_path }],\n      links: [{ label: "Sessions", href: sessions_path }] %\>) } do %>
           <%= tag.div(class: "page-header w-full px-4", data: data) do %>
+            <div class="page-header-trail">
+              <%# A div, not the partial's <nav>: a specimen adds no landmark to the page. %>
+              <div class="page-header-crumbs">
+                <ol>
+                  <li><a href="#tricks" class="page-header-crumb">Admin</a></li>
+                  <li><span class="page-header-crumb-current">Models</span></li>
+                </ol>
+              </div>
+              <a href="#tricks" class="page-header-parent"><span aria-hidden="true">&lsaquo;</span> Admin</a>
+            </div>
             <div class="page-header-lead">
               <p class="page-header-title">Models</p>
               <p class="page-header-meta label-upper">v1.2.3</p>
@@ -188,6 +205,10 @@
                 <a href="#tricks" class="btn btn-sm btn-neutral">Teams</a>
               </div>
             </div>
+            <div class="page-header-links">
+              <a href="#tricks" class="page-header-link">Sessions</a>
+              <a href="#tricks" class="page-header-link">Invites</a>
+            </div>
           <% end %>
         <% end %>
       <% end %>
@@ -217,6 +238,47 @@
     </div>
   </section>
 
+  <!-- Carousel -->
+  <section class="space-y-5" data-carousel-specimen>
+    <div class="space-y-1">
+      <h3 class="type-h4 text-heading">Carousel</h3>
+      <p class="text-muted text-sm"><code class="font-mono text-2xs">studio/_carousel</code> is a swipeable row of any slides, with arrows, dots and arrow keys.</p>
+    </div>
+    <%# The live partial: a carousel joins no stack and holds no title, so the
+        specimen is the real thing. Swipe it, press its arrows, or focus it and
+        use the arrow keys. %>
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio/_carousel",
+                    note: "Shows a set too long to grid, a few slides at a time.",
+                    usage: %(<%= render layout: "studio/carousel",\n      locals: { label: "Portfolio", items: @apps, per_view: 3 } do |app| %\>\n  <%= render "apps/card", app: app %\>\n<% end %\>) } do %>
+      <div class="w-full min-w-0">
+        <%= render layout: "studio/carousel",
+              locals: { label: "Specimen slides", items: (1..7).to_a, per_view: 3, id: "style-carousel-specimen" } do |n| %>
+          <div class="card h-full p-5 space-y-1">
+            <p class="label-upper">Slide <%= n %></p>
+            <p class="text-sm text-body">Any block content.</p>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio/_carousel (style: :spotlight)",
+                    note: "Centres one slide at full size and colour, with its caption, and shrinks, fades and greys its neighbours as they scroll by.",
+                    usage: %(<%= render layout: "studio/carousel",\n      locals: { label: "Team", items: @people, style: :spotlight,\n                caption: ->(person) { person.title } } do |person| %\>\n  <%= render "people/card", person: person %\>\n<% end %\>) } do %>
+      <div class="w-full min-w-0" data-carousel-spotlight-specimen>
+        <%= render layout: "studio/carousel",
+              locals: { label: "Spotlight specimen", items: (1..7).to_a, per_view: 3, style: :spotlight,
+                        id: "style-carousel-spotlight-specimen", caption: ->(n) { "Slide #{n}" } } do |n| %>
+          <div class="card h-full p-5 space-y-1 aspect-[4/3]" style="background-image: linear-gradient(150deg, rgb(var(--color-primary-rgb) / 0.35), transparent)">
+            <p class="label-upper">Slide <%= n %></p>
+            <p class="text-sm text-body">Any block content.</p>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+  </section>
+
   <!-- Surfaces, text and form -->
   <section class="space-y-5">
     <div class="space-y-1">

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

@@ -3,19 +3,21 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Five ENGINE sections, reached by the page header below and rendered
+     Six ENGINE sections, reached by the page header below and rendered
      as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the theme editor, the live preview, and the
-     logos and type), then Modals (the shared host + engine card blocks), Tricks
-     (the button/surface/motion/effect/leveling primitives, framed as a board of
-     copy-paste-for-an-agent snippets), Tasks (the shared board primitive), and
+     logos and type), then Tricks (the button/surface/motion/effect/leveling
+     primitives, framed as a board of copy-paste-for-an-agent snippets; second by
+     Alex McRitchie's ruling of 2026-11-05), Loaders (the eight loading primitives,
+     docs/LOADER.md), Modals (the shared host + engine card blocks), Tasks (the
+     shared board primitive), and
      Components (the ViewComponent previews, linking into the gallery at
      /admin/style/components).
 
-     A SIXTH section is the host app's own, and appears only on an app that asks
+     A SEVENTH section is the host app's own, and appears only on an app that asks
      for it: define app/views/style/host/_modals.html.erb in the consuming app
      and the guide grows a section (and a nav pill) for that app's own modals,
-     between Modals and Tricks. The gem still renders the section chrome; the app
+     between Modals and Tasks. The gem still renders the section chrome; the app
      supplies the specimens. Full contract, including which modal store a host
      specimen drives and why it is not the one the Modals section uses:
      app/views/style/_host.html.erb.
@@ -44,8 +46,11 @@
   # The section chrome and the consumer contract live in style/_host.html.erb.
   host_modals = lookup_context.exists?("modals", ["style/host"], true)
 
+  # Tricks second, after the landing Theme (Alex McRitchie, 2026-11-05).
   sections = [
     ["theme",  "Theme"],
+    ["tricks", "Tricks"],
+    ["loaders", "Loaders"],
     ["modals", "Modals"]
   ]
   # Adjacent to Modals, not appended: this page groups by SUBJECT, and a host's
@@ -53,7 +58,6 @@
   # name, so the pill says whose section it is.
   sections << ["host-modals", Studio.app_name] if host_modals
   sections += [
-    ["tricks", "Tricks"],
     ["tasks",  "Tasks"],
     ["components", "Components"]
   ]
@@ -68,6 +72,7 @@
       right before the module loads. %>
   <%= render "studio/page_header",
         title: "Style",
+        crumbs: studio_crumbs_here,
         meta: "v#{Studio::VERSION}",
         meta_title: "studio-engine",
         label: "Style guide sections",
@@ -83,11 +88,12 @@
       (76px on the hub at phone width). %>
   <div class="space-y-24 pt-10">
     <%= render "style/theme" %>
+    <%= render "style/tricks" %>
+    <%= render "style/loaders" %>
     <%= render "style/modals" %>
     <% if host_modals %>
       <%= render "style/host" %>
     <% end %>
-    <%= render "style/tricks" %>
     <%= render "style/tasks" %>
     <%= render "style/components" %>
   </div>

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

@@ -0,0 +1,7 @@
+<%# The Loaders section's demo feed, one page (StyleController#loaders_feed). A
+    whole page, so "Load more" opened with no script lands somewhere real; a
+    frame request takes just the frame it asked for out of it. %>
+<div class="max-w-xl mx-auto px-4 py-10 space-y-4">
+  <h1 class="type-h3 text-heading">Loaders demo feed</h1>
+  <%= render "style/loaders_feed_page", page: @page, feed_path: admin_style_loaders_feed_path %>
+</div>

data/lib/studio/crumbs.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Studio
+  # THE PARENT MAP behind studio/_page_header's crumb trail (docs/PAGE_HEADER.md, "Crumbs").
+  # An app names each page that has children once, with its label, its address and its own
+  # parent. A page then names only its parent, and the trail builds itself up the chain.
+  #
+  #   # config/initializers/studio_crumbs.rb
+  #   Studio.crumbs.draw do
+  #     page :admin,       "Admin",       :admin_dashboard_path
+  #     page :deployments, "Deployments", :deployments_path, parent: :admin
+  #     page :release,     ->(release:) { release.slug }, ->(release:) { release_path(release) },
+  #          parent: :deployments
+  #   end
+  #
+  #   <%= render "studio/page_header", title: "Deployments", crumbs: studio_crumbs(:deployments) %>
+  #   <%= render "studio/page_header", title: @task.title, crumbs: studio_crumbs(parent: :deployments) %>
+  #
+  # A label or an address is a String, a Symbol (a route helper, read in the view, then on
+  # main_app) or a lambda the view runs with the page's own keywords.
+  class Crumbs
+    Page = Struct.new(:key, :label, :path, :parent, keyword_init: true)
+
+    class UnknownPage < KeyError; end
+    class Cycle < ArgumentError; end
+
+    def initialize
+      @pages = {}
+    end
+
+    def draw(&block)
+      instance_eval(&block)
+      self
+    end
+
+    def page(key, label, path, parent: nil)
+      @pages[key.to_sym] = Page.new(key: key.to_sym, label: label, path: path, parent: parent&.to_sym)
+    end
+
+    def clear
+      @pages.clear
+      self
+    end
+
+    def key?(key) = @pages.key?(key.to_sym)
+
+    def fetch(key)
+      @pages.fetch(key.to_sym) { raise UnknownPage, "Studio.crumbs has no page #{key.inspect}" }
+    end
+
+    # The keys from the root down to `key`, `key` included.
+    def chain(key)
+      keys = []
+      current = key&.to_sym
+      while current
+        raise Cycle, "Studio.crumbs loops at #{current.inspect}" if keys.include?(current)
+
+        keys.unshift(current)
+        current = fetch(current).parent
+      end
+      keys
+    end
+
+    # The trail for one page: its ancestors, root first, as [{ label:, href: }]. Name the page
+    # itself (`key`, the page in the map) or only its parent (`parent:`, a page not in the map).
+    def trail(view, key = nil, parent: nil, **locals)
+      raise ArgumentError, "name the page or its parent, not both" if key && parent
+
+      keys = key ? chain(key)[0...-1] : chain(parent)
+      keys.map do |name|
+        page = fetch(name)
+        { label: resolve(view, page.label, locals).to_s, href: resolve(view, page.path, locals).to_s }
+      end
+    end
+
+    # The map's page at `path`, or nil: for a page the engine draws (the style guide, the
+    # model pages), which cannot know the host's key for it. Only pages whose address
+    # needs no keywords can match.
+    def key_for_path(view, path)
+      wanted = normalize(path)
+      @pages.each_value do |page|
+        next if page.path.is_a?(Proc) && keywords(page.path, required: true).any?
+
+        address = begin
+          resolve(view, page.path, {}).to_s
+        rescue StandardError
+          next
+        end
+        return page.key if normalize(address) == wanted
+      end
+      nil
+    end
+
+    # A name the map lacks, or a loop in it, is a mistake in the app's own code. In
+    # development and test it raises, so the mistake shows at once. Anywhere else (QA
+    # dynos run as production, so not Rails.env.production?) the page renders with no
+    # trail and the error is logged: a missing crumb is not worth a 500.
+    def self.strict?(env = (::Rails.env if defined?(::Rails) && ::Rails.respond_to?(:env)))
+      return true if env.nil?
+
+      env.development? || env.test?
+    end
+
+    REPORTED = {}
+    REPORTED_LOCK = Mutex.new
+
+    # Once per message per process: a layout renders on every request.
+    def self.report(error)
+      first = REPORTED_LOCK.synchronize { REPORTED[error.message] ? false : (REPORTED[error.message] = true) }
+      return unless first
+
+      if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+        ::ErrorLog.capture!(error)
+      elsif defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger.error("[studio-crumbs] no trail drawn: #{error.class}: #{error.message}")
+      end
+    rescue StandardError
+      nil # reporting is best-effort: the page still renders
+    end
+
+    private
+
+    # An address with no trailing slash; the root stays "/".
+    def normalize(path) = path.to_s.chomp("/").presence || "/"
+
+    def resolve(view, value, locals)
+      case value
+      when Proc then view.instance_exec(**locals.slice(*keywords(value)), &value)
+      when Symbol then route(view, value)
+      else value
+      end
+    end
+
+    def keywords(proc, required: false)
+      kinds = required ? %i[keyreq] : %i[key keyreq]
+      proc.parameters.filter_map { |kind, name| name if kinds.include?(kind) }
+    end
+
+    def route(view, name)
+      return view.public_send(name) if view.respond_to?(name)
+      return view.main_app.public_send(name) if view.respond_to?(:main_app)
+
+      raise NoMethodError, "Studio.crumbs: no route helper #{name}"
+    end
+  end
+
+  def self.crumbs
+    @crumbs ||= Crumbs.new
+  end
+end

data/lib/studio/loader.rb

@@ -23,6 +23,11 @@
 # The icon is drawn underneath as an image; the art is inlined over it. An art
 # file that is missing, outside public/, or has no marked layer falls back to
 # breathe, so a typo can never blank the loader.
+#
+# PLAIN styles draw no icon, only the theme's colours: spinner, dots and bar.
+# They are the small, everyday members of the same loader family, for a view to
+# name with studio_loader(style:). They are not an app's brand, so the app's own
+# config.loader refuses them.
 module Studio
   module Loader
     class InvalidConfig < ArgumentError; end
@@ -37,7 +42,20 @@ module Studio
     SETTING = "Studio.loader"
     GENERIC_STYLES = %i[breathe liquid orbit steel].freeze
     ART_STYLES = { weld_bead: "outline", sparkle: "spark" }.freeze
+    # The styles an app may declare as its loader: they draw its icon.
     STYLES = (GENERIC_STYLES + ART_STYLES.keys).freeze
+    # The styles a view may name that draw no icon (docs/LOADER.md, "The family").
+    PLAIN_STYLES = %i[spinner dots bar].freeze
+    # The size each style draws at when the caller names none: the icon styles at
+    # 96px, a spinner beside text, dots in a line, and a bar across its parent.
+    DEFAULT_SIZES = { spinner: 20, dots: 32, bar: "100%" }.freeze
+    DEFAULT_SIZE = 96
+    # The style guide's live infinite-scroll specimen: a demo feed of this many
+    # pages of this many items (style/_loaders_feed_page). Here, not on
+    # StyleController, so a view can read them without loading a controller that
+    # needs the host's ApplicationController.
+    DEMO_FEED_PAGES = 3
+    DEMO_FEED_PER_PAGE = 4
     DEFAULT_STYLE = :breathe
     KEYS = %i[style icon art].freeze
 
@@ -62,6 +80,10 @@ module Studio
       raise InvalidConfig, "#{SETTING} has unknown key :#{unknown.first} (takes #{KEYS.join(', ')})" if unknown.any?
 
       style = style!(config[:style] || DEFAULT_STYLE)
+      if PLAIN_STYLES.include?(style)
+        raise InvalidConfig, "#{SETTING} style :#{style} draws no icon, so it cannot be the app's loader " \
+                             "(one of #{STYLES.map(&:inspect).join(', ')}); a view names it with studio_loader(style: :#{style})"
+      end
       icon = path!(config[:icon], "#{SETTING}[:icon]")
       art = path!(config[:art], "#{SETTING}[:art]")
       if ART_STYLES.key?(style) && art.nil?
@@ -72,13 +94,19 @@ module Studio
       { style: style, icon: icon, art: art }.freeze
     end
 
+    # A style name as a Symbol, or InvalidConfig. Every style is a name a view may
+    # use; normalize refuses the plain ones for the app's own loader.
     def style!(value)
       style = value.to_s.strip.tr("-", "_").to_sym
-      return style if STYLES.include?(style)
+      return style if STYLES.include?(style) || PLAIN_STYLES.include?(style)
 
-      raise InvalidConfig, "#{SETTING} style must be one of #{STYLES.map(&:inspect).join(', ')} (got #{value.inspect})"
+      raise InvalidConfig, "#{SETTING} style must be one of #{(STYLES + PLAIN_STYLES).map(&:inspect).join(', ')} (got #{value.inspect})"
     end
 
+    def plain_style?(style) = PLAIN_STYLES.include?(style)
+
+    def default_size(style) = DEFAULT_SIZES.fetch(style, DEFAULT_SIZE)
+
     def path!(value, label)
       return nil if value.nil?
       return value.strip if value.is_a?(String) && !value.strip.empty?

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.130.0"
+  VERSION = "0.131.0"
 end

data/lib/studio.rb

@@ -77,6 +77,7 @@ require "studio/cable"
 require "studio/survey"
 require "studio/survey/breakdown"
 require "studio/survey/export"
+require "studio/crumbs"
 
 module Studio
   mattr_accessor :app_name,            default: "Studio"
@@ -2248,6 +2249,8 @@ module Studio
 
       # The living style guide (StyleController#index).
       get   "admin/style",            to: "style#index",               as: :admin_style
+      # One page of the Loaders section's demo feed (its live infinite scroll).
+      get   "admin/style/loaders_feed", to: "style#loaders_feed",      as: :admin_style_loaders_feed
 
       # The component gallery: Lookbook over the engine's ViewComponent previews.
       # The router refuses anyone but a signed-in admin, so a visitor and a