studio-engine 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d497957db77f7b61823d1d12422672bf4339d71381163b79a6c42d705abf3492
-  data.tar.gz: e31717daca9b7722e4b9e87d44a507d9ec8c8055421e192bb3de78aa31175542
+  metadata.gz: bb273757252724d41962bac1a7c6318c0d04006ff41c1ba29735ad413c0b57fc
+  data.tar.gz: 618a5a39311ac9a316c649a502b44fa6540e8dc70c776fc3c3b2c17455473479
 SHA512:
-  metadata.gz: 6f75c493e66ebae0fd31571d237fa6a4f1546e9c50143382a4f54bfe88d5614c1f582af6d758cafe93ffc47b744b01d875a280de92823012bf224f028859627d
-  data.tar.gz: dfa14e14dbe5796816a0247bd965da477b69e27e8c81750f554e1d2d497fbf486da5d14f1ae900aa26b28dcfe22c14a51f2e83ead2089d98f9667b0142d43b6d
+  metadata.gz: 9b7bcf2d4dca51566942a2179a6f06e6c4a70293acab99b5a747a76785d9cba69cf51e4992e02410e82e9602f6c317605866ed1bd5b59bbf452954eae5d620aa
+  data.tar.gz: 1136131a5250c8a014edeb8ddd602c23dced903a82b99d3c57eb3bf27dd2394b735c993d08a559ff6132b8ffcdf337a4d6a91d8f4396ef8ab83c7679b7e2c4d7

data/CHANGELOG.md

@@ -2,7 +2,41 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
-## Unreleased
+## 0.39.0 — 2026-08-11
+
+### Removed
+
+- **`--studio-bars-h` is gone.** 0.33 advertised this CSS custom property as the
+  contract between the bar stack and a consumer's navbar, and the navbar's
+  sticky `top` read it. It no longer exists: the stack now sits in normal flow
+  directly above the navbar and simply occupies its own height, so a navbar
+  sticky at `top: 0` starts underneath the bars with nothing to compute.
+
+  **No consumer breaks.** A navbar still spelling `top: var(--studio-bars-h,
+  0px)` resolves to its `0px` fallback — exactly where the new layout wants it —
+  so an adopting app self-heals with no change. Verified against
+  `mcritchie-studio` (which carries that spelling) and `turf-monster` (which
+  never adopted the stack).
+
+### Fixed
+
+- **The navbar no longer jumps on load or navigation.** The removed property was
+  published twice and the two publishers could disagree: the server rendered an
+  ESTIMATE (bar count × a fixed unit) and a `ResizeObserver` then MEASURED the
+  real height and overwrote it. The header painted at the estimate and moved
+  when the measurement landed, moved again whenever a webfont changed a bar's
+  real height, and during a view transition the outgoing and incoming headers
+  composited at two different tops — so the navbar visibly drew twice. A
+  position only CSS can set cannot disagree with itself.
+
+  The estimate, the `ResizeObserver`, and the inline `<style>`/`<script>` the
+  stack used to emit are all gone. Reported from QA by the operator.
+
+  **Trade, recorded deliberately:** the bars now scroll away rather than
+  pinning. Two pinned siblings of unknown height cannot stack in CSS alone —
+  one must measure the other, and that measurement *is* the defect.
+
+## 0.38.0 — 2026-08-10
 
 **The email registry becomes the email catalog.** 0.37 gave every app a shared
 page for its transactional email banners. This folds in the rest — **what each

data/app/views/layouts/_navbar.html.erb

@@ -38,13 +38,15 @@
 %>
 
 <header x-data="{ scrolled: false }" <%= '@scroll.window="scrolled = scrolled ? (window.scrollY > 5) : (window.scrollY > 60)"'.html_safe unless is_preview %>
-        <%# top offsets by whatever studio/banners/_stack rendered above us. The
-            stack publishes --studio-bars-h on :root; with no stack the fallback
-            0px makes this identical to the old `top-0`, so an app that has not
-            adopted the stack is unaffected. The navbar never learns WHICH bars
-            rendered — only how tall they are. %>
-        style="<%= "top:var(--studio-bars-h, 0px);" unless is_preview %>"
-        class="<%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky z-50 bg-page transition-shadow duration-300" %>"
+        <%# top-0, a STATIC value, and never a custom property. Any bars render as
+            this header's sibling in normal flow (studio/banners/_stack), so they
+            already occupy their own height above it and there is nothing to
+            offset by. An offset read from a runtime-published property is what
+            made this header jump: it painted at a server estimate, moved when the
+            measurement landed, moved again on a webfont swap, and drew twice
+            during a view transition composited at two different tops. Only CSS
+            can set this top now, so none of that is reachable. %>
+        class="<%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 z-50 bg-page transition-shadow duration-300" %>"
         :class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'">
   <style>
     .user-nav-col { width: 14rem; }

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

@@ -24,9 +24,12 @@
     }
   }
 
-  # INTRINSIC height — content decides, and studio/banners/_stack MEASURES the
-  # result. An earlier cut declared a fixed height so the stack could compute its
-  # total server-side; that was rejected deliberately, because it cannot express
+  # INTRINSIC height — content decides, and the LAYOUT absorbs the result: the
+  # stack sits in normal flow, so a bar simply occupies the height it needs and
+  # nothing has to measure it. (It once did measure, publishing --studio-bars-h;
+  # that jumped, and 0.39.0 removed it.) An earlier cut declared a fixed height
+  # so the stack could compute its total server-side; that was rejected
+  # deliberately — and the reason still holds — because it cannot express
   # a bar that needs to be taller, or two bars stacked, without every consuming
   # app being reworked. The apps should respond to what the bar needs, not the
   # other way round.

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

@@ -12,22 +12,31 @@
   0, 1 or 2, and growing. Nesting each new bar inside the navbar coupled two
   unrelated components and meant every new bar edited the navbar. Here the bars
   do not know the navbar exists, and the navbar does not know which bars
-  rendered — only how tall they are, via --studio-bars-h.
+  rendered — it simply starts below whatever space they take.
 
-  HOW THE HEIGHT IS KNOWN. The stack MEASURES itself and publishes the result, so
-  a bar that needs to be taller — or a second bar, or a third — just works, and no
-  consuming app is reworked to allow it. The apps respond to what the bars need.
+  HOW THE SPACE IS RESERVED. By the LAYOUT, and by nothing else. The stack sits
+  in normal flow directly above the navbar, so the bars occupy their own height
+  the way any block does, and the navbar — sticky at top:0 — starts underneath
+  them with no offset to compute. A taller bar, or a second, or a third, simply
+  takes more room and pushes the navbar down. Nothing measures, nothing
+  publishes, nothing repaints.
 
-  A server-rendered estimate (count × --studio-bar-unit) paints first so the
-  common case has no flash, then a ResizeObserver replaces it with the truth on
-  the same frame. An earlier cut declared a fixed bar height to avoid the
-  observer; that was rejected because it could only ever express the standard
-  case, which is the case that needed no help.
+  This replaced a measured custom property (--studio-bars-h: a server-rendered
+  estimate of count times a fixed unit, overwritten by a ResizeObserver reading
+  the real height). It worked, and it JUMPED: the header painted at the estimate
+  and moved when the measurement landed, then moved again whenever a webfont
+  changed the bar's real height — and during a view transition the outgoing and
+  incoming headers composited at two different tops, so the navbar visibly drew
+  twice. A position that only CSS can set cannot do any of that.
 
-  The property is published on :root from an inline <style>, deliberately. A
-  custom property set on this element would be invisible to the navbar, because
-  custom properties inherit DOWN, not ACROSS to siblings — and putting it on
-  <body> would need every host to change its layout.
+  THE TRADE, recorded so it is a decision and not a regression: the bars scroll
+  away with the page instead of pinning. Only the navbar stays. Two pinned
+  siblings of unknown height cannot stack in CSS alone — one has to measure the
+  other — so pinning the bars is what cost the offset variable. The navbar keeps
+  its pin; the bars are ambient labels, seen on every page load because a Turbo
+  visit lands at the top. An overlay that must clear the chrome should position
+  off --nav-bottom (published in layouts/studio/_head), which already reports the
+  header's live bottom edge and accounts for chrome above it.
 
   Locals (all optional):
     preview      — true inside a navbar-preview render; renders nothing, so a
@@ -61,42 +70,17 @@
     end
   end
 
-  # count { } and not count(true): show_impersonation is a truthy USER, not the
-  # literal true, and count(true) compares with ==. That published a one-bar
-  # height for a two-bar stack — the navbar would have sat under a bar.
-  bar_count = [show_environment, show_impersonation].count { |bar| bar }
+  # No count is kept. The old code counted bars to compute an offset, and had to
+  # use count { } rather than count(true) because show_impersonation is a truthy
+  # USER object, not the literal true — a mistake that once published a one-bar
+  # height for a two-bar stack. Normal flow needs no count at all: whatever
+  # rendered takes the room it needs.
+  any_bar = show_environment || show_impersonation
 %>
-<% if bar_count.positive? %>
-  <%# First-paint estimate only — the observer below replaces it with the measured
-      height. Expressed against a token so an app that retunes the unit still gets
-      a sensible pre-measurement value. %>
-  <%= tag.style safe_join([":root{--studio-bars-h:calc(#{bar_count} * var(--studio-bar-unit, 47px))}"]) %>
-  <div class="studio-bar-stack sticky top-0 z-[60] w-full" data-studio-bar-stack><%= bars %></div>
-  <script>
-    // Publishes the stack's REAL height, so the navbar offsets by what the bars
-    // actually need. Idempotent and re-bound on Turbo navigation — a stale
-    // observer pointed at a detached node silently stops updating, and the
-    // navbar would then sit at yesterday's offset.
-    (function () {
-      var apply = function () {
-        var el = document.querySelector("[data-studio-bar-stack]");
-        if (!el) {
-          document.documentElement.style.removeProperty("--studio-bars-h");
-          return;
-        }
-        if (window.__studioBarObserver) window.__studioBarObserver.disconnect();
-        var publish = function () {
-          var h = Math.round(el.getBoundingClientRect().height);
-          if (h > 0) document.documentElement.style.setProperty("--studio-bars-h", h + "px");
-        };
-        publish();
-        if (window.ResizeObserver) {
-          window.__studioBarObserver = new ResizeObserver(publish);
-          window.__studioBarObserver.observe(el);
-        }
-      };
-      apply();
-      document.addEventListener("turbo:load", apply);
-    })();
-  </script>
+<% 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. %>
+  <div class="studio-bar-stack w-full" data-studio-bar-stack><%= bars %></div>
 <% end %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.38.0"
+  VERSION = "0.39.0"
 end

metadata

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