0xtrails 0.12.2 → 0.13.0

package/src/widget/hooks/useViewManager.tsx

@@ -0,0 +1,505 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+} from "react"
+import type { ReactNode } from "react"
+import { logger } from "../../logger.js"
+
+export type Mode = "pay" | "fund" | "earn" | "swap" | "withdraw"
+
+export type Screen =
+  | "connect"
+  | "tokens"
+  | "select-origin-token"
+  | "select-origin-amount"
+  | "send-form"
+  | "fund-form"
+  | "fund-methods"
+  | "payment-methods"
+  | "select-funding-wallet"
+  | "onramp-payment-methods"
+  | "recipients"
+  | "earn-pools"
+  | "earn"
+  | "swap"
+  | "withdraw"
+  | "wallet-confirmation"
+  | "qr-code-wallet-select"
+  | "direct-transfer-screen"
+  | "onramp-meld"
+  | "pending"
+  | "receipt"
+  | "onramp-mesh"
+  | "wallet-connect"
+  | "wallet-list"
+  | "wallet-connection-pending"
+  | "account-history"
+  | "account-settings"
+  | "user-preferences"
+  | "chain-list"
+  | "disconnect"
+  | "qrcode-options"
+  | "meld-history"
+  | "onramp-confirmation"
+
+export interface NavigationEvent {
+  from: Screen
+  to: Screen
+}
+
+export type NavigationListener = (event: NavigationEvent) => void
+
+export interface StackEntry {
+  screen: Screen
+  backTarget?: Screen
+  key: string
+  timestamp: number
+}
+
+export interface ViewState {
+  screen: Screen
+  mode: Mode
+  configuredMode: Mode
+  stack: StackEntry[]
+  direction: "forward" | "backward" | "none"
+  screenData: Record<string, unknown> | null
+}
+
+export type ViewAction =
+  | {
+      type: "NAVIGATE"
+      screen: Screen
+      backTarget?: Screen
+      data?: Record<string, unknown>
+    }
+  | { type: "GO_BACK" }
+  | { type: "SET_MODE"; mode: Mode }
+  | { type: "OVERRIDE_MODE"; mode: Mode }
+  | { type: "RESET_MODE" }
+  | { type: "GO_HOME" }
+  | { type: "RESET"; initialScreen?: Screen }
+  | { type: "GO_BACK_TO"; screen: Screen }
+  | { type: "REPLACE"; screen: Screen; data?: Record<string, unknown> }
+
+const MAX_STACK_SIZE = 20
+
+export function getInitialScreen(mode: Mode): Screen {
+  switch (mode) {
+    case "swap":
+      return "swap"
+    case "earn":
+      return "earn"
+    case "fund":
+      return "fund-methods"
+    case "pay":
+      return "send-form"
+    case "withdraw":
+      return "withdraw"
+  }
+}
+
+export function createEntryKey(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    return crypto.randomUUID().slice(0, 8)
+  }
+  return Math.random().toString(36).slice(2, 10)
+}
+
+function createEntry(screen: Screen, backTarget?: Screen): StackEntry {
+  return {
+    screen,
+    backTarget,
+    key: createEntryKey(),
+    timestamp: Date.now(),
+  }
+}
+
+export function viewReducer(state: ViewState, action: ViewAction): ViewState {
+  switch (action.type) {
+    case "NAVIGATE": {
+      const currentEntry = state.stack[state.stack.length - 1]
+      const nextData = action.data ?? null
+      if (
+        state.screen === action.screen &&
+        currentEntry?.backTarget === action.backTarget &&
+        state.screenData === nextData
+      ) {
+        return state
+      }
+
+      const entry = createEntry(action.screen, action.backTarget)
+
+      return {
+        ...state,
+        screen: action.screen,
+        stack: [...state.stack, entry].slice(-MAX_STACK_SIZE),
+        direction: "forward",
+        screenData: action.data ?? null,
+      }
+    }
+
+    case "GO_BACK": {
+      if (state.stack.length <= 1) return state
+
+      const currentEntry = state.stack[state.stack.length - 1]
+      if (currentEntry?.backTarget) {
+        const targetIndex = state.stack.findLastIndex(
+          (e, index) =>
+            e.screen === currentEntry.backTarget &&
+            index < state.stack.length - 1,
+        )
+        const newStack =
+          targetIndex >= 0
+            ? state.stack.slice(0, targetIndex + 1)
+            : state.stack.slice(0, -1)
+        const newScreen =
+          newStack[newStack.length - 1]?.screen ?? getInitialScreen(state.mode)
+
+        return {
+          ...state,
+          screen: newScreen,
+          stack: newStack,
+          direction: "backward",
+          screenData: null,
+        }
+      }
+
+      const newStack = state.stack.slice(0, -1)
+      const newScreen =
+        newStack[newStack.length - 1]?.screen ?? getInitialScreen(state.mode)
+
+      return {
+        ...state,
+        screen: newScreen,
+        stack: newStack,
+        direction: "backward",
+        screenData: null,
+      }
+    }
+
+    case "GO_BACK_TO": {
+      const targetIndex = state.stack.findLastIndex(
+        (e) => e.screen === action.screen,
+      )
+      if (targetIndex < 0) return state
+
+      const newStack = state.stack.slice(0, targetIndex + 1)
+
+      return {
+        ...state,
+        screen: action.screen,
+        stack: newStack,
+        direction: "backward",
+        screenData: null,
+      }
+    }
+
+    case "REPLACE": {
+      const nextData = action.data ?? null
+      if (state.screen === action.screen && state.screenData === nextData) {
+        return state
+      }
+
+      const newStack = [...state.stack]
+      if (newStack.length > 0) {
+        newStack[newStack.length - 1] = createEntry(action.screen)
+      } else {
+        newStack.push(createEntry(action.screen))
+      }
+
+      return {
+        ...state,
+        screen: action.screen,
+        stack: newStack,
+        direction: "none",
+        screenData: action.data ?? null,
+      }
+    }
+
+    case "SET_MODE": {
+      const initialScreen = getInitialScreen(action.mode)
+      return {
+        ...state,
+        mode: action.mode,
+        configuredMode: action.mode,
+        screen: initialScreen,
+        stack: [createEntry(initialScreen)],
+        direction: "none",
+        screenData: null,
+      }
+    }
+
+    case "OVERRIDE_MODE": {
+      const initialScreen = getInitialScreen(action.mode)
+      return {
+        ...state,
+        mode: action.mode,
+        screen: initialScreen,
+        stack: [createEntry(initialScreen)],
+        direction: "none",
+        screenData: null,
+      }
+    }
+
+    case "RESET_MODE": {
+      const initialScreen = getInitialScreen(state.configuredMode)
+      return {
+        ...state,
+        mode: state.configuredMode,
+        screen: initialScreen,
+        stack: [createEntry(initialScreen)],
+        direction: "none",
+        screenData: null,
+      }
+    }
+
+    case "GO_HOME": {
+      const homeScreen = getInitialScreen(state.mode)
+      return {
+        ...state,
+        screen: homeScreen,
+        stack: [createEntry(homeScreen)],
+        direction: "backward",
+        screenData: null,
+      }
+    }
+
+    case "RESET": {
+      const initialScreen =
+        action.initialScreen ?? getInitialScreen(state.configuredMode)
+      return {
+        ...state,
+        mode: state.configuredMode,
+        screen: initialScreen,
+        stack: [createEntry(initialScreen)],
+        direction: "none",
+        screenData: null,
+      }
+    }
+
+    default:
+      return state
+  }
+}
+
+export function createInitialState(configuredMode: Mode): ViewState {
+  const initialScreen = getInitialScreen(configuredMode)
+  return {
+    screen: initialScreen,
+    mode: configuredMode,
+    configuredMode,
+    stack: [createEntry(initialScreen)],
+    direction: "none",
+    screenData: null,
+  }
+}
+
+export interface ViewManagerContextValue {
+  state: ViewState
+  dispatch: React.Dispatch<ViewAction>
+  navigate: (
+    screen: Screen,
+    options?: { backTarget?: Screen; data?: Record<string, unknown> },
+  ) => void
+  goBack: () => void
+  goBackTo: (screen: Screen) => void
+  replace: (screen: Screen, data?: Record<string, unknown>) => void
+  goHome: () => void
+  reset: (initialScreen?: Screen) => void
+  overrideMode: (mode: Mode) => void
+  resetMode: () => void
+  subscribe: SubscribeFn
+  canGoBack: boolean
+  backScreen: Screen | null
+  direction: "forward" | "backward" | "none"
+  mode: Mode
+  configuredMode: Mode
+  screen: Screen
+}
+
+type SubscribeFn = (listener: NavigationListener) => () => void
+
+const ViewManagerContext = createContext<ViewManagerContextValue | null>(null)
+
+interface ViewManagerProviderProps {
+  children: ReactNode
+  configuredMode: Mode
+}
+
+export function ViewManagerProvider({
+  children,
+  configuredMode,
+}: ViewManagerProviderProps) {
+  const [state, dispatch] = useReducer(
+    viewReducer,
+    configuredMode,
+    createInitialState,
+  )
+
+  const prevConfiguredModeRef = useRef(configuredMode)
+  useEffect(() => {
+    if (configuredMode === prevConfiguredModeRef.current) return
+    prevConfiguredModeRef.current = configuredMode
+    dispatch({ type: "SET_MODE", mode: configuredMode })
+  }, [configuredMode])
+
+  const listenersRef = useRef(new Set<NavigationListener>())
+  const prevScreenRef = useRef(state.screen)
+
+  useEffect(() => {
+    const prev = prevScreenRef.current
+    prevScreenRef.current = state.screen
+    if (prev !== state.screen) {
+      const event: NavigationEvent = { from: prev, to: state.screen }
+      for (const listener of listenersRef.current) {
+        try {
+          listener(event)
+        } catch (error) {
+          logger.console.error("[trails-sdk] Navigation listener error", error)
+        }
+      }
+    }
+  }, [state.screen])
+
+  const subscribe: SubscribeFn = useCallback((listener) => {
+    listenersRef.current.add(listener)
+    return () => {
+      listenersRef.current.delete(listener)
+    }
+  }, [])
+
+  const navigate = useCallback(
+    (
+      screen: Screen,
+      options?: { backTarget?: Screen; data?: Record<string, unknown> },
+    ) => {
+      dispatch({
+        type: "NAVIGATE",
+        screen,
+        backTarget: options?.backTarget,
+        data: options?.data,
+      })
+    },
+    [],
+  )
+
+  const goBack = useCallback(() => {
+    dispatch({ type: "GO_BACK" })
+  }, [])
+
+  const goBackTo = useCallback((screen: Screen) => {
+    dispatch({ type: "GO_BACK_TO", screen })
+  }, [])
+
+  const replace = useCallback(
+    (screen: Screen, data?: Record<string, unknown>) => {
+      dispatch({ type: "REPLACE", screen, data })
+    },
+    [],
+  )
+
+  const goHome = useCallback(() => {
+    dispatch({ type: "GO_HOME" })
+  }, [])
+
+  const reset = useCallback((initialScreen?: Screen) => {
+    dispatch({ type: "RESET", initialScreen })
+  }, [])
+
+  const overrideMode = useCallback(
+    (m: Mode) => dispatch({ type: "OVERRIDE_MODE", mode: m }),
+    [],
+  )
+
+  const resetMode = useCallback(() => dispatch({ type: "RESET_MODE" }), [])
+
+  const canGoBack = state.stack.length > 1
+
+  const backScreen = useMemo((): Screen | null => {
+    if (state.stack.length <= 1) return null
+
+    const currentEntry = state.stack[state.stack.length - 1]
+    if (currentEntry?.backTarget) {
+      return currentEntry.backTarget
+    }
+
+    const previousEntry = state.stack[state.stack.length - 2]
+    return previousEntry?.screen ?? null
+  }, [state.stack])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: stable dispatch wrappers omitted intentionally
+  const value = useMemo<ViewManagerContextValue>(
+    () => ({
+      state,
+      dispatch,
+      navigate,
+      goBack,
+      goBackTo,
+      replace,
+      goHome,
+      reset,
+      overrideMode,
+      resetMode,
+      canGoBack,
+      backScreen,
+      direction: state.direction,
+      mode: state.mode,
+      configuredMode: state.configuredMode,
+      screen: state.screen,
+      subscribe,
+    }),
+    [state, canGoBack, backScreen],
+  )
+
+  return (
+    <ViewManagerContext.Provider value={value}>
+      {children}
+    </ViewManagerContext.Provider>
+  )
+}
+
+export function useViewManager(): ViewManagerContextValue {
+  const context = useContext(ViewManagerContext)
+  if (!context) {
+    throw new Error("useViewManager must be used within a ViewManagerProvider")
+  }
+  return context
+}
+
+export function useNavigationEffect(callback: NavigationListener) {
+  const { subscribe } = useViewManager()
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  useEffect(() => {
+    return subscribe((event) => callbackRef.current(event))
+  }, [subscribe])
+}
+
+export function useScreenGuard(
+  condition: boolean,
+  target: Screen,
+  options?: { backTarget?: Screen },
+): boolean {
+  const { replace, navigate } = useViewManager()
+
+  useEffect(() => {
+    if (!condition) return
+
+    if (options?.backTarget) {
+      navigate(target, { backTarget: options.backTarget })
+    } else {
+      replace(target)
+    }
+  }, [condition, target, options?.backTarget, replace, navigate])
+
+  return condition
+}

package/src/widget/hooks/useWalletConnectUri.tsx

@@ -1,12 +1,10 @@
 import { useEffect, useCallback, useRef, useState } from "react"
 import { useConnect, useConnectors, type Connector } from "wagmi"
-import { walletConnect } from "wagmi/connectors"
 import { useTrails } from "../providers/TrailsProvider.js"
 import { logger } from "../../logger.js"
 
-/** Connectors from useConnectors() have emitter; raw CreateConnectorFn from walletConnect() does not. */
 function getConnectorEmitter(
-  connector: ReturnType<typeof walletConnect> | Connector,
+  connector: Connector,
 ): Connector["emitter"] | null {
   if (typeof connector === "object" && "emitter" in connector) {
     return connector.emitter
@@ -14,20 +12,22 @@ function getConnectorEmitter(
   return null
 }
 
-// Local singleton to avoid multiple Core initializations
-let wcConnectorSingleton: ReturnType<typeof walletConnect> | null = null
-function getWalletConnectConnector(projectId: string) {
-  if (!wcConnectorSingleton) {
-    logger.console.log(
-      "[trails-sdk] [useWalletConnectUri] Creating new connector with projectId:",
-      projectId,
-    )
-    wcConnectorSingleton = walletConnect({
-      projectId: projectId,
-      showQrModal: false,
-    })
+function getUriFromProvider(provider: unknown): string | null {
+  if (provider == null || typeof provider !== "object") {
+    return null
   }
-  return wcConnectorSingleton
+
+  const providerRecord = provider as {
+    connector?: { uri?: unknown }
+    session?: { pairingTopic?: unknown }
+  }
+
+  const connectorUri = providerRecord.connector?.uri
+  if (typeof connectorUri === "string" && connectorUri.length > 0) {
+    return connectorUri
+  }
+
+  return null
 }
 
 /**
@@ -81,8 +81,13 @@ export function useWalletConnectUri(projectId?: string): {
 
       if ((status === "pending" || status === "success") && !force) return
 
-      const makeConnector = () => getWalletConnectConnector(finalProjectId)
-      const connector = wcConnectorFromConfig || makeConnector()
+      const connector = wcConnectorFromConfig
+      if (!connector) {
+        logger.console.log(
+          "[trails-sdk] [useWalletConnectUri] WalletConnect connector not ready yet",
+        )
+        return
+      }
 
       logger.console.log(
         "[trails-sdk] [useWalletConnectUri] wcConnectorFromConfig",
@@ -158,6 +163,18 @@ export function useWalletConnectUri(projectId?: string): {
         }
 
         await connect({ connector })
+
+        if (typeof connector.getProvider === "function") {
+          const provider = await connector.getProvider()
+          const providerUri = getUriFromProvider(provider)
+          if (providerUri) {
+            logger.console.log(
+              "[trails-sdk] [useWalletConnectUri] Setting URI from provider.connector.uri",
+            )
+            debouncedSetWcUri(providerUri)
+            setError(null)
+          }
+        }
       } catch (err) {
         logger.console.error(
           "[trails-sdk] [useWalletConnectUri] connect error",
@@ -204,6 +221,48 @@ export function useWalletConnectUri(projectId?: string): {
     }
   }, [wcUri, status, handleConnect])
 
+  useEffect(() => {
+    if (!wcConnectorFromConfig || wcUri || status !== "pending") {
+      return
+    }
+
+    let isCancelled = false
+    let attempts = 0
+
+    const tryReadPendingUri = async () => {
+      if (
+        isCancelled ||
+        typeof wcConnectorFromConfig.getProvider !== "function"
+      ) {
+        return
+      }
+
+      const provider = await wcConnectorFromConfig.getProvider()
+      const providerUri = getUriFromProvider(provider)
+      if (providerUri) {
+        logger.console.log(
+          "[trails-sdk] [useWalletConnectUri] Recovered URI during pending status",
+        )
+        debouncedSetWcUri(providerUri)
+        setError(null)
+        return
+      }
+
+      attempts += 1
+      if (attempts < 10) {
+        setTimeout(() => {
+          void tryReadPendingUri()
+        }, 300)
+      }
+    }
+
+    void tryReadPendingUri()
+
+    return () => {
+      isCancelled = true
+    }
+  }, [wcConnectorFromConfig, wcUri, status, debouncedSetWcUri])
+
   // Force QR code regeneration when wcUri is cleared
   useEffect(() => {
     if (!wcUri && status !== "pending" && status !== "success") {

package/src/widget/hooks/useWalletConnectionContext.tsx

@@ -5,7 +5,7 @@ import {
   useCallback,
   type ReactNode,
 } from "react"
-import type { Screen } from "./useCurrentScreen.js"
+import type { Screen } from "./useViewManager.js"
 import { logger } from "../../logger.js"
 
 export type WalletConnectionPurpose =

package/src/widget/index.tsx

@@ -3,6 +3,7 @@
 export type { TrailsWidgetProps, TrailsWidgetRef } from "./widget.js"
 export {
   createModalController,
+  WidgetFundMethod,
   TrailsWidget,
 } from "./widget.js"
 

package/src/widget/providers/TrailsProvider.tsx

@@ -20,11 +20,8 @@ import {
 } from "../../constants.js"
 import { declareCommitHash, updateGlobalConfig } from "../../config.js"
 import { updateProjectAccessKey } from "../../analytics.js"
-import { logger } from "../../logger.js"
 import { useSyncLoggerDebug } from "../../logger/useSyncLoggerDebug.js"
 import { getQueryParam } from "../../queryParams.js"
-import { IntentExecutionWorker } from "../workers/intentExecutionWorker.js"
-import { getTrailsClient } from "../../trailsClient.js"
 
 export type SequenceEnv = "prod" | "dev" | "local" | "cors-anywhere"
 
@@ -119,44 +116,6 @@ export const TrailsProvider = ({ children, config }: TrailsProviderProps) => {
     }
   }, [trailsConfig.trailsApiKey])
 
-  // Initialize and start the intent execution worker (singleton)
-  useEffect(() => {
-    if (!trailsConfig.trailsApiKey) {
-      logger.console.log(
-        "[trails-sdk] No API key, skipping intent worker initialization",
-      )
-      return
-    }
-
-    logger.console.log(
-      "[trails-sdk] Initializing intent execution worker singleton",
-    )
-
-    const trailsClient = getTrailsClient({
-      apiKey: trailsConfig.trailsApiKey,
-      hostname: trailsConfig.trailsApiUrl,
-    })
-
-    // Get or create the singleton instance
-    const worker = IntentExecutionWorker.getInstance({
-      trailsClient,
-      trailsApiKey: trailsConfig.trailsApiKey,
-      sequenceIndexerUrl: trailsConfig.sequenceIndexerUrl,
-      enabled: true,
-    })
-
-    // Start the worker if not already running
-    worker.start()
-
-    // Note: We don't stop the worker on unmount since it's a singleton
-    // It will keep running across component remounts
-    // Only destroy it when the entire app unmounts (optional)
-  }, [
-    trailsConfig.trailsApiKey,
-    trailsConfig.trailsApiUrl,
-    trailsConfig.sequenceIndexerUrl,
-  ])
-
   const sequenceHooksConfig = useMemo(() => {
     return {
       projectAccessKey: trailsConfig.trailsApiKey || "",