solana-studio 0.6.1 → 0.8.0

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

@@ -76,6 +76,43 @@
                          browser, or to do something else entirely. The default
                          calls window.startPhantomDeepLink(linkMode, userId).
     onBack()             the Back button; DEFAULT closes the modal
+
+  CONTRACT WITH THE HOST'S JS. This gem ships no routes at all, and the JavaScript
+  it does ship provides no global in this list: solana_studio/network_guard.js
+  plus the redirect-transport primitives (wallet_transport, redirect_provider,
+  wallet_journal, wallet_ops). So every global below is the HOST'S to provide. Each is reached behind a `typeof` guard, and an absent
+  one degrades this card rather than breaking it — which is the whole reason the
+  list is written down here instead of being rediscovered per consumer.
+
+    window[connect_fn]              REQUIRED. Connect + verify. Default
+                                    window.solanaConnectAndVerify.
+    window.walletProvider           REQUIRED for the rows: .available() lists the
+                                    detected wallets this card paints.
+    parseSolanaError(msg)           optional. Maps a wallet string to a sentence
+                                    a user can act on; absent means the wallet's
+                                    own words are shown unmapped.
+    window.handleSolanaVerifySuccess(result)
+                                    optional. Post-verify hook on the happy path.
+    window.startPhantomDeepLink(linkMode, userId)
+                                    optional. The mobile deep link; absent hides
+                                    the Phantom deep-link row entirely.
+    window.reportWalletFailure(stage, provider, raw, mapped)
+                                    optional. Fire-and-forget observation, called
+                                    ONCE per caught rejection with stage
+                                    'wallet_connect'. `raw` is what the wallet
+                                    said and `mapped` is what the user was shown;
+                                    a host that records only one half cannot
+                                    diagnose a MIS-mapping, which is the failure
+                                    this exists for. Return value is ignored and
+                                    a throw is swallowed — see the call site.
+                                    Absent means this surface is DARK: the user
+                                    is served correctly and nothing is recorded
+                                    anywhere. Reference implementation and the
+                                    receiving endpoint (both host-owned, because
+                                    they need an ErrorLog this gem cannot assume)
+                                    live in turf-monster:
+                                    app/javascript/solana_errors.js and
+                                    POST /auth/solana/report_failure.
 %>
 <%
   store      = local_assigns.fetch(:store, "modals")
@@ -158,9 +195,25 @@
        // 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.
+       // iOS or not, and removing it leaves the user nothing.
+       //
+       // SOLFLARE AND BACKPACK STILL GET INSTALL ROWS HERE, and the reason is NOT
+       // the one this comment used to give. It claimed there was no deep link for
+       // them, which is FALSE and was costing those users: verified against both
+       // vendors' docs 2026-09-07, Solflare (solflare.com/ul/v1) and Backpack
+       // (backpack.app/ul/v1) each ship a full deeplink protocol, forked from
+       // Phantom's and sharing its encryption scheme and parameter names. So on a
+       // phone this row hands them a DESKTOP EXTENSION download page — a silent
+       // dead end, with no error, for a wallet that could have worked.
+       //
+       // What is actually missing is on OUR side: canDeepLink below asks whether
+       // ONE Phantom-specific global exists, so no other wallet can answer yes.
+       // solana_studio/redirect_provider.js now knows all three, and rewiring
+       // these three getters to ask it is the fix. Deliberately NOT done in the
+       // change that added that file: these getters are pinned by exact-source
+       // assertions in test/views/wallet_connect_picker_test.rb, and rewriting
+       // those belongs with the behaviour change rather than riding along with
+       // new primitives.
        get missingInstalls() {
          var self = this;
          return this.installs.filter(function(i) {
@@ -195,9 +248,46 @@
              this.connecting = false; this.picking = '';
            }
          } catch (e) {
-           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           // BOTH HALVES OR NEITHER. raw is what the WALLET said, captured
+           // before the mapper runs; msg is what the user reads. A mis-mapping
+           // is invisible in the mapped half alone, and that is not theoretical
+           // -- a correct mapper meeting a string it had never seen is how an
+           // empty Phantom came to be answered with balance advice seven times
+           // in one production session on 2026-09-06.
+           var raw = (e && e.message) || '';
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : (raw || 'Connection failed');
            if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
            this.error = msg; this.connecting = false; this.picking = '';
+           // ── OBSERVATION, AFTER THE USER HAS BEEN SERVED ──────────────────
+           //
+           // Deliberately the LAST statement in this block, and the three lines
+           // above are deliberately not in it: reporting may not delay, block or
+           // alter the line the user has just been handed.
+           //
+           // HOST-SUPPLIED, like every other global this partial reaches for
+           // (see CONTRACT WITH THE HOST'S JS in the header). The endpoint it
+           // posts to writes an ErrorLog, which is host-owned -- this gem ships
+           // no routes at all -- so a consumer that has not built one simply
+           // does not define this, the guard is false, and the card behaves
+           // exactly as it did before. Silence, never a 404.
+           //
+           // ALREADY REPORTED UPSTREAM? The connect helper substitutes its own
+           // sentence for an unusable wallet and reports the pair from in there,
+           // where the wallet's words still exist. Reporting again from out here
+           // would add a second row whose raw and mapped are BOTH our sentence
+           // -- the useless row, and the one an operator meets first.
+           //
+           // THE try/catch IS THIS GEM'S OWN LAYER, and it is not redundant with
+           // the reporter's. We do not own the reporter -- a host does, and a
+           // host's implementation may throw. A throw here escapes an async Alpine
+           // handler silently, which is the failure mode this whole feature
+           // exists to remove -- so the observation cannot be allowed to become
+           // the incident. Four values, and only these four: opts,
+           // verifyArgs() and this.props are all in scope and carry
+           // currentUserId, none of which belongs in an error log.
+           if (typeof window.reportWalletFailure === 'function' && !(e && e.walletFailureReported)) {
+             try { window.reportWalletFailure('wallet_connect', name, raw, msg); } catch (_e) {}
+           }
          }
        },
        deepLink() {

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

@@ -64,6 +64,19 @@
   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.
 
+  Two more host globals, both OPTIONAL and both reached behind a `typeof` guard:
+  `parseSolanaError(msg)` maps a wallet string to a sentence a user can act on,
+  and `window.reportWalletFailure(stage, provider, raw, mapped)` records a caught
+  rejection with stage 'web3_step_up'. The reporter is fire-and-forget — its
+  return value is ignored and a throw is swallowed — and it is called ONCE per
+  rejection, skipping any error solanaConnectAndVerify already reported upstream.
+  Send BOTH message halves: `raw` is what the wallet said, `mapped` is what the
+  user read, and only the pair makes a MIS-mapping diagnosable. A host that
+  defines neither gets this card exactly as it behaved before, with the failure
+  recorded nowhere. The reporter and its endpoint stay host-owned because they
+  need an ErrorLog this gem cannot assume — reference implementation in
+  turf-monster: app/javascript/solana_errors.js, POST /auth/solana/report_failure.
+
   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
@@ -167,9 +180,38 @@
            }
            this.error = (result && result.error) || 'Verification failed.';
          } catch (e) {
-           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           // BOTH HALVES OR NEITHER. raw is what the WALLET said, captured
+           // before the mapper runs; msg is what the user reads. A mis-mapping
+           // is invisible in the mapped half alone -- a correct mapper meeting a
+           // string it had never seen is how an empty Phantom came to be
+           // answered with balance advice seven times in one production session
+           // on 2026-09-06, which is the incident this reporting exists for.
+           var raw = (e && e.message) || '';
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : (raw || 'Connection failed');
            if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
            this.error = msg;
+           // Observation, LAST and after the user has been served. Host-supplied
+           // like every other global here (see CONTRACT WITH THE HOST'S JS in
+           // the header): the endpoint it posts to writes an ErrorLog, which is
+           // host-owned -- this gem ships no routes -- so a consumer that built
+           // none simply leaves this undefined and the card behaves exactly as
+           // before. The walletFailureReported tag means solanaConnectAndVerify
+           // already reported this one from where the wallet's words still
+           // existed; reporting again would file a second row carrying OUR
+           // sentence in both halves, and that is the row an operator meets
+           // first. Sibling call site in modals/_wallet_connect carries the long
+           // form of both arguments.
+           //
+           // THE try/catch IS LOAD-BEARING HERE IN A WAY IT IS NOT THERE.
+           // this.connecting = false sits OUTSIDE this catch block, on the
+           // line below. A host reporter that throws would skip it, leaving the
+           // sign-in button disabled forever with an error the user cannot
+           // retry -- and Alpine swallows a throw out of an async handler, so
+           // nothing anywhere would say so. An observer that can wedge the card
+           // is a worse bug than the darkness it was added to fix.
+           if (typeof window.reportWalletFailure === 'function' && !(e && e.walletFailureReported)) {
+             try { window.reportWalletFailure('web3_step_up', name, raw, msg); } catch (_e) {}
+           }
          }
          this.connecting = false;
        },
@@ -281,7 +323,7 @@
       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
+      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>

data/lib/solana_studio/engine.rb

@@ -30,6 +30,10 @@ module SolanaStudio
 
       app.config.assets.precompile += %w[
         solana_studio/network_guard.js
+        solana_studio/wallet_transport.js
+        solana_studio/redirect_provider.js
+        solana_studio/wallet_journal.js
+        solana_studio/wallet_ops.js
       ]
     end
   end

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.6.1"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -38,6 +38,10 @@ files:
 - LICENSE
 - README.md
 - app/assets/javascripts/solana_studio/network_guard.js
+- app/assets/javascripts/solana_studio/redirect_provider.js
+- app/assets/javascripts/solana_studio/wallet_journal.js
+- app/assets/javascripts/solana_studio/wallet_ops.js
+- app/assets/javascripts/solana_studio/wallet_transport.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