@gluwa/connect-kit 0.2.0-next.8 → 0.2.1-next.1

package/src/layout/connectDialog/index.tsx

@@ -2,6 +2,7 @@ import { type FC, useEffect, useRef, useState } from 'react';
 import { useConfig } from 'wagmi';
 import './style.scss';
 import {
+  type ConnectBannerSiteKey,
   type ConnectorId,
   type ConnectKitTheme,
   type WCWallet,
@@ -10,22 +11,22 @@ import {
 import { type DetailContent } from '../detailPanel';
 import { SelectorPanel } from '../selectorPanel';
 import { DetailPanel } from '../detailPanel';
-import { Snackbar } from '../../components/snackbar';
-import { resolveConnectorId } from '../../connector-meta';
+import { Toast } from '../../components/toast';
+import { CONNECTOR_META, 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 {
-  detectMetaMaskExtension,
-  isMobileDevice,
-  tryOpenDeepLink,
-  tryOpenCreditWalletDeeplink,
-} from '../../utils/platform';
+import { isMobileDevice, tryOpenDeepLink, tryOpenCreditWalletDeeplink } from '../../utils/platform';
+import { hasDeeplinkOpened, markDeeplinkOpened } from '../../core/deeplinkSignal';
 
 export type DialogStep = 'selector' | 'detail';
 
 export interface ConnectDialogProps {
   open: boolean;
+  siteKey: ConnectBannerSiteKey;
+  connectBannerUrl: string;
   theme?: ConnectKitTheme;
   connectors?: ConnectorId[];
   selectedConnector?: ConnectorId | null;
@@ -49,11 +50,28 @@ const getContentForConnector = (id: ConnectorId): DetailContent => {
 };
 
 // MM 은 확장 감지 시 즉시 extension 연결, 아니면 QR. (select / retry 공통)
-const getInitialContentForConnector = (id: ConnectorId): DetailContent =>
-  id === 'METAMASK' && !detectMetaMaskExtension() ? 'metamask-qr' : getContentForConnector(id);
+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,
@@ -86,10 +104,13 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
    * - 'wallet-qr'     개별 지갑 QR
    */
   const [content, setContent] = useState<DetailContent>('idle');
-  const [showCopySnackbar, setShowCopySnackbar] = useState(false);
+  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);
@@ -98,10 +119,15 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
   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 } = useWagmiConnect({
+  const { triggerConnect, cancelConnect, isConnecting } = useWagmiConnect({
     onConnect: (result) => {
       // recent = 연결 성공 기준. wagmi 가 recentConnectorId 를 localStorage 에 저장하므로
       // UI state 만 동기화. 다음 마운트 시 아래 effect 가 storage 에서 복원.
@@ -109,10 +135,25 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
       onConnect?.(result);
     },
     onError: (err, connectorId) => {
-      // WC: connect reject(사용자 거절 / 프로토콜 ~5분 만료 / 네트워크 등)는
-      //     모두 timeout UI("Connection Failed")로 통일.
-      if (connectorId === 'WALLET_CONNECT') {
+      // MetaMask는 pending 요청을 사전에 조회할 수 없어 새 요청의 -32002 응답으로만 판별한다.
+      if (
+        connectorId === 'METAMASK' &&
+        isMetaMaskExtensionInstalled &&
+        isMetaMaskPendingRequestError(err)
+      ) {
+        setShowMetaMaskPendingRequestToast(true);
+      }
+
+      // MM/WC/CC connect reject·실패는 타이머를 기다리지 않고 즉시 실패 화면으로 전환.
+      // (CC 는 서버 push 만료와 별개로, 지갑 앱에서 거절하면 connect promise 가 reject 된다.)
+      if (
+        connectorId === 'METAMASK' ||
+        connectorId === 'WALLET_CONNECT' ||
+        connectorId === 'CREDIT_CONNECT'
+      ) {
         setExpiredSignal((n) => n + 1);
+      } else {
+        connectorId satisfies never;
       }
       onError?.(err, connectorId);
     },
@@ -123,22 +164,45 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
 
   // 연결 타임아웃 (CC=서버 push / MM=client 타이머 / WC=connect reject) → timedOut.
   const timeoutActive = step === 'detail' && !!selectedConnector && content !== 'timeout';
-  const { timedOut, retry } = useConnectTimeout({
+  const {
+    timedOut,
+    reset: resetTimeout,
+    retry,
+  } = useConnectTimeout({
     connectorId: selectedConnector,
     active: timeoutActive,
+    isConnecting,
     expiredSignal,
     onRetry: () => {
       if (!selectedConnector) return;
-      cancelConnect();
-      setQrUri(null);
       // 타임아웃 직전 화면으로 복원 (예: WC 의 wallet-qr → 선택 지갑 QR 유지).
       // idle/timeout 처럼 복원 불가한 값이면 커넥터 초기 화면으로.
       const restore = preTimeoutContentRef.current;
       const nextContent: DetailContent =
         restore !== 'idle' && restore !== 'timeout'
           ? restore
-          : getInitialContentForConnector(selectedConnector);
+          : getInitialContentForConnector(selectedConnector, isMetaMaskExtensionInstalled);
+
+      // MetaMask 확장 pending 요청은 dApp에서 종료하거나 다시 요청할 수 없다.
+      // 실패 화면을 유지하고 기존 요청을 먼저 처리하도록 안내한다.
+      if (selectedConnector === 'METAMASK' && restore === 'metamask-ext' && isConnecting) {
+        setContent('timeout');
+        setShowMetaMaskPendingRequestToast(true);
+        return;
+      }
+
       setContent(nextContent);
+      setQrUri(null);
+
+      // 재시도는 채널을 파괴하지 않는다.
+      //   kit 의 타임아웃(DEFAULT_CONNECT_TIMEOUT_MS)은 '오래 걸린다'는 UI 신호일 뿐이고,
+      //   그 시점에 커넥터의 세션은 대체로 아직 유효하다. MM 의 경우 SDK 가 저장된 채널을
+      //   validUntil 까지 재사용하므로(originatorSessionConnect) 같은 QR/URI 가 다시 나오는데,
+      //   채널이 살아있으니 스캔·딥링크·Open app 이 모두 정상 동작한다.
+      //   반대로 sdk.terminate() 로 채널을 지우면, 이전 시도가 미완료라 SDK 가 startConnection
+      //   을 타지 못하고 캐시된 옛 qrcodeLink 를 재방출한다 → 죽은 채널의 QR 이 그려진다.
+      //   그래서 여기서는 평범한 재시도만 한다. CC/WC 는 커넥터가 매 connect 마다 새 세션을 만든다.
+      cancelConnect();
       triggerConnect(selectedConnector);
     },
   });
@@ -146,18 +210,44 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
   // 타임아웃 발생 → 진행 중 연결 취소 + timeout 화면 표시.
   // 전환 전 화면을 저장해 retry 시 복원 (WC wallet-qr 등).
   useEffect(() => {
-    if (!timedOut) return;
+    // selector로 돌아간 렌더에 이전 timedOut이 잠시 남아도 실패 화면을 다시 덮지 않는다.
+    if (!timedOut || !selectedConnector || step !== 'detail') return;
+    // cancelConnect로 isConnecting이 바뀌어 effect가 다시 실행되어도
+    // 기록한 이전 화면을 timeout으로 덮어쓰지 않는다.
+    if (contentRef.current === 'timeout') return;
     preTimeoutContentRef.current = contentRef.current;
-    cancelConnect();
+
+    // MetaMask 확장 pending 요청만 보존한다. QR/Deeplink는 Retry에서 SDK를 재시작한다.
+    const shouldPreserveMetaMaskRequest =
+      selectedConnector === 'METAMASK' && contentRef.current === 'metamask-ext' && isConnecting;
+    // 확장 승인 요청은 dApp에서 종료할 수 없으므로 원래 요청을 유지한다.
+    if (!shouldPreserveMetaMaskRequest) {
+      cancelConnect();
+    }
     setContent('timeout');
-  }, [timedOut, cancelConnect]);
+  }, [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);
+      try {
+        const wagmiId = await config.storage?.getItem('recentConnectorId');
+        const resolved = resolveConnectorId(wagmiId ?? undefined);
+        if (resolved) setRecentConnector(resolved);
+      } catch {
+        // 무시 — 실패해도 진행한다.
+      }
     };
     restoreRecent().catch(() => undefined);
   }, [config]);
@@ -166,9 +256,16 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
   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));
+    setContent(getInitialContentForConnector(id, isMetaMaskExtensionInstalled));
     setStep('detail');
     // wagmi connect 시작 (display_uri 도착 시 setQrUri 자동 호출)
     triggerConnect(id);
@@ -218,37 +315,73 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
   }, [open]);
 
   // selectedWallet 가 먼저 set 됐고 qrUri 가 뒤늦게 도착한 경우 자동 deeplink.
-  // handleSelectWallet 의 inline 호출과 중복 방지를 위해 deeplinkTriedRef 가드.
-  const deeplinkTriedRef = useRef(false);
+  // 자동 deeplink 는 best-effort 다 — 횟수 제한을 두지 않는다.
+  //   iOS WebKit 은 사용자 제스처 없는 커스텀 스킴 이동을 억제한다. display_uri 는 네트워크
+  //   왕복 뒤에 도착하므로 지갑 탭의 제스처 활성 창(수백 ms)을 이미 넘긴 상태이고,
+  //   따라서 이 시도는 브라우저가 허용할 때만 통과한다. dApp 이 제어할 수 있는 영역이 아니다.
+  //   막힌 경우의 확실한 경로는 'Open app' 버튼(제스처) 이다.
   useEffect(() => {
-    deeplinkTriedRef.current = false;
-  }, [selectedWallet]);
-  useEffect(() => {
-    if (deeplinkTriedRef.current) return;
     if (!selectedWallet || !qrUri || content !== 'wallet-qr') return;
     if (!isMobileDevice()) return;
     const base = selectedWallet.mobileNative || selectedWallet.mobileUniversal;
     if (!base) return;
-    deeplinkTriedRef.current = true;
     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 creditConnectDeeplinkTriedRef = useRef(false);
-  useEffect(() => {
-    creditConnectDeeplinkTriedRef.current = false;
-  }, [selectedConnector]);
   useEffect(() => {
-    if (creditConnectDeeplinkTriedRef.current) return;
     if (content !== 'qr' || !qrUri) return;
     if (selectedConnector !== 'CREDIT_CONNECT') return;
     if (!isMobileDevice()) return;
-    creditConnectDeeplinkTriedRef.current = true;
     tryOpenCreditWalletDeeplink(qrUri);
   }, [content, qrUri, selectedConnector]);
 
+  // MetaMask 는 기본적으로 SDK 가 앱을 연다 (core/config.ts 의 openDeeplink 콜백).
+  // 그런데 SDK 는 취소된 connect 가 남아있는 동안(initializationOngoing) 그 콜백을 호출하지 않는다.
+  //   그 래치를 dApp 이 강제로 풀 방법은 커넥터에 'rejected' 를 쏘는 것뿐인데, 그러면 SDK 가
+  //   4001 경로를 타며 handleDisconnect() 로 provider._state.isConnected 를 false 로 내리고,
+  //   이후 switchChain 등 모든 RPC 의 딥링크 리다이렉트가 write() 의 isMetaMaskInstalled()
+  //   가드에서 조용히 스킵된다. 그래서 SDK 상태는 건드리지 않는다.
+  // 대신 SDK 가 열지 않는 시도에서는 kit 이 직접 연다. 재방출되는 qrUri 는 terminate 를 하지
+  // 않는 한 살아있는 채널이므로('Open app' 이 같은 URI 로 정상 동작하는 것이 근거) 유효하다.
+  // 이중 발사는 deeplinkSignal 이 막는다 — connect 시도당 1회.
+  useEffect(() => {
+    if (content !== 'metamask-qr' || !qrUri) return;
+    if (selectedConnector !== 'METAMASK') return;
+    if (!isMobileDevice()) return;
+    if (hasDeeplinkOpened()) {
+      return;
+    }
+    const base = CONNECTOR_META.METAMASK.deepLinkBase;
+    if (!base) return;
+    markDeeplinkOpened();
+    tryOpenDeepLink(qrUri, base);
+  }, [content, qrUri, selectedConnector]);
+
+  // 'Open app' 버튼 — 사용자 제스처이므로 iOS 의 비제스처 이동 억제에 걸리지 않는다.
+  // 자동 시도가 막혔을 때의 확실한 경로.
+  const handleOpenApp = (): void => {
+    if (!qrUri) return;
+
+    if (content === 'qr' && selectedConnector === 'CREDIT_CONNECT') {
+      tryOpenCreditWalletDeeplink(qrUri);
+      return;
+    }
+
+    if (content === 'metamask-qr' && selectedConnector === 'METAMASK') {
+      const base = CONNECTOR_META.METAMASK.deepLinkBase;
+      if (!base) return;
+      tryOpenDeepLink(qrUri, base);
+      return;
+    }
+
+    if (content === 'wallet-qr' && selectedWallet) {
+      const base = selectedWallet.mobileNative || selectedWallet.mobileUniversal;
+      if (!base) return;
+      tryOpenDeepLink(qrUri, base);
+    }
+  };
+
   // Prevent background scroll while dialog is open
   useEffect(() => {
     const prev = document.body.style.overflow;
@@ -266,7 +399,8 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
       setSelectedConnector(null);
       setContent('idle');
       setStep('selector');
-      setShowCopySnackbar(false);
+      setShowCopyToast(false);
+      setShowMetaMaskPendingRequestToast(false);
     }
   }, [open, cancelConnect]);
 
@@ -276,7 +410,8 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
     if (!dialog) return undefined;
     const handleCancel = (e: Event) => {
       e.preventDefault();
-      setShowCopySnackbar(false);
+      setShowCopyToast(false);
+      setShowMetaMaskPendingRequestToast(false);
       onClose();
     };
     dialog.addEventListener('cancel', handleCancel);
@@ -302,6 +437,8 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
           onClose={onClose}
         />
         <DetailPanel
+          connectBanner={connectBanner}
+          connectBannerLoading={connectBannerLoading}
           selectedConnector={selectedConnector}
           selectedWallet={selectedWallet}
           content={content}
@@ -310,6 +447,7 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
           walletListLoading={wc.walletListLoading}
           walletCount={wc.walletList.length}
           onBack={handleBack}
+          onOpenApp={handleOpenApp}
           onClose={onClose}
           onRetry={retry}
           onShowAllWallets={handleShowAllWallets}
@@ -319,16 +457,27 @@ export const ConnectDialog: FC<ConnectDialogProps> = ({
             if (!qrUri) return;
             navigator.clipboard
               .writeText(qrUri)
-              .then(() => setShowCopySnackbar(true))
+              .then(() => {
+                setShowCopyToast(true);
+              })
               .catch((err) => {
                 // eslint-disable-next-line no-console
                 console.warn('[copyLink] clipboard write failed', err);
               });
           }}
         />
-        {showCopySnackbar && (
-          <div className="ck-dialog-snackbar">
-            <Snackbar message="Link copied" onClose={() => setShowCopySnackbar(false)} />
+        {(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>

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

@@ -12,6 +12,7 @@ interface MetaMaskProps {
   logoUrl?: string;
   downloadUrl?: string;
   onCopy?: () => void;
+  onOpenApp?: () => void;
 }
 
 export const MetaMask: FC<MetaMaskProps> = ({
@@ -19,7 +20,7 @@ export const MetaMask: FC<MetaMaskProps> = ({
   uri,
   logoUrl,
   downloadUrl = '',
-  onCopy,
+  onOpenApp,
 }) => {
   if (variant === 'extension') {
     return (
@@ -46,7 +47,7 @@ export const MetaMask: FC<MetaMaskProps> = ({
         logoUrl={logoUrl}
         hasBg
         label="Scan this QR Code with your phone"
-        onCopy={onCopy}
+        onOpenApp={onOpenApp}
       />
       <ActionItem
         as="a"

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

@@ -6,9 +6,10 @@ interface QRProps {
   uri?: string | null;
   logoUrl?: string;
   downloadUrl?: string;
+  onOpenApp?: () => void;
 }
 
-export const QR: FC<QRProps> = ({ uri, logoUrl, downloadUrl }) => {
+export const QR: FC<QRProps> = ({ uri, logoUrl, downloadUrl, onOpenApp }) => {
   const status = !uri ? 'loading' : 'ready';
 
   return (
@@ -18,6 +19,7 @@ export const QR: FC<QRProps> = ({ uri, logoUrl, downloadUrl }) => {
         status={status}
         logoUrl={logoUrl}
         label="Open the PenguinWallet app and scan the QR"
+        onOpenApp={onOpenApp}
       />
       <ActionItem
         as="a"

package/src/layout/connectDialog/style.scss

@@ -37,59 +37,12 @@
     width: 100%;
     max-width: none;
     grid-template-columns: 1fr;
+    grid-template-rows: minmax(0, 1fr);
     max-height: 82dvh;
-    height: 100%;
+    height: auto;
     border-radius: 12px 12px 0 0;
 
     &[data-step='selector'] .ck-detail { display: none !important; }
     &[data-step='detail'] .ck-selector { display: none !important; }
   }
 }
-
-.ck-root .ck-dialog-snackbar {
-  position: fixed;
-  top: clamp(20px, 9.2vh, 99px);
-  left: 50%;
-  z-index: 1001;
-  width: min(calc(100vw - 40px), 400px);
-  transform: translateX(-50%);
-  animation: ck-dialog-snackbar-in 0.2s ease;
-
-  @include tablet {
-    top: clamp(
-      calc(env(safe-area-inset-top, 0px) + 20px),
-      calc(env(safe-area-inset-top, 0px) + 20px),
-      calc(env(safe-area-inset-top, 0px) + 20px)
-    );
-    left: 20px;
-    right: 20px;
-    width: auto;
-    transform: none;
-  }
-}
-
-@keyframes ck-dialog-snackbar-in {
-  from {
-    opacity: 0;
-    transform: translateX(-50%) translateY(8px);
-  }
-
-  to {
-    opacity: 1;
-    transform: translateX(-50%) translateY(0);
-  }
-}
-
-@include tablet {
-  @keyframes ck-dialog-snackbar-in {
-    from {
-      opacity: 0;
-      transform: translateY(8px);
-    }
-
-    to {
-      opacity: 1;
-      transform: translateY(0);
-    }
-  }
-}

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

@@ -10,11 +10,6 @@ export const Timeout: FC<TimeoutProps> = ({ onRetry }) => {
     <div className="ck-timeout">
       <div className="ck-timeout-text">
         <h3 className="ck-timeout-title">Connection Failed</h3>
-        <p className="ck-timeout-desc">
-          The connection took too long to respond.
-          <br />
-          Please check your network and try again.
-        </p>
       </div>
       <button type="button" className="ck-timeout-retry-btn" onClick={onRetry}>
         Try Again

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

@@ -21,11 +21,6 @@
   color: var(--scale-gray-900);
 }
 
-.ck-timeout-desc {
-  @include textToken('body4-l1-regular');
-  color: var(--scale-gray-600);
-}
-
 .ck-root .ck-timeout-retry-btn {
   display: inline-flex;
   align-items: center;

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

@@ -7,9 +7,10 @@ interface WalletQRProps {
   wallet: WCWallet;
   uri?: string | null;
   onCopy?: () => void;
+  onOpenApp?: () => void;
 }
 
-export const WalletQR: FC<WalletQRProps> = ({ wallet, uri = null, onCopy }) => {
+export const WalletQR: FC<WalletQRProps> = ({ wallet, uri = null, onCopy, onOpenApp }) => {
   const downloadUrl = wallet.appIos || wallet.appAndroid || wallet.homepage;
 
   return (
@@ -21,6 +22,7 @@ export const WalletQR: FC<WalletQRProps> = ({ wallet, uri = null, onCopy }) => {
         hasBg
         label={`Scan with ${wallet.name}`}
         onCopy={onCopy}
+        onOpenApp={onOpenApp}
       />
       {downloadUrl && (
         <ActionItem

package/src/layout/detailPanel/index.tsx

@@ -2,7 +2,7 @@ import { type FC } from 'react';
 import { CloseIcon } from '../connectDialog/asset/closeIcon';
 import { BackIcon } from '../connectDialog/asset/backIcon';
 import './style.scss';
-import { type ConnectorId, type WCWallet } from '../../types';
+import { type ConnectBanner, type ConnectorId, type WCWallet } from '../../types';
 import { CONNECTOR_META } from '../../connector-meta';
 import { Idle } from '../connectDialog/idle';
 import { Loading } from '../connectDialog/loading';
@@ -25,6 +25,8 @@ export type DetailContent =
   | 'wallet-qr';
 
 interface DetailPanelProps {
+  connectBanner?: ConnectBanner | null;
+  connectBannerLoading?: boolean;
   selectedConnector: ConnectorId | null;
   selectedWallet?: WCWallet | null;
   content?: DetailContent;
@@ -40,6 +42,8 @@ interface DetailPanelProps {
   onShowAllWallets?: () => void;
   onSelectWallet?: (wallet: WCWallet) => void;
   onCopyLink?: () => void;
+  /** 모바일 QR 화면의 'Open app' 버튼 — 해당 지갑 앱을 deeplink 로 연다. */
+  onOpenApp?: () => void;
   /** timeout 화면의 "Try Again" 버튼 핸들러. */
   onRetry?: () => void;
 }
@@ -68,6 +72,8 @@ const getTitle = (content: DetailContent, connector: ConnectorId | null): string
 };
 
 export const DetailPanel: FC<DetailPanelProps> = ({
+  connectBanner = null,
+  connectBannerLoading = false,
   selectedConnector,
   selectedWallet = null,
   content = 'idle',
@@ -80,6 +86,7 @@ export const DetailPanel: FC<DetailPanelProps> = ({
   onShowAllWallets,
   onSelectWallet,
   onCopyLink,
+  onOpenApp,
   onRetry,
 }) => {
   // CONNECTOR_META 에서 활성 connector 의 logo / downloadUrl 가져옴.
@@ -91,6 +98,10 @@ export const DetailPanel: FC<DetailPanelProps> = ({
       ? `Scan with ${selectedWallet.name}`
       : getTitle(content, selectedConnector);
   const showBack = content !== 'idle';
+  const closeColor =
+    content === 'idle' && !connectBannerLoading
+      ? (connectBanner?.closeColor ?? '#FFFFFF')
+      : undefined;
 
   return (
     <section className="ck-detail">
@@ -105,15 +116,37 @@ export const DetailPanel: FC<DetailPanelProps> = ({
         ) : (
           <span className="ck-detail-header-spacer" aria-hidden="true" />
         )}
-        <button type="button" className="ck-btn-close" onClick={onClose} aria-label="Close">
+        <button
+          type="button"
+          className="ck-btn-close"
+          onClick={onClose}
+          aria-label="Close"
+          style={{ color: closeColor }}
+        >
           <CloseIcon />
         </button>
       </header>
       <div className="ck-detail-body">
-        {content === 'idle' && <Idle />}
+        {content === 'idle' && !connectBannerLoading && (
+          <Idle
+            title={connectBanner?.title}
+            description={connectBanner?.subtitle}
+            linkText={connectBanner?.linkText}
+            linkUrl={connectBanner?.linkUrl}
+            imageUrl={connectBanner?.imageUrl}
+            titleColor={connectBanner?.titleColor}
+            descriptionColor={connectBanner?.subtitleColor}
+            linkTextColor={connectBanner?.linkTextColor}
+          />
+        )}
         {content === 'loading' && <Loading />}
         {content === 'qr' && (
-          <QR uri={qrUri} logoUrl={connectorLogoUrl} downloadUrl={connectorDownloadUrl} />
+          <QR
+            uri={qrUri}
+            logoUrl={connectorLogoUrl}
+            downloadUrl={connectorDownloadUrl}
+            onOpenApp={onOpenApp}
+          />
         )}
         {content === 'timeout' && <Timeout onRetry={onRetry} />}
         {(content === 'metamask-ext' || content === 'metamask-qr') && (
@@ -122,7 +155,7 @@ export const DetailPanel: FC<DetailPanelProps> = ({
             logoUrl={connectorLogoUrl}
             uri={qrUri}
             downloadUrl={connectorDownloadUrl}
-            onCopy={onCopyLink}
+            onOpenApp={onOpenApp}
           />
         )}
         {content === 'walletconnect' && (
@@ -142,7 +175,7 @@ export const DetailPanel: FC<DetailPanelProps> = ({
           />
         )}
         {content === 'wallet-qr' && selectedWallet && (
-          <WalletQR wallet={selectedWallet} uri={qrUri} onCopy={onCopyLink} />
+          <WalletQR wallet={selectedWallet} uri={qrUri} onCopy={onCopyLink} onOpenApp={onOpenApp} />
         )}
       </div>
     </section>