@gluwa/connect-kit 0.2.0-next.1 → 0.2.0-next.11

package/src/components/walletItem/index.tsx

@@ -0,0 +1,49 @@
+import { type FC } from 'react';
+import './style.scss';
+import { type ConnectorId } from '../../types';
+
+interface WalletItemProps {
+  id: ConnectorId;
+  label: string;
+  logoUrl?: string;
+  isSelected: boolean;
+  isRecent?: boolean;
+  onSelect: (id: ConnectorId) => void;
+}
+
+export const WalletItem: FC<WalletItemProps> = ({
+  id,
+  label,
+  logoUrl,
+  isSelected,
+  isRecent = false,
+  onSelect,
+}) => {
+  return (
+    <button
+      type="button"
+      className={`ck-wallet-item${isSelected ? ' is-selected' : ''}`}
+      onClick={() => onSelect(id)}
+      aria-pressed={isSelected}
+    >
+      {logoUrl ? (
+        <img
+          className={`ck-wallet-item-icon${id === 'METAMASK' ? ' has-bg' : ''}`}
+          src={logoUrl}
+          alt=""
+          aria-hidden="true"
+        />
+      ) : (
+        <span className="ck-wallet-item-icon" aria-hidden="true" />
+      )}
+      <span className="ck-wallet-item-txt">
+        <span className="ck-wallet-item-label">{label}</span>
+        {isRecent && (
+          <span className="ck-wallet-item-badge" aria-label="Recently used">
+            Recent
+          </span>
+        )}
+      </span>
+    </button>
+  );
+};

package/src/components/walletItem/style.scss

@@ -0,0 +1,70 @@
+@use '../../style/mixin.scss' as *;
+
+.ck-root .ck-wallet-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  padding: 14px 20px;
+  border-radius: 12px;
+  background: var(--scale-gray-100);
+  cursor: pointer;
+  transition: background 0.15s ease;
+
+  &:hover {
+    background: var(--scale-gray-200);
+  }
+
+  &.is-selected {
+    background: var(--semantic-brand-trugi-primary);
+
+    .ck-wallet-item-label {
+      color: var(--static-white-main);
+    }
+
+    .ck-wallet-item-badge {
+      background: var(--static-white-alpha-200);
+      color: var(--static-white-main);
+    }
+  }
+}
+
+.ck-wallet-item-icon {
+  width: 36px;
+  height: 36px;
+  border-radius: 8px;
+  flex-shrink: 0;
+  overflow: hidden;
+  object-fit: cover;
+
+  &.has-bg {
+    background: var(--static-white-main);
+    padding: 2px;
+  }
+}
+
+.ck-wallet-item-txt {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+}
+
+.ck-wallet-item-label {
+  @include textToken('label3-bold');
+  color: var(--scale-gray-900);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex-shrink: 1;
+}
+
+.ck-wallet-item-badge {
+  @include textToken('caption3-bold');
+  color: var(--semantic-brand-trugi-primary);
+  background: var(--scale-blue2-alpha-100);
+  padding: 4px 8px;
+  border-radius: 500px;
+  flex-shrink: 0;
+}

package/src/connector-meta.ts

@@ -1,5 +1,5 @@
 import { type ConnectorId } from './types';
-import creditWalletIcon from '../assets/creditwallet.png';
+import penguinWalletIcon from '../assets/penguinwallet.png';
 import metaMaskIcon from '../assets/metamask.png';
 import wcIcon from '../assets/wc.png';
 
@@ -13,17 +13,10 @@ export interface ConnectorMeta {
 
 export const CONNECTOR_META: Record<ConnectorId, ConnectorMeta> = {
   CREDIT_CONNECT: {
-    label: 'Continue with Credit Wallet',
-    detailTitle: 'Scan with Credit Wallet',
+    label: 'Continue with PenguinWallet',
+    detailTitle: 'Scan with PenguinWallet',
     downloadUrl: 'https://creditwallet.onelink.me/Jv54',
-    logoUrl: creditWalletIcon,
-    // deepLinkBase: TODO — 앱 측 CC 딥링크 스킴 확정 후 추가
-  },
-  CREDIT_WALLET: {
-    label: 'Credit Wallet',
-    detailTitle: 'Scan with Credit Wallet',
-    downloadUrl: 'https://creditwallet.onelink.me/Jv54',
-    logoUrl: creditWalletIcon,
+    logoUrl: penguinWalletIcon,
     deepLinkBase: 'creditwallet://',
   },
   METAMASK: {
@@ -39,3 +32,15 @@ export const CONNECTOR_META: Record<ConnectorId, ConnectorMeta> = {
     logoUrl: wcIcon,
   },
 };
+
+// wagmi connector id (예: 'credit-connect' · 'metaMaskSDK' · 'walletConnect') → kit ConnectorId.
+// wagmi storage 의 recentConnectorId 복원 · account.connector 식별에 공용 사용.
+export const resolveConnectorId = (wagmiConnectorId: string | undefined): ConnectorId | null => {
+  if (!wagmiConnectorId) return null;
+  if (wagmiConnectorId === 'credit-connect') return 'CREDIT_CONNECT';
+  if (wagmiConnectorId === 'walletConnect') return 'WALLET_CONNECT';
+  const lower = wagmiConnectorId.toLowerCase();
+  if (lower.includes('metamask') || wagmiConnectorId === 'injected') return 'METAMASK';
+  if (lower.includes('walletconnect')) return 'WALLET_CONNECT';
+  return null;
+};

package/src/core/config.ts

@@ -2,6 +2,10 @@ import { createConfig, createStorage } from 'wagmi';
 import { metaMask, walletConnect, injected } from 'wagmi/connectors';
 import type { Config } from 'wagmi';
 import type { ConnectKitConfig } from '../types';
+import { creditConnectConnector } from '../creditConnectConnector';
+import { LocalStorageProvider } from '@gluwa/credit-connect-storage-local';
+import { tweetNaclE2EE } from '@gluwa/credit-connect-e2ee-tweetnacl';
+import { wsHubFactory } from '@gluwa/credit-connect-hub-node-ws';
 
 type KitSlot = {
   config: Config | null;
@@ -40,7 +44,22 @@ export const initConfig = (kitConfig: ConnectKitConfig): Config => {
     connectors.push(walletConnect({ projectId: kitConfig.wcProjectId, showQrModal: false }));
   }
 
-  connectors.push(metaMask({ storage: { enabled: true } }), injected({ shimDisconnect: false }));
+  connectors.push(
+    metaMask({ headless: true, storage: { enabled: true } }),
+    injected({ shimDisconnect: false }),
+  );
+
+  if (kitConfig.creditConnect) {
+    connectors.push(
+      creditConnectConnector({
+        projectKey: kitConfig.creditConnect.projectId,
+        serverUrl: kitConfig.creditConnect.serverUrl,
+        storage: new LocalStorageProvider(),
+        e2ee: tweetNaclE2EE,
+        createHub: wsHubFactory.createHubFromDapp,
+      }),
+    );
+  }
 
   if (kitConfig.extraConnectors?.length) {
     connectors.push(...kitConfig.extraConnectors);

package/src/creditConnectConnector.ts

@@ -84,18 +84,35 @@ export const creditConnectConnector = (
     });
 
     manager.on('changeState', (state) => {
+      // eslint-disable-next-line no-console
+      console.log('[CC connector] manager state →', state.status, {
+        hasConnectingPayload: Boolean(state.connectingPayload),
+        hasSession: 'session' in state && Boolean((state as { session?: unknown }).session),
+      });
       if (state.status === 'CONNECTING' && state.connectingPayload) {
+        // eslint-disable-next-line no-console
+        console.log('[CC connector] emit display_uri', {
+          payloadPrefix: state.connectingPayload.slice(0, 80),
+        });
         options.onDisplayUri?.(state.connectingPayload);
         emitWagmiMessage?.('display_uri', state.connectingPayload);
       }
 
       if (state.status === 'DISCONNECTED' && !isLocalDisconnect) {
+        // eslint-disable-next-line no-console
+        console.log('[CC connector] DISCONNECTED (non-local) → resetState + emit');
         resetState();
         emitProviderEvent('disconnect');
         emitWagmiDisconnect?.();
       }
     });
 
+    manager.on('sessionExpired', (payload) => {
+      // eslint-disable-next-line no-console
+      console.log('[CC connector] session expired → emit session_expired', payload);
+      emitWagmiMessage?.('session_expired', payload);
+    });
+
     return manager;
   };
 
@@ -343,32 +360,13 @@ export const creditConnectConnector = (
             });
           }
 
-          if (m.state.status === 'CONNECTING' && m.state.connectingPayload) {
-            options.onDisplayUri?.(m.state.connectingPayload);
-
-            if (!connectPromise) {
-              connectPromise = new Promise<boolean>((resolve) => {
-                const unsub = m.on('changeState', (state) => {
-                  if (state.status === 'CONNECTED') {
-                    unsub();
-                    resolve(true);
-                  } else if (state.status === 'DISCONNECTED') {
-                    unsub();
-                    resolve(false);
-                  }
-                });
-              });
-            }
-          }
-
+          // 새 connect 시도 — stale state (CONNECTING/CONNECTING_WAITING_PAYLOAD) 와
+          // stale connectPromise 는 SDK 의 self-heal (cleanupHub + attempt-id) 에 위임.
+          // connector 는 단순히 새 connectNewSession() 을 호출 — 이전 attempt 는 자연 정리됨.
           if (m.state.status !== 'CONNECTED') {
-            if (!connectPromise) {
-              if (m.state.status !== 'DISCONNECTED') {
-                throw new Error(`Cannot connect from ${m.state.status} state`);
-              }
-              connectPromise = m.connectNewSession();
-            }
-
+            // 이전 attempt 의 await 가 살아있어도, SDK 의 attempt-id 패턴이
+            // 그 결과를 무시하도록 보장한다. connectPromise 는 무조건 새 promise 로.
+            connectPromise = m.connectNewSession();
             const connected = await connectPromise;
             connectPromise = null;
 

package/src/events/account.ts

@@ -2,12 +2,14 @@ import {
   watchAccount as wagmiWatchAccount,
   watchConnections as wagmiWatchConnections,
   reconnect as wagmiReconnect,
+  connect as wagmiConnect,
+  getAccount as wagmiGetAccount,
   disconnect as wagmiDisconnect,
   type WatchAccountParameters,
   type WatchConnectionsParameters,
   type ReconnectReturnType,
 } from '@wagmi/core';
-import { getConfig } from '../core/config';
+import { getConfig, getKitConfig } from '../core/config';
 
 export const watchAccount = (params: WatchAccountParameters): (() => void) => {
   return wagmiWatchAccount(getConfig(), params);
@@ -17,8 +19,33 @@ export const watchConnections = (params: WatchConnectionsParameters): (() => voi
   return wagmiWatchConnections(getConfig(), params);
 };
 
-export const reconnect = (): Promise<ReconnectReturnType> => {
-  return wagmiReconnect(getConfig());
+export const reconnect = async (): Promise<ReconnectReturnType> => {
+  const config = getConfig();
+
+  if (getKitConfig().autoConnectInjected !== false) {
+    try {
+      const injected = config.connectors.find((connector) => connector.type === 'injected');
+      if (injected) {
+        const provider = (await injected.getProvider()) as
+          | { request?: (args: { method: string }) => Promise<unknown> }
+          | undefined;
+        const accounts = provider?.request
+          ? await provider.request({ method: 'eth_accounts' })
+          : [];
+        if (Array.isArray(accounts) && accounts.length > 0) {
+          await wagmiConnect(config, { connector: injected });
+        }
+      }
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn('injected auto-connect skipped (non-fatal):', error);
+    }
+  }
+
+  if (wagmiGetAccount(config).status === 'connected') {
+    return [];
+  }
+  return wagmiReconnect(config);
 };
 
 export const disconnectAll = async (

package/src/hooks/useConnectBanner.ts

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react';
+import type { ConnectBanner, ConnectBannerSiteKey } from '../types';
+
+interface ConnectBannersResponse {
+  banners: ConnectBanner[];
+}
+
+interface UseConnectBannerParams {
+  open: boolean;
+  siteKey: ConnectBannerSiteKey;
+  url: string;
+}
+
+interface UseConnectBannerResult {
+  banner: ConnectBanner | null;
+  loading: boolean;
+}
+
+const pickRandomBanner = (banners: ConnectBanner[]): ConnectBanner | null =>
+  banners[Math.floor(Math.random() * banners.length)] ?? null;
+
+export const useConnectBanner = ({
+  open,
+  siteKey,
+  url,
+}: UseConnectBannerParams): UseConnectBannerResult => {
+  const [candidates, setCandidates] = useState<ConnectBanner[]>([]);
+  const [banner, setBanner] = useState<ConnectBanner | null>(null);
+  const [loading, setLoading] = useState(true);
+  const wasOpenRef = useRef(open);
+
+  useEffect(() => {
+    if (!url) {
+      setCandidates([]);
+      setBanner(null);
+      setLoading(false);
+      return;
+    }
+
+    const controller = new AbortController();
+    setCandidates([]);
+    setBanner(null);
+    setLoading(true);
+
+    fetch(url, { signal: controller.signal })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`Failed to fetch connect banners: ${response.status}`);
+        return (await response.json()) as ConnectBannersResponse;
+      })
+      .then(({ banners }) => {
+        if (controller.signal.aborted) return;
+        if (!Array.isArray(banners)) {
+          setLoading(false);
+          return;
+        }
+
+        const nextCandidates = banners.filter((item) => item.siteKey !== siteKey);
+        setCandidates(nextCandidates);
+        setBanner(pickRandomBanner(nextCandidates));
+        setLoading(false);
+      })
+      .catch(() => {
+        // API 실패 시 기존 Idle placeholder를 유지한다.
+        if (!controller.signal.aborted) setLoading(false);
+      });
+
+    return () => controller.abort();
+  }, [siteKey, url]);
+
+  useEffect(() => {
+    const wasOpen = wasOpenRef.current;
+    wasOpenRef.current = open;
+
+    // 닫힌 dialog 안에서 다음 배너 이미지를 미리 렌더링한다.
+    if (wasOpen && !open) setBanner(pickRandomBanner(candidates));
+  }, [candidates, open]);
+
+  return { banner, loading };
+};

package/src/hooks/useConnectTimeout.ts

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { type ConnectorId } from '../types';
+
+// MM / CC 폴백용 기본 타임아웃. (CC 는 원칙적으로 서버 push 로 만료가 오지만,
+// 서버 값이 없거나 신호가 유실된 경우를 대비한 폴백 용도로도 쓸 수 있음.)
+export const DEFAULT_CONNECT_TIMEOUT_MS = 300_000;
+
+interface UseConnectTimeoutParams {
+  /** 현재 연결 시도 중인 커넥터. null = 유휴 상태. */
+  connectorId: ConnectorId | null;
+  /** 타임아웃 감시 활성화 여부 — pending/QR 표시 중일 때 true. */
+  active: boolean;
+  /** Wagmi connect promise가 실제로 대기 중인지 여부. */
+  isConnecting: boolean;
+  /**
+   * 외부 이벤트 기반 실패/만료 신호. 값이 증가할 때마다 연결 실패로 간주.
+   * - CC: dialog 가 connector 의 `session_expired`(서버 push) 를 받아 올림.
+   * - MM: connect promise reject.
+   * - WC: dialog 가 WC connect promise reject(프로토콜 ~5분 만료 등) 를 받아 올림.
+   */
+  expiredSignal?: number;
+  /** "Try Again" 시 실행할 재연결 로직 (dialog 가 주입). */
+  onRetry?: () => void;
+}
+
+interface UseConnectTimeoutResult {
+  /** 타임아웃 발생 여부 — true 면 dialog 가 <Timeout> 을 렌더. */
+  timedOut: boolean;
+  /** 다른 지갑 연결을 시작하기 전에 이전 타임아웃 상태를 즉시 초기화. */
+  reset: () => void;
+  /** "Try Again" 버튼에 연결할 함수 — 상태 리셋 + onRetry 실행. */
+  retry: () => void;
+}
+
+/**
+ * 커넥터별로 타임아웃 신호원을 분기해 하나의 `timedOut` 으로 수렴시키는 훅.
+ * - CC: 서버 push (`OnSessionExpired` → connector → expiredSignal).
+ * - MM: 네이티브 타임아웃 없음 → client 타이머(DEFAULT_CONNECT_TIMEOUT_MS).
+ * - WC: 프로토콜 자체 ~5분 proposal reject → connect promise reject → expiredSignal.
+ */
+export const useConnectTimeout = ({
+  connectorId,
+  active,
+  isConnecting,
+  expiredSignal = 0,
+  onRetry,
+}: UseConnectTimeoutParams): UseConnectTimeoutResult => {
+  const [timedOut, setTimedOut] = useState(false);
+
+  const fire = useCallback(() => {
+    setTimedOut(true);
+  }, []);
+
+  // 커넥터가 바뀌면(=새 연결 시도) 타임아웃 상태 리셋.
+  // active 가 false 로 떨어질 때는 리셋하지 않는다 — timeout UI 표시 중 상태가 날아가지 않도록.
+  useEffect(() => {
+    setTimedOut(false);
+  }, [connectorId]);
+
+  // MM 만 client 타이머로 강제 (승인 대기에 네이티브 상한이 없음).
+  // CC(서버 push) / WC(connect reject) 는 아래 expiredSignal effect 에서 처리.
+  useEffect(() => {
+    if (!active || !isConnecting || connectorId !== 'METAMASK') return;
+    const timer = setTimeout(fire, DEFAULT_CONNECT_TIMEOUT_MS);
+    return () => clearTimeout(timer);
+  }, [active, isConnecting, connectorId, fire]);
+
+  // 외부 실패/만료 신호 처리 (CC 서버 push / MM·WC connect reject).
+  // signal 값이 올라가면(새 만료 이벤트) 발화.
+  const prevSignal = useRef(expiredSignal);
+  useEffect(() => {
+    if (!active || !connectorId) {
+      prevSignal.current = expiredSignal;
+      return;
+    }
+    if (expiredSignal !== prevSignal.current) {
+      prevSignal.current = expiredSignal;
+      fire();
+    }
+  }, [expiredSignal, connectorId, active, fire]);
+
+  const retry = useCallback(() => {
+    setTimedOut(false);
+    onRetry?.();
+  }, [onRetry]);
+
+  const reset = useCallback(() => {
+    setTimedOut(false);
+  }, []);
+
+  return { timedOut, reset, retry };
+};

package/src/hooks/useMetaMaskExtension.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+
+const METAMASK_RDNS = 'io.metamask';
+
+// EIP-6963 응답의 rdns 로 MetaMask 확장을 식별.
+const isMetaMaskAnnouncement = (event: Event): boolean => {
+  const detail = (event as CustomEvent<{ info?: { rdns?: string }; provider?: unknown }>).detail;
+  return detail?.info?.rdns?.toLowerCase() === METAMASK_RDNS && detail.provider != null;
+};
+
+export const useMetaMaskExtension = (): boolean => {
+  const [isInstalled, setIsInstalled] = useState(false);
+
+  useEffect(() => {
+    const handleAnnouncement = (event: Event): void => {
+      if (isMetaMaskAnnouncement(event)) setIsInstalled(true);
+    };
+
+    // 응답 listener를 먼저 등록한 뒤 설치된 provider 목록을 요청.
+    window.addEventListener('eip6963:announceProvider', handleAnnouncement);
+    window.dispatchEvent(new Event('eip6963:requestProvider'));
+
+    return () => {
+      window.removeEventListener('eip6963:announceProvider', handleAnnouncement);
+    };
+  }, []);
+
+  return isInstalled;
+};

package/src/hooks/useWCState.ts

@@ -1,8 +1,20 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import type { WCWallet, WCSubView } from '../types';
+// TODO-CRCN-11: WC에 PenguinWallet 추가 시 변경
+import { CREDIT_WALLET_LISTING_ID, overrideWalletDisplay } from '../wallet-display-override';
+
+const sortCreditWalletFirst = (list: WCWallet[]): WCWallet[] =>
+  [...list].sort((a, b) => {
+    // TODO-CRCN-11: WC에 PenguinWallet 추가 시 변경
+    if (a.id === CREDIT_WALLET_LISTING_ID) return -1;
+    if (b.id === CREDIT_WALLET_LISTING_ID) return 1;
+    return 0;
+  });
 
 const fetchWCWalletList = async (projectId: string, signal?: AbortSignal): Promise<WCWallet[]> => {
-  const all: WCWallet[] = [];
+  // WC Explorer API 가 page 경계에서 같은 wallet 을 중복 emit 하는 케이스 관찰됨
+  // (paginate 사이 sort/dedup 보장 X). id 기준 first-write-wins dedup.
+  const byId = new Map<string, WCWallet>();
   let page = 1;
   const entries = 100;
 
@@ -34,7 +46,8 @@ const fetchWCWalletList = async (projectId: string, signal?: AbortSignal): Promi
 
     const listings = Object.values(json.listings ?? {});
     for (const w of listings) {
-      all.push({
+      if (byId.has(w.id)) continue;
+      byId.set(w.id, {
         id: w.id,
         name: w.name,
         imageUrl: w.image_url?.md ?? w.image_url?.sm ?? '',
@@ -48,11 +61,11 @@ const fetchWCWalletList = async (projectId: string, signal?: AbortSignal): Promi
       });
     }
 
-    if (listings.length < entries || all.length >= json.total) break;
+    if (listings.length < entries || byId.size >= json.total) break;
     page += 1;
   }
 
-  return all;
+  return Array.from(byId.values());
 };
 
 export interface WCState {
@@ -100,7 +113,10 @@ export const useWCState = (): WCState => {
     setWalletListLoading(true);
     try {
       const list = await fetchWCWalletList(projectId, controller.signal);
-      if (isMountedRef.current) setWalletList(list);
+      // TODO-CRCN-11: WC에 PenguinWallet 추가 시 변경
+      const sorted = sortCreditWalletFirst(list).map(overrideWalletDisplay);
+      // Credit Wallet 을 최상단으로 정렬한 상태로 state 저장 — view 측은 정렬 신경 X.
+      if (isMountedRef.current) setWalletList(sorted);
     } catch (err) {
       const isAbort = err instanceof DOMException && err.name === 'AbortError';
       if (!isAbort) loadedRef.current = false;

package/src/hooks/useWagmiConnect.ts

@@ -13,15 +13,10 @@ const hasMetaMaskKeyword = (value: string): boolean => value.toLowerCase().inclu
 const hasWalletConnectKeyword = (value: string): boolean =>
   value.toLowerCase().includes('walletconnect');
 
+// 전역 provider 대신 wagmi connector 메타데이터로 MetaMask를 판별.
 const isMetaMaskConnector = (connector: WagmiConnectorLike): boolean => {
   if (connector.id === 'metaMaskSDK') return true;
 
-  if (connector.id === 'injected') {
-    if (typeof window === 'undefined') return false;
-    const eth = (window as Window & { ethereum?: { isMetaMask?: boolean } }).ethereum;
-    return eth?.isMetaMask === true;
-  }
-
   if (hasMetaMaskKeyword(connector.id) || hasMetaMaskKeyword(connector.name)) return true;
 
   if (connector.rdns) {
@@ -49,7 +44,6 @@ export const resolveWagmiConnector = <T extends WagmiConnectorLike>(
     case 'METAMASK':
       return connectors.find(isMetaMaskConnector);
 
-    case 'CREDIT_WALLET':
     case 'WALLET_CONNECT':
       return connectors.find(isWalletConnectConnector);
 
@@ -62,11 +56,13 @@ interface Options {
   onConnect: (result: ConnectResult) => void;
   onError: (error: Error, connectorId: ConnectorId) => void;
   onQrUri: (uri: string | null) => void;
+  onSessionExpired?: () => void;
 }
 
 interface UseWagmiConnectResult {
   triggerConnect: (connectorId: ConnectorId) => void;
   cancelConnect: () => void;
+  restartConnect: (connectorId: ConnectorId) => Promise<void>;
   isConnecting: boolean;
 }
 
@@ -74,6 +70,7 @@ export const useWagmiConnect = ({
   onConnect,
   onError,
   onQrUri,
+  onSessionExpired,
 }: Options): UseWagmiConnectResult => {
   const config = useConfig();
   const pendingConnectorId = useRef<ConnectorId | null>(null);
@@ -82,11 +79,13 @@ export const useWagmiConnect = ({
   const onConnectRef = useRef(onConnect);
   const onErrorRef = useRef(onError);
   const onQrUriRef = useRef(onQrUri);
+  const onSessionExpiredRef = useRef(onSessionExpired);
   useEffect(() => {
     onConnectRef.current = onConnect;
     onErrorRef.current = onError;
     onQrUriRef.current = onQrUri;
-  }, [onConnect, onError, onQrUri]);
+    onSessionExpiredRef.current = onSessionExpired;
+  }, [onConnect, onError, onQrUri, onSessionExpired]);
 
   const { connectAsync, reset, isPending } = useConnect();
 
@@ -96,6 +95,9 @@ export const useWagmiConnect = ({
       if (msg?.type === 'display_uri' && typeof msg.data === 'string') {
         onQrUriRef.current(msg.data);
       }
+      if (msg?.type === 'session_expired') {
+        onSessionExpiredRef.current?.();
+      }
     };
 
     const unsubscribers = config.connectors.map((connector) => {
@@ -149,5 +151,29 @@ export const useWagmiConnect = ({
     reset();
   }, [reset]);
 
-  return { triggerConnect, cancelConnect, isConnecting: isPending };
+  const restartConnect = useCallback(
+    async (connectorId: ConnectorId): Promise<void> => {
+      const connector = resolveWagmiConnector(config.connectors, connectorId);
+
+      cancelConnect();
+      const restartAttempt = attemptCounter.current;
+
+      try {
+        // MetaMask SDK connector.disconnect()는 sdk.terminate()를 호출해
+        // 기존 QR/Deeplink 연결 채널을 정리한다.
+        await connector?.disconnect();
+      } catch (error) {
+        onErrorRef.current(error as Error, connectorId);
+        throw error;
+      }
+
+      // SDK 정리 중 다른 지갑을 선택하거나 모달을 닫았으면 재연결하지 않는다.
+      if (attemptCounter.current !== restartAttempt) return;
+
+      triggerConnect(connectorId);
+    },
+    [config.connectors, cancelConnect, triggerConnect],
+  );
+
+  return { triggerConnect, cancelConnect, restartConnect, isConnecting: isPending };
 };