@gluwa/connect-kit 0.1.0-next.3 → 0.2.0-next.10

package/src/layout/connectDialog/asset/spinner.tsx

@@ -0,0 +1,21 @@
+import { type FC, type SVGProps } from 'react';
+
+export const Spinner: FC<SVGProps<SVGSVGElement>> = (props) => {
+  return (
+    <svg
+      width={40}
+      height={40}
+      viewBox="0 0 40 40"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path
+        d="M19.995 3.34375C20.9155 3.34375 21.6617 4.08995 21.6617 5.01042V10.0104C21.6617 10.9309 20.9155 11.6771 19.995 11.6771C19.0745 11.6771 18.3284 10.9309 18.3284 10.0104V5.01042C18.3284 4.08995 19.0745 3.34375 19.995 3.34375ZM19.995 28.3438C20.9155 28.3438 21.6617 29.0899 21.6617 30.0104V35.0104C21.6617 35.9309 20.9155 36.6771 19.995 36.6771C19.0745 36.6771 18.3284 35.9309 18.3284 35.0104V30.0104C18.3284 29.0899 19.0745 28.3438 19.995 28.3438ZM36.6617 20.0104C36.6617 20.9309 35.9155 21.6771 34.995 21.6771H29.995C29.0745 21.6771 28.3284 20.9309 28.3284 20.0104C28.3284 19.0899 29.0745 18.3438 29.995 18.3438H34.995C35.9155 18.3438 36.6617 19.0899 36.6617 20.0104ZM11.6617 20.0104C11.6617 20.9309 10.9155 21.6771 9.99504 21.6771H4.99504C4.07457 21.6771 3.32837 20.9309 3.32837 20.0104C3.32837 19.0899 4.07457 18.3438 4.99504 18.3438H9.99504C10.9155 18.3438 11.6617 19.0899 11.6617 20.0104ZM31.7802 31.7956C31.1292 32.4464 30.074 32.4464 29.4232 31.7956L25.8875 28.2599C25.2367 27.6091 25.2367 26.5539 25.8875 25.9029C26.5385 25.2521 27.5937 25.2521 28.2445 25.9029L31.7802 29.4386C32.431 30.0894 32.431 31.1446 31.7802 31.7956ZM14.1025 14.1179C13.4516 14.7687 12.3963 14.7687 11.7455 14.1179L8.20992 10.5823C7.55905 9.93145 7.55905 8.87618 8.20992 8.2253C8.8608 7.57443 9.91607 7.57443 10.567 8.2253L14.1025 11.7608C14.7534 12.4117 14.7534 13.467 14.1025 14.1179ZM8.20992 31.7956C7.55905 31.1446 7.55905 30.0894 8.20992 29.4386L11.7455 25.9029C12.3963 25.2521 13.4516 25.2521 14.1025 25.9029C14.7534 26.5539 14.7534 27.6091 14.1025 28.2599L10.567 31.7956C9.91607 32.4464 8.8608 32.4464 8.20992 31.7956ZM25.8875 14.1179C25.2367 13.467 25.2367 12.4117 25.8875 11.7608L29.4232 8.2253C30.074 7.57443 31.1292 7.57443 31.7802 8.2253C32.431 8.87618 32.431 9.93145 31.7802 10.5823L28.2445 14.1179C27.5937 14.7687 26.5385 14.7687 25.8875 14.1179Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};

package/src/layout/connectDialog/asset/warningIcon.tsx

@@ -0,0 +1,21 @@
+import { type FC, type SVGProps } from 'react';
+
+export const WarningIcon: FC<SVGProps<SVGSVGElement>> = (props) => {
+  return (
+    <svg
+      width={20}
+      height={18}
+      viewBox="0 0 20 18"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path
+        d="M9.05688 0.833252C9.47596 0.107398 10.5234 0.107541 10.9426 0.833252L19.6663 15.9417C20.0852 16.6675 19.561 17.5744 18.7229 17.5745H1.27759C0.43938 17.5745 -0.0848319 16.6676 0.334229 15.9417L9.05688 0.833252ZM9.26685 13.0491V14.5149H10.7327V13.0491H9.26685ZM9.26685 6.65747V12.1018H10.7327V6.65747H9.26685Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};

package/src/layout/connectDialog/idle/index.tsx

@@ -0,0 +1,55 @@
+import { type FC } from 'react';
+import { LinkIcon } from '../asset/linkIcon';
+import placeholderImage from './assets/banner-placeholder.png';
+import './style.scss';
+
+interface IdleProps {
+  title?: string;
+  description?: string;
+  linkText?: string;
+  linkUrl?: string;
+  imageUrl?: string;
+  titleColor?: string;
+  descriptionColor?: string;
+  linkTextColor?: string;
+}
+
+export const Idle: FC<IdleProps> = ({
+  title = 'PenguinWallet',
+  description = `Your non-custodial gateway to the Creditcoin network.
+    Hold tokens, swap, and play ecosystem games in one app.`,
+  linkText = 'Download',
+  linkUrl = 'https://creditcoin.org/Penguin-Wallet',
+  imageUrl = placeholderImage,
+  titleColor = '#FFFFFF',
+  descriptionColor = '#888A8C',
+  linkTextColor = '#3374FF',
+}) => {
+  return (
+    <div className="ck-idle">
+      <img className="ck-idle-bg" src={imageUrl} alt="" />
+      {title && (
+        <h3 className="ck-idle-title" style={{ color: titleColor }}>
+          {title}
+        </h3>
+      )}
+      {description && (
+        <p className="ck-idle-desc" style={{ color: descriptionColor }}>
+          {description}
+        </p>
+      )}
+      {linkText && linkUrl && (
+        <a
+          className="ck-idle-link"
+          href={linkUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          style={{ color: linkTextColor }}
+        >
+          <span>{linkText}</span>
+          <LinkIcon />
+        </a>
+      )}
+    </div>
+  );
+};

package/src/layout/connectDialog/idle/style.scss

@@ -0,0 +1,52 @@
+@use '../../../style/mixin.scss' as *;
+.ck-root {
+  .ck-idle {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 6px;
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    padding: 60px;
+    box-sizing: border-box;
+  }
+
+  .ck-idle-bg {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    z-index: -1;
+  }
+
+  .ck-idle-title {
+    @include textToken('title1-bold'); 
+    color: var(--scale-gray-900);
+  }
+
+  .ck-idle-desc {
+    color: var(--scale-gray-600);
+    margin-top: 6px;
+    white-space: pre-line;
+    @include textToken('body4-l1-regular');
+  }
+
+  .ck-idle-link {
+    display: flex;
+    align-items: center;
+    margin: -2px -8px -8px -8px;
+    padding: 8px;
+
+    span {
+      @include textToken('body4-l1-bold');
+      color: inherit;
+    }
+
+    svg {
+      flex-shrink: 0;
+      color: inherit;
+    }
+  }
+}

package/src/layout/connectDialog/index.tsx

@@ -0,0 +1,432 @@
+import { type FC, useEffect, useRef, useState } from 'react';
+import { useConfig } from 'wagmi';
+import './style.scss';
+import {
+  type ConnectBannerSiteKey,
+  type ConnectorId,
+  type ConnectKitTheme,
+  type WCWallet,
+  type ConnectResult,
+} from '../../types';
+import { type DetailContent } from '../detailPanel';
+import { SelectorPanel } from '../selectorPanel';
+import { DetailPanel } from '../detailPanel';
+import { Toast } from '../../components/toast';
+import { resolveConnectorId } from '../../connector-meta';
+import { useMetaMaskExtension } from '../../hooks/useMetaMaskExtension';
+import { useWagmiConnect } from '../../hooks/useWagmiConnect';
+import { useConnectTimeout } from '../../hooks/useConnectTimeout';
+import { useConnectBanner } from '../../hooks/useConnectBanner';
+import { useWCState } from '../../hooks/useWCState';
+import { isMobileDevice, tryOpenDeepLink, tryOpenCreditWalletDeeplink } from '../../utils/platform';
+
+export type DialogStep = 'selector' | 'detail';
+
+export interface ConnectDialogProps {
+  open: boolean;
+  siteKey: ConnectBannerSiteKey;
+  connectBannerUrl: string;
+  theme?: ConnectKitTheme;
+  connectors?: ConnectorId[];
+  selectedConnector?: ConnectorId | null;
+  step?: DialogStep;
+  /** DEV: force initial content state for UI preview */
+  initialContent?: DetailContent;
+  /** WalletConnect Cloud projectId — useWCState.loadWalletList 호출 시 필요. */
+  wcProjectId?: string;
+  onSelectConnector?: (id: ConnectorId) => void;
+  onBack?: () => void;
+  onClose?: () => void;
+  onConnect?: (result: ConnectResult) => void;
+  onError?: (error: Error, connectorId: ConnectorId) => void;
+}
+
+const getContentForConnector = (id: ConnectorId): DetailContent => {
+  if (id === 'CREDIT_CONNECT') return 'qr';
+  if (id === 'METAMASK') return 'metamask-ext';
+  if (id === 'WALLET_CONNECT') return 'walletconnect';
+  return 'idle';
+};
+
+// MM 은 확장 감지 시 즉시 extension 연결, 아니면 QR. (select / retry 공통)
+const getInitialContentForConnector = (
+  id: ConnectorId,
+  isMetaMaskExtensionInstalled: boolean,
+): DetailContent =>
+  id === 'METAMASK' && !isMetaMaskExtensionInstalled ? 'metamask-qr' : getContentForConnector(id);
+
+const getErrorCode = (error: unknown, depth = 0): number | undefined => {
+  if (depth > 4 || !error || typeof error !== 'object') return undefined;
+
+  const candidate = error as { code?: unknown; cause?: unknown; error?: unknown };
+  const code = Number(candidate.code);
+  if (Number.isFinite(code)) return code;
+
+  return getErrorCode(candidate.cause, depth + 1) ?? getErrorCode(candidate.error, depth + 1);
+};
+
+const isMetaMaskPendingRequestError = (error: unknown): boolean => getErrorCode(error) === -32002;
+
+export const ConnectDialog: FC<ConnectDialogProps> = ({
+  open,
+  siteKey,
+  connectBannerUrl,
+  theme = 'dark',
+  connectors = ['CREDIT_CONNECT', 'METAMASK', 'WALLET_CONNECT'],
+  selectedConnector: selectedConnectorProp = null,
+  // NOTE: default values below are for dev/markup preview only
+  step: stepProp = 'detail',
+  wcProjectId,
+  onSelectConnector,
+  onBack,
+  onClose = () => undefined,
+  onConnect,
+  onError,
+}) => {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const [selectedConnector, setSelectedConnector] = useState<ConnectorId | null>(
+    selectedConnectorProp,
+  );
+  const [recentConnector, setRecentConnector] = useState<ConnectorId | null>(null);
+  const [selectedWallet, setSelectedWallet] = useState<WCWallet | null>(null);
+  const [step, setStep] = useState<DialogStep>(stepProp);
+  /**
+   * change this initial value to preview a specific content state.
+   * - 'idle'          selector만 표시 (detail 없음)
+   * - 'loading'       스피너
+   * - 'qr'            Credit Wallet QR
+   * - 'timeout'       연결 실패 화면
+   * - 'metamask-ext'  MetaMask 익스텐션 연결 요청
+   * - 'metamask-qr'   MetaMask QR
+   * - 'walletconnect' WalletConnect QR + All Wallets 버튼
+   * - 'all-wallets'   지갑 목록 그리드
+   * - 'wallet-qr'     개별 지갑 QR
+   */
+  const [content, setContent] = useState<DetailContent>('idle');
+  const [showCopyToast, setShowCopyToast] = useState(false);
+  const [showMetaMaskPendingRequestToast, setShowMetaMaskPendingRequestToast] = useState(false);
+  const [qrUri, setQrUri] = useState<string | null>(null);
+  // 외부 만료 신호 카운터 — CC(서버 push session_expired) / WC(connect reject) 수신 시 증가.
+  const [expiredSignal, setExpiredSignal] = useState(0);
+  // EIP-6963 기반 MetaMask 확장 설치 상태.
+  const isMetaMaskExtensionInstalled = useMetaMaskExtension();
+
+  // 현재 content 를 ref 로 추적 (effect deps 없이 최신값 참조용).
+  const contentRef = useRef<DetailContent>(content);
+  contentRef.current = content;
+  // 타임아웃 직전 화면 — retry 시 이 화면으로 복원 (예: WC 의 wallet-qr).
+  const preTimeoutContentRef = useRef<DetailContent>('idle');
+
+  const config = useConfig();
+  const { banner: connectBanner, loading: connectBannerLoading } = useConnectBanner({
+    open,
+    siteKey,
+    url: connectBannerUrl,
+  });
+
+  // wagmi connect + display_uri 이벤트 → qrUri state.
+  // 모든 wagmi connector 의 message 이벤트를 구독하므로 CC connector 의 display_uri emit 도 자동 포착.
+  const { triggerConnect, cancelConnect, restartConnect, isConnecting } = useWagmiConnect({
+    onConnect: (result) => {
+      // recent = 연결 성공 기준. wagmi 가 recentConnectorId 를 localStorage 에 저장하므로
+      // UI state 만 동기화. 다음 마운트 시 아래 effect 가 storage 에서 복원.
+      setRecentConnector(result.connectorId);
+      onConnect?.(result);
+    },
+    onError: (err, connectorId) => {
+      // MetaMask는 pending 요청을 사전에 조회할 수 없어 새 요청의 -32002 응답으로만 판별한다.
+      if (
+        connectorId === 'METAMASK' &&
+        isMetaMaskExtensionInstalled &&
+        isMetaMaskPendingRequestError(err)
+      ) {
+        setShowMetaMaskPendingRequestToast(true);
+      }
+
+      // MM/WC connect reject는 타이머를 기다리지 않고 즉시 실패 화면으로 전환.
+      if (connectorId === 'METAMASK' || connectorId === 'WALLET_CONNECT') {
+        setExpiredSignal((n) => n + 1);
+      }
+      onError?.(err, connectorId);
+    },
+    onQrUri: (uri) => setQrUri(uri),
+    // CC connector 가 서버 OnSessionExpired 를 릴레이 → 만료 신호 증가.
+    onSessionExpired: () => setExpiredSignal((n) => n + 1),
+  });
+
+  // 연결 타임아웃 (CC=서버 push / MM=client 타이머 / WC=connect reject) → timedOut.
+  const timeoutActive = step === 'detail' && !!selectedConnector && content !== 'timeout';
+  const {
+    timedOut,
+    reset: resetTimeout,
+    retry,
+  } = useConnectTimeout({
+    connectorId: selectedConnector,
+    active: timeoutActive,
+    isConnecting,
+    expiredSignal,
+    onRetry: () => {
+      if (!selectedConnector) return;
+      // 타임아웃 직전 화면으로 복원 (예: WC 의 wallet-qr → 선택 지갑 QR 유지).
+      // idle/timeout 처럼 복원 불가한 값이면 커넥터 초기 화면으로.
+      const restore = preTimeoutContentRef.current;
+      const nextContent: DetailContent =
+        restore !== 'idle' && restore !== 'timeout'
+          ? restore
+          : getInitialContentForConnector(selectedConnector, isMetaMaskExtensionInstalled);
+
+      // MetaMask 확장 pending 요청은 dApp에서 종료하거나 다시 요청할 수 없다.
+      // 실패 화면을 유지하고 기존 요청을 먼저 처리하도록 안내한다.
+      if (selectedConnector === 'METAMASK' && restore === 'metamask-ext' && isConnecting) {
+        setContent('timeout');
+        setShowMetaMaskPendingRequestToast(true);
+        return;
+      }
+
+      setContent(nextContent);
+      setQrUri(null);
+
+      // MetaMask QR/Deeplink는 SDK 채널을 종료한 뒤 새 요청을 생성한다.
+      if (selectedConnector === 'METAMASK' && restore === 'metamask-qr') {
+        restartConnect(selectedConnector).catch(() => undefined);
+        return;
+      }
+
+      cancelConnect();
+      triggerConnect(selectedConnector);
+    },
+  });
+
+  // 타임아웃 발생 → 진행 중 연결 취소 + timeout 화면 표시.
+  // 전환 전 화면을 저장해 retry 시 복원 (WC wallet-qr 등).
+  useEffect(() => {
+    // selector로 돌아간 렌더에 이전 timedOut이 잠시 남아도 실패 화면을 다시 덮지 않는다.
+    if (!timedOut || !selectedConnector || step !== 'detail') return;
+    // cancelConnect로 isConnecting이 바뀌어 effect가 다시 실행되어도
+    // 기록한 이전 화면을 timeout으로 덮어쓰지 않는다.
+    if (contentRef.current === 'timeout') return;
+    preTimeoutContentRef.current = contentRef.current;
+
+    // MetaMask 확장 pending 요청만 보존한다. QR/Deeplink는 Retry에서 SDK를 재시작한다.
+    const shouldPreserveMetaMaskRequest =
+      selectedConnector === 'METAMASK' && contentRef.current === 'metamask-ext' && isConnecting;
+    // 확장 승인 요청은 dApp에서 종료할 수 없으므로 원래 요청을 유지한다.
+    if (!shouldPreserveMetaMaskRequest) cancelConnect();
+    setContent('timeout');
+  }, [timedOut, selectedConnector, step, isConnecting, cancelConnect]);
+
+  // provider 응답이 늦게 도착하면 QR에서 확장 연결 화면으로 전환.
+  useEffect(() => {
+    if (
+      isMetaMaskExtensionInstalled &&
+      selectedConnector === 'METAMASK' &&
+      content === 'metamask-qr'
+    ) {
+      setContent('metamask-ext');
+    }
+  }, [isMetaMaskExtensionInstalled, selectedConnector, content]);
+
+  // 마운트 시 wagmi storage 의 recentConnectorId(연결 성공 시 wagmi 가 저장) 복원.
+  useEffect(() => {
+    const restoreRecent = async (): Promise<void> => {
+      const wagmiId = await config.storage?.getItem('recentConnectorId');
+      const resolved = resolveConnectorId(wagmiId ?? undefined);
+      if (resolved) setRecentConnector(resolved);
+    };
+    restoreRecent().catch(() => undefined);
+  }, [config]);
+
+  // WalletConnect Explorer API (walletList + loading + 등)
+  const wc = useWCState();
+
+  const handleSelect = (id: ConnectorId) => {
+    // 다른 지갑 선택은 이전 시도와 실패 상태를 이어받지 않고 항상 새 연결로 시작한다.
+    cancelConnect();
+    resetTimeout();
+    setQrUri(null);
+    setSelectedWallet(null);
+    setShowCopyToast(false);
+    setShowMetaMaskPendingRequestToast(false);
+    setSelectedConnector(id);
+    // recent 는 클릭이 아니라 연결 성공(onConnect) 시점에 기록 — 위 useWagmiConnect onConnect 참조.
+    setContent(getInitialContentForConnector(id, isMetaMaskExtensionInstalled));
+    setStep('detail');
+    // wagmi connect 시작 (display_uri 도착 시 setQrUri 자동 호출)
+    triggerConnect(id);
+    onSelectConnector?.(id);
+  };
+
+  const handleSelectWallet = (wallet: WCWallet) => {
+    setSelectedWallet(wallet);
+    setContent('wallet-qr');
+    // 자동 deeplink 는 아래 useEffect (selectedWallet + qrUri + content === 'wallet-qr') 에서.
+    // 모바일 + display_uri 도착 시 native/universal scheme 으로 redirect, 아니면 WalletQR fallback.
+  };
+
+  const handleBack = () => {
+    if (content === 'wallet-qr') {
+      setSelectedWallet(null);
+      setContent('all-wallets');
+      return;
+    }
+    if (content === 'all-wallets') {
+      setContent('walletconnect');
+      return;
+    }
+    // selector 로 복귀 → wagmi connect attempt 취소 + qrUri 초기화
+    cancelConnect();
+    setQrUri(null);
+    setSelectedConnector(null);
+    setContent('idle');
+    setStep('selector');
+    onBack?.();
+  };
+
+  const handleShowAllWallets = () => {
+    setContent('all-wallets');
+    // 처음 진입 시 WC Explorer API fetch (loadedRef guard 로 중복 호출 없음)
+    if (wcProjectId) {
+      wc.loadWalletList(wcProjectId).catch(() => undefined);
+    }
+  };
+
+  // showModal / close driven by open prop
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (open && !dialog.open) dialog.showModal();
+    if (!open && dialog.open) dialog.close();
+  }, [open]);
+
+  // selectedWallet 가 먼저 set 됐고 qrUri 가 뒤늦게 도착한 경우 자동 deeplink.
+  // 같은 지갑·URI 조합만 중복 방지하고, Retry로 새 URI가 오면 다시 실행한다.
+  const lastWalletDeeplinkKeyRef = useRef<string | null>(null);
+  useEffect(() => {
+    lastWalletDeeplinkKeyRef.current = null;
+  }, [selectedWallet]);
+  useEffect(() => {
+    if (!selectedWallet || !qrUri || content !== 'wallet-qr') return;
+    if (!isMobileDevice()) return;
+    const base = selectedWallet.mobileNative || selectedWallet.mobileUniversal;
+    if (!base) return;
+    const deeplinkKey = `${selectedWallet.id}:${qrUri}`;
+    if (lastWalletDeeplinkKeyRef.current === deeplinkKey) return;
+    lastWalletDeeplinkKeyRef.current = deeplinkKey;
+    tryOpenDeepLink(qrUri, base);
+  }, [selectedWallet, qrUri, content]);
+
+  // CC connector direct path: selector 의 'Continue with Credit Wallet' → content='qr'.
+  // wagmi MM connector 는 SDK 가 자체 deeplink 하지만 CC connector 는 emit display_uri 만 함 —
+  // kit 가 mobile redirect 책임. payload 는 full URL (`https://app.creditcoin.org/?creditconnect=...`).
+  const lastCreditConnectDeeplinkUriRef = useRef<string | null>(null);
+  useEffect(() => {
+    lastCreditConnectDeeplinkUriRef.current = null;
+  }, [selectedConnector]);
+  useEffect(() => {
+    if (content !== 'qr' || !qrUri) return;
+    if (selectedConnector !== 'CREDIT_CONNECT') return;
+    if (!isMobileDevice()) return;
+    if (lastCreditConnectDeeplinkUriRef.current === qrUri) return;
+    lastCreditConnectDeeplinkUriRef.current = qrUri;
+    tryOpenCreditWalletDeeplink(qrUri);
+  }, [content, qrUri, selectedConnector]);
+
+  // Prevent background scroll while dialog is open
+  useEffect(() => {
+    const prev = document.body.style.overflow;
+    if (open) document.body.style.overflow = 'hidden';
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  // Reset on close
+  useEffect(() => {
+    if (!open) {
+      cancelConnect();
+      setQrUri(null);
+      setSelectedConnector(null);
+      setContent('idle');
+      setStep('selector');
+      setShowCopyToast(false);
+      setShowMetaMaskPendingRequestToast(false);
+    }
+  }, [open, cancelConnect]);
+
+  // Intercept native Escape (cancel event) and delegate to onClose
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return undefined;
+    const handleCancel = (e: Event) => {
+      e.preventDefault();
+      setShowCopyToast(false);
+      setShowMetaMaskPendingRequestToast(false);
+      onClose();
+    };
+    dialog.addEventListener('cancel', handleCancel);
+    return () => dialog.removeEventListener('cancel', handleCancel);
+  }, [onClose]);
+
+  return (
+    <div className="ck-root" data-theme={theme} data-open={open}>
+      <dialog
+        ref={dialogRef}
+        className="ck-dialog"
+        data-step={step}
+        aria-label="Connect Wallet"
+        onClick={(e) => {
+          if (e.target === dialogRef.current) onClose();
+        }}
+      >
+        <SelectorPanel
+          connectors={connectors}
+          selectedConnector={selectedConnector}
+          recentConnector={recentConnector}
+          onSelect={handleSelect}
+          onClose={onClose}
+        />
+        <DetailPanel
+          connectBanner={connectBanner}
+          connectBannerLoading={connectBannerLoading}
+          selectedConnector={selectedConnector}
+          selectedWallet={selectedWallet}
+          content={content}
+          qrUri={qrUri}
+          wallets={wc.walletList}
+          walletListLoading={wc.walletListLoading}
+          walletCount={wc.walletList.length}
+          onBack={handleBack}
+          onClose={onClose}
+          onRetry={retry}
+          onShowAllWallets={handleShowAllWallets}
+          onSelectWallet={handleSelectWallet}
+          onCopyLink={() => {
+            // qrUri 미도착 시 silent no-op (사용자가 잘못 누른 게 아니라 wagmi 가 아직 안 emit).
+            if (!qrUri) return;
+            navigator.clipboard
+              .writeText(qrUri)
+              .then(() => setShowCopyToast(true))
+              .catch((err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[copyLink] clipboard write failed', err);
+              });
+          }}
+        />
+        {(showCopyToast || showMetaMaskPendingRequestToast) && (
+          <div className="ck-toast-stack">
+            {showCopyToast && (
+              <Toast message="Link copied" onClose={() => setShowCopyToast(false)} />
+            )}
+            {showMetaMaskPendingRequestToast && (
+              <Toast
+                variant="warning"
+                message="Clear the pending request in your wallet first."
+                onClose={() => setShowMetaMaskPendingRequestToast(false)}
+              />
+            )}
+          </div>
+        )}
+      </dialog>
+    </div>
+  );
+};

package/src/layout/connectDialog/loading/index.tsx

@@ -0,0 +1,13 @@
+import { type FC } from 'react';
+import './style.scss';
+import { Spinner } from '../asset/spinner';
+
+export const Loading: FC = () => {
+  return (
+    <div className="ck-loading">
+      <span className="ck-loading-spinner" role="status" aria-label="Connecting...">
+        <Spinner />
+      </span>
+    </div>
+  );
+};

package/src/layout/connectDialog/loading/style.scss

@@ -0,0 +1,19 @@
+@use '../../../style/mixin.scss' as *;
+
+.ck-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  min-height: 200px;
+}
+
+.ck-loading-spinner {
+  display: flex;
+  color: var(--scale-gray-400);
+  animation: ck-spin 2.5s linear infinite;
+}
+
+@keyframes ck-spin {
+  to { transform: rotate(360deg); }
+}

package/src/layout/connectDialog/metaMask/index.tsx

@@ -0,0 +1,61 @@
+import { type FC } from 'react';
+import './style.scss';
+import { QrArea } from '../../../components/qrArea';
+import { ActionItem } from '../../../components/actionItem';
+import { Spinner } from '../asset/spinner';
+
+type MetaMaskVariant = 'extension' | 'qr';
+
+interface MetaMaskProps {
+  variant: MetaMaskVariant;
+  uri?: string | null;
+  logoUrl?: string;
+  downloadUrl?: string;
+  onCopy?: () => void;
+}
+
+export const MetaMask: FC<MetaMaskProps> = ({
+  variant,
+  uri,
+  logoUrl,
+  downloadUrl = '',
+  onCopy,
+}) => {
+  if (variant === 'extension') {
+    return (
+      <div className="ck-metamask ck-metamask-extension">
+        {logoUrl && (
+          <img className="ck-metamask-logo" src={logoUrl} alt="MetaMask" width={48} height={48} />
+        )}
+        <div className="ck-metamask-text">
+          <h3 className="ck-metamask-title">Open MetaMask</h3>
+          <p className="ck-metamask-desc">Check the connection in your extension</p>
+        </div>
+        <span className="ck-metamask-spinner" aria-label="Connecting...">
+          <Spinner />
+        </span>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <QrArea
+        uri={uri}
+        status={!uri ? 'loading' : 'ready'}
+        logoUrl={logoUrl}
+        hasBg
+        label="Scan this QR Code with your phone"
+        onCopy={onCopy}
+      />
+      <ActionItem
+        as="a"
+        href={downloadUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        label="Don't have MetaMask Wallet?"
+        action="Download"
+      />
+    </>
+  );
+};