studio-engine 0.72.1 → 0.72.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6827dbf6d947e68f03792d54208e63d7132d87291d41c9f25a79a2b375f7c337
-  data.tar.gz: 6208b4449236e9e5a634a99a0f1634a28d53096ee11ab7a53180d41f3e2fc31e
+  metadata.gz: 13abdd4ef0f10262a6560c40b2bed302c16d9f3b3b21582f3569cf0a7517cdf8
+  data.tar.gz: 6f47a52a0ba75d8be96ff6200b75d30a1ff49d76db401581a17a0ea88b2dcd6c
 SHA512:
-  metadata.gz: 214d5859c1c05d13b11c5101ae403121b4874540cca544b201cc5c0d158f6fcef6936e9c9b038ccdc63a5221face3ad2e1f9a12e79406f0cfa741027c7246be8
-  data.tar.gz: 970cee9c4cea2c9fff4210930161e3565fbcd57cb02c4a86f82682e8bf9eca41f6c9ff07986939d37a270d66e4bbbce8c5788e3362e8f6c73936ca9ddf0a4130
+  metadata.gz: 4b82e9d95ec946a5ce8fdc2d82269eadd8e300bfe21e146163aa0105a3a96254065ac10b26dd6f87a29cff5a402de1ca6d9cb0cdb53ef7119604ee0102b841d5
+  data.tar.gz: f03181c1586eb6c147b50778614df087115b27d1e76eb0dee7236f6e73c68a4509dadde3448d04cb84ea16cad4d20ffbe9eef8fcb7e96eca4be34dbd4c080d52

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.
@@ -217,6 +272,45 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **The style guide's two "Sign Wallet" thumbnails no longer crown themselves
+  with a padlock the card stopped drawing, and the guide's lock no longer trails
+  the release that removed it.** solana-studio 0.6.1 replaced the step-up card's
+  padlock with the remembered wallet's own brand mark, falling back to a neutral
+  billfold where no brand is remembered. Both hand-drawn thumbnails in
+  `style/_modals` went on drawing the padlock, so the first thing a designer
+  reads advertised a glyph the design system had retired.
+
+  **THE THUMBNAILS WERE HALF OF IT.** The opened specimen renders the REAL
+  shared partial, but it does so through whatever `Gemfile.lock` resolves — so
+  it is only ever as current as the lock, and the lock sat on 0.6.0 while
+  turf-monster shipped 0.6.1. The guide's opened card was still drawing the
+  padlock too, which `bin/gem-drift-check` had already been failing on
+  (`engine 0.6.0 TRAILS turf-monster 0.6.1`). Correcting the sketches alone
+  would have put a brand mark on the thumbnail and a padlock in the card it
+  opens — moving the contradiction onto one screen rather than removing it. So
+  the lock had to move too, and it has: `accepted` carried the engine to
+  solana-studio 0.7.0 while this change sat in review, which is past the 0.6.1
+  that removed the padlock. This change no longer moves the lock itself — it
+  defers to the line `accepted` already holds — so the sketch and the card it
+  opens agree without it.
+
+  The sketches follow the card: a centered brand tile where a wallet is
+  remembered, the card's own billfold outline in an inset square where none is.
+  They stay SKETCHES rather than real brand marks for a mechanical reason worth
+  recording — every `se-wallet` symbol on the guide is defined inside a
+  `template x-if`, whose content is inert until Alpine clones it, so a `use`
+  placed outside one resolves to nothing and paints an empty box.
+
+  Guarded by `test/views/step_up_specimen_thumbnails_test.rb`, which slices each
+  thumbnail by a `data-test` hook before asserting. That slicing is the point:
+  the rendered guide already carried 17 `se-wallet-` hits from the picker and
+  the card's own CTA, so a page-wide assertion for the mark could not fail, and
+  a page-wide assertion against the padlock could not pass — the drag-board
+  specimen's prose legitimately contains one. The padlock is pinned in BOTH the
+  codepoint and the HTML-entity form. MEASURED: five mutants, five killed —
+  the padlock restored in either form, either header mark removed, and the lock
+  reverted to 0.6.0 each reddens the assertion that owns it.
+
 - **The style guide's page-scoped modal store now resolves animations through
   the LIVE registry, so the guide can no longer disagree with itself.**
   `style/_modals`' `dsModals` carried a hard-coded COPY of the animation table

data/Gemfile

@@ -75,11 +75,29 @@ end
 # nothing — which is precisely why it went four releases unnoticed.)
 #
 # SO THE FIX IS A GATE, NOT A PIN. bin/gem-drift-check fails when this engine's
-# lock TRAILS a consumer's, and consumer-ci.yml runs it — the only lane holding
-# two repos' lockfiles at once. Direction is one-way: engine behind fails, engine
-# ahead or level passes, a consumer bundling no solana-studio is a skip. Keeping
-# up is now enforced rather than remembered, which is what lets the floor stay a
-# floor. Guarded by test/lib/gem_drift_check_test.rb.
+# lock resolves an OLDER solana-studio than a consumer's, and consumer-ci.yml
+# runs it — the only lane holding two repos' lockfiles at once. Direction is
+# one-way: engine behind fails, engine ahead or level passes, a consumer
+# bundling no solana-studio is a skip. Guarded by
+# test/lib/gem_drift_check_test.rb.
+#
+# READ THE CONSUMER AS A MESSENGER, not as the target. The invariant is that
+# this engine resolves the LATEST RELEASED solana-studio. A consumer's lock is
+# compared only because it is the one newer-release fact on disk — the gate is
+# stdlib-only and makes no network call, deliberately, so it cannot ask the
+# registry directly. A consumer being ahead is EVIDENCE of a release this engine
+# missed, never itself the thing to catch up to.
+#
+# AND THE GATE ALONE WAS NOT ENOUGH. Enforcement only reddens; a human still had
+# to do the bump. Measured 2026-09-07: that human was late five times in ONE DAY
+# — by 3h, 2h20m, 14h15m and 1h10m — and the worst case was not the longest but
+# the fastest, a lock that went stale 36 minutes after the previous fix was
+# committed. While it is stale EVERY open engine PR is red, over a line no PR
+# author owns. So .github/dependabot.yml now opens the bump PR daily (scoped to
+# solana-studio ALONE, so this repo never inherits the third-party graveyard),
+# and .github/workflows/engine-lock-automerge.yml merges it when — and only
+# when — all four of bin/lock-bump-mergeable's conditions hold. A breaking bump
+# still stops, stays open and red, and still waits for a human.
 group :development, :test do
   gem "solana-studio", ">= 0.5.3"
 end

data/README.md

@@ -305,6 +305,18 @@ the one credential that skips attestation) and `props.submitting`. It receives
 one local, `modal_store`: the engine's real host is `"modals"`, the living style
 guide's page-scoped host is `"dsModals"`.
 
+**Name a store like a JavaScript identifier.** Partials splice this local in as a
+bare name — `$store.<name>.current()` — rather than as a string, so a value
+carrying a quote, a dot or a space is not a mangled store name: it is a
+SyntaxError in the whole `x-data`, and Alpine mounts a component that renders
+every element and does nothing. Escaping is not the repair (an escaped identifier
+is a different SyntaxError); a name that matches `/\A[A-Za-z_$][A-Za-z0-9_$]*\z/`
+is. `studio/modals/onboarding/_first_name` enforces exactly that and raises
+`ArgumentError` on anything else — the first partial to do so, not yet the fleet.
+Note the shape decides the repair, not the name of the local: `blocks/_birthday`
+and `blocks/_leveling_activity` pass `modal_store` in *string* position and
+correctly `escape_javascript` it instead.
+
 It also keeps two blocks the gem renders **by name** across the gem boundary:
 `studio/modals/blocks/wallet_brand_sprite` and `studio/modals/blocks/card_header`.
 Renaming either is a cross-repo change.

data/app/controllers/studio/onboarding_controller.rb

@@ -45,6 +45,17 @@ module Studio
     def first_name
       value = params[:first_name].to_s.strip.gsub(/\s+/, " ")
 
+      # THE SAME SENTENCE AS THE CARD'S EMPTY-FIELD ERROR, and deliberately NOT
+      # parameterised the way that one now is. `required` is a RENDER-TIME local of
+      # studio/modals/onboarding/_first_name; the server is never told which mode
+      # the card was drawn in, so this branch has no `required` to follow, and
+      # rewording it unconditionally would move McRitchie Studio's copy to say
+      # something only turf's gate needs.
+      #
+      # It is also UNREACHABLE FROM THE CARD: save() returns on a blank value
+      # before it posts, so what arrives here is a direct POST or a host driving
+      # these endpoints with its own form. If that ever becomes a mode-sensitive
+      # surface, the caller says which mode it is in — this string does not guess.
       if value.blank?
         return refuse("Enter your first name, or skip for now.")
       end

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/studio/modals/onboarding/_first_name.html.erb

@@ -10,8 +10,11 @@
   This partial owns ONE step; the host owns the sequence.
 
   Locals (all optional, defaults via local_assigns.fetch):
-    submit_path — POST target for the name (default "/onboarding/first_name")
-    skip_path   — POST target for the skip  (default "/onboarding/skip_first_name")
+    submit_path — POST target for the name (default "/onboarding/first_name").
+                  Interpolated into the x-data, so it is JS-escaped on the way in
+                  — see THE TWO SHAPES below.
+    skip_path   — POST target for the skip  (default "/onboarding/skip_first_name").
+                  JS-escaped, same as submit_path.
     required    — hide the SKIP affordances (default false, which keeps today's
                   skippable card). The × then merely CLOSES and is labelled
                   Close, and the "Skip for now" button is not rendered. For a
@@ -24,6 +27,11 @@
                   follows `required`, because a card that cannot be skipped is
                   talking to a different audience — a host that passes its own
                   subtext still wins)
+    empty_error — the inline error shown when the field is submitted EMPTY. Like
+                  subtext, its default follows `required`: a card that renders no
+                  skip must not answer an empty field by offering one. Rendered
+                  INSIDE the x-data, so it is escaped for a JS single-quoted
+                  string on the way in — see CRITICAL below.
     placeholder — (default "Alex")
     placeholder_names — OPTIONAL, and OFF unless passed: an array of first names,
                   one of which is TYPED into the placeholder a character at a
@@ -43,9 +51,13 @@
                   than store a name nobody typed)
     progress    — [current, total] to render the segmented pill, or nil for none
     modal_store — Alpine store name (default "modals"; the living style guide
-                  mounts its own page-scoped host and passes "dsModals")
+                  mounts its own page-scoped host and passes "dsModals"). It lands
+                  in IDENTIFIER position, not string position, so it is VALIDATED
+                  rather than escaped and a value that is not a JS identifier
+                  raises ArgumentError at render — see THE TWO SHAPES below.
     done_event  — window event dispatched when this step is finished, saved or
-                  skipped (default "onboarding-step-done"). Its detail carries
+                  skipped (default "onboarding-step-done"). JS-escaped, same as
+                  submit_path. Its detail carries
                   `{ next: [...], saved: true|false }` — see THE OUTCOME below.
                   The HOST decides what happens next; this partial never knows.
 
@@ -73,6 +85,38 @@
   DOUBLE-QUOTED attribute — a single " anywhere inside it (a code comment
   included) closes it early and the whole component mounts as a silent no-op that
   still renders markup. Keep every inner string SINGLE-quoted.
+
+  THE TWO SHAPES — read this before adding a local to the x-data. Five locals are
+  interpolated into that attribute and they do NOT take the same repair. Getting
+  this wrong does not raise; it mounts a card that renders every element and does
+  nothing, which is why it is written down here rather than left to be noticed.
+
+    STRING position — empty_error, submit_path, skip_path, done_event — each sits
+      inside a JS SINGLE-quoted literal. A bare apostrophe closes the literal, the
+      expression becomes a SyntaxError, and the card is that silent no-op. Repair:
+      escape_javascript, in the INTERPOLATED form. The wrapper is load-bearing:
+      escape_javascript(SafeBuffer) answers true to html_safe, so ERB would skip
+      its own attribute-escaping half and a raw double quote could still close the
+      attribute. Wrapping the value in a plain interpolation first strips the safe
+      marking, so both escapers run.
+
+    IDENTIFIER position — modal_store — is spliced in as a bare NAME, at three
+      sites: the props getter, finish's close, and the Ruby-built dismiss_action
+      emitted into the x's click handler. Escaping is the WRONG repair here: an
+      escaped identifier is a different SyntaxError and the same dead card.
+      Repair: refuse a value that is not a JS identifier, which the Ruby block
+      below does once, at the source, so all three sites are covered.
+
+  A PATTERN, NOT AN ALLOWLIST, and the reason is worth keeping: an allowlist would
+  be this engine enumerating its own consumers, so the next app to mount a
+  page-scoped host would be refused by its own dependency until a gem release
+  admitted the name. The contract is narrower and stateless — it is spliced into
+  member-access position, so it must be an identifier, and which one is the host's
+  business.
+
+  NOTE THE SAME LOCAL TAKES THE OTHER REPAIR ELSEWHERE. blocks/_birthday and
+  blocks/_leveling_activity pass modal_store in STRING position and escape it,
+  correctly. The shape decides the repair, never the name of the local.
 %>
 <%
   submit_path = local_assigns.fetch(:submit_path, "/onboarding/first_name")
@@ -85,6 +129,31 @@
                       "Just your first name — we use it to address you in emails."
                     end
   subtext     = local_assigns.fetch(:subtext, default_subtext)
+  # The inline error for an EMPTY field, resolved here for the same reason
+  # default_subtext is: `required` is known at render time, and a card that
+  # renders no skip button must not answer an empty field by offering one. It was
+  # a hard-coded literal until now, which is why a gated card told the user to
+  # skip for now and pointed at a button that is not on the page.
+  default_empty_error = if required
+                          "Enter your first name to continue."
+                        else
+                          "Enter your first name, or skip for now."
+                        end
+  empty_error = local_assigns.fetch(:empty_error, default_empty_error)
+  # ESCAPED FOR THE x-data, which is the hazard this local introduces: it is the
+  # first HOST-SUPPLIED PROSE to go inside that attribute, and prose has
+  # apostrophes. Interpolated raw, an error reading "We'll need a name" would
+  # close the JS single-quoted string, make the whole expression a SyntaxError,
+  # and mount the component as a SILENT NO-OP that still renders every element
+  # below. escape_javascript covers the apostrophe, the double quote, the
+  # backslash and the newline; the interpolation around it first strips any
+  # html_safe marking, because a safe string would skip ERB's own attribute
+  # escaping and could smuggle a raw double quote in — the exact failure the
+  # CRITICAL note above describes.
+  #
+  # INERT ON BOTH DEFAULTS. Neither default string contains a character either
+  # escaper touches, so the shipped card is byte-for-byte what it was.
+  empty_error_js = escape_javascript("#{empty_error}")
   placeholder = local_assigns.fetch(:placeholder, "Alex")
   # OFF unless a host passes a non-empty array. Normalised to nil so that an
   # empty list behaves exactly like an absent local rather than emitting the
@@ -95,7 +164,58 @@
   max_length  = local_assigns.fetch(:max_length, Studio::FULL_NAME_MAX_LENGTH)
   progress    = local_assigns.fetch(:progress, nil)
   modal_store = local_assigns.fetch(:modal_store, "modals")
+  # VALIDATED, NOT ESCAPED — and that distinction is the whole point of this local.
+  # Every other value inside the x-data is a JS STRING and is repaired by escaping.
+  # This one is spliced in as a bare NAME (`$store.<name>.current()`), so the same
+  # repair breaks it: escape_javascript turns `a'b` into `a\'b`, and
+  # `$store.a\'b.current()` is not a rescued identifier, it is a different
+  # SyntaxError — the same silently dead card, reached a longer way.
+  #
+  # A PATTERN RATHER THAN AN ALLOWLIST, deliberately. An allowlist would be this
+  # engine enumerating its own CONSUMERS — "modals" and the style guide's
+  # "dsModals" today — so the next app to mount a page-scoped host would be refused
+  # by its own dependency until a gem release admitted the name. That is backwards
+  # for a shared primitive. The real contract is narrower and stateless: this is
+  # spliced into member-access position, so it must be a JS identifier, and WHICH
+  # identifier is none of the engine's business.
+  #
+  # ASCII IdentifierName, which is what member access after a dot accepts. It
+  # admits every store name a host would plausibly write and rejects every
+  # character that could leave identifier position — quote, apostrophe, backslash,
+  # dot, space, semicolon, angle bracket.
+  #
+  # IT RAISES RATHER THAN FALLING BACK TO THE DEFAULT. A silent fallback is the
+  # worse of the two repairs: the card would mount, look perfect, and talk to a
+  # store that is not the host's — which is the SILENT-brick failure class this
+  # guard exists to leave behind. A host sees this the first time it renders.
+  unless modal_store.to_s.match?(/\A[A-Za-z_$][A-Za-z0-9_$]*\z/)
+    raise ArgumentError,
+          "modal_store must be a JS identifier (it is spliced into $store.<name>); " \
+          "got #{modal_store.inspect}. Escaping it would not help — an escaped " \
+          "identifier is a different SyntaxError, and the card would mount dead."
+  end
   done_event  = local_assigns.fetch(:done_event, "onboarding-step-done")
+  # THE SAME HAZARD empty_error_js CARRIES, on the three remaining locals that land
+  # inside a JS SINGLE-quoted literal in the x-data below. A bare apostrophe in any
+  # of them closes its literal, the whole expression becomes a SyntaxError, and
+  # Alpine mounts the component as a SILENT NO-OP that still renders every element
+  # — perfect-looking markup, dead card.
+  #
+  # THE INTERPOLATED FORM IS LOAD-BEARING, not a style choice:
+  # escape_javascript(SafeBuffer).html_safe? is TRUE, so ERB would skip its own
+  # attribute-escaping half and a raw double quote could still close the
+  # double-quoted x-data. Wrapping in "#{}" first strips the html_safe marking, so
+  # both escapers run: escape_javascript for the JS literal, ERB for the attribute.
+  #
+  # INERT ON EVERY DEFAULT. Two paths, an event name and a store name carry no
+  # character either escaper touches, so the shipped card is byte-for-byte what it
+  # was — the golden-fixture pin in the view test says so. This is latent cover: no
+  # host supplies these as prose today, but empty_error established that prose does
+  # belong in this attribute, and the next local to carry an apostrophe will look
+  # like an ordinary change to whoever writes it.
+  submit_path_js = escape_javascript("#{submit_path}")
+  skip_path_js   = escape_javascript("#{skip_path}")
+  done_event_js  = escape_javascript("#{done_event}")
   field_id    = local_assigns.fetch(:id, "onboarding-first-name")
   # The × mirrors the skip affordance it sits beside: it SKIPS while the step is
   # skippable, and merely CLOSES once it is required. Resolved here rather than in
@@ -175,9 +295,9 @@
        async save() {
          if (this.submitting) return;
          var value = (this.firstName || '').trim();
-         if (!value) { this.error = 'Enter your first name, or skip for now.'; return; }
+         if (!value) { this.error = '<%= empty_error_js %>'; return; }
          this.submitting = true; this.error = '';
-         var data = await this.post('<%= submit_path %>', { first_name: value });
+         var data = await this.post('<%= submit_path_js %>', { first_name: value });
          this.submitting = false;
          if (!data || !data.ok) {
            this.error = (data && data.error) || 'Could not save that — try again.';
@@ -188,7 +308,7 @@
        async skip() {
          if (this.submitting) return;
          this.submitting = true; this.error = '';
-         var data = await this.post('<%= skip_path %>', {});
+         var data = await this.post('<%= skip_path_js %>', {});
          this.submitting = false;
          this.finish((data && data.next) || [], false);
        },
@@ -211,7 +331,7 @@
 <% if typed_placeholder %>
          this.stopPlaceholder();
 <% end %>
-         window.dispatchEvent(new CustomEvent('<%= done_event %>', { detail: { next: next, saved: !!saved } }));
+         window.dispatchEvent(new CustomEvent('<%= done_event_js %>', { detail: { next: next, saved: !!saved } }));
          $store.<%= modal_store %>.close();
        }
      }"

data/app/views/style/_modals.html.erb

@@ -1291,9 +1291,22 @@
             on a 20px row, which is not a difference anyone can see at thumbnail
             size — and these two cards are the pair most likely to be mistaken for
             duplicates, because they share a modal id AND a title. So the sketch
-            now shows the actual distinction: this card KNOWS which wallet. %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
-          <div class="text-2xl leading-none">🔐</div>
+            now shows the actual distinction: this card KNOWS which wallet.
+
+            THE HEADER IS THE WALLET'S OWN MARK, not a padlock. This crowned a
+            padlock until 2026-09-07, which the card had already stopped drawing —
+            a thumbnail showing a glyph the card never paints is the style guide
+            misreporting the design system. The card now heads itself with the
+            remembered wallet's brand mark, so the sketch heads itself with a
+            brand tile, the same idiom the Connect-wallet thumbnail above uses.
+
+            A REAL SPRITE CANNOT BE USED HERE, and it is worth saying why so the
+            next reader does not try. Every se-wallet symbol on this page is
+            defined inside a template x-if, whose content is inert until Alpine
+            clones it, so a use outside one resolves to nothing and paints an
+            empty box. Thumbnails are sketches for that reason, not only taste. %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2" data-test="step-up-thumb-brand">
+          <span class="block w-7 h-7 mx-auto rounded-lg" style="background: var(--color-primary)"></span>
           <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
           <span class="flex items-center gap-1.5 h-7 w-full rounded-lg border px-1.5" style="border-color: var(--color-border-strong)">
             <span class="w-4 h-4 rounded shrink-0" style="background: var(--color-primary)"></span>
@@ -1311,9 +1324,21 @@
             disabled: web3_card_off, openable: web3_gem } do %>
         <%# An EMPTY slot: dashed outline, no brand tile, a "?" where the wallet's
             name would be. Reads at a glance as "we do not know which wallet",
-            which is the whole difference between this card and the one before it. %>
-        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
-          <div class="text-2xl leading-none">🔐</div>
+            which is the whole difference between this card and the one before it.
+
+            THE HEADER IS THE NEUTRAL BILLFOLD the card falls back to when no
+            brand is remembered — the same rounded, inset-filled square drawn with
+            the card's own billfold outline. It replaced a padlock on 2026-09-07,
+            for the reason given on the card above this one. Drawing the billfold
+            rather than tinting a tile keeps the two headers as different as the
+            two cards are: one names a wallet, this one cannot. %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2" data-test="step-up-thumb-no-brand">
+          <span class="inline-flex w-7 h-7 rounded-lg bg-inset items-center justify-center" aria-hidden="true">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" class="w-4 h-4 text-secondary">
+              <rect x="3" y="6.5" width="18" height="11" rx="2.5" />
+              <circle cx="16.6" cy="12" r="1.3" fill="currentColor" stroke="none" />
+            </svg>
+          </span>
           <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
           <span class="flex items-center justify-center h-7 w-full rounded-lg border border-dashed" style="border-color: var(--color-border-strong)">
             <span class="text-xs font-bold text-muted leading-none">?</span>

data/lib/studio/theme_resolver.rb

@@ -32,6 +32,13 @@ module Studio
       primary     = colors[:primary] || "#8E82FE"
       border_rgb  = ColorScale.lighten(dark_base, 0.30)
       danger      = colors[:danger] || "#EF4444"
+      surfaces    = dark_surfaces(dark_base)
+
+      secondary_ink = contrast_ink(dark_base, direction: :lighten, start: 0.70, target: 4.5, against: surfaces)
+      muted_ink     = ladder_clamp(
+        contrast_ink(dark_base, direction: :lighten, start: 0.55, target: 4.5, against: surfaces),
+        secondary_ink, direction: :lighten
+      )
 
       {
         "--color-page"           => dark_base,
@@ -48,10 +55,15 @@ module Studio
         # until the ink clears its target on every emitted dark surface
         # (clamped at pure white for pathological bases). Note the blend
         # DESATURATES toward gray; only strongly-tinted bases keep a cast.
-        "--color-text-secondary" => contrast_ink(dark_base, direction: :lighten, start: 0.70, target: 4.5,
-                                                 against: dark_surfaces(dark_base)),
-        "--color-text-muted"     => contrast_ink(dark_base, direction: :lighten, start: 0.55, target: 3.0,
-                                                 against: dark_surfaces(dark_base)),
+        "--color-text-secondary" => secondary_ink,
+        # MUTED IS NORMAL-SIZE TEXT, so its target is AA 4.5:1 — not 3.0.
+        # 3.0 is WCAG's LARGE-text allowance (>=18.66px, or 14px bold) and this
+        # ink does not land on large text: the engine's own `.label-upper`
+        # utility is `text-xs text-muted` (12px), and consumers render it at
+        # 11px. Measured on the default theme before this change: muted was
+        # #9896A4 at 3.84:1 on --color-surface (dark) and #818283 at 3.46:1 on
+        # --color-surface-alt (light) — both below AA, in BOTH themes.
+        "--color-text-muted"     => muted_ink,
         "--color-border"         => ColorScale.with_opacity(border_rgb, 0.2),
         "--color-border-strong"  => ColorScale.with_opacity(border_rgb, 0.4),
         "--color-shadow"         => "transparent",
@@ -95,6 +107,31 @@ module Studio
         ColorScale.darken(light_base, 0.08) ]
     end
 
+    # Keep the ink ladder monotonic: muted is the QUIETEST text ink and must
+    # never come out louder than secondary.
+    #
+    # This became reachable the moment muted's target rose to 4.5 and the two
+    # inks started sharing one threshold. They are found by the same stepped
+    # search from DIFFERENT starts (muted 0.40/0.55, secondary 0.55/0.70), so
+    # their grids are offset and the one that starts lower can overshoot PAST
+    # the one that starts higher. Measured on the default light base #f8fafc:
+    # the true minimum blend clearing 4.5 is 0.59, secondary lands exactly
+    # there, and muted — stepping 0.40, 0.42, ... — skips 0.59 and lands on
+    # 0.60, i.e. DARKER than secondary. The ladder inverted while every
+    # contrast assertion stayed green, because nothing compared the two.
+    #
+    # Ordering is a design decision, so make it structurally rather than let a
+    # 0.02 grid decide it. `direction` says which way "louder" runs: lightened
+    # ink on a dark base is louder as luminance RISES; darkened ink on a light
+    # base is louder as luminance FALLS.
+    def ladder_clamp(muted, secondary, direction:)
+      muted_l     = ColorScale.relative_luminance(muted)
+      secondary_l = ColorScale.relative_luminance(secondary)
+      louder = direction == :lighten ? muted_l > secondary_l : muted_l < secondary_l
+
+      louder ? secondary : muted
+    end
+
     # Bounded, clamped search: raise the blend amount from `start` until the
     # ink clears `target` contrast against every background in `against`.
     # Clamps at 1.0 (pure white/black), so a pathological base degrades to the
@@ -133,6 +170,13 @@ module Studio
       light_base = colors[:light] || "#f8fafc"
       primary    = colors[:primary] || "#8E82FE"
       danger     = colors[:danger] || "#EF4444"
+      surfaces   = light_surfaces(light_base)
+
+      secondary_ink = contrast_ink(light_base, direction: :darken, start: 0.55, target: 4.5, against: surfaces)
+      muted_ink     = ladder_clamp(
+        contrast_ink(light_base, direction: :darken, start: 0.40, target: 4.5, against: surfaces),
+        secondary_ink, direction: :darken
+      )
 
       {
         "--color-page"           => light_base,
@@ -144,10 +188,9 @@ module Studio
         # Same bounded search as dark mode: the old fixed grays measured as
         # low as 2.05:1 (muted on --color-inset) — below the very defect this
         # derivation exists to prevent. Ink darkens away from the light base.
-        "--color-text-secondary" => contrast_ink(light_base, direction: :darken, start: 0.55, target: 4.5,
-                                                 against: light_surfaces(light_base)),
-        "--color-text-muted"     => contrast_ink(light_base, direction: :darken, start: 0.40, target: 3.0,
-                                                 against: light_surfaces(light_base)),
+        "--color-text-secondary" => secondary_ink,
+        # See the dark-mode note: muted is normal-size text and owes AA 4.5:1.
+        "--color-text-muted"     => muted_ink,
         "--color-border"         => ColorScale.darken(light_base, 0.08),
         "--color-border-strong"  => ColorScale.darken(light_base, 0.15),
         "--color-shadow"         => "rgba(0,0,0,0.05)",

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.72.1"
+  VERSION = "0.72.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.72.1
+  version: 0.72.3
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails