studio-engine 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e37d3038ae5d72bbd0829247f562aa744960458dc9e54faa73c38fc1a2adcb83
-  data.tar.gz: a74cb5455f9977009b3499981dec577bb7df9782a5ab2f08a2bda92fe9cbe9c5
+  metadata.gz: 2aed8dd0e8d45e41602035462f0b60d01414ac3ea2f41484cbff9d4a40384cb8
+  data.tar.gz: e7aa1bfef279150c47cf3bd709de81b5b174f9027252a177a58a19e4609cf85c
 SHA512:
-  metadata.gz: 45ecd0d11aef5443dc5342013e39124b52ecf67b46261b096e45a57b088a22335e5ce7c1b58f894c0878888cd1dc087b886f76e7ed15875ec08759222a52ae74
-  data.tar.gz: 2e1b9c6dd268214317af8a93aa27bf49e1aa2ebff4e487010a81fd5f332ee261a0d1011fb636cbd9577dd3300c23ba0b1edc6e40e7b56366d83c7314d40a0636
+  metadata.gz: 2b0ed377abc9501ce2a0fa19cc17d547e02498673ac15265ceac38555bf1fa241996e52c7dc5af337677a3436cfeb2209dd47f75fe70757bea96cebca21194e1
+  data.tar.gz: 1bd498dc182950382bfe3dca7fb5056bf6e2ff5760161ee8edf5481ef3c444a35ca7d4c51fd682b5d62f8e6c30aec787297cf537daba0956b8aefcc810b6172c

data/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.24.0 — 2026-07-28
+
+The **smooth-load convention**, opt-in per app. Pages materialize behind the
+current one and present themselves with a view transition — navigation renders
+exactly once, with no stale-preview flash. Modifies an existing primitive:
+`layouts/studio/_head` gains the convention partial and a configurable nav
+spinner minimum.
+
+**One ungated visual change on the bump, opt-in or not:** `.turbo-progress-bar`
+in `engine.css` restyles every consumer's Turbo progress bar from Turbo's
+default blue to the app's theme CTA color (3px, `var(--color-cta)` — defined in
+both themes by the theme resolver, and the rule wins Turbo's injected-first
+stylesheet cascade). Everything else is inert until an app sets
+`Studio.smooth_load = true`.
+
+### Added
+
+- **Smooth-load convention (opt-in)** — `Studio.smooth_load` (default OFF)
+  renders `layouts/studio/_smooth_load` from `_head`: the `view-transition`
+  meta (Turbo 8 wraps page swaps in `document.startViewTransition`) plus
+  `turbo-cache-control: no-preview`, so the next page materializes behind the
+  current one and presents itself — navigation renders exactly once. An app
+  with known multi-second pages should fix those before opting in (no-preview
+  holds the old page until the fresh response arrives).
+- **`Studio.nav_spinner_min_ms`** — the nav spinner's minimum display time,
+  previously hardcoded to 2500 in `_head`. Default unchanged (2500); smooth-load
+  apps typically drop it to ~300 so fast loads never linger on a spinner.
+- **Smooth-load CSS in `engine.css`** — root fade-out / rise-in view-transition
+  keyframes (inert until the metas render), the `.vt-pinned-header` opt-in
+  utility (exactly one per page — a duplicate `view-transition-name` silently
+  disables the transition), the theme-colored `.turbo-progress-bar` noted
+  above, and a `prefers-reduced-motion` kill switch app e2e suites can lean on
+  (`reducedMotion: "reduce"`).
+
+### Fixed
+
+- **`rescue_from` order in `Studio::ErrorHandling`** — `RecordNotFound` now
+  resolves to `handle_not_found` (Rescuable matches last-registered first, so
+  the catch-all must register first). A missing record renders a real 404 from
+  `public/404.html` and **creates no ErrorLog row**; previously it was shadowed
+  by the catch-all, logged as an unexpected error, and soft-404'd (302 to root)
+  in production HTML. Per-host behavior changes only as each app bumps to this
+  release.
+
 ## 0.23.0 — 2026-07-28
 
 Phase D, slice 1 — the **board primitive**. The three near-identical McRitchie

data/README.md

@@ -42,6 +42,16 @@ Studio.configure do |config|
   )
   config.theme_primary = "#4BAF50"   # Override default violet
   config.theme_logos = ["logo.svg"]
+
+  # Smooth-load convention (default OFF). Renders the view-transition +
+  # no-preview metas: Turbo page swaps materialize behind the current page and
+  # present with a view transition, exactly one render per navigation. Fix any
+  # multi-second pages BEFORE opting in — no-preview holds the old page until
+  # the fresh response arrives.
+  config.smooth_load = true
+  # Nav spinner minimum display (default 2500). Smooth-load apps typically
+  # drop to ~300; keep the high floor if multi-second ops ride the spinner.
+  config.nav_spinner_min_ms = 300
 end
 ```
 
@@ -114,6 +124,18 @@ privileges while impersonating.
 
 ## UI Primitives
 
+### Smooth-load header pin — `.vt-pinned-header`
+
+When `Studio.smooth_load` is on, put `vt-pinned-header` on the app's sticky
+header: it gets its own named view-transition group, so page content
+transitions beneath a navbar that stays put (or smoothly morphs heights).
+**Exactly one element per page** — a duplicate `view-transition-name` makes
+the browser silently skip the whole transition, with no error and no animation.
+
+```erb
+<header class="sticky top-0 vt-pinned-header ...">
+```
+
 Render `components/emoji_swap` inside a link or button with the `group` class to
 slide between two emoji on hover and keyboard focus. The CSS ships through
 `studio_theme_css_tag`, including a reduced-motion fade fallback.

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

@@ -180,3 +180,62 @@
 @utility btn-lg {
   @apply px-8 py-3 text-base rounded-xl shadow-sm;
 }
+
+/* -- Smooth-load convention ------------------------------------------------
+   Paired with layouts/studio/_smooth_load.html.erb (the Studio.smooth_load
+   metas that opt Turbo into document.startViewTransition). These rules are
+   inert until an app renders those metas, so shipping them in the auto-bundled
+   layer costs nothing. The outgoing page fades while the incoming one rises in
+   underneath — quick enough to read as polish, not as a wait. */
+::view-transition-old(root) {
+  animation: vt-page-out 160ms cubic-bezier(0.4, 0, 1, 1) both;
+}
+
+::view-transition-new(root) {
+  animation: vt-page-in 220ms cubic-bezier(0, 0, 0.2, 1) both;
+}
+
+@keyframes vt-page-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes vt-page-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* Opt-in header pin: put this on the app's sticky header so it gets its own
+   named transition group, lifted out of the root snapshot — page content
+   transitions beneath a navbar that stays put (or smoothly morphs heights).
+   EXACTLY ONE element per page: a duplicate view-transition-name makes the
+   browser silently skip the whole transition. */
+@utility vt-pinned-header {
+  view-transition-name: studio-header;
+}
+
+/* Turbo's progress bar is the slow-load feedback under no-preview (the old
+   page holds until the fresh response). Theme it so every app's bar matches
+   its brand instead of Turbo's default. */
+.turbo-progress-bar {
+  height: 3px;
+  background: var(--color-cta);
+}
+
+/* Reduced motion: keep the single-render swap, drop the choreography. Also
+   what the apps' e2e suites lean on (reducedMotion: "reduce") for stable
+   clicks. */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}

data/app/controllers/concerns/studio/error_handling.rb

@@ -3,8 +3,15 @@ module Studio
     extend ActiveSupport::Concern
 
     included do
-      rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      # ORDER IS LOAD-BEARING — ActiveSupport::Rescuable resolves handlers with
+      # `reverse_each`, so the LAST matching rescue_from registered wins. The
+      # catch-all must therefore be declared FIRST and the specific handlers
+      # after it, or StandardError shadows every one of them: RecordNotFound
+      # rendered "Something went wrong" and wrote an ErrorLog row on every 404,
+      # fleet-wide, while handle_not_found sat unreachable. Add new specific
+      # handlers BELOW this line, never above it.
       rescue_from StandardError, with: :handle_unexpected_error
+      rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
 
       before_action :require_authentication
 
@@ -195,12 +202,33 @@ module Studio
       raise e
     end
 
-    # Layer 1: Catch-all for RecordNotFound — 404 redirect, no logging.
+    # Layer 1: RecordNotFound — Rails' own 404, never an ErrorLog row.
+    #
+    # This handler exists for exactly ONE reason: to stop `handle_unexpected_error`
+    # from claiming a RecordNotFound and writing an ErrorLog row for it. It
+    # deliberately renders NOTHING and re-raises, which hands the exception to
+    # `ActionDispatch::PublicExceptions` — the same path an app with no rescue_from
+    # at all takes. Registering the handler and re-raising is therefore not a
+    # no-op: matching here is what keeps the catch-all's `create_error_log` from
+    # running (a raise inside a rescue_from handler propagates out; Rescuable does
+    # not re-dispatch it into another handler).
+    #
+    # Why nothing is rendered here. The method was unreachable from the initial
+    # commit until the rescue_from order was fixed (see the note in `included`),
+    # so whatever it did had never actually run — consumers have been served
+    # Rails' standard 404 all along. Anything rendered here would therefore be a
+    # NEW fleet-wide behaviour, not a restoration: an earlier attempt at this fix
+    # rendered public/404.html and silently flipped `Accept: */*` clients (curl,
+    # uptime monitors, crawlers, link previewers) from `404 text/html` to
+    # `404 application/json`, changed the JSON body shape, and dropped the
+    # DebugExceptions backtrace in development. Re-raising keeps every one of
+    # those intact, along with `public/404.<locale>.html` and any
+    # `config.exceptions_app` a host configures.
+    #
+    # The bug being fixed is the ErrorLog pollution and the "Something went wrong"
+    # copy — never the status code, the format, or the body.
     def handle_not_found(exception)
-      respond_to do |format|
-        format.html { redirect_to root_path, alert: "Not found" }
-        format.json { render json: { error: "Not found" }, status: :not_found }
-      end
+      raise exception
     end
 
     # Layer 1: Catch-all for unexpected errors — log + friendly response.

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

@@ -10,6 +10,7 @@
 <meta name="apple-mobile-web-app-capable" content="yes">
 <%= csrf_meta_tags %>
 <%= csp_meta_tag %>
+<%= render "layouts/studio/smooth_load" %>
 <link rel="icon" type="image/png" href="/favicon.png">
 
 <%= yield :head %>
@@ -46,9 +47,10 @@
 </script>
 <script>
   // Nav spinner — scale morph between theme toggle and loading spinner
-  // Minimum display time prevents quick flashes
+  // Minimum display time prevents quick flashes; per-app via
+  // Studio.nav_spinner_min_ms (smooth-load apps drop it to ~300).
   window._navSpinnerShownAt = 0;
-  window._navSpinnerMinMs = 2500;
+  window._navSpinnerMinMs = <%= Studio.nav_spinner_min_ms.to_i %>;
   window.showNavSpinner = function() {
     window._navSpinnerShownAt = Date.now();
     document.querySelectorAll('.nav-toggle-icon').forEach(function(e) { e.style.opacity = '0'; e.style.transform = 'scale(0) rotate(90deg)'; });

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

@@ -0,0 +1,15 @@
+<%# Smooth-load convention (opt-in via Studio.smooth_load) — the next page
+    materializes behind the current one, then presents itself. Turbo 8 sees the
+    view-transition meta and wraps its body swap in document.startViewTransition;
+    browsers without support get the instant swap. no-preview stops application
+    visits from painting a stale cache snapshot before the fresh response — the
+    current page holds until the new one is ready, so navigation renders exactly
+    once. Restoration visits (back/forward) still restore instantly from cache.
+    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 %>
+  <meta name="view-transition" content="same-origin">
+  <meta name="turbo-cache-control" content="no-preview">
+<% end %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.23.0"
+  VERSION = "0.24.0"
 end

data/lib/studio.rb

@@ -25,6 +25,20 @@ module Studio
   mattr_accessor :theme_logos,         default: []
   mattr_accessor :sticky_table_headers, default: false
 
+  # ---- Smooth-load convention ---------------------------------------------
+  # Opt-in per app: renders the view-transition + no-preview metas so Turbo 8
+  # page swaps materialize behind the current page and present with a view
+  # transition (layouts/studio/_smooth_load). OFF by default — an app with
+  # known multi-second pages should fix those before opting in, because
+  # no-preview holds the old page until the fresh response arrives.
+  mattr_accessor :smooth_load,          default: false
+
+  # Minimum ms the nav spinner stays visible once shown (_head.html.erb).
+  # Apps wrapping multi-second operations in the spinner (e.g. Solana RPC)
+  # keep the high default to avoid flicker; smooth-load apps typically drop
+  # this to ~300 so fast loads never linger on a spinner.
+  mattr_accessor :nav_spinner_min_ms,   default: 2500
+
   # ---- Authentication ------------------------------------------------------
   # Which sign-in methods this app offers. The shared login/signup views render
   # a button/field per enabled method (gate with Studio.auth_method?). Order is

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -242,6 +241,7 @@ files:
 - app/views/layouts/branded_mailer.html.erb
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.html.erb
+- app/views/layouts/studio/_smooth_load.html.erb
 - app/views/magic_links/confirm.html.erb
 - app/views/navbar/show.html.erb
 - app/views/registrations/new.html.erb
@@ -349,7 +349,6 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -364,8 +363,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching