studio-engine 0.124.0 → 0.125.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7f68b7fc8c9d951dfa0f8069db58d4d819a9e5c785a35c5319c00d1a7450fab
-  data.tar.gz: 3674ddc7b3c29a7f58e06ee8c928bf63223a52388a191f819a90919986355e79
+  metadata.gz: 13bb9cfe1f6491a4dd2a199c16f734f466edad8fb38beae903033305e8fd91da
+  data.tar.gz: 20d1fec190a9bfe2391e4e4121f2fa11dc35729abd54a8df47e0a19346611715
 SHA512:
-  metadata.gz: 1b8755f0f24f02d33aaf1f91bac610325e988a5cf9633ec74b31227b14f9f8582293ff0bd225b38efdc62e468b433dabb66fa14590e785355073f70d339add32
-  data.tar.gz: '083f8e499dedaa8efb934df433a3cd99c196828d7625e77e0cd4cd3f5003d5ab57a26990eee8c031a803d4b80fb7777ce05133cb4fda5bd616a38b448a288dc6'
+  metadata.gz: 3687dd8d85fffecbb4c1ab84177bcdb9dee0bfd0aa87dac7dbad61a81a4921d920f9c2f1cda8cfc3bff378c4a12d3528ab015e14085b447204c745e69c84155e
+  data.tar.gz: 2d135f12456ce99328d5422df362a83271cd9075b9f618c80b0cf3053edccb3a383164a0c23fdc6cced5e5e4514467e90b637d5beb976f052b2b742cfd7a8b18

data/CHANGELOG.md

@@ -4,6 +4,37 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.125.0 — 2026-11-04
+
+### Added
+
+- **Page transitions across full page loads.** With `Studio.page_transition_direction` set,
+  a same-origin full load plays the app's direction through the browser's cross-document
+  view transition: the same pair of styles, keyframes and timing as a Turbo visit, with the
+  navbar and banners held still. This reaches strict-policy pages, which must stay their
+  own documents. New files, linked only with a direction: `studio/page_transition_full_load.css`
+  and the classic `studio/page_transition_reveal.js`, which carries the request's nonce. A
+  reload, a same-path load, reduced motion and a browser without support load plainly. A full
+  load has no morph, and it cannot wait for images, so the 500ms image cap does not apply.
+  With no direction, a host renders no new tag.
+  [`docs/PAGE_TRANSITIONS.md`](docs/PAGE_TRANSITIONS.md).
+
+### Fixed
+
+- **A Turbo visit answered by `turbo-visit-control: reload` no longer plays the engine's fade**
+  before the full load. Turbo opens its view transition before it reads the meta, so that
+  transition now draws nothing.
+- **The navbar no longer draws twice during a page transition** when the old header is taller
+  than the new one, as on Back to a scrolled page. This changes Turbo visits too: only the new
+  navbar draws.
+
+- Link sidebar: a one-line row centers its icon on its label. It sat 3px low. A row with a
+  description keeps its icon at the top. The navbar baseline is regenerated for it.
+- Page transitions: an advance visit to the same path keeps a shared `data-vt-morph` name, so
+  a launch panel still morphs into the chat at its own address. A refresh stays silent.
+- Page transitions: a GET that redirects moves the page once. It played the move twice, because
+  Turbo renders the response and then visits the final address with that same response.
+
 ## 0.124.0 — 2026-11-04
 
 ### Added

data/README.md

@@ -41,7 +41,7 @@ resolved.
 - **Geo**: `Studio::GeoDetection` places every visitor (IP → country + subdivision, session-cached), `Studio::GeoSetting` stores the operator's blocked countries and regions, `require_geo_allowed` locks whichever surfaces an app chooses, and the shared badge + `/admin/geo` manager ship with it. See [`docs/GEO.md`](docs/GEO.md).
 - **Site identity and link previews**: `Studio::SiteIdentity` holds the app's title, description and image, edited at `/admin/link_preview` beside a live unfurl card and read anywhere through `Studio.site_identity`. Every page unfurls with it unless it calls `link_preview image:, title:, description:`, and `Studio::LinkPreviewBots` serves preview fetchers a slim page under iMessage's 1 MiB limit. Adopt with `bin/rails g studio:site_identity`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).
 - **Branded loader**: `studio_loader`, `studio_loader_pending` and `studio_loader_overlay` draw the app's own icon in its theme colours for page loads, long waits and pending buttons, in the style `config.loader` names (Breathe by default). See [`docs/LOADER.md`](docs/LOADER.md).
-- **App-to-app page transitions**: `config.page_transition_direction` (`:left`, `:right`, `:top`, `:bottom`) moves an app's pages one way on every page change, with the navbar and banners held still. It turns smooth-load on. See [`docs/PAGE_TRANSITIONS.md`](docs/PAGE_TRANSITIONS.md).
+- **App-to-app page transitions**: `config.page_transition_direction` (`:left`, `:right`, `:top`, `:bottom`) moves an app's pages one way on every page change, full page loads included, with the navbar and banners held still. It turns smooth-load on. See [`docs/PAGE_TRANSITIONS.md`](docs/PAGE_TRANSITIONS.md).
 - **Public user page**: `/u/:username` shows a user's avatar and username (nothing else), and unfurls with their avatar, falling back to the site image. Link any username to it with `link_to_user_profile(user)` or `studio_user_profile_path(user)`. Opt in with `config.draw_public_user_routes = true`. See [`docs/PUBLIC_USER_PAGE.md`](docs/PUBLIC_USER_PAGE.md).
 - **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 - **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer. It is on by default: with nothing configured it prints the app's name, logo and the legal links the app has routes for, and no address. `config.site_footer` declares the app's own facts (brand, social profiles, link columns, an address with a live map, legal links), every part optional; `config.site_footer_address` adds a location in one setting; `config.site_footer = false` turns the footer off; `config.site_footer_chat_path` adds a standard Chat link to the Contact column. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).

data/app/assets/javascripts/studio/page_transition_reveal.js

@@ -0,0 +1,75 @@
+// studio/page_transition_reveal: the arriving half of a full-load page transition
+// (docs/PAGE_TRANSITIONS.md, "Full page loads"). Loaded only with
+// Studio.page_transition_direction set.
+//
+// CLASSIC AND SYNCHRONOUS ON PURPOSE. pagereveal fires before the first render, and a listener
+// bound after that misses it for good. A module is deferred, so it can be too late.
+//
+// It holds no table of styles. The leaving page drew the style with studio/page_transitions
+// at pageswap and left it here. No style means the leaving page did not plan this one (its
+// module had not run, or it was the same path), so the load is plain, not the browser's fade.
+(function () {
+  var STYLE_KEY = "studio-page-transition-style"
+  var HOLD_CAP_MS = 3000
+
+  // Holds the first render to the end of parsing, on an arrival only (nothing has this id). A
+  // render of half a body would give the new picture no navbar or stack to hold still. The
+  // browser sets no limit on this hold, so the timer does: a slow body paints at the cap. The
+  // cap sits inside the browser's own limit on the transition, so the motion still plays.
+  function holdForTheWholePage() {
+    try {
+      if (!window.sessionStorage.getItem(STYLE_KEY)) return
+    } catch (_error) {
+      return
+    }
+    var link = document.createElement("link")
+    link.rel = "expect"
+    link.href = "#studio-page-transition-end-of-parse"
+    link.setAttribute("blocking", "render")
+    document.head.appendChild(link)
+    window.setTimeout(function () { link.remove() }, HOLD_CAP_MS)
+  }
+
+  function takeStyle() {
+    try {
+      var style = window.sessionStorage.getItem(STYLE_KEY)
+      window.sessionStorage.removeItem(STYLE_KEY)
+      return style
+    } catch (_error) {
+      return null
+    }
+  }
+
+  holdForTheWholePage()
+
+  window.addEventListener("pagereveal", function (event) {
+    var root = document.documentElement
+    // A page back from the back/forward cache still wears what it had on when it left.
+    delete root.dataset.pageTransition
+    delete root.dataset.pageTransitionVisit
+
+    var style = takeStyle()
+    var transition = event.viewTransition
+    if (!transition) return
+    var direction = document.querySelector('meta[name="page-transition-direction"]')
+    if (!style || !direction) {
+      transition.skipTransition()
+      return
+    }
+
+    // engine.css reads these three. The new page's picture comes after this listener, so the
+    // held stack and every morph name are settled in time.
+    root.dataset.pageTransitionDirection = direction.content
+    root.dataset.pageTransition = style
+    root.dataset.pageTransitionVisit = ""
+    var stack = document.querySelector("[data-vt-held], .studio-bar-stack")
+    if (stack) stack.setAttribute("data-vt-held", "")
+
+    var done = function () {
+      if (root.dataset.pageTransition !== style) return
+      delete root.dataset.pageTransition
+      delete root.dataset.pageTransitionVisit
+    }
+    transition.finished.then(done, done)
+  })
+})()

data/app/assets/stylesheets/studio/page_transition_full_load.css

@@ -0,0 +1,10 @@
+/* Opts a document in to the browser's cross-document view transition. A separate file,
+   because this at-rule takes no selector: in the engine's bundle it would act on every
+   host. layouts/studio/_head links it only with Studio.page_transition_direction set.
+   Both documents must carry it. Reduced motion gets no transition at all.
+   docs/PAGE_TRANSITIONS.md, "Full page loads". */
+@media (prefers-reduced-motion: no-preference) {
+  @view-transition {
+    navigation: auto;
+  }
+}

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

@@ -674,7 +674,7 @@ html[data-page-transition]::view-transition-new(root) {
   backface-visibility: hidden;
 }
 
-/* A same-page visit (a refresh, a poll) draws nothing. */
+/* A same-page visit (a refresh, a poll, the second half of a redirect) draws nothing. */
 html[data-page-transition="still"]::view-transition-old(root),
 html[data-page-transition="still"]::view-transition-new(root) {
   animation: none;
@@ -695,6 +695,12 @@ html[data-page-transition-direction][data-page-transition-visit] [data-vt-held]
   animation: none;
 }
 
+/* A taller old navbar would show under the new one for the whole motion, then pop off.
+   Only the new navbar draws. Where the two match, the new one covers the same pixels. */
+html[data-page-transition]:not([data-page-transition="still"])::view-transition-old(studio-header) {
+  opacity: 0;
+}
+
 /* A named element moves with the page, unless both pages share its name. The
    script decides that before the old page's picture, and only then is the name let
    through, so the morph stands. data-vt-morph carries the name it marks. */

data/app/javascript/studio/page_transitions.js

@@ -7,6 +7,10 @@
 // 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({
@@ -16,9 +20,12 @@ export const DIRECTIONS = Object.freeze({
   bottom: Object.freeze(["fade-bottom", "unfold-top"]),
 })
 
-// A same-page visit (a refresh, a poll): the transition still runs, and draws nothing.
+// 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)"
 
@@ -29,13 +36,37 @@ export function pickStyle(direction, random = Math.random) {
 }
 
 // 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).
-export function planVisit({ direction, from, to, transitions, sharedName }, random = Math.random) {
+// 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 STILL
+  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))])
@@ -109,12 +140,14 @@ export function installPageTransitions(doc) {
   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 && shareName(morphNames(doc), names))
+  const predict = (names) => nameTheMorph((target !== from || advance) && shareName(morphNames(doc), names))
 
   root.dataset.pageTransitionDirection = readDirection(doc)
   markHeld(doc)
@@ -122,7 +155,17 @@ export function installPageTransitions(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))
   })
 
@@ -154,6 +197,7 @@ export function installPageTransitions(doc) {
       to: target,
       transitions: !!doc.startViewTransition && !win.matchMedia(REDUCED_MOTION).matches,
       sharedName,
+      advance,
     })
     nameTheMorph(sharedName && style !== STILL)
     if (style) root.dataset.pageTransition = style
@@ -161,11 +205,20 @@ export function installPageTransitions(doc) {
     if (style && style !== STILL) holdRender(event, () => readyForSwap(doc, newBody))
   }, { capture: true })
 
-  // Turbo fires this after the transition has finished.
+  // 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)
@@ -173,8 +226,37 @@ export function installPageTransitions(doc) {
 
   // 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 })
+    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
 }
 

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

@@ -37,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 %>

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

data/lib/studio/engine.rb

@@ -89,8 +89,9 @@ module Studio
       # loaded as an ES module (Alpine by the head's type="module" tag,
       # canvas-confetti and SortableJS through their importmap pins, Leaflet by
       # studio/footer_map's import()), and studio/session.js, the one classic
-      # script (layouts/studio/_head says why). The engine's own modules are
-      # under app/javascript, enumerated below.
+      # script (layouts/studio/_head says why), with studio/page_transition_reveal.js,
+      # the other classic one. The engine's own modules are under app/javascript,
+      # enumerated below.
       app.config.assets.precompile += %w[
         studio/sticky_table_header.css
         studio/alpine.js
@@ -99,6 +100,8 @@ module Studio
         studio/leaflet.js
         studio/leaflet.css
         studio/session.js
+        studio/page_transition_full_load.css
+        studio/page_transition_reveal.js
         studio/montserrat-latin.woff2
         studio/montserrat-latin-ext.woff2
       ]

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.124.0"
+  VERSION = "0.125.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.124.0
+  version: 0.125.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -424,9 +424,11 @@ files:
 - app/assets/javascripts/studio/alpine.js
 - app/assets/javascripts/studio/canvas_confetti.js
 - app/assets/javascripts/studio/leaflet.js
+- app/assets/javascripts/studio/page_transition_reveal.js
 - app/assets/javascripts/studio/session.js
 - app/assets/javascripts/studio/sortable.js
 - app/assets/stylesheets/studio/leaflet.css
+- app/assets/stylesheets/studio/page_transition_full_load.css
 - app/assets/stylesheets/studio/sticky_table_header.css
 - app/assets/tailwind/studio_engine/engine-motion.css
 - app/assets/tailwind/studio_engine/engine.css