studio-engine 0.123.0 → 0.125.0

data/app/javascript/studio/controllers/page_header_controller.js

@@ -0,0 +1,60 @@
+// page-header: says when studio/_page_header is stuck, marks which ends of its
+// tabs hide a tab, and shows the open tab on a narrow screen. It sits on the row's
+// sentinel, so the row keeps its data-studio-controller for the page's own.
+//
+//   <div class="page-header-sentinel" data-studio-controller="page-header"></div>
+//   <nav class="page-header sticky" data-pin="page">...</nav>
+//
+// A lazy controller (studio/stimulus): only a page with the row fetches it. The
+// row's tabs are links, so they work without it. If it fails to load, the sentinel
+// carries data-studio-controller-failed and engine.css gives the row its bar at
+// all times, so a stuck row never lays a transparent title over the page.
+import { Controller } from "@hotwired/stimulus"
+import { hiddenEnds, isStuck, revealBy } from "studio/page_header"
+
+export default class extends Controller {
+  connect() {
+    this.row = this.element.nextElementSibling
+    if (!this.row) return
+    this.tabs = this.row.querySelector(".page-header-tabs")
+    this.schedule = this.schedule.bind(this)
+    window.addEventListener("scroll", this.schedule, { passive: true })
+    window.addEventListener("resize", this.schedule, { passive: true })
+    this.tabs?.addEventListener("scroll", this.schedule, { passive: true })
+    this.revealOpenTab()
+    this.sync()
+  }
+
+  disconnect() {
+    window.removeEventListener("scroll", this.schedule)
+    window.removeEventListener("resize", this.schedule)
+    this.tabs?.removeEventListener("scroll", this.schedule)
+    if (this.frame) cancelAnimationFrame(this.frame)
+    this.frame = null
+  }
+
+  schedule() {
+    if (this.frame) return
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null
+      this.sync()
+    })
+  }
+
+  sync() {
+    const stuck = isStuck(this.row.getBoundingClientRect().top, this.element.getBoundingClientRect().top)
+    const ends = this.tabs ? hiddenEnds(this.tabs) : null
+
+    this.row.toggleAttribute("data-stuck", stuck)
+    if (!ends) return
+    this.tabs.toggleAttribute("data-fade-start", ends.start)
+    this.tabs.toggleAttribute("data-fade-end", ends.end)
+  }
+
+  // Moves the tabs only: scrollIntoView would also move the page.
+  revealOpenTab() {
+    const open = this.tabs?.querySelector("[aria-current]")
+    if (!open) return
+    this.tabs.scrollLeft += revealBy(this.tabs.getBoundingClientRect(), open.getBoundingClientRect())
+  }
+}

data/app/javascript/studio/page_header.js

@@ -0,0 +1,24 @@
+// studio/page_header: the page header's two measurements, as pure functions. It
+// imports nothing; test/javascript/page_header.test.mjs loads it as a data: module.
+
+// A sticky row is stuck once it has left its place in the flow. restTop is that
+// place, measured by the sentinel beside it. The half pixel is rounding: at rest
+// the two tops differ by a fraction at most, and a stuck row by at least a pixel.
+export function isStuck(rowTop, restTop) {
+  return rowTop - restTop > 0.5
+}
+
+// Which ends of the tabs hide a tab, so a fade marks only an end with more to see.
+export function hiddenEnds({ scrollLeft, clientWidth, scrollWidth }) {
+  return {
+    start: scrollLeft > 1,
+    end: scrollLeft + clientWidth < scrollWidth - 1
+  }
+}
+
+// How far the tabs must scroll to show a tab, clear of the fade. 0 if it shows.
+export function revealBy(box, tab, margin = 32) {
+  if (tab.left < box.left) return tab.left - box.left - margin
+  if (tab.right > box.right) return tab.right - box.right + margin
+  return 0
+}

data/app/javascript/studio/page_transitions.js

@@ -0,0 +1,263 @@
+// studio/page_transitions: the app-to-app page transition (Studio.page_transition_direction,
+// docs/PAGE_TRANSITIONS.md). Loaded by its own tag in layouts/studio/_head, only with the
+// setting on. It names a style on <html>, and engine.css draws it. It imports nothing.
+//
+// Turbo calls document.startViewTransition BEFORE turbo:before-render, and the browser takes
+// the old page's picture before Turbo's callback runs. So what the old picture holds is
+// settled ahead of the visit: the held banner stack and the morph names are decided here on
+// turbo:visit and from the response, never first at before-render.
+//
+// A full load is the other path to the same look. The new document draws the motion, so the old
+// one only plans it: at pageswap it names what it holds, draws the style here, and leaves it for
+// studio/page_transition_reveal, the classic script that applies it at pagereveal.
+//
+// The effects are from the Codrops Page Transitions demo; the keyframes were written fresh.
+
+export const DIRECTIONS = Object.freeze({
+  left: Object.freeze(["fade-left", "unfold-right"]),
+  right: Object.freeze(["fade-right", "unfold-left"]),
+  top: Object.freeze(["fade-top", "unfold-bottom"]),
+  bottom: Object.freeze(["fade-bottom", "unfold-top"]),
+})
+
+// A same-page visit (a refresh, a poll, the second half of a redirect): the transition still
+// runs, and draws nothing.
+export const STILL = "still"
+export const READY_CAP_MS = 500
+// Read by app/assets/javascripts/studio/page_transition_reveal.js too.
+export const FULL_LOAD_STYLE_KEY = "studio-page-transition-style"
+const MAX_READY_IMAGES = 12
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"
+
+export function pickStyle(direction, random = Math.random) {
+  if (!Object.hasOwn(DIRECTIONS, direction)) return null
+  const pair = DIRECTIONS[direction]
+  return pair[Math.floor(random() * pair.length)]
+}
+
+// The style for one visit, STILL, or null to leave the swap alone (the engine's fade plays,
+// and a morph between two pages stands). An advance visit to the same path can bring a new
+// page, as a launch panel does when it gives way to the chat at its own address, so a name
+// the two share still morphs. A refresh replaces, and stays silent.
+export function planVisit({ direction, from, to, transitions, sharedName, advance }, random = Math.random) {
+  if (!transitions || !from || !to || !Object.hasOwn(DIRECTIONS, direction)) return null
+  if (from === to) return advance && sharedName ? null : STILL
+  return sharedName ? null : pickStyle(direction, random)
+}
+
+// The style a full load should play, or null for a plain load: planVisit's own rule, so the
+// two paths cannot differ. No morph, since the old page cannot read the new page's names
+// before its picture, and a browser with no activation entry has nothing to compare.
+export function planFullLoad({ direction, from, activation }, random = Math.random) {
+  const url = activation && activation.entry && activation.entry.url
+  if (!url) return null
+  const to = new URL(url).pathname
+  const style = planVisit({ direction, from, to, transitions: true, sharedName: false }, random)
+  return style === STILL ? null : style
+}
+
+// Hands the style to the next document. Storage can refuse, and then the load is plain.
+export function leaveStyle(win, style) {
+  try {
+    if (style) win.sessionStorage.setItem(FULL_LOAD_STYLE_KEY, style)
+    else win.sessionStorage.removeItem(FULL_LOAD_STYLE_KEY)
+    return !!style
+  } catch {
+    return false
+  }
+}
+
+// A slow image must not hold a click: past the cap the swap goes ahead.
+export function withCap(promise, ms, timer = setTimeout) {
+  return Promise.race([promise, new Promise((done) => timer(done, ms))])
+}
+
+export function morphNames(root) {
+  return new Set([...root.querySelectorAll("[data-vt-morph]")].map((el) => el.getAttribute("data-vt-morph")))
+}
+
+export function shareName(here, there) {
+  return !!there && [...here].some((name) => there.has(name))
+}
+
+// Exactly one element takes the stack's view-transition name, however many a page renders:
+// a duplicate name silently cancels the whole transition.
+export function markHeld(root) {
+  const stack = root.querySelector(".studio-bar-stack")
+  if (stack) stack.setAttribute("data-vt-held", "")
+}
+
+export function eagerImages(body) {
+  return [...body.querySelectorAll("img")]
+    .filter((img) => img.getAttribute("loading") !== "lazy" && (img.getAttribute("src") || img.getAttribute("srcset")))
+    .slice(0, MAX_READY_IMAGES)
+}
+
+// The incoming body is inert, so each image is copied here to load, <picture> and all, so
+// the browser chooses the same source. Marked decoding=sync, the real one paints at once.
+function loadImage(doc, img) {
+  img.decoding = "sync"
+  const source = img.closest("picture") || img
+  const copy = doc.importNode(source, true)
+  const loader = copy.tagName === "IMG" ? copy : copy.querySelector("img")
+  return loader.decode().catch(() => {})
+}
+
+function readyForSwap(doc, body) {
+  const fonts = doc.fonts ? doc.fonts.ready.catch(() => {}) : null
+  // At least one tick, so Turf's one-tick hold for its snapshot stays honest.
+  const tick = new Promise((done) => setTimeout(done, 0))
+  return Promise.all([...eagerImages(body).map((img) => loadImage(doc, img)), fonts, tick])
+}
+
+// Turbo's resume is a promise's resolve, so the FIRST caller starts the render. Another
+// listener's short hold (Turf's turbo_snapshot_cache resumes on a timeout of 0) would cut
+// this wait to nothing, so a listener that runs after this one gets a resume that does
+// nothing, and this wait releases the render. It always does: cap, failure or success.
+export function holdRender(event, wait, cap = READY_CAP_MS) {
+  const resume = event.detail && event.detail.resume
+  if (typeof resume !== "function") return false
+  event.preventDefault()
+  event.detail.resume = () => {}
+  const release = () => resume()
+  withCap(Promise.resolve().then(wait), cap).then(release, release)
+  return true
+}
+
+function readDirection(doc) {
+  const meta = doc.querySelector('meta[name="page-transition-direction"]')
+  return meta ? meta.content : null
+}
+
+let installed = false
+
+export function installPageTransitions(doc) {
+  if (installed || !readDirection(doc)) return false
+  installed = true
+
+  const win = doc.defaultView
+  const root = doc.documentElement
+  const known = new Map()
+  let from = win.location.pathname
+  let target = null
+  let advance = false
+  let rendered = false
+
+  const nameTheMorph = (shared) => {
+    if (shared) root.dataset.pageTransitionMorph = ""
+    else delete root.dataset.pageTransitionMorph
+  }
+  const predict = (names) => nameTheMorph((target !== from || advance) && shareName(morphNames(doc), names))
+
+  root.dataset.pageTransitionDirection = readDirection(doc)
+  markHeld(doc)
+  known.set(from, morphNames(doc))
+
+  doc.addEventListener("turbo:visit", (event) => {
+    root.dataset.pageTransitionVisit = ""
+    // Turbo opens its view transition before it reads turbo-visit-control. A response it will
+    // not render gets no turbo:before-render, so this stands, and that transition draws nothing.
+    // The full load after it plays the one motion. Left alone while a motion is still running.
+    if (!root.dataset.pageTransition) root.dataset.pageTransition = STILL
+    target = new URL(event.detail.url).pathname
+    // A GET that redirects: Turbo renders the response, then replaces to the final address
+    // with that same response, all before turbo:load. The page has landed, so nothing moves.
+    const action = event.detail.action
+    if (rendered && action === "replace") from = target
+    rendered = false
+    advance = action === "advance"
+    predict(known.get(target))
+  })
+
+  // A page never visited: read its names from the response, ahead of the old page's picture.
+  // Only a page with names of its own can share one, so every other page skips the parse.
+  doc.addEventListener("turbo:before-fetch-response", (event) => {
+    if (event.target && event.target.tagName === "TURBO-FRAME") return
+    if (!morphNames(doc).size) return
+    const { fetchResponse } = event.detail
+    Promise.resolve(fetchResponse.responseHTML).then((html) => {
+      if (!html) return
+      const names = morphNames(new win.DOMParser().parseFromString(html, "text/html"))
+      const path = new URL(fetchResponse.response.url).pathname
+      known.set(path, names)
+      if (target && (path === target || fetchResponse.redirected)) predict(names)
+    }).catch(() => {})
+  })
+
+  // In capture, so the hold is in place before any other listener takes Turbo's resume.
+  doc.addEventListener("turbo:before-render", (event) => {
+    const { newBody } = event.detail
+    markHeld(newBody)
+    const names = morphNames(newBody)
+    if (target) known.set(target, names)
+    const sharedName = shareName(morphNames(doc), names)
+    const style = planVisit({
+      direction: readDirection(doc),
+      from,
+      to: target,
+      transitions: !!doc.startViewTransition && !win.matchMedia(REDUCED_MOTION).matches,
+      sharedName,
+      advance,
+    })
+    nameTheMorph(sharedName && style !== STILL)
+    if (style) root.dataset.pageTransition = style
+    else delete root.dataset.pageTransition
+    if (style && style !== STILL) holdRender(event, () => readyForSwap(doc, newBody))
+  }, { capture: true })
+
+  // A refused form renders with no visit and fires no turbo:load, so only a render inside a
+  // visit counts. Otherwise the flag would outlive that render and eat the next page's move.
+  doc.addEventListener("turbo:render", () => { rendered = !!target })
+
+  // Turbo fires this after the transition has finished. With no visit, it is this document's
+  // own first load, and a full load's motion can still be playing: its script cleans up.
+  doc.addEventListener("turbo:load", () => {
+    const visited = target !== null
+    from = win.location.pathname
+    target = null
+    advance = false
+    rendered = false
+    known.set(from, morphNames(doc))
+    if (!visited) return
+    delete root.dataset.pageTransition
+    delete root.dataset.pageTransitionVisit
+    nameTheMorph(false)
+  })
+
+  // A visit that never renders: the stack must not keep its name at rest.
+  for (const name of ["turbo:fetch-request-error", "turbo:reload"]) {
+    doc.addEventListener(name, () => {
+      delete root.dataset.pageTransitionVisit
+      if (name !== "turbo:reload") delete root.dataset.pageTransition
+    })
+  }
+
+  // The last moment on the old document. The browser takes its picture after this.
+  win.addEventListener("pageswap", (event) => {
+    const transition = event.viewTransition
+    const style = transition && planFullLoad({ direction: readDirection(doc), from, activation: event.activation })
+    const left = leaveStyle(win, style)
+    if (!transition) return
+    if (!left) {
+      transition.skipTransition()
+      return
+    }
+    markHeld(doc)
+    root.dataset.pageTransitionVisit = ""
+    nameTheMorph(false)
+    // The loader settles at pagehide, which comes after the picture.
+    if (win.StudioLoader) win.StudioLoader.hide()
+  })
+
+  // Back from the back/forward cache: a visit that left by a full load is over.
+  win.addEventListener("pageshow", (event) => {
+    if (!event.persisted) return
+    from = win.location.pathname
+    target = null
+    advance = false
+    rendered = false
+  })
+  return true
+}
+
+if (typeof document !== "undefined") installPageTransitions(document)

data/app/javascript/studio/pinned_stack.js

@@ -141,6 +141,17 @@ export function measurePin(el, name, legacy, timeline) {
   return { el: el, name: name, legacy: legacy, h: el.offsetHeight - band, bottom: Math.max(0, r.bottom) };
 }
 
+// WHERE AN ADOPTED HEADER GOES: its place in the document, since order is
+// document order (composed). Appended, it read as below every layer, so a layer
+// under it (studio/_page_header) composed a top of 0 and pinned over it.
+export function documentIndex(list, el) {
+  var FOLLOWING = 4; // Node.DOCUMENT_POSITION_FOLLOWING
+  for (var i = 0; i < list.length; i++) {
+    if (el.compareDocumentPosition(list[i].el) & FOLLOWING) return i;
+  }
+  return list.length;
+}
+
 // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
 //
 // This used to build a `pins` array once and hold each element by reference
@@ -179,7 +190,7 @@ export function readStack() {
   // contest board and mcritchie-studio's heartbeat CSS all read — would
   // never publish at all. Both live consumers own their header, so it is
   // adopted as a pin even when it does not ask to be.
-  if (header && !headerPinned) list.push(measurePin(header, 'nav', true, timeline));
+  if (header && !headerPinned) list.splice(documentIndex(list, header), 0, measurePin(header, 'nav', true, timeline));
   return {
     pins: list,
     stack: timeline ? pinnedAt(list) : composed(list),

data/app/javascript/studio/stimulus.js

@@ -65,6 +65,9 @@ export const schema = {
 // says recording did not load (data-studio-controller-failed="voice-recorder").
 // So is the chat's mic: a mic whose controller failed says voice did not load,
 // and the box still types (data-studio-controller-failed="agent-chat-voice").
+// So is copy-text: a colour whose controller failed still shows its hex to select.
+// So is the page header: its tabs are links, and a row whose controller failed
+// keeps its bar at all times (data-studio-controller-failed="page-header").
 export const LAZY = {
   "board": () => import("studio/controllers/board_controller"),
   "geo-settings": () => import("studio/controllers/geo_settings_controller"),
@@ -78,7 +81,9 @@ export const LAZY = {
   "agent-chat-voice": () => import("studio/controllers/agent_chat_voice_controller"),
   "voice-profile": () => import("studio/controllers/voice_profile_controller"),
   "microphone-chip": () => import("studio/controllers/microphone_chip_controller"),
-  "voice-recorder": () => import("studio/controllers/voice_recorder_controller")
+  "voice-recorder": () => import("studio/controllers/voice_recorder_controller"),
+  "copy-text": () => import("studio/controllers/copy_text_controller"),
+  "page-header": () => import("studio/controllers/page_header_controller")
 }
 
 export const application = Application.start(document.documentElement, schema)

data/app/views/components/_link_sidebar.html.erb

@@ -6,6 +6,9 @@
     this automatically when sections are declared. %>
 <% sections = studio_sidebar_sections %>
 <% sidebar_admin = respond_to?(:admin?) && admin? %>
+<%# A signed-out visitor's panel has no title: its links say what it is. It keeps its
+    accessible name (aria_label) and its close button. %>
+<% sidebar_title = if sidebar_admin then "Admin Menu" elsif respond_to?(:logged_in?) && logged_in? then "Links" end %>
 <% close_action = "$store.sidebars.linkTreeOpen = false" %>
 
 <style>
@@ -34,7 +37,7 @@
       <% section[:links].each do |link| %>
         <% target = link[:target].presence %>
         <%= link_to link[:href],
-              class: "group flex items-start gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset transition",
+              class: "group flex #{link[:desc].present? ? "items-start" : "items-center"} gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset transition",
               target: target,
               rel: target == "_blank" ? "noopener" : nil,
               "@click": close_action do %>
@@ -113,7 +116,7 @@
 
 <%= render "components/sidebar_panel",
       id: "studio-link-sidebar",
-      title: sidebar_admin ? "Admin Menu" : "Links",
+      title: sidebar_title,
       open: "$store.sidebars.linkTreeOpen",
       body_html: body_html,
       footer_html: footer_html,
@@ -126,7 +129,7 @@
 
 <%= render "components/sidebar_panel",
       id: "studio-link-sidebar-mobile",
-      title: sidebar_admin ? "Admin Menu" : "Links",
+      title: sidebar_title,
       open: "$store.sidebars.linkTreeOpen",
       body_html: body_html,
       footer_html: footer_html,

data/app/views/components/_user_nav.html.erb

@@ -5,8 +5,8 @@
     { partial: "path", locals: { ... } } when the partial needs locals:
       balance_slot     — balance display, rendered at the start of the
                          top row (e.g. a wallet balance link)
-      extra_icons_slot — app-specific icon buttons, rendered before the
-                         admin gear + theme toggle
+      extra_icons_slot — app-specific icon buttons, rendered between the
+                         theme toggle and the admin gear
       div2_slot        — replaces the default second row (the wallet
                          address + level progress bar) entirely
                          (e.g. a seeds bar)
@@ -329,13 +329,14 @@
     <div data-nav-avatar-badge><%= studio_navbar_slot_tag(avatar_badge) %></div>
     <% end %>
   <% else %>
+    <%# The signed-in rail's order: the theme toggle, then the gear. Desktop
+        only, as above: the phone row carries the toggle below md. %>
+    <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <% if menu_trigger %>
     <span class="hidden md:block" data-nav-menu-trigger><%= studio_navbar_slot_tag(menu_trigger) %></span>
     <% else %>
     <%= render "components/admin_dropdown", display_class: "hidden md:block" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
     <% end %>
-    <%# Desktop only, as above: the phone row carries the toggle below md. %>
-    <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <div class="flex items-center gap-3 ml-auto">
       <%= link_to Studio.sign_in_label, login_path, class: "text-heading hover:text-primary text-sm font-semibold transition" %>
       <%= link_to "Sign up", signup_path, class: "btn btn-primary btn-sm" %>

data/app/views/layouts/_navbar.html.erb

@@ -23,8 +23,9 @@
     put — hosts no longer shadow this partial just to add the class. Non-preview
     branch ONLY: preview renders can repeat per page, and a duplicate
     view-transition-name silently disables every transition. With the flag off,
-    nothing extra renders. %>
-<% pin_header = Studio.smooth_load && !is_preview %>
+    nothing extra renders. Studio.page_transition_direction turns the same flag
+    on (layouts/studio/_smooth_load). %>
+<% pin_header = (Studio.smooth_load || @studio_page_transition_direction || Studio.page_transition_direction) && !is_preview %>
 <% balance_html = local_assigns.fetch(:balance_html, nil) %>
 <% extra_icons_html = local_assigns.fetch(:extra_icons_html, nil) %>
 <%# The user nav's slot locals, forwarded only when passed, so a navbar that
@@ -244,8 +245,9 @@
         <%= render "components/user_nav", balance_html: balance_html, extra_icons_html: extra_icons_html, **user_nav_slots %>
       <% else %>
         <div class="flex items-center justify-end gap-3">
-          <%= sidebar_trigger_desktop if sidebar_active %>
+          <%# The signed-in rail's order: the theme toggle, then the gear. %>
           <span class="hidden md:flex"><%= render "components/theme_toggle_morph" %></span>
+          <%= sidebar_trigger_desktop if sidebar_active %>
           <% if signed_out_cta %>
           <%# sign_in_link: false drops the quiet link (the CTA is the sign-in);
               sign_in_path points it elsewhere; modal: opens a modal from the
@@ -277,6 +279,8 @@
       <% if signed_out_cta && signed_out_cta[:sign_in_link] != false %>
       <%= link_to Studio.sign_in_label, signed_out_cta[:sign_in_path] || login_path, class: "text-xs font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
       <% end %>
+      <%# The rail's order at this width too: the theme toggle, then the gears. %>
+      <%= render "components/theme_toggle_morph" %>
       <%= render "components/link_sidebar_trigger" if sidebar_active %>
       <%# Studio.navbar_menu_trigger takes the admin dropdown's seat here too: its
           second render (the rail is the first), so the partial carries no ids. %>
@@ -286,7 +290,6 @@
       <% else %>
       <%= render "components/admin_dropdown" unless sidebar_active && studio_sidebar_replaces_admin_menu? %>
       <% end %>
-      <%= render "components/theme_toggle_morph" %>
     </span>
   </div>
 </header>

data/app/views/layouts/studio/_head.html.erb

@@ -30,7 +30,7 @@
 <%# The session-drift stamp + browser store. Renders nothing unless the controller
     includes Studio::ErrorHandling. See studio/_session_stamp.
 
-    THE ONE ENGINE SCRIPT THAT STAYS CLASSIC, AND SYNCHRONOUS. Host code
+    AN ENGINE SCRIPT THAT STAYS CLASSIC, AND SYNCHRONOUS. Host code
     registers identity sources with window.StudioSession as its own modules
     EVALUATE (turf-monster registers its identity source from a module at
     import; CHANGELOG, "Held"), and the host's entry point is the module tag
@@ -39,6 +39,14 @@
     silently be null. It becomes a module when those consumers wait for it. %>
 <%= render "studio/session_stamp" %>
 <%= render "layouts/studio/smooth_load" %>
+<%# A FULL PAGE LOAD PLAYS THE SAME TRANSITION, only with the setting on: an app without it
+    gets neither tag. The sheet carries the at-rule that takes no selector, so it cannot sit in
+    the engine's bundle. The script is classic and synchronous, the second one here, because
+    pagereveal fires before the first render, ahead of every module. docs/PAGE_TRANSITIONS.md. %>
+<% if @studio_page_transition_direction || Studio.page_transition_direction %>
+  <%= stylesheet_link_tag "studio/page_transition_full_load" %>
+  <%= javascript_include_tag "studio/page_transition_reveal", nonce: studio_script_nonce %>
+<% end %>
 <%# The favicon's URL carries its content version (Studio::PublicFileVersion),
     so a redrawn favicon is a new URL no browser has cached. %>
 <link rel="icon" type="image/png" href="<%= Studio::PublicFileVersion.path("/favicon.png") %>">
@@ -197,7 +205,8 @@
     take every bare specifier on the page down with it. The ones below that load by
     URL (type="module" with a src) are external files, not inline scripts: they
     carry no body and need no nonce under a policy that allows 'self'. The session
-    store (studio/_session_stamp, above) is the one classic script, and says why.
+    store (studio/_session_stamp, above) and the full-load script above are the two
+    classic scripts, and each says why.
     A MODULE LOADED BY URL MUST IMPORT NO BARE SPECIFIER. javascript_include_tag
     also sends a `Link: rel=modulepreload` response header, which the browser
     acts on before it parses this map, so a bare import in that module can
@@ -208,6 +217,12 @@
     controllers, the pinned stack, and the Alpine shims. A module tag, so it
     carries the nonce. %>
 <%= javascript_import_module_tag "studio/application" %>
+<%# THE PAGE TRANSITION, BY ITS OWN DOOR, only with the setting on: an app without
+    it fetches nothing and renders these bytes as before. Not in the boot graph, so
+    it is not preloaded either. Its listeners are bound before the first visit. %>
+<% if @studio_page_transition_direction || Studio.page_transition_direction %>
+  <%= javascript_import_module_tag "studio/page_transitions" %>
+<% end %>
 <%# THE STIMULUS APPLICATION, BY ITS OWN DOOR. studio/stimulus starts the engine's
     Stimulus application and registers the hold button on it. Its only imports
     are Stimulus, studio/lazy_controllers and the hold button's controller, so

data/app/views/layouts/studio/_smooth_load.html.erb

@@ -8,8 +8,17 @@
     Transition styling ships in engine.css ("Smooth-load convention" block);
     pin an app's sticky header with the .vt-pinned-header utility (exactly one
     element per page — a duplicate view-transition-name silently disables the
-    whole transition). %>
-<% if Studio.smooth_load %>
+    whole transition).
+
+    Studio.page_transition_direction is the one switch for the app-to-app page
+    transition (docs/PAGE_TRANSITIONS.md): set, it turns all of this on, whatever
+    Studio.smooth_load says. The ivar lets one request set it without writing the
+    process-wide setting (the e2e lab). %>
+<% page_transition_direction = @studio_page_transition_direction || Studio.page_transition_direction %>
+<% if Studio.smooth_load || page_transition_direction %>
   <meta name="view-transition" content="same-origin">
   <meta name="turbo-cache-control" content="no-preview">
 <% end %>
+<% if page_transition_direction %>
+  <meta name="page-transition-direction" content="<%= page_transition_direction %>">
+<% end %>

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

@@ -0,0 +1,65 @@
+<%# locals: (title:, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, data: {}, row_class: "-mx-4 px-4") %>
+<%# THE PAGE HEADER: the second layer of the triple stack (docs/PAGE_HEADER.md).
+    navbar, then this row, then a table's sticky header, each below the last.
+
+    AT REST it has no background and no border: a title on the left, tabs on the
+    right. ONCE STUCK under the navbar it takes the bar. Its box never changes
+    between the two, so a state change moves nothing and republishes nothing.
+
+      title         the page's one h1.
+      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 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, for a row with no tabs.
+      data          data attributes for the row, such as the page's own controller.
+      row_class     the bleed. The default fits a container with px-4; pass "" in a
+                    container with no gutter of its own.
+
+    NOT components/_page_header: a host's view wins over the engine's at the same
+    path, and the hub has its own with other locals.
+
+    THE ROW IS NEVER A <header>. studio/pinned_stack takes the document's first
+    <header> as the navbar, so on a page with no navbar this row would publish as
+    --nav-bottom.
+
+    IT JOINS THE STACK WITH data-pin="page" AND POSITIONS OFF --pin-page-top, the
+    bottom of everything above it. --pin-stack-bottom includes the row's own edge,
+    so a row positioned off it would chase itself down the page. Anything below,
+    such as the sticky table header's clone, sits under the row with no edit.
+
+    THE SENTINEL stays at the row's place in the flow, and the row's distance from
+    it is what "stuck" means, on every kind of header. It is absolutely positioned,
+    so a space-y parent adds nothing for it. It carries the controller, so the row
+    keeps its data-studio-controller for the page's own. So the row carries no top
+    margin: the space above it belongs to its container. %>
+<div class="page-header-sentinel" data-studio-controller="page-header" aria-hidden="true"></div>
+<%= content_tag(tabs.any? ? :nav : :div,
+      class: "page-header sticky #{row_class}".strip,
+      style: "top: var(--pin-page-top, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)",
+      aria: { label: label.presence },
+      data: data.merge(pin: "page")) do %>
+  <div class="page-header-lead">
+    <h1 class="page-header-title"><%= title %></h1>
+    <% if meta.present? %>
+      <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.div(class: "page-header-tabs", data: tabs_data) do %>
+      <div class="page-header-track">
+        <% tabs.each do |tab| %>
+          <%= link_to tab.fetch(:label), tab.fetch(:href),
+                class: "btn btn-sm #{tab[:current].present? ? 'btn-primary' : 'btn-neutral'}",
+                aria: { current: tab[:current].presence },
+                data: tab.fetch(:data, {}) %>
+        <% end %>
+      </div>
+    <% end %>
+  <% elsif actions_html.present? %>
+    <div class="page-header-actions"><%= actions_html %></div>
+  <% end %>
+<% end %>