studio-engine 0.62.6 → 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);
     }
@@ -320,6 +349,7 @@
       scrolled: false,
       p: 0,
       _ramp: 144,
+      _maxPx: 5,
       _reduce: null,
       _onScroll: null,
       _onResize: null,
@@ -332,8 +362,11 @@
         this._reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
 
         function readRamp() {
-          var raw = parseFloat(getComputedStyle(el).getPropertyValue('--nav-ramp'));
+          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() {
@@ -349,14 +382,61 @@
                              - window.innerHeight
                              + ramp * self.p;
 
-          var p;
+          // WHERE THE COLLAPSE WANTS TO BE, from scroll position alone.
+          var target;
+          var snap = false;
           if (roomExpanded < ramp + 24) {
-            p = 0;
+            target = 0;
+            snap = true;
           } else if (self._reduce.matches) {
-            p = (self.p > 0 ? y > 5 : y > 60) ? 1 : 0;
+            target = (self.p > 0 ? y > 5 : y > 60) ? 1 : 0;
+            snap = true;
           } else {
             var t = Math.min(1, y / ramp);
-            p = t * t * (3 - 2 * t);
+            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) {
@@ -364,6 +444,17 @@
             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.

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"