@formo/analytics 1.36.0 → 1.38.0

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

@@ -96,6 +96,8 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * Call this when destroying the analytics instance
      * @returns {void}
      */
+    /** Set by cleanup(); a torn-down instance refuses new registrations. */
+    private isCleanedUp;
     cleanup(): void;
     /**
      * Emits a connect wallet event.
@@ -373,6 +375,68 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      */
     get solana(): SolanaManager;
     private getCurrentChainId;
+    /**
+     * Track an EIP-1193 provider the page constructed itself.
+     *
+     * Discovery covers EIP-6963 announcements and `window.ethereum`, which is
+     * every injected wallet and nothing else. WalletConnect and Ledger
+     * providers are built by the app (`EthereumProvider.init(...)`) and
+     * announce nothing, so their sessions were invisible: connects,
+     * signatures, and transactions all silently missing. Hand the provider
+     * here once it exists and it takes the exact pipeline a discovered
+     * provider takes - detect event, lifecycle listeners, request wrapper -
+     * and a session that is already live is adopted from the provider's
+     * synchronous state.
+     *
+     * Metadata resolution order: the caller's `info` overrides win; then a
+     * WalletConnect session's peer metadata, which names the REAL wallet on
+     * the far side of the transport (for example "Ledger Live"); then flag
+     * sniffing; then a generic fallback. One deliberate exception: a caller
+     * name of exactly "WalletConnect" is the generic transport name, so the
+     * live peer still replaces it on events - name the provider anything
+     * else to pin it verbatim.
+     *
+     * No-op outside the EIP-1193 path: in wagmi mode the connector system
+     * already tracks these sessions, and wrapping the same provider twice
+     * would double-report every event.
+     *
+     * With several live SDK instances (multi write-key pages) registering
+     * the SAME provider, request-derived events (signatures, transactions)
+     * go to the most recently registered live instance - the same
+     * single-observer semantics discovery has always had for the request
+     * wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * instance. Fanning request observations out to all instances is a
+     * separate feature.
+     *
+     * @returns true when the provider is (now) tracked, false when it was
+     * refused (wagmi mode, EVM disabled, or not a valid EIP-1193 provider).
+     *
+     * @example
+     * ```typescript
+     * const wcProvider = await EthereumProvider.init({ projectId, chains });
+     * formo.registerProvider(wcProvider);
+     * ```
+     */
+    /**
+     * INTERNAL. Install the request wrapper on a wagmi connector's provider.
+     *
+     * Wagmi mode watches the store and caches, which see hook-driven calls
+     * only; imperative viem calls (walletClient.sendTransaction,
+     * .signMessage, .writeContract, raw request) create no mutation and were
+     * silently lost. Every viem client in a wagmi app is built on the
+     * connector's EIP-1193 provider, so wrapping that provider closes the
+     * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
+     * request wrapper installs here. Double counting is prevented in the
+     * wrapper via `shouldSkipRequestCapture`.
+     */
+    _wrapWagmiProvider(provider: EIP1193Provider): void;
+    registerProvider(provider: EIP1193Provider, info?: {
+        name?: string;
+        rdns?: string;
+        icon?: `data:image/${string}`;
+    }): boolean;
+    /** Fallback uuid suffix for platforms without crypto.randomUUID. */
+    private static registeredProviderSeq;
     getTrackedProvidersCount(): number;
     /**
      * Get current provider state for debugging

package/dist/esm/src/FormoAnalytics.js

@@ -57,6 +57,7 @@ import { validateAddress, validateAndChecksumAddress } from "./utils/address";
 import { TrackingPolicy, } from "./tracking/TrackingPolicy";
 import { WalletStateStore } from "./wallet/WalletStateStore";
 import { EvmProviderRegistry } from "./evm/EvmProviderRegistry";
+import { detectInjectedProviderInfo, isValidProvider, readWalletConnectPeer, } from "./provider";
 import { EvmEventTracker } from "./evm/EvmEventTracker";
 import { EvmRequestTracker } from "./evm/EvmRequestTracker";
 import { parseChainId } from "./utils/chain";
@@ -90,6 +91,13 @@ var FormoAnalytics = /** @class */ (function () {
         this._currentUrl = "";
         this._pageHooksDisposed = false;
         this.currentUserId = "";
+        /**
+         * Clean up resources and event listeners
+         * Call this when destroying the analytics instance
+         * @returns {void}
+         */
+        /** Set by cleanup(); a torn-down instance refuses new registrations. */
+        this.isCleanedUp = false;
         this.config = {
             writeKey: writeKey,
         };
@@ -111,6 +119,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.transaction = this.transaction.bind(this);
         this.detect = this.detect.bind(this);
         this.track = this.track.bind(this);
+        this.registerProvider = this.registerProvider.bind(this);
         this.page = this.page.bind(this);
         this.reset = this.reset.bind(this);
         this.cleanup = this.cleanup.bind(this);
@@ -168,6 +177,11 @@ var FormoAnalytics = /** @class */ (function () {
             isAutocaptureEnabled: function (t) { return _this.isAutocaptureEnabled(t); },
             signature: function (params, properties) { return _this.signature(params, properties); },
             transaction: function (params, properties) { return _this.transaction(params, properties); },
+            // Hybrid capture: in wagmi mode the wrapper skips a request that a
+            // PENDING wagmi mutation already covers - the mutation handler
+            // captures it with ABI enrichment - and captures everything else
+            // (imperative viem calls that create no mutation).
+            shouldSkipRequestCapture: function (method, params) { var _a, _b; return (_b = (_a = _this.wagmiHandler) === null || _a === void 0 ? void 0 : _a.hasMatchingPendingMutation(method, params)) !== null && _b !== void 0 ? _b : false; },
         });
         this.evmEvents = new EvmEventTracker(this.wallet, this.evm, {
             isAutocaptureEnabled: function (t) { return _this.isAutocaptureEnabled(t); },
@@ -373,12 +387,8 @@ var FormoAnalytics = /** @class */ (function () {
         // re-attached to the next session's events.
         session().remove(SESSION_TRAFFIC_SOURCE_KEY);
     };
-    /**
-     * Clean up resources and event listeners
-     * Call this when destroying the analytics instance
-     * @returns {void}
-     */
     FormoAnalytics.prototype.cleanup = function () {
+        this.isCleanedUp = true;
         logger.debug("FormoAnalytics: Cleaning up resources");
         // Close the queue, don't just empty it. clear() only drops what is
         // buffered at this instant; asynchronous work already in flight (event
@@ -1014,7 +1024,21 @@ var FormoAnalytics = /** @class */ (function () {
      * @returns {void}
      */
     FormoAnalytics.prototype.optInTracking = function () {
+        var _this = this;
         var _a;
+        // A provider registered while the visitor was opted out had its
+        // session adoption refused; nothing else retries it. Guarded: a
+        // cleanup() racing this timer must not drive the torn-down tracker.
+        setTimeout(function () {
+            if (_this.isCleanedUp)
+                return;
+            try {
+                _this.evmEvents.retryExternalAdoptions();
+            }
+            catch (_a) {
+                /* adoption retry must never break opt-in */
+            }
+        }, 0);
         logger.info("Opting back into tracking");
         // Remove opt-out flag
         removeConsentFlag(this.writeKey, CONSENT_OPT_OUT_KEY);
@@ -1105,6 +1129,17 @@ var FormoAnalytics = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             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) {
+                    try {
+                        this.evmEvents.retryExternalAdoptions();
+                    }
+                    catch (_b) {
+                        /* never let the retry break a page hit */
+                    }
+                }
                 if (!this.shouldTrack()) {
                     logger.info("Track page hit: Skipping event due to tracking configuration");
                     return [2 /*return*/];
@@ -1272,6 +1307,119 @@ var FormoAnalytics = /** @class */ (function () {
     };
     // Explicitly untrack a provider: remove listeners, clear wrapper flag
     // and tracking
+    /**
+     * Track an EIP-1193 provider the page constructed itself.
+     *
+     * Discovery covers EIP-6963 announcements and `window.ethereum`, which is
+     * every injected wallet and nothing else. WalletConnect and Ledger
+     * providers are built by the app (`EthereumProvider.init(...)`) and
+     * announce nothing, so their sessions were invisible: connects,
+     * signatures, and transactions all silently missing. Hand the provider
+     * here once it exists and it takes the exact pipeline a discovered
+     * provider takes - detect event, lifecycle listeners, request wrapper -
+     * and a session that is already live is adopted from the provider's
+     * synchronous state.
+     *
+     * Metadata resolution order: the caller's `info` overrides win; then a
+     * WalletConnect session's peer metadata, which names the REAL wallet on
+     * the far side of the transport (for example "Ledger Live"); then flag
+     * sniffing; then a generic fallback. One deliberate exception: a caller
+     * name of exactly "WalletConnect" is the generic transport name, so the
+     * live peer still replaces it on events - name the provider anything
+     * else to pin it verbatim.
+     *
+     * No-op outside the EIP-1193 path: in wagmi mode the connector system
+     * already tracks these sessions, and wrapping the same provider twice
+     * would double-report every event.
+     *
+     * With several live SDK instances (multi write-key pages) registering
+     * the SAME provider, request-derived events (signatures, transactions)
+     * go to the most recently registered live instance - the same
+     * single-observer semantics discovery has always had for the request
+     * wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * instance. Fanning request observations out to all instances is a
+     * separate feature.
+     *
+     * @returns true when the provider is (now) tracked, false when it was
+     * refused (wagmi mode, EVM disabled, or not a valid EIP-1193 provider).
+     *
+     * @example
+     * ```typescript
+     * const wcProvider = await EthereumProvider.init({ projectId, chains });
+     * formo.registerProvider(wcProvider);
+     * ```
+     */
+    /**
+     * INTERNAL. Install the request wrapper on a wagmi connector's provider.
+     *
+     * Wagmi mode watches the store and caches, which see hook-driven calls
+     * only; imperative viem calls (walletClient.sendTransaction,
+     * .signMessage, .writeContract, raw request) create no mutation and were
+     * silently lost. Every viem client in a wagmi app is built on the
+     * connector's EIP-1193 provider, so wrapping that provider closes the
+     * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
+     * request wrapper installs here. Double counting is prevented in the
+     * wrapper via `shouldSkipRequestCapture`.
+     */
+    FormoAnalytics.prototype._wrapWagmiProvider = function (provider) {
+        if (this.isCleanedUp || !isValidProvider(provider))
+            return;
+        try {
+            this.evmRequests.registerRequestListeners(provider);
+        }
+        catch (e) {
+            logger.warn("Failed to wrap wagmi provider for hybrid capture", e);
+        }
+    };
+    FormoAnalytics.prototype.registerProvider = function (provider, info) {
+        var _a, _b, _c;
+        if (this.isCleanedUp) {
+            // Cleanup terminally closed the event queue; listeners attached now
+            // would hold this instance forever and deliver nothing.
+            logger.warn("registerProvider: instance is cleaned up; refusing");
+            return false;
+        }
+        if (this.isEvmDisabled) {
+            logger.warn("registerProvider: EVM tracking is disabled; refusing");
+            return false;
+        }
+        if (this.isWagmiMode) {
+            logger.warn("registerProvider: wagmi mode tracks connectors already; registering the provider here would double-report its events. Refusing.");
+            return false;
+        }
+        if (!isValidProvider(provider)) {
+            logger.warn("registerProvider: not a valid EIP-1193 provider; refusing");
+            return false;
+        }
+        var detected = detectInjectedProviderInfo(provider);
+        var peer = readWalletConnectPeer(provider);
+        // A live peer identifies the session as WalletConnect even when the
+        // provider carries no isWalletConnect flag (v2 providers often do not).
+        var rdns = (_a = info === null || info === void 0 ? void 0 : info.rdns) !== null && _a !== void 0 ? _a : (peer && detected.rdns === "io.injected.provider"
+            ? "com.walletconnect"
+            : detected.rdns);
+        // The peer name is deliberately NOT stored: sessions change wallets,
+        // and metadata frozen at registration would misname every later one.
+        // `infoFor` resolves the peer live on each read, over the generic
+        // transport name; a caller's explicit name still wins everywhere.
+        var name = (_b = info === null || info === void 0 ? void 0 : info.name) !== null && _b !== void 0 ? _b : (peer ? "WalletConnect" : detected.name);
+        // Per-instance uuid: EIP-6963 consumers (mipd included) deduplicate on
+        // it, so two registered instances sharing an rdns-derived uuid would
+        // collapse into one. Random when the platform provides it; a
+        // monotonic suffix otherwise.
+        var uuid = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+            ? crypto.randomUUID()
+            : "registered-".concat(rdns.replace(/[^a-zA-Z0-9]/g, "-"), "-").concat((FormoAnalytics.registeredProviderSeq += 1));
+        return this.evmEvents.adoptExternalProvider({
+            info: {
+                name: name,
+                rdns: rdns,
+                uuid: uuid,
+                icon: (_c = info === null || info === void 0 ? void 0 : info.icon) !== null && _c !== void 0 ? _c : detected.icon,
+            },
+            provider: provider,
+        });
+    };
     // Debug/monitoring helpers
     FormoAnalytics.prototype.getTrackedProvidersCount = function () {
         return this.evm.counts.trackedProviders;
@@ -1283,6 +1431,8 @@ var FormoAnalytics = /** @class */ (function () {
     FormoAnalytics.prototype.getProviderState = function () {
         return __assign(__assign({}, this.evm.counts), { activeProvider: !!this._provider });
     };
+    /** Fallback uuid suffix for platforms without crypto.randomUUID. */
+    FormoAnalytics.registeredProviderSeq = 0;
     return FormoAnalytics;
 }());
 export { FormoAnalytics };

package/dist/esm/src/FormoAnalyticsProvider.js

@@ -55,6 +55,7 @@ var defaultContext = {
     page: function () { return Promise.resolve(); },
     reset: function () { },
     cleanup: function () { },
+    registerProvider: function () { return false; },
     detect: function () { return Promise.resolve(); },
     connect: function () { return Promise.resolve(); },
     disconnect: function () { return Promise.resolve(); },

package/dist/esm/src/evm/EvmEventTracker.d.ts

@@ -43,20 +43,19 @@ export interface EvmEventTrackerDeps {
      */
     registerRequestListeners(provider: EIP1193Provider): boolean;
 }
-/**
- * The EIP-1193 side of wallet tracking: which providers to watch, and what
- * their events mean.
- *
- * Split out of `FormoAnalytics` (#336). It holds no wallet state and no
- * provider registry of its own - those have owners already - so what is left
- * here is the part that is genuinely about interpreting wallet events:
- * deciding when a connect has to be reported, when a switch is stale, and
- * when a provider has stopped being the one we follow.
- */
 export declare class EvmEventTracker {
     private readonly wallet;
     private readonly registry;
     private readonly deps;
+    /**
+     * Providers adopted through `registerProvider` rather than discovered.
+     * Announcement-driven cleanup must not touch them: they are never in an
+     * announcement list, so "missing from the announcement" is their normal
+     * state, not evidence of removal. A Set rather than a WeakSet because
+     * suppressed adoptions retry from it; the registry holds these providers
+     * strongly anyway, and untrack removes them.
+     */
+    private externallyRegistered;
     /**
      * The connect this SDK has already reported for a provider.
      *
@@ -91,6 +90,35 @@ export declare class EvmEventTracker {
      */
     trackEIP1193Provider(provider: EIP1193Provider): void;
     trackProviders(providers: readonly EIP6963ProviderDetail[]): void;
+    /**
+     * Adopt a provider the page constructed rather than announced.
+     *
+     * Discovery only ever sees EIP-6963 announcements and `window.ethereum`.
+     * A WalletConnect or Ledger provider is a constructed object that does
+     * neither, so without this entry point its whole session is invisible -
+     * the P-2403 gap. The pipeline from here on is the same one every
+     * discovered provider takes: registry, detect event, listeners, request
+     * wrapper.
+     *
+     * A session that already exists at registration is seeded from the
+     * provider's SYNCHRONOUS `accounts` state (WalletConnect exposes it), via
+     * the same accounts-arrival path a live `accountsChanged` takes. No RPC:
+     * nothing analytics-only may go on a wallet's transport, and
+     * WalletConnect's serialised relay socket is the very case that rule
+     * exists for.
+     */
+    adoptExternalProvider(detail: EIP6963ProviderDetail): boolean;
+    /**
+     * Re-run session adoption for every registered external provider.
+     *
+     * Registration while tracking was suppressed (opt-out, excluded route)
+     * reached the adoption path and was refused - and a provider whose
+     * session already exists may never emit another accountsChanged, so
+     * nothing would ever retry. Called when suppression can have ended
+     * (opt-in, page navigation). Idempotent: an already-adopted wallet is
+     * deduplicated by the same state and markers as any repeated signal.
+     */
+    retryExternalAdoptions(): void;
     private registerAccountsChangedListener;
     private onAccountsChanged;
     /**

package/dist/esm/src/evm/EvmEventTracker.js

@@ -1,3 +1,14 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -34,11 +45,20 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 import { createStore } from "mipd";
 import { logger } from "../logger";
 import { parseChainId } from "../utils/chain";
 import { validateAndChecksumAddress } from "../utils/address";
-import { detectInjectedProviderInfo, isValidProvider } from "../provider";
+import { detectInjectedProviderInfo, isValidProvider, DEFAULT_PROVIDER_ICON } from "../provider";
 /** Why the tracker moved the active slot to another provider. Log copy. */
 var PROVIDER_SWITCH_REASONS = {
     ADDRESS_MISMATCH: "Address mismatch indicates wallet switch",
@@ -55,11 +75,71 @@ var PROVIDER_SWITCH_REASONS = {
  * deciding when a connect has to be reported, when a switch is stale, and
  * when a provider has stopped being the one we follow.
  */
+/**
+ * A registered provider's current accounts, from its synchronous state.
+ *
+ * `provider.accounts` first - but a LIVE MetaMask Mobile session over
+ * WalletConnect has been observed with `accounts` EMPTY while the session's
+ * namespaces held the approved account ("eip155:11155111:0xabc..."), which
+ * silently defeated adoption. The namespaces are the session's ground
+ * truth, so they are the fallback. Still purely synchronous property
+ * reads; nothing goes on the wallet transport.
+ */
+function readProviderAccounts(provider) {
+    var _a;
+    var direct = provider.accounts;
+    if (Array.isArray(direct) &&
+        direct.length > 0 &&
+        direct.every(function (a) { return typeof a === "string"; })) {
+        return direct;
+    }
+    var session = provider.session;
+    // eip155 ONLY: a session can also carry Solana or other namespaces, and
+    // feeding a non-EVM address into the EVM adoption path would make
+    // validation reject it and drop the whole adoption. A session can also
+    // authorize DIFFERENT accounts per chain, so entries for the provider's
+    // active chain come first - the adopted address should be the one this
+    // chain actually authorized.
+    var ns = (_a = session === null || session === void 0 ? void 0 : session.namespaces) === null || _a === void 0 ? void 0 : _a.eip155;
+    var chainId = provider.chainId;
+    var parsed = typeof chainId === "number"
+        ? chainId
+        : typeof chainId === "string"
+            ? parseChainId(chainId)
+            : undefined;
+    var activePrefix = parsed ? "eip155:".concat(parsed, ":") : undefined;
+    var forChain = [];
+    var others = [];
+    if (Array.isArray(ns === null || ns === void 0 ? void 0 : ns.accounts)) {
+        for (var _i = 0, _b = ns.accounts; _i < _b.length; _i++) {
+            var entry = _b[_i];
+            if (typeof entry !== "string" || !entry.startsWith("eip155:"))
+                continue;
+            var address = entry.split(":")[2];
+            if (!address)
+                continue;
+            var bucket = activePrefix && entry.startsWith(activePrefix) ? forChain : others;
+            if (!bucket.includes(address))
+                bucket.push(address);
+        }
+    }
+    var out = __spreadArray(__spreadArray([], forChain, true), others.filter(function (a) { return !forChain.includes(a); }), true);
+    return out;
+}
 var EvmEventTracker = /** @class */ (function () {
     function EvmEventTracker(wallet, registry, deps) {
         this.wallet = wallet;
         this.registry = registry;
         this.deps = deps;
+        /**
+         * Providers adopted through `registerProvider` rather than discovered.
+         * Announcement-driven cleanup must not touch them: they are never in an
+         * announcement list, so "missing from the announcement" is their normal
+         * state, not evidence of removal. A Set rather than a WeakSet because
+         * suppressed adoptions retry from it; the registry holds these providers
+         * strongly anyway, and untrack removes them.
+         */
+        this.externallyRegistered = new Set();
         /**
          * The connect this SDK has already reported for a provider.
          *
@@ -187,6 +267,103 @@ var EvmEventTracker = /** @class */ (function () {
             logger.error("Failed to track EIP-6963 providers during initialization:", error);
         }
     };
+    /**
+     * Adopt a provider the page constructed rather than announced.
+     *
+     * Discovery only ever sees EIP-6963 announcements and `window.ethereum`.
+     * A WalletConnect or Ledger provider is a constructed object that does
+     * neither, so without this entry point its whole session is invisible -
+     * the P-2403 gap. The pipeline from here on is the same one every
+     * discovered provider takes: registry, detect event, listeners, request
+     * wrapper.
+     *
+     * A session that already exists at registration is seeded from the
+     * provider's SYNCHRONOUS `accounts` state (WalletConnect exposes it), via
+     * the same accounts-arrival path a live `accountsChanged` takes. No RPC:
+     * nothing analytics-only may go on a wallet's transport, and
+     * WalletConnect's serialised relay socket is the very case that rule
+     * exists for.
+     */
+    EvmEventTracker.prototype.adoptExternalProvider = function (detail) {
+        var provider = detail.provider;
+        // Exempt from announcement-driven cleanup BEFORE tracking: a registered
+        // provider is never in an EIP-6963 announcement, so without this the
+        // next wallet announcement would untrack it and its events would stop.
+        this.externallyRegistered.add(provider);
+        this.registry.add(detail);
+        this.trackProviders([detail]);
+        // Adoption and success both hinge on the wrapper actually installing:
+        // reporting success for a provider whose requests stay invisible would
+        // recreate the silent loss this API exists to close.
+        if (!this.registry.isTracked(provider)) {
+            this.externallyRegistered.delete(provider);
+            // Tracking got partway: lifecycle listeners may already be attached
+            // even though the request wrapper failed. Leaving them would leak
+            // callbacks that hold this instance for the life of the page.
+            this.untrackProvider(provider);
+            logger.warn("adoptExternalProvider: provider could not be tracked");
+            return false;
+        }
+        // A provider that was ALREADY tracked skips the pipeline above, and
+        // "tracked" means lifecycle listeners - it says nothing about the
+        // request wrapper, which a wallet can have replaced since. Re-verify
+        // it on every registration: the call reinstalls a displaced wrapper,
+        // rebinds ownership of an intact one, and refuses when it cannot -
+        // and success here must mean capture actually works.
+        if (!this.deps.registerRequestListeners(provider)) {
+            this.externallyRegistered.delete(provider);
+            this.untrackProvider(provider);
+            logger.warn("adoptExternalProvider: request wrapper could not be ensured");
+            return false;
+        }
+        // Detect with the LIVE name (peer-resolved when a session exists);
+        // the stored metadata stays generic so later sessions rename freely.
+        void this.detectWallets([
+            __assign(__assign({}, detail), { info: __assign(__assign({}, detail.info), this.registry.infoFor(provider)) }),
+        ]);
+        var accounts = readProviderAccounts(provider);
+        if (accounts.length > 0) {
+            void this.onAccountsChanged(provider, accounts);
+        }
+        return true;
+    };
+    /**
+     * Re-run session adoption for every registered external provider.
+     *
+     * Registration while tracking was suppressed (opt-out, excluded route)
+     * reached the adoption path and was refused - and a provider whose
+     * session already exists may never emit another accountsChanged, so
+     * nothing would ever retry. Called when suppression can have ended
+     * (opt-in, page navigation). Idempotent: an already-adopted wallet is
+     * deduplicated by the same state and markers as any repeated signal.
+     */
+    EvmEventTracker.prototype.retryExternalAdoptions = function () {
+        var _this = this;
+        this.externallyRegistered.forEach(function (provider) {
+            // A flagless provider registered BEFORE pairing detected as the
+            // generic injected identity; once the session's peer exists, the
+            // live identity differs and the corrected detect fires. The
+            // session-scoped rdns dedup keeps this from repeating.
+            var live = _this.registry.infoFor(provider);
+            if (live.rdns === "com.walletconnect") {
+                void _this.detectWallets([
+                    {
+                        info: {
+                            name: live.name,
+                            rdns: live.rdns,
+                            uuid: "corrected-com-walletconnect",
+                            icon: DEFAULT_PROVIDER_ICON,
+                        },
+                        provider: provider,
+                    },
+                ]);
+            }
+            var accounts = readProviderAccounts(provider);
+            if (accounts.length > 0) {
+                void _this.onAccountsChanged(provider, accounts);
+            }
+        });
+    };
     EvmEventTracker.prototype.registerAccountsChangedListener = function (provider) {
         var _this = this;
         logger.info("registerAccountsChangedListener");
@@ -1001,6 +1178,11 @@ var EvmEventTracker = /** @class */ (function () {
         var currentProviderInstances = new Set(current.map(function (detail) { return detail.provider; }));
         for (var _i = 0, _a = this.registry.trackedProviders(); _i < _a.length; _i++) {
             var provider = _a[_i];
+            // A registered external provider is never announced over EIP-6963;
+            // its absence from an announcement list says nothing about it.
+            if (this.externallyRegistered.has(provider)) {
+                continue;
+            }
             if (!currentProviderInstances.has(provider)) {
                 logger.info("Cleaning up unavailable provider: ".concat(provider.constructor.name));
                 this.untrackProvider(provider);

package/dist/esm/src/evm/EvmProviderRegistry.js

@@ -45,7 +45,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 import { logger } from "../logger";
 import { validateAndChecksumAddress } from "../utils/address";
-import { detectInjectedProviderInfo } from "../provider";
+import { detectInjectedProviderInfo, readWalletConnectPeer } from "../provider";
 import { WRAPPED_REQUEST_SYMBOL, WRAPPED_REQUEST_REF_SYMBOL, } from "../types";
 /**
  * Which EVM wallets exist, and what is known about each.
@@ -140,11 +140,33 @@ var EvmProviderRegistry = /** @class */ (function () {
      */
     EvmProviderRegistry.prototype.infoFor = function (provider) {
         var announced = this.details.find(function (p) { return p.provider === provider; });
-        if (announced) {
-            return { name: announced.info.name, rdns: announced.info.rdns };
+        var info = announced
+            ? { name: announced.info.name, rdns: announced.info.rdns }
+            : (function () {
+                var injected = detectInjectedProviderInfo(provider);
+                return { name: injected.name, rdns: injected.rdns };
+            })();
+        // WalletConnect names the TRANSPORT; the session's peer names the
+        // wallet. Resolved live, per read: a session established after the
+        // provider was registered still gets its signer's name onto every
+        // event from then on. Only GENERIC names are replaced - a caller who
+        // registered an explicit display name keeps it. "Injected Provider"
+        // is included because a flagless WalletConnect-compatible provider
+        // registered BEFORE its session exists detects as nothing at all;
+        // the peer appearing later is itself the proof of what it was, so
+        // the rdns upgrades with it.
+        if (info.name === "WalletConnect" || info.name === "Injected Provider") {
+            var peer = readWalletConnectPeer(provider);
+            if (peer === null || peer === void 0 ? void 0 : peer.name) {
+                return {
+                    name: peer.name,
+                    rdns: info.rdns === "io.injected.provider"
+                        ? "com.walletconnect"
+                        : info.rdns,
+                };
+            }
         }
-        var injected = detectInjectedProviderInfo(provider);
-        return { name: injected.name, rdns: injected.rdns };
+        return info;
     };
     // ── listener bookkeeping ─────────────────────────────────────────────────
     EvmProviderRegistry.prototype.addListener = function (provider, event, listener) {