studio-engine 0.93.0 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3769d755a39684b1488e69948a2c671c736c655400bf035d6c69e8db5c990a8e
-  data.tar.gz: 2941057ba862ce883d57e58f56d9dfae793c6ad0781802af6147848583604ecf
+  metadata.gz: 32e6d36ae904992ea14289647084091b399296ebc27daf777e45620ad126b772
+  data.tar.gz: 2c026cd62fca795d60fe39976ca9b47313103afdee12bff1ce590961a5d9ff6f
 SHA512:
-  metadata.gz: 443ae3e30df171f7ff4614a82785a0e40f231dc11d792d3e36a8160b9d13d112bd1e55fc420759a564b02ec6b69d0f64406c9d7265eca2bf2885edb8f7be58a4
-  data.tar.gz: 7f1b7c14d366cb9cd26f7c0a3caf8c5135d13ac79b359e8ca095047602657bf3a4eb28d5127fe13fcb5175137fe9fbb8844b370b89c13340bdbf4540679b8cc0
+  metadata.gz: ac374e2ec4e47bce46d2c17367c776dc33388ed8f6559ec1c6c8646eb336530d6c00d91047ebcf9f52afe89f06f7618db7693229b1e78bc47afba8fc3a6c7383
+  data.tar.gz: b2f4a82578a5f3e2dac0a9a649c992103921dc376ce439364a3f944e01f7880476a72a49dce125b24860214ff6180802cbf9ea11b3585f4c30d1dfee0edeecc7

data/CHANGELOG.md

@@ -4,6 +4,67 @@ 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

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])
+  })
+}

data/app/javascript/studio/nav_collapse.js

@@ -0,0 +1,238 @@
+// studio/nav_collapse: the scroll-linked navbar collapse.
+//
+// Publishes --nav-p on the <header> once per animation frame from
+// window.scrollY. The navbar's own stylesheet derives every collapsing
+// dimension from it with calc(), so the header moves only in a frame the
+// finger moved it, and stops the instant the finger does.
+//
+// It replaces `@scroll.window="scrolled = scrolled ? (scrollY > 5) : (scrollY
+// > 60)"` plus `transition-all duration-300`. That pair let the FINGER set a
+// step and an ease curve own everything after it. Measured in turf-monster at
+// 390x844 before the change: the header ran 178px -> 139px and 34 of those
+// 39px of document reflow landed AFTER the scroll had stopped, over 232ms, at
+// up to 3px per frame of content nobody asked to move -- plus a 1px REVERSE
+// lurch in the frame the class flipped, where a discrete text-3xl -> text-xl
+// swap collided with the stylesheet's own `transition: font-size`.
+//
+// ADOPTING IT: put `nav-shell` and `data-studio-controller="nav-collapse"` on
+// the header (studio/controllers/nav_collapse_controller), give each breakpoint
+// band a `--nav-ramp`, and write the collapsing dimensions as calc()s off
+// --nav-p. A header that still says `x-data="navCollapse()"` gets the same
+// mechanism through the Alpine shim (studio/alpine_shims). This file ships NO
+// sizing opinion, so an app whose navbar collapses to different endpoints than
+// the engine's adopts the mechanism without touching its markup.
+//
+// Four details are load-bearing:
+//
+//   passive + rAF: the listener never blocks the compositor and coalesces a
+//   burst of scroll events (iOS momentum fires far above 60Hz) into one write
+//   per frame. The write lands on the HEADER, not :root: an inherited custom
+//   property written on :root dirties style for the whole document every
+//   frame, and it would leak the live page's scroll progress into the preview
+//   headers on /navbar.
+//
+//   the smoothstep: collapsing a sticky, IN-FLOW header pulls the page up,
+//   so during the collapse content moves by the scroll AND by the shrink:
+//   faster than the finger, always. That is inherent; reclaiming the vertical
+//   space is the point. What is tunable is the shape of the burst. --nav-ramp
+//   is sized at 3x the band's collapse total and the ramp is smoothstepped,
+//   whose slope is zero at both ends, so content speed LEAVES 1x, peaks near
+//   1.5x mid-ramp, and returns to 1x with no velocity step. A linear ramp
+//   equal to the collapse hits 2x and steps straight back to 1x.
+//
+//   the short-page guard: collapsing shortens the document by the collapse
+//   total. On a page with barely more than that to scroll, the collapse
+//   deletes the very scroll room that triggered it, the browser clamps
+//   scrollY to 0, and the navbar flaps open and shut forever. roomExpanded
+//   adds back the shrink ALREADY applied, so the measurement cannot chase
+//   itself as it collapses.
+//
+//   reduced motion: scroll-linked motion has no clock left to slow down, but
+//   resizing type under a moving finger is itself the motion some readers are
+//   asking us to drop. Under the query --nav-p snaps 0/1 on the old
+//   60/5 hysteresis instead of interpolating.
+
+export const DEFAULT_RAMP = 144;
+export const DEFAULT_MAX_STEP = 5;
+
+// ONE FRAME OF THE COLLAPSE, as a pure function of what the frame measured.
+//
+//   y             window.scrollY, already clamped at 0
+//   p             the progress published last frame, 0..1
+//   ramp          --nav-ramp in px
+//   maxPx         --nav-max-step in px of header travel per frame
+//   scrollHeight  document.documentElement.scrollHeight
+//   innerHeight   window.innerHeight
+//   reduce        prefers-reduced-motion matches
+//
+// Answers { p, settling }: the progress to publish, and whether the frame
+// clamp left it short of where the scroll position wants it (so the caller
+// must schedule another frame).
+export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, reduce }) {
+  // The height the document WOULD have with the navbar expanded. The
+  // add-back is the whole trick; see the guard note above.
+  var roomExpanded = scrollHeight - innerHeight + ramp * p;
+
+  // WHERE THE COLLAPSE WANTS TO BE, from scroll position alone.
+  var target;
+  var snap = false;
+  if (roomExpanded < ramp + 24) {
+    target = 0;
+    snap = true;
+  } else if (reduce) {
+    target = (p > 0 ? y > 5 : y > 60) ? 1 : 0;
+    snap = true;
+  } else {
+    var t = Math.min(1, y / ramp);
+    target = t * t * (3 - 2 * t);
+  }
+
+  // THE RATE LIMIT: how far the collapse may travel in ONE frame.
+  //
+  // Position-linked progress fixed motion that OUTLIVED the gesture. It
+  // also guaranteed the opposite defect: if scrollY moves 90px between
+  // two frames, so does the header's whole range. Measured in
+  // turf-monster at 390x844, worst single-frame header height change by
+  // scroll profile:
+  //
+  //     8px/frame (slow, deliberate)   3.9px
+  //    24px/frame (normal swipe)      14.1px
+  //    momentum flick                 39.0px   <- the ENTIRE collapse
+  //    hard flick                     39.0px
+  //
+  // So the TARGET stays position-linked and the STEP is clamped. What
+  // makes this safe is that a slow scroll never REACHES the clamp:
+  // under --nav-max-step of header travel per frame the branch below
+  // returns `target` untouched, so the slow feel is not approximated,
+  // it is the same arithmetic.
+  //
+  // maxStep is derived, not tuned per band: engine.css sizes --nav-ramp
+  // at 3x the band's collapse total, so a cap of MAX px/frame is
+  // 3*MAX/ramp in --nav-p units. Mobile (ramp 120) gives 4.9px/frame,
+  // desktop (ramp 144) 5.0px. Retune --nav-ramp without keeping that 3x
+  // relation and this cap silently drifts with it.
+  var next;
+  if (snap) {
+    // A guard refusal and a reduced-motion state are DECISIONS, not
+    // motion; ramping them would animate the very thing each exists to
+    // avoid.
+    next = target;
+  } else {
+    var maxStep = (3 * maxPx) / ramp;
+    var delta = target - p;
+    next = Math.abs(delta) <= maxStep
+      ? target
+      : p + (delta > 0 ? maxStep : -maxStep);
+  }
+
+  return { p: next, settling: !snap && next !== target };
+}
+
+// The shadow is the one thing still on a clock, and it may stay there:
+// box-shadow paints, it never reflows, so it cannot move content.
+// Hysteresis keeps it from strobing at the boundary.
+export function shadowLit(lit, y) {
+  return lit ? y > 5 : y > 60;
+}
+
+// --nav-ramp and --nav-max-step off the header's computed style, each with
+// its default when the band declares none.
+export function readTuning(style) {
+  var raw = parseFloat(style.getPropertyValue('--nav-ramp'));
+  var step = parseFloat(style.getPropertyValue('--nav-max-step'));
+  return {
+    ramp: raw > 0 ? raw : DEFAULT_RAMP,
+    maxPx: step > 0 ? step : DEFAULT_MAX_STEP
+  };
+}
+
+// THE BINDING: one header, its listeners, and the frame loop. The Stimulus
+// controller and the Alpine shim both drive this, so the two cannot drift.
+// onScrolled(lit) fires when the shadow's hysteresis flips.
+export class NavCollapse {
+  constructor(el, onScrolled) {
+    this.el = el;
+    this.onScrolled = onScrolled || function () {};
+    this.p = 0;
+    this.scrolled = false;
+    this.queued = false;
+    this.stopped = false;
+    this.tuning = { ramp: DEFAULT_RAMP, maxPx: DEFAULT_MAX_STEP };
+    this._reduce = null;
+    this._onScroll = this.onScroll.bind(this);
+    this._onResize = this.onResize.bind(this);
+    this._apply = this.apply.bind(this);
+  }
+
+  start() {
+    this.stopped = false;
+    this._reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+    this.tuning = readTuning(getComputedStyle(this.el));
+    this.apply();
+
+    window.addEventListener('scroll', this._onScroll, { passive: true });
+    window.addEventListener('resize', this._onResize, { passive: true });
+    if (this._reduce.addEventListener) this._reduce.addEventListener('change', this._apply);
+  }
+
+  // A Turbo visit tears the header down and builds a new one; without this
+  // every visit would stack another listener on window.
+  stop() {
+    this.stopped = true;
+    window.removeEventListener('scroll', this._onScroll);
+    window.removeEventListener('resize', this._onResize);
+    if (this._reduce && this._reduce.removeEventListener) {
+      this._reduce.removeEventListener('change', this._apply);
+    }
+  }
+
+  onScroll() {
+    if (this.queued) return;
+    this.queued = true;
+    requestAnimationFrame(this._apply);
+  }
+
+  onResize() {
+    this.tuning = readTuning(getComputedStyle(this.el));
+    this.onScroll();
+  }
+
+  apply() {
+    this.queued = false;
+    if (this.stopped) return;
+    // Clamped: rubber-band overscroll reports a NEGATIVE scrollY, and a
+    // negative progress inflates the navbar past its expanded size.
+    var y = Math.max(0, window.scrollY);
+    var frame = collapseFrame({
+      y: y,
+      p: this.p,
+      ramp: this.tuning.ramp,
+      maxPx: this.tuning.maxPx,
+      scrollHeight: document.documentElement.scrollHeight,
+      innerHeight: window.innerHeight,
+      reduce: this._reduce.matches
+    });
+
+    if (frame.p !== this.p) {
+      this.p = frame.p;
+      this.el.style.setProperty('--nav-p', frame.p.toFixed(4));
+    }
+
+    // KEEP FRAMES COMING WHILE CATCHING UP. Nothing else will schedule
+    // one: the finger is off, so no more scroll events arrive, and
+    // without this the collapse freezes wherever the clamp left it. It
+    // converges LINEARLY and lands exactly: about 8 frames (~133ms) at
+    // the mobile --nav-ramp of 120, and about 10 (~167ms) at the default
+    // 144, from a hard flick.
+    if (frame.settling) {
+      this.queued = true;
+      requestAnimationFrame(this._apply);
+    }
+
+    var lit = shadowLit(this.scrolled, y);
+    if (lit !== this.scrolled) {
+      this.scrolled = lit;
+      this.onScrolled(lit);
+    }
+  }
+}