studio-engine 0.131.0 → 0.133.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f090aa3b8a00d7e7a62e7395fdc02fff3c0fdf4063350a492e1e835932dc5b26
-  data.tar.gz: 6d2ae853a4bb64281147c1a67721d93e1a8c38b5d3fb43e6897df85c7be964c7
+  metadata.gz: 7aa30f915a5a06beddbc97ad855340b80114d9875dab7d43669596202a62f197
+  data.tar.gz: 5737966bb7427575a76320d618e5a1221b747625c6e8393a4f2a4ede7ed4a306
 SHA512:
-  metadata.gz: 7cc84fc8fad2d0b18b53e41b96e8d11bc878d8cdad732bc4a02b3581466fdafb927f3fbec54984e0ca04c839c85417008bef31f6efe21b347ebe4fce7ad7672b
-  data.tar.gz: 2b005e75062ef195f1178074f97efc738d798e69ee9dccbfb58cd88f1155760f4cbc1712da6bbd8de624673fce6d76a2f0982a0b8b3a58d615add5fc2f626c87
+  metadata.gz: aed3464a127458df847bcebd599605b0816e1698803c36aaa850c287cc73848c40454cd794968cf0ea4359e6f22bc3a3d56919d442c79e70dabb32fd2c0bb1de
+  data.tar.gz: fed96340b5100692ff438bf1e40de11edee35cf3bed69260ef93520d0e004454cb4f4895cedd55c09112275dbb334b5a529796486f2bd943a92dd8019671b530

data/CHANGELOG.md

@@ -4,10 +4,97 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.133.0 — 2026-11-06
+
+### Deprecated
+
+- **`studio/_page_header`'s `actions_html:`.** It still renders, before the menu, for one
+  more release. In development the first render from each call site writes one warning to
+  the log. Move each control to `tabs:`, `menu:`, `action:`, `tools_html:` or `meta:`.
+### Changed
+
+- **A link to a place on the same page scrolls there. It no longer loads the page again.**
+  Alex McRitchie, on the style guide's tabs: "The system needs to understand when a scroll
+  down is the solution rather than a page change." Turbo 8 made a click on `#tricks` a full
+  visit: a fetch, a render and the page transition. `studio/in_page_links` now takes a plain
+  click on a link to this page's path and query with a `#fragment` whose element exists. It
+  smooth-scrolls to the element under the pinned stack (a jump under reduced motion), pushes
+  the fragment so Back and a shared link work, and moves focus to the target. Cross-page
+  links, modifier clicks, `target`, `download` and `data-turbo="false"` are untouched. The
+  style guide's tab highlight holds the clicked tab until the scroll settles
+  (docs/PAGE_HEADER.md, "In-page links"; task `in-page-links-scroll`).
+- **The style guide's cards carry trick names, not markup snippets.** Alex McRitchie,
+  2026-11-06: "I really just need to have a good naming convention so I can convey an
+  idea to my agents." Every card under Tricks, Loaders and Tasks on `/admin/style` now
+  shows a short name as its heading ("Sheen", "Border Glow", "Hold"), a one-line note,
+  and its class or helper small and muted. A variant is the name, a middle dot and a
+  lower-case word ("Sheen · loop", "Border Glow · clear", "Hold · recolor"), and
+  variants of one primitive share a card, side by side on its stage: Tricks and
+  Loaders went from 79 cards to 58. The usage `<pre>` and its Copy are gone; the one Copy copies the
+  agent line, for example `Sheen — .sheen; Sheen · loop — .sheen--loop`. One registry,
+  `config/studio_tricks.yml` (`Studio::Tricks`), feeds the cards and the generated
+  glossary `docs/TRICKS.md` (`bin/tricks-doc`; `test/lib/tricks_registry_test.rb`
+  fails when they drift, a name repeats, or a token names a class, helper, partial or
+  script the engine does not ship). `style/_specimen` takes `trick:` (and `variant:`)
+  in place of `klass:`, `usage:` and `note:`. The Tricks branded-loader group no longer
+  repeats the busy button and the overlay trigger: they are the Loaders section's Busy
+  Button and Overlay (task `tricks-named-not-snippets`).
+
+### Added
+
+- **The page header's four kinds of control.** Alex McRitchie, 2026-11-06: the
+  /deployments header showed a grey pill, a purple button and a black button side by
+  side. `studio/_page_header` now takes the right side as four kinds, each with one look,
+  in one fixed order and at one height: `tabs:` (views of the same thing) or `anchors:`
+  (sections of this page, the same pill group), `menu:` (pages elsewhere, behind one
+  neutral "Links" button that opens a popover list; Escape closes it and focus returns),
+  `action:` (the one primary button) and `tools_html:` (local-only controls, muted). A
+  small primary button in the row takes a clear 1px border, so it stands at a neutral
+  button's height. `docs/PAGE_HEADER.md` gives the decision rule for which kind a link is,
+  and the style guide's Page header specimen shows all four (task
+  `page-header-control-kinds`).
+
+- **A carousel can loop and play itself: `loop:` and `autoplay:`.** Alex McRitchie wants
+  the hub's Portfolio spotlight "auto scrolling and in a loop". `loop: true` wraps the
+  arrows and keys (last to first, first to last) and keeps both arrows enabled, with no
+  cloned slides. `autoplay: <seconds>` moves one slide each interval in `:standard` and
+  `:spotlight`; it holds on hover over the slides, on keyboard focus, in a hidden tab, off
+  screen, and after any swipe or press until the reader is idle; it starts stopped under
+  reduced motion and never writes the status line. A pause button (`.carousel-autoplay`,
+  "Pause slideshow" / "Play slideshow") meets WCAG 2.2.2. Both default off, so every
+  existing carousel is unchanged (task `carousel-autoplay-and-loop`).
+- **The engine ships a standard sign-in card.** Alex McRitchie, on the style guide's
+  Email field specimen: "this should use the standard auth component with Google and
+  Email." `studio/auth/_sign_in_card` (a page) and `studio/auth/_sign_in_modal` (a
+  modal host's template) render Google, then "or", then the email magic link; Send
+  flips the card to a link-sent step with the shared resend footer. Locals: `heading`,
+  `subheading` (default "Sign in to" the app name), `return_to` (a plain in-app path
+  only; it rides the magic-link POST and the Google request URL), `preamble` and
+  `extras` slots for an age attestation or extra providers, and `demo`. Real use
+  posts Google to `/auth/google_oauth2` (`button_to` POST, Turbo off) and the email to
+  `POST /magic_link`, and reads the `503 delivery_failed` answer. `demo: true` posts
+  nothing. `/admin/style` > Modals > Auth is now one "Sign in" specimen that opens
+  the card in demo mode; the separate Email field and Resend footer specimens are
+  gone, and both partials stay. `studio/modals/auth/_resend_footer` takes
+  `close: false` for a host that is not a modal. The hub and turf-monster still
+  render their own cards; adoption is follow-up work. This reverses the 2026-09-09
+  call (PR #319) that the engine ships only the fragments, not a card. Docs: `docs/SIGN_IN_CARD.md`
+  (task `engine-ships-sign-in-card`).
+
+## 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
@@ -36,7 +123,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   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 or key moves one slide, and every slide gets a dot. Where the browser
+  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
@@ -84,6 +172,11 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### 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
@@ -95,6 +188,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### 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

data/README.md

@@ -30,7 +30,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
+- **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; one standard sign-in card (Google, or, email magic link) as a page partial and a modal ([`docs/SIGN_IN_CARD.md`](docs/SIGN_IN_CARD.md))
 - **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`.
@@ -293,18 +293,24 @@ actions; the engine supplies only the banner.
 ### The page header — `studio/_page_header`
 
 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
+`studio_crumbs`) above an h2-size title, the right side's four kinds of control (tabs or
+anchors with a gliding pill, a Links menu, one action, then tools, in that order and at one
+height), 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"),
+      label: "Views", tabs: [{ label: "Board", href: deployments_path, current: "page" },
+                             { label: "Triage", href: triage_path }],
+      menu: [{ label: "Stages", href: stages_path }, { label: "Docs", href: docs_path }],
+      action: { label: "New Task", href: new_task_path },
       links: [{ label: "Epics", href: epics_path }] %>
 ```
 
+`actions_html:` is deprecated for one release; the decision rule for which kind a link is
+lives in [`docs/PAGE_HEADER.md`](docs/PAGE_HEADER.md#the-four-kinds-of-control).
+
 ### The section header — `studio/_section_header`
 
 A section's title that sticks under the page row until the next section's takes its place,
@@ -328,11 +334,40 @@ as a layout; the block draws each slide. `per_view:` is the wide row's count
 <% 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:` line (a callable on the item) under it, and its neighbours
-are smaller, faded and grey. The arrows 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.
+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.
+
+`loop: true` wraps the row: Next at the last slide goes to the first, Previous at the first
+to the last, and neither arrow is ever disabled. No slide is cloned, so a screen reader reads
+each one once; the row glides back across itself.
+
+`autoplay:` is the seconds between moves (default `nil`, off). The row moves one slide each
+interval, in both styles. It holds still while the pointer is over the slides, while keyboard
+focus is in the row, while the tab is hidden or the row is off screen, and after a swipe,
+wheel, arrow, dot or key until the reader leaves it alone for one interval (never under five
+seconds). A pause button ("Pause slideshow", then "Play slideshow") sits before the arrows,
+for WCAG 2.2.2. Under reduced motion the row starts stopped, and Play starts it. Autoplay
+never writes the status line. Without `loop:` it stops at the last slide, and Play starts
+again from the first.
+
+```erb
+<%= render layout: "studio/carousel",
+      locals: { label: "Portfolio", items: @apps, style: :spotlight, autoplay: 5, loop: true } do |app| %>
+  <%= render "apps/card", app: app %>
+<% end %>
+```
 
 ```erb
 <%= render layout: "studio/carousel",
@@ -612,23 +647,22 @@ inline transport nothing listens, so the dispatch is a harmless no-op there.
 
 #### The auth modal's credential slot
 
-**This engine ships no sign-in card.** Each app owns its own and computes its
-credential buttons itself: turf-monster's is `app/views/modals/_auth.html.erb`,
-which is also the authority `lib/studio.rb` cites beside the Solana routes. The
-engine's one auth card was the living style guide's MIRROR of turf's,
-`style/modals/_auth`, and it was retired with the other mirrors on 2026-09-09
-(PR #319). For sign-in the engine now ships fragments, not a card:
-`studio/modals/shared/_email_field` and `studio/modals/auth/_resend_footer`,
-each carded on the style guide.
-
-**The wallet credential slot has no host today.** solana-studio still ships
-`solana_studio/auth/_wallet_credential`, a Solana button written to be
-*contributed* into a sign-in card rather than copied into one. The retired
-mirror was its only renderer. Neither turf-monster nor mcritchie-studio names
-the path; turf's card draws its wallet button directly. So bundling solana-studio
-no longer puts a wallet button anywhere. Whether the engine should host the slot
-again, or the convention should be retired, is an open call, not a fact this
-README can settle.
+**This engine ships the standard sign-in card:** `studio/auth/_sign_in_card`
+(a page) and `studio/auth/_sign_in_modal` (a modal), Google, then "or", then the
+email magic link, built from `studio/modals/shared/_email_field` and
+`studio/modals/auth/_resend_footer` ([`docs/SIGN_IN_CARD.md`](docs/SIGN_IN_CARD.md)).
+It is the one authority `lib/studio.rb` cites beside the Solana routes. It
+reverses the 2026-09-09 call (PR #319) that the engine ships only the fragments
+(Alex McRitchie, 2026-11-06). Until the apps adopt it, each still renders its
+own card: turf-monster's `app/views/modals/_auth.html.erb` computes its wallet
+button from `auth_methods` and `feature?(:web3)`.
+
+**The wallet credential slot is the card's `extras:` local.** solana-studio
+still ships `solana_studio/auth/_wallet_credential`, a Solana button written to
+be *contributed* into a sign-in card rather than copied into one. The engine
+card takes extra providers as named partials, after Google and before "or", so
+an app passes `extras: "solana_studio/auth/wallet_credential"` (or its own
+wallet button). Turf's adoption decides which one it keeps.
 
 **A card that does host it owns the gate.** The retired mirror's rules still
 hold; they simply live in that app's view now. Two layers answer two different
@@ -822,8 +856,11 @@ than assuming drop-in equivalence:
 ### Style guide — your app's own section
 
 `/admin/style` is the engine's living style guide, and every section on it is
-the engine's: Theme, Modals, Tricks, Tasks. An app grows a **fifth section, its
-own**, by defining one partial:
+the engine's: Theme, Modals, Tricks, Tasks. Each card under Tricks, Loaders and
+Tasks carries a short trick name ("Sheen", "Border Glow · clear") that you can say
+to an agent: [`docs/TRICKS.md`](./docs/TRICKS.md) maps every name to its class or
+helper, generated from `config/studio_tricks.yml` by `bin/tricks-doc`. An app grows a
+**fifth section, its own**, by defining one partial:
 
 A host may also define `app/views/style/host/_logos.html.erb`, which replaces the Theme section's
 default logo grid.

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

@@ -377,6 +377,13 @@ body.modal-open .studio-app-banner {
 
 @utility page-header-actions {
   flex-shrink: 0;
+  /* The fixed order of the right side (docs/PAGE_HEADER.md, "The four kinds of control"):
+     the menu, then the action, then the tools. Each is a .btn-sm, so all share one height. */
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.5rem;
   /* Never wider than the row: a group of controls wraps inside it on a phone, and the
      page does not scroll sideways. */
   max-width: 100%;
@@ -388,6 +395,116 @@ body.modal-open .studio-app-banner {
   }
 }
 
+/* ONE CONTROL HEIGHT. A .btn-neutral carries a 1px border and a .btn-primary none, so side
+   by side the neutral one stood 2px taller (30px to 28px, measured in the e2e lab). In the
+   row every small primary takes a clear border of the same width, so a tab, the menu, the
+   action and a tool all stand at one height. */
+.page-header .btn-sm.btn-primary {
+  border: 1px solid transparent;
+}
+
+/* THE QUICK-LINKS MENU: related pages elsewhere, behind one neutral "Links" button. The
+   list is the browser's popover, so Escape, a click outside and the focus return need no
+   script. Where the browser has anchor positioning, CSS hangs the list under the button's
+   right edge; elsewhere the page-header controller places it (studio/page_header,
+   menuPlacement). anchor-scope keeps each row's button its own anchor. */
+@utility page-header-menu {
+  position: relative;
+  anchor-scope: --page-header-menu;
+}
+
+@utility page-header-menu-button {
+  gap: 0.375rem;
+  anchor-name: --page-header-menu;
+}
+
+/* A chevron that points down, and up while the list is open. CSS, so a reader hears the
+   button's name alone. */
+@utility page-header-menu-caret {
+  width: 0.375rem;
+  height: 0.375rem;
+  border-right: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  transform: translateY(-0.125rem) rotate(45deg);
+  transition: transform 150ms ease;
+
+  .page-header-menu:has(> .page-header-menu-list:popover-open) & {
+    transform: translateY(0.125rem) rotate(225deg);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}
+
+@utility page-header-menu-list {
+  /* The popover's own styles centre it on the screen; this is a dropdown. */
+  position: fixed;
+  inset: auto;
+  margin: 0;
+  min-width: 10rem;
+  max-width: min(20rem, calc(100vw - 2rem));
+  padding: 0.25rem;
+  @apply rounded-lg border border-subtle bg-surface text-body shadow-lg;
+
+  & ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  @supports (anchor-name: --a) and (position-anchor: --a) {
+    position-anchor: --page-header-menu;
+    top: anchor(bottom);
+    right: anchor(right);
+    margin-top: 0.25rem;
+    position-try-fallbacks: flip-block, flip-inline;
+  }
+}
+
+@utility page-header-menu-item {
+  display: block;
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.375rem;
+  font-size: calc(var(--type-base, 16px) * 0.875);
+  font-weight: 500;
+  text-decoration: none;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  @apply text-body;
+
+  &:hover,
+  &:focus-visible {
+    @apply bg-surface-alt text-heading;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: -2px;
+  }
+}
+
+/* THE TOOLS: local-only and dev controls, after the action. Muted, behind a dashed rule, so
+   they never read as the page's own controls; full strength while a pointer or focus is on
+   them. */
+@utility page-header-tools {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding-left: 0.5rem;
+  border-left: 1px dashed;
+  @apply border-subtle;
+  opacity: 0.7;
+  transition: opacity 150ms ease;
+
+  &:hover,
+  &:focus-within {
+    opacity: 1;
+  }
+}
+
 /* THE TRAIL: the page's ancestors above the title (docs/PAGE_HEADER.md, "Crumbs"). It takes
    the row's whole first line, so the title, the tabs and the actions share the next one.
    Ancestors are muted links, the page itself is bold, and a chevron sits between. Below
@@ -685,6 +802,20 @@ body.modal-open .studio-app-banner {
   flex: 0 0 calc((100% - var(--carousel-n) * var(--carousel-gap)) / (var(--carousel-n) + var(--carousel-peek)));
   min-width: 0;
   scroll-snap-align: start;
+
+  /* The partial's start: past the first slide. A browser with scroll-initial-target
+     opens the row on this slide before the first paint, so the start costs no jump;
+     elsewhere the controller sets it when it connects. */
+  &[data-carousel-start-slide] {
+    scroll-initial-target: nearest;
+  }
+}
+
+/* The caption's line under a slide (the partial's caption:). A standard row shows it
+   under every slide; the spotlight (below) shows it under the centred slide only. */
+@utility carousel-caption {
+  margin-top: 0.5rem;
+  @apply text-sm text-body;
 }
 
 @utility carousel-controls {
@@ -815,6 +946,23 @@ body.modal-open .studio-app-banner {
   }
 }
 
+/* The pause button of an autoplaying row (autoplay:), a carousel-button beside the
+   arrows. It shows pause while the row may move and play once the reader (or reduced
+   motion) has stopped it; the controller sets data-carousel-stopped and the name. */
+@utility carousel-autoplay {
+  & .carousel-autoplay-play {
+    display: none;
+  }
+
+  &[data-carousel-stopped] .carousel-autoplay-pause {
+    display: none;
+  }
+
+  &[data-carousel-stopped] .carousel-autoplay-play {
+    display: block;
+  }
+}
+
 /* -- The spotlight carousel (studio/_carousel, style: :spotlight) --------------
    The same region, track, arrows, dots and keys, but each slide snaps to the centre.
    The centred slide is full size and full colour, with its caption under it; its
@@ -1023,6 +1171,13 @@ body.modal-open .studio-app-banner {
   scroll-margin-top: calc(var(--nav-h, 5rem) + var(--pin-page-h, 0px) + var(--section-header-h));
 }
 
+/* An in-page link's target takes focus when the jump lands (studio/in_page_links). One that
+   is not focusable of itself gets tabindex=-1 and this mark until it loses focus. Focus is
+   for the next Tab, not a ring round a whole section. */
+[data-in-page-focus]:focus {
+  outline: none;
+}
+
 /* -- Scrims: tints and shades ----------------------------------------------
    A scrim is the wash laid over media (a photo, a video) so text reads on it.
    It comes in two TONES, and the tone is a design decision, not a colour pick:
@@ -2279,13 +2434,14 @@ html[data-theme-flip]::view-transition-new(*) {
        stop. The violet, centered on the brand colour, is bright enough at its low stop. */
     html.dark[data-surface-style="glass"] :is(.btn-secondary, .btn-danger, .btn-warning, .btn-success) { --lit-glow-stop: var(--lit-top-stop); }
     /* A TOUCH OF TRANSPARENCY on a full-size filled button, dark theme only: a photo behind it
-       shows subtly, and white text holds its contrast at the midpoint. An outer shadow is not painted
+       shows through. At 0.65 (Alex McRitchie, 2026-11-05) white text on the primary measures 5.6:1
+       on a dark page, 3.4:1 over a mid-grey photo and 3.0:1 over a light-mid one (#a0a0a0). An outer shadow is not painted
        under its own box, so the glow never brightens the fill. On a light page the backdrop would
        lift the fill and cost contrast, so it stays solid there. Without a blur, or without relative
        oklch (the gradient would drop out and leave white text on nothing), it stays solid. */
     @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) and (color: oklch(from red l c h)) {
       html.dark[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(.btn-sm, :disabled, [aria-disabled="true"], [class*=" bg-"], [class^="bg-"]) {
-        --lit-fill-alpha: 0.85;
+        --lit-fill-alpha: 0.65;
         background-color: transparent;
         -webkit-backdrop-filter: blur(6px);
         backdrop-filter: blur(6px);

data/app/javascript/studio/application.js

@@ -19,6 +19,7 @@ import IdentityMiniController from "studio/controllers/identity_mini_controller"
 import { startPinnedStack } from "studio/pinned_stack"
 import { installAlpineShims } from "studio/alpine_shims"
 import { installStudioLoader } from "studio/loader"
+import "studio/in_page_links"
 
 installAlpineShims()
 startPinnedStack()

data/app/javascript/studio/carousel.js

@@ -48,8 +48,15 @@ export function perPage(clientWidth, slideWidth, gap) {
 }
 
 // The stop an arrow or a key takes the row to, held to the first and last stop.
-export function targetStop(action, current, page, count) {
+// A LOOPING row (loop: true) wraps instead: Next at the last stop goes to the
+// first, Previous at the first goes to the last. A page that would overshoot an
+// end still lands on that end first, so no slide is skipped on the way round.
+export function targetStop(action, current, page, count, loop = false) {
   const last = Math.max(0, count - 1)
+  if (loop && last > 0) {
+    if (action === "next" && current >= last) return 0
+    if (action === "prev" && current <= 0) return last
+  }
   const to = {
     prev: current - page,
     next: current + page,
@@ -60,6 +67,64 @@ export function targetStop(action, current, page, count) {
   return Math.min(last, Math.max(0, to))
 }
 
+// AUTOPLAY (the partial's autoplay:, data-carousel-autoplay): the row moves one
+// stop each interval, never while a reason holds it still.
+
+// The interval in seconds from the attribute, or null for no autoplay.
+export function autoplaySeconds(value) {
+  if (value === null || value === undefined || value === "") return null
+  const seconds = Number(value)
+  return Number.isFinite(seconds) && seconds > 0 ? seconds : null
+}
+
+// The stop autoplay moves to from `current`: the next one, round to the first
+// on a looping row. Null where it has nowhere to go: the last stop of a row that
+// does not loop (autoplay stops there), or a row with one stop.
+export function autoplayStop(current, count, loop = false) {
+  if (!(count > 1)) return null
+  if (current < count - 1) return current + 1
+  return loop ? 0 : null
+}
+
+// What holds autoplay still. "stopped" is the reader's own pause button (and
+// reduced motion, which starts the row stopped); it alone shows the play icon.
+// The rest lift on their own: the pointer leaves, focus leaves, the tab shows,
+// the row scrolls back into view, the reader stops touching it.
+export const PAUSE_REASONS = ["stopped", "hover", "focus", "hidden", "offscreen", "interaction"]
+
+// The reasons with one set or lifted. A new Set: the old one is left alone.
+export function withReason(reasons, reason, on) {
+  const next = new Set(reasons)
+  if (on) next.add(reason)
+  else next.delete(reason)
+  return next
+}
+
+// The reasons a row starts with: stopped under reduced motion, hidden in a
+// hidden tab.
+export function initialReasons({ reducedMotion = false, hidden = false } = {}) {
+  const reasons = new Set()
+  if (reducedMotion) reasons.add("stopped")
+  if (hidden) reasons.add("hidden")
+  return reasons
+}
+
+// Whether autoplay runs: it is on and nothing holds it.
+export function autoplayRunning(seconds, reasons) {
+  return seconds !== null && seconds > 0 && reasons.size === 0
+}
+
+// How long after the reader's last swipe, scroll or press autoplay waits to
+// resume: one interval, and never under five seconds.
+export function idleDelay(seconds) {
+  return Math.max(5000, (seconds || 0) * 1000)
+}
+
+// The pause button's name, from whether the reader has stopped the row.
+export function toggleLabel(stopped) {
+  return stopped ? "Play slideshow" : "Pause slideshow"
+}
+
 // Keys inside these belong to the element, not the row: a form field, and a widget
 // that moves its own selection with the arrow keys.
 export const KEY_OWNERS = [
@@ -97,3 +162,11 @@ export function centerStops(slides, clientWidth, max) {
   if (slides.length === 0) return [0]
   return slides.map(({ left, width }) => Math.min(max, Math.max(0, left + width / 2 - clientWidth / 2)))
 }
+
+// The stop a row opens on, from the partial's start index: a standard row with
+// more slides than stops opens at its last stop.
+export function startStop(start, count) {
+  if (!(count > 0)) return 0
+  const index = Math.floor(Number(start)) || 0
+  return Math.min(count - 1, Math.max(0, index))
+}