From 1d187b4b195531cf5174a1101049271ac0b1387f Mon Sep 17 00:00:00 2001
From: jalil <jalil@1001.digital>
Date: Thu, 30 Jul 2026 12:25:25 +0200
Subject: [PATCH] Add pluggable wallet onboarding

---
 .changeset/smart-wallet-paths.md              |  7 ++
 docs/components/evm.md                        | 59 ++++++++++-----
 .../src/components/EvmConnect.vue             | 64 +++++++++++++---
 .../src/components/EvmConnectAuth.vue         |  3 +
 .../src/components/EvmConnectAuthDialog.vue   |  3 +
 .../src/components/EvmConnectDialog.vue       |  3 +
 .../src/components/EvmInAppWalletSetup.vue    | 73 ++++++++++++++++---
 packages/components.evm/src/index.ts          |  3 +
 packages/components.evm/src/types.ts          | 21 +++++-
 9 files changed, 193 insertions(+), 43 deletions(-)
 create mode 100644 .changeset/smart-wallet-paths.md

diff --git a/.changeset/smart-wallet-paths.md b/.changeset/smart-wallet-paths.md
new file mode 100644
index 00000000..a7daeb98
--- /dev/null
+++ b/.changeset/smart-wallet-paths.md
@@ -0,0 +1,7 @@
+---
+'@1001-digital/components.evm': minor
+---
+
+Make wallet onboarding composable with external-only and in-app-only connector
+filters, direct create or restore entry points for in-app wallets, and back
+events that bubble through the connect and SIWE auth wrappers.
diff --git a/docs/components/evm.md b/docs/components/evm.md
index 262b1d17..c3822272 100644
--- a/docs/components/evm.md
+++ b/docs/components/evm.md
@@ -6,17 +6,17 @@ Components that require wallet or browser APIs are marked client-only by the Nux
 
 ## Wallet Connection
 
-| Component                 | Purpose                             | Key API                                              |
-| ------------------------- | ----------------------------------- | ---------------------------------------------------- |
-| `EvmConnect`              | Inline wallet connection UI.        | Emits `connecting`, `connected`.                     |
-| `EvmConnectDialog`        | Dialog-based wallet connection.     | Prop `className`; emits `connected`, `disconnected`. |
-| `EvmConnectionStatus`     | Displays current connection status. | Uses wagmi connection state.                         |
-| `EvmConnectorQR`          | Generic QR connector UI.            | Prop `uri`.                                          |
-| `EvmMetaMaskQR`           | MetaMask QR flow.                   | Prop `uri`; emits `back`.                            |
-| `EvmWalletConnectQR`      | WalletConnect QR flow.              | Prop `uri`.                                          |
-| `EvmWalletConnectWallets` | WalletConnect wallet list.          | Prop `uri`; emits `back`.                            |
-| `EvmInAppWalletSetup`     | In-app wallet setup UI.             | Prop `note`; emits `connected`, `back`.              |
-| `EvmSeedPhraseInput`      | Seed phrase input.                  | `v-model`, `disabled`; emits `valid`, `submit`.      |
+| Component                 | Purpose                             | Key API                                                                                     |
+| ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `EvmConnect`              | Inline wallet connection UI.        | Props `connectorFilter`, `inAppWalletInitialStep`; emits `connecting`, `connected`, `back`. |
+| `EvmConnectDialog`        | Dialog-based wallet connection.     | Connect props plus `className`; emits `connected`, `disconnected`, `back`.                  |
+| `EvmConnectionStatus`     | Displays current connection status. | Uses wagmi connection state.                                                                |
+| `EvmConnectorQR`          | Generic QR connector UI.            | Prop `uri`.                                                                                 |
+| `EvmMetaMaskQR`           | MetaMask QR flow.                   | Prop `uri`; emits `back`.                                                                   |
+| `EvmWalletConnectQR`      | WalletConnect QR flow.              | Prop `uri`.                                                                                 |
+| `EvmWalletConnectWallets` | WalletConnect wallet list.          | Prop `uri`; emits `back`.                                                                   |
+| `EvmInAppWalletSetup`     | In-app wallet setup UI.             | Props `note`, `initialStep`; emits `connected`, `back`.                                     |
+| `EvmSeedPhraseInput`      | Seed phrase input.                  | `v-model`, `disabled`; emits `valid`, `submit`.                                             |
 
 ```vue
 <template>
@@ -34,6 +34,31 @@ Components that require wallet or browser APIs are marked client-only by the Nux
 </template>
 ```
 
+Use `connectorFilter` to let the host application own a wallet-choice screen.
+`external` excludes the in-app connector, while `in-app` opens the in-app
+setup without showing the connector list. The optional
+`inAppWalletInitialStep` can skip the setup's internal chooser:
+
+```vue
+<template>
+  <EvmConnectAuth
+    v-if="walletPath === 'existing'"
+    connector-filter="external"
+    :get-nonce="getNonce"
+    :verify="verify"
+    @back="walletPath = null"
+  />
+  <EvmConnectAuth
+    v-else-if="walletPath === 'create'"
+    connector-filter="in-app"
+    in-app-wallet-initial-step="create"
+    :get-nonce="getNonce"
+    :verify="verify"
+    @back="walletPath = null"
+  />
+</template>
+```
+
 ## Accounts, Inputs, and Profiles
 
 | Component           | Purpose                                               | Key API                                                                         |
@@ -117,12 +142,12 @@ The transaction flow checks chain selection, requests a transaction, waits for a
 
 ## SIWE and Auth
 
-| Component              | Purpose                               | Key API                                                                   |
-| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
-| `EvmSiwe`              | Inline Sign-In with Ethereum flow.    | Requires `getNonce` and `verify`; emits `authenticated`, `error`.         |
-| `EvmSiweDialog`        | Dialog-based SIWE flow.               | SIWE props plus `className`; emits `authenticated`, `signedOut`, `error`. |
-| `EvmConnectAuth`       | Wallet connect plus SIWE auth flow.   | SIWE props; emits connection and auth events.                             |
-| `EvmConnectAuthDialog` | Dialog wrapper for connect plus SIWE. | SIWE props plus `className`, `noTrigger`.                                 |
+| Component              | Purpose                               | Key API                                                                                 |
+| ---------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `EvmSiwe`              | Inline Sign-In with Ethereum flow.    | Requires `getNonce` and `verify`; emits `authenticated`, `error`.                       |
+| `EvmSiweDialog`        | Dialog-based SIWE flow.               | SIWE props plus `className`; emits `authenticated`, `signedOut`, `error`.               |
+| `EvmConnectAuth`       | Wallet connect plus SIWE auth flow.   | SIWE and connect props; emits connection, auth, and `back` events.                      |
+| `EvmConnectAuthDialog` | Dialog wrapper for connect plus SIWE. | SIWE and connect props plus `className`, `noTrigger`; emits auth and connection events. |
 
 ```vue
 <template>
diff --git a/packages/components.evm/src/components/EvmConnect.vue b/packages/components.evm/src/components/EvmConnect.vue
index 07974b56..ecc7c608 100644
--- a/packages/components.evm/src/components/EvmConnect.vue
+++ b/packages/components.evm/src/components/EvmConnect.vue
@@ -1,9 +1,23 @@
 <template>
-  <EvmInAppWalletSetup
-    v-if="showInAppSetup"
-    @connected="onInAppConnected"
-    @back="showInAppSetup = false"
-  />
+  <template v-if="showInAppSetup">
+    <EvmInAppWalletSetup
+      v-if="inAppConnector"
+      :key="inAppSetupKey"
+      :initial-step="inAppWalletInitialStep"
+      @connected="onInAppConnected"
+      @back="onInAppBack"
+    />
+    <template v-else>
+      <Alert type="error">In-app wallet is unavailable.</Alert>
+      <Button
+        class="link muted small"
+        @click="onInAppBack"
+      >
+        <Icon name="chevron-left" />
+        <span>Back</span>
+      </Button>
+    </template>
+  </template>
   <template v-else-if="errorMessage">
     <Alert type="error">
       {{ errorMessage }}
@@ -38,7 +52,7 @@
     class="wallet-options"
   >
     <Button
-      v-for="connector in shownConnectors"
+      v-for="connector in showExternalWallets ? shownConnectors : []"
       :key="connector.uid"
       @click="() => login(connector)"
       class="block choose-connector"
@@ -57,7 +71,7 @@
       <span>{{ connector.name }}</span>
     </Button>
     <Button
-      v-if="wcConnector"
+      v-if="showExternalWallets && wcConnector"
       @click="loginWithSafe"
       class="block choose-connector"
     >
@@ -68,7 +82,7 @@
       <span>Safe</span>
     </Button>
     <Button
-      v-if="inAppConnector"
+      v-if="showInAppWallet && inAppConnector"
       @click="
         () => {
           emit('connecting')
@@ -84,6 +98,7 @@
       <span>In App</span>
     </Button>
     <Button
+      v-if="showExternalWallets"
       to="https://ethereum.org/wallets/"
       target="_blank"
       class="link muted small"
@@ -95,7 +110,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed } from 'vue'
+import { ref, computed, watch } from 'vue'
 import type { Connector } from '@wagmi/vue'
 import {
   useConnect,
@@ -110,7 +125,7 @@ import { Button, Icon, Alert, Loading } from '@1001-digital/components'
 import EvmMetaMaskQR from './EvmMetaMaskQR.vue'
 import EvmWalletConnectWallets from './EvmWalletConnectWallets.vue'
 import EvmInAppWalletSetup from './EvmInAppWalletSetup.vue'
-import type { EvmConnectEmits } from '../types'
+import type { EvmConnectProps, EvmConnectEmits } from '../types'
 
 import coinbaseIcon from '../assets/wallets/coinbase.svg'
 import metamaskIcon from '../assets/wallets/metamask.svg'
@@ -137,6 +152,10 @@ const PRIORITY: Record<string, number> = {
   'Base Account': 10,
 }
 
+const props = withDefaults(defineProps<EvmConnectProps>(), {
+  connectorFilter: 'all',
+  inAppWalletInitialStep: 'choose',
+})
 const emit = defineEmits<EvmConnectEmits>()
 
 const chainId = useChainId()
@@ -146,7 +165,10 @@ const { mutateAsync: connectAsync } = useConnect()
 const inAppConnector = computed(() =>
   connectors.value.find((c) => c.type === 'inAppWallet'),
 )
-const showInAppSetup = ref(false)
+const showExternalWallets = computed(() => props.connectorFilter !== 'in-app')
+const showInAppWallet = computed(() => props.connectorFilter !== 'external')
+const showInAppSetup = ref(props.connectorFilter === 'in-app')
+const inAppSetupKey = ref(0)
 
 const shownConnectors = computed(() => {
   const unique = Array.from(
@@ -273,11 +295,29 @@ const onInAppConnected = () => {
   emit('connected')
 }
 
+const onInAppBack = () => {
+  if (props.connectorFilter === 'in-app') {
+    emit('back')
+    return
+  }
+  showInAppSetup.value = false
+}
+
 const reset = () => {
   resetConnection()
-  showInAppSetup.value = false
+  inAppSetupKey.value += 1
+  showInAppSetup.value = props.connectorFilter === 'in-app'
 }
 
+watch(
+  () => props.connectorFilter,
+  (connectorFilter) => {
+    resetConnection()
+    inAppSetupKey.value += 1
+    showInAppSetup.value = connectorFilter === 'in-app'
+  },
+)
+
 defineExpose({ reset })
 </script>
 
diff --git a/packages/components.evm/src/components/EvmConnectAuth.vue b/packages/components.evm/src/components/EvmConnectAuth.vue
index 5802f669..e2cf3787 100644
--- a/packages/components.evm/src/components/EvmConnectAuth.vue
+++ b/packages/components.evm/src/components/EvmConnectAuth.vue
@@ -2,8 +2,11 @@
   <EvmConnect
     v-if="!isConnected"
     ref="connectRef"
+    :connector-filter="connectorFilter"
+    :in-app-wallet-initial-step="inAppWalletInitialStep"
     @connecting="emit('connecting')"
     @connected="onConnected"
+    @back="emit('back')"
   />
   <EvmSiwe
     v-else-if="!isAuthenticated"
diff --git a/packages/components.evm/src/components/EvmConnectAuthDialog.vue b/packages/components.evm/src/components/EvmConnectAuthDialog.vue
index e717f19c..aa076688 100644
--- a/packages/components.evm/src/components/EvmConnectAuthDialog.vue
+++ b/packages/components.evm/src/components/EvmConnectAuthDialog.vue
@@ -34,8 +34,11 @@
       :resources="resources"
       :request-id="requestId"
       :expiration-time="expirationTime"
+      :connector-filter="connectorFilter"
+      :in-app-wallet-initial-step="inAppWalletInitialStep"
       @authenticated="onAuthenticated"
       @error="(e) => emit('error', e)"
+      @back="emit('back')"
     >
       <template #error-actions>
         <slot name="error-actions" />
diff --git a/packages/components.evm/src/components/EvmConnectDialog.vue b/packages/components.evm/src/components/EvmConnectDialog.vue
index b8cb8cab..c9a984a3 100644
--- a/packages/components.evm/src/components/EvmConnectDialog.vue
+++ b/packages/components.evm/src/components/EvmConnectDialog.vue
@@ -22,7 +22,10 @@
   >
     <EvmConnect
       ref="connectRef"
+      :connector-filter="connectorFilter"
+      :in-app-wallet-initial-step="inAppWalletInitialStep"
       @connected="onConnected"
+      @back="emit('back')"
     />
   </Dialog>
 </template>
diff --git a/packages/components.evm/src/components/EvmInAppWalletSetup.vue b/packages/components.evm/src/components/EvmInAppWalletSetup.vue
index 0e99cea4..05295961 100644
--- a/packages/components.evm/src/components/EvmInAppWalletSetup.vue
+++ b/packages/components.evm/src/components/EvmInAppWalletSetup.vue
@@ -1,5 +1,12 @@
 <template>
   <div class="in-app-wallet-setup">
+    <Alert
+      v-if="errorMessage"
+      type="error"
+    >
+      {{ errorMessage }}
+    </Alert>
+
     <!-- Step: Choose -->
     <div
       v-if="step === 'choose'"
@@ -32,6 +39,18 @@
       </Button>
     </div>
 
+    <!-- Step: Generating -->
+    <div
+      v-else-if="step === 'generating'"
+      class="setup-step"
+    >
+      <Loading
+        txt="Creating wallet..."
+        spinner
+        stacked
+      />
+    </div>
+
     <!-- Step: Generate -->
     <div
       v-else-if="step === 'generate'"
@@ -69,7 +88,7 @@
       </Button>
       <Button
         class="link muted small"
-        @click="step = 'choose'"
+        @click="goBack"
       >
         <Icon name="chevron-left" />
         <span>Back</span>
@@ -100,7 +119,7 @@
       </Button>
       <Button
         class="link muted small"
-        @click="step = 'choose'"
+        @click="goBack"
       >
         <Icon name="chevron-left" />
         <span>Back</span>
@@ -122,7 +141,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed } from 'vue'
+import { ref, computed, onMounted } from 'vue'
 import { useConnect, useConnectors } from '@wagmi/vue'
 import {
   Button,
@@ -140,6 +159,7 @@ import type {
 
 const props = withDefaults(defineProps<EvmInAppWalletSetupProps>(), {
   note: 'Create a browser-based wallet stored locally on this device. Only you have access to your keys.',
+  initialStep: 'choose',
 })
 
 const emit = defineEmits<EvmInAppWalletSetupEmits>()
@@ -150,8 +170,11 @@ const inAppConnector = computed(() =>
   connectors.value.find((c) => c.type === 'inAppWallet'),
 )
 
-type Step = 'choose' | 'generate' | 'restore' | 'connecting'
-const step = ref<Step>('choose')
+type Step = 'choose' | 'generating' | 'generate' | 'restore' | 'connecting'
+const step = ref<Step>(
+  props.initialStep === 'create' ? 'generating' : props.initialStep,
+)
+const errorMessage = ref('')
 
 // Generate state
 const generatedMnemonic = ref('')
@@ -163,40 +186,68 @@ const restorePhrase = ref('')
 const restoreValid = ref(false)
 
 async function startGenerate() {
-  const { generateMnemonic, english } = await import('viem/accounts')
-  generatedMnemonic.value = generateMnemonic(english)
-  generatedWords.value = generatedMnemonic.value.split(' ')
-  backupConfirmed.value = false
-  step.value = 'generate'
+  errorMessage.value = ''
+  step.value = 'generating'
+  try {
+    const { generateMnemonic, english } = await import('viem/accounts')
+    generatedMnemonic.value = generateMnemonic(english)
+    generatedWords.value = generatedMnemonic.value.split(' ')
+    backupConfirmed.value = false
+    step.value = 'generate'
+  } catch (error) {
+    console.error('Failed to create in-app wallet:', error)
+    errorMessage.value = 'Failed to create wallet. Please try again.'
+    step.value = 'choose'
+  }
 }
 
 async function connectWithMnemonic(mnemonic: string) {
+  if (!inAppConnector.value) {
+    throw new Error('In-app wallet connector is unavailable')
+  }
   await prepareInAppWallet(mnemonic)
-  await connectAsync({ connector: inAppConnector.value! })
+  await connectAsync({ connector: inAppConnector.value })
 }
 
 async function confirmGenerated() {
+  errorMessage.value = ''
   step.value = 'connecting'
   try {
     await connectWithMnemonic(generatedMnemonic.value)
     emit('connected')
   } catch (e) {
     console.error('Failed to connect in-app wallet:', e)
+    errorMessage.value = 'Failed to connect wallet. Please try again.'
     step.value = 'generate'
   }
 }
 
 async function restoreWallet() {
   if (!restoreValid.value) return
+  errorMessage.value = ''
   step.value = 'connecting'
   try {
     await connectWithMnemonic(restorePhrase.value)
     emit('connected')
   } catch (e) {
     console.error('Failed to restore in-app wallet:', e)
+    errorMessage.value = 'Failed to restore wallet. Please try again.'
     step.value = 'restore'
   }
 }
+
+function goBack() {
+  errorMessage.value = ''
+  if (props.initialStep === 'choose') {
+    step.value = 'choose'
+    return
+  }
+  emit('back')
+}
+
+onMounted(() => {
+  if (props.initialStep === 'create') void startGenerate()
+})
 </script>
 
 <style scoped>
diff --git a/packages/components.evm/src/index.ts b/packages/components.evm/src/index.ts
index 9d519c37..2f02996c 100644
--- a/packages/components.evm/src/index.ts
+++ b/packages/components.evm/src/index.ts
@@ -12,6 +12,8 @@ export type {
   EvmArtifactProps,
   EvmArtifactEmits,
   EvmAvatarProps,
+  EvmConnectorFilter,
+  EvmConnectProps,
   EvmConnectEmits,
   EvmConnectDialogProps,
   EvmConnectDialogEmits,
@@ -42,6 +44,7 @@ export type {
   EvmMultiTransactionFlowDialogEmits,
   EvmSeedPhraseInputProps,
   EvmSeedPhraseInputEmits,
+  EvmInAppWalletInitialStep,
   EvmInAppWalletSetupProps,
   EvmInAppWalletSetupEmits,
   EvmSiweProps,
diff --git a/packages/components.evm/src/types.ts b/packages/components.evm/src/types.ts
index 22049168..fe75f0bc 100644
--- a/packages/components.evm/src/types.ts
+++ b/packages/components.evm/src/types.ts
@@ -71,19 +71,28 @@ export interface EvmAvatarProps {
 }
 
 // EvmConnect
+export type EvmConnectorFilter = 'all' | 'external' | 'in-app'
+
+export interface EvmConnectProps {
+  connectorFilter?: EvmConnectorFilter
+  inAppWalletInitialStep?: EvmInAppWalletInitialStep
+}
+
 export interface EvmConnectEmits {
   connecting: []
   connected: []
+  back: []
 }
 
 // EvmConnectDialog
-export interface EvmConnectDialogProps {
+export interface EvmConnectDialogProps extends EvmConnectProps {
   className?: string
 }
 
 export interface EvmConnectDialogEmits {
   connected: [{ address: `0x${string}` | undefined }]
   disconnected: []
+  back: []
 }
 
 // EvmProfile
@@ -258,8 +267,11 @@ export interface EvmSeedPhraseInputEmits {
 }
 
 // EvmInAppWalletSetup
+export type EvmInAppWalletInitialStep = 'choose' | 'create' | 'restore'
+
 export interface EvmInAppWalletSetupProps {
   note?: string
+  initialStep?: EvmInAppWalletInitialStep
 }
 
 export interface EvmInAppWalletSetupEmits {
@@ -302,7 +314,7 @@ export interface EvmSiweDialogEmits {
 }
 
 // EvmConnectAuth
-export type EvmConnectAuthProps = EvmSiweProps
+export interface EvmConnectAuthProps extends EvmSiweProps, EvmConnectProps {}
 
 export interface EvmConnectAuthEmits {
   connecting: []
@@ -310,10 +322,12 @@ export interface EvmConnectAuthEmits {
   authenticated: [{ address: `0x${string}`; chainId: number }]
   signedOut: []
   error: [error: string]
+  back: []
 }
 
 // EvmConnectAuthDialog
-export interface EvmConnectAuthDialogProps extends EvmSiweProps {
+export interface EvmConnectAuthDialogProps
+  extends EvmSiweProps, EvmConnectProps {
   className?: string
   noTrigger?: boolean
 }
@@ -324,4 +338,5 @@ export interface EvmConnectAuthDialogEmits {
   authenticated: [{ address: `0x${string}`; chainId: number }]
   signedOut: []
   error: [error: string]
+  back: []
 }