studio-engine 0.130.0 → 0.132.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ce81b9c4f82a619f86521fd4495d07e8a2a81f9f1eb5f15963e26f0cb038aa
-  data.tar.gz: ed8a7169b6322c577ca796c974f4561bd3c4a2e29fa7da917cd28aec84f401b5
+  metadata.gz: dd2c739840540a736a0ad347abe13b22047ff20070c8e336df86172c6518d848
+  data.tar.gz: fced70c6c90490c2d74732bdae8270b25f0e7717a87623daf734984c6e4fb101
 SHA512:
-  metadata.gz: 4f0f640580ed2f77fdc6093e9a90f2edfc12bf2ba6925fc8ad6b24cd5587668c84d465090be866dcf19c5f536cb38ccbff123f078a52dbee52f8b2f7d73d302d
-  data.tar.gz: c02e3417b8f8eb1bb4b6b38706ddf79561959b61cacb7317a9465825c1724097c3b77fc5c4cf131f0011dff852b0c430c90f660277fd0067100a611cec10ec55
+  metadata.gz: fb8cc964841b4eb76cdb6a64a69cf2394f18d7d87863585c1159c2afc12305e5268acb8c508f7922744669793be9364135e79898415a1d6444c57c1e64dbd815
+  data.tar.gz: 3ad57bddb03aaf79c98c1f6f38ac5e92d743f59ce7701e502c092123b8731f0ac1c1d32a209310684662c8c81c6f2a2b44cbdb0a45c29d9265013aaa782ef607

data/CHANGELOG.md

@@ -4,6 +4,175 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.132.0 — 2026-11-06
+
+## 0.131.0 — 2026-11-05
+
+### Added
+
+- **A carousel opens where you tell it: `start:`, and a spotlight opens on its middle
+  slide.** Alex McRitchie saw an empty left half on a spotlight's first slide. `start:`
+  takes an index or `:middle`; it defaults to `:middle` for `style: :spotlight` and to 0
+  for a standard row, so a standard row is unchanged. The slide is the browser's
+  `scroll-initial-target`, so Chromium opens there before the first paint; elsewhere the
+  controller jumps there on connect, with no glide and an empty status line. The dots,
+  `data-current` and both arrows' `aria-disabled` are right from the server. A
+  `#fragment` inside the row wins over the start (task `carousel-start-and-button-glass`).
+- **`.studio-border-glow--clear`.** The border glow on a clear button: no fill, only the
+  moving rainbow ring and its halo, with the heading ink as the label (16:1 light, 18:1 dark,
+  measured). `<button class="btn studio-border-glow studio-border-glow--clear">`. Under
+  reduced motion the ring and halo of every `.studio-border-glow` stand still.
+- **The loader family: the eight ways a page says wait, in one place.** From the
+  reel Alex McRitchie shared (task `engine-loader-family`). `studio_loader` takes
+  three plain styles that draw no icon: `style: :spinner`, `style: :dots` and
+  `style: :bar` (a progressbar; `percent:` is its value, and with none it sweeps).
+  They wrap the canonical `.spinner`, `.loading-dots` and `.progress-meter` rules,
+  so there is one set of rules; an app's own `config.loader` still refuses them.
+  New: `studio_skeleton` (`:lines`, `:avatar`, `:card`, `:media`; aria-busy, shapes
+  hidden from assistive tech, a shimmer that stops under reduced motion),
+  `studio_infinite_scroll` (the next page loads in a Turbo frame as the list's end
+  nears, "Load more" stays visible, and a polite status line counts what came) and
+  `studio_pull_to_refresh` (phones with touch only). `/admin/style` has a Loaders
+  section with all eight, and a live infinite scroll from an admin-only demo feed
+  (`/admin/style/loaders_feed`). Busy buttons can show their busy words with
+  `data-loader-busy`. Docs: `docs/LOADER.md`, "The family".
+- **Agent replies show a small, safe Markdown subset.** In `studio/agent_chat`, an agent
+  turn's `**bold**`, `*italics*`, `` `code` ``, http(s) links, `- ` and `1. ` lists and
+  line breaks render as such, and a leading `> ` is dropped. The nodes are built with
+  `createElement` and text nodes, never HTML; any other markup, and any link that is not
+  http or https, shows as its own characters. A visitor's words stay plain text. Detail:
+  `docs/AGENT_CHAT.md`, "The page's script".
+- **A spotlight style for the carousel: `studio/_carousel`, `style: :spotlight`.** The
+  same carousel, arrows, dots and keys, but each slide snaps to the centre. The centred
+  slide is full size and colour, with an optional `caption:` line under it (a callable on
+  the item); its neighbours are smaller (0.75), faded and grey, and the next ones peek at
+  the edges. An arrow ("Previous slide", "Next slide") or key moves one slide, and every
+  slide gets a dot. It opens on its middle slide (`start:`, below). Where the browser
+  has scroll-driven animations (`animation-timeline: view()`), each slide's own view
+  timeline drives the look, so it follows the finger; elsewhere the controller marks the
+  centred slide `data-current` and CSS transitions it. Reduced motion scales and greys
+  nothing: the neighbours are only dimmed. An unknown `style:` raises. Specimen on
+  `/admin/style`, Tricks.
+- **Talk to an agent in a modal: `studio/agent_chat/_talk_modal`.** Render it once on a page,
+  then mark any link with `studio_talk_to_agent_link(label, href:, soul:, topic:, opener:)`. A
+  click opens the shared agent chat in a card on the page-scoped modal host and sends the
+  opener as the visitor's first message once the thread loads, so the agent is already
+  answering while the card opens. A new answer types itself in. It is the same chat and the
+  same hub thread as `studio/agent_chat/chat`, not a second one. The opener goes once per soul
+  and topic per tab. A modified click, a page with no modal, or a viewer
+  `agent_chat_allowed` refuses follows the link's `href`. The chat takes two new section
+  attributes, `data-agent-chat-opener` (with `-opener-key`) and `data-agent-chat-reveal`, and
+  the partial takes `compact: true`. Detail: `docs/AGENT_CHAT.md`, "Talk to an agent in a
+  modal".
+- **A crumb trail on the page header, from one parent map.** `studio/_page_header` takes
+  `crumbs:` (the page's ancestors, root first) and `crumb_label:`. The trail sits above the
+  title: muted ancestor links, the page itself bold, a chevron between. Below 40rem it gives
+  way to one "‹ Parent" link. An app names each parent page once in `Studio.crumbs.draw`
+  (`page :deployments, "Deployments", :deployments_path, parent: :admin`), and a view calls
+  `studio_crumbs(:key)` or `studio_crumbs(parent: :key)`. The row also takes `links:`, the
+  page's other links on a line at its foot that sticks with it, and renders `actions_html`
+  after the tabs when it has both. Detail: `docs/PAGE_HEADER.md`.
+- **The gliding pill.** The page header's open tab is one pill, anchored by CSS anchor
+  positioning to the tab with `aria-current`, so it glides to the next tab when the scroll spy
+  or a click moves `aria-current`. No script measures it. Reduced motion jumps. A browser
+  without anchor positioning keeps each tab's own fill.
+
+- **A carousel standard for the apps: `studio/_carousel`.** Render it as a layout, with
+  `label:` and `items:`, and the block draws each slide, so a slide is any block content.
+  The track is a native scroll-snap row: a swipe, a trackpad and a focused link move it with
+  no script. A wide row shows `per_view:` slides (default 3), a medium row up to two and a
+  phone one, each with a sliver of the next; the widths come from container queries on the
+  region, not the window. The lazy `carousel` controller adds the edge fade, arrows that
+  set `aria-disabled` at an end, dots that hide past the last stop, the arrow keys with Home
+  and End, and a polite status line after a press. It follows the APG carousel pattern:
+  a labelled region with `aria-roledescription="carousel"`, and each slide a labelled
+  group (`slide_label:` names it from its item). It honours `prefers-reduced-motion`, and
+  its arrows take the card fill, so they are glass under the glass surfaces. Until the
+  controller connects, the controls stay hidden and the row keeps a thin scrollbar. New
+  classes: `carousel`, `carousel-track`, `carousel-slide`, `carousel-controls`,
+  `carousel-dots`, `carousel-dot`, `carousel-arrows` and `carousel-button`. `/admin/style`
+  shows it under Tricks.
+
+### Changed
+
+- **A dark, full-size lit button's fill drops from 0.85 to 0.65 alpha** (`--lit-fill-alpha`),
+  Alex McRitchie's "even more transparent". White label on the primary, measured from painted
+  pixels at the label's median: a dark page 3.95 to 5.62, the lab photo 3.16 to 3.29, a mid-grey
+  backdrop (#808080) 3.25 to 3.42, a lighter one (#a0a0a0) 3.06 to 2.98. Light pages stay solid
+  (3.10).
+- **Back plays the app's page move the other way.** Browser Back (a Turbo restore that Turbo
+  marks `back`, or a full load that traverses to an earlier entry) and a click on a link with
+  `data-page-transition-back` (every ancestor crumb and the phone's parent link) play the
+  reverse direction in the same style: a `:left` slide goes back as `slide-right`, an
+  `:unfold` with `:right` as `unfold-right`. Forward keeps the app's own direction. Detail:
+  `docs/PAGE_TRANSITIONS.md`, "Back".
+- **The page header's title is the type scale's h2 from 40rem** (30px, weight 800), Alex
+  McRitchie's "H2 header"; a phone keeps 1.5x the base. It is still the page's one `h1`.
+
+### Fixed
+
+- **A standard carousel's `caption:` is a styled line** (small body text under each slide),
+  not bare text; the partial's docs and the README say which style shows which captions.
+- **Review follow-ups on the sidebar, the carousel and the page header** (/tasks/engine-ui-polish-follow-ups).
+  The link sidebar's focus ring (its rows, close button, Log out, trigger and geo rows) is
+  `ring-primary-ink`, a new ring colour from the theme's primary ink: measured 5.4 to 8.9:1
+  beside every surface in dark, light and glass on five palettes, from 1.3 to 2.0:1 for
+  `ring-primary/40`. A carousel arrow or key that goes nowhere scrolls and announces nothing;
+  keys inside a slider, listbox, combobox, tab list, other arrow-key widget or nested carousel
+  stay theirs; and the focusable track is a group named "<label> slides". The page header row
+  is now always a `<div>`: with tabs, the tabs are their own `<nav>` named by `label`, beside
+  the crumb and links navs, so no landmark nests in another (a host test that found the row by
+  `nav[aria-label=…]` now finds the tabs). The `/admin/style` specimen adds no landmark.
+  The current link under the title is bold as well as coloured, and the pill's track sets
+  `anchor-scope`. `studio_crumbs` with a key the map lacks still raises in development and
+  test; elsewhere it logs to ErrorLog and draws no trail, not a 500. The dead redirect guard
+  in `studio/page_transitions` is gone.
+- **`/admin/style`: Tricks is second, and nothing in the header is cut off.** The sections and
+  their pills run Theme, Tricks, Loaders, Modals, Tasks, Components (a host's own modals still
+  follow Modals). The tab scroller gives its pills 4px of room on every side, so their shadow, lit
+  edge and focus ring show, and the last pill's right edge too; phones still scroll sideways.
+  Each specimen card has one Copy (the snippet's, or the class name's when there is no
+  snippet), and the code wraps clear of it.
+- **The talk modal's opener is never dropped.** A visitor who sent a message before the
+  thread first loaded lost the opener: `studio/agent_chat` marked it sent, then the
+  post returned early because the visitor's send was in flight. Now a send made
+  before the load posts the opener first, then the visitor's words; a send made while
+  the opener is in flight waits for it; and the tab remembers the opener only as its
+  POST starts, forgetting it if the POST fails. It is never sent twice.
+- **`e2e/talk_to_agent.spec.js`'s modified-click spec no longer flakes.** It waited for
+  the new tab a Ctrl+click opens, which on CI's headless Linux Chromium stayed at
+  `about:blank` (it read "blank", and a wait for its URL timed out), so it measured the
+  browser rather than the modal. It now asserts what the modal owes a modified click:
+  the click is not prevented (the browser follows the `href`) and no card opens.
+- **A signup that cannot send its email no longer fails silently.** `RegistrationsController#create`
+  ended in a `rescue StandardError` that logged nothing and rendered `registrations/new`. On a
+  passwordless app `@user` was never set, so a failed link mint or mail raised `NoMethodError` on
+  nil in that view, and no ErrorLog row named the first failure. Now a passwordless failure is
+  logged through `rescue_and_log` and redirects to `/signup` with one friendly alert for every
+  address, so it reveals nothing about which emails have accounts. The account is still created
+  only when the link is used. A password signup re-renders the form on a validation error and
+  writes no ErrorLog row. A POST with no `user` params gets the form too, not a
+  `ParameterMissing`. Any other raise is logged once and goes to the catch-all. The rescue no
+  longer names the unsaved user as its target: ErrorLog's `belongs_to` autosaved it, which ran the
+  failing save again inside the logger. That second raise skipped the logged mark, so the
+  catch-all wrote the same failure twice.
+- **`rescue_and_log` writes one ErrorLog row per failure, also for an unsaved target.** It
+  linked `target:` with ErrorLog's `belongs_to`, which saves a new record. With an unsaved
+  record, the logger ran the failing save a second time. That raise skipped the logged mark,
+  so the catch-all wrote the same failure again, and a save that could pass created the
+  record. Now an unsaved target or parent is named on the row by its slug (else
+  `unsaved User`) and not linked. This covers the SSO, wallet and link sign-ups and the theme save. When the
+  ErrorLog write itself fails, in `rescue_and_log` or in the catch-all, `Rails.logger.error`
+  records both errors. `rescue_and_log` still raises the original error, and the catch-all
+  still gives its friendly reply. Before, the logger's error replaced both.
+- **`POST /magic_link` answers a failed mint or mail the same way for every address.** The
+  raise went to the catch-all: "Something went wrong" on the home page, or a JSON 500. Now
+  the failure is logged once and the visitor goes back to `/login` with one alert. JSON gets
+  `503` with `{ success: false, error: "delivery_failed", message: … }`: the input was
+  fine and a retry can work, so it is not a 4xx. The body does not carry the internal
+  message, and the action never looks an account up, so it reveals nothing about which
+  emails have accounts. `Studio::MagicLinkIssuing::DELIVERY_FAILED` holds the words.
+
 ## 0.130.0 — 2026-11-05
 
 ### Added

data/README.md

@@ -31,7 +31,7 @@ resolved.
 ## What It Provides
 
 - **Authentication**: Passwordless magic-link auth, optional password auth, Google OAuth via OmniAuth (ships ready: strategy, default `User.from_omniauth` and a setup modal until the OAuth client is set; docs/GOOGLE_AUTH_SETUP.md), Solana wallet sign-in, and optional one-way SSO patterns
-- **Error handling**: `Studio::ErrorHandling` concern with `rescue_and_log`, `ErrorLog` model with `capture!`, error log viewer at `/error_logs`
+- **Error handling**: `Studio::ErrorHandling` concern with `rescue_and_log`, `ErrorLog` model with `capture!`, error log viewer at `/error_logs`. `rescue_and_log` writes one row per failure: an unsaved `target:` or `parent:` is named on the row by its slug (else `unsaved User`), never linked, so the logger never saves it. If the row itself cannot be written, the original error still raises and `Rails.logger.error` records both.
 - **Session drift**: every page carries a session stamp and loads `window.StudioSession`, which notices when another tab signs in or out, the session expires, or the server revokes it; `session:changed` / `session:mismatch` events, cross-tab sync, an identity-source plug-in interface, and `expectChange` holds for deliberate switches. The rehydrate endpoint (`GET /session/state`) is opt-in. See [`docs/SESSION_DRIFT.md`](docs/SESSION_DRIFT.md).
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
 - **UI primitives**: Shared component partials and CSS primitives such as `components/emoji_swap` for nav/sidebar emoji hover transitions.
@@ -184,7 +184,9 @@ form only when `:password` is enabled and the User has `authenticate`
 sign-in-link form when `:magic_link` is enabled, and the Google button only with
 `:google`. A passwordless signup stores nothing from the form: it mails a link,
 and using the link creates the account. So `registration_params`' `:name` shows a
-Name field only on a password app.
+Name field only on a password app. If the link cannot be minted or mailed, the
+failure is logged to ErrorLog and the visitor goes back to `/signup` with one
+alert, the same for every address.
 
 `POST /login`, the password exchange, is drawn only when `auth_methods` includes
 `:password`. A passwordless app answers it with 404 for every address, so it
@@ -242,7 +244,7 @@ Rails.application.routes.draw do
 end
 ```
 
-This draws the enabled auth routes (`/login`, `/signup`, `/logout`, `POST /magic_link` to request a link, `GET`/`POST /l/:token` for the link itself, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`. Set `Studio.draw_geo_routes = true` to add the geo manager (`/admin/geo`) and its public probe (`/geo/check`) — off by default because turf-monster owns those helper names until its adoption lands. Magic-link emails point at the inert `GET /l/:token` confirmation page; the single-use token is burned only by the CSRF-protected `POST` to `link_consume_path`.
+This draws the enabled auth routes (`/login`, `/signup`, `/logout`, `POST /magic_link` to request a link, `GET`/`POST /l/:token` for the link itself, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`. Set `Studio.draw_geo_routes = true` to add the geo manager (`/admin/geo`) and its public probe (`/geo/check`) — off by default because turf-monster owns those helper names until its adoption lands. If `POST /magic_link` cannot mint or mail the link, it logs the failure and answers the same for every address: the login page with one alert, or a `503` with `{ success: false, error: "delivery_failed", message: … }` for JSON. Magic-link emails point at the inert `GET /l/:token` confirmation page; the single-use token is burned only by the CSRF-protected `POST` to `link_consume_path`.
 
 Set `Studio.draw_session_routes = true` to add the session-drift rehydrate endpoint (`GET /session/state`) — off by default because it inherits the host's filters, which an app should check first ([`docs/SESSION_DRIFT.md`](docs/SESSION_DRIFT.md)).
 
@@ -252,7 +254,7 @@ Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys
 
 **Magic links need the `studio_links` table.** Install it with `bin/rails studio_engine:install:migrations && bin/rails db:migrate` (install all of them) before enabling `:magic_link` — never by hand-copying the migration, which collides with the task's own copy on `class CreateStudioLinks`. Without the table, the first sign-in raises `Studio::Link::MissingTable`.
 
-Set `Studio.agent_chat_souls = %w[alex]` to add the shared agent chat's proxy (`POST /agent_chat/messages`, `GET /agent_chat/turns`), which forwards to the McRitchie Studio hub with the app's `AGENT_CHAT_TOKEN`; then `render "studio/agent_chat/chat", soul: "alex", name: "Alex", portrait: ...` on any page, with `voice: true` for hold to talk in the composer ([`docs/AGENT_CHAT.md`](docs/AGENT_CHAT.md)).
+Set `Studio.agent_chat_souls = %w[alex]` to add the shared agent chat's proxy (`POST /agent_chat/messages`, `GET /agent_chat/turns`), which forwards to the McRitchie Studio hub with the app's `AGENT_CHAT_TOKEN`; then `render "studio/agent_chat/chat", soul: "alex", name: "Alex", portrait: ...` on any page, with `voice: true` for hold to talk in the composer ([`docs/AGENT_CHAT.md`](docs/AGENT_CHAT.md)). To open that chat in a modal from any button, render `studio/agent_chat/talk_modal` once and mark the buttons with `studio_talk_to_agent_link` ([`docs/AGENT_CHAT.md`](docs/AGENT_CHAT.md), "Talk to an agent in a modal").
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
@@ -290,10 +292,19 @@ actions; the engine supplies only the banner.
 
 ### The page header — `studio/_page_header`
 
-An admin page's title: a plain header at rest, a bar once stuck under the navbar,
-in the pinned stack so a table's sticky header sits under it
+An admin page's title: a crumb trail from the app's one parent map (`Studio.crumbs`,
+`studio_crumbs`) above an h2-size title, tabs with a gliding pill and one action on the right,
+and the page's other links on a line under it. A plain header at rest, a bar once stuck under
+the navbar, in the pinned stack so a table's sticky header sits under it
 ([`docs/PAGE_HEADER.md`](docs/PAGE_HEADER.md)).
 
+```erb
+<%= render "studio/page_header", title: "Deployments", crumbs: studio_crumbs(:deployments),
+      label: "Views", tabs: [{ label: "Board", href: deployments_path, current: "page" }],
+      actions_html: link_to("New Task", new_task_path, class: "btn btn-sm btn-primary"),
+      links: [{ label: "Epics", href: epics_path }] %>
+```
+
 ### The section header — `studio/_section_header`
 
 A section's title that sticks under the page row until the next section's takes its place,
@@ -304,6 +315,41 @@ with a bar once stuck ([`docs/PAGE_HEADER.md`](docs/PAGE_HEADER.md#the-section-h
       tabs: [{ label: "Users", href: users_path, current: "page" }, { label: "Teams", href: teams_path }] %>
 ```
 
+### The carousel — `studio/_carousel`
+
+The apps' standard for a set too long to grid: a swipeable scroll-snap row with
+arrows, dots and arrow keys, a peek of the next slide, and an edge fade. Render it
+as a layout; the block draws each slide. `per_view:` is the wide row's count
+(default 3). `/admin/style` shows it under Tricks.
+
+```erb
+<%= render layout: "studio/carousel", locals: { label: "Portfolio", items: @apps, per_view: 3 } do |app| %>
+  <%= render "apps/card", app: app %>
+<% end %>
+```
+
+`caption:` (a callable on the item) writes a small line under each slide.
+
+`style: :spotlight` snaps each slide to the centre: the centred slide is full size and
+colour, with its caption under it (the spotlight shows the centred slide's only), and its
+neighbours are smaller, faded and grey. The arrows ("Previous slide", "Next slide") and
+keys move one slide. Where the browser has scroll-driven animations the look follows the
+scroll; elsewhere the controller marks the centred slide (`data-current`) and CSS
+transitions it. Reduced motion only dims.
+
+`start:` is the slide the row opens on: an index from 0, or `:middle`. A spotlight opens
+on its middle slide by default, so neither half of the row is empty at load; a standard
+row opens on its first. The browser sets it before the first paint where it has
+`scroll-initial-target`; elsewhere the controller jumps there when it connects, with no
+glide and nothing announced. A `#fragment` link to an element inside the row wins.
+
+```erb
+<%= render layout: "studio/carousel",
+      locals: { label: "Team", items: @people, style: :spotlight, caption: ->(person) { person.title } } do |person| %>
+  <%= render "people/card", person: person %>
+<% end %>
+```
+
 ### The "at" time stamp — `at_time_tag`
 
 Stamps WHEN something happened, on the reader's own clock: `at 3:53p`, gaining a

data/app/assets/tailwind/studio_engine/engine-motion.css

@@ -33,6 +33,9 @@
   Loader:
     .studio-loader        the app's icon as a branded loader   (Loader Lab picks)
     .studio-loader-overlay  the page-load overlay around it    (docs/LOADER.md)
+    .studio-skeleton      the content's shape while it loads   (loader family)
+    .studio-infinite-scroll  the next page near the end        (loader family)
+    .studio-pull-refresh  pull down to reload, phones only     (loader family)
 
   Leveling:
     .level-badge(-1..-10) progressive level pill ladder       (ported, TM)
@@ -2482,10 +2485,55 @@ body.modal-open { overflow: visible; }
     animation-delay: calc(var(--studio-loader-i, 0) * 0.6s - var(--studio-loader-sparks, 5) * 0.6s);
   }
 
+  /* ---- The plain styles: no icon, only the theme's colours ----------------
+     spinner, dots and bar wrap the canonical .spinner, .loading-dots and
+     .progress-meter rules (sections 2, 3 and 7 above) and only set their knobs,
+     so the family and those classes stay one set of rules. */
+  /* Drawn on the page like ink, so in the theme's contrast-checked primary
+     ink (theme_resolver), not the raw primary, which can sink into a dark
+     page. A mono loader keeps currentColor. */
+  .studio-loader:is([data-loader-style="spinner"], [data-loader-style="dots"], [data-loader-style="bar"]):not([data-loader-mono]) {
+    --studio-loader-color: var(--color-primary-ink, var(--color-primary));
+  }
+
+  /* :where() keeps the family's selectors from ending in the bare spinner class: a host
+     counts that one rule to prove the motion layer is imported once
+     (turf-monster test/lib/tailwind_css_first_test.rb). */
+  .studio-loader[data-loader-style="spinner"] :where(.spinner) {
+    --spinner-size: var(--studio-loader-size);
+    --spinner-thickness: max(2px, calc(var(--studio-loader-size) * 0.1));
+    --spinner-color: var(--studio-loader-color);
+    --spinner-track: color-mix(in srgb, var(--studio-loader-color) 22%, transparent);
+  }
+
+  .studio-loader[data-loader-style="dots"] { height: calc(var(--studio-loader-size) * 0.5); }
+  .studio-loader[data-loader-style="dots"] .loading-dots {
+    --loading-dots-size: calc(var(--studio-loader-size) * 0.22);
+    --loading-dots-gap: calc(var(--studio-loader-size) * 0.11);
+    --loading-dots-color: var(--studio-loader-color);
+  }
+
+  .studio-loader[data-loader-style="bar"] {
+    display: block;
+    height: var(--studio-loader-bar-height, 6px);
+    max-width: 100%;
+  }
+  .studio-loader[data-loader-style="bar"] .progress-meter {
+    --progress-height: 100%;
+    --progress: calc(var(--studio-loader-percent, 0) * 1%);
+    --progress-fill: var(--studio-loader-color);
+    --progress-track: color-mix(in srgb, var(--studio-loader-color) 16%, transparent);
+    display: block;
+    width: 100%;
+  }
+
   /* ---- Pending: inside a button, shown only while it or its form is busy --- */
   .studio-loader[data-loader-pending] { display: none; }
   :where(form, button)[aria-busy="true"] .studio-loader[data-loader-pending] { display: inline-grid; }
   :where(form, button)[aria-busy="true"] [data-loader-idle] { display: none; }
+  /* The words a busy button says instead ("Saving…"): shown only while busy. */
+  [data-loader-busy] { display: none; }
+  :where(form, button)[aria-busy="true"] [data-loader-busy] { display: inline; margin-inline-start: 0.5rem; }
   .studio-loader[data-loader-pending] .studio-loader-halo { display: none; }
   .studio-loader[data-loader-pending] .studio-loader-icon { width: 100%; height: 100%; animation-duration: 1.4s; }
 
@@ -2532,6 +2580,9 @@ body.modal-open { overflow: visible; }
     .studio-loader-orb,
     .studio-loader-art { display: none; }
     .studio-loader-fill { --studio-loader-level: 0.45; }
+    /* A still band would read as a percent; a still bar with no percent is a
+       faint full fill instead. */
+    .studio-loader[data-loader-style="bar"] .progress-meter--indeterminate .progress-meter-fill { width: 100%; opacity: 0.35; }
   }
 
   @keyframes studio-loader-breathe {
@@ -2578,3 +2629,126 @@ body.modal-open { overflow: visible; }
     26%, 100% { transform: scale(0.8); opacity: 0; }
   }
 }
+
+/* =============================================================================
+   LOADER FAMILY — skeleton, infinite scroll and pull to refresh (docs/LOADER.md).
+   The branded loader above draws a wait; these three hold a page's shape while
+   it waits. Markup: app/views/studio/loader/_skeleton, _infinite_scroll and
+   _pull_to_refresh, through Studio::LoaderHelper. Behaviour:
+   studio/infinite_scroll and studio/pull_to_refresh (lazy controllers).
+
+   Tune:  --studio-skeleton-bone    a bone's fill (default text at 9%)
+          --studio-skeleton-shine   the shimmer's highlight (default text at 7%)
+          --studio-skeleton-width   one line's width (the helper varies them)
+          --studio-skeleton-speed   one shimmer pass (default 1.6s)
+
+   The bones are tints of --color-text over whatever sits behind them, so one
+   rule reads on a dark, light or glass surface. Under prefers-reduced-motion a
+   skeleton is still and the pull indicator does not spin.
+   ========================================================================== */
+@layer components {
+  .studio-skeleton {
+    --studio-skeleton-bone: color-mix(in srgb, var(--color-text) 9%, transparent);
+    --studio-skeleton-shine: color-mix(in srgb, var(--color-text) 7%, transparent);
+    --studio-skeleton-speed: 1.6s;
+    position: relative;
+    display: grid;
+    gap: 1rem;
+  }
+
+  .studio-skeleton-item { display: grid; gap: 0.6rem; align-content: start; }
+  .studio-skeleton-item[data-skeleton-kind="avatar"] {
+    grid-template-columns: auto 1fr;
+    align-items: center;
+    column-gap: 0.85rem;
+  }
+  .studio-skeleton-item[data-skeleton-kind="avatar"] > .studio-skeleton-lines { display: grid; gap: 0.5rem; }
+  .studio-skeleton-lines { display: grid; gap: 0.55rem; }
+
+  .studio-skeleton-bone {
+    display: block;
+    border-radius: 0.375rem;
+    background:
+      linear-gradient(90deg, transparent 0%, var(--studio-skeleton-shine) 50%, transparent 100%) 0 0 / 200% 100% no-repeat,
+      var(--studio-skeleton-bone);
+    background-position: 150% 0, 0 0;
+    animation: studio-skeleton-shimmer var(--studio-skeleton-speed) ease-in-out infinite;
+  }
+
+  .studio-skeleton-bone[data-bone="line"] {
+    height: 0.75rem;
+    width: var(--studio-skeleton-width, 100%);
+  }
+  .studio-skeleton-bone[data-bone="title"] { height: 1.1rem; width: var(--studio-skeleton-width, 55%); }
+  .studio-skeleton-bone[data-bone="avatar"] { width: 2.75rem; height: 2.75rem; border-radius: 9999px; }
+  .studio-skeleton-bone[data-bone="media"] { width: 100%; aspect-ratio: 16 / 9; border-radius: 0.75rem; }
+
+  .studio-skeleton-item[data-skeleton-kind="card"] {
+    padding: 0.85rem;
+    border-radius: 1rem;
+    border: 1px solid color-mix(in srgb, var(--color-text) 8%, transparent);
+  }
+
+  @keyframes studio-skeleton-shimmer {
+    from { background-position: 150% 0, 0 0; }
+    to { background-position: -50% 0, 0 0; }
+  }
+
+  /* ---- Infinite scroll ----------------------------------------------------
+     Each page arrives inside a <turbo-frame> nested in the one before. The
+     frames take no box (display: contents), so the items flow into the
+     list's own grid or stack as if they were one list. */
+  .studio-infinite-scroll turbo-frame { display: contents; }
+  .studio-infinite-scroll-more,
+  .studio-infinite-scroll-end {
+    grid-column: 1 / -1;
+    display: flex;
+    justify-content: center;
+    padding-block: 1rem;
+  }
+  .studio-infinite-scroll-more .studio-loader { margin-inline-start: 0.5rem; }
+  .studio-infinite-scroll-end { margin: 0; font-size: 0.875rem; color: var(--color-text-secondary); }
+  /* Turbo marks the frame aria-busy while it fetches: the button keeps its
+     place and its words, and shows a spinner beside them (a [data-loader-idle]
+     child would hide while busy; "Load more" has none). */
+  .studio-infinite-scroll-next[aria-busy="true"] .studio-loader[data-loader-pending] { display: inline-grid; }
+  .studio-infinite-scroll-next[aria-busy="true"] [data-loader-idle] { display: none; }
+
+  /* ---- Pull to refresh ----------------------------------------------------
+     Phone widths and touch only: the controller arms itself there and nowhere
+     else, so on a desktop the indicator never shows. --studio-pull is how far
+     the finger has pulled, 0..1 of the threshold. */
+  .studio-pull-refresh { position: relative; }
+  .studio-pull-refresh-indicator {
+    --studio-pull: 0;
+    position: absolute;
+    top: 0;
+    left: 50%;
+    z-index: var(--z-raised, 10);
+    display: grid;
+    place-items: center;
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: 9999px;
+    background: var(--color-surface);
+    box-shadow: 0 2px 10px color-mix(in srgb, var(--color-text) 18%, transparent);
+    color: var(--color-primary-ink, var(--color-primary));
+    opacity: min(1, calc(var(--studio-pull) * 1.4));
+    transform: translate(-50%, calc(var(--studio-pull) * 4.5rem - 3rem)) rotate(calc(var(--studio-pull) * 270deg));
+    pointer-events: none;
+  }
+  .studio-pull-refresh-indicator[hidden] { display: none; }
+  .studio-pull-refresh[data-pull-state="settling"] .studio-pull-refresh-indicator { transition: transform 0.2s ease, opacity 0.2s ease; }
+  .studio-pull-refresh[data-pull-state="refreshing"] .studio-pull-refresh-indicator {
+    --studio-pull: 1;
+    transform: translate(-50%, 1.5rem);
+  }
+  .studio-pull-refresh-indicator .studio-pull-refresh-spinner { animation-play-state: paused; }
+  .studio-pull-refresh[data-pull-state="refreshing"] .studio-pull-refresh-indicator .studio-pull-refresh-spinner { animation-play-state: running; }
+
+  @media (prefers-reduced-motion: reduce) {
+    .studio-skeleton-bone { animation: none; background-position: 150% 0, 0 0; }
+    .studio-pull-refresh-indicator,
+    .studio-pull-refresh-indicator * { transition: none !important; animation: none !important; }
+  }
+}