studio-engine 0.63.0 → 0.65.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fcb787be0caeb8c975281d334f56a0d0ce699dbd25851b59948de0e5c6a87a4
-  data.tar.gz: a0b21daec66caf0110d3fc6f33f311a678b4216bda5b7d033011d84465ec54d3
+  metadata.gz: 8914b74430f105820bbc5a41f44d6c573ff88492bcd882534f769fa2c2a11608
+  data.tar.gz: f3d1ffbec8dcb09ef354d21ab3786d2d5b9b0590a665ac95a949e7282668a66b
 SHA512:
-  metadata.gz: 26fdea81fbf8edcb85f0e6121c9bfa8b15dc34cf2b9166ebdd3cf158e2c09636d6ea5401baf203f293f6c2b2a866a2ddecdeacdd326c85bb3df6fa058af16800
-  data.tar.gz: 2493f082d861b7a8dadf60963df93c09aac10da94b6f0a7064644600b7da5bbd0079d0b58d4d1d1dbda717881f63af9fc53a5fdb9eab0c0ad644c1e7eaf5fb0b
+  metadata.gz: d52952922f19f864f97fd09297d8711c246ba54415bd40d60682569cbdfe0d51ccf7fb7673e7d921a361ab3657b35871f4999aad0baa80374dd3098cd3c267b2
+  data.tar.gz: 82afd75d6a4e57bfbe3708b59c1c1e7eec188cf2bcfd5921e3eeb50e006090d1f0839e5fc280be8ee60c8d6dc999bb07bb148e7e2220b7d061559048e14b6225

data/CHANGELOG.md

@@ -4,6 +4,69 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+
+- **`data-pin` — the pinned stack publishes itself.** `--nav-h` / `--nav-bottom`
+  answer for one element. Everything else that pins has been re-deriving the
+  same geometry by hand: on `mcritchie-studio`'s `/deployments` the app strip
+  positions itself with `:style="{ top: offset + 'px' }"`, and the lane headers
+  compute *"site header height + strip height"* in Alpine behind **their own**
+  `ResizeObserver` on `.vt-pinned-header` — while `--nav-bottom`, which already
+  answers the first half, goes unused there. Same shape as the four copies of
+  the navbar collapse, one layer up.
+
+  Any element carrying `data-pin="<name>"` now publishes `--pin-<name>-h` and
+  `--pin-<name>-bottom`, from **one shared `ResizeObserver`**, through the same
+  rAF coalescer and the same no-op-write skip the header already uses — and one
+  measurement pass for the whole frame, every read taken before any write.
+
+  That last part was wrong in the first cut of this change and review caught it:
+  the frame published the header (writing two inherited properties on
+  `documentElement`) and *then* read the pins, so the reads-before-writes order
+  held inside each function and broke across them. Measured at 6× CPU throttle
+  over 175 frames, pin loop on vs off: frames past 20ms **62 vs 42**, p90 **34.2
+  vs 26.0ms**; at 10×, **84/180 vs 4/180**. The header is now a pin like any
+  other — measured once, writing `--nav-h` / `--nav-bottom` from that same
+  reading rather than a second one. A consumer composes layers in pure
+  CSS:
+
+  ```css
+  top: max(var(--pin-nav-bottom, 0px), var(--pin-apps-bottom, 0px));
+  ```
+
+  **`max()` rather than a declared stacking order.** A hidden layer measures 0
+  and drops out, so nothing has to say which layer sits above which, and
+  reordering a partial cannot break the arithmetic.
+
+  **A host-owned header still publishes the legacy pair.** The registry is built
+  from `[data-pin]`, so a header that does not carry the attribute would never be
+  measured and `--nav-h` / `--nav-bottom` would never publish — and **both live
+  consumers own their header** (`turf-monster` `layouts/_navbar`,
+  `mcritchie-studio` `layouts/application`), neither carrying `data-pin`. Review
+  measured the gear drawer **82px** out of place and the contest board **114px**,
+  with 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. The
+  header is adopted as the legacy pin whether or not it asks to be.
+
+  **A departed layer has its properties removed.** `display:none` and `x-show`
+  keep the node, so it measures 0 and drops out of a consumer's `max()` on its
+  own; a REMOVED node cannot be measured by anything, and its last value would
+  stand forever — review measured a removed 300px strip holding the property at
+  300px against a real stack bottom of 160px. The registry remembers what it
+  published and clears whatever is no longer in the document.
+
+  The registry is **rebuilt from the document**, on attach and after
+  `turbo:before-stream-render` — a Turbo Stream replaces nodes without a
+  `turbo:load`, which is precisely the stale-node bug the board documents
+  against its own version.
+
+  `layouts/_navbar` carries `data-pin="nav"`, so every consuming app gets
+  `--pin-nav-bottom` for free. **`--nav-h` and `--nav-bottom` keep publishing
+  unchanged** — `studio/_sidebar_panel` and turf-monster's `scroll-margin-top`
+  read them, and `nav_offset_contract_test` still pins both to their exact
+  sources. This is additive.
+
+
 ### Changed
 
 - **The navbar collapse primitive is broadcastable, rate-limited, and cheap per

data/app/controllers/solana_sessions_controller.rb

@@ -22,6 +22,15 @@ class SolanaSessionsController < ApplicationController
     render json: { nonce: session[:solana_nonce] }
   end
 
+  # Where Phantom redirects back to after a mobile signIn. The page itself does
+  # the work — decrypt Phantom's reply with the keypair the deep link stashed in
+  # localStorage, rebuild the signed message, and POST it to #verify — so this
+  # action only renders it. It must stay UNAUTHENTICATED: the whole point is
+  # that nobody is signed in yet.
+  def phantom_callback
+    render :phantom_callback
+  end
+
   def verify
     pubkey_b58 = verify_solana_signature!(
       message:       params[:message],

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

@@ -46,7 +46,11 @@
     so it cannot move content under the reader.
     Preview keeps nav-shell (the calc()s have to resolve) but no x-data — the
     /navbar review page drives --nav-p from its own Scrolled toggle. %>
-<header <%= 'x-data="navCollapse()"'.html_safe unless is_preview %>
+<%# data-pin names this header as a layer of the pinned stack, so
+    layouts/studio/_head publishes --pin-nav-h and --pin-nav-bottom for it and
+    anything below can position off it in pure CSS. The legacy --nav-h /
+    --nav-bottom keep publishing unchanged; this is additive. %>
+<header data-pin="nav" <%= 'x-data="navCollapse()"'.html_safe unless is_preview %>
         <%# 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

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

@@ -200,74 +200,168 @@
   (function () {
     if (!window.ResizeObserver) return;
     var ro = null;
-    var current = null;
     var queued = false;
-    var lastH = null;
-    var lastBottom = null;
-    function publish(header) {
+    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.
+    //
+    // 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.
+    //
+    // 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;
-      // SKIP THE NO-OP WRITE. --nav-h and --nav-bottom are INHERITED custom
-      // properties on documentElement, so every write invalidates style for the
-      // whole document. Most republishes carry the same number — a scroll with
-      // the header already pinned, a resize that missed this element — and
-      // those cost nothing now.
-      // BOTH READS BEFORE EITHER WRITE. Writing a custom property on
-      // documentElement invalidates style, so a read taken after one write
-      // forces a fresh layout — the thrash this whole change exists to remove.
-      var h = header.offsetHeight;
-      // Scroll-dependent where --nav-h is not: chrome above the header scrolls
-      // away while an overlay is open (nothing here locks body scroll), so this
-      // is republished on scroll. Clamped at 0 — once the sticky header is
-      // pinned at top:0 the two values converge, which is why a consumer whose
-      // header already starts at the viewport top sees no change at all.
-      var bottom = Math.max(0, header.getBoundingClientRect().bottom);
-      if (h !== lastH) {
-        lastH = h;
-        style.setProperty('--nav-h', h + 'px');
+      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 (bottom !== lastBottom) {
-        lastBottom = bottom;
-        style.setProperty('--nav-bottom', bottom + '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 || !current) return;
+      if (queued || !pins.length) return;
       queued = true;
-      window.requestAnimationFrame(function () { queued = false; if (current) publish(current); });
+      window.requestAnimationFrame(function () { queued = false; publishAll(); });
     }
-    function attach() {
+    // 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 = {};
       var header = document.querySelector('header');
-      if (!header) {
-        // A page with no <header> — a bare error page, a print view. RELEASE the
-        // old node instead of returning: the scroll listener outlives the visit,
-        // and publishing from a DETACHED element yields an all-zero rect, which
-        // would drive --nav-h to 0px. Before this listener existed nothing ran
-        // after detach, so --nav-h simply kept its last value; keep that promise.
-        if (ro) { ro.disconnect(); ro = null; }
-        current = null;
-        return;
+      var headerPinned = false;
+      var nodes = document.querySelectorAll('[data-pin]');
+      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]);
+      }
+      // 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
+      // 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');
+        }
       }
-      current = header;
+      // 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);
+      }
+
+      published = seen;
+      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();
-      // THROUGH schedule(), NOT STRAIGHT TO publish(). This callback used to
-      // call publish() directly, which was fine while the header only resized
-      // during a 300ms transition. navCollapse made it resize on EVERY scroll
-      // frame, and each direct publish forced layout and then wrote two
-      // inherited custom properties on documentElement. Measured in
-      // turf-monster at 6x CPU throttle: frames over 20ms were 13/24 THROUGH
-      // the collapse ramp versus 0/24 past it, median 26ms versus 8ms.
-      // Ablating this observer alone took it to 0/24 and median 13ms — it cost
-      // about 2.6x the reflow it was reacting to. schedule() already coalesces
-      // to one publish per frame and is what the scroll and resize listeners
-      // use; the ResizeObserver was the one path that bypassed it.
-      ro = new ResizeObserver(schedule);
-      ro.observe(header);
-      publish(header);
+      registerPins();
+      if (!pins.length && ro) { ro.disconnect(); ro = null; }
     }
     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.
+    document.addEventListener('turbo:before-stream-render', function () {
+      window.requestAnimationFrame(registerPins);
+    });
     // Registered ONCE at script eval, not inside attach(), so a Turbo nav
-    // re-points `current` instead of stacking another listener per visit.
+    // re-scans instead of stacking another listener per visit.
     window.addEventListener('scroll', schedule, { passive: true });
     window.addEventListener('resize', schedule, { passive: true });
   })();

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

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

data/app/views/studio/modals/_wallet_connect.html.erb

@@ -141,16 +141,31 @@
          var n = ('' + name).toLowerCase();
          return ['phantom', 'solflare', 'backpack'].indexOf(n) !== -1 ? n : null;
        },
+       // Is there anywhere for a mobile Phantom row to GO? A consumer that does
+       // not render studio/solana/phantom_deeplink has no startPhantomDeepLink,
+       // and every branch below turns on this answer.
+       //
+       // WHY IT IS CHECKED AT ALL: without it, adopting this picker replaced an
+       // app's dead-end install row with a dead BUTTON — the install row
+       // suppressed, the deep-link row painted, and its tap a no-op. Found
+       // before the hub adopted, which had no mobile wallet path whatsoever.
+       // An absent capability must not default to the permissive branch.
+       get canDeepLink() {
+         return typeof startPhantomDeepLink === 'function';
+       },
        // A phone has no extension to install, and Phantom's own row on mobile
        // is the deep link below — so drop Phantom here rather than paint a
        // SECOND Phantom row pointing at a desktop download page the user
-       // cannot act on. Solflare and Backpack keep their install rows: there is
-       // no deep link for them, so the download page is still their only path.
+       // cannot act on. ONLY when a deep link can replace it: with no deep
+       // link the install row is the only Phantom path there is, dead end on
+       // iOS or not, and removing it leaves the user nothing. Solflare and
+       // Backpack keep their install rows either way — there is no deep link
+       // for them, so the download page is still their only path.
        get missingInstalls() {
          var self = this;
          return this.installs.filter(function(i) {
            if (self.hasWallet(i.name)) return false;
-           if (self.isMobile && i.name === 'Phantom') return false;
+           if (self.isMobile && self.canDeepLink && i.name === 'Phantom') return false;
            return true;
          });
        },
@@ -158,7 +173,7 @@
        // means the detected row above already offers a working connect, so a
        // deep link would only offer to leave Phantom to open Phantom.
        get showPhantomDeepLink() {
-         return this.isMobile && !this.hasWallet('Phantom');
+         return this.isMobile && !this.hasWallet('Phantom') && this.canDeepLink;
        },
        async pick(name) {
          if (this.connecting) return;

data/app/views/studio/modals/blocks/_close_x.html.erb

@@ -13,6 +13,24 @@
   modals/_wallet_deposit, _wallet_topup, _cdp_ramp, _onramp_hub, _buy_entry_token
   and three under modals/auth/ (_paypal_tokens, _usdc_funding, _tokens).
 
+  THE /admin/style SPECIMENS SHOW STRUCTURE, NOT CONTENT. If you are adopting
+  this primitive to replace existing markup, take every VALUE — here modal_store
+  and label — from the markup you are REPLACING, and use the specimen only to
+  learn which locals exist and how they compose. A specimen is a demo: the
+  engine is entitled to pick any plausible value for it, and those values are
+  not your app's. style/modals/_ds_wallet_topup passes modal_store "dsModals",
+  its own page-scoped host; a callsite that copies it closes a store the app
+  does not have, so the mark renders and does nothing.
+
+  The incident that earned this paragraph: an adopter built a new callsite from
+  style/modals/_ds_wallet_topup and carried its icon across. The specimen passes
+  U+1F39F ADMISSION TICKETS; the markup being replaced had always drawn U+1F3AB
+  TICKET. A different glyph in a different colour landed on the primary rail of
+  the web2 kill-switch face of Top Up Wallet — the single call to action shown to
+  the audience that cannot pay with USDC. Nothing raised, CI was 6/6 green, and
+  no assertion anywhere pinned the glyph. It was caught only by rendering the
+  modal before and after and diffing the markup.
+
   THE PARENT MUST BE POSITIONED. This is `absolute`, so it anchors to the nearest
   positioned ancestor — every callsite wraps its card in `class="relative"`. On an
   unpositioned parent the × climbs to whatever is positioned above it, which in a

data/app/views/studio/modals/blocks/_rail_row.html.erb

@@ -9,6 +9,22 @@
   why that is a named local rather than a class passthrough — a passthrough would
   have let the eleventh copy drift on day one, which is how ten happened.
 
+  THE /admin/style SPECIMENS SHOW STRUCTURE, NOT CONTENT. If you are adopting
+  this primitive to replace existing markup, take every VALUE — icon_label,
+  icon_bg, title, subtitle, badge, data hooks — from the markup you are
+  REPLACING, and use the specimen only to learn which locals exist and how
+  they compose. A specimen is a demo: the engine is entitled to pick any
+  plausible value for it, and those values are not your app's.
+
+  The incident that earned this paragraph: an adopter built a new callsite from
+  style/modals/_ds_wallet_topup and carried its icon across. The specimen passes
+  U+1F39F ADMISSION TICKETS; the markup being replaced had always drawn U+1F3AB
+  TICKET. A different glyph in a different colour landed on the primary rail of
+  the web2 kill-switch face of Top Up Wallet — the single call to action shown to
+  the audience that cannot pay with USDC. Nothing raised, CI was 6/6 green, and
+  no assertion anywhere pinned the glyph. It was caught only by rendering the
+  modal before and after and diffing the markup.
+
   THE EMPHASIS IS A RANKING, not decoration. A hub full of equally-weighted rails
   asks the person to compare payment processors, which is not a question they can
   answer. Exactly one rail should be :primary — the one the app wants taken —

data/app/views/studio/modals/blocks/_success_card.html.erb

@@ -236,10 +236,17 @@
              :style="{ animation: 'studio-modal-drain ' + _total + 's linear forwards' }"></div>
         <span class="relative z-10"><%= cta_label %></span>
       </button>
+    <%# btn-lg, matching the drain branches above and every sibling in this family
+        (_onchain_success, _cta_redirect). Without it these two rendered 36px
+        (.btn alone: py-2 + text-sm) while the drain branch rendered 48 — the
+        same card, two heights, decided by whether an auto-redirect happened to
+        be configured. 36px is also under the 44px mobile touch-target
+        guideline. Not 40px: that is the HAND-ROLLED drain button one branch up
+        (px-4 py-2.5 text-sm), a different element with a different sum. %>
     <% elsif local_assigns[:cta_href_key] %>
-      <a :href="<%= cta_href_key %>" class="btn btn-primary w-full"><%= cta_label %></a>
+      <a :href="<%= cta_href_key %>" class="btn btn-primary btn-lg w-full"><%= cta_label %></a>
     <% elsif local_assigns[:cta_event] %>
-      <button @click="$dispatch('<%= cta_event %>')" class="btn btn-primary w-full"><%= cta_label %></button>
+      <button @click="$dispatch('<%= cta_event %>')" class="btn btn-primary btn-lg w-full"><%= cta_label %></button>
     <% end %>
   <% end %>
 

data/app/views/studio/solana/_deeplink_assets.html.erb

@@ -0,0 +1,37 @@
+<%#
+  tweetnacl, for the Phantom mobile deep link. Both halves of that flow need
+  window.nacl: the deep link generates an x25519 keypair so Phantom can encrypt
+  its reply, and the callback opens that box with the stashed secret.
+
+  IDEMPOTENT ON PURPOSE. turf-monster already loads tweetnacl from its own
+  layout, so this must not load a second copy there; the guard means a consumer
+  that already supplies nacl keeps its own and one that does not (the hub, which
+  had no mobile wallet path at all) gets it here.
+
+  Pinned to an exact version rather than a range: this is signing-path crypto,
+  and a range lets a CDN swap it under a running app. The same reasoning is
+  written out beside turf-monster's web3.js pin.
+
+  Render before studio/solana/phantom_deeplink and in the callback view.
+%>
+<script>
+  // NOT document.write. Under turbo-rails a Drive visit re-executes body scripts
+  // at readyState === 'complete', where document.write implicitly calls
+  // document.open() and BLANKS THE PAGE — on exactly the consumer this guard
+  // exists for. Append a real element instead; it is also non-blocking.
+  (function () {
+    if (typeof window.nacl !== 'undefined') return;
+    if (document.querySelector('script[data-studio-nacl]')) return;
+    var s = document.createElement('script');
+    s.src = 'https://cdn.jsdelivr.net/npm/tweetnacl@1.0.3/nacl-fast.min.js';
+    // Derived with `openssl dgst -sha384 -binary | openssl base64 -A` against the
+    // fetched file, and cross-checked against the value turf-monster already pins
+    // for this exact URL. NEVER hand-write an SRI: a plausible-looking wrong one
+    // makes the browser refuse the script and nacl silently absent, which fails
+    // every mobile sign-in before any other code runs.
+    s.integrity = 'sha384-05+sicyRJQ56XpL4U9HJ8YbtSzFDvAg7apPKOGV6A0JsAJKFM68jp5oLnUjG5mEp';
+    s.crossOrigin = 'anonymous';
+    s.setAttribute('data-studio-nacl', '');
+    document.head.appendChild(s);
+  })();
+</script>

data/app/views/studio/solana/_phantom_deeplink.html.erb

@@ -0,0 +1,167 @@
+<%#
+  Phantom MOBILE deep link — the round trip a phone needs to sign in with a
+  wallet. On desktop Phantom is a browser extension the page can call directly;
+  on a phone it is a separate APP, so the page hands off to it and comes back.
+
+  PROMOTED from turf-monster (app/javascript/phantom_deeplink.js) so every
+  consumer gets it. The server half was already shared — the engine's
+  solana_sessions_controller owns nonce + verify and Solana::SessionAuth owns
+  verify_solana_signature! — only this mobile round trip was app-side.
+
+  Render it once, wherever the Connect-Wallet flow can be reached — an ERB
+  output tag rendering the partial path "studio/solana/phantom_deeplink".
+  (Described rather than quoted on purpose: an ERB comment ends at the first
+  close sequence, so spelling the tag out here would terminate this comment and
+  leak the rest of it as visible text into every consuming app. The engine's
+  erb_comment_leak_test enforces that, and it caught this very paragraph.)
+
+  It defines window.startPhantomDeepLink(linkMode, currentUserId). The engine's
+  wallet picker (studio/modals/_wallet_connect) gates its mobile Phantom row on
+  that function EXISTING, so a consumer that does not render this partial keeps
+  its install row instead of painting a button that does nothing.
+
+  THREE THINGS THAT MUST NOT BE MADE CONFIGURABLE — traced through
+  Solana::SessionAuth#verify_solana_signature! before this was generalised:
+
+    domain        the client builds it from window.location.host and the server
+                  checks it against request.host_with_port (OPSEC-018). An app
+                  override breaks sign-in.
+    User-ID line  OPSEC-005 does a SUBSTRING match on "User-ID: <id>". Do not
+                  reformat it and do not translate it.
+    the nonce     deleted server-side BEFORE verification; that is the replay
+                  protection for the login path.
+
+  The STATEMENT is the one part that varies, and it varies safely: the server
+  does NOT verify it — it is what the human reads inside Phantom. It derives
+  from Studio.app_name, which reproduces turf-monster's previous literal
+  ("Sign in to Turf Monster") BYTE FOR BYTE, so promoting this changed no
+  signed message. It MUST match the callback's copy exactly, because the
+  callback reconstructs the signed message to post for verification — both read
+  this same helper, which is why they cannot drift.
+
+  Requires tweetnacl (window.nacl); render "studio/solana/deeplink_assets"
+  first, or supply it yourself.
+%>
+<script>
+  (function () {
+    var STATEMENT = <%= Studio.wallet_sign_in_statement.to_json.html_safe %>;
+
+    // Base58, INLINE and self-contained. turf-monster took this from a separate
+    // app/javascript/base58.js module that assigned window.encodeBase58, so its
+    // deep link depended on a second global. Promoting only the deep link would
+    // have left encodeBase58 undefined in any consumer without that file — it
+    // throws on the first keypair encode, at the moment the user taps Connect.
+    // The callback view already carries its own codec for the same reason; this
+    // matches it, so the partial has exactly one dependency (nacl) and it is a
+    // guarded one.
+    // THE CONSTANT THE ENCODER READS. It was left behind when the function body
+    // was inlined: base58.js declares it at module scope, so it is unreachable
+    // from a classic script, and encodeBase58 referenced a free variable that
+    // resolved to nothing AT CALL TIME. Every mobile sign-in threw
+    // "B58_ALPHABET is not defined" on the first keypair encode.
+    //
+    // Invisible to eleven passing view tests and to a browser spec that checked
+    // `typeof startPhantomDeepLink` without ever CALLING it. A parse-time
+    // mutation cannot reach this class either — the program parses fine.
+    const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+    function encodeBase58(bytes) {
+      const digits = [0];
+      for (let i = 0; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+          carry += digits[j] << 8;
+          digits[j] = carry % 58;
+          carry = (carry / 58) | 0;
+        }
+        while (carry) { digits.push(carry % 58); carry = (carry / 58) | 0; }
+      }
+      let str = '';
+      for (let i = 0; i < bytes.length && bytes[i] === 0; i++) str += '1';
+      for (let i = digits.length - 1; i >= 0; i--) str += B58_ALPHABET[digits[i]];
+      return str;
+    }
+
+    // Phantom deep link protocol for mobile browsers
+    // Uses signIn deep link — ONE trip to Phantom (connect + sign combined)
+    // Flow: generate keypair → fetch nonce → build SIWS input → redirect to Phantom signIn
+
+    function startPhantomDeepLink(linkMode, currentUserId) {
+      // The consumer declares its cluster on <body data-solana-cluster="...">.
+  // turf-monster does; an app that does NOT silently signs against devnet while
+  // its wallet is on mainnet, which reads to the user as a rejected signature
+  // and to the log as nothing. Warn loudly rather than guess quietly — the
+  // default stays devnet so behaviour is unchanged for anyone already relying
+  // on it.
+  var cluster = document.body.dataset.solanaCluster;
+  if (!cluster) {
+    console.warn('[StudioSolana] no data-solana-cluster on <body>; defaulting to devnet. ' +
+                 'Set it on the body tag to sign against the cluster you mean.');
+    cluster = 'devnet';
+  }
+      var callbackUrl = window.location.origin + '/auth/phantom/callback';
+
+      // Generate x25519 keypair for decrypting Phantom's response
+      var dappKeyPair = nacl.box.keyPair();
+
+      // Fetch nonce from server, then redirect to Phantom signIn
+      fetch('/auth/solana/nonce')
+        .then(function(r) { return r.json(); })
+        .then(function(data) {
+          // OPSEC-005: when linking a wallet to a logged-in user, embed
+          // `User-ID: <id>` so the server can refuse signatures captured
+          // against a different session's nonce. Login (no currentUserId)
+          // skips the binding line.
+          var statement = STATEMENT;
+          if (linkMode && currentUserId) {
+            statement = statement + '\nUser-ID: ' + currentUserId;
+          }
+
+          // Build SIWS input (CAIP-122 / Sign In With Solana format)
+          // Note: chainId omitted — optional per spec, avoids mismatch warning
+          // when app is on devnet but user's wallet is on mainnet
+          var signInInput = {
+            domain: window.location.host,
+            statement: statement,
+            uri: window.location.origin,
+            version: '1',
+            nonce: data.nonce,
+            issuedAt: new Date().toISOString()
+          };
+
+          // Save state to localStorage (persists across redirect)
+          localStorage.setItem('phantom_dl_secret', encodeBase58(dappKeyPair.secretKey));
+          localStorage.setItem('phantom_dl_pubkey', encodeBase58(dappKeyPair.publicKey));
+          localStorage.setItem('phantom_dl_nonce', data.nonce);
+          localStorage.setItem('phantom_dl_nonce_at', Date.now().toString());
+          localStorage.setItem('phantom_dl_step', 'signIn');
+          localStorage.setItem('phantom_dl_link_mode', linkMode ? 'true' : 'false');
+          localStorage.setItem('phantom_dl_cluster', cluster);
+          if (currentUserId) {
+            localStorage.setItem('phantom_dl_user_id', String(currentUserId));
+          } else {
+            localStorage.removeItem('phantom_dl_user_id');
+          }
+
+          // Base58-encode the SIWS input JSON (NOT encrypted — per Phantom signIn protocol)
+          var payloadB58 = encodeBase58(new TextEncoder().encode(JSON.stringify(signInInput)));
+
+          // Build Phantom signIn deep link
+          var params = new URLSearchParams({
+            dapp_encryption_public_key: encodeBase58(dappKeyPair.publicKey),
+            cluster: cluster,
+            app_url: window.location.origin,
+            redirect_link: callbackUrl,
+            payload: payloadB58
+          });
+
+          window.location.href = 'https://phantom.app/ul/v1/signIn?' + params.toString();
+        })
+        .catch(function(err) {
+          alert('Failed to start Phantom connection: ' + err.message);
+        });
+    }
+
+    window.startPhantomDeepLink = startPhantomDeepLink;
+  })();
+</script>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.63.0"
+  VERSION = "0.65.0"
 end

data/lib/studio.rb

@@ -56,6 +56,46 @@ module Studio
   mattr_accessor :after_newsletter_change, default: ->(_user, subscribed:, first_join:) {}
   mattr_accessor :sso_logo,            default: nil
   mattr_accessor :wallet_address_method, default: nil
+
+  # The statement a wallet signs, and the line the human reads inside Phantom.
+  # Deliberately DERIVED rather than configured: "Sign in to Turf Monster" was
+  # turf-monster's literal before the mobile deep link was promoted, and
+  # app_name reproduces it byte for byte, so nothing that was already signed
+  # changed. Safe to vary because the server does NOT verify this text — see
+  # Solana::SessionAuth#verify_solana_signature!, which checks the nonce, the
+  # host, and the OPSEC-005 User-ID binding, and nothing else about the message.
+  # UNVERIFIED IS NOT UNCONSTRAINED. Solana::AuthVerifier reads the nonce with a
+  # FIRST-MATCH /Nonce: (\w+)/ and the statement is interpolated ABOVE the real
+  # nonce line, so a statement containing "Nonce: something" would be read as the
+  # nonce and fail every verify. Not an attack surface (this is app config, never
+  # user input) but a real constraint on what may be put here.
+  # Both the deep-link partial and the callback view read THIS, so they cannot
+  # drift; the callback rebuilds the signed message to post for verification, so
+  # a drift between them would fail every mobile sign-in.
+  mattr_accessor :wallet_sign_in_statement_builder,
+                 default: -> { "Sign in to #{Studio.app_name}" }
+
+  def self.wallet_sign_in_statement
+    wallet_sign_in_statement_builder.call
+  end
+
+  # The Phantom callback's on-page debug sink. DEFAULTS TO OFF, and the default
+  # is the point: that sink printed the dapp x25519 SECRET KEY to the page and
+  # the console on every mobile sign-in. A capability that leaks a signing key
+  # must be opted INTO, never defaulted on and switched off per environment.
+  #
+  # Rails.env.production? is the wrong predicate here and that is why this is a
+  # lambda rather than an env check: a Heroku QA dyno runs RAILS_ENV=production,
+  # so an env test would take QA's debugging away. turf-monster restores exactly
+  # what it had with:
+  #
+  #     config.wallet_debug_sink = -> { !AppFlags.live_production? }
+  #
+  # The callback treats an absent sink as "debug off" and stays null-safe, so
+  # turning this off can never break sign-in.
+  mattr_accessor :wallet_debug_sink, default: -> { false }
+
+  def self.wallet_debug_sink? = wallet_debug_sink.call
   mattr_accessor :theme_logos,         default: []
   mattr_accessor :sticky_table_headers, default: false
 
@@ -782,13 +822,18 @@ module Studio
              constraints: { token: %r{[^/]+} }
       end
 
-      # Solana / Phantom wallet sign-in (nonce challenge + signature verify).
-      # The browser posts to these literal paths from the shared Connect-Wallet
-      # flow; app-specific surfaces (mobile deep-link callback, account-linking,
-      # OAuth popup) stay in the consuming app's routes.
+      # Solana / Phantom wallet sign-in (nonce challenge + signature verify),
+      # plus the MOBILE deep-link callback Phantom redirects back to. The
+      # callback used to be listed here as app-specific and is not any more —
+      # it was promoted with the deep link itself, because the hub had no
+      # mobile wallet path at all and copying 400 lines of SIWS protocol per
+      # app is how the picker came to exist three times. Account-linking and
+      # the OAuth popup DO stay app-side.
       if Studio.draw_auth_routes && Studio.auth_method?(:wallet)
         get  "auth/solana/nonce",  to: "solana_sessions#nonce",  as: :solana_nonce
         post "auth/solana/verify", to: "solana_sessions#verify", as: :solana_verify
+        get  "auth/phantom/callback", to: "solana_sessions#phantom_callback",
+             as: :phantom_callback
       end
 
       # The shared profile page. ON by default — unlike /admin/emails and the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.63.0
+  version: 0.65.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -401,6 +401,7 @@ files:
 - app/views/schema/index.html.erb
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
+- app/views/solana_sessions/phantom_callback.html.erb
 - app/views/studio/_at_time_script.html.erb
 - app/views/studio/_birthday_assets.html.erb
 - app/views/studio/_board_assets.html.erb
@@ -498,6 +499,8 @@ files:
 - app/views/studio/profiles/_save_controls.html.erb
 - app/views/studio/profiles/edit.html.erb
 - app/views/studio/profiles/show.html.erb
+- app/views/studio/solana/_deeplink_assets.html.erb
+- app/views/studio/solana/_phantom_deeplink.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb