solana-studio 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa775c67a1f3ae154dabf231c294c86e6a03dc74f2866fcfdab2cb7f8bf9da9b
-  data.tar.gz: 6dd4bd255c9ea0d99c8daaeff4a176152226e63a61f36943869f70f3e9a57441
+  metadata.gz: 70e8fb8d6ac999a75bafc72260c08f2bdc4812a10506d2e6c4185c30432dcdda
+  data.tar.gz: 1a679edcf52dfe801d46e9cd2e8009169b54a1546a1eb5052751e3bb17d0aed1
 SHA512:
-  metadata.gz: b52fd18bf1bab93c0a060d5cc135b1e9bc81bdfb5b32b9771251f831ffaaa5653891706927904e5e57a852094c3a4e41a45350e84bcca16f4f30cd9913bdbc55
-  data.tar.gz: 701023cfadfee72780409a021e2e2bfa2223cb3366a07659409764f5aa7f4aa1fb2adc961a5b7ba68103fe5263dfa77506f659727c6c315171d63faa4d16f735
+  metadata.gz: 9cb3227a5821ec101fa87e67d2f5953a60fef0362b53e1d3fdb74f555f8acbabe19de68167906dbba84b537e4e1350652b68b19fa0a365eadf6e31bf7fa798bd
+  data.tar.gz: 27873ce2d2d94c22c313d4a587ac7be649fa0dc9b7eb3f468cb80150f8f97b05a5b33ff42a09304afaa125b197e27ad005986d49ec35bccccb630ff3e447318e

data/CHANGELOG.md

@@ -6,12 +6,22 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 - **The wallet sign-in button, contributed into studio-engine's auth modal** (`app/views/solana_studio/auth/_wallet_credential.html.erb`). Part of the base/bolt-on split: studio-engine plus McRitchie Studio is the template every app is built from, web2 and web3 alike, and this gem plus Turf Monster is the web3 bolt-on. Sign-in is a base concern so the modal stays in the engine; **wallets are not**, so the button moved here. The engine renders whatever resolves at `solana_studio/auth/wallet_credential` and nothing when the path is empty, so bundling this gem IS the registration and a web2 app carries no wallet markup at all. Deliberately NOT solved by giving this gem its own auth modal: that would fork a surface both apps sign in through, which is how the wallet picker reached three drifting copies before it was promoted. The engine keeps both halves of the existing gate (`Studio.auth_method?(:wallet)` and `Studio.feature?(:web3)`) so the hub — which bundles this gem for its signing primitives with web3 off — still renders a web2 sign-in modal.
+- **The web3 modals move here** — `solana_studio/modals/wallet_connect`, `solana_studio/modals/web3_step_up`, `solana_studio/phantom_deeplink` and `solana_studio/deeplink_assets`, promoted out of studio-engine byte for byte. They are Solana-specific to the last line, and studio-engine is the engine EVERY app bundles, including apps that ship no chain feature at all. Only the home changes: the markup, the locals and the behaviour are identical, and the four files are added here before studio-engine drops its copies, so no consumer is ever without a home for them.
+
+### Changed
+- `.github/workflows/gem-ci.yml` asserts all four new partials are inside the BUILT gem, not just the manifest. `test/gemspec_test.rb` already asserts the invariant that every `app/` file reaches `spec.files`; the artifact check is a different claim, and only the artifact is what a consumer installs.
 
 ### Tests
 - `test/auth_credential_test.rb` (7): the partial sits at the path the engine resolves, the click handler consults the modal's age gate, visibility binds to the shared `methodOn('wallet')` toggle, `modal_store` is required with no default, the swap carries the picker's `backTo`/`ageAttested` contract, the brand gradient id is namespaced against collisions, and the mark stays inline rather than becoming a sprockets asset request. Every assertion reads ERB-comment-stripped source, because this file documents its own contract in prose and a bare grep would match the paragraph instead of the code — proven by mutating the gate into a comment and watching it go red.
 - `test/gemspec_test.rb` and `.github/workflows/gem-ci.yml` name the new partial alongside the modal, so a `spec.files` glob that stopped matching it fails at build rather than in a consumer.
+- **`test/web3_modals_test.rb`** (5) — resolves each partial BY VIRTUAL PATH through an `ActionView::LookupContext` over the engine's own view paths, which is the mechanism a consumer uses, rather than `File.exist?` (true of a file no consumer can reach). Each identifier must sit under this gem's view root — asserted that way rather than by matching `/gems/` in the path, because turf-monster's own `test/support/resolved_wallet_picker.rb` warns against that form: it fails a path checkout while proving nothing extra.
+- **`test/erb_comment_leak_test.rb`** (6) — ported from studio-engine, whose glob stops covering these files the moment they leave it. An ERB comment ends at its FIRST close sequence, so a comment quoting a tag leaks its tail into the page as visible prose; the two most comment-dense files in the move (`_wallet_connect`, `_web3_step_up`, 8 comments each) were exactly the ones losing the guard. All three leak signatures ported with their guard-the-guard probes, and mutation-proved on a real moved file.
+
+### Notes for hosts
+- **These require studio-engine at render time** — they render its modal host and its shared blocks by name, and paint with its utilities and theme tokens. `solana_studio/modals/network_mismatch` already shipped on exactly these terms, so this is the established arrangement rather than new coupling. studio-engine stays a DEVELOPMENT dependency; a runtime one would drag Rails into every plain-Ruby consumer.
+- **`phantom_deeplink` still emits `Studio.wallet_sign_in_statement`, deliberately.** studio-engine's `solana_sessions/phantom_callback` rebuilds the signed message to verify it, so both halves read one accessor precisely so they cannot drift. Parameterising it would decouple the gem, read as an improvement, and break the signature check on every mobile sign-in. Pinned from both directions in `test/web3_modals_test.rb`.
 
-## Unreleased — targets v0.5.0 (minor)
+## v0.5.0
 
 Ships the gem's first Rails half, and its first CI. The version number is
 allocated by the release conductor, not by this entry.

data/README.md

@@ -214,6 +214,60 @@ Why a contributed button and not a second auth modal: Turf Monster wants Google
 plus magic-link plus wallet, McRitchie Studio wants Google plus magic-link. A
 forked modal would put a surface both apps sign in through into two files, which
 is how the wallet picker reached three copies before it was promoted.
+### Web3 modals
+
+Four partials promoted out of studio-engine, where every consumer paid for them
+whether or not it shipped a chain feature at all:
+
+| Virtual path | What it is |
+|---|---|
+| `solana_studio/modals/wallet_connect` | The Connect-Wallet picker — detected wallets, install rows, and Phantom's mobile deep-link row |
+| `solana_studio/modals/web3_step_up` | The sign-with-your-wallet step-up card |
+| `solana_studio/phantom_deeplink` | Defines `window.startPhantomDeepLink(linkMode, currentUserId)` — the phone round trip |
+| `solana_studio/deeplink_assets` | An idempotent, non-blocking tweetnacl loader for that round trip |
+
+```erb
+<%# once, inside your modal host %>
+<template x-if="$store.modals.current().id === 'wallet-connect'">
+  <%= render "solana_studio/modals/wallet_connect" %>
+</template>
+
+<template x-if="$store.modals.current().id === 'web3-step-up'">
+  <%= render "solana_studio/modals/web3_step_up" %>
+</template>
+```
+
+Render `solana_studio/phantom_deeplink` **once**, anywhere the Connect-Wallet
+flow can be reached. The picker gates its mobile Phantom row on
+`startPhantomDeepLink` existing, so a host that skips it keeps the install row
+instead of painting a button that does nothing.
+
+**These require studio-engine at render time.** They render its modal host and
+its shared blocks (`studio/modals/blocks/wallet_brand_sprite`, `.../card_header`)
+by name, paint with its utilities (`badge`, `pulse-cta`, `spinner`) and theme
+role tokens, and drive its store through `$store.<store>.swap()`. studio-engine
+stays a **development** dependency here — a runtime one would drag Rails into
+every plain-Ruby consumer, which is what `lib/solana_studio/engine.rb`'s guard
+exists to prevent — so this is a documented host requirement, not something the
+gem can enforce from inside. `solana_studio/modals/network_mismatch` already
+shipped on exactly these terms.
+
+#### The signed statement is not configurable
+
+`solana_studio/phantom_deeplink` emits `Studio.wallet_sign_in_statement`, and it
+must keep doing so. studio-engine's `solana_sessions/phantom_callback`
+**rebuilds** the signed message to post for verification, so the two read one
+accessor precisely so they cannot drift; a caller-supplied statement would break
+the signature check on every mobile sign-in. `test/web3_modals_test.rb` pins
+this from both directions.
+
+#### Choosing between the loader and your own tag
+
+`solana_studio/deeplink_assets` **appends** a script element, so it is
+asynchronous. A callback that reads `nacl` at parse time will lose that race.
+Adopt the loader only together with a callback that waits; otherwise keep a
+blocking `<script>` tag of your own with the same SRI-pinned URL. turf-monster
+deliberately does the latter.
 
 ## Dependencies
 
@@ -226,12 +280,47 @@ is how the wallet picker reached three copies before it was promoted.
 
 See [RUNBOOK.md](./RUNBOOK.md) for troubleshooting and local test commands.
 
+### 🧊 The durable-nonce primitives have two consumers, and one of them is on ice
+
+`Solana::SystemProgram` and `Solana::NonceAccount` landed together in **v0.4.6
+(2026-06-02, `11ec512`)** for **two** consumers at once, and the commit says so:
+*"the reusable core for the signing console's two-browser flow and for making
+turf's operator tx flows expiry-immune."*
+
+**The first of those went on ice on 2026-08-31.** McRitchie Studio's admin
+signing console — N wallets signing in separate browsers, anchored on a durable
+nonce so a half-signed transaction does not expire between signers — is **frozen
+in place: still working, not removed, not deprecated**, and not expected to drive
+any further work in this gem. Its full note (why it was frozen, and the one
+question that would revive it) lives in the hub, at `docs/SIGNING_CONSOLE_V2.md`.
+
+**Do not read that as permission to drop these two files.** The second consumer
+is the one in production:
+
+| Primitive | Live use |
+|---|---|
+| `Solana::SystemProgram.advance_nonce_account` | turf-monster prepends it as **instruction #0** of a durable-nonce vault cosign transaction (`app/services/solana/vault.rb`). Its cosign validator also **allow-lists exactly this one System instruction** — a nonce-anchored entry with any other System instruction is rejected. |
+| `Solana::NonceAccount.parse` | turf-monster reads the on-chain nonce account in the same path. |
+
+So the frozen consumer is the *quieter* one, never the only one. Both primitives
+are byte-match tested in `test/system_program_test.rb`, and a change to either
+still lands on turf-monster's money path — treat them as `onchain`, not as dead
+code left over from a shelved tool.
+
 ### The browser lane
 
-The Ruby suite cannot see two things this gem ships: whether
-`network_guard.js` actually **runs** in a browser, and whether
+The Ruby suite cannot see three things this gem ships: whether
+`network_guard.js` actually **runs** in a browser, whether
 `_network_mismatch.html.erb` **renders** (rendering it needs studio-engine's modal
-blocks and a view context, so `test/views_test.rb` only proves it compiles).
+blocks and a view context, so `test/views_test.rb` only proves it compiles), and
+whether the base58 encoder inlined in `_phantom_deeplink.html.erb` produces the
+**right bytes**. That last one is signing-path code: the deep link encodes the
+payload a user signs inside Phantom, so an encoder that mis-encodes yields a
+signature over the wrong bytes. The failure is invisible to a String assertion —
+the source is identical either way — and lands when someone taps Connect on a
+phone. `e2e/phantom_deeplink.spec.js` decodes the emitted payload with its own
+independent implementation and compares bytes, rather than checking the parameter
+merely looks like base58.
 
 ```bash
 npm ci && npx playwright install chromium

data/app/views/solana_studio/_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 solana_studio/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/solana_studio/_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 "solana_studio/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 (solana_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 "solana_studio/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/app/views/solana_studio/modals/_wallet_connect.html.erb

@@ -0,0 +1,330 @@
+<%#
+  "Connect Wallet" picker — the reown-style wallet chooser, OWNED BY THE ENGINE.
+  Promoted out of style/modals/_wallet_connect (where only the living style guide
+  could render it) so the apps stop each keeping their own copy: before this the
+  same screen existed THREE times — turf-monster 226 lines, mcritchie-studio 107,
+  and the guide's 176 — sharing no code and drifting apart. The hub's copy still
+  pointed at app-served PNGs the engine's brand sprite replaced in 0.20.
+
+  Mount it inside the modal host's <template x-if="id==='wallet-connect'">, so
+  this MUST have a SINGLE ROOT — everything lives inside the outer <div>.
+
+  Props (set by whoever opens the modal, read off the store entry):
+    linkMode       — true when this is an account-LINKING flow (already logged in)
+    currentUserId  — bound into the SIWS message when linking
+    returnUrl      — where to go after a successful connect
+
+  Locals:
+    store       — Alpine store name backing the modal. Default "modals".
+    connect_fn  — name of the window function that connects AND verifies a
+                  wallet, called as window[connect_fn](name, opts) and expected
+                  to resolve { success: true, redirect } or { success: false,
+                  error }. Default "solanaConnectAndVerify".
+    title       — card heading. Default "Connect Wallet".
+    extra_data  — EXTRA x-data members for this component, as a JS fragment with
+                  NO surrounding braces, merged after the built-ins. This is how
+                  an app adds its own state (and the hooks below) without forking
+                  the picker. Default "".
+
+                  SHAPED LIKE style/_modal_specimen's card_data but NOT handled
+                  the same way, and the difference is deliberate. That file marks
+                  open_expr and glow_when html_safe and leaves card_data escaped
+                  (:42-44), so its fragment reaches the attribute as entities.
+                  Both work — a browser decodes entities inside an attribute —
+                  but only one is readable in View Source, and a reader comparing
+                  the two seams deserves to be told they diverge rather than left
+                  to assume a typo. If they are ever reconciled, reconcile them
+                  in one pass; do not quietly copy this decision back.
+    slot        — OPTIONAL partial path rendered between the heading and the
+                  wallet rows: the place for an app's legal-age attestation or
+                  any other pre-connect consent. It renders INSIDE this
+                  component's root, so it can bind straight to the members
+                  extra_data contributes.
+    slot_locals — locals for that partial. Default {}.
+
+  A NAMED LOCAL AND NOT A BLOCK, and this is load-bearing. `block_given?` is
+  ALWAYS TRUE inside a compiled Rails partial — PartialRenderer hands the
+  template a block either way — so a bare `yield if block_given?` falls through
+  to view_flow[:layout] and prints THE WHOLE CAPTURED PAGE BODY inside the card.
+  Both consuming apps mount the modal host in application.html.erb, which is
+  exactly when that flow is populated, and the hub's planned adoption is a bare
+  render with no block. Caught in review of this partial's own first version.
+  blocks/_card_header documents the same hazard and blocks/_entry_confirmed made
+  the same choice (above_seeds) for the same reason.
+
+  HOOKS — optional methods an app defines in extra_data. Each is called only if
+  it exists, so an app that needs none passes no extra_data at all. They are
+  METHODS rather than string-expression locals on purpose: an Alpine expression
+  threaded through an ERB local has to survive a double-quoted HTML attribute,
+  and an escaped handler there renders working-looking HTML that passes every
+  markup assertion. Methods live inside the x-data where they are just code.
+
+    onInit()             extra init, run BEFORE the first wallet refresh
+    canPick()            return falsy to ABORT a pick or a deep link (a consent
+                         gate); absent means always allowed
+    verifyArgs()         object merged into the connect options (extra fields
+                         the app's verify endpoint needs)
+    onConnected(result)  what to do on success; DEFAULT navigates to
+                         props.returnUrl || result.redirect || '/'. Override it
+                         for a demo or an in-page continuation — and note the
+                         override OWNS the reset: pick() leaves `connecting` and
+                         `picking` set, because the default navigates away and
+                         never comes back. An override that stays on the page
+                         must clear both or the rows stay disabled.
+    onDeepLink()         REPLACES the Phantom deep-link action. Use it to stash
+                         state that must survive the round trip out of the
+                         browser, or to do something else entirely. The default
+                         calls window.startPhantomDeepLink(linkMode, userId).
+    onBack()             the Back button; DEFAULT closes the modal
+%>
+<%
+  store      = local_assigns.fetch(:store, "modals")
+  connect_fn = local_assigns.fetch(:connect_fn, "solanaConnectAndVerify")
+  title      = local_assigns.fetch(:title, "Connect Wallet")
+  # html_safe, and deliberately: extra_data is a DEVELOPER-AUTHORED JavaScript
+  # fragment, never user input. Without it ActionView escapes the fragment on
+  # its way into the x-data attribute and every single quote becomes &#39; —
+  # which still PARSES (the browser decodes entities in an attribute), so the
+  # page works and only the source reads wrong. That is exactly the failure a
+  # markup assertion cannot see. On style/_modal_specimen: see the header. It
+  # marks open_expr and glow_when safe but leaves card_data ESCAPED, so the two
+  # seams DIVERGE — deliberately, and not because one of them has a typo.
+  slot        = local_assigns[:slot].presence
+  slot_locals = local_assigns.fetch(:slot_locals, {})
+  extra_data  = local_assigns.fetch(:extra_data, "").to_s.strip
+  # Built here and marked safe ONCE, rather than interpolated at the call site.
+  # Two traps sit on this line, both of which render a working-looking page:
+  #   1. Marking extra_data safe is NOT enough. Interpolating a SafeBuffer into
+  #      a plain string literal yields a PLAIN String, the safety is lost, and
+  #      every quote in the fragment escapes to an entity. It still PARSES (a
+  #      browser decodes entities in an attribute), so only the source reads
+  #      wrong. Concatenate, then mark the result.
+  #   2. The fragment is developer-authored JavaScript, never user input. That
+  #      is what makes html_safe correct here rather than a hole.
+  extra_fragment = extra_data.present? ? (",\n       " + extra_data).html_safe : "".html_safe
+%>
+<div x-data="{
+       get props() { var c = $store.<%= store %>.current(); return (c && c.props) || {}; },
+       wallets: [],
+       installs: [
+         { name: 'Phantom',  url: 'https://phantom.app/download' },
+         { name: 'Solflare', url: 'https://solflare.com/download' },
+         { name: 'Backpack', url: 'https://backpack.app/downloads' }
+       ],
+       connecting: false,
+       picking: '',
+       error: '',
+       init() {
+         if (typeof this.onInit === 'function') this.onInit();
+         this.refresh();
+         // Wallet Standard registration can land a tick after the module
+         // loads — re-read once so a just-registered wallet still appears.
+         var self = this;
+         setTimeout(function() { if (!self.connecting) self.refresh(); }, 300);
+       },
+       refresh() {
+         this.wallets = (window.walletProvider && window.walletProvider.available && window.walletProvider.available()) || [];
+       },
+       get isMobile() { return !!(window.walletProvider && window.walletProvider.isMobile && window.walletProvider.isMobile()); },
+       hasWallet(name) {
+         var n = ('' + name).toLowerCase();
+         return (this.wallets || []).some(function(w) { return w.name && w.name.toLowerCase() === n; });
+       },
+       allowed() {
+         return typeof this.canPick === 'function' ? !!this.canPick() : true;
+       },
+       // Resolve a known install-brand name to its sprite symbol suffix. The
+       // three install rows are always known brands, so this always resolves;
+       // an unknown name returns null and the use paints nothing (detected rows
+       // never use it — they keep the wallet's own Wallet-Standard icon).
+       brandIcon(name) {
+         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 solana_studio/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. 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 && self.canDeepLink && i.name === 'Phantom') return false;
+           return true;
+         });
+       },
+       // ONE Phantom row in every state: injected (Phantom's in-app browser)
+       // 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') && this.canDeepLink;
+       },
+       async pick(name) {
+         if (this.connecting) return;
+         if (!this.allowed()) return;
+         this.connecting = true; this.picking = name; this.error = '';
+         try {
+           var opts = { linkMode: this.props.linkMode, currentUserId: this.props.currentUserId };
+           if (typeof this.verifyArgs === 'function') Object.assign(opts, this.verifyArgs() || {});
+           var result = await window.<%= connect_fn %>(name, opts);
+           if (result && result.success) {
+             if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
+             if (typeof this.onConnected === 'function') {
+               this.onConnected(result);
+             } else {
+               window.location.href = this.props.returnUrl || result.redirect || '/';
+             }
+           } else {
+             this.error = (result && result.error) || 'Verification failed.';
+             this.connecting = false; this.picking = '';
+           }
+         } catch (e) {
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
+           this.error = msg; this.connecting = false; this.picking = '';
+         }
+       },
+       deepLink() {
+         // Same connecting guard as pick(). Without it a tap during an in-flight
+         // SIWS verify fires the deep link and walks the user out of the browser
+         // mid-signature. The app copies this was promoted from had the same
+         // hole; sharing the partial is the moment to close it for everyone.
+         if (this.connecting) return;
+         if (!this.allowed()) return;
+         if (typeof this.onDeepLink === 'function') { this.onDeepLink(); return; }
+         if (typeof startPhantomDeepLink === 'function') {
+           startPhantomDeepLink(this.props.linkMode || false, (this.props.linkMode && this.props.currentUserId) || null);
+         }
+       },
+       back() {
+         if (this.connecting) return;
+         if (typeof this.onBack === 'function') { this.onBack(); return; }
+         // Alpine.store(), not the $store magic: this runs as a METHOD BODY, and
+         // both consuming apps reach the store this way from inside one. The
+         // $store form stays where it is proven — the props getter and the
+         // Alpine attribute expressions in the markup below.
+         Alpine.store('<%= store %>').close();
+       }<%= extra_fragment %>
+     }"
+     class="relative">
+
+  <%# Wallet brand-icon sprite. Inline SVG symbol marks for the known install
+      brands, referenced by the rows below via use href="#se-wallet-…". MUST
+      live inside this picker's single root so the host's template x-if clones
+      it with the card — a sibling of the root is dropped, painting empty
+      icons. Replaces the per-app wallet PNGs. %>
+  <%= render "studio/modals/blocks/wallet_brand_sprite" %>
+
+  <div class="relative mb-4">
+    <h3 class="text-heading font-bold text-lg text-center pt-1"><%= title %></h3>
+    <button @click="$store.<%= store %>.close()"
+            class="absolute top-0 right-0 -mr-1 text-secondary hover:text-heading text-xl leading-none"
+            aria-label="Close">&times;</button>
+  </div>
+
+  <%# App slot — consent, legal copy, anything that must be answered before a
+      wallet is picked. Rendered from a NAMED LOCAL, never a block: see the
+      header. The app's own x-data members (and canPick) arrive through
+      extra_data, so the slot partial can bind straight to them. %>
+  <% if slot %>
+    <%= render slot, **slot_locals %>
+  <% end %>
+
+  <div class="space-y-2">
+    <%# Detected wallets — INSTALLED, click to connect %>
+    <template x-for="w in wallets" :key="w.name">
+      <button type="button" @click="pick(w.name)" :disabled="connecting"
+              class="w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left disabled:opacity-60 disabled:cursor-wait">
+        <%# Brand mark, three ways, and NONE of them an app-served file. A wallet
+            that registered through Wallet Standard supplies its own icon, and
+            that is the most accurate mark available, so it wins. Otherwise the
+            engine sprite by brand name. Otherwise a letter tile. The markup
+            promoted from the app fell back to /solana-mark.svg, a per-app asset
+            — exactly what blocks/_wallet_brand_sprite exists to end, and a 404
+            in any app that had not copied it. %>
+        <template x-if="w.icon">
+          <img :src="w.icon" alt="" class="w-9 h-9 rounded-lg shrink-0">
+        </template>
+        <template x-if="!w.icon && brandIcon(w.name)">
+          <span class="w-9 h-9 rounded-lg overflow-hidden flex items-center justify-center shrink-0">
+            <svg class="w-9 h-9 shrink-0" aria-hidden="true"><use :href="'#se-wallet-' + brandIcon(w.name)"></use></svg>
+          </span>
+        </template>
+        <template x-if="!w.icon && !brandIcon(w.name)">
+          <span class="w-9 h-9 rounded-lg bg-inset flex items-center justify-center text-sm font-bold text-heading shrink-0" x-text="w.name.slice(0,1)"></span>
+        </template>
+        <span class="font-semibold text-heading" x-text="w.name"></span>
+        <span class="ml-auto flex items-center gap-2">
+          <span x-show="picking === w.name" class="inline-flex items-center gap-1.5 text-xs text-secondary"><span class="spinner" aria-hidden="true"></span>Connecting&hellip;</span>
+          <span x-show="picking !== w.name" class="badge border-primary text-primary">Installed</span>
+          <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4 text-muted">
+            <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+          </svg>
+        </span>
+      </button>
+    </template>
+
+    <%# Mobile Phantom — the deep link IS the Phantom row here, so it sits in
+        Phantom's usual first position wearing the same brand icon and chevron
+        as the install rows, not as a second Phantom entry at the bottom of the
+        list. Phantom's universal link covers both states on its own: app
+        installed opens it, app absent falls through to Phantom's install page. %>
+    <button x-show="showPhantomDeepLink" x-cloak type="button" @click="deepLink()"
+            class="w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left">
+      <svg class="w-9 h-9 shrink-0" aria-hidden="true"><use href="#se-wallet-phantom"></use></svg>
+      <span class="font-semibold text-heading">Phantom</span>
+      <span class="ml-auto flex items-center gap-2">
+        <span class="text-xs text-muted uppercase tracking-wide">Open app</span>
+        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4 text-muted">
+          <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+        </svg>
+      </span>
+    </button>
+
+    <%# Featured wallets that aren't installed — open the install page %>
+    <template x-for="i in missingInstalls" :key="i.name">
+      <a :href="i.url" target="_blank" rel="noopener noreferrer"
+         class="w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition no-underline">
+        <svg class="w-9 h-9 shrink-0" aria-hidden="true"><use :href="'#se-wallet-' + brandIcon(i.name)"></use></svg>
+        <span class="font-semibold text-heading" x-text="i.name"></span>
+        <span class="ml-auto flex items-center gap-2">
+          <span class="text-xs text-muted uppercase tracking-wide">Install</span>
+          <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4 text-muted">
+            <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+          </svg>
+        </span>
+      </a>
+    </template>
+  </div>
+
+  <%# role="alert" — the engine requires every rendered error paragraph to carry
+      a live region (test/integration/modal_error_announcement_render_test.rb).
+      The app markup this was promoted from had none, so a connect failure was
+      shown and never ANNOUNCED. Adopting the primitive is what surfaced it: the
+      apps were never subject to this test. Same defect, same fix, as the
+      attestation error in studio/modals/shared/_age_attestation. %>
+  <template x-if="error">
+    <p role="alert" class="text-red-400 text-sm mt-3 text-center" x-text="error"></p>
+  </template>
+
+  <button type="button" @click="back()" :disabled="connecting"
+          class="mt-4 w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+    &larr; Back
+  </button>
+</div>

data/app/views/solana_studio/modals/_web3_step_up.html.erb

@@ -0,0 +1,292 @@
+<%#
+  Web3 step-up — the shared "your session cannot sign on-chain" card.
+
+  THE SITUATION IT NAMES: an account that holds a self-custody wallet signs in
+  with a WEB2 credential — a magic link, email, or Google. Both facts are
+  ordinary alone; together they mean the person is signed in but cannot sign
+  anything on-chain. `SessionContext` has modelled that intersection since it was
+  lifted into this engine (`web2?` AND `phantom_linked?`) and nothing acted on
+  it, so every web3 Studio app logged a wallet owner straight in with no web3
+  beat at all. This partial is the missing step; SessionContext stays the state.
+
+  Ported from turf-monster (2026-08-21), where it shipped first as the working
+  vertical. What is NOT shared — and deliberately stays in the host — is WHEN to
+  show it and what it costs to dismiss: the host's policy decides who sees the
+  card, and the host's gates keep their own teeth. This partial owns ONE step.
+
+  ADVISORY BY CONSTRUCTION. The card is dismissible and says so. A self-custody
+  wallet is the one credential a host cannot reset for a user, so a card that
+  could not be closed would lock a legitimate owner out of their own account
+  over a wallet they merely cannot reach right now. That is why the escape hatch
+  below is not optional decoration — and why enforcement must live in the host's
+  on-chain gates, never in this card.
+
+  Locals (all optional, defaults via local_assigns.fetch):
+    heading         — (default "Sign in with your wallet")
+    subtext         — the one-line why
+    help_url        — the escape hatch for a user who cannot reach their wallet
+                      (default "/help"). Set to nil to drop the line entirely.
+    help_label      — (default "Get help")
+    picker_modal_id — the host's brand picker, reached by "Use a different
+                      wallet" (default "wallet-connect"). The picker is expected
+                      to honour a `backTo` prop pointing back at this card.
+    modal_id        — this card's own id, passed to the picker as backTo
+                      (default "web3-step-up")
+    modal_store     — Alpine store name (default "modals"; the living style
+                      guide mounts a page-scoped host and passes "dsModals")
+    dismiss_event   — window event dispatched on dismissal (default
+                      "web3-step-up-dismissed"). The HOST decides what happens
+                      next — typically releasing an onboarding chain it held
+                      while this card had the screen. This partial never opens
+                      another modal itself.
+
+  PROPS (set by the opener, all optional — the host's policy produces them):
+    provider      — normalised brand key ('phantom' / 'solflare' / 'backpack'),
+                    or null when the account linked its wallet before the host
+                    started remembering the brand.
+    providerLabel — how that brand writes its own name, for the row.
+    walletHint    — the truncated address (4…4), so the user can confirm the
+                    card is asking for the wallet they think it is.
+
+  WITH a remembered provider this is ONE row. Without one it is the same card
+  with the picker as its primary action — the fallback is never a dead end.
+
+  CONTRACT WITH THE HOST'S JS. Signing calls `window.solanaConnectAndVerify(name,
+  { linkMode: false })`, the global every web3 Studio app already provides, and
+  hands a success to `window.handleSolanaVerifySuccess` when present. linkMode is
+  deliberately FALSE: the link path binds to the current user but does not grant
+  the on-chain session, which is the thing this card exists to obtain. One
+  inherited consequence, stated plainly: signing with a DIFFERENT wallet signs
+  you into that wallet's account, exactly as a standalone wallet button does. The
+  walletHint is shown precisely so that is a visible choice, not a surprise.
+
+  CRITICAL (Alpine): this partial is cloned from a <template x-if> by the modal
+  host, so it must have ONE root element, and the x-data below is a
+  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.
+%>
+<%
+  heading         = local_assigns.fetch(:heading, "Sign in with your wallet")
+  subtext         = local_assigns.fetch(:subtext,
+                      "This account is secured by a Solana wallet. You are signed in, but this " \
+                      "session can’t sign on-chain — so on-chain actions still need your wallet.")
+  help_url        = local_assigns.fetch(:help_url, "/help")
+  help_label      = local_assigns.fetch(:help_label, "Get help")
+  picker_modal_id = local_assigns.fetch(:picker_modal_id, "wallet-connect")
+  modal_id        = local_assigns.fetch(:modal_id, "web3-step-up")
+  modal_store     = local_assigns.fetch(:modal_store, "modals")
+  dismiss_event   = local_assigns.fetch(:dismiss_event, "web3-step-up-dismissed")
+%>
+<div x-data="{
+       get props() { var c = $store.<%= modal_store %>.current(); return (c && c.props) || {}; },
+       connecting: false,
+       error: '',
+       // Set when the remembered wallet turns out not to be reachable in THIS
+       // browser (a different machine, the extension removed). It flips the card
+       // to the picker rather than leaving the user pressing a button that
+       // cannot work.
+       providerMissing: false,
+       // Which wallets this document can actually see. Read on a poll, NOT once
+       // at mount: wallet provider registration fills in asynchronously, and
+       // this card auto-opens on the render right after auth — the worst
+       // possible moment. A single early read is a coin flip that would badge an
+       // installed wallet as missing.
+       wallets: [],
+       _poll: null,
+       _onRegister: null,
+       get provider() { return this.props.provider || null; },
+       get providerLabel() { return this.props.providerLabel || null; },
+       get walletHint() { return this.props.walletHint || null; },
+       // One-click only while we remember a brand AND it is still reachable.
+       get canOneClick() { return !!this.provider && !this.providerMissing; },
+       // Does the remembered brand answer in THIS document right now? Drives the
+       // Installed badge, the same one the connect picker shows, so a detected
+       // wallet reads identically in both places.
+       get detected() {
+         var name = ('' + (this.provider || '')).toLowerCase();
+         if (!name) return false;
+         return (this.wallets || []).some(function(w) { return w.name && w.name.toLowerCase() === name; });
+       },
+       init() {
+         var self = this;
+         this.refresh();
+         this._onRegister = function() { if (!self.connecting) self.refresh(); };
+         window.addEventListener('wallet-standard:register-wallet', this._onRegister);
+         this._poll = setInterval(function() {
+           if (self.connecting) return;
+           self.refresh();
+           if (self.wallets.length > 0) { clearInterval(self._poll); self._poll = null; }
+         }, 1000);
+       },
+       destroy() {
+         if (this._poll) clearInterval(this._poll);
+         if (this._onRegister) window.removeEventListener('wallet-standard:register-wallet', this._onRegister);
+       },
+       refresh() {
+         this.wallets = (window.walletProvider && window.walletProvider.available && window.walletProvider.available()) || [];
+       },
+       reachable(name) {
+         if (!window.walletProvider || !window.walletProvider.get) return false;
+         return !!window.walletProvider.get(name);
+       },
+       async signIn() {
+         if (this.connecting) return;
+         var name = this.provider;
+         if (!name) return this.openPicker();
+         if (!this.reachable(name)) {
+           this.providerMissing = true;
+           this.error = 'We could not reach your ' + (this.providerLabel || 'wallet') + ' in this browser.';
+           return;
+         }
+         if (typeof window.solanaConnectAndVerify !== 'function') {
+           this.error = 'Wallet sign-in is unavailable on this page.';
+           return;
+         }
+         this.connecting = true; this.error = '';
+         try {
+           var result = await window.solanaConnectAndVerify(name, { linkMode: false });
+           if (result && result.success) {
+             if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
+             // Reload rather than follow a redirect: the user was already
+             // somewhere, and the only thing that changed is that this session
+             // can now sign. Sending them to a post-login landing would move
+             // them off the page they were reading.
+             window.location.reload();
+             return;
+           }
+           this.error = (result && result.error) || 'Verification failed.';
+         } catch (e) {
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
+           this.error = msg;
+         }
+         this.connecting = false;
+       },
+       // Hand off to the host's brand picker. swap() rather than open() so the
+       // picker's back arrow returns HERE instead of stranding the user.
+       openPicker() {
+         if (this.connecting) return;
+         $store.<%= modal_store %>.swap('<%= picker_modal_id %>',
+           { backTo: '<%= modal_id %>', stepUpProps: this.props, returnUrl: window.location.href });
+       },
+       // Dismiss. Dispatched so the HOST knows this card is done and can release
+       // whatever it was holding — this partial never opens another modal.
+       dismiss() {
+         if (this.connecting) return;
+         window.dispatchEvent(new CustomEvent('<%= dismiss_event %>'));
+         $store.<%= modal_store %>.close();
+       }
+     }"
+     class="relative">
+
+  <%# Brand sprite — MUST live inside this card's single root so the host's
+      <template x-if> clones it along with the card. A sibling of the root is
+      dropped and the icon paints empty. %>
+  <%= render "studio/modals/blocks/wallet_brand_sprite" %>
+
+  <div class="relative mb-1">
+    <button @click="dismiss()" :disabled="connecting"
+            class="absolute top-0 right-0 -mr-1 text-secondary hover:text-heading text-xl leading-none disabled:opacity-50"
+            aria-label="Close">&times;</button>
+  </div>
+
+  <%= render "studio/modals/blocks/card_header", icon_emoji: "🔐", title: heading do %>
+    <p class="text-sm text-body"><%= subtext %></p>
+  <% end %>
+
+  <%# PRIMARY — THE STANDARD WEB3 AUTH BUTTON: a wallet row, not a filled CTA.
+      Same shape the connect picker uses — brand mark, the wallet's own name, an
+      Installed badge, chevron — so a wallet reads identically everywhere it is
+      offered and this card does not invent a third look for one action.
+
+      It carries `pulse-cta` (engine-motion) because it is the ONE target on the
+      card and the whole point of the card is that the user should press it. %>
+  <template x-if="canOneClick">
+    <div>
+      <button type="button" @click="signIn()" :disabled="connecting"
+              style="--pulse-cta-color: var(--color-primary); --pulse-cta-strength: 0.4; --pulse-cta-scale: 1.02"
+              class="pulse-cta w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left disabled:opacity-60 disabled:cursor-wait">
+        <span class="w-9 h-9 rounded-lg overflow-hidden flex items-center justify-center shrink-0">
+          <svg class="w-9 h-9" aria-hidden="true"><use :href="'#se-wallet-' + provider"></use></svg>
+        </span>
+        <span class="font-semibold text-heading" x-text="providerLabel"></span>
+        <span class="ml-auto flex items-center gap-2">
+          <span x-show="connecting" class="inline-flex items-center gap-1.5 text-xs text-secondary"><span class="spinner" aria-hidden="true"></span>Connecting&hellip;</span>
+          <span x-show="!connecting && detected" class="badge border-primary text-primary">Installed</span>
+          <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4 text-muted">
+            <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+          </svg>
+        </span>
+      </button>
+      <%# One line on what pressing it DOES. A signature prompt is alarming
+          without it, and "no funds move" is the difference between clicking and
+          bailing. The address rides here so the user can confirm the card is
+          asking for the wallet they think it is. %>
+      <p class="text-[11px] text-muted mt-1.5 px-1">
+        Signing proves the wallet is yours &mdash; it does not move any funds.
+        <template x-if="walletHint">
+          <span>Wallet <span class="font-mono text-secondary" x-text="walletHint"></span></span>
+        </template>
+      </p>
+    </div>
+  </template>
+
+  <%# No remembered brand — the same row shape with no mark to show, so the two
+      halves of this card look like one card. %>
+  <template x-if="!canOneClick">
+    <button type="button" @click="openPicker()" :disabled="connecting"
+            style="--pulse-cta-color: var(--color-primary); --pulse-cta-strength: 0.4; --pulse-cta-scale: 1.02"
+            class="pulse-cta w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left disabled:opacity-60">
+      <%# A neutral wallet mark, NOT an emoji. This tile sits inches from a real
+          brand mark, so a platform emoji (the first pass used U+1F45B PURSE)
+          reads as a pink handbag next to Phantom and is the one thing on the
+          card that belongs to no design system. Stroked in the same idiom as
+          the chevron beside it, on theme tokens.
+
+          A billfold: body plus clasp, and NO band across the top. The first
+          drawing had one and it read as a credit-card magstripe at 20px — the
+          wrong object on a card whose whole subject is a wallet. %>
+      <span class="w-9 h-9 rounded-lg bg-inset flex items-center justify-center shrink-0" aria-hidden="true">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" class="w-5 h-5 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="font-semibold text-heading">Connect your wallet</span>
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="ml-auto w-4 h-4 text-muted">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+      </svg>
+    </button>
+  </template>
+
+  <template x-if="error">
+    <p role="alert" class="text-red-400 text-sm mt-3 text-center" x-text="error"></p>
+  </template>
+
+  <%# SECONDARY — always reachable, so a user whose remembered wallet is the
+      wrong one is never cornered by our memory of it. %>
+  <template x-if="canOneClick">
+    <button type="button" @click="openPicker()" :disabled="connecting"
+            class="mt-3 block w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Use a different wallet
+    </button>
+  </template>
+
+  <div class="mt-4 pt-3 border-t border-strong">
+    <button type="button" @click="dismiss()" :disabled="connecting"
+            class="block w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Not now
+    </button>
+    <%# THE ESCAPE HATCH. A self-custody wallet is the one credential a host
+        cannot reset for the user, so the card must not end without a way to
+        reach a human. Droppable only by passing help_url: nil, which is a
+        deliberate act at the callsite rather than an omission. %>
+    <% if help_url.present? %>
+      <p class="mt-2 text-center text-[11px] text-muted">
+        Can&rsquo;t access your wallet?
+        <a href="<%= help_url %>" class="underline hover:text-secondary"><%= help_label %></a>
+      </p>
+    <% end %>
+  </div>
+</div>

data/lib/solana_studio/version.rb

@@ -16,5 +16,5 @@ module SolanaStudio
   # through the normal cycle. Splitting the version out is the same shape
   # studio-engine already uses (lib/studio/version.rb) and hands each file back
   # to its real owner: this one to the release, the gemspec to the PR.
-  VERSION = "0.5.2"
+  VERSION = "0.5.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.4
 platform: ruby
 authors:
 - Alex McRitchie
@@ -38,8 +38,12 @@ files:
 - LICENSE
 - README.md
 - app/assets/javascripts/solana_studio/network_guard.js
+- app/views/solana_studio/_deeplink_assets.html.erb
+- app/views/solana_studio/_phantom_deeplink.html.erb
 - app/views/solana_studio/auth/_wallet_credential.html.erb
 - app/views/solana_studio/modals/_network_mismatch.html.erb
+- app/views/solana_studio/modals/_wallet_connect.html.erb
+- app/views/solana_studio/modals/_web3_step_up.html.erb
 - lib/solana-studio.rb
 - lib/solana/auth_verifier.rb
 - lib/solana/borsh.rb