@formo/analytics 1.38.2 → 1.40.0

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

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

@@ -0,0 +1,54 @@
+/**
+ * The subset of the Wallet Standard this SDK reads.
+ *
+ * Duck-typed on purpose: the SDK must not depend on `@wallet-standard/*`
+ * packages (see the dependency policy), and a wallet is discovered through
+ * window events, so nothing here is ever imported from a wallet library.
+ * Every field is what a conforming wallet exposes; the shapes are looser
+ * than the reference types so a slightly off wallet is skipped, not thrown
+ * on.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+/** `namespace:reference`, e.g. `solana:mainnet` or `solana:devnet`. */
+export type WalletStandardChain = string;
+export interface WalletStandardAccount {
+    readonly address: string;
+    readonly publicKey?: unknown;
+    /** Chains this account can sign for. Absent on a non-conforming wallet. */
+    readonly chains?: readonly WalletStandardChain[];
+    readonly features?: readonly string[];
+    readonly label?: string;
+    readonly icon?: string;
+}
+export interface WalletStandardWallet {
+    readonly version?: string;
+    readonly name: string;
+    readonly icon?: string;
+    /** Every chain the wallet supports, NOT the one currently selected. */
+    readonly chains: readonly WalletStandardChain[];
+    readonly features: Readonly<Record<string, unknown>>;
+    /** Accounts the app is currently authorized for; empty until connected. */
+    readonly accounts: readonly WalletStandardAccount[];
+}
+/** What a `standard:events` `change` event carries: only what changed. */
+export interface WalletStandardChangeProperties {
+    readonly chains?: readonly WalletStandardChain[];
+    readonly features?: Readonly<Record<string, unknown>>;
+    readonly accounts?: readonly WalletStandardAccount[];
+}
+/** The `standard:events` feature. */
+export interface WalletStandardEventsFeature {
+    readonly version?: string;
+    on(event: "change", listener: (properties: WalletStandardChangeProperties) => void): () => void;
+}
+/** The API an app hands to wallets so they can announce themselves. */
+export interface WalletStandardRegisterApi {
+    register(...wallets: WalletStandardWallet[]): () => void;
+}
+/** Dispatched by the app on `window`; `detail` is the register API. */
+export declare const WALLET_STANDARD_APP_READY_EVENT = "wallet-standard:app-ready";
+/** Dispatched by a wallet on `window`; `detail` is a callback taking the API. */
+export declare const WALLET_STANDARD_REGISTER_WALLET_EVENT = "wallet-standard:register-wallet";
+export declare const WALLET_STANDARD_EVENTS_FEATURE = "standard:events";
+//# sourceMappingURL=walletStandardTypes.d.ts.map

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

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * The subset of the Wallet Standard this SDK reads.
+ *
+ * Duck-typed on purpose: the SDK must not depend on `@wallet-standard/*`
+ * packages (see the dependency policy), and a wallet is discovered through
+ * window events, so nothing here is ever imported from a wallet library.
+ * Every field is what a conforming wallet exposes; the shapes are looser
+ * than the reference types so a slightly off wallet is skipped, not thrown
+ * on.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WALLET_STANDARD_EVENTS_FEATURE = exports.WALLET_STANDARD_REGISTER_WALLET_EVENT = exports.WALLET_STANDARD_APP_READY_EVENT = void 0;
+/** Dispatched by the app on `window`; `detail` is the register API. */
+exports.WALLET_STANDARD_APP_READY_EVENT = "wallet-standard:app-ready";
+/** Dispatched by a wallet on `window`; `detail` is a callback taking the API. */
+exports.WALLET_STANDARD_REGISTER_WALLET_EVENT = "wallet-standard:register-wallet";
+exports.WALLET_STANDARD_EVENTS_FEATURE = "standard:events";
+//# sourceMappingURL=walletStandardTypes.js.map

package/dist/cjs/src/storage/StorageManager.d.ts

@@ -2,8 +2,10 @@ import { IStorage, StorageType } from "./type";
 export declare class StorageManager {
     private readonly writeKey;
     private storages;
+    private resolvedTypes;
     constructor(writeKey: string);
     getStorage(type: StorageType): IStorage;
+    getResolvedType(type: StorageType): StorageType;
     private createStorage;
     private getWebStorage;
 }

package/dist/cjs/src/storage/StorageManager.js

@@ -19,6 +19,7 @@ var StorageManager = /** @class */ (function () {
     function StorageManager(writeKey) {
         this.writeKey = writeKey;
         this.storages = new Map();
+        this.resolvedTypes = new Map();
     }
     StorageManager.prototype.getStorage = function (type) {
         if (!this.storages.has(type)) {
@@ -39,9 +40,14 @@ var StorageManager = /** @class */ (function () {
             }
             // Add to cache
             this.storages.set(type, storage);
+            this.resolvedTypes.set(type, currentType);
         }
         return this.storages.get(type);
     };
+    StorageManager.prototype.getResolvedType = function (type) {
+        this.getStorage(type);
+        return this.resolvedTypes.get(type);
+    };
     StorageManager.prototype.createStorage = function (type) {
         switch (type) {
             case "cookieStorage":

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

@@ -5,4 +5,5 @@ export declare const cookie: () => IStorage;
 export declare const local: () => IStorage;
 export declare const session: () => IStorage;
 export declare const memory: () => IStorage;
+export declare const usesCookieStorage: () => boolean;
 //# sourceMappingURL=index.d.ts.map

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

@@ -14,7 +14,7 @@ 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.memory = exports.session = exports.local = exports.cookie = void 0;
+exports.usesCookieStorage = exports.memory = exports.session = exports.local = exports.cookie = void 0;
 exports.initStorageManager = initStorageManager;
 var StorageManager_1 = require("./StorageManager");
 __exportStar(require("./type"), exports);
@@ -38,4 +38,10 @@ var session = function () { return getStorageInstance("sessionStorage"); };
 exports.session = session;
 var memory = function () { return getStorageInstance("memoryStorage"); };
 exports.memory = memory;
+var usesCookieStorage = function () {
+    if (!globalManager)
+        return false;
+    return globalManager.getResolvedType("cookieStorage") === "cookieStorage";
+};
+exports.usesCookieStorage = usesCookieStorage;
 //# sourceMappingURL=index.js.map

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

@@ -246,16 +246,26 @@ export interface Options {
      */
     wagmi?: WagmiOptions;
     /**
-     * Solana integration configuration.
-     * Pass `store: client.store` from framework-kit for automatic tracking of
-     * wallet connect/disconnect and transaction events.
+     * Solana wallet tracking.
+     *
+     * On by default: wallets are discovered through the Wallet Standard, the
+     * Solana analogue of EIP-6963, so connect and disconnect are autocaptured
+     * for compatible wallets registered with the page, including wallets used
+     * through Solana Kit, wallet-adapter, and framework-kit.
+     *
+     * - `false`: disable Solana wallet discovery and tracking entirely.
+     * - `SolanaOptions`: additionally pass `store: client.store` from
+     *   framework-kit for transaction lifecycle events and cluster switches,
+     *   or `cluster` to name the network a non-mainnet app is on.
      *
      * For signMessage/signTransaction, use formo.signature() directly
-     * (framework-kit doesn't track these in the store).
+     * (neither the Wallet Standard nor framework-kit's store reports these).
      *
+     * @see https://github.com/wallet-standard/wallet-standard
      * @see https://github.com/solana-foundation/framework-kit
+     * @default true
      */
-    solana?: SolanaOptions;
+    solana?: boolean | SolanaOptions;
     /**
      * Custom API host for sending events through your own domain to bypass ad blockers
      * - If not provided, events are sent directly to events.formo.so

package/dist/cjs/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "1.38.2";
+export declare const version = "1.40.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/src/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-exports.version = '1.38.2';
+exports.version = '1.40.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/src/FormoAnalytics.d.ts

@@ -54,6 +54,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private _onPopStateListener?;
     private _onLocationChangeListener?;
     private _pageHooksDisposed;
+    private _pageGeneration;
     config: Config;
     /**
      * The wallet later events are attributed to, derived from whichever
@@ -87,7 +88,8 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      */
     page(category?: string, name?: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     /**
-     * Reset the current user session.
+     * Reset user and wallet state while preserving the browser's anonymous id.
+     * Use `optOutTracking()` to clear the anonymous id and the attribution.
      * @returns {void}
      */
     reset(): void;
@@ -142,6 +144,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
         chainId?: ChainID;
         address?: Address;
     }): void;
+    private retryWalletDetection;
     /** @see WalletStateStore.clearProvider */
     private clearActiveProvider;
     /** @see WalletStateStore.backfill */

package/dist/esm/src/FormoAnalytics.js

@@ -49,6 +49,7 @@ import { EVENTS_API_HOST, EventType, LOCAL_ANONYMOUS_ID_KEY, SESSION_USER_ID_KEY
 import { cookie, session, initStorageManager } from "./storage";
 import { getIdentityCookieDomain, getIdentityCookieSecurity, } from "./storage/cookiePolicy";
 import { EventManager } from "./event";
+import { clearAnonymousId } from "./event/utils";
 import { EventQueue } from "./queue";
 import { logger, Logger } from "./logger";
 import { setConsentFlag, getConsentFlag, removeConsentFlag, } from "./consent";
@@ -90,6 +91,7 @@ var FormoAnalytics = /** @class */ (function () {
         /** In-memory URL used to deduplicate SPA pageview events. */
         this._currentUrl = "";
         this._pageHooksDisposed = false;
+        this._pageGeneration = 0;
         this.currentUserId = "";
         /**
          * Clean up resources and event listeners
@@ -187,6 +189,7 @@ var FormoAnalytics = /** @class */ (function () {
             isAutocaptureEnabled: function (t) { return _this.isAutocaptureEnabled(t); },
             isTrackingSuppressed: function () { return _this.isTrackingSuppressed(); },
             willTrackEvent: function (chainId) { return _this.willTrackEvent(chainId); },
+            retryDetection: function () { return _this.retryWalletDetection(); },
             isWagmiMode: function () { return _this.isWagmiMode; },
             connect: function (params, properties) { return _this.connect(params, properties); },
             disconnect: function (params) { return _this.disconnect(params); },
@@ -215,7 +218,7 @@ var FormoAnalytics = /** @class */ (function () {
             // ever sent once the user has opted out, even via a timer or
             // pagehide flush scheduled before opt-out.
             canSend: function () { return !_this.hasOptedOutTracking(); },
-        }), options);
+        }), options, function () { return !_this.hasOptedOutTracking(); });
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
             logger.info("User has previously opted out of tracking");
@@ -242,9 +245,12 @@ var FormoAnalytics = /** @class */ (function () {
                 this.evmEvents.trackEIP1193Provider(provider);
             }
         }
-        // Initialize Solana manager if Solana options are provided
-        if (options.solana) {
-            this.solanaManager = new SolanaManager(this, options.solana);
+        // Solana wallets are discovered through the Wallet Standard
+        // unconditionally, the way EVM wallets are through EIP-6963: an app
+        // that never configures Solana still gets its connects. `solana: false`
+        // is the opt-out; an object adds framework-kit's store or a cluster.
+        if (options.solana !== false) {
+            this.solanaManager = new SolanaManager(this, typeof options.solana === "object" ? options.solana : undefined);
         }
         this._currentUrl = window.location.href;
         // Seed currentAddress/currentChainId from the persisted snapshot before
@@ -314,7 +320,7 @@ var FormoAnalytics = /** @class */ (function () {
     });
     FormoAnalytics.init = function (writeKey, options) {
         return __awaiter(this, void 0, void 0, function () {
-            var analytics, discovered;
+            var analytics, discovered, error_1;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -324,18 +330,21 @@ var FormoAnalytics = /** @class */ (function () {
                         logger.info("FormoAnalytics: Skipping provider detection (EVM disabled)");
                         return [3 /*break*/, 5];
                     case 1:
-                        if (!!analytics.isWagmiMode) return [3 /*break*/, 4];
+                        _a.trys.push([1, 4, , 5]);
                         return [4 /*yield*/, analytics.evmEvents.getProviders()];
                     case 2:
                         discovered = _a.sent();
                         return [4 /*yield*/, analytics.evmEvents.detectWallets(discovered)];
                     case 3:
                         _a.sent();
-                        analytics.evmEvents.trackProviders(discovered);
+                        if (!analytics.isWagmiMode) {
+                            analytics.evmEvents.trackProviders(discovered);
+                        }
                         return [3 /*break*/, 5];
                     case 4:
-                        logger.info("FormoAnalytics: Skipping provider detection (Wagmi mode)");
-                        _a.label = 5;
+                        error_1 = _a.sent();
+                        logger.warn("FormoAnalytics: Provider discovery failed", error_1);
+                        return [3 /*break*/, 5];
                     case 5: return [2 /*return*/, analytics];
                 }
             });
@@ -366,7 +375,8 @@ var FormoAnalytics = /** @class */ (function () {
         });
     };
     /**
-     * Reset the current user session.
+     * Reset user and wallet state while preserving the browser's anonymous id.
+     * Use `optOutTracking()` to clear the anonymous id and the attribution.
      * @returns {void}
      */
     FormoAnalytics.prototype.reset = function () {
@@ -377,15 +387,11 @@ var FormoAnalytics = /** @class */ (function () {
         // page lifetime, because they fall back to currentAddress. Keep the
         // EVM provider reference so tracking can resume on the next connect.
         this.wallet.reset();
-        cookie().remove(LOCAL_ANONYMOUS_ID_KEY);
         cookie().remove(SESSION_USER_ID_KEY);
         cookie().remove(SESSION_WALLET_DETECTED_KEY);
         cookie().remove(SESSION_WALLET_IDENTIFIED_KEY);
         cookie().remove(ACTIVE_WALLET_KEY);
-        // Stored traffic-source attribution (referrer/UTM) is tracking data;
-        // clear it too so reset()/optOutTracking() don't leave it to be
-        // re-attached to the next session's events.
-        session().remove(SESSION_TRAFFIC_SOURCE_KEY);
+        // Attribution belongs to the visit, so reset preserves it.
     };
     FormoAnalytics.prototype.cleanup = function () {
         this.isCleanedUp = true;
@@ -569,6 +575,12 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.syncWalletState = function (params) {
         this.wallet.syncWalletState(params);
+        this.retryWalletDetection();
+    };
+    FormoAnalytics.prototype.retryWalletDetection = function () {
+        if (this.isCleanedUp)
+            return;
+        void this.evmEvents.detectWallets(this.evmEvents.detectableProviders());
     };
     /** @see WalletStateStore.clearProvider */
     FormoAnalytics.prototype.clearActiveProvider = function () {
@@ -768,6 +780,11 @@ var FormoAnalytics = /** @class */ (function () {
                             return [2 /*return*/];
                         }
                         if (!!params) return [3 /*break*/, 12];
+                        // Wagmi owns wallet identification.
+                        if (this.isWagmiMode) {
+                            logger.info("identify() without params is a no-op in Wagmi mode");
+                            return [2 /*return*/];
+                        }
                         // If no params provided, auto-identify
                         logger.info("Auto-identifying with providers:", this.evm.all.map(function (p) { return p.info.name; }));
                         _i = 0, _a = this.evm.all;
@@ -947,10 +964,8 @@ var FormoAnalytics = /** @class */ (function () {
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        // detect() marks wallet detection (a cookie write) before
-                        // trackEvent's consent check - gate it for a suppressed visitor or
-                        // excluded environment (opt-out / timezone / host / path).
-                        if (this.isTrackingSuppressed()) {
+                        // Apply all policy checks before persisting the detection marker.
+                        if (!this.shouldTrack()) {
                             logger.info("detect() skipped: tracking is suppressed for this visitor or environment");
                             return [2 /*return*/];
                         }
@@ -1012,6 +1027,7 @@ var FormoAnalytics = /** @class */ (function () {
         // Set opt-out flag in persistent storage using direct cookie access
         // This must be done before switching storage to ensure persistence
         setConsentFlag(this.writeKey, CONSENT_OPT_OUT_KEY, "true");
+        this._pageGeneration++;
         // Drop anything already buffered so a pending timer/pagehide flush
         // cannot ship events after consent withdrawal.
         this.eventManager.clear();
@@ -1019,6 +1035,9 @@ var FormoAnalytics = /** @class */ (function () {
         // on opt-in, and nothing else would retry an already-adopted one.
         this.evmEvents.markRegisteredAdoptionsPending();
         this.reset();
+        // Consent withdrawal also clears the browser id and the attribution.
+        clearAnonymousId(LOCAL_ANONYMOUS_ID_KEY);
+        session().remove(SESSION_TRAFFIC_SOURCE_KEY);
         logger.info("Successfully opted out of tracking");
     };
     /**
@@ -1045,11 +1064,9 @@ var FormoAnalytics = /** @class */ (function () {
         logger.info("Opting back into tracking");
         // Remove opt-out flag
         removeConsentFlag(this.writeKey, CONSENT_OPT_OUT_KEY);
-        // A wallet connected while opted out was declined by syncWalletState, and
-        // an unchanged wagmi connection produces no status or chain update to
-        // retry on. Without this, opting back in leaves that wallet invisible for
-        // the rest of the page load.
+        // Retry wallet adoption skipped while opted out.
         (_a = this.wagmiHandler) === null || _a === void 0 ? void 0 : _a.retryAdoption();
+        this.retryWalletDetection();
         logger.info("Successfully opted back into tracking");
     };
     /**
@@ -1130,29 +1147,30 @@ var FormoAnalytics = /** @class */ (function () {
     };
     FormoAnalytics.prototype.trackPageHit = function (category, name, properties, context, callback) {
         return __awaiter(this, void 0, void 0, function () {
+            var canTrack, generation;
             var _this = this;
             return __generator(this, function (_a) {
-                // A route change can end path-based suppression; a provider registered
-                // while suppressed gets its refused session adoption retried here.
-                // Idempotent and cheap when nothing is pending.
-                if (!this.isCleanedUp) {
+                canTrack = this.shouldTrack();
+                if (!this.isCleanedUp && canTrack) {
                     try {
                         this.evmEvents.retryExternalAdoptions();
+                        this.retryWalletDetection();
                     }
                     catch (_b) {
-                        /* never let the retry break a page hit */
+                        // Detection retries must not break page tracking.
                     }
                 }
-                if (!this.shouldTrack()) {
+                if (!canTrack) {
                     logger.info("Track page hit: Skipping event due to tracking configuration");
                     return [2 /*return*/];
                 }
+                generation = this._pageGeneration;
                 setTimeout(function () {
                     // Drop in-flight page hits from an SDK instance that was torn down
                     // between scheduling and firing (e.g. provider remount in React Strict
                     // Mode / HMR). Otherwise the orphan instance would queue a page event
                     // here with its stale, never-populated `currentAddress`.
-                    if (_this._pageHooksDisposed)
+                    if (_this._pageHooksDisposed || generation !== _this._pageGeneration)
                         return;
                     (function () { return __awaiter(_this, void 0, void 0, function () {
                         var e_2;
@@ -1182,7 +1200,7 @@ var FormoAnalytics = /** @class */ (function () {
     };
     FormoAnalytics.prototype.trackEvent = function (type, payload, properties, context, callback) {
         return __awaiter(this, void 0, void 0, function () {
-            var error_1;
+            var error_2;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -1201,8 +1219,8 @@ var FormoAnalytics = /** @class */ (function () {
                         _a.sent();
                         return [3 /*break*/, 3];
                     case 2:
-                        error_1 = _a.sent();
-                        logger.error("Error tracking event:", error_1);
+                        error_2 = _a.sent();
+                        logger.error("Error tracking event:", error_2);
                         return [3 /*break*/, 3];
                     case 3: return [2 /*return*/];
                 }
@@ -1268,7 +1286,9 @@ var FormoAnalytics = /** @class */ (function () {
          */
         get: function () {
             if (!this.solanaManager) {
-                this.solanaManager = new SolanaManager(this);
+                // Only reachable after `solana: false` (or after cleanup). The host
+                // opted out of discovery, so this manager serves the store path only.
+                this.solanaManager = new SolanaManager(this, undefined, false);
             }
             return this.solanaManager;
         },

package/dist/esm/src/FormoAnalyticsProvider.js

@@ -69,6 +69,18 @@ var defaultContext = {
     hasOptedOutTracking: function () { return false; },
 };
 export var FormoAnalyticsContext = createContext(defaultContext);
+var optionObjectIds = new WeakMap();
+var nextOptionObjectId = 1;
+var optionObjectId = function (value) {
+    if (!value)
+        return undefined;
+    var id = optionObjectIds.get(value);
+    if (id === undefined) {
+        id = nextOptionObjectId++;
+        optionObjectIds.set(value, id);
+    }
+    return id;
+};
 /**
  * A stable key over the serializable parts of Options. The provider effect
  * re-initialises the SDK when this key changes; anything that alters SDK
@@ -92,6 +104,14 @@ export var computeOptionsKey = function (options) {
         logger: options.logger,
         referral: options.referral,
         evm: options.evm,
+        // `solana` is a boolean or an options object. A store is a live event
+        // source, so replacing it must reinitialize the SDK even when both the
+        // old and new options contain a store.
+        solana: typeof options.solana === "object" ? undefined : options.solana,
+        solanaStoreId: typeof options.solana === "object"
+            ? optionObjectId(options.solana.store)
+            : undefined,
+        solanaCluster: typeof options.solana === "object" ? options.solana.cluster : undefined,
         // For complex objects, just track their presence, not their content
         hasProvider: !!options.provider,
         hasWagmi: !!options.wagmi,

package/dist/esm/src/event/EventFactory.d.ts

@@ -1,10 +1,16 @@
 import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, Options, SignatureStatus, TransactionStatus } from "../types";
 import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
+    /** Consulted once per event, after the only await in creation. */
+    private readonly canCreate;
     private options?;
     private compiledPathPattern?;
     private excludedQueryParams;
-    constructor(options?: Options);
+    /** Bumped by invalidate(); an event created across a bump is dropped. */
+    private generation;
+    constructor(options?: Options, 
+    /** Consulted once per event, after the only await in creation. */
+    canCreate?: () => boolean);
     /**
      * Validate an address for both EVM and Solana chains.
      * Uses chainId for strict validation when available.
@@ -56,6 +62,8 @@ declare class EventFactory implements IEventFactory {
     private redactStoredTrafficSources;
     private getTrafficSources;
     private getScreen;
+    /** Drop every event still being created. Called on clear() and close(). */
+    invalidate(): void;
     private generateContext;
     /**
      * Add any missing default page properties using values from options and defaults