studio-engine 0.62.5 → 0.63.0

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

@@ -202,15 +202,33 @@
     var ro = null;
     var current = null;
     var queued = false;
+    var lastH = null;
+    var lastBottom = null;
     function publish(header) {
       var style = document.documentElement.style;
-      style.setProperty('--nav-h', header.offsetHeight + 'px');
+      // SKIP THE NO-OP WRITE. --nav-h and --nav-bottom are INHERITED custom
+      // properties on documentElement, so every write invalidates style for the
+      // whole document. Most republishes carry the same number — a scroll with
+      // the header already pinned, a resize that missed this element — and
+      // those cost nothing now.
+      // BOTH READS BEFORE EITHER WRITE. Writing a custom property on
+      // documentElement invalidates style, so a read taken after one write
+      // forces a fresh layout — the thrash this whole change exists to remove.
+      var h = header.offsetHeight;
       // Scroll-dependent where --nav-h is not: chrome above the header scrolls
       // away while an overlay is open (nothing here locks body scroll), so this
       // is republished on scroll. Clamped at 0 — once the sticky header is
       // pinned at top:0 the two values converge, which is why a consumer whose
       // header already starts at the viewport top sees no change at all.
-      style.setProperty('--nav-bottom', Math.max(0, header.getBoundingClientRect().bottom) + 'px');
+      var bottom = Math.max(0, header.getBoundingClientRect().bottom);
+      if (h !== lastH) {
+        lastH = h;
+        style.setProperty('--nav-h', h + 'px');
+      }
+      if (bottom !== lastBottom) {
+        lastBottom = bottom;
+        style.setProperty('--nav-bottom', bottom + 'px');
+      }
     }
     function schedule() {
       if (queued || !current) return;
@@ -231,7 +249,18 @@
       }
       current = header;
       if (ro) ro.disconnect();
-      ro = new ResizeObserver(function () { publish(header); });
+      // THROUGH schedule(), NOT STRAIGHT TO publish(). This callback used to
+      // call publish() directly, which was fine while the header only resized
+      // during a 300ms transition. navCollapse made it resize on EVERY scroll
+      // frame, and each direct publish forced layout and then wrote two
+      // inherited custom properties on documentElement. Measured in
+      // turf-monster at 6x CPU throttle: frames over 20ms were 13/24 THROUGH
+      // the collapse ramp versus 0/24 past it, median 26ms versus 8ms.
+      // Ablating this observer alone took it to 0/24 and median 13ms — it cost
+      // about 2.6x the reflow it was reacting to. schedule() already coalesces
+      // to one publish per frame and is what the scroll and resize listeners
+      // use; the ResizeObserver was the one path that bypassed it.
+      ro = new ResizeObserver(schedule);
       ro.observe(header);
       publish(header);
     }
@@ -244,6 +273,223 @@
   })();
 </script>
 
+<style>
+  /* studio-engine: --nav-p, the sticky header's COLLAPSE PROGRESS, 0 (expanded)
+     to 1 (collapsed). Third of the header properties published from this file,
+     and the only one that is an INPUT to the header rather than a measurement
+     of it — --nav-h and --nav-bottom above say how big it is, this says how far
+     through its collapse it has got.
+
+     REGISTERED, not merely declared. Untyped, `calc(3rem - 1rem * var(--nav-p))`
+     is invalid at computed-value time on a page that has never scrolled and
+     every collapsing dimension drops to its unstyled default; the <number> type
+     is what makes the arithmetic legal and the initial value real. Registration
+     also makes it INTERPOLABLE, which is how /navbar's Scrolled toggle animates
+     the whole collapse by transitioning one property. */
+  @property --nav-p {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 0;
+  }
+</style>
+<script>
+  // studio-engine: navCollapse — 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 `x-data="navCollapse()"` on the header,
+  // give each breakpoint band a `--nav-ramp`, and write the collapsing
+  // dimensions as calc()s off --nav-p. 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.
+  window.navCollapse = function () {
+    return {
+      scrolled: false,
+      p: 0,
+      _ramp: 144,
+      _maxPx: 5,
+      _reduce: null,
+      _onScroll: null,
+      _onResize: null,
+      _onReduce: null,
+      init: function () {
+        var self = this;
+        var el = this.$el;
+        var queued = false;
+
+        this._reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+        function readRamp() {
+          var style = getComputedStyle(el);
+          var raw = parseFloat(style.getPropertyValue('--nav-ramp'));
+          self._ramp = raw > 0 ? raw : 144;
+          var step = parseFloat(style.getPropertyValue('--nav-max-step'));
+          self._maxPx = step > 0 ? step : 5;
+        }
+
+        function apply() {
+          queued = false;
+          var ramp = self._ramp;
+          // 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);
+
+          // The height the document WOULD have with the navbar expanded. The
+          // add-back is the whole trick — see the guard note above.
+          var roomExpanded = document.documentElement.scrollHeight
+                             - window.innerHeight
+                             + ramp * self.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 (self._reduce.matches) {
+            target = (self.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
+          //
+          // 39px is the full 178 -> 139. It was found on a phone: slow
+          // scrolling looked right, a flick jumped. The measurements behind the
+          // original primitive all walked a constant 8px/frame, which is
+          // exactly the case that already worked.
+          //
+          // 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 p;
+          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.
+            p = target;
+          } else {
+            var maxStep = (3 * self._maxPx) / ramp;
+            var delta = target - self.p;
+            p = Math.abs(delta) <= maxStep
+              ? target
+              : self.p + (delta > 0 ? maxStep : -maxStep);
+          }
+
+          if (p !== self.p) {
+            self.p = p;
+            el.style.setProperty('--nav-p', 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 4 frames (~67ms) from
+          // a hard flick — rather than crawling asymptotically the way the
+          // 300ms ease this replaced did.
+          if (!snap && p !== target) {
+            queued = true;
+            requestAnimationFrame(apply);
+          }
+
+          // 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.
+          var lit = self.scrolled ? y > 5 : y > 60;
+          if (lit !== self.scrolled) self.scrolled = lit;
+        }
+
+        this._onScroll = function () {
+          if (queued) return;
+          queued = true;
+          requestAnimationFrame(apply);
+        };
+        this._onResize = function () { readRamp(); self._onScroll(); };
+        this._onReduce = apply;
+
+        readRamp();
+        apply();
+
+        window.addEventListener('scroll', this._onScroll, { passive: true });
+        window.addEventListener('resize', this._onResize, { passive: true });
+        if (this._reduce.addEventListener) this._reduce.addEventListener('change', this._onReduce);
+      },
+      destroy: function () {
+        // A Turbo visit tears the header down and builds a new one; without
+        // this every visit would stack another listener on window.
+        if (this._onScroll) window.removeEventListener('scroll', this._onScroll);
+        if (this._onResize) window.removeEventListener('resize', this._onResize);
+        if (this._reduce && this._reduce.removeEventListener && this._onReduce) {
+          this._reduce.removeEventListener('change', this._onReduce);
+        }
+      }
+    };
+  };
+</script>
+
 <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
 <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
 <% if Studio.sticky_table_headers %>

data/app/views/navbar/show.html.erb

@@ -7,7 +7,11 @@
     border: 2px solid var(--color-border-strong);
     border-radius: 0.5rem;
     pointer-events: none;
-    transition: width 0.15s ease;
+    /* --nav-p is a registered <number>, so the Scrolled toggle can TRANSITION
+       it directly — one interpolating property in place of the five
+       per-element font-size/width/padding transitions this block used to
+       carry. */
+    transition: width 0.15s ease, --nav-p 0.3s ease;
   }
   .navbar-preview header { position: static !important; }
 
@@ -18,19 +22,32 @@
   .navbar-preview.is-mobile .user-nav-col, .navbar-preview.is-mobile .user-nav-fit { padding-left: 0 !important; padding-right: 1rem !important; }
   .navbar-preview.is-mobile .nav-title { flex-direction: column !important; gap: 0 !important; line-height: 1.15 !important; }
   .navbar-preview.is-mobile .nav-title span:first-child { margin-bottom: -4px !important; }
-  .navbar-preview.is-mobile .nav-title span:last-child { font-size: 1.5rem !important; }
   .navbar-preview.is-mobile .nav-logo-link { gap: 0.5rem !important; }
 
+  /* Breakpoint simulation for the --nav-p sizes. The live navbar picks these
+     up from media queries in layouts/_navbar, which cannot fire for a
+     CONTAINER at a fixed viewport width — so the same calc()s are re-keyed on
+     the wrapper. They are the same expressions, not a second set of numbers:
+     retune the collapse and retune both, or the preview starts lying. */
+  .navbar-preview.is-mobile .nav-shell {
+    --nav-logo-size: calc(3rem - 0.5rem * var(--nav-p));
+  }
+  .navbar-preview.bp-tiny .nav-shell {
+    --nav-title-size: calc(1.1rem - 0.2rem * var(--nav-p));
+    --nav-title-lead-size: calc(1.3rem - 0.3rem * var(--nav-p));
+  }
+  .navbar-preview.bp-small .nav-shell {
+    --nav-title-size: calc(1.25rem - 0.25rem * var(--nav-p));
+    --nav-title-lead-size: calc(1.5rem - 0.35rem * var(--nav-p));
+  }
+
   /* Tiny (< 400px) */
-  .navbar-preview.bp-tiny .nav-title { font-size: 1.1rem !important; }
-  .navbar-preview.bp-tiny .nav-title span:last-child { font-size: 1.3rem !important; }
   .navbar-preview.bp-tiny .nav-logo-link { gap: 0.25rem !important; }
   .navbar-preview.bp-tiny .user-nav-col { width: 14rem !important; }
   .navbar-preview.bp-tiny .user-nav-fit { max-width: 14rem !important; }
   .navbar-preview.bp-tiny .username-cap { max-width: 5rem !important; }
 
   /* Small (400-767px) */
-  .navbar-preview.bp-small .nav-title { font-size: 1.25rem !important; }
   .navbar-preview.bp-small .user-nav-col { width: 15rem !important; }
   .navbar-preview.bp-small .user-nav-fit { max-width: 15rem !important; }
   .navbar-preview.bp-small .username-cap { max-width: 6rem !important; }
@@ -40,27 +57,14 @@
   .navbar-preview.is-desktop .user-nav-fit { max-width: 20rem !important; }
   .navbar-preview.is-desktop .username-cap { max-width: 7rem !important; }
 
-  /* Transitions for scrolled toggle */
-  .navbar-preview .nav-logo { transition: width 0.3s, height 0.3s; }
-  .navbar-preview .nav-title,
-  .navbar-preview .nav-title span:last-child { transition: font-size 0.3s; }
-  .navbar-preview .py-6 { transition: padding 0.3s; }
+  /* Scrolled state. The size half of this used to be TWELVE !important rules
+     restating every collapsed value; the toggle now just sets --nav-p: 1 on
+     the wrapper (below) and the shipped calc()s do the rest, so the preview
+     exercises the real rules instead of a parallel copy of them. What is left
+     is the shadow, which the live header gets from .is-scrolled and a preview
+     header (no x-data, so no `scrolled`) cannot. */
   .navbar-preview header { transition: box-shadow 0.3s, border-color 0.3s; }
-  .navbar-preview [data-balance-display] { transition: font-size 0.3s; }
-
-  /* Scrolled state: base (all breakpoints) */
   .navbar-preview.is-scrolled-preview header { box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); border-bottom: 1px solid var(--color-border-subtle); }
-  .navbar-preview.is-scrolled-preview .py-6 { padding-top: 0.5rem !important; padding-bottom: 0.5rem !important; }
-  .navbar-preview.is-scrolled-preview .nav-logo { width: 2rem !important; height: 2rem !important; }
-  .navbar-preview.is-scrolled-preview .nav-title { font-size: 1.25rem !important; }
-  .navbar-preview.is-scrolled-preview [data-balance-display] { font-size: 1.125rem !important; }
-
-  /* Scrolled state: mobile overrides */
-  .navbar-preview.is-mobile.is-scrolled-preview .nav-logo { width: 2.5rem !important; height: 2.5rem !important; }
-  .navbar-preview.bp-tiny.is-scrolled-preview .nav-title { font-size: 0.9rem !important; }
-  .navbar-preview.bp-tiny.is-scrolled-preview .nav-title span:last-child { font-size: 1rem !important; }
-  .navbar-preview.bp-small.is-scrolled-preview .nav-title { font-size: 1rem !important; }
-  .navbar-preview.bp-small.is-scrolled-preview .nav-title span:last-child { font-size: 1.15rem !important; }
 
   /* Slider with device marker */
   .slider-wrap { position: relative; }
@@ -139,7 +143,7 @@
                 Scrolled
               </button>
             </div>
-            <div class="navbar-preview <%= bp[:classes] %>" :class="scrolled && 'is-scrolled-preview'" :style="'width: ' + w + 'px'">
+            <div class="navbar-preview <%= bp[:classes] %>" :class="scrolled && 'is-scrolled-preview'" :style="'width: ' + w + 'px; --nav-p: ' + (scrolled ? 1 : 0)">
               <%= render "layouts/navbar", preview: true, show_logged_in: section[:show_logged_in] %>
             </div>
           </div>

data/app/views/studio/admin_models/_teams_table.html.erb

@@ -53,7 +53,7 @@
               <template x-teleport="body">
                 <div x-show="open"
                      x-cloak
-                     class="fixed inset-0 z-[130] flex items-center justify-center bg-black/70 p-4"
+                     class="fixed inset-0 z-[var(--z-lightbox)] flex items-center justify-center bg-black/70 p-4"
                      role="dialog"
                      aria-modal="true"
                      aria-label="<%= team.name %> JSON"

data/app/views/studio/banners/_app_banner.html.erb

@@ -41,7 +41,10 @@
   style = tones.fetch(tone)
 %>
 
-<div class="w-full" style="background:<%= style.fetch(:background) %>; color:<%= style.fetch(:color) %>; box-shadow:<%= style.fetch(:shadow) %>;">
+<%# studio-app-banner is the LIFT HOOK, not styling: engine.css raises the bars
+    above the modal backdrop while body.modal-open is set. Keep the class even if
+    the markup changes. %>
+<div class="studio-app-banner w-full" data-studio-app-banner style="background:<%= style.fetch(:background) %>; color:<%= style.fetch(:color) %>; box-shadow:<%= style.fetch(:shadow) %>;">
   <div class="max-w-7xl mx-auto flex items-center justify-between gap-3" style="<%= density_styles.fetch(density) %>">
     <span class="min-w-0 truncate"><%= message %></span>
     <% if actions.present? %>

data/app/views/studio/banners/_button.html.erb

@@ -66,8 +66,8 @@
     tooltip_content = capture do
 %>
       <span data-studio-banner-tooltip
-            class="pointer-events-none absolute right-0 top-full z-[140] mt-2 w-max max-w-[260px] whitespace-normal rounded bg-white px-3 py-2 text-xs font-semibold text-slate-900 opacity-0 shadow-lg ring-1 ring-black/10 transition-opacity duration-150 group-hover:opacity-100 group-focus-visible:opacity-100"
-            style="position:absolute; right:0; top:100%; z-index:140; margin-top:8px; max-width:260px; width:max-content; white-space:normal; border-radius:4px; background:#ffffff; color:#111827; padding:8px 12px; font-size:12px; font-weight:700; line-height:1.2; opacity:0; pointer-events:none; box-shadow:0 8px 18px rgba(0,0,0,0.18); transition:opacity 150ms ease;">
+            class="pointer-events-none absolute right-0 top-full z-[var(--z-tooltip)] mt-2 w-max max-w-[260px] whitespace-normal rounded bg-white px-3 py-2 text-xs font-semibold text-slate-900 opacity-0 shadow-lg ring-1 ring-black/10 transition-opacity duration-150 group-hover:opacity-100 group-focus-visible:opacity-100"
+            style="position:absolute; right:0; top:100%; z-index:var(--z-tooltip, 600); margin-top:8px; max-width:260px; width:max-content; white-space:normal; border-radius:4px; background:#ffffff; color:#111827; padding:8px 12px; font-size:12px; font-weight:700; line-height:1.2; opacity:0; pointer-events:none; box-shadow:0 8px 18px rgba(0,0,0,0.18); transition:opacity 150ms ease;">
         <%= tooltip %>
       </span>
 <%

data/app/views/studio/banners/_stack.html.erb

@@ -78,9 +78,17 @@
   any_bar = show_environment || show_impersonation
 %>
 <% if any_bar %>
-  <%# Normal flow, deliberately. No sticky, no z-index, no measured offset: the
-      navbar is the only pinned chrome, so the bars simply take their own height
-      above it. Not sticky also keeps the paint order right — the pinned navbar
-      is positioned, so it draws over these bars as they scroll up behind it. %>
+  <%# Normal flow, deliberately. No sticky, no measured offset: the navbar is the
+      only pinned chrome, so the bars simply take their own height above it. Not
+      sticky also keeps the paint order right — the pinned navbar is positioned,
+      so it draws over these bars as they scroll up behind it.
+
+      ONE exception, and it is scoped to the state that makes it free:
+      `body.modal-open .studio-bar-stack` in engine.css lifts the stack to
+      --z-banner, above the modal backdrop, so DEV MODE and the email chip stay
+      lit and clickable while a modal is up. It cannot cost the paint order
+      above, because the same class locks body scroll — the bars never move
+      relative to the navbar while the lift is on. Flow is still the resting
+      state; nothing here is positioned until a modal opens. %>
   <div class="studio-bar-stack w-full" data-studio-bar-stack><%= bars %></div>
 <% end %>

data/app/views/studio/modals/_host.html.erb

@@ -13,14 +13,53 @@
   for pages that drive a modal host WITHOUT rendering this partial —
   e.g. the living style guide's page-scoped dsModals host. The two are
   byte-identical; keep them in sync if you retune a curve or duration.
+
+  THREE CONSUMER EXTENSION POINTS, so an app never has to fork this file
+  to change an animation, a width, or register an app-wide modal:
+
+    window.ModalAnimations         per-modal enter/exit animation, merged
+                                   over the engine defaults (see below)
+    window.StudioModals.CARD_WIDTHS  per-modal card width by modal id,
+                                   merged the same way; DEFAULT_CARD_WIDTH
+                                   covers every id it does not name
+    app/views/modals/_host_extras  OPTIONAL app partial, rendered inside
+                                   the card on every render path through
+                                   this host — for a modal that belongs to
+                                   the app rather than to one call site
+
   Consumer integration example and API reference: the "Modal host"
   section of the gem README.
 %>
 <style>
   /* Scroll lock applied by $store.modals._sync() when the stack is non-empty.
-     Combined with the fixed backdrop on the host below, this keeps the
-     page beneath any modal from scrolling on wheel / touch / spacebar. */
-  body.modal-open { overflow: hidden; }
+     Combined with the fixed backdrop on the host below, this keeps the page
+     beneath any modal from scrolling on wheel / touch / spacebar — a claim that
+     was FALSE wherever this gem's link sidebar shipped, until the rule below
+     moved off body. */
+  /* THE SCROLL LOCK GOES ON THE ELEMENT THAT ACTUALLY SCROLLS.
+     Measured on a consumer, 2026-08-27, before this change: with a modal open a
+     real wheel gesture still scrolled the page (600px → 1000px) and the sticky
+     header unpinned and slid away with it. The lock had been inert there for as
+     long as the link sidebar had shipped.
+
+     `body { overflow: hidden }` locks the viewport only when it PROPAGATES to
+     it, and body's overflow propagates only while `html` is `overflow: visible`.
+     This gem's own link-sidebar partial sets `html { overflow-x: clip }` so the
+     off-canvas panel never flashes a scrollbar — correct on its own terms, clip
+     creates no scroll container — but it ends the propagation. The lock then
+     stopped locking the viewport and started making BODY a scroll container
+     instead: one holding scrollTop 0 forever while the viewport scrolled past
+     it. Every `position: sticky` child of body then has a scrollport that never
+     moves, which is why the header unpinned and why the modal-open banner lift
+     had nothing to pin against.
+
+     So lock `html`, and put body back to `visible` so it is not a second scroll
+     container. An app that sets no overflow on html is unaffected — locking html
+     is correct there too; it was simply never the only thing that worked.
+
+     :has() is the trigger because the class lands on body, not html. */
+  html:has(body.modal-open) { overflow: hidden; }
+  body.modal-open { overflow: visible; }
 
   /* Drain-bar keyframe used by studio/modals/blocks/_success_card when
      cta_drain is set — the CTA button hosts a translucent overlay that
@@ -195,6 +234,32 @@
       enter: Object.assign({}, animDefaults.enter, animOverrides.enter || {}),
       exit:  Object.assign({}, animDefaults.exit,  animOverrides.exit  || {})
     };
+
+    // Per-modal CARD WIDTH — the second consumer extension point, deliberately
+    // shaped like the animation one above so a consumer learns the pattern once.
+    // Define window.StudioModals.CARD_WIDTHS BEFORE this script runs, keyed by
+    // modal id, and app entries merge OVER the engine defaults (empty: the
+    // engine ships no per-id width, only the default below).
+    //
+    //   window.StudioModals = window.StudioModals || {};
+    //   window.StudioModals.CARD_WIDTHS = { 'wallet-setup': 'max-w-md' };
+    //
+    // BY MODAL ID, NOT BY PROP, and that is the whole reason this is a registry.
+    // A card opened from several places would have to carry the prop at every
+    // opener, and ONE miss renders the same card at two widths depending on how
+    // the user got there. The originating case is turf-monster's wallet-setup,
+    // opened from three (the board's entry gate, the onboarding chain driver,
+    // and the post-Connect reopen).
+    //
+    // Resolved in cardClasses(), NEVER written as a static class on the card
+    // element: exactly one max-w-* may land on that div, and a static class
+    // alongside a bound one leaves the winner to stylesheet source order, which
+    // is not something this file gets to decide.
+    window.StudioModals = window.StudioModals || {};
+    var widthOverrides = window.StudioModals.CARD_WIDTHS || {};
+    window.StudioModals.CARD_WIDTHS = Object.assign({}, widthOverrides);
+    window.StudioModals.DEFAULT_CARD_WIDTH =
+      window.StudioModals.DEFAULT_CARD_WIDTH || 'max-w-sm';
     // Late-binding guard: read window.ModalAnimations at CALL time, and
     // never return undefined. A consumer script that loads after this one
     // (e.g. an importmap module) may REPLACE the merged registry object
@@ -206,6 +271,17 @@
       return table[key] || table.pop || animDefaults[channel].pop;
     }
 
+    // Same late-binding guard as modalAnim, for the same reason and with one
+    // extra: a width that fails to resolve does not throw, it renders a
+    // FULL-BLEED card. A silent failure gets a literal floor, not a chance.
+    var DEFAULT_CARD_WIDTH = 'max-w-sm';
+    function modalCardWidth(id) {
+      var sm = window.StudioModals || {};
+      return (sm.CARD_WIDTHS && sm.CARD_WIDTHS[id]) ||
+             sm.DEFAULT_CARD_WIDTH ||
+             DEFAULT_CARD_WIDTH;
+    }
+
     // Where focus returns when the last modal closes. A module-level closure, NOT a
     // store property — see captureFocus below for why a DOM node must never live on
     // a reactive store.
@@ -624,6 +700,10 @@
           var c = this.current();
           if (!c) return {};
           var o = {};
+          // The card element carries no static max-w-*; this is the only
+          // one it ever gets. Set FIRST so the animation keys below, which
+          // never collide with a max-w-* name, read as additions to it.
+          o[modalCardWidth(c.id)] = true;
           if (!c._settled && !c._swappingIn && !c._swappingOut && !c._closing) {
             o[modalAnim('enter', c.props && c.props.enterAnim).cls] = true;
           }
@@ -712,7 +792,7 @@
       tabindex="-1" makes the backdrop programmatically focusable without adding it
       to the tab order. The name comes from props (ariaLabel, else title, else the
       modal id) so a screen reader never announces a bare unnamed dialog. %>
-  <div class="fixed inset-0 z-[120] flex items-center justify-center p-4 modal-backdrop-mount"
+  <div class="fixed inset-0 z-[var(--z-modal)] flex items-center justify-center p-4 modal-backdrop-mount"
        :class="$store.modals.current()?._closing && 'modal-backdrop-unmount'"
        style="background:rgba(0,0,0,0.6)"
        role="dialog"
@@ -744,12 +824,32 @@
         a dead end, since escape and click-outside are gated off. 100dvh, not 100vh:
         mobile browsers shrink the visual viewport when the URL bar is showing, and
         vh ignores that. %>
-    <div class="bg-surface rounded-xl border border-subtle shadow-2xl p-6 max-w-sm w-full max-h-[85dvh] overflow-y-auto"
+    <%# No max-w-* here — cardClasses() supplies exactly one, per modal id, from
+        the CARD_WIDTHS registry above. max-h/overflow are unrelated and stay. %>
+    <div class="bg-surface rounded-xl border border-subtle shadow-2xl p-6 w-full max-h-[85dvh] overflow-y-auto"
          :class="$store.modals.cardClasses()">
       <%# Consumer-provided content registrations. Each block typically
           contains a <template x-if="$store.modals.current().id === 'X'">
           render "modals/X" </template>. %>
       <%= yield if block_given? %>
+
+      <%# APP-WIDE modal registrations — the second seam. The block above is
+          per-CALLSITE: an app rendering this host from two layouts (a live one
+          and, say, an /admin preview harness) must repeat every registration in
+          both. A modal that belongs to the APP rather than to the page defines
+          app/views/modals/_host_extras.html.erb instead and is registered ONCE,
+          for every render path through this partial.
+
+          Convention, not a local, on purpose: a local would have to be passed at
+          each call site, which is the duplication this exists to remove. An app
+          that ships no such partial renders nothing and changes nothing.
+
+          It sits INSIDE the card, beside the block, because each registration is
+          a <template x-if> keyed on $store.modals.current().id — the outer
+          template x-if above is what guarantees current() is non-null here. %>
+      <% if lookup_context.exists?("host_extras", ["modals"], true) %>
+        <%= render "modals/host_extras" %>
+      <% end %>
     </div>
   </div>
 </template>

data/app/views/studio/modals/_scoped_host.html.erb

@@ -53,7 +53,30 @@
 <style>
   /* Scroll lock, applied by the store's _sync() while the stack is non-empty.
      Shipped here too because an app with no shared host never defines it. */
-  body.modal-open { overflow: hidden; }
+  /* THE SCROLL LOCK GOES ON THE ELEMENT THAT ACTUALLY SCROLLS.
+     Measured on a consumer, 2026-08-27, before this change: with a modal open a
+     real wheel gesture still scrolled the page (600px → 1000px) and the sticky
+     header unpinned and slid away with it. The lock had been inert there for as
+     long as the link sidebar had shipped.
+
+     `body { overflow: hidden }` locks the viewport only when it PROPAGATES to
+     it, and body's overflow propagates only while `html` is `overflow: visible`.
+     This gem's own link-sidebar partial sets `html { overflow-x: clip }` so the
+     off-canvas panel never flashes a scrollbar — correct on its own terms, clip
+     creates no scroll container — but it ends the propagation. The lock then
+     stopped locking the viewport and started making BODY a scroll container
+     instead: one holding scrollTop 0 forever while the viewport scrolled past
+     it. Every `position: sticky` child of body then has a scrollport that never
+     moves, which is why the header unpinned and why the modal-open banner lift
+     had nothing to pin against.
+
+     So lock `html`, and put body back to `visible` so it is not a second scroll
+     container. An app that sets no overflow on html is unaffected — locking html
+     is correct there too; it was simply never the only thing that worked.
+
+     :has() is the trigger because the class lands on body, not html. */
+  html:has(body.modal-open) { overflow: hidden; }
+  body.modal-open { overflow: visible; }
 </style>
 
 <script>
@@ -313,7 +336,7 @@
 </script>
 
 <template x-if="$store.<%= scoped_store %>.current()">
-  <div class="fixed inset-0 z-[120] flex items-center justify-center p-4 modal-backdrop-mount"
+  <div class="fixed inset-0 z-[var(--z-modal)] flex items-center justify-center p-4 modal-backdrop-mount"
        :class="$store.<%= scoped_store %>.current()?._closing && 'modal-backdrop-unmount'"
        style="background:rgba(0,0,0,0.6)"
        role="dialog"