studio-engine 0.131.0 → 0.133.0

data/app/javascript/studio/in_page_links.js

@@ -0,0 +1,308 @@
+// studio/in_page_links: a link to a place on the page the reader is on scrolls there. It
+// does not load the page again (docs/PAGE_HEADER.md, "In-page links").
+//
+// Alex McRitchie, 2026-11-06, on the style guide's section pills: "The system needs to
+// understand when a scroll down is the solution rather than a page change."
+//
+// WHY THE ENGINE HAS TO DO THIS. Turbo 8 does not treat a link to "#section" on the same
+// path as a jump: its Navigator.locationWithActionIsSamePage returns false, so the click is a
+// full Turbo visit. It fetches the page, renders it again, fires turbo:visit (the loader and
+// the page transition hear it) and lands with a cut. That reads as a page load.
+//
+// So a plain click on a link whose address is this page (origin, path and query) with a
+// #fragment whose element exists is taken here: no visit, a smooth scroll to the element
+// under the pinned stack, the fragment pushed onto history, and focus moved to the target.
+// Reduced motion jumps. Every other link is left alone, for Turbo or the browser.
+//
+// THE LISTENER BUBBLES, ON THE DOCUMENT. Turbo follows a link from a bubble listener on the
+// window, which runs after this one and skips a click whose default is prevented. A
+// component's own handler on the link (a tab that switches a panel by its hash, an Alpine
+// @click.prevent) runs before this one, so a click it took is never taken here.
+//
+// BACK. Turbo turns history's scroll restoration to "manual", and on a popstate with Turbo's
+// state it starts a restore visit: a second page load. So an entry this module pushed carries
+// Turbo's own state, with the same restoration id, and a popstate between two entries of the
+// page on screen is taken here first (capture, at the window) and scrolls to the place the
+// reader left. A popstate to the page from another page is Turbo's, as before.
+//
+// It imports nothing; test/javascript/in_page_links.test.mjs loads it as a data: module.
+
+// The event a link's own controller hears: the scroll began, and where it is going.
+// detail: { link, target, hash }. It bubbles from the link.
+export const SCROLL_EVENT = "studio:in-page-scroll"
+// The scroll this module started has settled, or the reader took over. On the document.
+export const SCROLL_END_EVENT = "studio:in-page-scroll-end"
+// The state key on a history entry this module wrote: { scrollY } where the reader was.
+export const STATE_KEY = "studioInPage"
+// The mark on a target that took tabindex=-1 for focus here; engine.css draws no ring on it.
+export const FOCUS_MARK = "data-in-page-focus"
+// No scroll for this long ends the scroll, where the browser has no scrollend event.
+export const SETTLE_MS = 150
+// A scroll the reader never sees move still ends: the cap for a scroll that never starts.
+export const START_CAP_MS = 400
+// A scroll aims again at a target that moved more than this, at most this many times.
+export const AIM_SLACK_PX = 2
+export const MAX_AIMS = 6
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"
+const FOCUSABLE = "a[href], area[href], button, input, select, textarea, summary, iframe, [contenteditable], [tabindex]"
+
+// The fragment of `href` when it points into the page at `here`: same origin, path and query,
+// and a fragment that names something. Decoded, as the browser looks it up. Else null.
+export function samePageFragment(href, here) {
+  if (!href || !here) return null
+  let url, page
+  try {
+    page = new URL(here)
+    url = new URL(href, page)
+  } catch {
+    return null
+  }
+  if (url.origin !== page.origin || url.pathname !== page.pathname || url.search !== page.search) return null
+  if (url.hash.length < 2) return null
+  const raw = url.hash.slice(1)
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+// A click the browser would follow in place: the main button, no modifier, not already taken.
+export function plainClick(event) {
+  if (!event || event.defaultPrevented) return false
+  if (event.button !== undefined && event.button !== 0) return false
+  return !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+}
+
+// A link that asks for something other than a jump in this window: a new window or frame, a
+// download, Turbo off, a method or stream link, or a named Turbo frame.
+export function linkOptsOut(link) {
+  const target = link.getAttribute("target")
+  if (target && target.toLowerCase() !== "_self") return true
+  if (link.hasAttribute("download")) return true
+  if (link.hasAttribute("data-turbo-method") || link.hasAttribute("data-method")) return true
+  if (link.hasAttribute("data-turbo-stream")) return true
+  const frame = link.getAttribute("data-turbo-frame")
+  if (frame && frame !== "_top") return true
+  const drive = link.closest ? link.closest("[data-turbo]") : null
+  return !!drive && drive.getAttribute("data-turbo") === "false"
+}
+
+// The element a fragment names: its id, else an <a name>, as the browser finds it.
+export function findTarget(doc, fragment) {
+  if (!fragment) return null
+  const byId = doc.getElementById(fragment)
+  if (byId) return byId
+  const named = doc.getElementsByName ? [...doc.getElementsByName(fragment)] : []
+  return named.find((el) => el.tagName === "A") || null
+}
+
+// THE DECISION: the target to scroll to for this click on this link, or null to leave it.
+export function inPageTarget(event, link, doc, here) {
+  if (!link || !plainClick(event) || linkOptsOut(link)) return null
+  const fragment = samePageFragment(link.getAttribute("href"), here)
+  return fragment === null ? null : findTarget(doc, fragment)
+}
+
+// The history state for the entry a jump pushes. It keeps Turbo's restoration id, so a
+// restore from another page finds this page's snapshot, and moves its index one on.
+export function pushedState(current) {
+  const turbo = current && current.turbo
+  if (!turbo) return { [STATE_KEY]: {} }
+  return { turbo: { ...turbo, restorationIndex: (turbo.restorationIndex || 0) + 1 }, [STATE_KEY]: {} }
+}
+
+// Whether a popstate moves between two entries of the page on screen: the same address,
+// bar the fragment, and, under Turbo, the same restoration id as the page Turbo shows.
+export function samePagePop(state, shownId, url, shownUrl) {
+  if (!sameDocumentAddress(url, shownUrl)) return false
+  const turbo = state && state.turbo
+  if (!turbo) return !!(state && state[STATE_KEY])
+  return !!shownId && turbo.restorationIdentifier === shownId
+}
+
+export function sameDocumentAddress(a, b) {
+  try {
+    const one = new URL(a)
+    const two = new URL(b)
+    return one.origin === two.origin && one.pathname === two.pathname && one.search === two.search
+  } catch {
+    return false
+  }
+}
+
+// How far above the target the scroll stops. Its own scroll-margin-top first: the engine's
+// section-target and section-subtarget already know the stack. Without one, the bottom of the
+// pinned stack, measured now, so the target never lands under the chrome.
+export function marginFor(declared, stackBottom) {
+  if (declared > 0) return null
+  return stackBottom > 0 ? Math.round(stackBottom) : null
+}
+
+function focusTarget(target) {
+  if (!target.matches(FOCUSABLE)) {
+    target.setAttribute("tabindex", "-1")
+    target.setAttribute(FOCUS_MARK, "")
+    target.addEventListener("blur", () => {
+      target.removeAttribute("tabindex")
+      target.removeAttribute(FOCUS_MARK)
+    }, { once: true })
+  }
+  try {
+    target.focus({ preventScroll: true })
+  } catch {
+    // An element that cannot take focus leaves it where it was.
+  }
+}
+
+let installed = false
+
+export function installInPageLinks(doc) {
+  if (installed || !doc || !doc.defaultView) return false
+  installed = true
+  const win = doc.defaultView
+  let shownUrl = win.location.href
+  let settling = null
+
+  const turboHistory = () => (win.Turbo && win.Turbo.session && win.Turbo.session.history) || null
+  const shownId = () => {
+    const history = turboHistory()
+    if (history && history.restorationIdentifier) return history.restorationIdentifier
+    const state = win.history.state
+    return (state && state.turbo && state.turbo.restorationIdentifier) || null
+  }
+  const reduced = () => !!(win.matchMedia && win.matchMedia(REDUCED_MOTION).matches)
+
+  const scrollTo = (target, behavior) => {
+    const declared = parseFloat(win.getComputedStyle(target).scrollMarginTop) || 0
+    const stack = win.studioPinnedStack && win.studioPinnedStack.bottom ? win.studioPinnedStack.bottom() : 0
+    const margin = marginFor(declared, stack)
+    const inline = target.style.scrollMarginTop
+    if (margin !== null) target.style.scrollMarginTop = `${margin}px`
+    target.scrollIntoView({ behavior, block: "start" })
+    if (margin !== null) target.style.scrollMarginTop = inline
+  }
+  const pageTop = (target) => target.getBoundingClientRect().top + win.scrollY
+
+  // One jump, from its start to its end. The browser fixes a smooth scroll's end where the
+  // target was at the start. Content that grows on the way (a lazy frame the scroll passes,
+  // the navbar's collapse) moves the target, so the scroll aims again, up to MAX_AIMS times,
+  // until the reader takes over (a wheel, a touch, a key, a press). The end is the browser's
+  // scrollend where it has one, a quiet spell where not; then the end event, once.
+  const jump = (target, behavior) => {
+    if (settling) settling()
+    let quiet = null
+    let cap = null
+    let aims = 0
+    let reader = false
+    let live = true
+    let aimed = pageTop(target)
+    const takeOver = () => { reader = true }
+    const INPUTS = ["wheel", "touchstart", "keydown", "pointerdown"]
+    const reaim = () => {
+      if (reader || aims >= MAX_AIMS || Math.abs(pageTop(target) - aimed) <= AIM_SLACK_PX) return false
+      aims += 1
+      scrollTo(target, behavior)
+      aimed = pageTop(target)
+      return true
+    }
+    const wait = (ms) => {
+      win.clearTimeout(quiet)
+      quiet = win.setTimeout(end, ms)
+    }
+    const end = () => {
+      if (!live) return
+      // The target moved after the scroll stopped: aim once more and wait for that end.
+      if (reaim()) return wait(START_CAP_MS)
+      win.removeEventListener("scroll", onScroll)
+      win.removeEventListener("scrollend", end)
+      for (const name of INPUTS) win.removeEventListener(name, takeOver, true)
+      win.clearTimeout(quiet)
+      win.clearTimeout(cap)
+      live = false
+      if (settling === stop) settling = null
+      doc.dispatchEvent(new win.CustomEvent(SCROLL_END_EVENT))
+    }
+    const onScroll = () => {
+      win.clearTimeout(cap)
+      reaim()
+      wait(SETTLE_MS)
+    }
+    const stop = () => {
+      reader = true
+      end()
+    }
+    settling = stop
+    win.addEventListener("scroll", onScroll, { passive: true })
+    if ("onscrollend" in win) win.addEventListener("scrollend", end)
+    for (const name of INPUTS) win.addEventListener(name, takeOver, { capture: true, passive: true })
+    cap = win.setTimeout(end, START_CAP_MS)
+    scrollTo(target, behavior)
+    aimed = pageTop(target)
+  }
+
+  doc.addEventListener("click", (event) => {
+    const link = event.target && event.target.closest ? event.target.closest("a[href]") : null
+    const target = inPageTarget(event, link, doc, win.location.href)
+    if (!target) return
+    event.preventDefault()
+
+    const oldURL = win.location.href
+    const href = new URL(link.getAttribute("href"), oldURL).href
+    const behavior = reduced() ? "instant" : "smooth"
+    if (href !== oldURL) {
+      // The entry the reader leaves keeps where they were, for Back.
+      win.history.replaceState({ ...(win.history.state || {}), [STATE_KEY]: { scrollY: win.scrollY } }, "", oldURL)
+      const state = pushedState(win.history.state)
+      win.history.pushState(state, "", href)
+      const history = turboHistory()
+      if (history && state.turbo) {
+        history.currentIndex = state.turbo.restorationIndex
+        history.location = new URL(href)
+      }
+    }
+    shownUrl = win.location.href
+
+    // A scroll still running from an earlier click ends first, so its end cannot release this one.
+    if (settling) settling()
+    link.dispatchEvent(new win.CustomEvent(SCROLL_EVENT, { bubbles: true, detail: { link, target, hash: new URL(href).hash } }))
+    jump(target, behavior)
+    focusTarget(target)
+    if (href !== oldURL) win.dispatchEvent(new win.HashChangeEvent("hashchange", { oldURL, newURL: href }))
+  })
+
+  // Capture at the window runs ahead of Turbo's own popstate listener there.
+  win.addEventListener("popstate", (event) => {
+    const url = win.location.href
+    if (!samePagePop(event.state, shownId(), url, shownUrl)) {
+      shownUrl = url
+      return
+    }
+    shownUrl = url
+    // Turbo would start a restore visit; without Turbo the browser restores the scroll itself.
+    if (event.state && event.state.turbo) {
+      event.stopImmediatePropagation()
+      const history = turboHistory()
+      if (history) {
+        history.location = new URL(url)
+        history.currentIndex = event.state.turbo.restorationIndex
+      }
+    }
+    if (win.history.scrollRestoration !== "manual") return
+    const saved = event.state && event.state[STATE_KEY]
+    if (saved && typeof saved.scrollY === "number") {
+      win.scrollTo({ top: saved.scrollY, behavior: "instant" })
+      return
+    }
+    const fragment = samePageFragment(url, url)
+    const target = findTarget(doc, fragment)
+    if (target) scrollTo(target, "instant")
+    else if (!fragment) win.scrollTo({ top: 0, behavior: "instant" })
+  }, { capture: true })
+
+  // A Turbo visit shows another page, or this one anew.
+  doc.addEventListener("turbo:load", () => { shownUrl = win.location.href })
+  return true
+}
+
+if (typeof document !== "undefined") installInPageLinks(document)

data/app/javascript/studio/page_header.js

@@ -29,3 +29,20 @@ export function revealBy(box, tab, margin = 32) {
   if (tab.right > box.right) return tab.right - box.right + margin
   return 0
 }
+
+// Where the quick-links list goes when the browser has no anchor positioning: under the
+// button, its right edge on the button's, and kept on the screen with a gap of `gap`. It
+// opens above the button when there is no room below and more room above. Fixed
+// coordinates, as the list is a popover in the top layer.
+export function menuPlacement(button, list, viewport, gap = 8) {
+  const below = viewport.height - button.bottom
+  const above = button.top
+  const top = below < list.height + gap && above > below
+    ? Math.max(gap, button.top - list.height - 4)
+    : button.bottom + 4
+  const left = Math.min(
+    Math.max(gap, button.right - list.width),
+    Math.max(gap, viewport.width - list.width - gap)
+  )
+  return { top, left }
+}

data/app/views/studio/_carousel.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil) %>
+<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil, autoplay: nil, loop: false) %>
 <%# THE CAROUSEL: one sideways row of slides, the apps' standard for a set too
     long to grid. Render it as a layout, so each slide is your own block:
 
@@ -21,8 +21,27 @@
       style        :standard (slides snap to the start) or :spotlight (the
                    centred slide is full size and colour, its neighbours smaller,
                    faded and grey, and the arrows and keys move one slide).
-      caption      a callable that writes a line under a slide from its item.
-                   The spotlight shows it under the centred slide only.
+      caption      a callable that writes a line under a slide from its item. A
+                   standard row shows a small line under every slide; the
+                   spotlight shows it under the centred slide only.
+      start        the slide the row opens on: an index from 0, or :middle (the
+                   slide at items.size / 2). Defaults to :middle for the spotlight,
+                   so both halves of the row hold a slide at load, and to 0 for a
+                   standard row. The browser sets it before the first paint where
+                   it has scroll-initial-target; elsewhere the controller sets it
+                   when it connects, with no glide and nothing announced. A link
+                   to an id inside the row (#fragment) wins over the start.
+      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 once.
+      autoplay     seconds between moves (a number above 0); nil, the default, is
+                   off. The row moves one slide each interval and holds still while
+                   the pointer is over the slides, while keyboard focus is in it,
+                   while the tab is hidden or the row is off screen, and after a
+                   swipe or press until the reader leaves it alone a while. A pause
+                   button sits beside the arrows (WCAG 2.2.2). Under reduced motion
+                   the row starts stopped, and Play starts it. Without loop it
+                   stops at the last slide; Play then starts again from the first.
 
     THE SPOTLIGHT (engine.css, carousel-spotlight) snaps each slide to the centre.
     Where the browser has scroll-driven animations, each slide's own view timeline
@@ -44,7 +63,7 @@
     slide a group with aria-roledescription slide and its own label, named arrows
     that set aria-disabled at an end (not disabled, so focus stays on the arrow),
     and a polite, atomic status line that speaks only after a press that moves the
-    row. A key pressed in a form field, an arrow-key widget (a slider, a tab list,
+    row (a looping row's arrows are never disabled; autoplay never speaks). A key pressed in a form field, an arrow-key widget (a slider, a tab list,
     a listbox...) or a nested carousel stays that element's. %>
 <%
   per_view = per_view.to_f.clamp(1, 6)
@@ -56,13 +75,28 @@
               when "spotlight" then true
               else raise ArgumentError, "studio/carousel style: #{style.inspect} is not :standard or :spotlight"
               end
+  start = spotlight ? :middle : 0 if start.nil?
+  start_index = case start
+                when :middle, "middle" then total / 2
+                when Integer then start.clamp(0, [total - 1, 0].max)
+                else raise ArgumentError, "studio/carousel start: #{start.inspect} is not an index or :middle"
+                end
+  autoplay = nil if autoplay == false
+  unless autoplay.nil? || (autoplay.is_a?(Numeric) && autoplay.positive? && autoplay.finite?)
+    raise ArgumentError, "studio/carousel autoplay: #{autoplay.inspect} is not a number of seconds above 0 or nil"
+  end
+  autoplay = autoplay.to_i if autoplay && autoplay == autoplay.floor
+  loop = loop ? true : false
+  wraps = loop && total > 1
+  arrow_noun = spotlight ? "slide" : "slides"
   track_id = id.presence || "carousel-#{label.to_s.parameterize.presence || 'slides'}"
 %>
 <%= tag.section(class: ["carousel", ("carousel-spotlight" if spotlight), class_name].compact.join(" "),
       role: "region",
       aria: { roledescription: "carousel", label: label },
       style: "--carousel-per-view: #{per_view}",
-      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key" }.merge(data)) do %>
+      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key", carousel_start: (start_index.to_s if start_index.positive?),
+              carousel_autoplay: (autoplay.to_s if autoplay), carousel_loop: ("" if loop) }.compact.merge(data)) do %>
   <%# The track takes focus for the keys, so it carries a name: a group, since a
       bare div may not be named. %>
   <div id="<%= track_id %>" class="carousel-track" tabindex="0" role="group"
@@ -70,25 +104,34 @@
     <% items.each_with_index do |item, index| %>
       <div class="carousel-slide" role="group" aria-roledescription="slide"
            aria-label="<%= slide_label ? slide_label.call(item) : "#{index + 1} of #{total}" %>"
-           data-carousel-target="slide"><% if spotlight %><div class="carousel-spotlight-body"><%= yield(item) %></div><% else %><%= yield(item) %><% end %><% if caption %><div class="carousel-caption"><%= caption.call(item) %></div><% end %></div>
+           data-carousel-target="slide"<%= ' data-carousel-start-slide'.html_safe if start_index.positive? && index == start_index %><%= ' data-current'.html_safe if spotlight && index == start_index %>><% if spotlight %><div class="carousel-spotlight-body"><%= yield(item) %></div><% else %><%= yield(item) %><% end %><% if caption %><div class="carousel-caption"><%= caption.call(item) %></div><% end %></div>
     <% end %>
   </div>
   <div class="carousel-controls">
     <div class="carousel-dots" role="group" aria-label="Choose a slide">
       <% total.times do |index| %>
         <button type="button" class="carousel-dot" aria-label="Go to slide <%= index + 1 %>"
-                aria-controls="<%= track_id %>"<%= ' aria-current="true"'.html_safe if index.zero? %>
+                aria-controls="<%= track_id %>"<%= ' aria-current="true"'.html_safe if index == start_index %>
                 data-carousel-target="dot" data-carousel-index="<%= index %>"
                 data-studio-action="click->carousel#goTo"></button>
       <% end %>
     </div>
     <div class="carousel-arrows">
-      <button type="button" class="carousel-button" aria-label="Previous slides" aria-controls="<%= track_id %>"
-              aria-disabled="true" data-carousel-target="prev" data-studio-action="click->carousel#prev">
+      <% if autoplay %>
+        <%# The pause button (WCAG 2.2.2). The controller renames it "Play slideshow"
+            and swaps the icon when the reader stops the row. %>
+        <button type="button" class="carousel-button carousel-autoplay" aria-label="Pause slideshow" aria-controls="<%= track_id %>"
+                data-carousel-target="toggle" data-studio-action="click->carousel#toggle">
+          <svg class="carousel-autoplay-pause" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><rect x="5.5" y="4.5" width="3" height="11" rx="1"/><rect x="11.5" y="4.5" width="3" height="11" rx="1"/></svg>
+          <svg class="carousel-autoplay-play" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M7 4.8v10.4a.8.8 0 0 0 1.2.7l8.2-5.2a.8.8 0 0 0 0-1.4L8.2 4.1A.8.8 0 0 0 7 4.8Z"/></svg>
+        </button>
+      <% end %>
+      <button type="button" class="carousel-button" aria-label="Previous <%= arrow_noun %>" aria-controls="<%= track_id %>"
+              aria-disabled="<%= !wraps && start_index.zero? %>" data-carousel-target="prev" data-studio-action="click->carousel#prev">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12.5 15 7.5 10l5-5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
-      <button type="button" class="carousel-button" aria-label="Next slides" aria-controls="<%= track_id %>"
-              data-carousel-target="next" data-studio-action="click->carousel#next">
+      <button type="button" class="carousel-button" aria-label="Next <%= arrow_noun %>" aria-controls="<%= track_id %>"
+              <%= 'aria-disabled="true" '.html_safe if !wraps && total.positive? && start_index == total - 1 %>data-carousel-target="next" data-studio-action="click->carousel#next">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m7.5 5 5 5-5 5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
     </div>

data/app/views/studio/_page_header.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (title:, crumbs: [], crumb_label: nil, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, links: [], links_label: "More links", data: {}, row_class: "-mx-4 px-4") %>
+<%# locals: (title:, crumbs: [], crumb_label: nil, meta: nil, meta_title: nil, label: nil, tabs: [], anchors: [], tabs_data: {}, menu: [], menu_label: "Links", action: nil, tools_html: nil, actions_html: nil, links: [], links_label: "More links", data: {}, row_class: "-mx-4 px-4") %>
 <%# THE PAGE HEADER: the second layer of the pinned stack (docs/PAGE_HEADER.md).
     navbar, then this row, then a section's header (studio/_section_header), then a
     table's sticky header, each below the last.
@@ -19,12 +19,25 @@
       meta          short text beside the title, such as the version. Hidden on a
                     phone, where the tabs need the width.
       meta_title    the meta's title attribute.
-      label         the tabs' nav's accessible name. A row with tabs needs it.
-      tabs          [{ label:, href:, current:, data: }]. `current` is the
-                    aria-current value ("page" or "true"), and blank on the others.
-      tabs_data     data attributes for the tabs' scroller.
-      actions_html  a control on the right, such as the page's one primary action.
-                    After the tabs, when the row has both.
+      label         the pill group's nav's accessible name. A row with tabs or
+                    anchors needs it.
+
+    THE FOUR KINDS OF CONTROL on the right (docs/PAGE_HEADER.md, "The four kinds of
+    control"), always in this order and at the one height of .btn-sm:
+
+      tabs          views of the same thing (Deployments | Triage), [{ label:, href:,
+                    current:, data: }]. One pill group with the gliding pill. `current`
+                    is the aria-current value ("page" or "true"), blank on the others.
+      anchors       sections of this page, [{ label:, href: "#id", current:, data: }].
+                    The same pill group; a same-page link scrolls, with no visit. A row
+                    takes tabs or anchors, never both: it has one pill group.
+      tabs_data     data attributes for the pill group's scroller.
+      menu          related pages elsewhere, [{ label:, href:, data: }]: one neutral
+                    button, menu_label ("Links"), that opens a list of them.
+      action        the page's one primary action, { label:, href:, data: }. Rightmost.
+      tools_html    local-only and dev controls, after the action, muted.
+      actions_html  DEPRECATED: free HTML after the pill group. It renders for one
+                    release and warns once per call site in development.
       links         the page's other links, [{ label:, href:, current: }], on a line of
                     their own at the foot of the row, so they stick with it.
       links_label   that line's accessible name.
@@ -79,13 +92,16 @@
       <p class="page-header-meta label-upper"<%= %( title="#{ERB::Util.h(meta_title)}").html_safe if meta_title.present? %>><%= meta %></p>
     <% end %>
   </div>
-  <% if tabs.any? %>
-    <%= tag.nav(class: "page-header-tabs", aria: { label: label.presence }, data: tabs_data) do %>
+  <% raise ArgumentError, "studio/_page_header takes tabs: or anchors:, not both (one pill group)" if tabs.any? && anchors.any? %>
+  <% raise ArgumentError, "studio/_page_header takes one action: a Hash { label:, href: }" unless action.nil? || action.is_a?(Hash) %>
+  <% pills, pill_kind = tabs.any? ? [tabs, "tabs"] : [anchors, "anchors"] %>
+  <% if pills.any? %>
+    <%= tag.nav(class: "page-header-tabs", aria: { label: label.presence }, data: { page_header_kind: pill_kind }.merge(tabs_data)) do %>
       <%# The glide: one pill, drawn once, that CSS anchors to the tab with aria-current and
           slides from tab to tab (engine.css, "The gliding pill"). Each tab keeps its own
           fill where the browser has no anchor positioning. %>
       <div class="page-header-track">
-        <% tabs.each do |tab| %>
+        <% pills.each do |tab| %>
           <%= link_to tab.fetch(:href),
                 class: "page-header-tab btn btn-sm #{tab[:current].present? ? 'btn-primary' : 'btn-neutral'}",
                 aria: { current: tab[:current].presence },
@@ -95,8 +111,44 @@
       </div>
     <% end %>
   <% end %>
-  <% if actions_html.present? %>
-    <div class="page-header-actions"><%= actions_html %></div>
+  <% if actions_html.present? && defined?(Studio::PageHeader) && Studio::PageHeader.warning_enabled? %>
+    <% site = caller_locations.find { |loc| loc.path.to_s.end_with?(".erb") && !loc.path.to_s.end_with?("_page_header.html.erb") } %>
+    <% Studio::PageHeader.deprecate_actions_html(site: site && "#{site.path}:#{site.lineno}") %>
+  <% end %>
+  <% if [actions_html, tools_html].any?(&:present?) || menu.any? || action.present? %>
+    <%# One cluster, in the fixed order: the old free HTML where it always stood, then
+        the menu, then the action, then the tools. Each control is .btn-sm, so all
+        four kinds share one height. %>
+    <div class="page-header-actions">
+      <%= actions_html if actions_html.present? %>
+      <% if menu.any? %>
+        <%# A disclosure, not role="menu": a list of links that Tab walks. The browser's
+            popover opens it from the button, closes it on Escape or a click outside,
+            and gives focus back to the button, with no script. The page-header
+            controller adds aria-expanded, and places the list where the browser has
+            no anchor positioning. %>
+        <% menu_id = "page-header-menu-#{SecureRandom.hex(4)}" %>
+        <div class="page-header-menu" data-page-header-kind="menu">
+          <button type="button" class="page-header-menu-button btn btn-sm btn-neutral"
+                  popovertarget="<%= menu_id %>" aria-controls="<%= menu_id %>"><%= menu_label %><span class="page-header-menu-caret" aria-hidden="true"></span></button>
+          <div id="<%= menu_id %>" class="page-header-menu-list" popover="auto">
+            <ul>
+              <% menu.each do |item| %>
+                <li><%= link_to item.fetch(:label), item.fetch(:href), class: "page-header-menu-item", data: item.fetch(:data, {}) %></li>
+              <% end %>
+            </ul>
+          </div>
+        </div>
+      <% end %>
+      <% if action.present? %>
+        <%= link_to action.fetch(:label), action.fetch(:href),
+              class: "page-header-action btn btn-sm btn-primary",
+              data: { page_header_kind: "action" }.merge(action.fetch(:data, {})) %>
+      <% end %>
+      <% if tools_html.present? %>
+        <div class="page-header-tools" data-page-header-kind="tools"><%= tools_html %></div>
+      <% end %>
+    </div>
   <% end %>
   <% if links.any? %>
     <nav class="page-header-links" aria-label="<%= links_label %>">