@formo/analytics 1.38.2 → 1.39.0

package/dist/cjs/src/solana/SolanaWalletStandardRegistry.js

@@ -0,0 +1,447 @@
+"use strict";
+/**
+ * SolanaWalletStandardRegistry
+ *
+ * Which Solana wallets exist, and whether each is connected. The Solana
+ * analogue of `EvmProviderRegistry` + EIP-6963.
+ *
+ * Compatible wallets (Phantom, Solflare, Backpack, ...) announce themselves
+ * through the Wallet Standard's window-event handshake. Solana Kit,
+ * wallet-adapter, and framework-kit use these registered wallets. Observing
+ * the handshake covers those wallets without coupling Formo to the host
+ * library: the registry announces `wallet-standard:app-ready`, listens for
+ * `wallet-standard:register-wallet`, and subscribes to each wallet's
+ * `standard:events` `change` event.
+ *
+ * What it reports:
+ *  - `detect` when a wallet registers (session-deduped by the SDK on rdns).
+ *  - `connect` when a wallet's Solana accounts go from none to some, or the
+ *    first account changes; `disconnect` when they go from some to none.
+ *  - `chain` when the configured cluster changes while a wallet is connected.
+ *
+ * What it does not do: wrap any wallet method, issue any request to a
+ * wallet, or depend on `@wallet-standard/*` (the handshake is a few lines,
+ * and the SDK's dependency policy is two runtime dependencies, forever).
+ *
+ * Cluster: the Wallet Standard lists every cluster a wallet SUPPORTS, not
+ * the one the app is using, so the cluster is `options.solana.cluster` when
+ * given, else mainnet-beta when the wallet supports it, else the first
+ * Solana cluster it lists. A framework-kit app gets the cluster from its
+ * store instead, through `SolanaStoreHandler`.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolanaWalletStandardRegistry = void 0;
+var logger_1 = require("../logger");
+var address_1 = require("./address");
+var types_1 = require("./types");
+var walletStandardTypes_1 = require("./walletStandardTypes");
+var SOLANA_CHAIN_PREFIX = "solana:";
+/** Wallet Standard chain identifiers, keyed to Formo cluster names. */
+var CLUSTER_BY_CHAIN = {
+    "solana:mainnet": "mainnet-beta",
+    "solana:devnet": "devnet",
+    "solana:testnet": "testnet",
+    "solana:localnet": "localnet",
+};
+/** Whether a chain identifier belongs to the Solana namespace. */
+function isSolanaChain(chain) {
+    return typeof chain === "string" && chain.startsWith(SOLANA_CHAIN_PREFIX);
+}
+/**
+ * Accept only what looks like a Wallet Standard wallet that speaks Solana.
+ *
+ * A multichain wallet may register once and list Solana beside other
+ * namespaces; that is fine. A wallet that lists no Solana chain at all is
+ * not ours to track.
+ */
+function asSolanaWallet(candidate) {
+    if (!candidate || typeof candidate !== "object")
+        return undefined;
+    var wallet = candidate;
+    if (typeof wallet.name !== "string" || !wallet.name)
+        return undefined;
+    if (!Array.isArray(wallet.chains) || !wallet.chains.some(isSolanaChain)) {
+        return undefined;
+    }
+    if (!wallet.features || typeof wallet.features !== "object")
+        return undefined;
+    if (!Array.isArray(wallet.accounts))
+        return undefined;
+    return wallet;
+}
+/**
+ * The first account that is a Solana wallet account, or undefined.
+ *
+ * An account declares the chains it signs for. On a multichain wallet the
+ * list can hold an EVM account beside a Solana one, and the SDK's connect
+ * validates the address against the chain id, so only a Solana account may
+ * be reported under a Solana chain id. An account with no chain list is
+ * judged on its address alone.
+ */
+function firstSolanaAccount(accounts) {
+    for (var _i = 0, accounts_1 = accounts; _i < accounts_1.length; _i++) {
+        var candidate = accounts_1[_i];
+        if (!candidate || typeof candidate !== "object")
+            continue;
+        var account = candidate;
+        if (Array.isArray(account.chains) && !account.chains.some(isSolanaChain)) {
+            continue;
+        }
+        if (!(0, address_1.isSolanaAddress)(account.address))
+            continue;
+        if ((0, address_1.isBlockedSolanaAddress)(account.address))
+            continue;
+        return account;
+    }
+    return undefined;
+}
+var SolanaWalletStandardRegistry = /** @class */ (function () {
+    function SolanaWalletStandardRegistry(deps, options) {
+        var _this = this;
+        this.deps = deps;
+        this.wallets = new Map();
+        /** Set by cleanup(); a torn-down registry refuses late registrations. */
+        this.isCleanedUp = false;
+        this.cluster = options === null || options === void 0 ? void 0 : options.cluster;
+        this.api = Object.freeze({
+            register: function () {
+                var wallets = [];
+                for (var _i = 0; _i < arguments.length; _i++) {
+                    wallets[_i] = arguments[_i];
+                }
+                return _this.register.apply(_this, wallets);
+            },
+        });
+        this.listen();
+    }
+    // ── discovery ───────────────────────────────────────────────────────────
+    /**
+     * The Wallet Standard handshake, both directions.
+     *
+     * A wallet injected before us hears `app-ready` and registers at once; a
+     * wallet injected after us dispatches `register-wallet`, which we answer.
+     * Neither is optional: an extension's content script and the app's bundle
+     * race, and which one wins differs per page load.
+     */
+    SolanaWalletStandardRegistry.prototype.listen = function () {
+        var _this = this;
+        if (typeof window === "undefined" ||
+            typeof window.addEventListener !== "function") {
+            return;
+        }
+        var onRegisterWallet = function (event) {
+            var callback = event.detail;
+            if (typeof callback !== "function")
+                return;
+            try {
+                callback(_this.api);
+            }
+            catch (error) {
+                logger_1.logger.warn("SolanaWalletStandardRegistry: A wallet threw while registering", error);
+            }
+        };
+        try {
+            window.addEventListener(walletStandardTypes_1.WALLET_STANDARD_REGISTER_WALLET_EVENT, onRegisterWallet);
+            this.removeWindowListener = function () {
+                return window.removeEventListener(walletStandardTypes_1.WALLET_STANDARD_REGISTER_WALLET_EVENT, onRegisterWallet);
+            };
+        }
+        catch (error) {
+            logger_1.logger.warn("SolanaWalletStandardRegistry: Could not listen for wallet registrations", error);
+        }
+        if (typeof CustomEvent !== "function")
+            return;
+        try {
+            window.dispatchEvent(new CustomEvent(walletStandardTypes_1.WALLET_STANDARD_APP_READY_EVENT, { detail: this.api }));
+        }
+        catch (error) {
+            logger_1.logger.warn("SolanaWalletStandardRegistry: Could not announce app-ready", error);
+        }
+    };
+    /**
+     * Add wallets once. Returns an unregister function, as the standard asks.
+     *
+     * Public so an integration that already holds a wallet object (its own
+     * `getWallets()` call, say) can hand it over without the window handshake.
+     */
+    SolanaWalletStandardRegistry.prototype.register = function () {
+        var _this = this;
+        var wallets = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            wallets[_i] = arguments[_i];
+        }
+        var added = [];
+        if (this.isCleanedUp)
+            return function () { return undefined; };
+        for (var _a = 0, wallets_1 = wallets; _a < wallets_1.length; _a++) {
+            var candidate = wallets_1[_a];
+            var wallet = asSolanaWallet(candidate);
+            if (!wallet || this.wallets.has(wallet))
+                continue;
+            var tracked = {
+                wallet: wallet,
+                name: wallet.name,
+                rdns: (0, types_1.solanaWalletRdns)(wallet.name),
+                connectWasReported: false,
+            };
+            this.wallets.set(wallet, tracked);
+            added.push(tracked);
+            this.track(tracked);
+        }
+        return function () {
+            for (var _i = 0, added_1 = added; _i < added_1.length; _i++) {
+                var tracked = added_1[_i];
+                _this.untrack(tracked);
+            }
+        };
+    };
+    SolanaWalletStandardRegistry.prototype.track = function (tracked) {
+        var _this = this;
+        logger_1.logger.info("SolanaWalletStandardRegistry: Discovered wallet", {
+            name: tracked.name,
+            chains: tracked.wallet.chains,
+        });
+        this.deps
+            .detect({ providerName: tracked.name, rdns: tracked.rdns })
+            .catch(function (error) {
+            logger_1.logger.error("SolanaWalletStandardRegistry: Error emitting detect", error);
+        });
+        var events = tracked.wallet.features[walletStandardTypes_1.WALLET_STANDARD_EVENTS_FEATURE];
+        if (events && typeof events.on === "function") {
+            try {
+                tracked.unsubscribe = events.on("change", function (properties) {
+                    return _this.onChange(tracked, properties);
+                });
+            }
+            catch (error) {
+                logger_1.logger.warn("SolanaWalletStandardRegistry: Could not subscribe to ".concat(tracked.name, " events"), error);
+            }
+        }
+        else {
+            logger_1.logger.info("SolanaWalletStandardRegistry: ".concat(tracked.name, " has no standard:events feature; connections cannot be observed"));
+        }
+        // A wallet that is already authorized when we first see it (the app
+        // connected before the SDK initialised, or the wallet restored a trusted
+        // session on load) will never fire a change event for that connection.
+        this.reconcile(tracked, tracked.wallet.accounts);
+    };
+    SolanaWalletStandardRegistry.prototype.untrack = function (tracked) {
+        var _a;
+        try {
+            (_a = tracked.unsubscribe) === null || _a === void 0 ? void 0 : _a.call(tracked);
+        }
+        catch (error) {
+            logger_1.logger.warn("SolanaWalletStandardRegistry: Could not unsubscribe from ".concat(tracked.name), error);
+        }
+        tracked.unsubscribe = undefined;
+        this.wallets.delete(tracked.wallet);
+    };
+    // ── connection state ────────────────────────────────────────────────────
+    SolanaWalletStandardRegistry.prototype.onChange = function (tracked, properties) {
+        if (this.isCleanedUp)
+            return;
+        // `change` carries only what changed. A wallet that omits `accounts` is
+        // reporting something else (chains, features); the wallet's own
+        // `accounts` is the ground truth either way, so read that when the
+        // event does not say.
+        var accounts = Array.isArray(properties === null || properties === void 0 ? void 0 : properties.accounts)
+            ? properties.accounts
+            : tracked.wallet.accounts;
+        this.reconcile(tracked, Array.isArray(accounts) ? accounts : []);
+    };
+    /**
+     * Compare what the wallet now authorizes with what was last reported.
+     *
+     * none → some is a connect, some → none a disconnect, and a different
+     * first account is a disconnect followed by a connect, matching what the
+     * framework-kit store handler reports for the same transitions.
+     */
+    SolanaWalletStandardRegistry.prototype.reconcile = function (tracked, accounts) {
+        var next = firstSolanaAccount(accounts);
+        var previous = tracked.connected;
+        if (!previous && !next)
+            return;
+        if (previous && next && previous.address === next.address)
+            return;
+        if (!this.deps.ownsWalletEvents()) {
+            // The store handler reports this connection. Still record it, so a
+            // later change is judged against what the wallet actually did rather
+            // than against a stale snapshot.
+            tracked.connected = next
+                ? { address: next.address, chainId: this.chainIdFor(tracked) }
+                : undefined;
+            tracked.connectWasReported = false;
+            return;
+        }
+        if (previous)
+            this.reportDisconnect(tracked, previous);
+        if (next)
+            this.reportConnect(tracked, next.address);
+    };
+    SolanaWalletStandardRegistry.prototype.reportConnect = function (tracked, address) {
+        var chainId = this.chainIdFor(tracked);
+        tracked.connected = { address: address, chainId: chainId };
+        tracked.connectWasReported = false;
+        logger_1.logger.info("SolanaWalletStandardRegistry: Wallet connected", {
+            name: tracked.name,
+            address: address,
+            chainId: chainId,
+        });
+        if (!this.deps.isAutocaptureEnabled("connect"))
+            return;
+        // FormoAnalytics.connect() deliberately resolves without enqueueing when
+        // tracking is suppressed or this chain is excluded. Only a connect that
+        // can actually be accepted may suppress the authoritative store event
+        // that can follow.
+        if (!this.deps.willTrackEvent(chainId))
+            return;
+        tracked.connectWasReported = true;
+        this.deps
+            .connect({ chainId: chainId, address: address }, { providerName: tracked.name, rdns: tracked.rdns })
+            .catch(function (error) {
+            logger_1.logger.error("SolanaWalletStandardRegistry: Error emitting connect", error);
+        });
+    };
+    SolanaWalletStandardRegistry.prototype.reportDisconnect = function (tracked, previous) {
+        tracked.connected = undefined;
+        tracked.connectWasReported = false;
+        logger_1.logger.info("SolanaWalletStandardRegistry: Wallet disconnected", {
+            name: tracked.name,
+            address: previous.address,
+            chainId: previous.chainId,
+        });
+        if (!this.deps.isAutocaptureEnabled("disconnect"))
+            return;
+        this.deps.disconnect(previous).catch(function (error) {
+            logger_1.logger.error("SolanaWalletStandardRegistry: Error emitting disconnect", error);
+        });
+    };
+    // ── cluster ─────────────────────────────────────────────────────────────
+    /**
+     * The chain id to report for a wallet.
+     *
+     * The Wallet Standard cannot say which cluster the app is on, only which
+     * ones the wallet supports, so an explicit cluster wins, then mainnet-beta
+     * if supported (nearly every wallet lists every cluster, and production
+     * traffic is mainnet), then the first cluster listed.
+     */
+    SolanaWalletStandardRegistry.prototype.chainIdFor = function (tracked) {
+        if (this.cluster)
+            return types_1.SOLANA_CHAIN_IDS[this.cluster];
+        var chains = tracked.wallet.chains;
+        if (chains.includes("solana:mainnet"))
+            return types_1.DEFAULT_SOLANA_CHAIN_ID;
+        for (var _i = 0, chains_1 = chains; _i < chains_1.length; _i++) {
+            var chain = chains_1[_i];
+            var cluster = CLUSTER_BY_CHAIN[chain];
+            if (cluster)
+                return types_1.SOLANA_CHAIN_IDS[cluster];
+        }
+        return types_1.DEFAULT_SOLANA_CHAIN_ID;
+    };
+    /**
+     * Set the cluster the app uses. A connected wallet's chain id follows,
+     * with a `chain` event, the same as the store handler on a cluster switch.
+     */
+    SolanaWalletStandardRegistry.prototype.setCluster = function (cluster) {
+        var _a;
+        if (this.cluster === cluster)
+            return;
+        this.cluster = cluster;
+        var chainId = types_1.SOLANA_CHAIN_IDS[cluster];
+        var all = Array.from(this.wallets.values());
+        // Central state follows ONE wallet. Two wallets can hold an authorized
+        // account at once, and writing each of them here would hand the wallet
+        // slot to the last REGISTERED wallet rather than to the one the SDK
+        // already treats as active, which is the last CONNECTED one.
+        var active = this.deps.currentAddress();
+        var owner = (_a = all.find(function (t) { return t.connected && t.connected.address === active; })) !== null && _a !== void 0 ? _a : all.find(function (t) { return t.connected; });
+        for (var _i = 0, all_1 = all; _i < all_1.length; _i++) {
+            var tracked = all_1[_i];
+            var connected = tracked.connected;
+            if (!connected || connected.chainId === chainId)
+                continue;
+            tracked.connected = { address: connected.address, chainId: chainId };
+            if (!this.deps.ownsWalletEvents())
+                continue;
+            // Central state moves first, so a suppressed chain event still leaves
+            // the SDK on the cluster the wallet is actually on. `chain()` writes
+            // the cluster itself, but only when the event is not suppressed.
+            if (tracked === owner) {
+                this.deps.syncWalletState({ chainId: chainId, address: connected.address });
+            }
+            if (!this.deps.isAutocaptureEnabled("chain"))
+                continue;
+            this.deps
+                .chain({ chainId: chainId, address: connected.address })
+                .catch(function (error) {
+                logger_1.logger.error("SolanaWalletStandardRegistry: Error emitting chain event", error);
+            });
+        }
+    };
+    Object.defineProperty(SolanaWalletStandardRegistry.prototype, "walletNames", {
+        // ── introspection ───────────────────────────────────────────────────────
+        /** Names of every wallet discovered so far, for the debug helpers. */
+        get: function () {
+            return Array.from(this.wallets.values()).map(function (t) { return t.name; });
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * The rdns this registry reported a still-live connect for `address`
+     * under, if any. Lets a failed store adoption name both identities.
+     */
+    SolanaWalletStandardRegistry.prototype.reportedConnectionRdns = function (address) {
+        var _a;
+        for (var _i = 0, _b = Array.from(this.wallets.values()); _i < _b.length; _i++) {
+            var tracked = _b[_i];
+            if (tracked.connectWasReported &&
+                ((_a = tracked.connected) === null || _a === void 0 ? void 0 : _a.address) === address) {
+                return tracked.rdns;
+            }
+        }
+        return undefined;
+    };
+    /**
+     * Transfer a connect already emitted by this registry to a store handler.
+     * The state remains connected, but the same transition must not be emitted
+     * a second time when framework-kit's store catches up.
+     */
+    SolanaWalletStandardRegistry.prototype.takeReportedConnection = function (address, rdns) {
+        var _a;
+        for (var _i = 0, _b = Array.from(this.wallets.values()); _i < _b.length; _i++) {
+            var tracked = _b[_i];
+            if (tracked.connectWasReported &&
+                ((_a = tracked.connected) === null || _a === void 0 ? void 0 : _a.address) === address &&
+                tracked.rdns === rdns) {
+                tracked.connectWasReported = false;
+                return tracked.connected;
+            }
+        }
+        return undefined;
+    };
+    // ── teardown ────────────────────────────────────────────────────────────
+    SolanaWalletStandardRegistry.prototype.cleanup = function () {
+        var _a;
+        this.isCleanedUp = true;
+        try {
+            (_a = this.removeWindowListener) === null || _a === void 0 ? void 0 : _a.call(this);
+        }
+        catch (error) {
+            logger_1.logger.warn("SolanaWalletStandardRegistry: Could not remove window listener", error);
+        }
+        this.removeWindowListener = undefined;
+        for (var _i = 0, _b = Array.from(this.wallets.values()); _i < _b.length; _i++) {
+            var tracked = _b[_i];
+            this.untrack(tracked);
+        }
+        this.wallets.clear();
+        logger_1.logger.debug("SolanaWalletStandardRegistry: Cleanup complete");
+    };
+    return SolanaWalletStandardRegistry;
+}());
+exports.SolanaWalletStandardRegistry = SolanaWalletStandardRegistry;
+//# sourceMappingURL=SolanaWalletStandardRegistry.js.map

package/dist/cjs/src/solana/index.d.ts

@@ -1,17 +1,22 @@
 /**
  * Solana integration module
  *
- * Provides automatic event capture for Solana wallets via framework-kit's
- * zustand store. Connect/disconnect and transaction events are tracked
- * automatically. Signature events (signMessage/signTransaction) require
- * explicit tracking via formo.signature() since framework-kit
- * doesn't track these in store state.
+ * Wallets are discovered through the Wallet Standard and their connect /
+ * disconnect events captured automatically for wallets registered with the
+ * page through Wallet Standard.
+ * Framework-kit apps can additionally pass their zustand store for
+ * transaction lifecycle events. Signature events (signMessage /
+ * signTransaction) require explicit tracking via formo.signature(), since
+ * neither source reports them.
  *
+ * @see https://github.com/wallet-standard/wallet-standard
  * @see https://github.com/solana-foundation/framework-kit
  */
 export { SolanaStoreHandler } from "./SolanaStoreHandler";
+export { SolanaWalletStandardRegistry } from "./SolanaWalletStandardRegistry";
 export { SolanaManager } from "./SolanaManager";
 export * from "./types";
 export * from "./storeTypes";
+export * from "./walletStandardTypes";
 export * from "./address";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/src/solana/index.js

@@ -2,12 +2,15 @@
 /**
  * Solana integration module
  *
- * Provides automatic event capture for Solana wallets via framework-kit's
- * zustand store. Connect/disconnect and transaction events are tracked
- * automatically. Signature events (signMessage/signTransaction) require
- * explicit tracking via formo.signature() since framework-kit
- * doesn't track these in store state.
+ * Wallets are discovered through the Wallet Standard and their connect /
+ * disconnect events captured automatically for wallets registered with the
+ * page through Wallet Standard.
+ * Framework-kit apps can additionally pass their zustand store for
+ * transaction lifecycle events. Signature events (signMessage /
+ * signTransaction) require explicit tracking via formo.signature(), since
+ * neither source reports them.
  *
+ * @see https://github.com/wallet-standard/wallet-standard
  * @see https://github.com/solana-foundation/framework-kit
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -25,12 +28,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SolanaManager = exports.SolanaStoreHandler = void 0;
+exports.SolanaManager = exports.SolanaWalletStandardRegistry = exports.SolanaStoreHandler = void 0;
 var SolanaStoreHandler_1 = require("./SolanaStoreHandler");
 Object.defineProperty(exports, "SolanaStoreHandler", { enumerable: true, get: function () { return SolanaStoreHandler_1.SolanaStoreHandler; } });
+var SolanaWalletStandardRegistry_1 = require("./SolanaWalletStandardRegistry");
+Object.defineProperty(exports, "SolanaWalletStandardRegistry", { enumerable: true, get: function () { return SolanaWalletStandardRegistry_1.SolanaWalletStandardRegistry; } });
 var SolanaManager_1 = require("./SolanaManager");
 Object.defineProperty(exports, "SolanaManager", { enumerable: true, get: function () { return SolanaManager_1.SolanaManager; } });
 __exportStar(require("./types"), exports);
 __exportStar(require("./storeTypes"), exports);
+__exportStar(require("./walletStandardTypes"), exports);
 __exportStar(require("./address"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/solana/storeTypes.d.ts

@@ -72,13 +72,32 @@ export interface SolanaWalletConnectorMetadata {
     readonly name: string;
     readonly icon?: string;
 }
+/** Cluster health as exposed by framework-kit. */
+export type SolanaClusterStatus = Readonly<{
+    status: "idle";
+}> | Readonly<{
+    status: "connecting";
+}> | Readonly<{
+    status: "ready";
+    latencyMs?: number;
+}> | Readonly<{
+    status: "error";
+    error: unknown;
+}>;
+/** @deprecated framework-kit emits {@link SolanaClusterStatus} objects. */
+export type LegacySolanaClusterStatus = SolanaClusterStatus["status"];
 /**
  * Cluster state from the store.
  */
 export interface SolanaClusterState {
     readonly endpoint: string;
     readonly commitment?: string;
-    readonly status: "idle" | "connecting" | "ready" | "error";
+    /**
+     * framework-kit's `ClusterStatus` is a discriminated union such as
+     * `{ status: 'ready', latencyMs?: number }`. The pre-1.39 string form is
+     * retained so custom stores and test doubles remain source-compatible.
+     */
+    readonly status: SolanaClusterStatus | LegacySolanaClusterStatus;
 }
 /**
  * The zustand vanilla store API that framework-kit exposes via `client.store`.

package/dist/cjs/src/solana/types.d.ts

@@ -46,15 +46,32 @@ export interface SolanaPublicKey {
  */
 export type UnsubscribeFn = () => void;
 /**
- * Solana options for FormoAnalytics
+ * The rdns reported for a Solana wallet.
+ *
+ * The Wallet Standard has no reverse-domain identifier, so one is derived
+ * from the wallet's normalized name. Lowercasing and removing whitespace
+ * preserves the values historically reported by the framework-kit store;
+ * encoding keeps delimiters and other special characters safe for storage.
+ * Both Solana paths (Wallet Standard discovery and the framework-kit store)
+ * derive it the same way, so a wallet's `detect` and its `connect` share one
+ * rdns whichever path reported each.
+ */
+export declare function solanaWalletRdns(walletName: string): string;
+/**
+ * Solana options for FormoAnalytics.
+ *
+ * Wallet discovery through the Wallet Standard is on by default and needs
+ * none of these. They add framework-kit's store, or name the cluster.
  */
 export interface SolanaOptions {
     /**
-     * The framework-kit client store (client.store) for automatic event tracking.
-     * When provided, wallet connect/disconnect and transaction events are tracked
-     * automatically by subscribing to zustand store state changes.
+     * The framework-kit client store (client.store).
+     * When provided, transaction lifecycle events and cluster switches are
+     * tracked from the store, and connect/disconnect come from the store
+     * rather than from Wallet Standard discovery.
      *
-     * This is the recommended approach for apps using framework-kit.
+     * Only for apps using framework-kit (`@solana/client`). Other integrations
+     * do not need a store when their wallets register through Wallet Standard.
      *
      * @example
      * ```tsx
@@ -65,10 +82,16 @@ export interface SolanaOptions {
      */
     store?: import("./storeTypes").SolanaClientStore;
     /**
-     * The Solana cluster/network.
-     * Usually auto-detected from the store's endpoint URL.
-     * Only needed for custom RPC URLs that don't contain a recognizable cluster name.
-     * @default auto-detected, or "mainnet-beta" if detection fails
+     * The Solana cluster/network the app is on.
+     *
+     * With a store, usually auto-detected from its endpoint URL; only needed
+     * for custom RPC URLs that don't contain a recognizable cluster name.
+     * Without a store, the Wallet Standard cannot say which cluster the app
+     * uses, so a devnet or testnet app should set this (or call
+     * `formo.solana.setCluster()`); otherwise connections are reported on
+     * mainnet-beta.
+     * @default auto-detected from the store; otherwise mainnet-beta when the
+     * wallet supports it, or its first supported Solana cluster
      */
     cluster?: SolanaCluster;
 }

package/dist/cjs/src/solana/types.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SOLANA_CHAIN_ID = exports.SOLANA_CLUSTERS_BY_ID = exports.SOLANA_CHAIN_IDS = void 0;
 exports.isSolanaChainId = isSolanaChainId;
+exports.solanaWalletRdns = solanaWalletRdns;
 /**
  * Mapping of Solana clusters to numeric chain IDs for consistency with EVM events
  * These IDs are non-standard but provide a way to identify Solana networks in our analytics
@@ -44,4 +45,18 @@ function isSolanaChainId(chainId) {
         return false;
     return Object.values(exports.SOLANA_CHAIN_IDS).includes(chainId);
 }
+/**
+ * The rdns reported for a Solana wallet.
+ *
+ * The Wallet Standard has no reverse-domain identifier, so one is derived
+ * from the wallet's normalized name. Lowercasing and removing whitespace
+ * preserves the values historically reported by the framework-kit store;
+ * encoding keeps delimiters and other special characters safe for storage.
+ * Both Solana paths (Wallet Standard discovery and the framework-kit store)
+ * derive it the same way, so a wallet's `detect` and its `connect` share one
+ * rdns whichever path reported each.
+ */
+function solanaWalletRdns(walletName) {
+    return "sol.wallet.".concat(encodeURIComponent(walletName.toLowerCase().replace(/\s+/g, "")));
+}
 //# sourceMappingURL=types.js.map