solana-studio 0.6.1 → 0.8.0

data/app/assets/javascripts/solana_studio/wallet_ops.js

@@ -0,0 +1,260 @@
+// SolanaStudio.walletOps — one call site, every platform.
+//
+// THE PROBLEM THIS SOLVES, and it is not "mobile support". It is that the SAME
+// piece of product logic — enter a contest, rename a user, export a wallet — has
+// to run over two transports with incompatible shapes: one where `await` works,
+// and one where the page is destroyed mid-operation. Written per-call-site, that
+// becomes two implementations of every flow, and the mobile one silently rots
+// because nobody exercises it on a laptop.
+//
+// So a flow is declared ONCE, as an intent:
+//
+//   walletOps.define('contest_entry', {
+//     prepare:  function (ctx) { ... return { transaction: <base58>, ...state }; },
+//     complete: function (ctx, result, state) { ... }
+//   });
+//
+//   walletOps.run('contest_entry', { contestId: 12 }, { provider: ... });
+//
+// THE ONE RULE A CALLER MUST FOLLOW: handlers are registered BY NAME at page
+// load, not passed as closures. A closure is precisely what cannot survive the
+// redirect — the page that held it no longer exists when the wallet answers. The
+// name is the only thing that can be written down and looked up again. Every
+// other constraint in this file follows from that one.
+//
+// AND THE CORRESPONDING RULE ON STATE: whatever `prepare` returns must be
+// JSON-serialisable, because on the redirect transport it is literally
+// serialised. This is why the entry flow's server-side prepared-transaction slug
+// matters so much — a slug survives the trip; a Transaction object does not.
+//
+// WHAT THIS FILE DOES NOT DO: it does not broadcast. Signing and sending are
+// different responsibilities with different failure modes, and the wallet that
+// broadcasts differs per vendor (Phantom deprecated its send-side deeplink, so
+// the app sends; Solflare and Backpack send for you). `complete` is told which
+// happened and owns the RPC, exactly as the existing flows already do.
+(function (W) {
+  'use strict';
+
+  W.SolanaStudio = W.SolanaStudio || {};
+
+  var handlers = {};
+
+  function studio() { return W.SolanaStudio; }
+
+  function requireHandler(name) {
+    var h = handlers[name];
+    if (!h) {
+      // NAMED, because the most likely cause is a real and specific bug: a
+      // callback page that did not load the script defining this intent. The
+      // resume then fails here, far from the define() that never ran, and a
+      // generic "not found" sends the reader hunting the journal instead.
+      throw new Error(
+        'No wallet intent registered as "' + name + '" — the page handling this ' +
+        'callback must load the same script that defined it'
+      );
+    }
+    return h;
+  }
+
+  // Default navigation, injectable so the whole surface stays testable in node.
+  function defaultNavigate(url) {
+    W.location.href = url;
+  }
+
+  // --- inline transport ----------------------------------------------------
+  //
+  // The path that already worked: the provider is injected, promises resolve,
+  // nothing is written down. Kept deliberately close to what the existing call
+  // sites do, so adopting walletOps is not also a rewrite of the desktop flow.
+  function runInline(name, ctx, opts) {
+    var handler = requireHandler(name);
+    var provider = opts.provider;
+
+    return Promise.resolve(handler.prepare(ctx)).then(function (prepared) {
+      return Promise.resolve(provider.connect()).then(function () {
+        return provider.signTransaction(prepared.transaction);
+      }).then(function (signed) {
+        return handler.complete(ctx, {
+          signedTransaction: signed,
+          signature: null,
+          sendStrategy: 'app-broadcasts'
+        }, prepared);
+      });
+    });
+  }
+
+  // --- redirect transport --------------------------------------------------
+  //
+  // Two or three hops, each ending in the page's destruction. `run` gets as far
+  // as the first navigation; `resume` picks up whatever the callback carries and
+  // either navigates again or finishes.
+  function runRedirect(name, ctx, opts) {
+    var handler = requireHandler(name);
+    var provider = opts.provider;
+    var journalStore = studio().walletJournal;
+    var navigate = opts.navigate || defaultNavigate;
+
+    // REFUSE EARLY rather than strand the user in their wallet app. Without a
+    // writable store there is nothing to resume from, and the trip would end in
+    // a callback page that finds no pending request and can only apologise.
+    if (!journalStore.writable()) {
+      return Promise.reject(new Error(
+        'This browser cannot store a pending wallet request — open this page in ' +
+        'your wallet app instead'
+      ));
+    }
+
+    return Promise.resolve(handler.prepare(ctx)).then(function (prepared) {
+      var intent = { op: name, ctx: ctx, state: prepared };
+
+      // Already connected? Go straight to signing. Otherwise connect first and
+      // carry the intent through — sessions do not expire on any of the three
+      // wallets, so this branch is taken once per user, not once per action.
+      var existing = opts.session || null;
+      var begun = existing
+        ? beginSigning(provider, intent, existing, opts)
+        : provider.beginConnect({
+            appUrl: opts.appUrl,
+            redirectLink: opts.redirectLink,
+            cluster: opts.cluster,
+            intent: intent
+          });
+
+      if (!journalStore.save(begun.journal)) {
+        return Promise.reject(new Error('Could not record the pending wallet request'));
+      }
+      navigate(begun.url);
+      // Nothing resolves here in a real browser — the page is gone. The value is
+      // for tests and for a caller that wants to know a trip started.
+      return { suspended: true, url: begun.url };
+    });
+  }
+
+  function beginSigning(provider, intent, session, opts) {
+    var connected = {
+      v: provider.JOURNAL_VERSION,
+      step: 'connected'
+    };
+    // A caller supplying its own session hands us the journal fields the connect
+    // hop would have produced. Kept explicit rather than reconstructed, because
+    // guessing them is how a shared secret ends up derived from the wrong key.
+    for (var k in session) {
+      if (Object.prototype.hasOwnProperty.call(session, k)) connected[k] = session[k];
+    }
+    connected.intent = intent;
+    return signingHop(provider, connected, opts);
+  }
+
+  // Which signing method this wallet gets is a CAPABILITY QUESTION, not a
+  // preference: Phantom's send-side deeplink is deprecated, so it signs and the
+  // app broadcasts. Asking the provider keeps that fact in the profile table
+  // where it is asserted, rather than branching on a wallet name here.
+  function signingHop(provider, journal, opts) {
+    var payload = {
+      journal: journal,
+      transaction: journal.intent.state.transaction,
+      redirectLink: opts.redirectLink,
+      intent: journal.intent
+    };
+    return provider.can('signAndSendTransaction')
+      ? provider.beginSignAndSendTransaction(payload)
+      : provider.beginSignTransaction(payload);
+  }
+
+  // Called by the callback page. Reads the pending journal, advances one step,
+  // and either navigates again or hands back the finished result.
+  //
+  // `take()` rather than `peek()` — reading clears, so a reloaded or
+  // double-fired callback cannot advance the same step twice.
+  function resume(params, opts) {
+    opts = opts || {};
+    var journalStore = studio().walletJournal;
+    var navigate = opts.navigate || defaultNavigate;
+
+    var journal = journalStore.take();
+    if (!journal) return Promise.resolve({ pending: false });
+
+    var provider = opts.provider ||
+      studio().redirectProvider.forWallet(journal.wallet);
+    if (!provider) {
+      return Promise.reject(new Error('No provider for wallet "' + journal.wallet + '"'));
+    }
+
+    try {
+      if (journal.step === 'connect') {
+        var connected = provider.completeConnect(params, journal);
+        var intent = connected.journal.intent;
+
+        // Connect with no intent behind it is a plain sign-in: hand the caller
+        // the account and stop. Connect CARRYING an intent immediately takes the
+        // next hop, which is what makes a transaction on a cold session two
+        // navigations rather than two user-initiated attempts.
+        if (!intent) {
+          return Promise.resolve({ pending: true, done: true, connect: connected });
+        }
+
+        var next = signingHop(provider, connected.journal, {
+          redirectLink: opts.redirectLink || journal.redirectLink
+        });
+        if (!journalStore.save(next.journal)) {
+          return Promise.reject(new Error('Could not record the pending wallet request'));
+        }
+        navigate(next.url);
+        return Promise.resolve({ pending: true, suspended: true, url: next.url });
+      }
+
+      if (journal.step === 'signTransaction' || journal.step === 'signAndSendTransaction') {
+        // HANDLER FIRST, BEFORE ANY DECRYPTION. If the intent is not registered
+        // on this page, no amount of successful decryption helps — and a crypto
+        // error surfacing here would send the reader after the shared secret
+        // when the real fault is a script the callback page did not load.
+        var handler = requireHandler(journal.intent && journal.intent.op);
+
+        var wallet = journal.step === 'signAndSendTransaction';
+        var out = wallet
+          ? provider.completeSignAndSendTransaction(params, journal)
+          : provider.completeSignTransaction(params, journal);
+        return Promise.resolve(handler.complete(journal.intent.ctx, {
+          signature: out.signature || null,
+          signedTransaction: out.transaction || null,
+          sendStrategy: wallet ? 'wallet-broadcasts' : 'app-broadcasts'
+        }, journal.intent.state)).then(function (value) {
+          return { pending: true, done: true, value: value };
+        });
+      }
+
+      return Promise.reject(new Error('Unknown wallet journal step: ' + journal.step));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  }
+
+  W.SolanaStudio.walletOps = {
+    define: function (name, handler) {
+      if (!handler || typeof handler.prepare !== 'function' || typeof handler.complete !== 'function') {
+        throw new Error('walletOps.define("' + name + '") needs both prepare and complete');
+      }
+      handlers[name] = handler;
+    },
+
+    defined: function (name) { return !!handlers[name]; },
+    names: function () { return Object.keys(handlers); },
+
+    // Test seam only. Production pages define once at load and never clear.
+    reset: function () { handlers = {}; },
+
+    // The single call site. Chooses the transport from the provider it is given,
+    // so a view never asks what platform it is on.
+    run: function (name, ctx, opts) {
+      opts = opts || {};
+      if (!opts.provider) {
+        return Promise.reject(new Error('walletOps.run needs a provider'));
+      }
+      return opts.provider.transport === 'redirect'
+        ? runRedirect(name, ctx, opts)
+        : runInline(name, ctx, opts);
+    },
+
+    resume: resume
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

data/app/assets/javascripts/solana_studio/wallet_transport.js

@@ -0,0 +1,367 @@
+// SolanaStudio.walletTransport — the REDIRECT transport's shared core.
+//
+// WHY THIS FILE EXISTS. `walletProvider` in the consuming apps models exactly one
+// way of reaching a wallet: an object injected into the page. That is true of a
+// desktop extension and of a wallet's own in-app browser, and it is false of
+// every ordinary mobile browser. On iOS Safari and Android Chrome there is no
+// injected provider, `detect()` returns null, and every call site that reaches
+// for `provider.connect()` throws a null-dereference into a user-facing modal.
+//
+// The second transport is a REDIRECT: the page hands off to the wallet app by
+// URL and the answer comes back on a callback URL, with the original page
+// destroyed in between. A promise cannot survive that, which is the single fact
+// this whole design is shaped around.
+//
+// WHAT THIS FILE IS AND IS NOT. It is the wallet-agnostic HALF: the codec, the
+// per-wallet profile table, and the URL builders. It performs no navigation,
+// touches no localStorage, and knows nothing about intents or resume — those
+// belong to the journal (studio-engine) and the intent registry, which build ON
+// this. Keeping them apart is what lets this half be exercised in node without a
+// browser, which is how its per-wallet differences are actually pinned.
+//
+// THE PROTOCOLS ARE ~95% IDENTICAL, WHICH IS THE WHOLE OPPORTUNITY. Solflare and
+// Backpack both forked Phantom's deeplink spec: same x25519 + nacl.box, same
+// 24-byte nonce, base58 everywhere, byte-identical error tables, identical
+// payload JSON keys, identical response keys. Solflare's own docs even link
+// Phantom's blocklist repo. So the codec below is genuinely shared and only a
+// small profile varies. Verified against all three vendors' live docs
+// 2026-09-07; every divergence is recorded in PROFILES with its reason.
+//
+// ONE DEPENDENCY, AND IT IS GUARDED: window.nacl (tweetnacl). Base58 is INLINE
+// and self-contained on purpose — a previous extraction left B58_ALPHABET behind
+// at module scope where a classic script could not reach it, and every mobile
+// sign-in threw "B58_ALPHABET is not defined" on the first keypair encode. That
+// was invisible to eleven passing view tests and to a browser spec that checked
+// `typeof` without ever CALLING the function. Nothing here reads a free
+// variable it does not declare.
+(function (W) {
+  'use strict';
+
+  W.SolanaStudio = W.SolanaStudio || {};
+
+  var B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+  // CORRECTED DURING EXTRACTION, and deliberately NOT a faithful copy. Both
+  // shipped encoders this was lifted from (turf-monster's deep link and
+  // studio-engine's callback) seed `digits` with [0] and then convert EVERY
+  // byte, including the leading zeros they also emit as '1' separately. For any
+  // input that is entirely zero bytes that yields one character too many —
+  // encode([0]) returns '11', which decodes back to [0, 0] — and encode([])
+  // returns '1' rather than the empty string.
+  //
+  // NOT A LIVE BUG IN EITHER CONSUMER, and worth saying so plainly rather than
+  // overstating the find: the only things they encode are 32-byte x25519 keys
+  // and 24-byte nonces, and an all-zero one of either is not reachable. It is
+  // still wrong, and a shared core that other code will build on should not
+  // carry a round-trip that fails on its simplest input.
+  //
+  // The fix is to count the leading zero bytes, convert only what remains, and
+  // let a zero value contribute no digits at all.
+  function encodeBase58(bytes) {
+    var zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+
+    var digits = [];
+    for (var i = zeros; 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 k = 0; k < zeros; k++) str += '1';
+    // The most significant digit of a non-zero number is never 0, so the '1'
+    // characters above stay unambiguously the zero-byte prefix on decode.
+    for (var m = digits.length - 1; m >= 0; m--) str += B58_ALPHABET[digits[m]];
+    return str;
+  }
+
+  function decodeBase58(str) {
+    var bytes = [];
+    for (var i = 0; i < str.length; i++) {
+      var idx = B58_ALPHABET.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 k = 0; k < str.length && str[k] === '1'; k++) bytes.push(0);
+    return new Uint8Array(bytes.reverse());
+  }
+
+  // --- Per-wallet profiles -------------------------------------------------
+  //
+  // Everything that is NOT shared. Each field below is a place one vendor
+  // diverged, and each carries why — because the next reader's instinct will be
+  // "these are all the same, collapse them", and four of them are traps.
+  var PROFILES = {
+    phantom: {
+      name: 'Phantom',
+      host: 'https://phantom.app',
+      // Phantom's scheme has NO /ul/ segment. Solflare's does. This is the one
+      // place a "just swap the host" adapter breaks.
+      scheme: 'phantom://v1/',
+      connectKeys: ['phantom_encryption_public_key'],
+      // browse carries NO version segment on Phantom — documented that way, and
+      // different from its own provider methods.
+      browsePath: '/ul/browse/',
+      clusters: ['mainnet-beta', 'testnet', 'devnet'],
+      // DEPRECATED BY PHANTOM: "The signAndSendTransaction deeplink is
+      // deprecated. Use signAllTransactions or signTransaction instead." So on
+      // Phantom the APP still broadcasts — sendRawTransaction + a confirmation
+      // poll stay. This is the opposite of the other two, and it applies to the
+      // wallet most users hold, so it is not an edge case.
+      send: 'app-broadcasts',
+      methods: {
+        connect: true, disconnect: true, signMessage: true,
+        signTransaction: true, signAllTransactions: true,
+        signAndSendTransaction: false, browse: true, signIn: false
+      }
+    },
+
+    solflare: {
+      name: 'Solflare',
+      host: 'https://solflare.com',
+      // KEEPS /ul/ — unlike Phantom. Evidence is Solflare's own sample app; the
+      // scheme form is not documented in prose.
+      scheme: 'solflare://ul/v1/',
+      connectKeys: ['solflare_encryption_public_key'],
+      browsePath: '/ul/v1/browse/',
+      clusters: ['mainnet-beta', 'testnet', 'devnet'],
+      send: 'wallet-broadcasts',
+      methods: {
+        connect: true, disconnect: true, signMessage: true,
+        signTransaction: true, signAllTransactions: true,
+        signAndSendTransaction: true, browse: true, signIn: false
+      }
+    },
+
+    backpack: {
+      name: 'Backpack',
+      host: 'https://backpack.app',
+      // NO custom scheme is documented anywhere in Backpack's corpus — universal
+      // links only. Unlike Phantom there is no scheme fallback, so a caller that
+      // needs one must handle null rather than assume a template.
+      scheme: null,
+      // Backpack's docs CONTRADICT THEMSELVES on this key: its encryption page
+      // says wallet_encryption_public_key, its connect page says `wallet_xxx`,
+      // which reads as an unresolved placeholder. Both are listed so the
+      // resolver tries the documented name first and still works if the
+      // placeholder turns out to be literal. Confirm on a device before trusting
+      // either — this is the highest-risk unknown in the profile table.
+      connectKeys: ['wallet_encryption_public_key', 'wallet_xxx'],
+      browsePath: '/ul/v1/browse/',
+      // DEVNET IS NOT DOCUMENTED for Backpack — its cluster parameter documents
+      // only mainnet-beta (plus an Eclipse chain id). Consumers that test on
+      // devnet cannot currently QA this wallet, which is a lane decision, not a
+      // bug to paper over here. supportsCluster() reports it honestly.
+      clusters: ['mainnet-beta'],
+      send: 'wallet-broadcasts',
+      methods: {
+        connect: true, disconnect: true, signMessage: true,
+        signTransaction: true, signAllTransactions: true,
+        signAndSendTransaction: true, browse: true, signIn: false
+      }
+    }
+  };
+
+  // NO WALLET SHIPS A DOCUMENTED signIn DEEPLINK — every profile above says
+  // false, and that is a measurement, not an oversight. Phantom's 404s in its
+  // docs and exists only in its official demo app, where the payload is base58
+  // PLAINTEXT rather than ciphertext and the response key is `address` or
+  // `public_key` depending on version. Consumers currently depending on that
+  // endpoint are depending on something unspecified. Mobile sign-in is
+  // connect-then-signMessage — two hops — on all three wallets.
+
+  function key(wallet) {
+    return String(wallet == null ? '' : wallet).toLowerCase();
+  }
+
+  function profile(wallet) {
+    return PROFILES[key(wallet)] || null;
+  }
+
+  // Can THIS wallet do THIS method over the redirect transport?
+  //
+  // The capability question is the one that prevents this whole bug class: a
+  // button that renders without asking is how a null provider reached
+  // `.connect()` in the first place. An unknown wallet answers false rather
+  // than throwing — a caller asking about a wallet we have never heard of
+  // wants "no", not an exception.
+  function can(wallet, method) {
+    var p = profile(wallet);
+    return !!(p && p.methods[method] === true);
+  }
+
+  function supportsCluster(wallet, cluster) {
+    var p = profile(wallet);
+    return !!(p && p.clusters.indexOf(String(cluster)) !== -1);
+  }
+
+  // Which side broadcasts a signed transaction for this wallet.
+  // 'app-broadcasts'    → sign only, then the app sends and confirms (Phantom)
+  // 'wallet-broadcasts' → signAndSendTransaction returns a signature
+  function sendStrategy(wallet) {
+    var p = profile(wallet);
+    return p ? p.send : null;
+  }
+
+  // Pull the wallet's encryption public key out of the connect redirect's query
+  // params. This is the ONLY response key that differs between wallets, which is
+  // exactly why it is resolved here instead of at call sites.
+  //
+  // `params` is anything with a .get (URLSearchParams, or a plain-object shim).
+  function connectPublicKey(wallet, params) {
+    var p = profile(wallet);
+    if (!p || !params) return null;
+    var get = typeof params.get === 'function'
+      ? function (k) { return params.get(k); }
+      : function (k) { return params[k]; };
+    for (var i = 0; i < p.connectKeys.length; i++) {
+      var v = get(p.connectKeys[i]);
+      if (v) return v;
+    }
+    return null;
+  }
+
+  // --- Codec ---------------------------------------------------------------
+  //
+  // Shared by all three wallets without variation. Throws a NAMED error when
+  // nacl is absent rather than a bare TypeError on `nacl.box` — the whole point
+  // of a guarded dependency is that its absence reads as itself.
+  function nacl() {
+    if (!W.nacl) throw new Error('SolanaStudio.walletTransport requires tweetnacl (window.nacl)');
+    return W.nacl;
+  }
+
+  var codec = {
+    keypair: function () { return nacl().box.keyPair(); },
+
+    sharedSecret: function (walletPublicKeyB58, dappSecretKey) {
+      return nacl().box.before(decodeBase58(walletPublicKeyB58), dappSecretKey);
+    },
+
+    // Returns the two halves a request needs, both base58, ready to be query
+    // params. The nonce is fresh per request — reusing one across requests under
+    // the same shared secret is a real break, not a style preference.
+    encrypt: function (payloadObject, sharedSecret) {
+      var n = nacl();
+      var nonce = n.randomBytes(24);
+      var bytes = new TextEncoder().encode(JSON.stringify(payloadObject));
+      return {
+        nonce: encodeBase58(nonce),
+        payload: encodeBase58(n.box.after(bytes, nonce, sharedSecret))
+      };
+    },
+
+    decrypt: function (dataB58, nonceB58, sharedSecret) {
+      var opened = nacl().box.open.after(
+        decodeBase58(dataB58), decodeBase58(nonceB58), sharedSecret
+      );
+      if (!opened) throw new Error('Decryption failed — wrong shared secret or corrupt payload');
+      return JSON.parse(new TextDecoder().decode(opened));
+    }
+  };
+
+  // --- URL builders --------------------------------------------------------
+  function base(wallet, useScheme) {
+    var p = profile(wallet);
+    if (!p) throw new Error('Unknown wallet: ' + wallet);
+    // A caller may ASK for the scheme and not get it — Backpack documents none.
+    // Falling back to the universal link is correct and silent here; refusing
+    // would strand a caller that has a perfectly good link available.
+    if (useScheme && p.scheme) return { profile: p, prefix: p.scheme };
+    return { profile: p, prefix: p.host + '/ul/v1/' };
+  }
+
+  function query(pairs) {
+    var parts = [];
+    for (var k in pairs) {
+      if (!Object.prototype.hasOwnProperty.call(pairs, k)) continue;
+      if (pairs[k] === null || pairs[k] === undefined || pairs[k] === '') continue;
+      parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(pairs[k]));
+    }
+    return parts.join('&');
+  }
+
+  var url = {
+    // connect carries NO nonce and NO payload — the shared secret does not exist
+    // yet. Every other method requires both.
+    connect: function (wallet, opts) {
+      var b = base(wallet, opts && opts.useScheme);
+      return b.prefix + 'connect?' + query({
+        app_url: opts.appUrl,
+        dapp_encryption_public_key: opts.dappPublicKey,
+        redirect_link: opts.redirectLink,
+        cluster: opts.cluster
+      });
+    },
+
+    method: function (wallet, method, opts) {
+      if (!can(wallet, method)) {
+        throw new Error(wallet + ' does not support ' + method + ' over the redirect transport');
+      }
+      var b = base(wallet, opts && opts.useScheme);
+      return b.prefix + method + '?' + query({
+        dapp_encryption_public_key: opts.dappPublicKey,
+        nonce: opts.nonce,
+        redirect_link: opts.redirectLink,
+        payload: opts.payload
+      });
+    },
+
+    // The tier-3 handoff: open a page inside the wallet's own in-app browser,
+    // where the INJECTED provider works and the existing inline transport needs
+    // no changes at all. The target is a PATH segment, not a query param, and
+    // the version segment differs per wallet — both encoded in browsePath.
+    browse: function (wallet, targetUrl, refUrl) {
+      var p = profile(wallet);
+      if (!p) throw new Error('Unknown wallet: ' + wallet);
+      if (!can(wallet, 'browse')) throw new Error(p.name + ' has no browse deeplink');
+      return p.host + p.browsePath + encodeURIComponent(targetUrl) +
+             '?' + query({ ref: refUrl });
+    }
+  };
+
+  // Error redirects are IDENTICAL across all three wallets, codes included, so
+  // this needs no per-wallet branch. Read it BEFORE attempting any decryption:
+  // an error redirect carries no `data` and no `nonce`, so a decrypt-first
+  // reader turns a clean user rejection into a decryption exception.
+  var USER_REJECTED = '4001';
+
+  function errorFrom(params) {
+    if (!params) return null;
+    var get = typeof params.get === 'function'
+      ? function (k) { return params.get(k); }
+      : function (k) { return params[k]; };
+    var code = get('errorCode');
+    if (!code) return null;
+    return {
+      code: String(code),
+      message: get('errorMessage') || 'Wallet request failed',
+      rejected: String(code) === USER_REJECTED
+    };
+  }
+
+  W.SolanaStudio.walletTransport = {
+    PROFILES: PROFILES,
+    profile: profile,
+    can: can,
+    supportsCluster: supportsCluster,
+    sendStrategy: sendStrategy,
+    connectPublicKey: connectPublicKey,
+    errorFrom: errorFrom,
+    USER_REJECTED: USER_REJECTED,
+    base58: { encode: encodeBase58, decode: decodeBase58 },
+    codec: codec,
+    url: url
+  };
+})(typeof window !== 'undefined' ? window : globalThis);