studio-engine 0.62.6 → 0.64.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/solana_sessions/phantom_callback.html.erb

@@ -0,0 +1,343 @@
+<div class="flex flex-col items-center justify-center min-h-[60vh] px-4">
+  <div class="text-center">
+    <div id="phantom-spinner" class="inline-block w-10 h-10 border-4 border-primary border-t-transparent rounded-full animate-spin mb-4"></div>
+    <p id="phantom-status" class="text-secondary text-sm">Processing Phantom response...</p>
+    <p id="phantom-error" class="text-red-400 text-sm mt-2 hidden"></p>
+  </div>
+
+  <%# Visual debug log — NEVER rendered on a real production deploy. This sink printed
+      the dapp x25519 secret key (phantom_dl_secret) to the page and the console on every
+      mobile Phantom sign-in. Studio.wallet_debug_sink DEFAULTS TO OFF —
+      a sink that prints a signing key is opted into, not defaulted on. An app that
+      wants QA debugging back sets it to a predicate of its own (turf-monster:
+      -> { !AppFlags.live_production? }); Rails.env.production? will NOT do, because
+      a Heroku QA dyno runs RAILS_ENV=production. The script below
+      treats an absent sink as "debug off" and must stay null-safe: if this div is gone and
+      dbg() still touched logEl, the callback would throw and break sign-in outright. %>
+  <% if Studio.wallet_debug_sink? %>
+    <div id="phantom-log" class="mt-6 w-full max-w-lg text-left bg-surface-alt rounded-lg border border-subtle p-3 overflow-y-auto" style="max-height:50vh">
+      <p class="text-xs font-mono text-muted mb-2">Debug Log</p>
+    </div>
+  <% end %>
+</div>
+
+<script>
+(function() {
+  var logEl = document.getElementById('phantom-log');
+  // The sink is absent on a real production deploy (see the ERB guard above), and that
+  // absence IS the off switch — for the console too, not just the page.
+  var DEBUG_SINK = !!logEl;
+
+  function dbg(label, value) {
+    if (!DEBUG_SINK) { return; }
+    var line = document.createElement('p');
+    line.className = 'text-xs font-mono break-all mb-1';
+    if (label === 'ERROR' || label === 'CATCH') {
+      line.style.color = '#EF4444';
+    } else if (label === 'OK') {
+      line.style.color = '#4BAF50';
+    } else {
+      line.style.color = '#94a3b8';
+    }
+    var val = (value === undefined || value === null) ? '' : String(value);
+    line.textContent = label + (val ? ': ' + val : '');
+    logEl.appendChild(line);
+    logEl.scrollTop = logEl.scrollHeight;
+    console.log('[PhantomDL]', label, value);
+  }
+
+  function truncate(s, n) {
+    return s && s.length > n ? s.substring(0, n) + '...' : s;
+  }
+
+  dbg('Page loaded', new Date().toISOString());
+  dbg('URL', window.location.href);
+
+  // Self-contained Base58
+  var B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+  function b58encode(bytes) {
+    var digits = [0];
+    for (var i = 0; i < bytes.length; i++) {
+      var carry = bytes[i];
+      for (var j = 0; j < digits.length; j++) {
+        carry += digits[j] << 8;
+        digits[j] = carry % 58;
+        carry = (carry / 58) | 0;
+      }
+      while (carry) { digits.push(carry % 58); carry = (carry / 58) | 0; }
+    }
+    var str = '';
+    for (var i = 0; i < bytes.length && bytes[i] === 0; i++) str += '1';
+    for (var i = digits.length - 1; i >= 0; i--) str += B58[digits[i]];
+    return str;
+  }
+
+  function b58decode(str) {
+    var bytes = [];
+    for (var i = 0; i < str.length; i++) {
+      var idx = B58.indexOf(str[i]);
+      if (idx < 0) throw new Error('Invalid base58 character');
+      var carry = idx;
+      for (var j = 0; j < bytes.length; j++) {
+        carry += bytes[j] * 58;
+        bytes[j] = carry & 0xff;
+        carry >>= 8;
+      }
+      while (carry) { bytes.push(carry & 0xff); carry >>= 8; }
+    }
+    for (var i = 0; i < str.length && str[i] === '1'; i++) bytes.push(0);
+    return new Uint8Array(bytes.reverse());
+  }
+
+  var statusEl = document.getElementById('phantom-status');
+  var errorEl = document.getElementById('phantom-error');
+  var spinnerEl = document.getElementById('phantom-spinner');
+
+  function showError(msg) {
+    dbg('ERROR', msg);
+    spinnerEl.classList.add('hidden');
+    statusEl.classList.add('hidden');
+    errorEl.textContent = msg;
+    errorEl.classList.remove('hidden');
+    setTimeout(function() { window.location.href = '/signin'; }, 30000);
+  }
+
+  var ALL_KEYS = [
+    'phantom_dl_secret', 'phantom_dl_pubkey', 'phantom_dl_nonce', 'phantom_dl_nonce_at',
+    'phantom_dl_step', 'phantom_dl_link_mode', 'phantom_dl_cluster', 'phantom_dl_age_attested'
+  ];
+
+  // Keys whose VALUE must never be printed. ALL_KEYS above stays COMPLETE on purpose:
+  // cleanup() iterates it to REMOVE these from localStorage, so pruning the secret from
+  // it would leave the private key sitting on the device forever — a worse bug than the
+  // one this task fixes. Redact at the point of display instead.
+  var SECRET_KEYS = ['phantom_dl_secret'];
+
+  function cleanup() {
+    ALL_KEYS.forEach(function(k) { localStorage.removeItem(k); });
+  }
+
+  // Dump localStorage
+  dbg('--- localStorage ---');
+  ALL_KEYS.forEach(function(k) {
+    var v = localStorage.getItem(k);
+    var short = k.replace('phantom_dl_', '');
+    if (SECRET_KEYS.indexOf(k) !== -1) {
+      dbg('  ' + short, v ? '(present, ' + v.length + ' chars, redacted)' : '(empty)');
+    } else {
+      dbg('  ' + short, v ? truncate(v, 40) : '(empty)');
+    }
+  });
+
+  // Parse + dump URL params
+  var params = new URLSearchParams(window.location.search);
+  dbg('--- URL params ---');
+  params.forEach(function(val, key) {
+    dbg('  ' + key, truncate(val, 40));
+  });
+
+  // Check for Phantom error
+  if (params.get('errorCode')) {
+    dbg('ERROR', 'errorCode=' + params.get('errorCode'));
+    dbg('ERROR', 'errorMessage=' + params.get('errorMessage'));
+    cleanup();
+    showError('Phantom error: ' + (params.get('errorMessage') || 'Request rejected'));
+    return;
+  }
+
+  var step = localStorage.getItem('phantom_dl_step');
+  dbg('Step', step);
+
+  if (!step) {
+    showError('No pending Phantom request. Redirecting to login...');
+    return;
+  }
+
+  // Check nonce expiry
+  var nonceAt = parseInt(localStorage.getItem('phantom_dl_nonce_at') || '0');
+  var elapsed = Date.now() - nonceAt;
+  dbg('Nonce age', Math.round(elapsed / 1000) + 's');
+  if (elapsed > 270000) {
+    cleanup();
+    showError('Session expired. Please try again.');
+    return;
+  }
+
+  // Check nacl
+  dbg('nacl available', typeof nacl !== 'undefined');
+  if (typeof nacl === 'undefined') {
+    showError('TweetNaCl not loaded');
+    return;
+  }
+
+  // URL params from Phantom response
+  var phantomEncPubkeyB58 = params.get('phantom_encryption_public_key');
+  var dataParm = params.get('data');
+  var nonceParm = params.get('nonce');
+
+  dbg('Has phantom_encryption_public_key', !!phantomEncPubkeyB58);
+  dbg('Has data', !!dataParm);
+  dbg('Has nonce', !!nonceParm);
+
+  if (!phantomEncPubkeyB58 || !dataParm || !nonceParm) {
+    cleanup();
+    showError('Missing Phantom response parameters');
+    return;
+  }
+
+  try {
+    // Recover dapp secret key from localStorage
+    var dappSecretKey = b58decode(localStorage.getItem('phantom_dl_secret'));
+    dbg('Dapp secret key bytes', dappSecretKey.length);
+
+    // Compute shared secret (Diffie-Hellman)
+    var phantomPubBytes = b58decode(phantomEncPubkeyB58);
+    dbg('Phantom pubkey bytes', phantomPubBytes.length);
+    var sharedSecret = nacl.box.before(phantomPubBytes, dappSecretKey);
+    dbg('OK', 'Shared secret computed, ' + sharedSecret.length + 'B');
+
+    // Decrypt response
+    var data = b58decode(dataParm);
+    var nonce = b58decode(nonceParm);
+    dbg('Decrypt', 'data=' + data.length + 'B nonce=' + nonce.length + 'B');
+
+    var decrypted = nacl.box.open.after(data, nonce, sharedSecret);
+    if (!decrypted) throw new Error('Decryption failed — nacl.box.open.after returned null');
+
+    var responseText = new TextDecoder().decode(decrypted);
+    dbg('OK', 'Decrypted ' + responseText.length + ' chars');
+
+    var response = JSON.parse(responseText);
+
+    // Log ALL response fields for debugging
+    dbg('=== RESPONSE FIELDS ===');
+    var keys = Object.keys(response);
+    dbg('Keys', keys.join(', '));
+    keys.forEach(function(k) {
+      var v = response[k];
+      if (typeof v === 'string') {
+        dbg('  ' + k, truncate(v, 50));
+      } else if (typeof v === 'object' && v !== null) {
+        dbg('  ' + k, JSON.stringify(v).substring(0, 80));
+      } else {
+        dbg('  ' + k, String(v));
+      }
+    });
+
+    // Extract wallet address
+    var walletPubkey = response.address || response.public_key;
+    dbg('Wallet', walletPubkey);
+
+    if (!walletPubkey) {
+      throw new Error('No wallet address in response');
+    }
+
+    // Extract signature and signed message (SIWS response)
+    var signatureB58 = response.signature;
+    var signedMessageB58 = response.signed_message || response.signedMessage;
+    var outputB58 = response.output;
+
+    dbg('signature', truncate(signatureB58, 30));
+    dbg('signedMessage', truncate(signedMessageB58, 30));
+    dbg('output', truncate(outputB58, 30));
+
+    // Decode the signed message to UTF-8 text (server expects the raw message string)
+    var message = null;
+    if (signedMessageB58) {
+      var msgBytes = b58decode(signedMessageB58);
+      message = new TextDecoder().decode(msgBytes);
+      dbg('Message text', truncate(message, 60));
+    }
+
+    // If no signature in response, show debug info and stop
+    if (!signatureB58) {
+      dbg('ERROR', 'No signature field in response — signIn may not return SIWS data');
+      dbg('Full response', responseText.substring(0, 200));
+      showError('No signature in Phantom response. See debug log.');
+      return;
+    }
+
+    if (!message) {
+      // Try to reconstruct message from our stored data
+      var serverNonce = localStorage.getItem('phantom_dl_nonce');
+      var domain = window.location.host;
+      // OPSEC-005: include `User-ID: <id>` when we were linking — mirrors
+      // the statement we built in startPhantomDeepLink so the server's
+      // session-binding check passes.
+      var storedUserId = localStorage.getItem('phantom_dl_user_id');
+      var storedLinkMode = localStorage.getItem('phantom_dl_link_mode') === 'true';
+      var statementLine = <%= Studio.wallet_sign_in_statement.to_json.html_safe %>;
+      if (storedLinkMode && storedUserId) {
+        statementLine += '\nUser-ID: ' + storedUserId;
+      }
+      message = domain + ' wants you to sign in with your Solana account:\n' +
+        walletPubkey + '\n\n' + statementLine + '\n\nNonce: ' + serverNonce;
+      dbg('Reconstructed message', truncate(message, 60));
+    }
+
+    var linkMode = localStorage.getItem('phantom_dl_link_mode') === 'true';
+    var verifyUrl = linkMode ? '/account/link_solana' : '/auth/solana/verify';
+    var csrfToken = document.querySelector('meta[name="csrf-token"]');
+
+    dbg('Verify URL', verifyUrl);
+    dbg('CSRF token', !!csrfToken);
+    dbg('POSTing to verify...');
+    statusEl.textContent = 'Logging in...';
+
+    fetch(verifyUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken ? csrfToken.content : ''
+      },
+      body: JSON.stringify({
+        message: message,
+        signature: signatureB58,
+        pubkey: walletPubkey,
+        // Legal-age attestation, stashed by the Connect Wallet picker before
+        // the deep-link round trip (undefined is dropped by JSON.stringify).
+        age_attestation: (!linkMode && localStorage.getItem('phantom_dl_age_attested') === '1') ? '1' : undefined,
+        // Hardcoded, and correctly so: this whole page exists to service the
+        // PHANTOM mobile deep link (phantom_dl_*), so the brand is a property of
+        // the route rather than something to detect. A user arriving here signed
+        // in the Phantom app.
+        wallet_provider: 'phantom'
+      })
+    })
+    .then(function(r) {
+      dbg('Verify status', r.status);
+      return r.json();
+    })
+    .then(function(result) {
+      dbg('Verify result', JSON.stringify(result));
+      if (result.success) {
+        cleanup();
+        // Guarded, matching studio/modals/_wallet_connect two files over. An app
+        // that does not define this hook would otherwise throw HERE — after a
+        // successful verify, with the session already set — so the user is
+        // signed in and the page dies before redirecting. The engine cannot
+        // require a hook it does not ship.
+        if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
+        dbg('OK', 'Login success! Redirecting...');
+        window.location.href = result.redirect || '/';
+      } else {
+        cleanup();
+        dbg('ERROR', 'Verify failed: ' + (result.error || JSON.stringify(result)));
+        showError(result.error || 'Verification failed');
+      }
+    })
+    .catch(function(err) {
+      dbg('ERROR', 'Fetch error: ' + err.message);
+      cleanup();
+      showError('Verification failed: ' + err.message);
+    });
+
+  } catch (e) {
+    dbg('CATCH', e.message);
+    dbg('CATCH', e.stack || '(no stack)');
+    cleanup();
+    showError(e.message || 'Something went wrong');
+  }
+})();
+</script>

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 %>