studio-engine 0.72.2 → 0.73.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dffda6dc9fdd89e1770f0d456e28cfb9a674679d09bc1226816f3f30ed8cf255
-  data.tar.gz: ef6f36d167f21886920a64cbc687ca0981c49bfb93117050cb74cabf60e8e875
+  metadata.gz: 60486d6f2711eb8d61d258fa6305f05cfd2d85910858aacc1506dee587f3c114
+  data.tar.gz: beb3d3a69e3c01fca35a1196e37065b56b9b563696e2d7d3c6d15d5718440fd1
 SHA512:
-  metadata.gz: 56ce7f21bc05749d76d3a6325f040892ad288f4c82a1bef8e62d64cf0666cd3d88a019a9b9591a375a8d5519ce536d9d6e629ab8dda9f5faaf98b12da6019e8c
-  data.tar.gz: ef82414cc1ed55acf4d35ccafea238e4c2defe39a2ce684ad1fb5e18d8f47dc928b1f07ba015be1fee6b847f357225d2e073b638f03da335270638275bc87f4a
+  metadata.gz: c668f68df4d51e460a58a3bfb6b8608acb943b9ab75558b7676c9ed79489219e686249e45c20593ec97c70401ed34c9b8ce78fafb927201912c1d0e87012fd1e
+  data.tar.gz: f9f13b69c48bd71d7ad127e1229245a7079dd0155dcfd731fe3044b25fcd439217e6dd61ca3f33b4c73b065cd8d5629dacd500218ac1b27cd02270f528f78e3a

data/CHANGELOG.md

@@ -185,6 +185,61 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Changed
 
+- **The pinned stack composes itself, and publishes in the frame the change
+  happened.** `data-pin` layers now also publish `--pin-stack-bottom` (the bottom
+  of the whole stack) and `--pin-<name>-top` (the bottom of everything above that
+  layer), and the publisher writes them from inside its ResizeObserver callback
+  rather than deferring to `requestAnimationFrame`.
+
+  **THE DEFECT.** A frame runs `rAF -> style/layout -> ResizeObserver -> paint`,
+  so a write made in the frame callback lands at the top of the NEXT frame. Every
+  frame in which a pinned layer appeared or disappeared therefore painted with the
+  previous frame's number. Measured in isolation by toggling a layer's `display`
+  and sampling what the changing frame paints: rAF-deferred wrong on 8/8 changing
+  frames, synchronous wrong on 0/8. On mcritchie-studio's production
+  `/deployments` it showed as the board's swim-lane headers slamming 99px and back
+  on a page nobody was touching — parked at a fixed scroll offset with document
+  height, row position and nav height all constant, the header's `top` went
+  152 -> 53 -> 152 -> 53px in 240ms behind two Turbo broadcasts.
+
+  **AND CONSUMERS NO LONGER COMPOSE THE STACK.** `top: max(var(--pin-nav-bottom),
+  var(--pin-apps-bottom))` fails twice: it does not scale, because a fourth layer
+  means editing every consumer that ever wanted to sit under the stack; and it is
+  not sound, because a `max()` over two custom properties is only meaningful if
+  they were written in the same frame. `--pin-stack-bottom` is one value that
+  cannot disagree with itself. A layer that is ITSELF in the stack reads
+  `--pin-<name>-top` instead, which excludes its own edge — positioning off the
+  stack bottom would make it chase itself down the page. Stacking order is
+  document order, with `data-pin-order` overriding it for a layer whose DOM
+  position does not match where it sits on screen.
+
+  **THE REGISTRY IS DERIVED PER PUBLISH, never cached.** A Turbo Stream replaces a
+  pinned layer's node without a `turbo:load`, and a held reference then points at
+  the DETACHED predecessor, whose rect is all zeros — indistinguishable from a
+  layer that is legitimately hidden. Re-querying makes the stale reference
+  impossible rather than merely unlikely.
+
+  **THE COST, re-measured**, because the rule this reverses was itself justified by
+  a measurement (turf-monster, 6x CPU throttle, frames over 20ms 13/24 through the
+  collapse ramp vs 0/24 once the observer was coalesced). What was expensive there
+  was read-write thrash, not the observer: the publisher now takes one read pass
+  and one write pass per invocation, and in an RO callback layout is already clean,
+  so those reads force nothing. On the engine lab at the same 6x throttle, ~700
+  frames of ramp each way — `RO through rAF` median 8.3ms / p90 10.0ms / 0 frames
+  over 20ms; `RO synchronous` median 8.4-8.5ms / p90 11.0ms / 3-6 frames over 20ms;
+  ZERO frames over 32ms on either, so neither drops one.
+
+  **BACK-COMPAT.** `--nav-h`, `--nav-bottom` and `--pin-<name>-h` /
+  `--pin-<name>-bottom` publish exactly as before, from the same measurements, so
+  the 26 consumers across turf-monster, rolio and mcritchie-studio need no change
+  and no floor bump. A structural change (a Turbo patch, a fresh document, a layer
+  joining or leaving) now forces a full write, because the unchanged-write skip is
+  only safe while nothing else touches these properties — the lab caught
+  `--nav-h` staying empty through a re-scan on exactly the host-owned-header path
+  both live consumers use. The lane contract moves 131 -> 132
+  (`config/e2e_lane.yml`), re-derived with the lister.
+
+
 - **`Gemfile.lock` resolves solana-studio 0.5.7, and a gate now keeps it there.** The lock had sat on **0.5.3 for four patch releases** while BOTH consumers shipped 0.5.7 (turf-monster `~> 0.5.3`, mcritchie-studio `~> 0.5`). Nothing was red and nothing could have been: engine CI installs with `bundler-cache: true`, so it resolves from the lock and never fresh — the drift does not self-correct and never surfaces as flakiness. It matters because `test/views/style_web3_specimens_test.rb` exists to prove "the style guide renders the REAL gem cards" and reads them off whatever the LOCK resolved; four versions behind, that guard certifies a card no consumer receives. It still passes — only its MEANING changes. MEASURED on this span, the gem's whole `app/` tree was byte-identical 0.5.3 → 0.5.7 (only `CHANGELOG.md`, `README.md` and `version.rb` differ), so this instance cost nothing, which is exactly why it went four releases unnoticed.
 - **The constraint stays `>= 0.5.3`, deliberately.** 0.5.3 is a real FLOOR (0.5.2 shipped the credential partial without `solana_studio/modals/_wallet_connect`, which the web3 capability gate requires). Above it this engine claims no ceiling: it is the BASE half of the base/bolt-on split, and a pessimistic `~> 0.5.3` here would be NARROWER than mcritchie-studio's own `~> 0.5` — a dev-only dependency constraining a resolution it does not own. The defect was the LOCK, not the pin, so the fix is a gate rather than a tighter pin.
 - **`bin/gem-drift-check`** — fails when this engine's lock resolves a tracked gem OLDER than a consumer's, wired into `consumer-ci.yml` after the consumer bundle install. That lane is the only place two repos' lockfiles exist at once (engine at `studio/`, consumer beside it); `test/lib/consumer_ci_shard_contract_test.rb` records the same constraint for its own cross-repo contract. Direction is ONE-WAY on purpose: engine behind FAILS, engine level or ahead passes (the engine is the producer and may test an unreleased gem), and a consumer bundling no tracked gem is a SKIP, not a failure — `mcritchie_industries` is the base half working as designed. Stdlib-only, and it names its one-command remedy (`bundle update solana-studio`) in the failure.

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

@@ -182,186 +182,295 @@
   body { overflow-anchor: none; }
 </style>
 <script>
-  // studio-engine: publish the sticky header's live geometry as CSS custom
-  // properties so fixed/sticky elements can position off it without hardcoded
-  // px. Tracks every resize, including scroll-collapse animations, and
-  // re-attaches after Turbo nav.
+  // studio-engine: THE PINNED STACK. Publishes the live geometry of every layer
+  // of pinned page chrome as CSS custom properties, so anything fixed or sticky
+  // positions off it in CSS with no hardcoded px and no JS of its own.
   //
-  //   --nav-h      the header's HEIGHT
-  //   --nav-bottom the header's BOTTOM EDGE, in viewport coordinates
+  // A layer joins by carrying `data-pin="<name>"`. Nothing else is required:
+  // no registration call, no declared stacking order, no consumer edit.
   //
-  // They are equal only when the header sits at the top of the viewport, which
-  // is why one was long mistaken for the other. An app that stacks chrome ABOVE
-  // the header — an environment banner rendered before the navbar, as
-  // mcritchie-industries does — pushes the header down, and a `fixed` overlay
-  // positioned at --nav-h then rides UP over the header by exactly the height of
-  // that chrome. Use --nav-h to size something as tall as the header; use
-  // --nav-bottom to start something underneath it.
+  // WHAT A CONSUMER READS — prefer the first two; they are the reason this is a
+  // primitive rather than an arithmetic helper:
+  //
+  //   --pin-stack-bottom  the bottom of the WHOLE stack. What something sitting
+  //                       BENEATH all the pinned chrome positions off.
+  //   --pin-<name>-top    the bottom of everything ABOVE that layer. What a layer
+  //                       that is ITSELF in the stack positions off.
+  //   --pin-<name>-h      that layer's HEIGHT.
+  //   --pin-<name>-bottom that layer's own BOTTOM EDGE, in viewport coordinates.
+  //   --nav-h / --nav-bottom  the <header>'s height and bottom edge, under their
+  //                       legacy names, from the same measurement.
+  //
+  // DO NOT COMPOSE THE STACK IN A CONSUMER. `top: max(var(--pin-nav-bottom),
+  // var(--pin-apps-bottom))` is what this replaced, and it fails twice: it does
+  // not scale, because a fourth layer means editing every consumer that ever
+  // wanted to sit under the stack; and it is not sound, because a max() over two
+  // custom properties is only meaningful if they were written in the same frame.
+  // --pin-stack-bottom is one value that cannot disagree with itself.
+  //
+  // --nav-h AND --nav-bottom ARE NOT THE SAME NUMBER. They are equal only when
+  // the header sits at the top of the viewport, which is why one was long
+  // mistaken for the other. An app that stacks chrome ABOVE the header — an
+  // environment banner rendered before the navbar, as mcritchie-industries does —
+  // pushes the header down, and a `fixed` overlay positioned at --nav-h then
+  // rides UP over the header by exactly the height of that chrome. Use --nav-h to
+  // SIZE something as tall as the header; use --nav-bottom to START something
+  // underneath it. Same distinction for --pin-<name>-h vs --pin-<name>-bottom.
   (function () {
     if (!window.ResizeObserver) return;
     var ro = null;
     var queued = false;
-    var pins = [];
-    // The names this publisher has written, so a DEPARTED layer can be cleared.
-    var published = {};
-
-    // ONE MEASUREMENT PER ELEMENT PER FRAME, and every read before every write.
+    // WHAT WAS LAST PUBLISHED, per layer name: { h, bottom, top }. It does two
+    // jobs. It is the record of which names this publisher has written, so a
+    // DEPARTED layer can be cleared. And it is what lets an UNCHANGED value skip
+    // its write — these are INHERITED custom properties on documentElement, so
+    // even a write of the same number invalidates style for the whole document,
+    // and a scroll frame touches this four times per layer.
+    var last = {};
+    var lastStack = null;
+    // SKIPPING AN UNCHANGED WRITE IS ONLY SAFE WHILE NOTHING ELSE TOUCHES THESE
+    // PROPERTIES. On a scroll frame that holds, and skipping is most of why this
+    // is cheap. On a STRUCTURAL change it does not: a layer arriving or leaving,
+    // a Turbo patch, a fresh document — anything there may have cleared a
+    // property out from under the cache, and a skip would then never write it
+    // again. So a structural change forces a full write, once.
+    var forceWrite = true;
+    // The nodes currently under observation, held only to know what to unobserve
+    // when one departs. The REGISTRY ITSELF is never cached; see readPins().
+    var observed = [];
+
+    // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
     //
-    // publish() and publishPin() each kept reads-before-writes INTERNALLY, and
-    // that was not enough: the frame ran publish(current) — which WRITES two
-    // inherited custom properties on documentElement — and then the pin loop,
-    // whose first act is a getBoundingClientRect(). A read after a write to the
-    // root forces a fresh layout, so the thrash this file removed came straight
-    // back one function boundary over. Measured by review at 6x CPU throttle
-    // over 175 frames, pin loop on vs off: frames past 20ms 62 vs 42, median
-    // 17.7 vs 14.9ms, p90 34.2 vs 26.0ms; at 10x, 84/180 vs 4/180.
+    // This used to build a `pins` array once and hold each element by reference
+    // until something re-registered it. A Turbo Stream replaces a pinned layer's
+    // node WITHOUT a turbo:load, so between the patch and the re-scan the held
+    // reference pointed at the DETACHED predecessor — and a detached node's rect
+    // is all zeros, which is indistinguishable from a layer that is legitimately
+    // hidden. Measured on mcritchie-studio's /deployments: --pin-apps-bottom
+    // published 0px while the live strip stood at display:block, bottom 152px,
+    // and the board's lane headers slammed 99px up and back on every broadcast.
     //
-    // The header was also measured TWICE — once as `current`, once as pin
-    // `nav` — for values proven identical across 40 frames. It is a pin like
-    // any other now; the only thing special about it is that it ALSO writes the
-    // legacy --nav-h / --nav-bottom that studio/_sidebar_panel and
-    // turf-monster's scroll-margin-top already read.
-    function readPin(pin) {
-      return {
-        pin: pin,
-        h: pin.el.offsetHeight,
-        bottom: Math.max(0, pin.el.getBoundingClientRect().bottom)
-      };
-    }
-    function writeReading(r) {
-      var style = document.documentElement.style;
-      var pin = r.pin;
-      if (r.h !== pin.lastH) {
-        pin.lastH = r.h;
-        style.setProperty('--pin-' + pin.name + '-h', r.h + 'px');
-        if (pin.legacy) style.setProperty('--nav-h', r.h + 'px');
-      }
-      if (r.bottom !== pin.lastBottom) {
-        pin.lastBottom = r.bottom;
-        style.setProperty('--pin-' + pin.name + '-bottom', r.bottom + 'px');
-        if (pin.legacy) style.setProperty('--nav-bottom', r.bottom + 'px');
-      }
-    }
-    function publishAll() {
-      var readings = [];
-      var i;
-      for (i = 0; i < pins.length; i++) readings.push(readPin(pins[i]));
-      for (i = 0; i < readings.length; i++) writeReading(readings[i]);
-    }
-    function schedule() {
-      if (queued || !pins.length) return;
-      queued = true;
-      window.requestAnimationFrame(function () { queued = false; publishAll(); });
-    }
-    // ONE construction site. Two of them let attach() replace the observer that
-    // registerPins() had already put the pins on, silently dropping every live
-    // observation — caught by test_pins_share_one_observer_and_one_frame, which
-    // counts them for exactly that reason.
-    function ensureObserver() {
-      if (!ro) ro = new ResizeObserver(schedule);
-      return ro;
-    }
-    function registerPins() {
-      ensureObserver();
-      pins = [];
-      var seen = {};
+    // Re-querying costs one querySelectorAll over a handful of nodes per publish.
+    // That is cheaper than the class of bug it removes, because it makes a stale
+    // reference IMPOSSIBLE rather than merely unlikely: there is no window between
+    // a DOM patch and a re-scan in which this can be pointed at the wrong node.
+    function readPins() {
       var header = document.querySelector('header');
-      var headerPinned = false;
       var nodes = document.querySelectorAll('[data-pin]');
+      var list = [];
+      var headerPinned = false;
       for (var i = 0; i < nodes.length; i++) {
         var name = nodes[i].getAttribute('data-pin');
         // An unnamed pin would write `--pin--h`, a valid property name and a
         // silent nonsense one. Skip it rather than publish it.
         if (!name) continue;
-        seen[name] = true;
         if (nodes[i] === header) headerPinned = true;
-        pins.push({
-          el: nodes[i],
-          name: name,
-          // The header keeps publishing --nav-h / --nav-bottom, from the SAME
-          // measurement, so it is never measured twice.
-          legacy: nodes[i] === header,
-          lastH: null,
-          lastBottom: null
-        });
-        ro.observe(nodes[i]);
+        list.push(measure(nodes[i], name, nodes[i] === header));
+      }
+      // THE HOST-OWNED HEADER, and the back-compat promise that depends on it.
+      // A header that does not carry [data-pin] is not in the registry, so the
+      // legacy --nav-h / --nav-bottom — which studio/_sidebar_panel, turf's
+      // contest board and mcritchie-studio's heartbeat CSS all read — would
+      // never publish at all. Both live consumers own their header, so it is
+      // adopted as a pin even when it does not ask to be.
+      if (header && !headerPinned) list.push(measure(header, 'nav', true));
+      return list;
+    }
+
+    // ONE READ PER ELEMENT PER PUBLISH, and every read before every write.
+    // A read after a write to the root forces a fresh layout, which is the
+    // thrash this publisher exists without. Measured by review at 6x CPU
+    // throttle over 175 frames: frames past 20ms 62 vs 42, median 17.7 vs
+    // 14.9ms, p90 34.2 vs 26.0ms; at 10x, 84/180 vs 4/180.
+    function measure(el, name, legacy) {
+      // A hidden layer needs no special case: display:none gives offsetHeight 0
+      // and an all-zero rect, so it measures 0 and drops out of the stack on its
+      // own. That is what lets a layer come and go without anyone declaring a
+      // stacking order, and it is load-bearing rather than incidental.
+      var r = el.getBoundingClientRect();
+      return { el: el, name: name, legacy: legacy, h: el.offsetHeight, bottom: Math.max(0, r.bottom) };
+    }
+
+    // THE STACK, COMPOSED HERE RATHER THAN BY EVERY CONSUMER.
+    //
+    // Consumers used to write `top: max(var(--pin-nav-bottom), var(--pin-apps-bottom))`
+    // — every layer enumerated, in every consumer. That is two failures at once.
+    // It does not SCALE: a fourth pinned layer means editing every consumer that
+    // ever wanted to sit under the stack. And it is not SOUND: max() over two
+    // independently-written custom properties is only meaningful if they were
+    // written in the same frame, and any skew between them is expressed instantly
+    // as layout. Composing here means a consumer reads ONE value that cannot
+    // disagree with itself.
+    //
+    //   --pin-stack-bottom  the bottom of the WHOLE pinned stack. What something
+    //                       sitting beneath all the chrome positions off.
+    //   --pin-<name>-top    the bottom of everything ABOVE that layer. What a
+    //                       layer that is ITSELF in the stack positions off —
+    //                       --pin-stack-bottom would include the layer's own
+    //                       edge, so a layer positioned off it would chase itself
+    //                       down the page.
+    //
+    // ORDER is document order, which is the order the layers were declared and
+    // therefore the order they read in. `data-pin-order` overrides it for a layer
+    // whose DOM position does not match where it sits on screen; it is a plain
+    // number, lower is higher up, and it needs to exist on only the layer that
+    // disagrees rather than on all of them.
+    function order(p) {
+      var raw = parseFloat(p.el.getAttribute('data-pin-order'));
+      return isNaN(raw) ? null : raw;
+    }
+    function composed(pins) {
+      var i, j, stack = 0;
+      for (i = 0; i < pins.length; i++) {
+        if (pins[i].bottom > stack) stack = pins[i].bottom;
+        var above = 0;
+        for (j = 0; j < pins.length; j++) {
+          if (i === j) continue;
+          var oi = order(pins[i]), oj = order(pins[j]);
+          // Both ordered: compare the numbers. Otherwise fall back to document
+          // order, which querySelectorAll already returns them in.
+          var jIsAbove = (oi !== null && oj !== null) ? oj < oi : j < i;
+          if (jIsAbove && pins[j].bottom > above) above = pins[j].bottom;
+        }
+        pins[i].top = above;
+      }
+      return stack;
+    }
+
+    function write(pins, stack) {
+      var style = document.documentElement.style;
+      var seen = {};
+      var i, p, prev;
+      // A ROSTER CHANGE IS STRUCTURAL TOO, and it is not always announced by an
+      // event: an x-show that adds the node, a layer rendered by something other
+      // than a stream. Compare the names against what was published last.
+      var force = forceWrite;
+      forceWrite = false;
+      if (!force) {
+        for (i = 0; i < pins.length; i++) { if (!last.hasOwnProperty(pins[i].name)) { force = true; break; } }
       }
+      for (i = 0; i < pins.length; i++) {
+        p = pins[i];
+        seen[p.name] = true;
+        prev = last[p.name] || {};
+        if (force || p.h !== prev.h) {
+          style.setProperty('--pin-' + p.name + '-h', p.h + 'px');
+          if (p.legacy) style.setProperty('--nav-h', p.h + 'px');
+        }
+        if (force || p.bottom !== prev.bottom) {
+          style.setProperty('--pin-' + p.name + '-bottom', p.bottom + 'px');
+          if (p.legacy) style.setProperty('--nav-bottom', p.bottom + 'px');
+        }
+        if (force || p.top !== prev.top) style.setProperty('--pin-' + p.name + '-top', p.top + 'px');
+        last[p.name] = { h: p.h, bottom: p.bottom, top: p.top };
+      }
+      if (force || stack !== lastStack) {
+        style.setProperty('--pin-stack-bottom', stack + 'px');
+        lastStack = stack;
+      }
+
       // CLEAR WHAT LEFT. A layer goes away three ways: display:none and x-show
-      // both keep the node, so it measures 0 and drops out of a consumer's
-      // max() on its own. REMOVAL does not — nothing is left to measure, the
-      // last published value stands forever, and a consumer sits at the height
+      // both keep the node, so it measures 0 and drops out of the stack on its
+      // own. REMOVAL does not — nothing is left to measure, and without this the
+      // last published value stands forever while the consumer sits at the height
       // of a strip that is gone. Review measured a removed 300px strip holding
-      // --pin-apps-bottom at 300px against a real stack bottom of 160px: a
-      // permanent 140px error, and a direct contradiction of this primitive's
-      // headline promise.
-      for (var name2 in published) {
-        if (published.hasOwnProperty(name2) && !seen[name2]) {
-          document.documentElement.style.removeProperty('--pin-' + name2 + '-h');
-          document.documentElement.style.removeProperty('--pin-' + name2 + '-bottom');
+      // --pin-apps-bottom at 300px against a real stack bottom of 160px.
+      for (var name in last) {
+        if (last.hasOwnProperty(name) && !seen[name]) {
+          style.removeProperty('--pin-' + name + '-h');
+          style.removeProperty('--pin-' + name + '-bottom');
+          style.removeProperty('--pin-' + name + '-top');
+          delete last[name];
         }
       }
-      // THE HOST-OWNED HEADER, and the back-compat promise that depends on it.
-      //
-      // The registry is built from [data-pin], so a header that does not carry
-      // the attribute is not in it — and --nav-h / --nav-bottom, which are
-      // written from the legacy pin's reading, would never publish at all.
-      // THIS ENGINE'S navbar carries data-pin, so every test here and the whole
-      // e2e lab publish fine; the broken path exists only in a consumer that
-      // owns its header, which is BOTH live consumers:
-      //
-      //   turf-monster      layouts/_navbar.html.erb      (data-navbar-root)
-      //   mcritchie-studio  layouts/application.html.erb  (inline)
-      //
-      // Review measured it against turf's real header and its real sidebar
-      // declaration: --nav-h and --nav-bottom unset, the gear drawer 82px out
-      // of place, the contest board 114px, and neither tracking the collapse.
-      // Both apps pin a two-segment ~> under 1.0, so it would have landed on
-      // their next bundle update with no floor bump to warn anyone.
-      //
-      // So the header is adopted as a pin even when it does not ask to be. It
-      // still publishes --pin-nav-* under that name, which is what an app gets
-      // for free the moment it wants the general contract.
-      if (header && !headerPinned) {
-        pins.push({
-          el: header,
-          name: 'nav',
-          legacy: true,
-          lastH: null,
-          lastBottom: null
-        });
-        seen.nav = true;
-        ensureObserver().observe(header);
+    }
+
+    function publishAll() {
+      var pins = readPins();
+      write(pins, composed(pins));
+      syncObserver(pins);
+    }
+
+    // Observe whatever is pinned RIGHT NOW. observe() on an already-observed node
+    // is a no-op, so this only ever adds the new; unobserve() drops the departed
+    // so a replaced node cannot keep waking us from outside the document.
+    function syncObserver(pins) {
+      if (!pins.length) {
+        if (ro) { ro.disconnect(); ro = null; observed = []; }
+        return;
       }
+      if (!ro) ro = new ResizeObserver(onResize);
+      var i, next = [];
+      for (i = 0; i < pins.length; i++) { next.push(pins[i].el); ro.observe(pins[i].el); }
+      for (i = 0; i < observed.length; i++) {
+        if (next.indexOf(observed[i]) === -1) ro.unobserve(observed[i]);
+      }
+      observed = next;
+    }
 
-      published = seen;
+    // PUBLISH IN THE ResizeObserver CALLBACK, SYNCHRONOUSLY. This is the whole
+    // fix, and it is a statement about WHEN a frame does its work rather than
+    // about what this code computes.
+    //
+    // A frame runs: rAF callbacks -> style/layout -> ResizeObserver callbacks ->
+    // paint. This publisher used to be woken by the observer and then DEFER the
+    // write to requestAnimationFrame, which lands at the top of the NEXT frame —
+    // so the frame in which a layer actually appeared or disappeared painted with
+    // the previous frame's number, every time. The RO callback runs after layout
+    // and before paint, which is exactly the last moment a write can still land
+    // in the frame that caused it.
+    //
+    // A/B measured in isolation, toggling a pinned layer's display and sampling
+    // what the changing frame paints: rAF-deferred wrong on 8/8 changing frames,
+    // RO-synchronous wrong on 0/8.
+    //
+    // This cannot loop. The values written here move CONSUMERS, and a consumer is
+    // not a pin — nothing this writes resizes anything it observes. A pinned layer
+    // that positions off --pin-<name>-top MOVES without RESIZING, and the observer
+    // fires on size, so it settles in one pass rather than ringing.
+    // The one way a SYNCHRONOUS publish could misbehave: a consumer that both
+    // reads a published value and is itself a pin, sized off what it reads
+    // (`height: calc(100vh - var(--pin-apps-top))`). That resizes an observed
+    // node from inside the observer's own callback, and left alone the browser
+    // reports "ResizeObserver loop completed with undelivered notifications" and
+    // drops the frame. So re-entry is counted, and past a couple of settling
+    // passes this hands the rest to the frame callback: the pathological page
+    // degrades to the OLD one-frame-late behaviour instead of wedging, and the
+    // ordinary page never reaches the branch. Reset on the next frame, so the
+    // count measures one frame's settling rather than the session's.
+    var depth = 0, resetQueued = false;
+    function onResize() {
+      if (depth >= 3) { schedule(); return; }
+      depth++;
+      if (!resetQueued) {
+        resetQueued = true;
+        window.requestAnimationFrame(function () { resetQueued = false; depth = 0; });
+      }
       publishAll();
     }
-    // ATTACH IS NOW JUST A RE-SCAN. The header used to be tracked separately as
-    // `current`, with its own observe and its own publish; it is a pin named
-    // "nav" like any other, so registerPins() covers it. What survives is the
-    // release promise: a page with no pinned chrome at all disconnects the
-    // observer rather than leaving it on detached nodes, and the properties keep
-    // their last value rather than being driven to 0 by an all-zero rect.
-    //
-    // A page that never has a <header> is served too — the observer is built by
-    // ensureObserver() from registerPins(), not from a has-header branch. It was
-    // only reachable from that branch before, so pins on a headerless layout were
-    // permanently dead.
-    function attach() {
-      if (ro) ro.disconnect();
-      registerPins();
-      if (!pins.length && ro) { ro.disconnect(); ro = null; }
+
+    // SCROLL STILL NEEDS THE FRAME CALLBACK. A scroll changes a sticky header's
+    // bottom EDGE without changing its size, so the observer never sees it and
+    // there is nothing to be synchronous with — rAF is the right clock, and it
+    // coalesces the burst iOS momentum fires far above 60Hz.
+    function schedule() {
+      if (queued) return;
+      queued = true;
+      window.requestAnimationFrame(function () { queued = false; publishAll(); });
     }
-    document.addEventListener('DOMContentLoaded', attach);
-    document.addEventListener('turbo:load', attach);
-    // A Turbo Stream replaces nodes WITHOUT a turbo:load, which is how a
-    // captured pin goes stale. Re-register on the next frame, once the stream
-    // has actually patched the DOM.
+
+    function invalidate() { forceWrite = true; publishAll(); }
+    document.addEventListener('DOMContentLoaded', invalidate);
+    document.addEventListener('turbo:load', invalidate);
+    // A Turbo Stream replaces nodes WITHOUT a turbo:load. The registry is derived
+    // per publish, so a stale reference is no longer possible either way — but the
+    // OBSERVER still has to be moved onto the incoming node, and the stack has to
+    // be recomposed for a layer that arrived or left. Both happen in publishAll.
     document.addEventListener('turbo:before-stream-render', function () {
-      window.requestAnimationFrame(registerPins);
+      window.requestAnimationFrame(invalidate);
     });
-    // Registered ONCE at script eval, not inside attach(), so a Turbo nav
-    // re-scans instead of stacking another listener per visit.
+    // Registered ONCE at script eval, not inside a re-scan, so a Turbo nav
+    // re-publishes instead of stacking another listener per visit.
     window.addEventListener('scroll', schedule, { passive: true });
     window.addEventListener('resize', schedule, { passive: true });
   })();

data/app/views/solana_sessions/phantom_callback.html.erb

@@ -137,6 +137,68 @@
     dbg('  ' + key, truncate(val, 40));
   });
 
+  // === THE REDIRECT TRANSPORT'S RETURN LEG ==============================
+  //
+  // TRIED FIRST, AND EVERYTHING BELOW IS LEFT EXACTLY AS IT WAS. The legacy
+  // block that follows handles ONE step — Phantom's signIn — with keys named
+  // phantom_dl_*, and it is what production mobile sign-in runs on TODAY. It is
+  // not touched, moved, or reworded here: a consumer that has not yet adopted
+  // the new transport must behave identically after this change, and the only
+  // honest way to promise that is to leave its code alone.
+  //
+  // GUARDED THE WAY THIS CODEBASE GUARDS EVERY OPTIONAL CAPABILITY: a host that
+  // does not load solana_studio/wallet_ops.js + wallet_journal.js has no
+  // SolanaStudio.walletOps, so this branch never runs and the legacy path is
+  // the whole program. An absent capability must not default to the permissive
+  // branch — the same rule the wallet picker's canDeepLink learned.
+  //
+  // WHY THE PENDING-JOURNAL CHECK IS PART OF THE GUARD, not just the globals:
+  // a host may load the new scripts while a signIn started under the OLD keys
+  // is still in flight — a user mid-round-trip across a deploy. Requiring an
+  // actual wallet_dl journal means that user finishes on the path they started,
+  // rather than being handed to a resumer with nothing to resume.
+  //
+  // WHAT THIS BRANCH DOES NOT DO: decrypt, verify, or know what the user was
+  // trying to accomplish. walletOps owns the step machine and the registered
+  // intent owns the outcome. This is a seam, and keeping it a seam is what lets
+  // the same callback serve sign-in and a contest entry without learning either.
+  var studio = window.SolanaStudio;
+  var hasResumer = !!(studio && studio.walletOps && typeof studio.walletOps.resume === 'function' &&
+                      studio.walletJournal && typeof studio.walletJournal.peek === 'function');
+
+  if (hasResumer && studio.walletJournal.peek()) {
+    dbg('Transport', 'wallet_dl journal present — resuming through walletOps');
+
+    studio.walletOps.resume(params, {
+      navigate: function(url) { window.location.href = url; }
+    }).then(function(result) {
+      // SUSPENDED means resume already navigated to the next hop; this document
+      // is on its way out and must not also redirect, or the two race.
+      if (result && result.suspended) {
+        dbg('Transport', 'advanced to the next hop');
+        return;
+      }
+      if (result && result.done) {
+        dbg('Transport', 'intent complete');
+        // The registered intent owns where to land — it knows what the user was
+        // doing. Falling back to '/' rather than guessing a wallet-specific
+        // destination, which this file has no business knowing.
+        window.location.href = (result.value && result.value.redirect) || '/';
+        return;
+      }
+      // No pending request is a STATE, not a failure: a stale bookmark, a second
+      // tab, a reload after the journal was consumed. peek() said otherwise a
+      // moment ago, so this is a race, and the honest answer is to start over.
+      showError('No pending wallet request. Redirecting to login...');
+    }, function(err) {
+      // A user rejection arrives here with .rejected set — the wallet's own
+      // words, already mapped. Anything else is a genuine fault.
+      dbg('Transport ERROR', (err && err.message) || String(err));
+      showError((err && err.message) || 'Wallet request failed');
+    });
+    return;
+  }
+
   // Check for Phantom error
   if (params.get('errorCode')) {
     dbg('ERROR', 'errorCode=' + params.get('errorCode'));

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.72.2"
+  VERSION = "0.73.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.72.2
+  version: 0.73.0
 platform: ruby
 authors:
 - Alex McRitchie