studio-engine 0.129.0 → 0.131.0

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

@@ -3,26 +3,29 @@
      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.
 
      HEADINGS wear the type ladder, on trial on this page only (style/_type_ladder): the one
      <h1> is studio/_page_header's, at type-h2; a section is an <h2> at type-h3; a subsection
-     is an <h3> at type-h4.
+     is an <h3> at type-h4. The section's <h2> is studio/_section_header's, in type-h3's numbers,
+     which sticks under the page row until the next section's takes its place.
 
      Specimens use ONLY the engine's own classes (engine.css component layer plus
      engine-motion.css motion/effect/leveling layer), so a consumer that imports
@@ -43,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
@@ -52,14 +58,13 @@
   # 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"]
   ]
 %>
 <div class="max-w-6xl mx-auto px-4 pt-6 pb-16" data-type-ladder>
   <%# The page's title and its section tabs: studio/_page_header, the row of the
-      triple stack (docs/PAGE_HEADER.md). It sits at --z-sticky, above --z-raised,
+      pinned stack (docs/PAGE_HEADER.md). It sits at --z-sticky, above --z-raised,
       so the live hold button's portal bubbles scroll under it rather than over it.
 
       The style-section-nav controller moves the highlight as the page scrolls
@@ -67,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",
@@ -77,13 +83,17 @@
             data: { style_section_nav_target: "link" } }
         } %>
 
-  <div class="space-y-16 pt-10">
+  <%# 6rem between sections: a first jump from the top of the page lands by the navbar's
+      collapse below the line, and the section above must be gone from the bar by then
+      (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.129.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.129.0
+  version: 0.131.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-05 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -482,6 +482,7 @@ files:
 - app/helpers/studio/admin_models_table_helper.rb
 - app/helpers/studio/agent_chat_helper.rb
 - app/helpers/studio/at_time_helper.rb
+- app/helpers/studio/crumbs_helper.rb
 - app/helpers/studio/fizz_helper.rb
 - app/helpers/studio/geo_helper.rb
 - app/helpers/studio/link_preview_helper.rb
@@ -502,17 +503,20 @@ files:
 - app/javascript/studio/birthday.js
 - app/javascript/studio/board.js
 - app/javascript/studio/booking.js
+- app/javascript/studio/carousel.js
 - app/javascript/studio/confirm_interstitial.js
 - app/javascript/studio/controllers/agent_chat_controller.js
 - app/javascript/studio/controllers/agent_chat_voice_controller.js
 - app/javascript/studio/controllers/board_controller.js
 - app/javascript/studio/controllers/booking_controller.js
+- app/javascript/studio/controllers/carousel_controller.js
 - app/javascript/studio/controllers/copy_text_controller.js
 - app/javascript/studio/controllers/email_banner_scale_controller.js
 - app/javascript/studio/controllers/footer_map_controller.js
 - app/javascript/studio/controllers/geo_settings_controller.js
 - app/javascript/studio/controllers/hold_button_controller.js
 - app/javascript/studio/controllers/identity_mini_controller.js
+- app/javascript/studio/controllers/infinite_scroll_controller.js
 - app/javascript/studio/controllers/knowledge_transcript_controller.js
 - app/javascript/studio/controllers/link_preview_card_controller.js
 - app/javascript/studio/controllers/link_sidebar_controller.js
@@ -520,9 +524,11 @@ files:
 - app/javascript/studio/controllers/modal_host_controller.js
 - app/javascript/studio/controllers/nav_collapse_controller.js
 - app/javascript/studio/controllers/page_header_controller.js
+- app/javascript/studio/controllers/pull_to_refresh_controller.js
 - app/javascript/studio/controllers/style_modals_controller.js
 - app/javascript/studio/controllers/style_section_nav_controller.js
 - app/javascript/studio/controllers/survey_controller.js
+- app/javascript/studio/controllers/talk_to_agent_controller.js
 - app/javascript/studio/controllers/toast_controller.js
 - app/javascript/studio/controllers/voice_profile_controller.js
 - app/javascript/studio/controllers/voice_recorder_controller.js
@@ -537,6 +543,7 @@ files:
 - app/javascript/studio/host_fetchers.js
 - app/javascript/studio/identity_mini.js
 - app/javascript/studio/image_upload.js
+- app/javascript/studio/infinite_scroll.js
 - app/javascript/studio/knowledge_transcript.js
 - app/javascript/studio/lazy_controllers.js
 - app/javascript/studio/level_meter.js
@@ -555,6 +562,7 @@ files:
 - app/javascript/studio/page_transitions.js
 - app/javascript/studio/pinned_stack.js
 - app/javascript/studio/profile_form.js
+- app/javascript/studio/pull_to_refresh.js
 - app/javascript/studio/sticky_table_header.js
 - app/javascript/studio/stimulus.js
 - app/javascript/studio/studio_confetti.js
@@ -562,6 +570,7 @@ files:
 - app/javascript/studio/style_modals.js
 - app/javascript/studio/style_section_nav.js
 - app/javascript/studio/survey.js
+- app/javascript/studio/talk_to_agent.js
 - app/javascript/studio/theme_editor.js
 - app/javascript/studio/toast.js
 - app/javascript/studio/transition_snapshot.js
@@ -638,13 +647,16 @@ files:
 - app/views/studio/_at_time_script.html.erb
 - app/views/studio/_birthday_assets.html.erb
 - app/views/studio/_board_assets.html.erb
+- app/views/studio/_carousel.html.erb
 - app/views/studio/_confirm_interstitial.html.erb
 - app/views/studio/_cropper_assets.html.erb
+- app/views/studio/_fizz.html.erb
 - app/views/studio/_fizz_layer.html.erb
 - app/views/studio/_hold_button.html.erb
 - app/views/studio/_hold_button_guard.html.erb
 - app/views/studio/_leveling_activity_assets.html.erb
 - app/views/studio/_page_header.html.erb
+- app/views/studio/_section_header.html.erb
 - app/views/studio/_session_stamp.html.erb
 - app/views/studio/admin_models/_arenas_table.html.erb
 - app/views/studio/admin_models/_sessions_table.html.erb
@@ -655,6 +667,7 @@ files:
 - app/views/studio/agent_chat/_chat.html.erb
 - app/views/studio/agent_chat/_form.html.erb
 - app/views/studio/agent_chat/_header.html.erb
+- app/views/studio/agent_chat/_talk_modal.html.erb
 - app/views/studio/agent_chat/_turn.html.erb
 - app/views/studio/agent_chat/_typing.html.erb
 - app/views/studio/agent_chat/_voice.html.erb
@@ -705,8 +718,11 @@ files:
 - app/views/studio/knowledge_docs/preview.html.erb
 - app/views/studio/knowledge_docs/show.html.erb
 - app/views/studio/links/confirm.html.erb
+- app/views/studio/loader/_infinite_scroll.html.erb
 - app/views/studio/loader/_loader.html.erb
 - app/views/studio/loader/_overlay.html.erb
+- app/views/studio/loader/_pull_to_refresh.html.erb
+- app/views/studio/loader/_skeleton.html.erb
 - app/views/studio/local_emails/index.html.erb
 - app/views/studio/mailers/_layered_banner.html.erb
 - app/views/studio/marketing_kit/_assets.html.erb
@@ -793,6 +809,8 @@ files:
 - app/views/style/_components.html.erb
 - app/views/style/_glass.html.erb
 - app/views/style/_host.html.erb
+- app/views/style/_loaders.html.erb
+- app/views/style/_loaders_feed_page.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_scrims.html.erb
@@ -804,6 +822,7 @@ files:
 - app/views/style/_type_ladder.html.erb
 - app/views/style/board/_demo_card.html.erb
 - app/views/style/index.html.erb
+- app/views/style/loaders_feed.html.erb
 - app/views/style/modals/_age_gate.html.erb
 - app/views/style/modals/_birthday.html.erb
 - app/views/style/modals/_ds_close_x.html.erb
@@ -855,6 +874,7 @@ files:
 - lib/studio/cable.rb
 - lib/studio/color_scale.rb
 - lib/studio/component_gallery.rb
+- lib/studio/crumbs.rb
 - lib/studio/email.rb
 - lib/studio/email_image_generator.rb
 - lib/studio/email_smoke.rb