@abstraxn/signer-react 3.3.5 → 3.3.7

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.7] - 2026-09-15
+
+### Fixed
+- **WalletConnect loader stuck after MetaMask approve (create proposal / deposit)** – Returning from the wallet left a zombie relay socket (`connected === true` on a dead WebSocket). The SDK skipped `restartTransport()`, so the tx hash never reached the dapp even though MetaMask confirmed on-chain. After a backgrounded deeplink the relay is now force-restarted, receipt polling retries when the tab is visible again, and React Query refetches on reconnect/focus so status can update without a manual refresh.
+
+## [3.3.6] - 2026-09-14
+
+### Fixed
+- **WalletConnect mobile approve/reject never returned to the dapp** – After a WalletConnect action deeplinked to MetaMask (or another wallet) on iOS/Android, the browser dropped the relay WebSocket. Approve and reject results never reached the in-flight `signMessage` / `sendTransaction` / `writeContract` promise. The SDK now resumes the WalletConnect relay when the tab becomes visible again and before user-approval requests, and no longer treats a transport drop as a session disconnect.
+- **WalletConnect iOS return opened Safari on the homepage** – Return metadata used `location.origin`, so MetaMask opened Safari at `/` and reloaded the app (lost in-memory UI state). Metadata now uses the current page URL. On iOS Chrome/Firefox/Edge/Brave/Opera, `redirect.native` is the source browser app scheme with no path so the existing tab can be foregrounded. On Safari, `redirect.universal` is omitted so the wallet can return to the same tab instead of navigating to `/`. If a wallet still lands on the homepage, the SDK restores the page the user transacted from.
+
+### Notes
+- Disconnect and reconnect WalletConnect once after upgrading so the wallet stores the new return metadata. Existing sessions keep the old homepage/Safari redirect until re-paired.
+
 ## [3.3.4] - 2026-08-31
 
 ### Fixed

package/dist/src/components/AbstraxnProvider/AbstraxnProvider.js

@@ -10,6 +10,7 @@ import { EVM_CHAINS, toCoreChain } from "../../chains";
 import { AbstraxnProviderWithWagmi } from "./AbstraxnProviderWithWagmi";
 import { AbstraxnProviderWithoutWagmi } from "./AbstraxnProviderWithoutWagmi";
 import { useQueryClientSafe, QueryClientWrapper, canUseReactQuery } from "./utils";
+import { restoreAfterWalletRedirect } from "../../walletConnectMobile";
 import { ConnectionProvider, WalletProvider } from "@solana/wallet-adapter-react";
 import { PhantomWalletAdapter, SolflareWalletAdapter } from "@solana/wallet-adapter-wallets";
 export function AbstraxnProvider({ config, children }) {
@@ -26,6 +27,9 @@ export function AbstraxnProvider({ config, children }) {
     const [isHydrated, setIsHydrated] = useState(() => {
         return typeof window !== 'undefined';
     });
+    useEffect(() => {
+        restoreAfterWalletRedirect();
+    }, []);
     useEffect(() => {
         if (externalSsr && typeof window !== 'undefined' && !isHydrated) {
             // Wait for wallet injection scripts to run (Phantom, etc.)

package/dist/src/components/AbstraxnProvider/AbstraxnProviderInner.js

@@ -12,7 +12,7 @@ import { ExternalWalletButtons, resetExternalWalletViewState, } from "../../Exte
 import { EVM_CHAINS, SOLANA_CHAINS, getChainById, toCoreChain, } from "../../chains";
 import { AbstraxnContext } from "./context";
 import { isLinkAuthCallback } from "./utils";
-import { hasActiveWalletConnectSession, hasPendingWalletConnectApproval, isWalletConnectConnector, patchWalletConnectProviderForMobile, resumeWalletConnectRelayer, subscribeWalletConnectForegroundResume, } from "../../walletConnectMobile";
+import { hasActiveWalletConnectSession, hasPendingWalletConnectApproval, isWalletConnectConnector, patchWalletConnectProviderForMobile, rememberCurrentPageForWalletReturn, resumeWalletConnectRelayer, subscribeWalletConnectForegroundResume, syncWalletConnectDappRedirect, } from "../../walletConnectMobile";
 /** Syncs wagmi disconnect to external wallet state; only rendered when wagmi is available (under WagmiProvider). */
 function WagmiConnectionEffectSync({ onDisconnect, }) {
     useConnectionEffect({ onDisconnect });
@@ -2878,6 +2878,21 @@ export function AbstraxnProviderInner({ config, children, base, wagmi, solana, }
                 });
             }
             try {
+                if (isWalletConnectConnector) {
+                    rememberCurrentPageForWalletReturn();
+                    try {
+                        if (typeof connector.getProvider === "function") {
+                            const provider = await connector.getProvider();
+                            if (provider) {
+                                syncWalletConnectDappRedirect(provider);
+                                patchWalletConnectProviderForMobile(provider);
+                            }
+                        }
+                    }
+                    catch {
+                        // Provider may not exist until after connect.
+                    }
+                }
                 // Use connectAsync to properly await the connection
                 const result = await wagmiConnect.connectAsync({ connector });
                 // Use the result directly to set state immediately
@@ -3187,6 +3202,7 @@ export function AbstraxnProviderInner({ config, children, base, wagmi, solana, }
                 const isWc = isWalletConnectConnector(connector);
                 if (isWc) {
                     wcProviderRef.current = p;
+                    syncWalletConnectDappRedirect(p);
                     patchWalletConnectProviderForMobile(p);
                     unsubscribeForeground = subscribeWalletConnectForegroundResume(p);
                     if (!mounted) {

package/dist/src/components/AbstraxnProvider/utils.js

@@ -68,8 +68,11 @@ export function useQueryClientSafe() {
         return new QueryClient({
             defaultOptions: {
                 queries: {
-                    refetchOnWindowFocus: false,
-                    retry: false,
+                    // Recover waitForTransactionReceipt / balance queries after returning
+                    // from a mobile wallet deeplink (tab was frozen / network dropped).
+                    refetchOnWindowFocus: true,
+                    refetchOnReconnect: true,
+                    retry: 2,
                 },
             },
         });

package/dist/src/hooks.d.ts

@@ -358,16 +358,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
             withdrawals?: import("viem").Withdrawal[] | undefined | undefined;
             withdrawalsRoot?: `0x${string}` | undefined;
             transactions: includeTransactions extends true ? ({
+                input: import("viem").Hex;
+                s: import("viem").Hex;
                 type: "legacy";
                 value: bigint;
                 yParity?: undefined | undefined;
                 from: Address;
                 gas: bigint;
                 hash: import("viem").Hash;
-                input: import("viem").Hex;
                 nonce: number;
                 r: import("viem").Hex;
-                s: import("viem").Hex;
                 to: Address | null;
                 typeHex: import("viem").Hex | null;
                 v: bigint;
@@ -383,16 +383,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
                 blockNumber: (blockTag extends "pending" ? true : false) extends infer T_1 ? T_1 extends (blockTag extends "pending" ? true : false) ? T_1 extends true ? null : bigint : never : never;
                 transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_2 ? T_2 extends (blockTag extends "pending" ? true : false) ? T_2 extends true ? null : number : never : never;
             } | {
+                input: import("viem").Hex;
+                s: import("viem").Hex;
                 type: "eip2930";
                 value: bigint;
                 yParity: number;
                 from: Address;
                 gas: bigint;
                 hash: import("viem").Hash;
-                input: import("viem").Hex;
                 nonce: number;
                 r: import("viem").Hex;
-                s: import("viem").Hex;
                 to: Address | null;
                 typeHex: import("viem").Hex | null;
                 v: bigint;
@@ -408,16 +408,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
                 blockNumber: (blockTag extends "pending" ? true : false) extends infer T_4 ? T_4 extends (blockTag extends "pending" ? true : false) ? T_4 extends true ? null : bigint : never : never;
                 transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_5 ? T_5 extends (blockTag extends "pending" ? true : false) ? T_5 extends true ? null : number : never : never;
             } | {
+                input: import("viem").Hex;
+                s: import("viem").Hex;
                 type: "eip1559";
                 value: bigint;
                 yParity: number;
                 from: Address;
                 gas: bigint;
                 hash: import("viem").Hash;
-                input: import("viem").Hex;
                 nonce: number;
                 r: import("viem").Hex;
-                s: import("viem").Hex;
                 to: Address | null;
                 typeHex: import("viem").Hex | null;
                 v: bigint;
@@ -433,16 +433,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
                 blockNumber: (blockTag extends "pending" ? true : false) extends infer T_7 ? T_7 extends (blockTag extends "pending" ? true : false) ? T_7 extends true ? null : bigint : never : never;
                 transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_8 ? T_8 extends (blockTag extends "pending" ? true : false) ? T_8 extends true ? null : number : never : never;
             } | {
+                input: import("viem").Hex;
+                s: import("viem").Hex;
                 type: "eip4844";
                 value: bigint;
                 yParity: number;
                 from: Address;
                 gas: bigint;
                 hash: import("viem").Hash;
-                input: import("viem").Hex;
                 nonce: number;
                 r: import("viem").Hex;
-                s: import("viem").Hex;
                 to: Address | null;
                 typeHex: import("viem").Hex | null;
                 v: bigint;
@@ -458,16 +458,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
                 blockNumber: (blockTag extends "pending" ? true : false) extends infer T_10 ? T_10 extends (blockTag extends "pending" ? true : false) ? T_10 extends true ? null : bigint : never : never;
                 transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_11 ? T_11 extends (blockTag extends "pending" ? true : false) ? T_11 extends true ? null : number : never : never;
             } | {
+                input: import("viem").Hex;
+                s: import("viem").Hex;
                 type: "eip7702";
                 value: bigint;
                 yParity: number;
                 from: Address;
                 gas: bigint;
                 hash: import("viem").Hash;
-                input: import("viem").Hex;
                 nonce: number;
                 r: import("viem").Hex;
-                s: import("viem").Hex;
                 to: Address | null;
                 typeHex: import("viem").Hex | null;
                 v: bigint;
@@ -508,16 +508,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
         } | undefined) => Promise<import("viem").EstimateMaxPriorityFeePerGasReturnType>;
         getStorageAt: (args: import("viem").GetStorageAtParameters) => Promise<import("viem").GetStorageAtReturnType>;
         getTransaction: <blockTag extends import("viem").BlockTag = "latest">(args: import("viem").GetTransactionParameters<blockTag>) => Promise<{
+            input: import("viem").Hex;
+            s: import("viem").Hex;
             type: "legacy";
             value: bigint;
             yParity?: undefined | undefined;
             from: Address;
             gas: bigint;
             hash: import("viem").Hash;
-            input: import("viem").Hex;
             nonce: number;
             r: import("viem").Hex;
-            s: import("viem").Hex;
             to: Address | null;
             typeHex: import("viem").Hex | null;
             v: bigint;
@@ -533,16 +533,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
             blockNumber: (blockTag extends "pending" ? true : false) extends infer T_1 ? T_1 extends (blockTag extends "pending" ? true : false) ? T_1 extends true ? null : bigint : never : never;
             transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_2 ? T_2 extends (blockTag extends "pending" ? true : false) ? T_2 extends true ? null : number : never : never;
         } | {
+            input: import("viem").Hex;
+            s: import("viem").Hex;
             type: "eip2930";
             value: bigint;
             yParity: number;
             from: Address;
             gas: bigint;
             hash: import("viem").Hash;
-            input: import("viem").Hex;
             nonce: number;
             r: import("viem").Hex;
-            s: import("viem").Hex;
             to: Address | null;
             typeHex: import("viem").Hex | null;
             v: bigint;
@@ -558,16 +558,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
             blockNumber: (blockTag extends "pending" ? true : false) extends infer T_4 ? T_4 extends (blockTag extends "pending" ? true : false) ? T_4 extends true ? null : bigint : never : never;
             transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_5 ? T_5 extends (blockTag extends "pending" ? true : false) ? T_5 extends true ? null : number : never : never;
         } | {
+            input: import("viem").Hex;
+            s: import("viem").Hex;
             type: "eip1559";
             value: bigint;
             yParity: number;
             from: Address;
             gas: bigint;
             hash: import("viem").Hash;
-            input: import("viem").Hex;
             nonce: number;
             r: import("viem").Hex;
-            s: import("viem").Hex;
             to: Address | null;
             typeHex: import("viem").Hex | null;
             v: bigint;
@@ -583,16 +583,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
             blockNumber: (blockTag extends "pending" ? true : false) extends infer T_7 ? T_7 extends (blockTag extends "pending" ? true : false) ? T_7 extends true ? null : bigint : never : never;
             transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_8 ? T_8 extends (blockTag extends "pending" ? true : false) ? T_8 extends true ? null : number : never : never;
         } | {
+            input: import("viem").Hex;
+            s: import("viem").Hex;
             type: "eip4844";
             value: bigint;
             yParity: number;
             from: Address;
             gas: bigint;
             hash: import("viem").Hash;
-            input: import("viem").Hex;
             nonce: number;
             r: import("viem").Hex;
-            s: import("viem").Hex;
             to: Address | null;
             typeHex: import("viem").Hex | null;
             v: bigint;
@@ -608,16 +608,16 @@ export declare function usePublicClient(chain: Chain, rpcUrl: string): {
             blockNumber: (blockTag extends "pending" ? true : false) extends infer T_10 ? T_10 extends (blockTag extends "pending" ? true : false) ? T_10 extends true ? null : bigint : never : never;
             transactionIndex: (blockTag extends "pending" ? true : false) extends infer T_11 ? T_11 extends (blockTag extends "pending" ? true : false) ? T_11 extends true ? null : number : never : never;
         } | {
+            input: import("viem").Hex;
+            s: import("viem").Hex;
             type: "eip7702";
             value: bigint;
             yParity: number;
             from: Address;
             gas: bigint;
             hash: import("viem").Hash;
-            input: import("viem").Hex;
             nonce: number;
             r: import("viem").Hex;
-            s: import("viem").Hex;
             to: Address | null;
             typeHex: import("viem").Hex | null;
             v: bigint;
@@ -8162,9 +8162,9 @@ export declare function useWalletClient(chain: any, rpcUrl?: string): {
             [x: `address[${string}]`]: undefined;
             [x: `bool[${string}]`]: undefined;
             [x: `bytes[${string}]`]: undefined;
+            [x: `bytes3[${string}]`]: undefined;
             [x: `bytes1[${string}]`]: undefined;
             [x: `bytes2[${string}]`]: undefined;
-            [x: `bytes3[${string}]`]: undefined;
             [x: `bytes4[${string}]`]: undefined;
             [x: `bytes5[${string}]`]: undefined;
             [x: `bytes6[${string}]`]: undefined;
@@ -8264,9 +8264,9 @@ export declare function useWalletClient(chain: any, rpcUrl?: string): {
             address?: undefined;
             bool?: undefined;
             bytes?: undefined;
+            bytes3?: undefined;
             bytes1?: undefined;
             bytes2?: undefined;
-            bytes3?: undefined;
             bytes4?: undefined;
             bytes5?: undefined;
             bytes6?: undefined;
@@ -13137,9 +13137,9 @@ export declare function useExternalWalletClient(): {
             [x: `address[${string}]`]: undefined;
             [x: `bool[${string}]`]: undefined;
             [x: `bytes[${string}]`]: undefined;
+            [x: `bytes3[${string}]`]: undefined;
             [x: `bytes1[${string}]`]: undefined;
             [x: `bytes2[${string}]`]: undefined;
-            [x: `bytes3[${string}]`]: undefined;
             [x: `bytes4[${string}]`]: undefined;
             [x: `bytes5[${string}]`]: undefined;
             [x: `bytes6[${string}]`]: undefined;
@@ -13239,9 +13239,9 @@ export declare function useExternalWalletClient(): {
             address?: undefined;
             bool?: undefined;
             bytes?: undefined;
+            bytes3?: undefined;
             bytes1?: undefined;
             bytes2?: undefined;
-            bytes3?: undefined;
             bytes4?: undefined;
             bytes5?: undefined;
             bytes6?: undefined;

package/dist/src/hooks.js

@@ -12,6 +12,7 @@ import { useWalletClient as useWagmiWalletClient, useAccount, useConfig, useChai
 import { getWalletClient, switchChain } from '@wagmi/core';
 import { getConnectorMeta } from './connectors';
 import { getChainById } from './chains';
+import { waitUntilDocumentVisible } from './walletConnectMobile';
 /**
  * Hook to check if wallet is connected
  */
@@ -2064,15 +2065,40 @@ export function useWaitForTxnReceipt(provider) {
             throw new Error('Transaction hash is required');
         }
         try {
-            // waitForTransactionReceipt is a method on PublicClient
-            const receipt = await provider.waitForTransactionReceipt({
-                hash,
-                confirmations,
-                timeout,
-            });
-            return receipt;
+            // After MetaMask deeplink the tab was frozen; wait until we are visible
+            // again and retry receipt polls so the UI is not stuck on a loader.
+            await waitUntilDocumentVisible();
+            const overallTimeout = timeout ?? 180_000;
+            const startedAt = Date.now();
+            let lastError;
+            while (Date.now() - startedAt < overallTimeout) {
+                const remaining = overallTimeout - (Date.now() - startedAt);
+                try {
+                    const receipt = await provider.waitForTransactionReceipt({
+                        hash,
+                        confirmations,
+                        timeout: Math.min(20_000, remaining),
+                        pollingInterval: 1_500,
+                    });
+                    return receipt;
+                }
+                catch (error) {
+                    lastError = error;
+                    await waitUntilDocumentVisible();
+                    await new Promise((resolve) => setTimeout(resolve, 1_000));
+                }
+            }
+            if (lastError instanceof Error) {
+                throw new Error(`Failed to wait for transaction receipt: ${lastError.message}`);
+            }
+            throw lastError instanceof Error
+                ? lastError
+                : new Error('Failed to wait for transaction receipt');
         }
         catch (error) {
+            if (error instanceof Error && error.message.startsWith('Failed to wait for transaction receipt')) {
+                throw error;
+            }
             if (error instanceof Error) {
                 throw new Error(`Failed to wait for transaction receipt: ${error.message}`);
             }

package/dist/src/wagmiConfig.js

@@ -4,6 +4,7 @@
 import { createConfig, createStorage, http, cookieStorage, } from "@wagmi/core";
 import { injected, walletConnect } from "wagmi/connectors";
 import { SUPPORTED_CHAINS, } from "@abstraxn/signer-core";
+import { createWalletConnectDappMetadata } from "./walletConnectMobile";
 /**
  * Convert internal Chain type to viem Chain type
  * Uses viem's built-in chain definitions when available for better compatibility
@@ -77,21 +78,9 @@ export function createWagmiConfig(chains, walletConnectProjectId, enabledConnect
             console.warn("WalletConnect project ID is required for WalletConnect connector. Skipping...");
         }
         else {
-            const dappUrl = typeof window !== "undefined"
-                ? window.location.origin
-                : "https://abstraxn.com";
             connectors.push(walletConnect({
                 projectId: walletConnectProjectId,
-                metadata: {
-                    name: "Abstraxn",
-                    description: "Abstraxn Wallet",
-                    url: dappUrl,
-                    icons: ["https://avatars.githubusercontent.com/u/37784886"],
-                    // Helps mobile wallets (MetaMask) return to this dapp after approve/reject.
-                    redirect: {
-                        universal: dappUrl,
-                    },
-                },
+                metadata: createWalletConnectDappMetadata(),
                 showQrModal: true,
                 qrModalOptions: {
                     themeMode: theme === "dark" ? "dark" : "light",

package/dist/src/walletConnectMobile.d.ts

@@ -5,6 +5,14 @@
  * WebSocket when the user is sent to MetaMask (or another wallet) via deeplink.
  * The wallet still approves/rejects, but the in-flight JSON-RPC promise never
  * settles unless the relay is resumed when the dapp becomes visible again.
+ *
+ * After approve/reject, MetaMask opens metadata.redirect / metadata.url. Using
+ * only `location.origin` sends iOS users to Safari on the homepage (full reload,
+ * lost React state). We:
+ * - keep metadata.url as the current page (not origin)
+ * - on iOS Chrome/Firefox/etc. set redirect.native to the browser app scheme
+ *   with no path, so the existing tab is foregrounded
+ * - on Safari omit redirect so MetaMask can `goBack()` to the same tab
  */
 /** Selectors used to close/restore Reown AppKit + WalletConnect modal DOM. */
 export declare const WALLETCONNECT_MODAL_SELECTORS: string[];
@@ -15,11 +23,57 @@ export declare function isWalletConnectConnector(connector: {
 export declare function isUserApprovalRpcMethod(method: unknown): boolean;
 export declare function hasPendingWalletConnectApproval(provider?: any): boolean;
 export declare function hasActiveWalletConnectSession(provider: any): boolean;
+/**
+ * Current dapp page, including path/query/hash. Never origin-only — that is
+ * what made MetaMask open the homepage after approve/reject.
+ */
+export declare function getDappReturnUrl(): string;
+/**
+ * iOS-only app scheme for the browser the user is actually in. No path:
+ * opening `googlechrome://` foregrounds Chrome's existing tab instead of
+ * navigating Safari to a new URL (which reloads and drops in-memory state).
+ */
+export declare function getSourceBrowserNativeRedirect(): string | undefined;
+/**
+ * Lazy metadata so url/redirect are read at connect/request time, not at
+ * provider mount (which is often the homepage in Next.js layouts).
+ */
+export declare function createWalletConnectDappMetadata(): {
+    name: string;
+    description: string;
+    icons: string[];
+    url: string;
+    redirect?: {
+        native?: string;
+        universal?: string;
+    };
+};
+export declare function rememberCurrentPageForWalletReturn(): void;
+export declare function clearWalletReturnIfSameDocument(): void;
+/**
+ * If the wallet opened a fresh Safari tab on the homepage, send the user back
+ * to the page they transacted from. This still reloads that page (React state
+ * cannot be recovered), but it is better than leaving them on `/`.
+ */
+export declare function restoreAfterWalletRedirect(): void;
+/**
+ * Push the current page + source-browser scheme onto the live WC provider so
+ * MetaMask does not keep a stale homepage redirect from first init.
+ */
+export declare function syncWalletConnectDappRedirect(provider: any): void;
 /**
  * Re-open the WalletConnect relay after the mobile browser comes back
  * from the wallet app so pending approve/reject responses can be delivered.
+ *
+ * `force` must be used after the tab was backgrounded: iOS/Android often leave
+ * `relayer.connected === true` on a dead socket, so a ping/early-return skips
+ * the restart and the in-flight tx hash never arrives (loader hangs until refresh).
  */
-export declare function resumeWalletConnectRelayer(provider: any): Promise<void>;
+export declare function resumeWalletConnectRelayer(provider: any, options?: {
+    force?: boolean;
+}): Promise<void>;
+/** Resolves when the dapp tab is in the foreground again (mobile wallet return). */
+export declare function waitUntilDocumentVisible(): Promise<void>;
 /**
  * Undo the inline `display: none !important` we apply after connect so the
  * WalletConnect modal can show "Continue in wallet" and process the response.

package/dist/src/walletConnectMobile.js

@@ -5,9 +5,22 @@
  * WebSocket when the user is sent to MetaMask (or another wallet) via deeplink.
  * The wallet still approves/rejects, but the in-flight JSON-RPC promise never
  * settles unless the relay is resumed when the dapp becomes visible again.
+ *
+ * After approve/reject, MetaMask opens metadata.redirect / metadata.url. Using
+ * only `location.origin` sends iOS users to Safari on the homepage (full reload,
+ * lost React state). We:
+ * - keep metadata.url as the current page (not origin)
+ * - on iOS Chrome/Firefox/etc. set redirect.native to the browser app scheme
+ *   with no path, so the existing tab is foregrounded
+ * - on Safari omit redirect so MetaMask can `goBack()` to the same tab
  */
 const PATCHED_FLAG = "__abstraxnWcMobilePatched";
 const PENDING_FLAG = "__abstraxnWcPendingApprovals";
+const NEEDS_RESUME_FLAG = "__abstraxnWcNeedsResume";
+const RESUME_LOCK = "__abstraxnWcResumeLock";
+const RETURN_HREF_KEY = "abstraxn_wc_return_href";
+const RETURN_AT_KEY = "abstraxn_wc_return_at";
+const RETURN_TTL_MS = 3 * 60 * 1000;
 const USER_APPROVAL_METHODS = new Set([
     "personal_sign",
     "eth_sign",
@@ -69,6 +82,163 @@ export function hasActiveWalletConnectSession(provider) {
     }
     return true;
 }
+function isIOS() {
+    if (typeof navigator === "undefined")
+        return false;
+    const ua = navigator.userAgent || "";
+    const platform = navigator.platform || "";
+    return (/iPad|iPhone|iPod/i.test(ua) ||
+        (platform === "MacIntel" && (navigator.maxTouchPoints || 0) > 1));
+}
+/**
+ * Current dapp page, including path/query/hash. Never origin-only — that is
+ * what made MetaMask open the homepage after approve/reject.
+ */
+export function getDappReturnUrl() {
+    if (typeof window === "undefined")
+        return "https://abstraxn.com";
+    const url = new URL(window.location.href);
+    url.searchParams.delete("wc_ev");
+    url.searchParams.delete("wc_res");
+    return `${url.origin}${url.pathname}${url.search}${url.hash}`;
+}
+/**
+ * iOS-only app scheme for the browser the user is actually in. No path:
+ * opening `googlechrome://` foregrounds Chrome's existing tab instead of
+ * navigating Safari to a new URL (which reloads and drops in-memory state).
+ */
+export function getSourceBrowserNativeRedirect() {
+    if (typeof navigator === "undefined" || !isIOS())
+        return undefined;
+    const ua = navigator.userAgent || "";
+    if (/FxiOS/i.test(ua))
+        return "firefox://";
+    if (/EdgiOS/i.test(ua))
+        return "microsoft-edge://";
+    if (/OPiOS/i.test(ua) || /OPT\//i.test(ua))
+        return "touch://";
+    if (/Brave/i.test(ua))
+        return "brave://";
+    if (/CriOS/i.test(ua))
+        return "googlechrome://";
+    return undefined;
+}
+function getWalletConnectRedirect() {
+    const native = getSourceBrowserNativeRedirect();
+    return native ? { native } : undefined;
+}
+/**
+ * Lazy metadata so url/redirect are read at connect/request time, not at
+ * provider mount (which is often the homepage in Next.js layouts).
+ */
+export function createWalletConnectDappMetadata() {
+    return {
+        name: "Abstraxn",
+        description: "Abstraxn Wallet",
+        icons: ["https://avatars.githubusercontent.com/u/37784886"],
+        get url() {
+            return getDappReturnUrl();
+        },
+        get redirect() {
+            return getWalletConnectRedirect();
+        },
+    };
+}
+export function rememberCurrentPageForWalletReturn() {
+    if (typeof window === "undefined")
+        return;
+    try {
+        window.localStorage.setItem(RETURN_HREF_KEY, getDappReturnUrl());
+        window.localStorage.setItem(RETURN_AT_KEY, String(Date.now()));
+    }
+    catch {
+        // Ignore quota / private-mode errors.
+    }
+}
+export function clearWalletReturnIfSameDocument() {
+    if (typeof window === "undefined")
+        return;
+    try {
+        const saved = window.localStorage.getItem(RETURN_HREF_KEY);
+        if (!saved)
+            return;
+        const savedUrl = new URL(saved, window.location.origin);
+        if (savedUrl.origin !== window.location.origin)
+            return;
+        if (savedUrl.pathname === window.location.pathname &&
+            savedUrl.search === window.location.search &&
+            savedUrl.hash === window.location.hash) {
+            window.localStorage.removeItem(RETURN_HREF_KEY);
+            window.localStorage.removeItem(RETURN_AT_KEY);
+        }
+    }
+    catch {
+        // Ignore
+    }
+}
+/**
+ * If the wallet opened a fresh Safari tab on the homepage, send the user back
+ * to the page they transacted from. This still reloads that page (React state
+ * cannot be recovered), but it is better than leaving them on `/`.
+ */
+export function restoreAfterWalletRedirect() {
+    if (typeof window === "undefined")
+        return;
+    try {
+        const at = Number(window.localStorage.getItem(RETURN_AT_KEY) || 0);
+        const saved = window.localStorage.getItem(RETURN_HREF_KEY);
+        if (!saved || !at || Date.now() - at > RETURN_TTL_MS) {
+            window.localStorage.removeItem(RETURN_HREF_KEY);
+            window.localStorage.removeItem(RETURN_AT_KEY);
+            return;
+        }
+        const savedUrl = new URL(saved, window.location.origin);
+        if (savedUrl.origin !== window.location.origin) {
+            window.localStorage.removeItem(RETURN_HREF_KEY);
+            window.localStorage.removeItem(RETURN_AT_KEY);
+            return;
+        }
+        const savedPath = `${savedUrl.pathname}${savedUrl.search}${savedUrl.hash}`;
+        const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+        if (savedPath === currentPath) {
+            window.localStorage.removeItem(RETURN_HREF_KEY);
+            window.localStorage.removeItem(RETURN_AT_KEY);
+            return;
+        }
+        window.localStorage.removeItem(RETURN_HREF_KEY);
+        window.localStorage.removeItem(RETURN_AT_KEY);
+        window.location.replace(savedUrl.href);
+    }
+    catch {
+        // Ignore
+    }
+}
+function applyDappMetadata(meta, url, redirect) {
+    if (!meta || typeof meta !== "object")
+        return;
+    meta.url = url;
+    if (redirect) {
+        meta.redirect = { native: redirect.native };
+    }
+    else if (meta.redirect) {
+        delete meta.redirect;
+    }
+}
+/**
+ * Push the current page + source-browser scheme onto the live WC provider so
+ * MetaMask does not keep a stale homepage redirect from first init.
+ */
+export function syncWalletConnectDappRedirect(provider) {
+    if (!provider || typeof window === "undefined")
+        return;
+    const url = getDappReturnUrl();
+    const redirect = getWalletConnectRedirect();
+    rememberCurrentPageForWalletReturn();
+    applyDappMetadata(provider.metadata, url, redirect);
+    applyDappMetadata(provider.signer?.metadata, url, redirect);
+    applyDappMetadata(provider.session?.self?.metadata, url, redirect);
+    applyDappMetadata(provider.signer?.session?.self?.metadata, url, redirect);
+}
 function getWalletConnectRelayer(provider) {
     return (provider?.signer?.client?.core?.relayer ||
         provider?.client?.core?.relayer ||
@@ -81,60 +251,102 @@ function isRelayerConnected(relayer) {
         relayer?.provider?.connected === true ||
         relayer?.provider?.connection?.connected === true);
 }
+async function restartWalletConnectTransport(relayer) {
+    if (typeof relayer.restartTransport === "function") {
+        await relayer.restartTransport();
+        return;
+    }
+    if (typeof relayer.transportOpen === "function") {
+        try {
+            await relayer.transportClose?.();
+        }
+        catch {
+            // Ignore close errors and still try to open.
+        }
+        await relayer.transportOpen();
+    }
+}
 /**
  * Re-open the WalletConnect relay after the mobile browser comes back
  * from the wallet app so pending approve/reject responses can be delivered.
+ *
+ * `force` must be used after the tab was backgrounded: iOS/Android often leave
+ * `relayer.connected === true` on a dead socket, so a ping/early-return skips
+ * the restart and the in-flight tx hash never arrives (loader hangs until refresh).
  */
-export async function resumeWalletConnectRelayer(provider) {
+export async function resumeWalletConnectRelayer(provider, options) {
     if (!provider)
         return;
     const relayer = getWalletConnectRelayer(provider);
     if (!relayer)
         return;
-    try {
-        if (isRelayerConnected(relayer)) {
-            try {
+    const existing = provider[RESUME_LOCK];
+    if (existing && !options?.force) {
+        try {
+            await existing;
+        }
+        catch {
+            // Previous resume failed.
+        }
+        return;
+    }
+    const run = (async () => {
+        try {
+            if (!options?.force && isRelayerConnected(relayer)) {
                 const ping = relayer.provider?.connection?.ping;
                 if (typeof ping === "function") {
                     await Promise.race([
                         ping.call(relayer.provider.connection),
                         new Promise((_, reject) => setTimeout(() => reject(new Error("ping timeout")), 1500)),
                     ]);
+                    return;
                 }
-                return;
+                // No ping API: do not assume a zombie "connected" socket is healthy.
             }
-            catch {
-                // Ping failed — transport looks stale, restart below.
+            await restartWalletConnectTransport(relayer);
+            const session = provider?.session ?? provider?.signer?.session;
+            const topic = session?.topic;
+            const client = provider?.signer?.client || provider?.client;
+            if (topic && typeof client?.ping === "function") {
+                try {
+                    await client.ping({ topic });
+                }
+                catch {
+                    // Session ping is best-effort; the request may still complete.
+                }
             }
         }
-        if (typeof relayer.restartTransport === "function") {
-            await relayer.restartTransport();
-        }
-        else if (typeof relayer.transportOpen === "function") {
-            try {
-                await relayer.transportClose?.();
-            }
-            catch {
-                // Ignore close errors and still try to open.
-            }
-            await relayer.transportOpen();
-        }
-        const session = provider?.session ?? provider?.signer?.session;
-        const topic = session?.topic;
-        const client = provider?.signer?.client || provider?.client;
-        if (topic && typeof client?.ping === "function") {
-            try {
-                await client.ping({ topic });
-            }
-            catch {
-                // Session ping is best-effort; the request may still complete.
-            }
+        catch {
+            // Best-effort: a failed resume should not break the original request.
         }
+    })();
+    provider[RESUME_LOCK] = run;
+    try {
+        await run;
     }
-    catch {
-        // Best-effort: a failed resume should not break the original request.
+    finally {
+        if (provider[RESUME_LOCK] === run)
+            provider[RESUME_LOCK] = null;
     }
 }
+/** Resolves when the dapp tab is in the foreground again (mobile wallet return). */
+export function waitUntilDocumentVisible() {
+    if (typeof document === "undefined")
+        return Promise.resolve();
+    if (document.visibilityState === "visible")
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const onVis = () => {
+            if (document.visibilityState === "visible") {
+                document.removeEventListener("visibilitychange", onVis);
+                window.removeEventListener("pageshow", onVis);
+                resolve();
+            }
+        };
+        document.addEventListener("visibilitychange", onVis);
+        window.addEventListener("pageshow", onVis);
+    });
+}
 /**
  * Undo the inline `display: none !important` we apply after connect so the
  * WalletConnect modal can show "Continue in wallet" and process the response.
@@ -179,17 +391,26 @@ export function patchWalletConnectProviderForMobile(provider) {
     provider[PENDING_FLAG] = 0;
     provider.request = async (...args) => {
         const method = getRequestMethod(args);
-        if (!isUserApprovalRpcMethod(method)) {
+        const isApproval = isUserApprovalRpcMethod(method);
+        const wasBackgrounded = !!provider[NEEDS_RESUME_FLAG];
+        if (!isApproval && !wasBackgrounded) {
             return originalRequest(...args);
         }
-        provider[PENDING_FLAG] = (provider[PENDING_FLAG] || 0) + 1;
-        restoreWalletConnectModal();
+        if (isApproval) {
+            provider[PENDING_FLAG] = (provider[PENDING_FLAG] || 0) + 1;
+            restoreWalletConnectModal();
+            syncWalletConnectDappRedirect(provider);
+        }
         try {
-            await resumeWalletConnectRelayer(provider);
+            await resumeWalletConnectRelayer(provider, { force: wasBackgrounded });
+            if (wasBackgrounded)
+                provider[NEEDS_RESUME_FLAG] = false;
             return await originalRequest(...args);
         }
         finally {
-            provider[PENDING_FLAG] = Math.max(0, (provider[PENDING_FLAG] || 1) - 1);
+            if (isApproval) {
+                provider[PENDING_FLAG] = Math.max(0, (provider[PENDING_FLAG] || 1) - 1);
+            }
         }
     };
 }
@@ -201,17 +422,28 @@ export function subscribeWalletConnectForegroundResume(provider) {
     if (typeof window === "undefined" || !provider)
         return () => { };
     let timer = null;
+    let hiddenAt = 0;
     const resume = () => {
         if (timer)
             clearTimeout(timer);
+        const hiddenMs = hiddenAt ? Date.now() - hiddenAt : 0;
+        const pending = hasPendingWalletConnectApproval(provider);
+        const force = pending || hiddenMs > 400 || !!provider[NEEDS_RESUME_FLAG];
         timer = setTimeout(() => {
-            void resumeWalletConnectRelayer(provider);
-            if (hasPendingWalletConnectApproval(provider)) {
+            clearWalletReturnIfSameDocument();
+            void resumeWalletConnectRelayer(provider, { force });
+            if (pending)
                 restoreWalletConnectModal();
-            }
-        }, 250);
+        }, pending || force ? 50 : 250);
     };
     const onVisibility = () => {
+        if (document.visibilityState === "hidden") {
+            hiddenAt = Date.now();
+            if (hasPendingWalletConnectApproval(provider)) {
+                provider[NEEDS_RESUME_FLAG] = true;
+            }
+            return;
+        }
         if (document.visibilityState === "visible")
             resume();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abstraxn/signer-react",
-  "version": "3.3.5",
+  "version": "3.3.7",
   "description": "React SDK for Abstraxn Wallet - React components, hooks, and providers for seamless Web3 wallet integration",
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",