@zerodev/wallet-react-ui 0.0.11 → 0.0.12

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

@@ -23,7 +23,7 @@ export function SignUpInstalledWallets({
   const { authPending, guardAgreement, setError, registeredWallets } =
     useSignUpContext()
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
+  const { connect, isPending } = useConnect()
   useReportPending(isPending)
 
   // Same rule that earns the INSTALLED badge elsewhere: only a 6963

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

@@ -1,13 +1,15 @@
 import { ListItem, ListItemChevron, ListItemIcon } from '@zerodev/react-ui'
 import { useState } from 'react'
 import { useConnect, 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 { isZeroDevWalletConnect } from '../../utils/isZeroDevWalletConnect'
+import { announcesWallet, matchesWallet, WALLET_GUIDE } from '../../walletGuide'
 import { useReportPending, useSignUpContext } from './context'
 
 /** "More wallets" row — opens the wallet grid sheet. */
@@ -17,10 +19,11 @@ export function SignUpMoreWallets({
   title?: string
 }) {
   const { goToStep } = useAuth()
-  const { authPending, guardAgreement, setError } = useSignUpContext()
+  const { authPending, guardAgreement, setError, openWalletSheet } =
+    useSignUpContext()
   const [open, setOpen] = useState(false)
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
+  const { connect, isPending } = useConnect()
   useReportPending(isPending)
 
   // Our own connector is the embedded wallet, and walletConnect-type
@@ -50,17 +53,33 @@ export function SignUpMoreWallets({
     )
   }
 
-  // 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)
+          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)
           return
         }
         setOpen(false)
@@ -80,6 +99,22 @@ export function SignUpMoreWallets({
       onSelect: () => startConnect(connector),
     }))
 
+  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 +133,7 @@ export function SignUpMoreWallets({
       <WalletGridSheet
         open={open}
         onOpenChange={setOpen}
-        tiles={[...guideTiles, ...connectorTiles]}
+        tiles={[...walletConnectTiles, ...guideTiles, ...connectorTiles]}
       />
     </>
   )

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

@@ -3,7 +3,13 @@ import { useLayoutEffect } from 'react'
 import { useConnect, useConnectors } from 'wagmi'
 import { useAuth } from '../../hooks/useAuth'
 import { isCancellationError } from '../../utils/isCancellationError'
-import { matchesWallet, WALLET_GUIDE, type WalletId } from '../../walletGuide'
+import { isZeroDevWalletConnect } from '../../utils/isZeroDevWalletConnect'
+import {
+  announcesWallet,
+  matchesWallet,
+  WALLET_GUIDE,
+  type WalletId,
+} from '../../walletGuide'
 import { useReportPending, useSignUpContext } from './context'
 
 /** Dedicated row for a single guide wallet: connects it directly when a live
@@ -18,19 +24,21 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
   }
 
   const { goToStep } = useAuth()
-  const { authPending, guardAgreement, setError, registerWallet } =
-    useSignUpContext()
+  const {
+    authPending,
+    guardAgreement,
+    setError,
+    registerWallet,
+    openWalletSheet,
+  } = useSignUpContext()
   const connectors = useConnectors()
-  const { mutate: connect, isPending } = useConnect()
+  const { 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 +46,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 */}
@@ -56,7 +86,7 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
     if (!guardAgreement()) return
     setError(null)
     connect(
-      { connector: installed },
+      { connector: claimed },
       {
         // The external wallet is now the active wagmi connection — the
         // embedded-wallet flow is done, so close it (mirrors SignUp.MoreWallets).
@@ -73,7 +103,7 @@ export function SignUpWallet({ walletId }: { walletId: WalletId }) {
   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/utils/isMobile.ts

@@ -0,0 +1,9 @@
+export function isMobile() {
+  if (typeof window === 'undefined') return false
+  return (
+    window.matchMedia?.('(pointer: coarse)')?.matches ||
+    /Android|webOS|iPhone|iPad|iPod|BlackBerry|Opera Mini/u.test(
+      navigator.userAgent,
+    )
+  )
+}

package/src/auth/utils/isZeroDevWalletConnect.ts

@@ -0,0 +1,8 @@
+import type { Connector } from 'wagmi'
+
+/** True for connectors created by `zeroDevWalletConnect` — the only ones the
+ * kit pairs through. A raw `walletConnect()` may have `showQrModal` enabled
+ * (its default), which can't be read back, so it's ignored. */
+export function isZeroDevWalletConnect(connector: Connector) {
+  return connector.type === 'walletConnect' && 'zdWalletConnect' in connector
+}

package/src/auth/utils/walletDeepLink.ts

@@ -0,0 +1,23 @@
+import { matchesWallet, type WalletGuideEntry } from '../walletGuide'
+
+/**
+ * Wrapped deep link for the one-tap mobile redirect into `wallet`'s app, or
+ * null when the tap should just open the sheet: desktop, a claiming installed
+ * connector (direct connect wins), or no pairing URI.
+ */
+export function walletDeepLink(params: {
+  wallet: WalletGuideEntry
+  connectors: readonly {
+    id: string
+    name?: string
+    type?: string
+    rdns?: string | readonly string[] | undefined
+  }[]
+  uri: string | null
+  mobile: boolean
+}): string | null {
+  const { wallet, connectors, uri, mobile } = params
+  if (!wallet.mobileLink || !mobile || !uri) return null
+  if (connectors.some((c) => matchesWallet(c, wallet))) return null
+  return `${wallet.mobileLink}${encodeURIComponent(uri)}`
+}

package/src/auth/walletGuide.ts

@@ -27,20 +27,53 @@ export type WalletGuideEntry = {
 }
 
 /**
- * A live connector "claims" a guide wallet by rdns: announced (6963)
- * connectors carry `id === rdns`, explicit ones (e.g. `metaMask()`) declare
- * `rdns` as a string or array.
+ * A live 6963 announcement claiming a guide wallet. Announced connectors
+ * carry `id === rdns`; wallets' in-app browsers announce a variant rdns
+ * (MetaMask mobile is `io.metamask.mobile`) but keep the wallet's exact
+ * name, so an announced connector matching the guide name also counts —
+ * the same fallback Reown AppKit and Dynamic use. The generic `injected()`
+ * connector (id "injected") and our embedded connector also claim type
+ * "injected" without being announcements.
+ */
+export function announcesWallet(
+  connector: {
+    id: string
+    name?: string
+    type?: string
+    rdns?: string | readonly string[] | undefined
+  },
+  wallet: WalletGuideEntry,
+): boolean {
+  if (!!wallet.rdns && connector.id === wallet.rdns) return true
+  return (
+    !!wallet.rdns &&
+    connector.type === 'injected' &&
+    connector.id !== 'injected' &&
+    connector.id !== 'zerodev-wallet' &&
+    connector.name === wallet.name
+  )
+}
+
+/**
+ * A live connector "claims" a guide wallet: it announces it (see
+ * `announcesWallet`), or is an explicit connector (e.g. `metaMask()`)
+ * declaring the wallet's rdns as a string or array.
  */
 export function matchesWallet(
-  connector: { id: string; rdns?: string | readonly string[] | undefined },
+  connector: {
+    id: string
+    name?: string
+    type?: string
+    rdns?: string | readonly string[] | undefined
+  },
   wallet: WalletGuideEntry,
 ): boolean {
+  if (announcesWallet(connector, wallet)) return true
   return (
     !!wallet.rdns &&
-    (connector.id === wallet.rdns ||
-      (Array.isArray(connector.rdns)
-        ? connector.rdns.includes(wallet.rdns)
-        : connector.rdns === wallet.rdns))
+    (Array.isArray(connector.rdns)
+      ? connector.rdns.includes(wallet.rdns)
+      : connector.rdns === wallet.rdns)
   )
 }
 
@@ -81,6 +114,7 @@ const guide = [
     name: 'Rabby Wallet',
     rdns: 'io.rabby',
     icon: 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20fill%3D%22none%22%20viewBox%3D%220%200%2028%2028%22%3E%3Cg%20clip-path%3D%22url(%23a)%22%3E%3Cpath%20fill%3D%22%238697FF%22%20d%3D%22M28%200H0v28h28V0Z%22%2F%3E%3Cpath%20fill%3D%22url(%23b)%22%20d%3D%22M22.54%2015.078c.677-1.514-2.673-5.744-5.874-7.506-2.017-1.365-4.12-1.178-4.545-.579-.935%201.316%203.094%202.43%205.788%203.731-.58.252-1.125.703-1.446%201.28-1.004-1.096-3.209-2.04-5.796-1.28-1.743.513-3.191%201.721-3.751%203.546a1.097%201.097%200%201%200-.445%202.1c.112%200%20.463-.075.463-.075l5.612.041c-2.244%203.56-4.018%204.081-4.018%204.698s1.697.45%202.335.22c3.05-1.1%206.327-4.531%206.89-5.519%202.36.295%204.345.33%204.786-.657Z%22%2F%3E%3Cpath%20fill%3D%22url(%23c)%22%20fill-rule%3D%22evenodd%22%20d%3D%22m17.885%2010.713.025.01c.125-.049.105-.233.07-.378-.078-.333-1.438-1.676-2.715-2.277-1.743-.82-3.025-.777-3.212-.398.356.726%201.998%201.408%203.714%202.12.723.3%201.46.606%202.118.923Z%22%20clip-rule%3D%22evenodd%22%2F%3E%3Cpath%20fill%3D%22url(%23d)%22%20fill-rule%3D%22evenodd%22%20d%3D%22M15.701%2018.036a10.296%2010.296%200%200%200-1.2-.37c.482-.862.583-2.138.128-2.945-.639-1.133-1.44-1.736-3.304-1.736-1.024%200-3.783.346-3.832%202.648-.005.242%200%20.464.017.667l5.036.037a17.264%2017.264%200%200%201-1.871%202.483c.669.172%201.221.316%201.728.448.48.125.92.24%201.38.357a21.003%2021.003%200%200%200%201.918-1.59Z%22%20clip-rule%3D%22evenodd%22%2F%3E%3Cpath%20fill%3D%22url(%23e)%22%20d%3D%22M6.848%2016.063c.206%201.75%201.2%202.435%203.232%202.638%202.032.203%203.197.067%204.749.208%201.296.118%202.453.778%202.882.55.386-.205.17-.947-.347-1.423-.67-.617-1.597-1.046-3.229-1.199.325-.89.234-2.138-.27-2.817-.731-.982-2.079-1.426-3.785-1.232-1.782.202-3.49%201.08-3.232%203.275Z%22%2F%3E%3C%2Fg%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22b%22%20x1%3D%2210.464%22%20x2%3D%2222.394%22%20y1%3D%2213.737%22%20y2%3D%2217.12%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20stop-color%3D%22%23fff%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%23fff%22%2F%3E%3C%2FlinearGradient%3E%3ClinearGradient%20id%3D%22c%22%20x1%3D%2220.386%22%20x2%3D%2211.779%22%20y1%3D%2213.509%22%20y2%3D%224.879%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20stop-color%3D%22%237258DC%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%23797DEA%22%20stop-opacity%3D%220%22%2F%3E%3C%2FlinearGradient%3E%3ClinearGradient%20id%3D%22d%22%20x1%3D%2215.94%22%20x2%3D%227.673%22%20y1%3D%2218.337%22%20y2%3D%2213.584%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20stop-color%3D%22%237461EA%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%23BFC2FF%22%20stop-opacity%3D%220%22%2F%3E%3C%2FlinearGradient%3E%3ClinearGradient%20id%3D%22e%22%20x1%3D%2211.177%22%20x2%3D%2216.765%22%20y1%3D%2213.648%22%20y2%3D%2220.749%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20stop-color%3D%22%23fff%22%2F%3E%3Cstop%20offset%3D%22.984%22%20stop-color%3D%22%23D5CEFF%22%2F%3E%3C%2FlinearGradient%3E%3CclipPath%20id%3D%22a%22%3E%3Cpath%20fill%3D%22%23fff%22%20d%3D%22M0%200h28v28H0z%22%2F%3E%3C%2FclipPath%3E%3C%2Fdefs%3E%3C%2Fsvg%3E',
+    mobileLink: 'rabby://wc?uri=',
     downloadUrl: 'https://rabby.io',
   },
   {

package/src/index.ts

@@ -6,17 +6,21 @@
 // Auth
 export { ConnectWallet } from './auth'
 export { useAuth } from './auth/hooks/useAuth'
+// Connected wallet identity (call-compatible with AppKit's useWalletInfo)
+export type {
+  WalletInfo,
+  WalletSource,
+} from './auth/hooks/useWalletInfo.js'
+export { useWalletInfo } from './auth/hooks/useWalletInfo.js'
 export { SignUp } from './auth/pages/SignUp'
 export type { AuthMethod, AuthStep, EmailAuthMethod } from './auth/types'
 export type { WalletId } from './auth/walletGuide'
-
 // Connector
 export type {
   // SigningConfig,
   ZeroDevKitConnectorParams,
 } from './connector.js'
 export { zeroDevWallet } from './connector.js'
-
 // History
 export {
   TxHistory,
@@ -24,6 +28,7 @@ export {
   type TxHistoryStep,
 } from './history/pages'
 export type { TxHistoryEntry } from './history/types'
+export { zeroDevWalletConnect } from './zeroDevWalletConnect.js'
 
 // Signing
 // export type { SignatureRequestProps } from './signing'

package/src/zeroDevWalletConnect.ts

@@ -0,0 +1,95 @@
+import type { CreateConnectorFn } from 'wagmi'
+import { type WalletConnectParameters, walletConnect } from 'wagmi/connectors'
+import { isMobile } from './auth/utils/isMobile'
+
+/**
+ * localStorage key `@walletconnect/sign-client` reads before publishing each
+ * session request — when set, the SDK deep-links back into the chosen wallet
+ * app (`{href}/wc?requestId=…&sessionTopic=…`) so the approval prompt is in
+ * front of the user. Same key AppKit writes; the SDK no-ops when it's absent.
+ */
+const DEEPLINK_CHOICE_KEY = 'WALLETCONNECT_DEEPLINK_CHOICE'
+
+/** The slice of `@walletconnect/ethereum-provider` this module touches. */
+type WcSessionProvider = {
+  on: (event: 'connect' | 'disconnect', listener: () => void) => unknown
+  session?: {
+    peer?: {
+      metadata?: { name?: string; redirect?: { native?: string } }
+    }
+  }
+}
+
+const watched = new WeakSet<object>()
+
+/**
+ * Arm the SDK's redirect-on-request with the connected wallet's own
+ * registered scheme (`session.peer.metadata.redirect.native`) — authoritative
+ * for whichever wallet actually claimed the pairing. Desktop sessions and
+ * wallets that register no native redirect stay unarmed.
+ */
+function storeDeepLinkChoice(provider: WcSessionProvider) {
+  const metadata = provider.session?.peer?.metadata
+  const href = metadata?.redirect?.native
+  if (!href || !isMobile()) {
+    clearDeepLinkChoice()
+    return
+  }
+  try {
+    localStorage.setItem(
+      DEEPLINK_CHOICE_KEY,
+      JSON.stringify({ href, name: metadata?.name ?? '' }),
+    )
+  } catch {
+    // Storage unavailable — requests still work, minus the app hop.
+  }
+}
+
+function clearDeepLinkChoice() {
+  try {
+    localStorage.removeItem(DEEPLINK_CHOICE_KEY)
+  } catch {
+    // Nothing to clear if storage is unavailable.
+  }
+}
+
+function watchSession(provider: WcSessionProvider) {
+  if (watched.has(provider)) return
+  watched.add(provider)
+  provider.on('connect', () => storeDeepLinkChoice(provider))
+  // A stale choice would deep-link a future session to the wrong app.
+  provider.on('disconnect', clearDeepLinkChoice)
+  // Session restored from storage (page reload) — re-arm without an event.
+  if (provider.session) storeDeepLinkChoice(provider)
+}
+
+/**
+ * WalletConnect connector preconfigured for the kit. `showQrModal: false` is
+ * required — the kit renders its own pairing UI, and WalletConnect's bundled
+ * Reown modal would pop over it otherwise. All other WalletConnect
+ * parameters (e.g. `metadata`) are forwarded as-is.
+ *
+ * The kit only pairs through connectors created here — a raw `walletConnect()`
+ * in the config is ignored, since its `showQrModal` can't be read back.
+ */
+export function zeroDevWalletConnect(
+  params: Omit<WalletConnectParameters, 'showQrModal'>,
+): CreateConnectorFn {
+  if (!params.projectId) {
+    throw new Error('zeroDevWalletConnect requires a WalletConnect projectId')
+  }
+  const create = walletConnect({ ...params, showQrModal: false })
+  return (config) => {
+    // Stamp the connector instance so the kit's discovery can tell a
+    // correctly-configured connector from a raw walletConnect(), where
+    // showQrModal defaults to true.
+    const connector = Object.assign(create(config), { zdWalletConnect: true })
+    const getProvider = connector.getProvider.bind(connector)
+    connector.getProvider = async (...args: Parameters<typeof getProvider>) => {
+      const provider = await getProvider(...args)
+      watchSession(provider as WcSessionProvider)
+      return provider
+    }
+    return connector
+  }
+}