0xtrails 0.12.2 → 0.13.0

package/src/widget/widget.tsx

@@ -51,6 +51,7 @@ interface OnrampTransferResult {
   txHash?: string
   transferId?: string
 }
+
 import {
   createStorage,
   useAccount,
@@ -61,7 +62,7 @@ import {
   useDisconnect,
   useSwitchAccount,
 } from "wagmi"
-import { getSessionId, trackWidgetScreen } from "../analytics.js"
+import { getSessionId } from "../analytics.js"
 import { getChainInfo } from "../chains.js"
 // Config is now managed exclusively by TrailsProvider
 import { cssObjectToString } from "../cssUtils.js"
@@ -73,14 +74,11 @@ import {
   getIsUserRejectionError,
   getPrettifiedErrorMessage,
 } from "../error.js"
-import { removeStoredIntent } from "../intentStorage.js"
 import { logger } from "../logger.js"
-import type { Mode } from "../mode.js"
+import { abortControllerRegistry } from "../abortController.js"
 import type { Pool } from "../pools.js"
 import { usePools } from "../pools.js"
-// TODO: temporary ignore this Biome warning for now; do not refactor code in this pass.
-// biome-ignore lint/style/useImportType: Keep current import shape for now per requested temporary ignores.
-import { type PrepareSendQuote } from "../prepareSend.js"
+import type { PrepareSendQuote } from "../prepareSend.js"
 import { isValidInteger, isValidNumeric } from "../utils/validation.js"
 import type { Theme } from "../theme.js"
 import type { Token } from "../tokens.js"
@@ -135,14 +133,13 @@ import WalletConnectScreen from "./components/WalletConnect.js"
 import WalletConnectionPending from "./components/WalletConnectionPending.js"
 import { FundWalletSelection } from "./components/FundWalletSelection.js"
 import { WalletList } from "./components/WalletList.js"
-import { useBack } from "./hooks/useBack.js"
 import { useCheckout } from "./hooks/useCheckout.js"
-import { useCurrentScreen, type Screen } from "./hooks/useCurrentScreen.js"
 import { useDebugScreens } from "./hooks/useDebugScreens.js"
+import { useExternalFundingReceiptSync } from "./hooks/useExternalFundingReceiptSync.js"
+import { useScreenTracking } from "./hooks/useScreenTracking.js"
 import { useEarnPool } from "./hooks/useEarnPool.js"
-import { useInitialRedirect } from "./hooks/useInitialRedirect.js"
+
 import { useIsSequenceWallet } from "./hooks/useIsSequenceWallet.js"
-import { useMode } from "./hooks/useMode.js"
 import { useOriginSelectedToken as useSelectedToken } from "./hooks/useOriginSelectedToken.js"
 import { PriceImpactWarningProvider } from "./hooks/usePriceImpactWarning.js"
 import { useRecentTokens } from "./hooks/useRecentTokens.js"
@@ -151,9 +148,11 @@ import { useSelectedFundMethod } from "./hooks/useSelectedFundMethod.js"
 import { useSelectedRecipient } from "./hooks/useSelectedRecipient.js"
 import type { OnCompleteProps } from "./hooks/useSendForm.js"
 import { useTargetAmount } from "./hooks/useTargetAmount.js"
+import { useSwapState } from "./hooks/useSwapState.js"
 import { useWidgetAnalytics } from "./analytics/useWidgetAnalytics.js"
 import { useWalletConnectionContext } from "./hooks/useWalletConnectionContext.js"
 import { useWidgetProps } from "./hooks/useWidgetProps.js"
+import { clearFundStateForMethodSwitch } from "./utils/fundMethodSwitchState.js"
 import { useOnRampProviderWidget } from "./hooks/useOnRampProviderWidget.js"
 import { WidgetProviders } from "./components/WidgetProviders.js"
 import {
@@ -161,7 +160,14 @@ import {
   type TrailsProviderProps,
 } from "./providers/TrailsProvider.js"
 import { useTrailsModal } from "./providers/TrailsModalProvider.js"
-import { usePreviousScreen } from "./hooks/usePreviousScreen.js"
+import {
+  useViewManager,
+  useNavigationEffect,
+  useScreenGuard,
+  getInitialScreen,
+  type Screen,
+  type Mode,
+} from "./hooks/useViewManager.js"
 import PaymentMethods from "./components/PaymentMethods.js"
 import type { OnrampQuote } from "./hooks/useOnRampQuote.js"
 import {
@@ -169,14 +175,15 @@ import {
   isNativeToken,
   normalizeAddress,
 } from "../utils/address.js"
+import { isWalletConnectConnector } from "../walletUtils.js"
 import type { SendOptions, SwapReturn } from "./hooks/useQuote.js"
 import { hasFailedOrAbortedTransaction } from "./utils/transactionFailure.js"
-
-export type FundMethodListOption =
-  | "connected-wallet"
-  | "crypto-transfer"
-  | "cc-onramp"
-  | "exchange-onramp"
+import {
+  shouldClearTransferFlowOnNavigate,
+  shouldRedirectToConnect,
+} from "./utils/viewManagerGuards.js"
+import type { FundMethod } from "../transactionIntent/types.js"
+import { isExternalFundingMethod } from "../transactionIntent/types.js"
 
 // Validate toToken - must be "ETH", "USDC", or a valid hex address
 const isValidToToToken = (toToken: string | null | undefined) => {
@@ -191,6 +198,21 @@ const isValidToToToken = (toToken: string | null | undefined) => {
   return isAddress(token)
 }
 
+export type FundMethodListOption =
+  | "connected-wallet"
+  | "crypto-transfer"
+  | "cc-onramp"
+  | "exchange-onramp"
+
+export const WidgetFundMethod = {
+  Wallet: "wallet",
+  CryptoTransfer: "crypto-transfer",
+  Onramp: "onramp",
+  OnrampExchange: "onramp-exchange",
+} as const
+export type WidgetFundMethod =
+  (typeof WidgetFundMethod)[keyof typeof WidgetFundMethod]
+
 export type TrailsWidgetProps = {
   apiKey: string
   sequenceIndexerUrl?: string
@@ -218,6 +240,17 @@ export type TrailsWidgetProps = {
   renderInline?: boolean
   theme?: Theme
   mode?: Mode
+  /**
+   * Pre-select funding method used by the widget.
+   *
+   * This applies across modes (fund/pay/swap/earn) wherever funding method is used.
+   * In fund mode it also controls the initial destination flow:
+   * - "wallet" -> Funding with wallet flow
+   * - "crypto-transfer" --> Funding with QR Code or deposit to address flow
+   * - "onramp" --> Funding with onramp flow
+   * - "onramp-exchange" --> Funding with exchange flow
+   */
+  fundMethod?: WidgetFundMethod
   walletOptions?: string[]
   onOriginConfirmation?: (data: {
     txHash: string
@@ -302,6 +335,10 @@ export type TrailsWidgetProps = {
      * Default: false.
      */
     hideUnlistedFundMethods?: boolean
+    /** ISO 4217 currency code to pre-select in onramp mode (e.g. "EUR", "GBP") */
+    fiatCurrency?: string
+    /** Fiat amount to pre-populate in onramp mode */
+    fiatAmount?: string
   }
   toast?: boolean
   appName?: string
@@ -619,6 +656,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     decoupleWagmi,
     hideDisconnect,
     defaultInputMode,
+    fundMethod: configuredFundMethod,
   } = useWidgetProps()
   const { address, chainId, connector } = useAccount()
   const connectors = useConnectors()
@@ -688,11 +726,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     },
   })
 
-  // Handle fromAccount preselection (one-time only)
-  // We use a ref to ensure this only runs once on mount.
-  // Without this guard, the effect re-fires on every render cycle
-  // and overrides the user's wallet selection (e.g. switching back
-  // from MetaMask to Privy embedded wallet).
+  // Handle fromAccount preselection
   const hasInitializedFromAccount = useRef(false)
   useEffect(() => {
     if (hasInitializedFromAccount.current) return
@@ -737,11 +771,31 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       isModalOpen,
     )
   }, [isModalOpen])
-  const { mode: currentMode, configuredMode, resetMode } = useMode()
-  const { currentScreen, setCurrentScreen } = useCurrentScreen()
-  const { previousScreen } = usePreviousScreen()
-  const { goBack, clearHistory, setCurrentScreenWithBack, getPreviousScreen } =
-    useBack()
+  const {
+    mode: currentMode,
+    configuredMode,
+    resetMode,
+    screen,
+    navigate,
+    goBack,
+    goHome,
+    canGoBack,
+    backScreen,
+    state,
+  } = useViewManager()
+  const { setSellAmount, setBuyAmount } = useSwapState()
+
+  // Abort in-flight requests when navigating away from transfer screens.
+  useNavigationEffect(({ from, to }) => {
+    if (shouldClearTransferFlowOnNavigate(from, to)) {
+      abortControllerRegistry.abortAll()
+      setPrepareSendQuote(null)
+    }
+
+    if (to === "fund-methods") {
+      fundMethodSelectionStartRef.current = selectedFundMethod
+    }
+  })
   const {
     connectionContext,
     clearConnectionContext,
@@ -753,12 +807,34 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   // Wrapper function that clears errors when going back
   const handleBack = () => {
     setError(null)
-    goBack?.()
+    if (canGoBack) goBack()
+    else goHome()
   }
   const [previousAddress, setPreviousAddress] = useState<string | undefined>(
     address,
   )
   const { selectedFundMethod, setSelectedFundMethod } = useSelectedFundMethod()
+  const fundMethodSelectionStartRef = useRef(selectedFundMethod)
+  const clearStateForFundMethodSwitch = useCallback(
+    (nextMethod: typeof selectedFundMethod) => {
+      const previousMethod = fundMethodSelectionStartRef.current
+      const didSwitchMethods = clearFundStateForMethodSwitch(
+        previousMethod,
+        nextMethod,
+        {
+          clearSelectedToken,
+          setSellAmount,
+          setBuyAmount,
+          setPrepareSendQuote,
+        },
+      )
+
+      if (didSwitchMethods) {
+        fundMethodSelectionStartRef.current = nextMethod
+      }
+    },
+    [clearSelectedToken, setSellAmount, setBuyAmount],
+  )
   const { selectedPool, setSelectedPool } = useEarnPool()
   const [selectedWalletId, setSelectedWalletId] = useState<string | null>(
     () => {
@@ -788,9 +864,6 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     useState<PrepareSendQuote | null>(null)
   const [onrampProviderQuote, setOnrampProviderQuote] =
     useState<OnrampQuote | null>(null)
-  const [prepareSendFn, setPrepareSendFn] = useState<
-    ((options?: SendOptions) => Promise<SwapReturn | null>) | null
-  >(null)
 
   // Store widget creation parameters for retry functionality
   const [widgetCreationParams, setWidgetCreationParams] = useState<{
@@ -831,73 +904,94 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   >(null)
   const { connectAsync } = useConnect()
 
-  const getInitialScreenForMode = useCallback((mode: Mode) => {
-    if (mode === "swap") {
-      return "swap"
-    } else if (mode === "earn") {
-      return "earn"
-    } else if (mode === "fund") {
-      return "fund-methods"
-    } else if (mode === "withdraw") {
-      return "withdraw"
-    } else if (mode === "pay") {
-      return "send-form"
-    } else {
-      return "send-form"
-    }
-  }, [])
-
-  const prevConfiguredModeRef = useRef(configuredMode)
+  const hasAppliedFundMethodNavigation = useRef<string | null>(null)
   useEffect(() => {
-    if (!isConnected) return
-    if (configuredMode === prevConfiguredModeRef.current) return
-    prevConfiguredModeRef.current = configuredMode
-    setCurrentScreen("home")
-  }, [configuredMode, isConnected, setCurrentScreen])
-
-  const goHome = useCallback(() => {
-    const initialScreen = getInitialScreenForMode(currentMode)
-    setCurrentScreen(initialScreen)
-  }, [currentMode, setCurrentScreen, getInitialScreenForMode])
+    const isWidgetActive = renderInline || isModalOpen
+    if (!isWidgetActive) {
+      hasAppliedFundMethodNavigation.current = null
+    }
+  }, [renderInline, isModalOpen])
 
   useEffect(() => {
-    if (currentScreen === "home") {
-      goHome()
+    const isWidgetActive = renderInline || isModalOpen
+    if (!isWidgetActive) return
+
+    let mappedFundMethod: FundMethod | null = null
+    if (configuredFundMethod === WidgetFundMethod.Wallet) {
+      mappedFundMethod = "wallet"
+    } else if (configuredFundMethod === WidgetFundMethod.CryptoTransfer) {
+      mappedFundMethod = "direct-transfer"
+    } else if (
+      configuredFundMethod === WidgetFundMethod.Onramp &&
+      currentMode !== "pay" &&
+      currentMode !== "earn"
+    ) {
+      mappedFundMethod = "onramp-meld"
+    } else if (
+      configuredFundMethod === WidgetFundMethod.OnrampExchange &&
+      currentMode !== "pay"
+    ) {
+      mappedFundMethod = "onramp-mesh"
     }
-  }, [currentScreen, goHome])
 
-  // Use the simple initial redirect hook
-  const { hasConnectedBefore } = useInitialRedirect(
-    isConnected,
+    if (!mappedFundMethod) return
+    if (selectedFundMethod === mappedFundMethod) return
+    setSelectedFundMethod(mappedFundMethod)
+  }, [
+    configuredFundMethod,
+    selectedFundMethod,
+    setSelectedFundMethod,
+    renderInline,
+    isModalOpen,
     currentMode,
-    getInitialScreenForMode,
-  )
+  ])
 
-  // Keep screen and wallet-connection state in sync without bouncing between screens
   useEffect(() => {
-    const connectionExemptScreens = [
-      "connect",
-      "wallet-connect",
-      "wallet-connection-pending",
-      "wallet-list",
-    ]
-
-    if (!isConnected && !connectionExemptScreens.includes(currentScreen)) {
-      setCurrentScreen("connect")
+    const isWidgetActive = renderInline || isModalOpen
+    if (!isWidgetActive) return
+    if (!isConnected) return
+    if (currentMode !== "fund") return
+
+    if (!configuredFundMethod) {
       return
     }
 
-    if (isConnected && connectionExemptScreens.includes(currentScreen)) {
-      setCurrentScreen(getInitialScreenForMode(currentMode))
+    const navKey = `${configuredFundMethod}:${currentMode}:${isWidgetActive}`
+    if (hasAppliedFundMethodNavigation.current === navKey) return
+    hasAppliedFundMethodNavigation.current = navKey
+
+    if (configuredFundMethod === WidgetFundMethod.Onramp) {
+      setSelectedFundMethod("onramp-meld")
+      navigate("fund-form")
+    } else if (configuredFundMethod === WidgetFundMethod.Wallet) {
+      setSelectedFundMethod("wallet")
+      navigate("tokens")
+    } else if (configuredFundMethod === WidgetFundMethod.CryptoTransfer) {
+      setSelectedFundMethod("direct-transfer")
+      navigate("fund-form")
+    } else if (configuredFundMethod === WidgetFundMethod.OnrampExchange) {
+      setSelectedFundMethod("onramp-mesh")
+      navigate("fund-form")
     }
   }, [
-    isConnected,
-    currentScreen,
     currentMode,
-    setCurrentScreen,
-    getInitialScreenForMode,
+    isConnected,
+    configuredFundMethod,
+    renderInline,
+    isModalOpen,
+    navigate,
+    setSelectedFundMethod,
   ])
 
+  useEffect(() => {
+    if (!isConnected || screen !== "connect") return
+    if (currentMode === "fund" && configuredFundMethod) return
+    goHome()
+  }, [isConnected, screen, currentMode, configuredFundMethod, goHome])
+
+  // Global wallet connection check — redirect to connect screen when disconnected
+  useScreenGuard(shouldRedirectToConnect(isConnected, screen), "connect")
+
   const modeToButtonText: Record<string, string> = {
     fund: "Fund",
     swap: "Swap",
@@ -1149,18 +1243,11 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   )
 
   // Auto-navigate from pending → receipt when first transaction is aborted or failed
-  useEffect(() => {
-    if (currentScreen !== "pending") return
-    if (!transactionStates || transactionStates.length === 0) return
-
-    const firstTx = transactionStates[0]
-    if (firstTx && hasFailedOrAbortedTransaction(firstTx)) {
-      logger.console.log(
-        `[trails-sdk] First transaction state is ${firstTx.state}, navigating to receipt`,
-      )
-      setCurrentScreen("receipt")
-    }
-  }, [transactionStates, currentScreen, setCurrentScreen])
+  const firstTx = transactionStates?.[0]
+  useScreenGuard(
+    screen === "pending" && !!firstTx && hasFailedOrAbortedTransaction(firstTx),
+    "receipt",
+  )
 
   const { checkoutOnHandlers } = useCheckout({
     onCheckoutStart,
@@ -1177,10 +1264,29 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   })
 
   const { clearSelectedFeeOption } = useSelectedFeeOption()
+  useExternalFundingReceiptSync({
+    enabled:
+      isExternalFundingMethod(selectedFundMethod) &&
+      !!prepareSendQuote?.intentId &&
+      (screen === "direct-transfer-screen" ||
+        screen === "onramp-confirmation" ||
+        screen === "pending"),
+    intentId: prepareSendQuote?.intentId ?? undefined,
+    fallbackTransactionStates: prepareSendQuote?.transactionStates,
+    setTransactionStates,
+    onStatusUpdate: checkoutOnHandlers?.triggerCheckoutStatusUpdate,
+    onFundingObserved: () => {
+      if (
+        screen === "direct-transfer-screen" ||
+        screen === "onramp-confirmation"
+      ) {
+        navigate("pending")
+      }
+    },
+  })
 
   // Use the debug screens hook
   const { handleDebugScreenSelect } = useDebugScreens({
-    setCurrentScreen,
     setSelectedToken,
     setTransactionStates,
     setPrepareSendQuote,
@@ -1188,30 +1294,20 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     setSelectedWalletId,
     setShowWalletConnectionRetry,
     setError,
-    setIsConnecting,
-    setOnrampProps,
     isConnected,
   })
 
   // Auto-detect mode changes and switch screens accordingly
-  useEffect(() => {
-    if (
-      selectedPool &&
-      (currentScreen === "send-form" || currentScreen === "fund-form")
-    ) {
-      const targetScreen = currentMode === "fund" ? "fund-form" : "send-form"
-      if (currentScreen !== targetScreen) {
-        setCurrentScreen(targetScreen)
-      }
-    }
-  }, [currentMode, currentScreen, selectedPool, setCurrentScreen])
+  const poolTargetScreen: Screen =
+    currentMode === "fund" ? "fund-form" : "send-form"
+  useScreenGuard(
+    !!selectedPool &&
+      (screen === "send-form" || screen === "fund-form") &&
+      screen !== poolTargetScreen,
+    poolTargetScreen,
+  )
 
-  useEffect(() => {
-    trackWidgetScreen({
-      screen: currentScreen,
-      userAddress: address || undefined,
-    })
-  }, [currentScreen, address])
+  useScreenTracking(address || undefined)
 
   useEffect(() => {
     const status = hostTransactionState.status
@@ -1225,27 +1321,27 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
     switch (status) {
       case "awaiting-origin":
-        setCurrentScreen("select-origin-token")
+        navigate("select-origin-token")
         break
       case "awaiting-amount":
-        setCurrentScreen("select-origin-amount")
+        navigate("select-origin-amount")
         break
       case "confirmation":
-        setCurrentScreen("wallet-confirmation")
+        navigate("wallet-confirmation")
         break
       case "pending":
-        setCurrentScreen("pending")
+        navigate("pending")
         break
       case "success":
       case "error":
         if (hostTransactionStates.length > 0) {
-          setCurrentScreen("receipt")
+          navigate("receipt")
         } else {
-          setCurrentScreen("pending")
+          navigate("pending")
         }
         break
       default:
-        setCurrentScreen("pending")
+        navigate("pending")
         break
     }
   }, [
@@ -1253,7 +1349,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     hostTransactionStates.length,
     isModalOpen,
     openTrailsModal,
-    setCurrentScreen,
+    navigate,
   ])
 
   useEffect(() => {
@@ -1305,14 +1401,14 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
         "earn",
       ]
 
-      if (screensToReset.includes(currentScreen)) {
+      if (screensToReset.includes(screen)) {
         logger.console.log(
           "[trails-sdk] Resetting to tokens screen due to account change",
-          currentScreen,
+          screen,
         )
-        if (previousScreen !== "select-funding-wallet") {
-          const initialScreen = getInitialScreenForMode(currentMode)
-          setCurrentScreen(initialScreen)
+        if (!state.stack.some((e) => e.screen === "select-funding-wallet")) {
+          const initialScreen = getInitialScreen(currentMode)
+          navigate(initialScreen)
           clearSelectedToken()
         }
         setError(null)
@@ -1326,12 +1422,11 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   }, [
     address,
     previousAddress,
-    currentScreen,
+    screen,
     currentMode,
     clearSelectedToken,
-    setCurrentScreen,
-    getInitialScreenForMode,
-    previousScreen,
+    navigate,
+    state.stack,
   ])
 
   // Update generated calldata when amount changes in earn mode
@@ -1466,9 +1561,9 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           // Navigate back to the origin screen (recipients)
           const originScreen = connectionContext.originScreen
           if (originScreen) {
-            setCurrentScreen(originScreen)
+            navigate(originScreen)
           } else {
-            setCurrentScreen("recipients")
+            navigate("recipients")
           }
         } else if (isFundMethodSelection) {
           logger.console.log(
@@ -1478,9 +1573,9 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           clearConnectionContext()
 
           if (currentMode === "fund") {
-            setCurrentScreen("tokens")
+            navigate("tokens", { backTarget: "fund-methods" })
           } else {
-            setCurrentScreen("home")
+            goHome()
           }
         } else {
           // Normal connection - switch active wallet and navigate home
@@ -1491,20 +1586,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           // Clear the connection context
           clearConnectionContext()
 
-          // Check if this is the first wallet connection
-          if (!hasConnectedBefore) {
-            // First connection - go to initial screen for the mode
-            logger.console.log(
-              "[trails-sdk] First wallet connection, going home",
-            )
-            goHome()
-          } else {
-            // Subsequent connection - go to home which will route to the appropriate screen
-            logger.console.log(
-              "[trails-sdk] Subsequent wallet connection, going to home",
-            )
-            goHome()
-          }
+          logger.console.log("[trails-sdk] Wallet connected, going home")
+          goHome()
         }
       } else if (walletConnector === getWalletConnectConnector()) {
         // Store the current connector as previous before switching to WalletConnect
@@ -1512,7 +1595,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           setPreviousConnector(connector)
         }
         // Route to dedicated WalletConnect screen where we show our own QR
-        setCurrentScreen("wallet-connect")
+        navigate("wallet-connect")
         setIsConnecting(false)
         return
       }
@@ -1560,7 +1643,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       logger.console.error("[trails-sdk] Failed to disconnect:", error)
     }
 
-    setCurrentScreen("connect")
+    navigate("connect")
   }
 
   const handleContinue = async () => {
@@ -1600,9 +1683,9 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       // Navigate back to the origin screen (recipients)
       const originScreen = connectionContext.originScreen
       if (originScreen) {
-        setCurrentScreen(originScreen)
+        navigate(originScreen)
       } else {
-        setCurrentScreen("recipients")
+        navigate("recipients")
       }
     } else if (isFundMethodSelection) {
       logger.console.log(
@@ -1612,22 +1695,22 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       clearConnectionContext()
 
       if (currentMode === "fund") {
-        setCurrentScreen("tokens")
+        navigate("tokens", { backTarget: "fund-methods" })
       } else {
-        setCurrentScreen("home")
+        goHome()
       }
     } else {
       // Normal flow - navigate based on mode
       if (currentMode === "swap") {
-        setCurrentScreen("swap")
+        navigate("swap")
       } else if (currentMode === "earn") {
-        setCurrentScreen("earn")
+        navigate("earn")
       } else if (currentMode === "fund") {
-        setCurrentScreen("fund-methods")
+        navigate("fund-methods")
       } else if (currentMode === "pay") {
-        setCurrentScreen("send-form")
+        navigate("send-form")
       } else {
-        setCurrentScreen("account-settings")
+        navigate("account-settings")
       }
     }
   }
@@ -1671,18 +1754,18 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       if (currentMode === "earn") {
         if (toAddress && toChainId) {
           // Skip earn-pools and go directly to send-form when toAddress and toChainId are specified
-          setCurrentScreen("send-form")
+          navigate("send-form")
         } else if (selectedPool) {
           // If a pool is already selected (auto-selected or manually), go to send-form
-          setCurrentScreen("send-form")
+          navigate("send-form")
         } else {
           // Go to earn-pools for pool selection when no specific destination is set
-          setCurrentScreen("earn-pools")
+          navigate("earn-pools")
         }
       } else if (currentMode === "swap") {
-        setCurrentScreen("swap")
+        navigate("swap")
       } else {
-        setCurrentScreen(currentMode === "fund" ? "fund-form" : "send-form")
+        navigate(currentMode === "fund" ? "fund-form" : "send-form")
       }
 
       handleTrackToken(token)
@@ -1772,16 +1855,11 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
   const handleSendAnother = () => {
     invalidateTokenBalancesCache()
-    const initialScreen = getInitialScreenForMode(currentMode)
-    setCurrentScreen(initialScreen)
     resetState()
   }
 
   const resetState = useCallback(() => {
-    resetMode()
     setSelectedFundMethod("wallet")
-    // Reset to appropriate screen based on mode
-    setCurrentScreen("home")
     setSelectedPool(null)
     setSelectedWalletId(null)
     setIsConnecting(false)
@@ -1794,13 +1872,12 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     setTransactionStates([])
     setPrepareSendQuote(null)
     setTotalCompletionSeconds(null)
-    clearHistory()
     // Clear selected fee option, but localStorage preference is preserved
     // Auto-selection will use the preference when fee options render next time
     clearSelectedFeeOption()
     resetHostTransactionState()
+    goHome()
   }, [
-    resetMode,
     setSelectedFundMethod,
     setDestinationTxHash,
     setDestinationChainId,
@@ -1808,19 +1885,11 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     setOriginTxHash,
     setOriginChainId,
     setSelectedPool,
-    setCurrentScreen,
-    clearHistory,
+    goHome,
     clearSelectedFeeOption,
     resetHostTransactionState,
   ])
 
-  // Update the currentScreen state when the widget receives an updated 'mode' prop passed in by the consuming app.
-  // This allows the widget to change modes without remounting the component.
-  useEffect(() => {
-    const initialScreen = getInitialScreenForMode(configuredMode)
-    setCurrentScreen(initialScreen)
-  }, [configuredMode, getInitialScreenForMode, setCurrentScreen])
-
   // When pendingSelection exists (from useTrailsSendTransaction),
   // open the modal and navigate to select-origin-token screen
   useEffect(() => {
@@ -1830,60 +1899,81 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
         openTrailsModal()
       }
       // Navigate to select-origin-token screen
-      if (currentScreen !== "select-origin-token") {
-        setCurrentScreen("select-origin-token")
+      if (screen !== "select-origin-token") {
+        navigate("select-origin-token")
       }
     }
-  }, [
-    pendingSelection,
-    isModalOpen,
-    currentScreen,
-    setCurrentScreen,
-    openTrailsModal,
-  ])
+  }, [pendingSelection, isModalOpen, screen, navigate, openTrailsModal])
+
+  const onOpenRef = useRef(onOpen)
+  onOpenRef.current = onOpen
+  const onCloseRef = useRef(onClose)
+  onCloseRef.current = onClose
+  const pendingSelectionRef = useRef(pendingSelection)
+  pendingSelectionRef.current = pendingSelection
+  const prepareSendQuoteRef = useRef(prepareSendQuote)
+  prepareSendQuoteRef.current = prepareSendQuote
+  const screenRef = useRef(screen)
+  screenRef.current = screen
+
+  const initialActiveConnectorRef = useRef<any>(null)
+  const initialActiveAddressRef = useRef<string | null>(null)
 
   const handleOpenModal = useCallback(() => {
+    if (!decoupleWagmi) {
+      initialActiveConnectorRef.current = connector ?? null
+      initialActiveAddressRef.current = address ?? null
+    }
     openTrailsModal()
-    onOpen?.()
-  }, [openTrailsModal, onOpen])
-
-  const screensWithCommittedIntent: Screen[] = [
-    "wallet-confirmation",
-    "onramp-confirmation",
-  ]
+    onOpenRef.current?.()
+  }, [openTrailsModal, decoupleWagmi, connector, address])
 
   const handleCloseModal = useCallback(() => {
-    if (
-      prepareSendQuote?.intentId &&
-      screensWithCommittedIntent.includes(currentScreen)
-    ) {
-      removeStoredIntent(prepareSendQuote.intentId)
-    }
-    if (pendingSelection) {
+    const pending = pendingSelectionRef.current
+    if (pending) {
       logger.console.log(
         "[trails-sdk] handleCloseModal called, rejecting pending selection",
       )
-      pendingSelection.reject(new Error("Modal closed by user"))
+      pending.reject(new Error("Modal closed by user"))
       setPendingSelection(undefined)
     } else {
       logger.console.log(
         "[trails-sdk] handleCloseModal called, no pending selection",
       )
     }
+
+    if (!decoupleWagmi && initialActiveConnectorRef.current) {
+      const originalStillConnected = connections.some(
+        (c) => c.connector.id === initialActiveConnectorRef.current?.id,
+      )
+      if (
+        originalStillConnected &&
+        initialActiveConnectorRef.current.id !== connector?.id
+      ) {
+        logger.console.log(
+          "[trails-sdk] Restoring host app active wallet:",
+          initialActiveAddressRef.current,
+        )
+        switchAccount({ connector: initialActiveConnectorRef.current })
+      }
+    }
+    initialActiveConnectorRef.current = null
+    initialActiveAddressRef.current = null
+
     logger.console.log("[trails-sdk] handleCloseModal called, closing modal")
     closeTrailsModal()
     resetState()
     resetHostTransactionState()
-    onClose?.()
+    onCloseRef.current?.()
   }, [
     closeTrailsModal,
     resetState,
     resetHostTransactionState,
-    onClose,
-    pendingSelection,
     setPendingSelection,
-    prepareSendQuote,
-    currentScreen,
+    decoupleWagmi,
+    connections,
+    connector,
+    switchAccount,
   ])
 
   // Register handleCloseModal with TrailsModalProvider so ScreenHeader can use it
@@ -1906,7 +1996,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   )
 
   function handleWalletConfirmComplete() {
-    setCurrentScreen("pending")
+    navigate("pending")
   }
 
   function handleElapsedTime(totalCompletionSeconds: number = 0) {
@@ -1943,11 +2033,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       setDestinationChainId(lastTransactionState?.chainId)
     }
 
-    // clear the stored intent from local storage
-    if (prepareSendQuote?.intentId) {
-      removeStoredIntent(prepareSendQuote.intentId)
-    }
-    setCurrentScreen("receipt")
+    navigate("receipt")
   }
 
   async function handleOnrampComplete(transferData: OnrampTransferResult) {
@@ -1958,7 +2044,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     logger.console.log("[trails-sdk] handleOnrampComplete state:", {
       hasOnrampContinueSend: !!onrampContinueSend,
       hasPrepareSendQuote: !!prepareSendQuote,
-      currentScreen,
+      screen,
       onrampContinueSendInProgress,
     })
 
@@ -1978,7 +2064,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
     // Navigate away from onramp screen immediately
     logger.console.log("[trails-sdk] Navigating away from onramp screen")
-    setCurrentScreen("pending")
+    navigate("pending")
 
     // Continue with the send flow after onramp completes
     if (onrampContinueSend) {
@@ -2036,7 +2122,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
     // Navigate to pending screen immediately
     logger.console.log("[trails-sdk] Navigating to pending screen")
-    setCurrentScreen("pending")
+    navigate("pending")
 
     // Continue with the send flow after deposit is confirmed
     if (onrampContinueSend) {
@@ -2082,7 +2168,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       setPreviousConnector(connector)
     }
     setSelectedWalletId(null)
-    setCurrentScreen("wallet-connect")
+    navigate("wallet-connect")
   }
 
   const handleReconnectPreviousWallet = async () => {
@@ -2108,11 +2194,11 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           error,
         )
         // If reconnection fails, go back to fund methods
-        setCurrentScreen("fund-methods")
+        navigate("fund-methods")
       }
     } else {
       // If no previous connector, go back to fund methods
-      setCurrentScreen("fund-methods")
+      navigate("fund-methods")
     }
   }
 
@@ -2164,7 +2250,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       onRampMethod && onRampMethod === "onramp-meld"
         ? "onramp-meld"
         : "onramp-mesh"
-    setCurrentScreen(targetScreen)
+    navigate(targetScreen)
 
     if (
       targetScreen === "onramp-meld" &&
@@ -2240,10 +2326,6 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     setPrepareSendQuote(quote ?? null)
     // Navigate to QR wallet selection when using QR code funding method
     if (selectedFundMethod === "direct-transfer") {
-      if (sendFn) {
-        setPrepareSendFn(() => sendFn)
-      }
-
       if (!sendFn) {
         handleSendError(
           "Unable to continue: direct-transfer send function is missing.",
@@ -2252,17 +2334,18 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       }
 
       setError(null)
+
       void (async () => {
         try {
-          await sendFn({ commitOnly: true, skipIntentMonitoring: true })
-          setCurrentScreenWithBack("direct-transfer-screen", currentScreen)
+          await sendFn()
+          navigate("direct-transfer-screen", { backTarget: screen })
         } catch (error) {
           handleSendError(error as Error | string | null)
         }
       })()
       return
     }
-    setCurrentScreen("wallet-confirmation")
+    navigate("wallet-confirmation")
   }
 
   const handleWaitingOnrampConfirm = (
@@ -2279,7 +2362,6 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       paymentMethodType?: string
     },
     sessionId?: string,
-    sendFn?: ((options?: SendOptions) => Promise<SwapReturn | null>) | null,
     popupWindowRef?: Window | null,
   ) => {
     logger.console.log(
@@ -2288,9 +2370,6 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     )
     setPrepareSendQuote(quote ?? null)
     setOnrampProviderQuote(onrampProviderQuote ?? null)
-    if (sendFn) {
-      setPrepareSendFn(() => sendFn)
-    }
     setOnrampPopupWindowRef(popupWindowRef ?? null)
     if (params) {
       setWidgetCreationParams(params)
@@ -2304,7 +2383,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       )
       setExternalSessionId(null)
     }
-    setCurrentScreen("onramp-confirmation")
+    navigate("onramp-confirmation")
   }
 
   async function handleWalletConfirmRetry() {
@@ -2327,7 +2406,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   const { targetAmountUsd, targetAmountUsdFormatted } = useTargetAmount()
 
   const renderScreenContent = () => {
-    switch (currentScreen) {
+    switch (screen) {
       case "connect": {
         const showDisconnect = !decoupleWagmi && !hideDisconnect
         return (
@@ -2354,20 +2433,20 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
               // Check if we need to show WalletConnect QR
               // Don't show QR if we have an EIP-6963 connector or injected connector
               const shouldShowQR =
-                !isEIP6963Connector &&
-                walletConnector === getWalletConnectConnector()
+                !isEIP6963Connector && isWalletConnectConnector(walletConnector)
 
               if (shouldShowQR) {
                 saveLastClickedWallet(walletId)
-                setCurrentScreen("wallet-connect")
+                navigate("wallet-connect")
               } else {
                 saveLastClickedWallet(walletId)
                 // Preserve the existing back route from the navigation stack
-                const backRoute = getPreviousScreen()
-                setCurrentScreenWithBack(
-                  "wallet-connection-pending",
-                  backRoute || undefined,
-                )
+                const backRoute = backScreen
+                const safeBackRoute =
+                  backRoute === "wallet-confirmation" ? undefined : backRoute
+                navigate("wallet-connection-pending", {
+                  backTarget: safeBackRoute || undefined,
+                })
                 // Auto-trigger connection - pass the actual connector
                 setTimeout(() => {
                   handleConnectWallet(walletId, walletConnector)
@@ -2391,44 +2470,52 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
                 : "Choose a funding method"
             }
             onBack={() => {
-              const previous = getPreviousScreen()
-              if (previous) {
+              if (currentMode !== configuredMode) {
                 resetMode()
-                goBack?.()
-              } else {
-                goHome()
+                return
+              }
+
+              if (canGoBack) {
+                goBack()
+                return
               }
+
+              goHome()
             }}
             onramp={onrampFactory}
             onSelectWalletConnect={handleSelectWalletConnect}
             onSelectConnectedAccount={() => {
+              clearStateForFundMethodSwitch("wallet")
               setSelectedFundMethod("wallet")
               if (currentMode === "fund") {
-                setCurrentScreen("select-origin-token")
+                navigate("select-origin-token", { backTarget: "fund-methods" })
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
             onSelectTransferCrypto={() => {
+              clearStateForFundMethodSwitch("direct-transfer")
               setSelectedFundMethod("direct-transfer")
               if (currentMode === "fund") {
-                setCurrentScreenWithBack("fund-form", "fund-methods")
+                navigate("fund-form", { backTarget: "fund-methods" })
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
             onSelectOnrampMeld={() => {
+              clearStateForFundMethodSwitch("onramp-meld")
               if (currentMode === "fund") {
-                setCurrentScreen("fund-form")
+                navigate("fund-form")
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
             onSelectOnrampExchange={() => {
+              clearStateForFundMethodSwitch("onramp-mesh")
               if (currentMode === "fund") {
-                setCurrentScreen("fund-form")
+                navigate("fund-form")
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
           />
@@ -2439,33 +2526,31 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onBack={() => goHome()}
             onSelectWalletConnect={handleSelectWalletConnect}
             onSelectConnectedAccount={() => {
+              clearStateForFundMethodSwitch("wallet")
               setSelectedFundMethod("wallet")
-              setCurrentScreen("home")
+              goHome()
             }}
             onSelectQrCode={() => {
-              setCurrentScreenWithBack("qrcode-options", "payment-methods")
+              navigate("qrcode-options", { backTarget: "payment-methods" })
             }}
           />
         )
       case "select-funding-wallet":
         return <FundWalletSelection />
       case "onramp-payment-methods":
-        return (
-          <OnrampPaymentMethods
-            onBack={() => setCurrentScreen("fund-methods")}
-          />
-        )
+        return <OnrampPaymentMethods onBack={() => navigate("fund-methods")} />
       case "qrcode-options":
         return (
           <QRCodeOptions
             onBack={handleBack}
             onSelectWalletConnect={handleSelectWalletConnect}
             onSelectQRCode={() => {
+              clearStateForFundMethodSwitch("direct-transfer")
               setSelectedFundMethod("direct-transfer")
               if (currentMode === "fund") {
-                setCurrentScreen("fund-form")
+                navigate("fund-form")
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
           />
@@ -2482,14 +2567,14 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onRecentTokenSelect={handleRecentTokenSelect}
             fundMethod={selectedFundMethod}
             renderInline={renderInline}
-            onNavigateToFundMethods={() => setCurrentScreen("fund-methods")}
+            onNavigateToFundMethods={() => navigate("fund-methods")}
           />
         )
       case "select-origin-token":
         return (
           <TokenList
             onContinue={handleTokenSelect}
-            onBack={handleCloseModal}
+            onBack={handleBack}
             targetAmountUsd={null}
             targetAmountUsdFormatted={null}
             onError={handleTokenListError}
@@ -2503,7 +2588,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
         return (
           <OriginSelectionAmount
             token={selectedToken}
-            onBack={() => setCurrentScreen("select-origin-token")}
+            onBack={() => navigate("select-origin-token")}
             onCancel={handleCloseModal}
             onSubmit={handleOriginAmountSubmit}
           />
@@ -2515,7 +2600,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             selectedToken={selectedToken}
             onSend={handleOnSend}
             onWaitingForWalletConfirm={handleWaitingForWalletConfirm}
-            onConfirm={() => setCurrentScreen("pending")}
+            onConfirm={() => navigate("pending")}
             onComplete={handleTransferComplete}
             account={walletClient?.account}
             toRecipient={
@@ -2587,9 +2672,9 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onSend={handleOnSend}
             onWaitingForWalletConfirm={handleWaitingForWalletConfirm}
             onrampPropsCallback={setOnrampProps}
-            screenNavigationCallback={setCurrentScreen}
+            screenNavigationCallback={navigate}
             onWaitingForOnrampConfirm={handleWaitingOnrampConfirm}
-            onConfirm={() => setCurrentScreen("pending")}
+            onConfirm={() => navigate("pending")}
             onComplete={handleTransferComplete}
             account={walletClient?.account}
             toAmount={toAmount || undefined}
@@ -2622,18 +2707,17 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onBack={handleBack}
             onRetry={() => {
               // Go back to fund screen to regenerate widget session
-              setCurrentScreen("fund-form")
+              navigate("fund-form")
             }}
             onIntentExecuted={() => {
               // Navigate to pending screen when intent is executed
-              setCurrentScreen("pending")
+              navigate("pending")
             }}
             quote={prepareSendQuote}
             onRampQuote={onrampProviderQuote}
             widgetCreationParams={widgetCreationParams}
             onCreateWidgetSession={createWidgetSession}
             externalSessionId={externalSessionId}
-            sendFn={prepareSendFn}
             popupWindowRef={onrampPopupWindowRef}
           />
         )
@@ -2675,7 +2759,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onBack={handleBack}
             onSelect={(walletId) => {
               setQrCodeWalletId(walletId)
-              setCurrentScreen("direct-transfer-screen")
+              navigate("direct-transfer-screen")
             }}
             selectedWalletId={qrCodeWalletId}
           />
@@ -2685,27 +2769,18 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           <DirectTransfer
             onBack={() => {
               if (currentMode === "fund") {
-                setCurrentScreen("fund-form")
+                navigate("fund-form")
               } else {
-                setCurrentScreen("home")
+                goHome()
               }
             }}
-            onChangeWallet={() => setCurrentScreen("qr-code-wallet-select")}
+            onChangeWallet={() => navigate("qr-code-wallet-select")}
             quote={prepareSendQuote}
             selectedWalletId={qrCodeWalletId}
             walletOptions={qrCodeWallets}
-            sendFn={prepareSendFn}
-            onIntentExecuted={() => setCurrentScreen("pending")}
+            onIntentExecuted={() => navigate("pending")}
           />
         )
-      // case "onramp-meld":
-      //   return (
-      //     <OnrampDeposit
-      //       onBack={handleBack}
-      //       quote={prepareSendQuote}
-      //       onDepositComplete={handleOnrampDepositComplete}
-      //     />
-      //   )
       case "pending":
         return (
           <TransferPending
@@ -2716,7 +2791,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             timestamp={hostTransactionTimestamp ?? undefined}
             onContinue={() => {
               logger.console.log("[trails-sdk] onContinue called")
-              setCurrentScreen("receipt")
+              navigate("receipt")
             }}
           />
         )
@@ -2789,7 +2864,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             <div className="flex flex-col h-full">
               {onrampFactory({
                 setCurrentScreen: (screen) => {
-                  setCurrentScreen(screen)
+                  navigate(screen)
                 },
                 onComplete: handleOnrampComplete,
                 onError: (error) => {
@@ -2835,7 +2910,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             </div>
           )
         }
-      case "meld-onramp":
+      case "onramp-meld":
         return <MeldStepsFlow onBack={handleBack} />
       case "wallet-connect":
         return (
@@ -2857,14 +2932,17 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
               )
 
               if (
-                allWallets.find((w) => w.id === walletId)?.connector ===
-                getWalletConnectConnector()
+                isWalletConnectConnector(
+                  allWallets.find((w) => w.id === walletId)?.connector as
+                    | Connector
+                    | undefined,
+                )
               ) {
                 saveLastClickedWallet(walletId)
                 logger.console.log(
                   "[trails-sdk] WalletConnect selected, going to wallet-connect screen",
                 )
-                setCurrentScreen("wallet-connect")
+                navigate("wallet-connect")
               } else {
                 saveLastClickedWallet(walletId)
                 logger.console.log(
@@ -2873,11 +2951,12 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
                 // Don't reset the redirect flag - user has already been through initial flow
                 setTimeout(() => {
                   // Preserve the existing back route from the navigation stack
-                  const backRoute = getPreviousScreen()
-                  setCurrentScreenWithBack(
-                    "wallet-connection-pending",
-                    backRoute || undefined,
-                  )
+                  const backRoute = backScreen
+                  const safeBackRoute =
+                    backRoute === "wallet-confirmation" ? undefined : backRoute
+                  navigate("wallet-connection-pending", {
+                    backTarget: safeBackRoute || undefined,
+                  })
                 }, 100)
                 // Auto-trigger connection
                 setTimeout(() => {
@@ -2896,13 +2975,13 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       case "earn":
         return (
           <Earn
-            onContinue={() => setCurrentScreen("send-form")}
+            onContinue={() => navigate("send-form")}
             account={walletClient?.account}
             walletClient={walletClient ?? undefined}
             onTransactionStateChange={handleTransactionStateChange}
             onError={handleSendError}
             onWaitingForWalletConfirm={handleWaitingForWalletConfirm}
-            onConfirm={() => setCurrentScreen("pending")}
+            onConfirm={() => navigate("pending")}
             onComplete={handleTransferComplete}
             onSend={handleOnSend}
             paymasterUrls={paymasterUrls}
@@ -2925,7 +3004,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onPoolSelect={(pool) => {
               logger.console.log("Selected pool:", pool)
               setSelectedPool(pool)
-              setCurrentScreen("send-form")
+              navigate("send-form")
             }}
           />
         )
@@ -2935,7 +3014,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             onSend={handleOnSend}
             onWaitingForWalletConfirm={handleWaitingForWalletConfirm}
             onWaitingForOnrampConfirm={handleWaitingOnrampConfirm}
-            onConfirm={() => setCurrentScreen("pending")}
+            onConfirm={() => navigate("pending")}
             onComplete={handleTransferComplete}
             selectedToken={selectedToken}
             account={walletClient?.account}
@@ -2967,7 +3046,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           <Withdraw
             onSend={handleOnSend}
             onWaitingForWalletConfirm={handleWaitingForWalletConfirm}
-            onConfirm={() => setCurrentScreen("pending")}
+            onConfirm={() => navigate("pending")}
             onComplete={handleTransferComplete}
             selectedToken={selectedToken}
             account={walletClient?.account}
@@ -3027,7 +3106,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       case "user-preferences":
         return <UserPreferences onBack={handleBack} />
       case "chain-list":
-        return <ChainList onBack={() => setCurrentScreen("tokens")} />
+        return <ChainList onBack={() => navigate("tokens")} />
       case "recipients":
         return <Recipients onBack={handleBack} />
       case "disconnect":
@@ -3037,13 +3116,10 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             disconnectHandler={handleWalletDisconnect}
           />
         )
-      case "home": {
-        // Navigation handled by useEffect above, otherwise it would cause a loop
-        return null
-      }
-      default:
-        return null
     }
+
+    const unhandledScreen: never = screen
+    throw new Error(`[trails-sdk] Unhandled screen state: ${unhandledScreen}`)
   }
 
   const renderScreen = () => {
@@ -3072,7 +3148,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
         >
           <AnimatePresence mode="wait">
             <motion.div
-              key={currentScreen}
+              key={screen}
               initial={{ opacity: 0, x: 20 }}
               animate={{ opacity: 1, x: 0 }}
               exit={{ opacity: 0, x: -20 }}
@@ -3164,11 +3240,24 @@ export const TrailsWidget = forwardRef<TrailsWidgetRef, TrailsWidgetProps>(
 
     // Memoize connectors separately to ensure stable references
     const connectors = React.useMemo(() => {
-      if (Array.isArray(props.wagmiConnectors)) {
+      if (!Array.isArray(props.wagmiConnectors)) {
+        return getConnectorsInternal(props.apiKey, props.trailsApiUrl)
+      }
+
+      if (
+        props.wagmiConnectors.some((connector) =>
+          isWalletConnectConnector(connector),
+        )
+      ) {
         return props.wagmiConnectors
       }
-      return getConnectorsInternal(props.apiKey)
-    }, [props.apiKey, props.wagmiConnectors])
+
+      logger.console.warn(
+        "[trails-sdk] wagmiConnectors is missing WalletConnect connector; appending internal WalletConnect connector to avoid broken QR flow",
+      )
+      // TODO: Remove this append fallback in a future major release. The correct long-term behavior may be to hide WalletConnect options when consumers intentionally omit the connector.
+      return [...props.wagmiConnectors, getWalletConnectConnector()]
+    }, [props.apiKey, props.trailsApiUrl, props.wagmiConnectors])
 
     // Create stable wagmi config using useMemo with minimal dependencies
     const wagmiConfig = React.useMemo(() => {