studio-engine 0.92.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e0b538d638180facefc1cff85cc4c5ccbea6aa49711d6ac48f1863a87e8d776
-  data.tar.gz: c48c355f0e8e9e2164649383eb61c7f47eaece289dfd0007e1f4f2d849137023
+  metadata.gz: 32e6d36ae904992ea14289647084091b399296ebc27daf777e45620ad126b772
+  data.tar.gz: 2c026cd62fca795d60fe39976ca9b47313103afdee12bff1ce590961a5d9ff6f
 SHA512:
-  metadata.gz: 9ac3c8a86695295f537aaa8355bfdc393a3b6a7ff5409308b7fe6ab402021e145089adc5a212d44aaced6921904563ccb16cf838ec5c46a33f7c9850196e2dda
-  data.tar.gz: 6d0fbbc3746e31d7dfd570185740ce394f91fb5503e5c3ce6f0ad7d59c4a6ba4f302669d8fd96e4bd1e6c2ef509aa5703951b8417381411bfb5d276cc8607e1d
+  metadata.gz: ac374e2ec4e47bce46d2c17367c776dc33388ed8f6559ec1c6c8646eb336530d6c00d91047ebcf9f52afe89f06f7618db7693229b1e78bc47afba8fc3a6c7383
+  data.tar.gz: b2f4a82578a5f3e2dac0a9a649c992103921dc376ce439364a3f944e01f7880476a72a49dce125b24860214ff6180802cbf9ea11b3585f4c30d1dfee0edeecc7

data/CHANGELOG.md

@@ -4,6 +4,69 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.94.0 — 2026-10-07
+
+### Added
+
+- **The engine boots its own Stimulus application** (`studio/application`),
+  imported on every page by `layouts/studio/_head` through
+  `javascript_import_module_tag`, which carries the request's CSP nonce. Engine
+  application reads its own attributes (`data-studio-controller`,
+  `data-studio-action`, `data-studio-target`), so a host's Stimulus application
+  and its lazy loader never see an engine controller. Stimulus 3.2.2 is vendored
+  (`studio/vendor/stimulus.js`) and pinned as `@hotwired/stimulus`; a host that
+  pins its own wins. The boot's module graph is preloaded
+  (`Studio::Engine.javascript_boot_graph`); every other engine pin is still
+  fetched only when imported.
+- **`nav-collapse`**, the navbar collapse as a Stimulus controller
+  (`data-studio-controller="nav-collapse"`). The engine navbar uses it;
+  `data-nav-collapse-scrolled-class` names the
+  classes it toggles when the shadow's hysteresis flips.
+
+### Changed
+
+- **The head's behaviour moves from inline scripts to ES modules.**
+  `layouts/studio/_head` goes from 714 lines and seven inline scripts to 197
+  lines and one: the pre-paint theme script, which now carries the request's
+  CSP nonce. The navbar collapse is `studio/nav_collapse`, the pinned stack is
+  `studio/pinned_stack`, and the theme and devMode stores, nav spinner and
+  success confetti are `studio/head_chrome`, each with `node:test` unit tests.
+  `window.navCollapse`, `window.showNavSpinner`, `window.hideNavSpinner`,
+  `window.fireSuccessConfetti`, `$store.theme` and `$store.devMode` keep their
+  names as thin shims (`studio/alpine_shims`); a host that defines its own
+  `window.navCollapse` keeps it.
+- **Alpine loads after the module tags.** So the shims exist before Alpine
+  starts, the head now loads Alpine after `javascript_importmap_tags`. A host
+  module therefore evaluates before `window.Alpine` exists: register Alpine
+  data and stores in an `alpine:init` listener (which now fires for host
+  modules), not at module evaluation. Inline scripts in the page are unaffected.
+- **The engine navbar's header binds `data-studio-controller="nav-collapse"`**
+  in place of `x-data="navCollapse()"`, and keeps a bare `x-data` as the Alpine
+  scope its descendants bind through. A forked header may keep
+  `x-data="navCollapse()"`.
+- Studio.nav_spinner_min_ms reaches the browser as
+  `<meta name="studio-nav-spinner-min-ms">`.
+
+### Fixed
+
+- **The theme and devMode Alpine stores survive a boot that fails to load.**
+  They move to `studio/alpine_stores`, a module that imports nothing, and
+  `layouts/studio/_head` imports it by its own `javascript_import_module_tag`
+  (nonced, before Alpine) as well as through the boot's graph. So when
+  `studio/application` fails to load, a host's
+  `:class="{ 'dev-mode': $store.devMode }"` body binding and the theme toggle
+  still find their stores instead of throwing. A store registers only where
+  Alpine has none of that name, so the two paths never register twice and a
+  host's own store wins. `storedTheme` and `toggleTheme` move from
+  `studio/head_chrome` to `studio/alpine_stores`.
+
+### Breaking
+
+- **`window._navSpinnerShownAt` and `window._navSpinnerMinMs` are removed.**
+  The spinner's state is private to `studio/head_chrome`; no consumer reads them.
+
+## 0.93.0 — 2026-10-07
+
 ## 0.92.2 — 2026-10-07
 
 ## 0.92.1 — 2026-10-07
@@ -22,6 +85,26 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   raises `Studio::HostSchemaError` in development and test, and logs (and reports
   to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
   overrides. Extra host columns are never reported, and rake tasks skip it.
+- **`Sluggable#rename_slug!` changes a slug on purpose and cascades.** It updates
+  the row and every child column that holds the old slug in one transaction:
+  each `has_many`/`has_one` declared with `primary_key: :slug`, plus the pairs a
+  model declares with `has_slug_children "table" => :column`. A blank, badly
+  formed (`slug_format`, parameterize-shaped by default) or taken slug raises
+  `Sluggable::SlugRefused`, a `RecordInvalid` with the reason on
+  `errors[:slug]`; `rename_slug` returns false instead.
+- **`Studio::ErrorHandling` answers a refused slug rename with 422** and the
+  reason (JSON and other formats), or a redirect back with the reason as the
+  alert (HTML), never the 500 catch-all and no ErrorLog row.
+
+### Changed
+
+- **A slug is written once, at create.** `Sluggable` no longer recomputes
+  `slug` from `name_slug` on every save, so a name edit stops renaming the row
+  and orphaning the child rows that point at it. A persisted row with a blank
+  slug still gets one on its next save, and a `name_slug` that reads the id is
+  settled inside the create, so `user-<id>` no longer waits for a second save.
+  Code that relied on a save moving the slug calls `rename_slug!(name_slug)`
+  instead.
 
 ### Fixed
 

data/README.md

@@ -35,7 +35,7 @@ resolved.
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
 - **UI primitives**: Shared component partials and CSS primitives such as `components/emoji_swap` for nav/sidebar emoji hover transitions.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls and `studio/banners/impersonation`.
-- **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
+- **Sluggable concern**: a human-readable slug written once at create (`to_param` returns it); `rename_slug!` changes it and cascades to every child column in one transaction, and a refused rename answers 422
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
 - **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).

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

@@ -17,6 +17,8 @@ module Studio
       # handlers BELOW this line, never above it.
       rescue_from StandardError, with: :handle_unexpected_error
       rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      # A string, so including this concern does not load the model concern.
+      rescue_from "Sluggable::SlugRefused", with: :handle_slug_refused
 
       before_action :require_authentication
 
@@ -243,6 +245,19 @@ module Studio
       raise exception
     end
 
+    # Layer 1: a refused slug rename (Sluggable#rename_slug!) is the caller's
+    # input, not a fault: 422 with the reason for JSON and other formats, and a
+    # redirect back with the reason as the alert for HTML. No ErrorLog row.
+    def handle_slug_refused(exception)
+      reason = exception.record.errors.full_messages_for(:slug).to_sentence.presence || exception.message
+
+      respond_to do |format|
+        format.html { redirect_back_or_to root_path, alert: reason }
+        format.json { render json: { error: reason }, status: :unprocessable_entity }
+        format.any  { render plain: reason, status: :unprocessable_entity }
+      end
+    end
+
     # Layer 1: Catch-all for unexpected errors — log + friendly response.
     # Skips logging if rescue_and_log already captured it.
     def handle_unexpected_error(exception)

data/app/controllers/studio/onboarding_controller.rb

@@ -79,12 +79,10 @@ module Studio
         #   2. It steps around any host before_save that DERIVES first_name FROM
         #      name — set_name_parts does exactly that — which would discard the
         #      value we were just handed.
-        #   3. THE SLUG. Sluggable's `before_save :set_slug` is UNGATED, and
-        #      mcritchie-studio's User#name_slug is built from `name`. A full
-        #      save right after this writes `name` would therefore re-point the
-        #      slug the account answers on — a URL change, on a column carrying
-        #      a unique index, for every signup. That is the constraint this
-        #      endpoint has always been protecting; it is not a shortcut.
+        #   3. A host save can carry other callbacks that react to a name
+        #      write; this endpoint writes only the name columns. (Sluggable
+        #      writes the slug once, at create, so the slug stays put either
+        #      way.)
         #
         # WHAT SKIPPING CALLBACKS USED TO COST. Because set_name_parts never
         # ran, `first_name` got the WHOLE typed value: someone answering "Ada

data/app/javascript/studio/alpine_shims.js

@@ -0,0 +1,45 @@
+// studio/alpine_shims: the Alpine names and window globals consumers still
+// bind to, each a thin delegate to the module that now owns the behaviour.
+//
+// They exist while a consumer binds to them, and go with the consumer phase of
+// the Stimulus migration. Every binding site is listed on the task
+// engine-behaviour-moves-to-stimulus.
+//
+// WHY THIS WORKS BEFORE ALPINE STARTS. layouts/studio/_head loads Alpine AFTER
+// the module tags, and deferred classic scripts and module scripts execute in
+// document order. So this module has run, and its `alpine:init` listener is
+// registered, before Alpine evaluates its first x-data.
+//
+// THE STORES ARE NOT HERE. $store.theme and $store.devMode are
+// studio/alpine_stores, which the head also loads by its own module tag, so a
+// host's body binding survives a boot that failed to load. Importing it here
+// keeps it in the boot graph, preloaded; it installs itself on evaluation.
+import "studio/alpine_stores"
+import { NavCollapse } from "studio/nav_collapse"
+import {
+  showNavSpinner, hideNavSpinner, installSpinnerReset, fireSuccessConfetti
+} from "studio/head_chrome"
+
+// x-data="navCollapse()": the hub's own header. A host that defines its own
+// window.navCollapse (turf-monster does, inline, before this runs) keeps it.
+export function navCollapse() {
+  return {
+    scrolled: false,
+    init: function () {
+      var self = this
+      this._collapse = new NavCollapse(this.$el, function (lit) { self.scrolled = lit })
+      this._collapse.start()
+    },
+    destroy: function () {
+      if (this._collapse) this._collapse.stop()
+    }
+  }
+}
+
+export function installAlpineShims() {
+  if (!window.navCollapse) window.navCollapse = navCollapse
+  if (!window.showNavSpinner) window.showNavSpinner = showNavSpinner
+  if (!window.hideNavSpinner) window.hideNavSpinner = hideNavSpinner
+  if (!window.fireSuccessConfetti) window.fireSuccessConfetti = fireSuccessConfetti
+  installSpinnerReset()
+}

data/app/javascript/studio/alpine_stores.js

@@ -0,0 +1,82 @@
+// studio/alpine_stores: the Alpine stores every host body binds to,
+// $store.theme and $store.devMode, and the theme value and toggle behind them.
+//
+// WHY THIS IS ITS OWN ENTRY POINT. Every host's <body> says
+// :class="{ 'dev-mode': $store.devMode }", and the engine's theme toggle reads
+// $store.theme. When those stores lived only inside studio/application's graph,
+// any failure to load that graph (a missing digest after a deploy, a network
+// drop, a throw in Stimulus or a controller) left Alpine evaluating the body
+// binding against an undefined store, and it threw on every page.
+//
+// So the stores load by two paths, and either one alone is enough:
+//
+//   1. layouts/studio/_head imports this module with its own
+//      javascript_import_module_tag, which carries the request's CSP nonce.
+//      A failed studio/application does not stop it.
+//   2. studio/alpine_shims imports it, so the boot graph carries it too and the
+//      module is preloaded with the rest of the boot.
+//
+// Both resolve to one module instance, and the install below is idempotent
+// regardless: one alpine:init listener per document, and a store is registered
+// only when Alpine does not have one of that name (so a host's own wins).
+//
+// THIS MODULE IMPORTS NOTHING, and test/javascript/alpine_stores.test.mjs holds
+// it to that: an import would put another module's failure back in its path.
+//
+// The pre-paint half of the theme (adding `dark` before first paint) stays an
+// inline, nonced script in the head: it must run before the stylesheet paints,
+// which no deferred module can.
+
+// The stored theme, dark unless the reader chose light.
+export function storedTheme(storage) {
+  return storage.getItem('theme') || 'dark'
+}
+
+// Flips the root's `dark` class under a short transition class, stores the
+// result, and answers it.
+export function toggleTheme(root, storage, later) {
+  root.classList.add('theme-transition')
+  root.classList.toggle('dark')
+  var value = root.classList.contains('dark') ? 'dark' : 'light'
+  storage.setItem('theme', value)
+  later(function () { root.classList.remove('theme-transition') }, 300)
+  return value
+}
+
+// Registers each store Alpine does not already have. env carries what the
+// stores read and write: { storage, root, later }.
+export function registerStudioStores(Alpine, env) {
+  if (Alpine.store('devMode') === undefined) {
+    Alpine.store('devMode', env.storage.getItem('devMode') === 'true')
+  }
+  if (Alpine.store('theme') === undefined) {
+    Alpine.store('theme', {
+      value: storedTheme(env.storage),
+      get isDark() { return this.value === 'dark' },
+      toggle: function () {
+        this.value = toggleTheme(env.root, env.storage, env.later)
+      }
+    })
+  }
+}
+
+// Adds the alpine:init listener that registers the stores, once per document.
+// It must run before Alpine starts: the head loads Alpine after the module
+// tags, and deferred and module scripts run in document order.
+var installedOn = new WeakSet()
+
+export function installStudioStores(doc, win) {
+  if (installedOn.has(doc)) return
+  installedOn.add(doc)
+  doc.addEventListener('alpine:init', function () {
+    registerStudioStores(win.Alpine, {
+      storage: win.localStorage,
+      root: doc.documentElement,
+      later: function (fn, ms) { win.setTimeout(fn, ms) }
+    })
+  })
+}
+
+if (typeof document !== 'undefined' && typeof window !== 'undefined') {
+  installStudioStores(document, window)
+}

data/app/javascript/studio/application.js

@@ -0,0 +1,37 @@
+// studio/application: the engine's browser boot, imported on every page by
+// layouts/studio/_head (javascript_import_module_tag, which carries the
+// request's CSP nonce).
+//
+// The engine runs its own Stimulus application on its OWN attributes:
+//
+//   data-studio-controller="nav-collapse"   data-studio-action   data-studio-target
+//
+// so a host's Stimulus application never sees an engine controller. That is not
+// tidiness: stimulus-loading's lazy loader (cyvasse) imports
+// "controllers/<identifier>_controller" for every data-controller it meets, and
+// would log "Failed to autoload controller" for each engine element. Values and
+// classes keep Stimulus' own naming (data-nav-collapse-scrolled-class).
+// "@hotwired/stimulus" resolves to the engine's vendored copy unless the host
+// pins its own.
+//
+// Everything this file imports statically is preloaded on every page
+// (Studio::Engine.javascript_boot_graph), so the boot costs one round trip.
+import { Application, defaultSchema } from "@hotwired/stimulus"
+import NavCollapseController from "studio/controllers/nav_collapse_controller"
+import { startPinnedStack } from "studio/pinned_stack"
+import { installAlpineShims } from "studio/alpine_shims"
+
+installAlpineShims()
+startPinnedStack()
+
+export const schema = {
+  ...defaultSchema,
+  controllerAttribute: "data-studio-controller",
+  actionAttribute: "data-studio-action",
+  targetAttribute: "data-studio-target"
+}
+
+const application = Application.start(document.documentElement, schema)
+application.register("nav-collapse", NavCollapseController)
+
+export { application }

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

@@ -0,0 +1,28 @@
+// nav-collapse: the scroll-linked navbar collapse on a <header>, on the engine's
+// Stimulus application (studio/application, which reads data-studio-controller).
+//
+//   <header class="nav-shell ..." data-studio-controller="nav-collapse"
+//           data-nav-collapse-scrolled-class="shadow-lg is-scrolled">
+//
+// The behaviour is studio/nav_collapse; this controller binds it to the
+// element's lifetime and toggles the `scrolled` classes when the shadow's
+// hysteresis flips. Registered by studio/application.
+import { Controller } from "@hotwired/stimulus"
+import { NavCollapse } from "studio/nav_collapse"
+
+export default class extends Controller {
+  static classes = ["scrolled"]
+
+  connect() {
+    this.collapse = new NavCollapse(this.element, (lit) => {
+      if (!this.hasScrolledClass) return
+      for (const name of this.scrolledClasses) this.element.classList.toggle(name, lit)
+    })
+    this.collapse.start()
+  }
+
+  disconnect() {
+    if (this.collapse) this.collapse.stop()
+    this.collapse = null
+  }
+}

data/app/javascript/studio/head_chrome.js

@@ -0,0 +1,79 @@
+// studio/head_chrome: the small behaviours every page's chrome carries. Each
+// piece below used to be an inline <script> in layouts/studio/_head.
+//
+//   nav spinner   the scale morph between the theme toggle and a spinner
+//   confetti      the success burst a completed flow fires
+//
+// The logic is exported for test/javascript/head_chrome.test.mjs. The window
+// globals that consumers bind to are installed by studio/alpine_shims. The
+// theme and its Alpine store are studio/alpine_stores, which loads even when
+// this module does not.
+
+// ---- NAV SPINNER ------------------------------------------------------------
+//
+// Minimum display time prevents quick flashes; per app via
+// Studio.nav_spinner_min_ms, which the head publishes as
+// <meta name="studio-nav-spinner-min-ms"> (smooth-load apps drop it to ~300).
+
+// How long hide must still wait so the spinner shows for at least minMs.
+export function spinnerHideDelay(shownAt, now, minMs) {
+  return Math.max(0, minMs - (now - shownAt))
+}
+
+export function spinnerMinMs(doc) {
+  var meta = doc.querySelector('meta[name="studio-nav-spinner-min-ms"]')
+  var value = meta ? parseInt(meta.getAttribute('content'), 10) : 0
+  return value > 0 ? value : 0
+}
+
+var spinnerShownAt = 0
+
+function showToggle(doc) {
+  doc.querySelectorAll('.nav-toggle-icon').forEach(function (e) { e.style.opacity = '1'; e.style.transform = 'scale(1) rotate(0deg)' })
+  doc.querySelectorAll('.nav-spinner-icon').forEach(function (e) { e.style.opacity = '0'; e.style.transform = 'scale(0) rotate(-90deg)' })
+}
+
+export function showNavSpinner() {
+  spinnerShownAt = Date.now()
+  document.querySelectorAll('.nav-toggle-icon').forEach(function (e) { e.style.opacity = '0'; e.style.transform = 'scale(0) rotate(90deg)' })
+  document.querySelectorAll('.nav-spinner-icon').forEach(function (e) { e.style.opacity = '1'; e.style.transform = 'scale(1) rotate(0deg)' })
+}
+
+export function hideNavSpinner() {
+  var wait = spinnerHideDelay(spinnerShownAt, Date.now(), spinnerMinMs(document))
+  setTimeout(function () { showToggle(document) }, wait)
+}
+
+// Reset spinner state before Turbo caches the page. Installed once.
+var spinnerResetInstalled = false
+export function installSpinnerReset() {
+  if (spinnerResetInstalled) return
+  spinnerResetInstalled = true
+  document.addEventListener('turbo:before-cache', function () { showToggle(document) })
+}
+
+// ---- SUCCESS CONFETTI -------------------------------------------------------
+//
+// Rides the global `confetti` that studio/canvas_confetti defines; does
+// nothing when it is absent. window.CONFETTI_COLORS overrides the palette.
+
+export var SUCCESS_COLORS = ['#4BAF50', '#8E82FE', '#06D6A0', '#FF7C47', '#FFD700', '#00BFFF', '#FF6B9D', '#C084FC']
+
+// The four bursts, each as [delay ms, confetti options].
+export function successBursts(colors) {
+  return [
+    [0, { particleCount: 150, spread: 100, origin: { x: 0.5, y: 0.5 }, colors: colors, zIndex: 9999, startVelocity: 45, gravity: 0.8, ticks: 300, scalar: 1.2 }],
+    [150, { particleCount: 80, angle: 60, spread: 60, origin: { x: 0, y: 0.6 }, colors: colors, zIndex: 9999, startVelocity: 55, gravity: 1, ticks: 250 }],
+    [150, { particleCount: 80, angle: 120, spread: 60, origin: { x: 1, y: 0.6 }, colors: colors, zIndex: 9999, startVelocity: 55, gravity: 1, ticks: 250 }],
+    [400, { particleCount: 100, spread: 160, origin: { x: 0.5, y: 0.3 }, colors: colors, zIndex: 9999, startVelocity: 30, gravity: 1.2, ticks: 200, scalar: 0.8 }]
+  ]
+}
+
+export function fireSuccessConfetti() {
+  if (typeof window.confetti === 'undefined') return
+  var fire = window.confetti
+  successBursts(window.CONFETTI_COLORS || SUCCESS_COLORS).forEach(function (burst) {
+    if (burst[0] === 0) fire(burst[1])
+    else setTimeout(function () { fire(burst[1]) }, burst[0])
+  })
+}