@multiplatform.one/web3 6.0.4 → 6.3.0

package/src/connectkit/connectors/embeddedDesktop.ts

@@ -0,0 +1,46 @@
+/**
+ * Tauri (and similar) desktop shells load the *web* bundle inside a native
+ * WebView. Browser extensions never inject there, so MetaMask must use the SDK
+ * remote/QR path — never `window.location.href = metamask://…`, which would
+ * navigate the whole WebView away from the app.
+ *
+ * Intentionally does NOT flip `@multiplatform.one/platform` `isTauri`: the web
+ * bundle running in Tauri currently keeps web platform flags (better-auth
+ * session, etc.). Wallet code detects the shell locally via `__TAURI*`.
+ */
+
+export function isEmbeddedDesktopWebview(
+  win: Window & {
+    __TAURI_INTERNALS__?: unknown;
+    __TAURI__?: unknown;
+  } = typeof window !== "undefined" ? window : (undefined as never),
+): boolean {
+  if (typeof win === "undefined" || !win) return false;
+  return !!(win.__TAURI_INTERNALS__ || win.__TAURI__);
+}
+
+export type MetaMaskEmbeddedDesktopOptions = {
+  /** Prefer https://metamask.app.link over metamask:// in the QR payload. */
+  useDeeplink: false;
+  /** Suppress SDK InstallModal custom-elements (WKWebView-hostile); ConnectKit renders QR. */
+  headless: true;
+  /**
+   * Never assign location.href for custom schemes. https universal links may
+   * open in the system browser via window.open; custom schemes are ignored.
+   */
+  openDeeplink: (url: string) => void;
+};
+
+/** MetaMask SDK options that are safe inside Tauri/WebView2/WKWebView. */
+export function metaMaskOptionsForEmbeddedDesktop(): MetaMaskEmbeddedDesktopOptions {
+  return {
+    useDeeplink: false,
+    headless: true,
+    openDeeplink: (url: string) => {
+      if (typeof window === "undefined") return;
+      // Custom schemes (metamask://) must not navigate the WebView.
+      if (!/^https?:\/\//i.test(url)) return;
+      window.open(url, "_blank", "noopener,noreferrer");
+    },
+  };
+}

package/src/connectkit/connectors/metaMaskSdkConnector.ts

@@ -0,0 +1,505 @@
+// wagmi connector for MetaMask over the CLASSIC @metamask/sdk (0.33.x) transport,
+// ported from @wagmi/connectors@5.11.2 src/metaMask.ts onto wagmi 3's connector API.
+//
+// Why not @wagmi/connectors 8.x's metaMask() (MWP / @metamask/connect-evm): MWP has
+// no story for the dapp page freezing or being discarded while the wallet app is
+// foregrounded — on Android the tab's relay websocket dies mid-handshake and the
+// wallet's approval publishes to a channel nobody re-reads, so mobile-browser
+// deeplink connects never complete (verified on-device 2026-07-15 against both
+// connect-evm 1.4.0 and 2.1.1). The classic SDK survives that same bounce by
+// design: it persists channel keys, reconnects its own socket.io relay, and
+// re-requests pending results on resume — the promanager keycloak login uses it
+// and is e2e-verified on real Android MetaMask.
+//
+// Kept identical to upstream where possible; the id stays `metaMaskSDK`, which is
+// what isMetaMaskConnector(), useWallets' EIP-6963 dedupe, and ConnectWithInjector's
+// display_uri deeplink listener all key off.
+import type { MetaMaskSDK, MetaMaskSDKOptions, RPC_URLS_MAP, SDKProvider } from "@metamask/sdk";
+import {
+  ChainNotConfiguredError,
+  type Connector,
+  createConnector,
+  extractRpcUrls,
+  ProviderNotFoundError,
+} from "@wagmi/core";
+import type {
+  Compute,
+  ExactPartial,
+  OneOf,
+  RemoveUndefined,
+  UnionCompute,
+} from "@wagmi/core/internal";
+import {
+  type AddEthereumChainParameter,
+  type Address,
+  getAddress,
+  type Hex,
+  hexToNumber,
+  numberToHex,
+  type ProviderConnectInfo,
+  type ProviderRpcError,
+  ResourceUnavailableRpcError,
+  type RpcError,
+  SwitchChainError,
+  UserRejectedRequestError,
+  withRetry,
+  withTimeout,
+} from "viem";
+
+export type MetaMaskSdkParameters = UnionCompute<
+  WagmiMetaMaskSDKOptions &
+    OneOf<
+      | {
+          /* Shortcut to connect and sign a message */
+          connectAndSign?: string | undefined;
+        }
+      | {
+          /* Allow `connectWith` any rpc method */
+          connectWith?: { method: string; params: unknown[] } | undefined;
+        }
+    >
+>;
+
+type WagmiMetaMaskSDKOptions = Compute<
+  ExactPartial<
+    Omit<
+      MetaMaskSDKOptions,
+      | "_source"
+      | "forceDeleteProvider"
+      | "forceInjectProvider"
+      | "injectProvider"
+      | "useDeeplink"
+      | "readonlyRPCMap"
+    >
+  > & {
+    /** @deprecated */
+    forceDeleteProvider?: MetaMaskSDKOptions["forceDeleteProvider"];
+    /** @deprecated */
+    forceInjectProvider?: MetaMaskSDKOptions["forceInjectProvider"];
+    /** @deprecated */
+    injectProvider?: MetaMaskSDKOptions["injectProvider"];
+    /** @deprecated */
+    useDeeplink?: MetaMaskSDKOptions["useDeeplink"];
+  }
+>;
+
+metaMaskSdk.type = "metaMask" as const;
+export function metaMaskSdk(parameters: MetaMaskSdkParameters = {}) {
+  type Provider = SDKProvider;
+  type Properties = {
+    onConnect(connectInfo: ProviderConnectInfo): void;
+    onDisplayUri(uri: string): void;
+  };
+  type Listener = Parameters<Provider["on"]>[1];
+
+  let sdk: MetaMaskSDK;
+  let provider: Provider | undefined;
+  let providerPromise: Promise<typeof provider>;
+
+  let accountsChanged: Connector["onAccountsChanged"] | undefined;
+  let chainChanged: Connector["onChainChanged"] | undefined;
+  let connect: Connector["onConnect"] | undefined;
+  let displayUri: ((uri: string) => void) | undefined;
+  let disconnect: Connector["onDisconnect"] | undefined;
+
+  return createConnector<Provider, Properties>((config) => ({
+    id: "metaMaskSDK",
+    name: "MetaMask",
+    rdns: ["io.metamask", "io.metamask.mobile"],
+    type: metaMaskSdk.type,
+    async setup() {
+      const provider = await this.getProvider();
+      if (provider?.on) {
+        if (!connect) {
+          connect = this.onConnect.bind(this);
+          provider.on("connect", connect as Listener);
+        }
+
+        // Some wallets, like MetaMask, do not implement the `'connect'` event and
+        // overload `'accountsChanged'` instead.
+        if (!accountsChanged) {
+          accountsChanged = this.onAccountsChanged.bind(this);
+          provider.on("accountsChanged", accountsChanged as Listener);
+        }
+      }
+    },
+    async connect({ chainId, isReconnecting, withCapabilities } = {}) {
+      const provider = await this.getProvider();
+      if (!displayUri) {
+        displayUri = this.onDisplayUri;
+        provider.on("display_uri", displayUri as Listener);
+      }
+
+      let accounts: readonly Address[] = [];
+      if (isReconnecting) accounts = await this.getAccounts().catch(() => []);
+
+      try {
+        let signResponse: string | undefined;
+        let connectWithResponse: unknown | undefined;
+        if (!accounts?.length) {
+          if (parameters.connectAndSign || parameters.connectWith) {
+            if (parameters.connectAndSign)
+              signResponse = await sdk.connectAndSign({
+                msg: parameters.connectAndSign,
+              });
+            else if (parameters.connectWith)
+              connectWithResponse = await sdk.connectWith({
+                method: parameters.connectWith.method,
+                params: parameters.connectWith.params,
+              });
+
+            accounts = await this.getAccounts();
+          } else {
+            const requestedAccounts = (await sdk.connect()) as string[];
+            accounts = requestedAccounts.map((x) => getAddress(x));
+          }
+        }
+        // Switch to chain if provided
+        let currentChainId = (await this.getChainId()) as number;
+        if (chainId && currentChainId !== chainId) {
+          const chain = await this.switchChain!({ chainId }).catch((error) => {
+            if (error.code === UserRejectedRequestError.code) throw error;
+            return { id: currentChainId };
+          });
+          currentChainId = chain?.id ?? currentChainId;
+        }
+
+        if (displayUri) {
+          provider.removeListener("display_uri", displayUri);
+          displayUri = undefined;
+        }
+
+        if (signResponse)
+          provider.emit("connectAndSign", {
+            accounts,
+            chainId: currentChainId,
+            signResponse,
+          });
+        else if (connectWithResponse)
+          provider.emit("connectWith", {
+            accounts,
+            chainId: currentChainId,
+            connectWithResponse,
+          });
+
+        // Manage EIP-1193 event listeners
+        // https://eips.ethereum.org/EIPS/eip-1193#events
+        if (connect) {
+          provider.removeListener("connect", connect);
+          connect = undefined;
+        }
+        if (!accountsChanged) {
+          accountsChanged = this.onAccountsChanged.bind(this);
+          provider.on("accountsChanged", accountsChanged as Listener);
+        }
+        if (!chainChanged) {
+          chainChanged = this.onChainChanged.bind(this);
+          provider.on("chainChanged", chainChanged as Listener);
+        }
+        if (!disconnect) {
+          disconnect = this.onDisconnect.bind(this);
+          provider.on("disconnect", disconnect as Listener);
+        }
+
+        return {
+          accounts: (withCapabilities
+            ? accounts.map((address) => ({ address, capabilities: {} }))
+            : accounts) as never,
+          chainId: currentChainId,
+        };
+      } catch (err) {
+        const error = err as RpcError;
+        if (error.code === UserRejectedRequestError.code) throw new UserRejectedRequestError(error);
+        if (error.code === ResourceUnavailableRpcError.code)
+          throw new ResourceUnavailableRpcError(error);
+        throw error;
+      }
+    },
+    async disconnect() {
+      const provider = await this.getProvider();
+
+      // Manage EIP-1193 event listeners
+      if (chainChanged) {
+        provider.removeListener("chainChanged", chainChanged);
+        chainChanged = undefined;
+      }
+      if (disconnect) {
+        provider.removeListener("disconnect", disconnect);
+        disconnect = undefined;
+      }
+      if (!connect) {
+        connect = this.onConnect.bind(this);
+        provider.on("connect", connect as Listener);
+      }
+
+      await sdk.terminate();
+    },
+    async getAccounts() {
+      const provider = await this.getProvider();
+      const accounts = (await provider.request({
+        method: "eth_accounts",
+      })) as string[];
+      return accounts.map((x) => getAddress(x));
+    },
+    async getChainId() {
+      const provider = await this.getProvider();
+      const chainId = provider.getChainId() || (await provider?.request({ method: "eth_chainId" }));
+      return Number(chainId);
+    },
+    async getProvider() {
+      async function initProvider() {
+        // Unwrapping import for Vite compatibility.
+        // See: https://github.com/vitejs/vite/issues/9703
+        const MetaMaskSDK = await (async () => {
+          const { default: SDK } = (await import("@metamask/sdk")) as any; // CJS/ESM interop unwrap
+          if (typeof SDK !== "function" && typeof SDK.default === "function")
+            return SDK.default as typeof import("@metamask/sdk").MetaMaskSDK;
+          return SDK as typeof import("@metamask/sdk").MetaMaskSDK;
+        })();
+
+        const readonlyRPCMap: RPC_URLS_MAP = {};
+        for (const chain of config.chains)
+          readonlyRPCMap[numberToHex(chain.id)] = extractRpcUrls({
+            chain,
+            transports: config.transports,
+          })?.[0];
+
+        sdk = new MetaMaskSDK({
+          _source: "wagmi",
+          forceDeleteProvider: false,
+          forceInjectProvider: false,
+          injectProvider: false,
+          // Workaround cast since MetaMask SDK does not support `'exactOptionalPropertyTypes'`
+          ...(parameters as RemoveUndefined<typeof parameters>),
+          readonlyRPCMap,
+          dappMetadata: {
+            ...parameters.dappMetadata,
+            name: parameters.dappMetadata?.name ? parameters.dappMetadata?.name : "wagmi",
+            url: parameters.dappMetadata?.url
+              ? parameters.dappMetadata?.url
+              : typeof window !== "undefined"
+                ? window.location.origin
+                : "https://wagmi.sh",
+          },
+          useDeeplink: parameters.useDeeplink ?? true,
+        });
+        const result = await sdk.init();
+        // On initial load, sometimes `sdk.getProvider` does not return provider.
+        // https://github.com/wevm/wagmi/issues/4367
+        const provider = (() => {
+          if (result?.activeProvider) return result.activeProvider;
+          return sdk.getProvider();
+        })();
+        if (!provider) throw new ProviderNotFoundError();
+        return provider;
+      }
+
+      if (!provider) {
+        if (!providerPromise) providerPromise = initProvider();
+        provider = await providerPromise;
+      }
+      return provider!;
+    },
+    async isAuthorized() {
+      try {
+        // MetaMask mobile provider sometimes fails to immediately resolve
+        // JSON-RPC requests on page load
+        const timeout = 200;
+        const accounts = await withRetry(() => withTimeout(() => this.getAccounts(), { timeout }), {
+          delay: timeout + 1,
+          retryCount: 3,
+        });
+        return !!accounts.length;
+      } catch {
+        return false;
+      }
+    },
+    async switchChain({ addEthereumChainParameter, chainId }) {
+      const provider = await this.getProvider();
+
+      const chain = config.chains.find((x) => x.id === chainId);
+      if (!chain) throw new SwitchChainError(new ChainNotConfiguredError());
+
+      try {
+        await provider.request({
+          method: "wallet_switchEthereumChain",
+          params: [{ chainId: numberToHex(chainId) }],
+        });
+
+        // During `'wallet_switchEthereumChain'`, MetaMask makes a `'net_version'` RPC
+        // call to the target chain. If this request fails, MetaMask does not emit the
+        // `'chainChanged'` event, but will still switch the chain.
+        // https://github.com/MetaMask/metamask-extension/issues/24247
+        await waitForChainIdToSync();
+        await sendAndWaitForChangeEvent(chainId);
+
+        return chain;
+      } catch (err) {
+        const error = err as RpcError;
+
+        if (error.code === UserRejectedRequestError.code) throw new UserRejectedRequestError(error);
+
+        // Indicates chain is not added to provider
+        if (
+          error.code === 4902 ||
+          // Unwrapping for MetaMask Mobile
+          // https://github.com/MetaMask/metamask-mobile/issues/2944#issuecomment-976988719
+          (error as ProviderRpcError<{ originalError?: { code: number } }>)?.data?.originalError
+            ?.code === 4902
+        ) {
+          try {
+            await provider.request({
+              method: "wallet_addEthereumChain",
+              params: [
+                {
+                  blockExplorerUrls: (() => {
+                    const { default: blockExplorer, ...blockExplorers } =
+                      chain.blockExplorers ?? {};
+                    if (addEthereumChainParameter?.blockExplorerUrls)
+                      return addEthereumChainParameter.blockExplorerUrls;
+                    if (blockExplorer)
+                      return [
+                        blockExplorer.url,
+                        ...Object.values(blockExplorers).map((x) => x.url),
+                      ];
+                    return;
+                  })(),
+                  chainId: numberToHex(chainId),
+                  chainName: addEthereumChainParameter?.chainName ?? chain.name,
+                  iconUrls: addEthereumChainParameter?.iconUrls,
+                  nativeCurrency: addEthereumChainParameter?.nativeCurrency ?? chain.nativeCurrency,
+                  rpcUrls: (() => {
+                    if (addEthereumChainParameter?.rpcUrls?.length)
+                      return addEthereumChainParameter.rpcUrls;
+                    return [chain.rpcUrls.default?.http[0] ?? ""];
+                  })(),
+                } satisfies AddEthereumChainParameter,
+              ],
+            });
+
+            await waitForChainIdToSync();
+            await sendAndWaitForChangeEvent(chainId);
+
+            return chain;
+          } catch (err) {
+            const error = err as RpcError;
+            if (error.code === UserRejectedRequestError.code)
+              throw new UserRejectedRequestError(error);
+            throw new SwitchChainError(error);
+          }
+        }
+
+        throw new SwitchChainError(error);
+      }
+
+      async function waitForChainIdToSync() {
+        // On mobile, there is a race condition between the result of
+        // `'wallet_addEthereumChain'` and `'eth_chainId'`, so retry until they agree.
+        await withRetry(
+          async () => {
+            const value = hexToNumber(
+              // `'eth_chainId'` is cached by the MetaMask SDK side to avoid unnecessary deeplinks
+              (await provider.request({ method: "eth_chainId" })) as Hex,
+            );
+            // `value` doesn't match expected `chainId`, throw to trigger retry
+            if (value !== chainId) throw new Error("User rejected switch after adding network.");
+            return value;
+          },
+          {
+            delay: 50,
+            retryCount: 20, // android device encryption is slower
+          },
+        );
+      }
+
+      async function sendAndWaitForChangeEvent(chainId: number) {
+        await new Promise<void>((resolve) => {
+          const listener = ((data) => {
+            if ("chainId" in data && data.chainId === chainId) {
+              config.emitter.off("change", listener);
+              resolve();
+            }
+          }) satisfies Parameters<typeof config.emitter.on>[1];
+          config.emitter.on("change", listener);
+          config.emitter.emit("change", { chainId });
+        });
+      }
+    },
+    async onAccountsChanged(accounts) {
+      // Disconnect if there are no accounts
+      if (accounts.length === 0) {
+        // ... and using browser extension
+        if (sdk.isExtensionActive()) this.onDisconnect();
+        // FIXME(upstream): Mobile app sometimes emits invalid `accountsChanged` event with empty accounts array
+        else return;
+      }
+      // Connect if emitter is listening for connect event (e.g. is disconnected and connects through wallet interface)
+      else if (config.emitter.listenerCount("connect")) {
+        const chainId = (await this.getChainId()).toString();
+        this.onConnect({ chainId });
+      }
+      // Regular change event
+      else
+        config.emitter.emit("change", {
+          accounts: accounts.map((x) => getAddress(x)),
+        });
+    },
+    onChainChanged(chain) {
+      const chainId = Number(chain);
+      config.emitter.emit("change", { chainId });
+    },
+    async onConnect(connectInfo) {
+      const accounts = await this.getAccounts();
+      if (accounts.length === 0) return;
+
+      const chainId = Number(connectInfo.chainId);
+      config.emitter.emit("connect", { accounts, chainId });
+
+      const provider = await this.getProvider();
+      if (connect) {
+        provider.removeListener("connect", connect);
+        connect = undefined;
+      }
+      if (!accountsChanged) {
+        accountsChanged = this.onAccountsChanged.bind(this);
+        provider.on("accountsChanged", accountsChanged as Listener);
+      }
+      if (!chainChanged) {
+        chainChanged = this.onChainChanged.bind(this);
+        provider.on("chainChanged", chainChanged as Listener);
+      }
+      if (!disconnect) {
+        disconnect = this.onDisconnect.bind(this);
+        provider.on("disconnect", disconnect as Listener);
+      }
+    },
+    async onDisconnect(error) {
+      const provider = await this.getProvider();
+
+      // If MetaMask emits a `code: 1013` error, wait for reconnection before disconnecting
+      // https://github.com/MetaMask/providers/pull/120
+      if (error && (error as RpcError<1013>).code === 1013) {
+        if (provider && !!(await this.getAccounts()).length) return;
+      }
+
+      config.emitter.emit("disconnect");
+
+      // Manage EIP-1193 event listeners
+      if (chainChanged) {
+        provider.removeListener("chainChanged", chainChanged);
+        chainChanged = undefined;
+      }
+      if (disconnect) {
+        provider.removeListener("disconnect", disconnect);
+        disconnect = undefined;
+      }
+      if (!connect) {
+        connect = this.onConnect.bind(this);
+        provider.on("connect", connect as Listener);
+      }
+    },
+    onDisplayUri(uri) {
+      config.emitter.emit("message", { type: "display_uri", data: uri });
+    },
+  }));
+}

package/src/connectkit/connectors/syntheticChains.ts

@@ -29,11 +29,21 @@ export const ecosystemBySyntheticChainId: Record<number, Ecosystem> = {
 export const isSyntheticChainId = (chainId?: number): boolean =>
   chainId != null && chainId in ecosystemBySyntheticChainId;
 
+// wagmi's metaMask connector maps EVERY chain in the config into the MetaMask
+// SDK's `supportedNetworks` as `chain.rpcUrls.default.http[0] ?? ""`, and
+// @metamask/connect-evm validates each entry with `new URL(...)`. An empty rpc
+// list therefore threw "supportedNetworks contains invalid URLs" during
+// createEVMClient, which killed connect() before it emitted `display_uri` — the
+// deeplink event the mobile "Open <wallet>" button needs — so MetaMask never
+// opened on any platform. A syntactically valid URL satisfies that check. `.invalid`
+// is reserved by RFC 2606 and never resolves, so nothing can accidentally dial it.
+const placeholderRpcUrl = "https://siww.invalid/";
+
 const makeChain = (id: number, name: string, symbol: string, decimals: number): Chain => ({
   id,
   name,
   nativeCurrency: { name, symbol, decimals },
-  rpcUrls: { default: { http: [] } },
+  rpcUrls: { default: { http: [placeholderRpcUrl] } },
 });
 
 export const solanaChain = makeChain(SOLANA_CHAIN_ID, "Solana", "SOL", 9);

package/src/connectkit/defaultConnectors.ts

@@ -1,11 +1,10 @@
 import { CreateConnectorFn } from "wagmi";
+import { walletConnect, coinbaseWallet, CoinbaseWalletParameters, safe } from "@wagmi/connectors";
+import { metaMaskSdk } from "./connectors/metaMaskSdkConnector";
 import {
-  injected,
-  walletConnect,
-  coinbaseWallet,
-  CoinbaseWalletParameters,
-  safe,
-} from "@wagmi/connectors";
+  isEmbeddedDesktopWebview,
+  metaMaskOptionsForEmbeddedDesktop,
+} from "./connectors/embeddedDesktop";
 
 import { EthereumProviderOptions as AaveAccountOptions, aaveAccountConnector } from "@aave/account";
 
@@ -47,7 +46,28 @@ const defaultConnectors = ({
 
   // Add the rest of the connectors
   connectors.push(
-    injected({ target: "metaMask" }),
+    // MetaMask rides its OWN SDK (id `metaMaskSDK`) — never WalletConnect.
+    // This is the CLASSIC @metamask/sdk connector (see metaMaskSdkConnector.ts for
+    // why not @wagmi/connectors' MWP-based one): mobile browser = deeplink over the
+    // SDK's persistent socket.io relay, which survives the tab being frozen or
+    // discarded during the wallet bounce; desktop = extension; MetaMask in-app
+    // browser = injected; desktop without the extension = the SDK's own QR/install
+    // modal (ConnectKit's QR page is WalletConnect-only, so let the SDK render it).
+    //
+    // Tauri/WebView2/WKWebView: no extension injection. SDK InstallModal custom
+    // elements + `location.href = metamask://` are hostile there — use headless
+    // remote connect and let ConnectKit render the display_uri QR instead.
+    // Mobile options are untouched (useDeeplink stays default true).
+    metaMaskSdk({
+      dappMetadata: {
+        name: app.name,
+        url: app.url,
+        iconUrl: app.icon,
+      },
+      enableAnalytics: false,
+      checkInstallationImmediately: false,
+      ...(isEmbeddedDesktopWebview() ? metaMaskOptionsForEmbeddedDesktop() : {}),
+    }),
     coinbaseWallet({
       appName: app.name,
       appLogoUrl: app.icon,

package/src/connectkit/siwe/connectIntent.ts

@@ -0,0 +1,49 @@
+/**
+ * Records that the user started a connect FROM the modal and therefore means to
+ * continue into the sign-in step.
+ *
+ * Why this can't be React state or a ref: on mobile, connecting bounces out to the
+ * wallet app (MetaMask's deeplink) and back, which remounts — often fully reloads —
+ * the dapp page. Everything in memory is gone, and the modal comes back closed. When
+ * wagmi then rehydrates the connection, `isConnected` flips to true with the modal
+ * shut, so web3Bridge would route to the sign-in screen without anything on screen —
+ * the user has to press connect a second time just to reach the signature prompt.
+ *
+ * sessionStorage survives that reload (same tab), so the intent does too.
+ *
+ * It is deliberately an INTENT flag rather than "reopen whenever connected": a cold
+ * page load with a wallet already connected must NOT pop a modal the user never asked
+ * for. Only a connect the user just initiated carries the intent, and it's consumed
+ * once acted on.
+ */
+const KEY = "siww:connect-intent";
+
+export function setConnectIntent() {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(KEY, "1");
+  } catch {
+    // Private mode / storage disabled — degrade to the old behaviour, don't throw.
+  }
+}
+
+/** Reads and clears the flag; true only for a connect the user just initiated. */
+export function consumeConnectIntent(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    const had = window.sessionStorage.getItem(KEY) !== null;
+    window.sessionStorage.removeItem(KEY);
+    return had;
+  } catch {
+    return false;
+  }
+}
+
+export function clearConnectIntent() {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.removeItem(KEY);
+  } catch {
+    // ignore
+  }
+}

package/src/connectkit/wallets/useWallets.tsx

@@ -6,6 +6,7 @@ import { useContext } from "@multiplatform.one/connectkit";
 import {
   isCoinbaseWalletConnector,
   isInjectedConnector,
+  isMetaMaskConnector,
   getConnectorEcosystem,
   type Ecosystem,
 } from "@multiplatform.one/connectkit";
@@ -50,6 +51,7 @@ export const useWallets = (): WalletProps[] => {
         connector.type === "mock" ||
         connector.type === "siww" || // siww wallets are only listed when detected present
         (connector.type === "injected" && connector.id !== "metaMask") ||
+        isMetaMaskConnector(connector.id) || // always run the MetaMask SDK (extension, mobile deeplink, or SDK modal)
         isCoinbaseWalletConnector(connector.id), // always run coinbase wallet SDK
     };