studio-engine 0.111.0 → 0.111.1.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d7cabff315fe9d235009b89cffbc4409acdec4cb52b5e99f750dbc09a10b2ba
-  data.tar.gz: 4f7b337c79de43cc0c1269570f0bc2947f8e55ceccef13281e2494ee85e70178
+  metadata.gz: 650a35a39685ece1959d6a403014344875cfd107f28dee2bd0594a66667592f3
+  data.tar.gz: 413b0ffb720c3da0e51327700723b126fb6cc88d7404543bdbccde28764e4a21
 SHA512:
-  metadata.gz: a5a8f42972f22be43ad7e325b629bf7d2b5b4e374ffee170e531b0d6c730dbadecd96cebc5f8b36d7024dd476bbd424ee27892b9423c9d5af2f4ce5a2d8b1e19
-  data.tar.gz: 187c2bb411cc2f2a1312379e6998879f44f13bedcdbb5e2fe7d92ca94a11795c89a187d2c36d616ca72bfe3424a361ed1f9d308ac879418d8ebaca6f4e87fbe5
+  metadata.gz: 8ffc0f710b353aea044308e4e16a687915e120dfee1950aa52c79c7be656a8b2a68d92df9c453182f2dd6b82980428ee0e7d2a4fc433ed20dfa1aeadd47c722d
+  data.tar.gz: bc4149aecbb0ac3c38a3905dec253d44c30459d0b9ba4a624bf18abbdc05613c568015fd4ce827d6d2dc39576b1de6bc244ab989ba56df9e5b875ba93229917b

data/CHANGELOG.md

@@ -4,6 +4,40 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.111.1 — 2026-10-16
+
+### Added
+
+- **A live read of the pinned stack for scripts.** `studio/pinned_stack`
+  exports `stackBottom()` and `stackReading()`, and sets
+  `window.studioPinnedStack` (`bottom()`, `read()`), measured on call from the
+  same reading the publisher makes. The root's `--pin-stack-bottom` can lag a
+  scroll by up to 160ms (in motion only CSS readers are written), so a script
+  reading it mid-scroll got a stale edge; Cyvasse's phone dock did.
+  `docs/NAVBAR_SETUP.md`, *Reading the Pinned Stack*.
+- **`data-pin-edge`**: a fixed reader of the stack follows the header's edge on
+  the scroll timeline, in CSS. `components/_sidebar_panel` carries it.
+
+### Changed
+
+- **On a scroll-timeline header the pinned stack writes nothing per scroll
+  frame.** The compact bar does not move while the page scrolls, so the stack
+  publishes where its layers sit once pinned, and writes on a resize, a band
+  re-measure (`studio/nav_collapse` fires `studio:pinned-stack-refresh`) or a
+  change of layers only. Sticky readers sit at the compact bar; the follower
+  write path goes unused there. The publisher marks the root
+  `data-pin-timeline` and publishes `--pin-stack-travel` while it is on.
+
+### Fixed
+
+- **A timeline header resized across 768px while scrolled no longer collapses
+  above the window.** The resize queued a frame on the `--nav-p` path, the
+  query's change then swapped to the scroll timeline, and the frame wrote
+  `--nav-p` onto the timeline header and eased it to 1: a 48px box translated
+  up by the band. `studio/nav_collapse` now cancels that frame on the swap, and
+  its frame writes nothing in timeline mode. Narrowing while scrolled hands the
+  header back to a live `--nav-p` path.
+
 ## 0.111.0 — 2026-10-16
 
 ### Added

data/app/assets/tailwind/studio_engine/engine.css

@@ -151,8 +151,10 @@
    navbar, before it — not inside <header>. A pinned header carrying a z-index
    is a stacking context, and a descendant's z-index is clamped inside it, so a
    bar nested in the header composites at the HEADER's level no matter what it
-   asks for. --nav-bottom already reports the header's live bottom edge for
-   anything that needs to sit under chrome stacked above it. */
+   asks for. --nav-bottom reports the header's bottom edge for anything that
+   needs to sit under chrome stacked above it: its live edge, or on a
+   scroll-timeline header its PINNED edge, which a fixed reader closes with
+   data-pin-edge (THE PINNED EDGE ON THE SCROLL TIMELINE, below). */
 body.modal-open .studio-bar-stack,
 body.modal-open .studio-app-banner {
   position: sticky;
@@ -839,6 +841,36 @@ body.modal-open .studio-app-banner {
     }
   }
 }
+/* THE PINNED EDGE ON THE SCROLL TIMELINE (studio/pinned_stack).
+   On a timeline header the pinned stack publishes where the stack sits once it
+   has PINNED (the compact bar), and writes nothing per scroll frame. A sticky
+   reader needs nothing more: it pins at that value. A FIXED reader is on screen
+   at the top of the page too, where the expanded header (and any bars above it)
+   still reach --pin-stack-travel further down. It opts in with data-pin-edge
+   and closes that gap here, on the same scroll timeline the header collapses
+   on, with no script per frame. The publisher puts data-pin-timeline on the
+   root, and the travel beside it, only while the header is on the timeline, so
+   off it this rule matches nothing and the reader's own style stands.
+   components/_sidebar_panel opts in; it positions off --nav-bottom. */
+@layer utilities {
+  @supports (animation-timeline: scroll()) {
+    html[data-pin-timeline] [data-pin-edge] {
+      animation: studio-pin-edge linear both;
+      animation-timeline: scroll(root block);
+      animation-range: 0px var(--pin-stack-travel, 0px);
+    }
+  }
+}
+@keyframes studio-pin-edge {
+  from {
+    top: calc(var(--nav-bottom, 0px) + var(--pin-stack-travel, 0px));
+    height: calc(100% - var(--nav-bottom, 0px) - var(--pin-stack-travel, 0px));
+  }
+  to {
+    top: var(--nav-bottom, 0px);
+    height: calc(100% - var(--nav-bottom, 0px));
+  }
+}
 @keyframes nav-tl-row { to { transform: translateY(calc(var(--nav-band) / 2)); } }
 @keyframes nav-tl-brand { to { transform: scale(var(--nav-brand-scale, 1)); } }
 @keyframes nav-tl-avatar { to { transform: scale(var(--nav-avatar-scale, 1)); } }

data/app/javascript/studio/nav_collapse.js

@@ -246,8 +246,20 @@ var TIMELINE_PROPS = ['--nav-band', '--nav-start', '--nav-brand-scale', '--nav-a
 // below 768px (a phone rotated, then Back) arrives still carrying it, and
 // pinned_stack would subtract the stale band from --nav-h.
 export function clearTimeline(el) {
+  var was = el.hasAttribute('data-nav-timeline-on');
   TIMELINE_PROPS.forEach(function (name) { el.style.removeProperty(name); });
   el.removeAttribute('data-nav-timeline-on');
+  if (was) refreshPinnedStack();
+}
+
+// studio/pinned_stack's REFRESH_EVENT. The header's PINNED height (its box
+// less the band) and the stack's travel change when timeline mode starts,
+// re-measures or stops, and none of that resizes the box, so the stack's
+// ResizeObserver cannot hear it. Named here rather than imported so neither
+// module has to load the other.
+export var PINNED_STACK_REFRESH = 'studio:pinned-stack-refresh';
+function refreshPinnedStack() {
+  if (typeof document !== 'undefined') document.dispatchEvent(new CustomEvent(PINNED_STACK_REFRESH));
 }
 
 function round(n) {
@@ -264,6 +276,7 @@ export class NavCollapse {
     this.p = 0;
     this.scrolled = false;
     this.queued = false;
+    this._frame = 0;
     this.stopped = false;
     this.tuning = { ramp: DEFAULT_RAMP, maxPx: DEFAULT_MAX_STEP };
     this._reduce = null;
@@ -348,6 +361,7 @@ export class NavCollapse {
   // every visit would stack another listener on window.
   stop() {
     this.stopped = true;
+    this.cancelFrame();
     if (this._wide && this._wide.removeEventListener) this._wide.removeEventListener('change', this._onWide);
     this._wide = null;
     if (this.timeline) {
@@ -368,6 +382,19 @@ export class NavCollapse {
     }
   }
 
+  // A frame the --nav-p path queued (a resize, a scroll, the settle loop)
+  // must not land after a stop. Crossing 768px fires this path's resize
+  // listener BEFORE the query's change, so the frame is queued, the swap
+  // runs, start() clears `stopped`, and the frame then wrote --nav-p onto
+  // the timeline header and eased it to 1: a 48px box translated up by the
+  // band, above the window (task timeline-header-resize-collapse). Cancel
+  // it, and clear `queued` so the next mode can schedule its own.
+  cancelFrame() {
+    if (this._frame && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this._frame);
+    this._frame = 0;
+    this.queued = false;
+  }
+
   // Crossing 768px swaps modes: undo the one running, start the one that
   // now applies.
   onWide() {
@@ -449,9 +476,11 @@ export class NavCollapse {
       '--nav-avatar-shrink': round(vars.avatarShrink) + 'px',
       '--nav-tools-shift': round(vars.toolsShift) + 'px'
     };
+    var changed = false;
     for (var key in props) {
-      if (el.style.getPropertyValue(key) !== props[key]) el.style.setProperty(key, props[key]);
+      if (el.style.getPropertyValue(key) !== props[key]) { el.style.setProperty(key, props[key]); changed = true; }
     }
+    if (changed) refreshPinnedStack();
   }
 
   // The scrolled marker on the controller's own hysteresis, written only when
@@ -468,7 +497,7 @@ export class NavCollapse {
   onScroll() {
     if (this.queued) return;
     this.queued = true;
-    requestAnimationFrame(this._apply);
+    this._frame = requestAnimationFrame(this._apply);
   }
 
   onResize() {
@@ -538,7 +567,10 @@ export class NavCollapse {
 
   apply() {
     this.queued = false;
-    if (this.stopped) return;
+    this._frame = 0;
+    // Timeline mode owns the header: --nav-p is the stylesheet's there, and
+    // this path writes nothing, whatever frame is still in flight.
+    if (this.stopped || this.timeline) return;
     // Clamped: rubber-band overscroll reports a NEGATIVE scrollY, and a
     // negative progress inflates the navbar past its expanded size.
     var y = Math.max(0, window.scrollY);
@@ -566,7 +598,7 @@ export class NavCollapse {
     // 144, from a hard flick.
     if (frame.settling) {
       this.queued = true;
-      requestAnimationFrame(this._apply);
+      this._frame = requestAnimationFrame(this._apply);
     }
 
     var lit = shadowLit(this.scrolled, y);

data/app/javascript/studio/pinned_stack.js

@@ -17,6 +17,10 @@
 //   --nav-h / --nav-bottom  the <header>'s height and bottom edge, under their
 //                       legacy names, from the same measurement.
 //
+// THOSE ARE FOR CSS. A SCRIPT reads window.studioPinnedStack.bottom() (or the
+// stackBottom export), measured on call: the root's values can lag a scroll by
+// up to SETTLE_MS (see THE LIVE READ below).
+//
 // 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
@@ -83,6 +87,151 @@ export function composed(pins) {
   return stack;
 }
 
+// THE STACK ON A SCROLL-TIMELINE HEADER (studio/nav_collapse's timeline mode,
+// data-nav-timeline-on). That header keeps its expanded box and is sticky at
+// minus its band, so what pins is the compact bar, and its height never changes
+// while the page scrolls. Every layer of the stack is chrome that pins at the
+// bottom of the layers above it, so on such a page the stack is a fact of
+// HEIGHTS, not of where the window happens to be: each visible layer sits at
+// its composed top and ends one height below it. That is where a sticky reader
+// (a board's lane headers) lands the moment it pins, and it does not move per
+// scroll frame, so nothing is written per scroll frame either: the publisher
+// writes on resize and on a roster change, and the follower path goes unused.
+//
+// A hidden layer (height 0) still drops out at 0. Settles in one pass per
+// layer of depth; bounded by the layer count so a contradictory data-pin-order
+// cannot spin.
+export function pinnedAt(pins) {
+  var i, pass, stack = 0;
+  for (i = 0; i < pins.length; i++) pins[i].bottom = 0;
+  for (pass = 0; pass <= pins.length; pass++) {
+    stack = composed(pins);
+    var moved = false;
+    for (i = 0; i < pins.length; i++) {
+      var bottom = pins[i].h > 0 ? pins[i].top + pins[i].h : 0;
+      if (bottom !== pins[i].bottom) { pins[i].bottom = bottom; moved = true; }
+    }
+    if (!moved) break;
+  }
+  return stack;
+}
+
+export function onTimeline(header) {
+  return !!header && header.hasAttribute('data-nav-timeline-on');
+}
+
+// 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.
+export function measurePin(el, name, legacy, timeline) {
+  // A header on the scroll timeline keeps its expanded box, and its top band
+  // scrolls away above the window; what pins is the compact bar, so that is
+  // its height here. An inline read, no layout.
+  var band = el.hasAttribute('data-nav-timeline-on') ? parseFloat(el.style.getPropertyValue('--nav-band')) || 0 : 0;
+  // On the timeline the bottom comes from the heights (pinnedAt), so the rect
+  // is not read at all.
+  if (timeline) return { el: el, name: name, legacy: legacy, h: el.offsetHeight - band, bottom: 0 };
+  // 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 - band, bottom: Math.max(0, r.bottom) };
+}
+
+// THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
+//
+// 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.
+//
+// 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.
+//
+// Returns { pins, stack, timeline }: every layer measured and composed, the
+// stack's bottom, and whether the header is on the scroll timeline.
+export function readStack() {
+  var header = document.querySelector('header');
+  var timeline = onTimeline(header);
+  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;
+    if (nodes[i] === header) headerPinned = true;
+    list.push(measurePin(nodes[i], name, nodes[i] === header, timeline));
+  }
+  // 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(measurePin(header, 'nav', true, timeline));
+  return {
+    pins: list,
+    stack: timeline ? pinnedAt(list) : composed(list),
+    timeline: timeline,
+    travel: timeline ? timelineTravel(header) : 0
+  };
+}
+
+// HOW FAR THE PAGE SCROLLS BEFORE THE TIMELINE HEADER PINS: the bars above it
+// in flow (--nav-start) plus the band that scrolls away (--nav-band), both
+// written inline by studio/nav_collapse. Inline reads, no layout. A FIXED
+// reader (data-pin-edge) starts this far below the stack's bottom at the top
+// of the page and closes the gap on the scroll timeline, in CSS (engine.css,
+// THE PINNED EDGE ON THE SCROLL TIMELINE).
+export function timelineTravel(header) {
+  var px = function (name) { return parseFloat(header.style.getPropertyValue(name)) || 0; };
+  return Math.max(0, px('--nav-start') + px('--nav-band'));
+}
+
+// THE LIVE READ, for SCRIPT readers. The custom properties are for CSS; a
+// script that reads --pin-stack-bottom off documentElement can be up to
+// SETTLE_MS late, because in motion the publisher writes only the elements
+// that read the stack in CSS and writes the root once the scroll settles.
+// Cyvasse's phone dock read the root mid-scroll and sat 30px off. This
+// measures on call, from the same reading the publisher would make now, so it
+// is never stale and never writes anything.
+//
+//   import { stackBottom } from "studio/pinned_stack"
+//   window.studioPinnedStack.bottom()   // the same, for a script with no import
+//   window.studioPinnedStack.read()     // { bottom, timeline, layers: { nav: { h, top, bottom } } }
+export function stackBottom() {
+  return readStack().stack;
+}
+
+export function stackReading() {
+  var r = readStack();
+  var layers = {};
+  for (var i = 0; i < r.pins.length; i++) {
+    layers[r.pins[i].name] = { h: r.pins[i].h, top: r.pins[i].top, bottom: r.pins[i].bottom };
+  }
+  return { bottom: r.stack, timeline: r.timeline, travel: r.travel, layers: layers };
+}
+
+if (typeof window !== 'undefined') {
+  window.studioPinnedStack = { bottom: stackBottom, read: stackReading };
+}
+
+// What studio/nav_collapse fires on the document when its timeline mode
+// starts, re-measures its band, or stops: the header's pinned height changed
+// without its box resizing, which the ResizeObserver cannot see.
+export var REFRESH_EVENT = 'studio:pinned-stack-refresh';
+
 var started = false
 
 // THE READERS OF THE STACK, found rather than declared.
@@ -239,64 +388,11 @@ export function startPinnedStack() {
     releaseFollowers();
   }
 
-  // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
-  //
-  // 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.
-  //
-  // 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 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;
-      if (nodes[i] === header) headerPinned = true;
-      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();
-    // A header on the scroll timeline (studio/nav_collapse) keeps its expanded
-    // box, and its top band scrolls away above the window; what pins is the
-    // compact bar, so that is its height here. An inline read, no layout.
-    var band = el.hasAttribute('data-nav-timeline-on') ? parseFloat(el.style.getPropertyValue('--nav-band')) || 0 : 0;
-    return { el: el, name: name, legacy: legacy, h: el.offsetHeight - band, bottom: Math.max(0, r.bottom) };
-  }
+  // The registry and the measurement are module-level (readStack, measurePin
+  // above) so the live read and the publisher make the same reading.
 
-
-  function write(pins, stack) {
+  var lastTravel = null;
+  function write(pins, stack, timeline, travel) {
     var style = document.documentElement.style;
     var seen = {};
     var i, p, prev;
@@ -309,9 +405,30 @@ export function startPinnedStack() {
       for (i = 0; i < pins.length; i++) { if (!last.hasOwnProperty(pins[i].name)) { force = true; break; } }
     }
 
+    // ON THE SCROLL TIMELINE the stack does not move with the scroll (see
+    // pinnedAt), so a scroll frame finds nothing changed and the root path
+    // below writes nothing. The follower path is for values that DO move per
+    // frame; it goes unused here, and any copies a --nav-p frame left go back.
+    if (timeline) {
+      if (settleTimer) { clearTimeout(settleTimer); settleTimer = null; }
+      if (followed.length) releaseFollowers();
+    }
+    // The fixed readers' scroll-timeline path (data-pin-edge, engine.css) is
+    // switched on by this attribute and sized by --pin-stack-travel. Both are
+    // written only when they change: on a resize or a mode swap.
+    var root = document.documentElement;
+    if (timeline) {
+      if (force || travel !== lastTravel) { style.setProperty('--pin-stack-travel', travel + 'px'); lastTravel = travel; }
+      if (!root.hasAttribute('data-pin-timeline')) root.setAttribute('data-pin-timeline', '');
+    } else if (lastTravel !== null || root.hasAttribute('data-pin-timeline')) {
+      style.removeProperty('--pin-stack-travel');
+      root.removeAttribute('data-pin-timeline');
+      lastTravel = null;
+    }
+
     // IN MOTION, THE FOLLOWERS ONLY. A structural change still writes the
     // root at once: it is rare, and a layer arriving must reach every reader.
-    if (!force && performance.now() - lastScrollAt < SETTLE_MS) {
+    if (!force && !timeline && performance.now() - lastScrollAt < SETTLE_MS) {
       var props = [];
       for (i = 0; i < pins.length; i++) {
         p = pins[i];
@@ -361,8 +478,9 @@ export function startPinnedStack() {
   }
 
   function publishAll() {
-    var pins = readPins();
-    write(pins, composed(pins));
+    var reading = readStack();
+    var pins = reading.pins;
+    write(pins, reading.stack, reading.timeline, reading.travel);
     syncObserver(pins);
   }
 
@@ -450,6 +568,9 @@ export function startPinnedStack() {
   document.addEventListener('turbo:before-stream-render', function () {
     window.requestAnimationFrame(invalidate);
   });
+  // The timeline header's pinned height moves when its band is measured,
+  // which changes no box size, so the observer never hears of it.
+  document.addEventListener(REFRESH_EVENT, publishAll);
   // Registered ONCE at start, not inside a re-scan, so a Turbo nav
   // re-publishes instead of stacking another listener per visit.
   window.addEventListener('scroll', schedule, { passive: true });

data/app/views/components/_sidebar_panel.html.erb

@@ -12,7 +12,12 @@
     It is reachable only when a host OVERRIDES layouts/studio/_head, in which
     case --nav-bottom is never published and this degrades to the previous,
     BUGGY geometry. That is a deliberate floor, not a safe default: it keeps an
-    overriding host at today's behaviour instead of collapsing to 6rem. %>
+    overriding host at today's behaviour instead of collapsing to 6rem.
+
+    data-pin-edge: on a header on the scroll timeline the stack publishes the
+    PINNED bar and nothing per frame, so at the top of the page this fixed panel
+    would cover the expanded header. engine.css (THE PINNED EDGE ON THE SCROLL
+    TIMELINE) moves it with the header on the scroll timeline instead. %>
 <% id             = local_assigns.fetch(:id, nil) %>
 <% title          = local_assigns.fetch(:title, nil) %>
 <% open           = local_assigns.fetch(:open) %>
@@ -55,6 +60,7 @@
   x-transition:leave-end="translate-x-full"
   class="<%= display_class %> fixed right-0 <%= width_class %> bg-surface border-l border-subtle shadow-2xl <%= z_class %> flex-col <%= panel_class %>"
   style="top:var(--nav-bottom, var(--nav-h, 6rem));height:calc(100% - var(--nav-bottom, var(--nav-h, 6rem)))"
+  data-pin-edge
   role="<%= role %>"
   <% if labelledby %>aria-labelledby="<%= labelledby %>"<% elsif aria_label.present? %>aria-label="<%= aria_label %>"<% end %>>
   <div class="flex flex-col h-full">

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

@@ -150,7 +150,10 @@
 </style>
 <%# THE PINNED STACK: studio/pinned_stack publishes --pin-<name>-h, -bottom and
     -top for every [data-pin] layer, --pin-stack-bottom, and the legacy --nav-h /
-    --nav-bottom. Started by studio/application. %>
+    --nav-bottom. Started by studio/application. Those are for CSS: a script
+    reads window.studioPinnedStack.bottom(), measured on call, because the root
+    values lag a scroll in motion by up to 160ms (docs/NAVBAR_SETUP.md, Reading
+    the Pinned Stack). %>
 
 <style>
   /* studio-engine: --nav-p, the sticky header's COLLAPSE PROGRESS, 0 (expanded)

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

@@ -35,8 +35,10 @@
   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.
+  off --nav-bottom (published in layouts/studio/_head), which reports the
+  header's bottom edge and accounts for chrome above it. On a scroll-timeline
+  header that is the PINNED edge, so a fixed overlay also carries data-pin-edge
+  (engine.css, THE PINNED EDGE ON THE SCROLL TIMELINE).
 
   Locals (all optional):
     preview      — true inside a navbar-preview render; renders nothing, so a

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.111.0"
+  VERSION = "0.111.1.rc1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.111.0
+  version: 0.111.1.rc1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails