@zerodev/wallet-react-ui 0.0.11 → 0.0.13

package/src/auth/hooks/useWalletInfo.ts

@@ -0,0 +1,145 @@
+import { useEffect, useMemo, useState } from 'react'
+import { useAccount } from 'wagmi'
+import {
+  matchesWallet,
+  WALLET_GUIDE,
+  type WalletGuideEntry,
+  type WalletId,
+} from '../walletGuide'
+
+/** How the active connection reaches the wallet. */
+export type WalletSource = 'injected' | 'walletconnect' | 'embedded' | 'other'
+
+export type WalletInfo = {
+  /** Human-readable wallet name ('MetaMask', 'Trust Wallet', …). */
+  name?: string | undefined
+  /** Wallet icon URL or data: URI, when one is known. */
+  icon?: string | undefined
+  /** Guide id when the wallet matches the kit's wallet guide. */
+  walletId?: WalletId | undefined
+  source: WalletSource
+}
+
+/** The slice of `@walletconnect/ethereum-provider` this hook reads. */
+type WcPeerProvider = {
+  session?: {
+    peer?: {
+      metadata?: { name?: string; icons?: readonly string[] }
+    }
+  }
+}
+
+/**
+ * Guide entry for a WalletConnect peer, matched by name. Peers report their
+ * own branding ('MetaMask Wallet', 'Trust Wallet', …), so match by
+ * case-insensitive containment in either direction against the guide names.
+ */
+function guideEntryForPeerName(name: string): WalletGuideEntry | undefined {
+  const peer = name.toLowerCase()
+  return WALLET_GUIDE.find((wallet) => {
+    const guide = wallet.name.toLowerCase()
+    return peer.includes(guide) || guide.includes(peer)
+  })
+}
+
+function guideEntryForConnector(connector: {
+  id: string
+  name?: string
+  type?: string
+  rdns?: string | readonly string[] | undefined
+}): WalletGuideEntry | undefined {
+  return WALLET_GUIDE.find((wallet) => matchesWallet(connector, wallet))
+}
+
+function useResolvedWalletInfo(): WalletInfo | undefined {
+  const { connector, isConnected } = useAccount()
+  const [peerMetadata, setPeerMetadata] = useState<
+    { name?: string; icons?: readonly string[] } | undefined
+  >(undefined)
+
+  const isWalletConnect = !!connector && connector.type === 'walletConnect'
+
+  useEffect(() => {
+    if (!connector || !isWalletConnect) {
+      setPeerMetadata(undefined)
+      return
+    }
+    let cancelled = false
+    connector
+      .getProvider()
+      .then((provider) => {
+        if (cancelled) return
+        const metadata = (provider as WcPeerProvider).session?.peer?.metadata
+        setPeerMetadata(metadata)
+      })
+      .catch(() => {
+        // Provider unavailable (torn down mid-flight) — stay unresolved.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [connector, isWalletConnect])
+
+  // Memoized so the identity is reference-stable across renders: consumers
+  // put `walletInfo` in effect deps (analytics on wallet change), and a fresh
+  // object every render would fire those on every render instead.
+  return useMemo((): WalletInfo | undefined => {
+    if (!isConnected || !connector) return undefined
+
+    if (connector.id === 'zerodev-wallet') {
+      return {
+        name: connector.name,
+        icon: connector.icon,
+        source: 'embedded',
+      }
+    }
+
+    if (isWalletConnect) {
+      const entry = peerMetadata?.name
+        ? guideEntryForPeerName(peerMetadata.name)
+        : undefined
+      return {
+        name: peerMetadata?.name ?? undefined,
+        icon: peerMetadata?.icons?.[0] ?? entry?.icon,
+        walletId: entry?.id as WalletId | undefined,
+        // Identity is about the session, so a raw walletConnect() connector
+        // resolves here too — unlike pairing, which is kit-connector-only.
+        source: 'walletconnect',
+      }
+    }
+
+    const entry = guideEntryForConnector(connector)
+
+    return {
+      name: connector.name,
+      icon: connector.icon ?? entry?.icon,
+      walletId: entry?.id as WalletId | undefined,
+      source: connector.type === 'injected' ? 'injected' : 'other',
+    }
+  }, [connector, isConnected, isWalletConnect, peerMetadata])
+}
+
+/**
+ * Identity of the wallet behind the active wagmi connection, for
+ * wallet-specific handling and analytics attribution. Call-compatible with
+ * AppKit's `useWalletInfo` — same name, same `{ walletInfo }` return shape,
+ * so migrating is an import swap; `walletId` and `source` are kit extras.
+ *
+ * wagmi's `useAccount().connector` already names injected wallets, but a
+ * WalletConnect connection only reports "WalletConnect" — the actual wallet
+ * on the other end (Trust, Rainbow, … on a phone) is in the session's peer
+ * metadata, which this hook reads from the provider. `walletInfo` is
+ * `undefined` while disconnected, and the WalletConnect case resolves
+ * asynchronously (briefly `name: undefined` after connect/reload).
+ *
+ * @param _namespace - Accepted for AppKit call-compatibility ('eip155');
+ * ignored — the kit is EVM-only.
+ */
+export function useWalletInfo(_namespace?: string): {
+  walletInfo: WalletInfo | undefined
+} {
+  const walletInfo = useResolvedWalletInfo()
+  // The wrapper is memoized too, so the returned object is stable for
+  // consumers that depend on it whole rather than destructuring.
+  return useMemo(() => ({ walletInfo }), [walletInfo])
+}

package/src/auth/index.tsx

@@ -7,6 +7,7 @@ import { ErrorScreen } from './pages/ErrorScreen'
 import { OtpInput } from './pages/OtpInput'
 import { SignUp } from './pages/SignUp'
 import { Verifying } from './pages/Verifying'
+import { WalletConnecting } from './pages/WalletConnecting'
 import type { AuthStep } from './types'
 import { hasMagicLinkCodeInUrl, stripMagicLinkCodeFromUrl } from './utils/url'
 
@@ -47,6 +48,8 @@ function renderStep(
       return <OAuthCallback />
     case 'passkey-prompt':
       return <PasskeyPrompt />
+    case 'wallet-connecting':
+      return <WalletConnecting />
     case 'error':
       return <ErrorScreen />
     default:

package/src/auth/pages/SignUp/InstalledWallets.tsx

@@ -1,9 +1,8 @@
 import { Badge, ListItem, ListItemChevron } from '@zerodev/react-ui'
-import { useConnect, useConnectors } from 'wagmi'
+import { useConnectors } from 'wagmi'
 import { useAuth } from '../../hooks/useAuth'
-import { isCancellationError } from '../../utils/isCancellationError'
 import { matchesWallet, WALLET_GUIDE } from '../../walletGuide'
-import { useReportPending, useSignUpContext } from './context'
+import { useSignUpContext } from './context'
 
 /** Auto-discovered rows for installed wallets: one row per announced (6963)
  * browser extension. Renders nothing when no wallet is installed. */
@@ -19,12 +18,9 @@ export function SignUpInstalledWallets({
    * curated ones. */
   maxWallets?: number
 }) {
-  const { goToStep } = useAuth()
-  const { authPending, guardAgreement, setError, registeredWallets } =
-    useSignUpContext()
+  const { startWalletConnection } = useAuth()
+  const { authPending, guardAgreement, registeredWallets } = useSignUpContext()
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
-  useReportPending(isPending)
 
   // Same rule that earns the INSTALLED badge elsewhere: only a 6963
   // announcement proves a live extension. Announcements surface as
@@ -56,38 +52,32 @@ export function SignUpInstalledWallets({
     .sort((a, b) => a.rank - b.rank)
     .slice(0, maxWallets)
 
-  const startConnect = (connector: (typeof connectors)[number]) => {
+  // Hand off to the `wallet-connecting` step, which owns the connect() call.
+  const startConnect = (row: (typeof rows)[number]) => {
     if (authPending) return
     if (!guardAgreement()) return
-    setError(null)
-    connect(
-      { connector },
-      {
-        // The external wallet is now the active wagmi connection — the
-        // embedded-wallet flow is done, so close it (mirrors SignUp.Wallet).
-        onSuccess: () => goToStep(null),
-        onError: (err) => {
-          if (!isCancellationError(err)) {
-            setError(err instanceof Error ? err.message : String(err))
-          }
-        },
-      },
-    )
+    startWalletConnection({
+      connectorUid: row.connector.uid,
+      name: row.name,
+      icon: row.icon,
+    })
   }
 
   return (
     <>
-      {rows.map(({ connector, name, icon }) => (
+      {rows.map((row) => (
         <ListItem
-          key={connector.uid}
-          title={name}
+          key={row.connector.uid}
+          title={row.name}
           icon={
-            icon ? <img src={icon} alt="" className="zd:w-6 zd:h-6" /> : null
+            row.icon ? (
+              <img src={row.icon} alt="" className="zd:w-6 zd:h-6" />
+            ) : null
           }
           subtitle={<Badge text="INSTALLED" />}
           trailing={<ListItemChevron />}
           disabled={authPending}
-          onClick={() => startConnect(connector)}
+          onClick={() => startConnect(row)}
         />
       ))}
     </>

package/src/auth/pages/SignUp/MoreWallets.tsx

@@ -1,14 +1,15 @@
 import { ListItem, ListItemChevron, ListItemIcon } from '@zerodev/react-ui'
 import { useState } from 'react'
-import { useConnect, useConnectors } from 'wagmi'
+import { useConnectors } from 'wagmi'
+import { walletConnectLogo } from '../../brandAssets'
 import {
   WalletGridSheet,
   type WalletTileData,
 } from '../../components/WalletGridSheet'
 import { useAuth } from '../../hooks/useAuth'
-import { isCancellationError } from '../../utils/isCancellationError'
-import { matchesWallet, WALLET_GUIDE } from '../../walletGuide'
-import { useReportPending, useSignUpContext } from './context'
+import { isZeroDevWalletConnect } from '../../utils/isZeroDevWalletConnect'
+import { announcesWallet, matchesWallet, WALLET_GUIDE } from '../../walletGuide'
+import { useSignUpContext } from './context'
 
 /** "More wallets" row — opens the wallet grid sheet. */
 export function SignUpMoreWallets({
@@ -16,12 +17,10 @@ export function SignUpMoreWallets({
 }: {
   title?: string
 }) {
-  const { goToStep } = useAuth()
-  const { authPending, guardAgreement, setError } = useSignUpContext()
+  const { startWalletConnection } = useAuth()
+  const { authPending, guardAgreement, openWalletSheet } = useSignUpContext()
   const [open, setOpen] = useState(false)
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
-  useReportPending(isPending)
 
   // Our own connector is the embedded wallet, and walletConnect-type
   // connectors are the mobile transport rather than a wallet — neither
@@ -30,37 +29,45 @@ export function SignUpMoreWallets({
     (c) => c.id !== 'zerodev-wallet' && c.type !== 'walletConnect',
   )
 
-  const startConnect = (connector: (typeof connectors)[number]) => {
+  // Hand off to the `wallet-connecting` step, which owns the connect() call.
+  const startConnect = (
+    connector: (typeof connectors)[number],
+    name: string,
+    icon: string | undefined,
+  ) => {
     if (authPending) return
     if (!guardAgreement()) return
     setOpen(false)
-    setError(null)
-    connect(
-      { connector },
-      {
-        // The external wallet is now the active wagmi connection — the
-        // embedded-wallet flow is done, so close it.
-        onSuccess: () => goToStep(null),
-        onError: (err) => {
-          if (!isCancellationError(err)) {
-            setError(err instanceof Error ? err.message : String(err))
-          }
-        },
-      },
-    )
+    startWalletConnection({ connectorUid: connector.uid, name, icon })
   }
 
-  // Claimed by a connector → connect it; otherwise the tile opens the
-  // vendor download page.
+  const wcEnabled = connectors.some(isZeroDevWalletConnect)
+
   const guideTiles: WalletTileData[] = WALLET_GUIDE.map((wallet) => {
-    const installed = walletConnectors.find((c) => matchesWallet(c, wallet))
+    const announced = walletConnectors.find((c) => announcesWallet(c, wallet))
     return {
       key: wallet.id,
       name: wallet.name,
       icon: wallet.icon,
       onSelect: () => {
-        if (installed) {
-          startConnect(installed)
+        // Announced = the wallet is live on this page (extension or its own
+        // in-app browser) — connect directly instead of a WC handoff.
+        if (announced) {
+          startConnect(announced, wallet.name, wallet.icon)
+          return
+        }
+        if (wcEnabled) {
+          if (authPending) return
+          if (!guardAgreement()) return
+          setOpen(false)
+          openWalletSheet(wallet)
+          return
+        }
+        // No WC handoff available — a configured connector that claims the
+        // wallet (e.g. a vendor SDK) is the last way to connect.
+        const claimed = walletConnectors.find((c) => matchesWallet(c, wallet))
+        if (claimed) {
+          startConnect(claimed, wallet.name, wallet.icon)
           return
         }
         setOpen(false)
@@ -77,9 +84,25 @@ export function SignUpMoreWallets({
       key: connector.uid,
       name: connector.name,
       icon: connector.icon,
-      onSelect: () => startConnect(connector),
+      onSelect: () => startConnect(connector, connector.name, connector.icon),
     }))
 
+  const walletConnectTiles: WalletTileData[] = wcEnabled
+    ? [
+        {
+          key: 'walletconnect',
+          name: 'WalletConnect',
+          icon: walletConnectLogo,
+          onSelect: () => {
+            if (authPending) return
+            if (!guardAgreement()) return
+            setOpen(false)
+            openWalletSheet()
+          },
+        },
+      ]
+    : []
+
   const handleClick = () => {
     if (authPending) return
     if (!guardAgreement()) return
@@ -98,7 +121,7 @@ export function SignUpMoreWallets({
       <WalletGridSheet
         open={open}
         onOpenChange={setOpen}
-        tiles={[...guideTiles, ...connectorTiles]}
+        tiles={[...walletConnectTiles, ...guideTiles, ...connectorTiles]}
       />
     </>
   )

package/src/auth/pages/SignUp/Wallet.tsx

@@ -1,10 +1,15 @@
 import { Badge, ListItem, ListItemChevron } from '@zerodev/react-ui'
 import { useLayoutEffect } from 'react'
-import { useConnect, useConnectors } from 'wagmi'
+import { useConnectors } from 'wagmi'
 import { useAuth } from '../../hooks/useAuth'
-import { isCancellationError } from '../../utils/isCancellationError'
-import { matchesWallet, WALLET_GUIDE, type WalletId } from '../../walletGuide'
-import { useReportPending, useSignUpContext } from './context'
+import { isZeroDevWalletConnect } from '../../utils/isZeroDevWalletConnect'
+import {
+  announcesWallet,
+  matchesWallet,
+  WALLET_GUIDE,
+  type WalletId,
+} from '../../walletGuide'
+import { useSignUpContext } from './context'
 
 /** Dedicated row for a single guide wallet: connects it directly when a live
  * connector claims it, and is a download link for the vendor page otherwise. */
@@ -17,20 +22,15 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
     )
   }
 
-  const { goToStep } = useAuth()
-  const { authPending, guardAgreement, setError, registerWallet } =
+  const { startWalletConnection } = useAuth()
+  const { authPending, guardAgreement, registerWallet, openWalletSheet } =
     useSignUpContext()
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
-  useReportPending(isPending)
   useLayoutEffect(() => registerWallet(wallet.id), [registerWallet, wallet.id])
 
-  // Same claim rule as the MoreWallets grid: a 6963 announcement or a
-  // configured SDK connector both make the row connectable. Only an
-  // announcement (id === rdns) proves a live extension and earns the badge.
-  const installed = connectors.find((c) => matchesWallet(c, wallet))
-  const isAnnounced =
-    !!wallet.rdns && connectors.some((c) => c.id === wallet.rdns)
+  // Only a 6963 announcement proves a live extension (or the wallet's own
+  // in-app browser) — it earns the badge and a direct connect.
+  const announced = connectors.find((c) => announcesWallet(c, wallet))
 
   const shared = {
     title: wallet.name,
@@ -38,7 +38,29 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
     trailing: <ListItemChevron />,
   }
 
-  if (!installed) {
+  // An announcement means the wallet is right here (extension, or its own
+  // in-app browser) — connect it directly; WC pairing would bounce out of
+  // the very wallet the user is standing in.
+  if (!announced && connectors.some(isZeroDevWalletConnect)) {
+    return (
+      <ListItem
+        {...shared}
+        disabled={authPending}
+        onClick={() => {
+          if (authPending) return
+          if (!guardAgreement()) return
+          openWalletSheet(wallet)
+        }}
+      />
+    )
+  }
+
+  // Same claim rule as the MoreWallets grid: announced, or — without a WC
+  // handoff — a configured connector (e.g. a vendor SDK) that claims the
+  // wallet.
+  const claimed = announced ?? connectors.find((c) => matchesWallet(c, wallet))
+
+  if (!claimed) {
     return (
       <ListItem {...shared} asChild>
         {/* biome-ignore lint/a11y/useAnchorContent: the row layout (incl. the title text) is injected into the anchor via Slot */}
@@ -51,29 +73,21 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
     )
   }
 
+  // Hand off to the `wallet-connecting` step, which owns the connect() call.
   const handleClick = () => {
     if (authPending) return
     if (!guardAgreement()) return
-    setError(null)
-    connect(
-      { connector: installed },
-      {
-        // The external wallet is now the active wagmi connection — the
-        // embedded-wallet flow is done, so close it (mirrors SignUp.MoreWallets).
-        onSuccess: () => goToStep(null),
-        onError: (err) => {
-          if (!isCancellationError(err)) {
-            setError(err instanceof Error ? err.message : String(err))
-          }
-        },
-      },
-    )
+    startWalletConnection({
+      connectorUid: claimed.uid,
+      name: wallet.name,
+      icon: wallet.icon,
+    })
   }
 
   return (
     <ListItem
       {...shared}
-      {...(isAnnounced && { subtitle: <Badge text="INSTALLED" /> })}
+      {...(!!announced && { subtitle: <Badge text="INSTALLED" /> })}
       disabled={authPending}
       onClick={handleClick}
     />

package/src/auth/pages/SignUp/WalletConnect.tsx

@@ -0,0 +1,32 @@
+import { Badge, ListItem, ListItemChevron } from '@zerodev/react-ui'
+import { useConnectors } from 'wagmi'
+import { walletConnectLogo } from '../../brandAssets'
+import { isZeroDevWalletConnect } from '../../utils/isZeroDevWalletConnect'
+import { useSignUpContext } from './context'
+
+/** Generic WalletConnect row — opens the pairing sheet with a raw-URI QR any
+ * wallet's scanner can claim. Renders nothing unless a `zeroDevWalletConnect`
+ * connector is in the wagmi config. */
+export function SignUpWalletConnect() {
+  const { authPending, guardAgreement, openWalletSheet } = useSignUpContext()
+  const connectors = useConnectors()
+
+  if (!connectors.some(isZeroDevWalletConnect)) return null
+
+  const handleClick = () => {
+    if (authPending) return
+    if (!guardAgreement()) return
+    openWalletSheet()
+  }
+
+  return (
+    <ListItem
+      title="WalletConnect"
+      icon={<img src={walletConnectLogo} alt="" className="zd:w-6 zd:h-6" />}
+      subtitle={<Badge text="QR CODE" />}
+      trailing={<ListItemChevron />}
+      disabled={authPending}
+      onClick={handleClick}
+    />
+  )
+}

package/src/auth/pages/SignUp/context.tsx

@@ -1,5 +1,6 @@
 import { createContext, useContext, useEffect } from 'react'
 import type { EmailAuthMethod } from '../../types'
+import type { WalletGuideEntry } from '../../walletGuide'
 
 export type SignUpContextValue = {
   /** True while any method's auth attempt is in flight — used to disable
@@ -21,6 +22,9 @@ export type SignUpContextValue = {
   registeredWallets: readonly string[]
   /** Returns the unregister function. */
   registerWallet: (walletId: string) => () => void
+  /** Opens the root's single WalletSheet — a wallet's connection paths, or
+   * the generic WalletConnect pairing when called without one. */
+  openWalletSheet: (wallet?: WalletGuideEntry) => void
 }
 
 export const SignUpContext = createContext<SignUpContextValue | null>(null)

package/src/auth/pages/SignUp/index.tsx

@@ -2,7 +2,10 @@ import { Button, Text } from '@zerodev/react-ui'
 import { type ReactNode, useCallback, useState } from 'react'
 import { SignUpFooter } from '../../../shared/components/SignUpFooter'
 import { BlobAnimation } from '../../components/BlobAnimation'
+import { WalletSheet } from '../../components/WalletSheet'
+import { useWalletConnectPairing } from '../../hooks/useWalletConnectPairing'
 import type { EmailAuthMethod } from '../../types'
+import type { WalletGuideEntry } from '../../walletGuide'
 import { SignUpContext } from './context'
 import { SignUpEmail } from './Email'
 import { SignUpGoogle } from './Google'
@@ -10,6 +13,7 @@ import { SignUpInstalledWallets } from './InstalledWallets'
 import { SignUpMoreWallets } from './MoreWallets'
 import { SignUpPasskey } from './Passkey'
 import { SignUpWallet } from './Wallet'
+import { SignUpWalletConnect } from './WalletConnect'
 
 type SignUpRootProps = {
   children: ReactNode
@@ -51,6 +55,17 @@ function SignUpRoot({
     }
   }, [])
 
+  // The page's single WalletSheet — every wallet surface opens it via
+  // `openWalletSheet` instead of mounting a sheet of its own. The box
+  // distinguishes open-without-a-wallet (generic pairing) from closed.
+  const [walletSheet, setWalletSheet] = useState<{
+    wallet?: WalletGuideEntry | undefined
+  } | null>(null)
+  // Pairing preloads at page mount so the sheet's QR is ready on open and the
+  // mobile deep link below fires synchronously inside the tap — iOS only
+  // hands a universal link to the app for gesture-qualified navigations.
+  const pairing = useWalletConnectPairing()
+
   const requiresAgreement = !!(termsAndConditionsUrl || privacyPolicyUrl)
   const needsAgreement = requiresAgreement && !agreedToTerms
 
@@ -71,6 +86,13 @@ function SignUpRoot({
         setError,
         registeredWallets,
         registerWallet,
+        openWalletSheet: (wallet) => {
+          const deepLink = wallet && pairing.deepLinkFor(wallet)
+          if (deepLink) window.location.href = deepLink
+          // Sheet opens either way — it's the fallback surface when the
+          // redirect doesn't take (and the only surface on desktop).
+          setWalletSheet({ wallet })
+        },
       }}
     >
       {error !== null && (
@@ -124,6 +146,14 @@ function SignUpRoot({
           />
         </div>
       </div>
+      <WalletSheet
+        pairing={pairing}
+        open={walletSheet !== null}
+        onOpenChange={(open) => {
+          if (!open) setWalletSheet(null)
+        }}
+        wallet={walletSheet?.wallet}
+      />
     </SignUpContext.Provider>
   )
 }
@@ -158,6 +188,7 @@ export const SignUp = Object.assign(SignUpRoot, {
   Google: SignUpGoogle,
   Email: SignUpEmail,
   Wallet: SignUpWallet,
+  WalletConnect: SignUpWalletConnect,
   InstalledWallets: SignUpInstalledWallets,
   MoreWallets: SignUpMoreWallets,
   Divider: SignUpDivider,

package/src/auth/pages/Verifying.tsx

@@ -15,6 +15,7 @@ export function Verifying() {
     useAuth()
   const [code] = useState<string | null>(getCodeFromUrl)
   const [error, setError] = useState<Error | null>(null)
+  const [sessionMissing, setSessionMissing] = useState(false)
 
   // ref to prevent useEffect firing twice in dev's StrictMode
   const hasVerifiedRef = useRef(false)
@@ -35,14 +36,15 @@ export function Verifying() {
     if (hasVerifiedRef.current || !code) return
     hasVerifiedRef.current = true
 
-    // No active OTP session — most commonly the user tapped the same
-    // magic link again after a successful verify, which cleared the
-    // session. Skip the (doomed) mutation, clean the URL, and drop
-    // back to step=null so the host app's own routing handles the
-    // already-authenticated user without flashing an error.
+    // No active OTP session — the link was already used, expired, or opened
+    // in a browser that never started the email flow. Skip the (doomed)
+    // mutation and show the expired-link error below instead of silently
+    // dropping the step: a blank screen gives the user nothing to act on.
+    // The already-authenticated re-tap case is covered too — hosts route
+    // connected users away on their own (wagmi reconnect), so the error only
+    // stays up for users who genuinely can't be verified.
     if (!otpId || !otpEncryptionTargetBundle) {
-      stripMagicLinkCodeFromUrl()
-      goToStep(null)
+      setSessionMissing(true)
       return
     }
 
@@ -58,7 +60,25 @@ export function Verifying() {
           </StatusScreen>
         )}
 
-        {!error && !code && !isVerificationLoading && (
+        {!error && sessionMissing && (
+          <>
+            <StatusScreen imageName="error" title="Link Expired">
+              This verification link has expired or was already used.
+              <br />
+              Please sign in again to request a new one.
+            </StatusScreen>
+            <Button
+              action="primary"
+              onClick={() => {
+                stripMagicLinkCodeFromUrl()
+                goToStep('sign-up')
+              }}
+              text="Choose another sign-in method"
+            />
+          </>
+        )}
+
+        {!error && !sessionMissing && !code && !isVerificationLoading && (
           <>
             <StatusScreen imageName="error" title="Invalid Link">
               This verification link is invalid or incomplete.