@gluwa/connect-kit 0.1.0-next.1 → 0.1.0-next.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gluwa/wallet-kit
 
+## 0.1.0-next.2
+
+### Patch Changes
+
+- d44580e: add provider
+
 ## 0.1.0-next.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FC } from 'react';
+import { ReactNode, FC } from 'react';
 import { createConnector } from '@wagmi/core';
 import { StorageProvider } from '@gluwa/credit-connect-sdk/storage';
 import { E2EEProvider } from '@gluwa/credit-connect-sdk/e2ee';
@@ -28,6 +28,14 @@ interface ConnectResult {
     address: `0x${string}`;
     connectorId: ConnectorId;
 }
+type ConnectErrorReason = 'rejected' | 'unsupported' | 'unknown';
+interface ConnectErrorContext {
+    connectorId: ConnectorId;
+    reason: ConnectErrorReason;
+    error: Error;
+    retry: () => void;
+    dismiss: () => void;
+}
 interface ConnectModalProps {
     open: boolean;
     connectors: Connectors;
@@ -35,10 +43,45 @@ interface ConnectModalProps {
     onClose: () => void;
     onLog?: (message: string, error?: Error) => void;
     wcProjectId?: string;
+    requiredChainId?: number;
+    renderConnectError?: (ctx: ConnectErrorContext) => ReactNode;
 }
 
 declare const ConnectModal: FC<ConnectModalProps>;
 
+interface ConnectKitProviderProps {
+    children: ReactNode;
+    connectors: Connectors;
+    wcProjectId?: string;
+    /**
+     * 연결돼 있는 동안 강제할 체인 ID. 다른 체인에 연결돼 있으면
+     * 자동으로 스위치 모달이 떠서 사용자에게 전환 또는 disconnect를 요구.
+     */
+    requiredChainId?: number;
+    /**
+     * 연결이 정상적으로 끝나고(체인 검증까지 통과) "사용 가능한 상태"가 됐을 때 한 번 호출.
+     * 재연결(reconnect)에서는 호출되지 않음 — 그쪽은 dApp의 watchAccount 책임.
+     */
+    onConnect?: (result: ConnectResult) => void;
+    onLog?: (message: string, error?: Error) => void;
+    /**
+     * 연결 실패(거절/미설치/기타) 시 모달 안에 표시할 fallback UI를 dApp이 직접 그리고 싶을 때.
+     * 미제공 시 기본 동작은 selector로 복귀.
+     */
+    renderConnectError?: (ctx: ConnectErrorContext) => ReactNode;
+}
+interface ConnectKitContextValue {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    isConnected: boolean;
+    address: `0x${string}` | undefined;
+    connectorId: ConnectorId | null;
+    disconnect: () => Promise<void>;
+}
+declare const ConnectKitProvider: FC<ConnectKitProviderProps>;
+declare const useConnectKit: () => ConnectKitContextValue;
+
 type CreditConnectConnectorOptions = {
     projectKey: string;
     serverUrl: string;
@@ -49,4 +92,4 @@ type CreditConnectConnectorOptions = {
 };
 declare const creditConnectConnector: (options: CreditConnectConnectorOptions) => ReturnType<typeof createConnector>;
 
-export { ConnectModal, type ConnectModalProps, type ConnectResult, type ConnectorId, type Connectors, type CreditConnectConnectorOptions, type CreditWalletStrategy, type WCSubView, type WCWallet, creditConnectConnector };
+export { type ConnectErrorContext, type ConnectErrorReason, type ConnectKitContextValue, ConnectKitProvider, type ConnectKitProviderProps, ConnectModal, type ConnectModalProps, type ConnectResult, type ConnectorId, type Connectors, type CreditConnectConnectorOptions, type CreditWalletStrategy, type WCSubView, type WCWallet, creditConnectConnector, useConnectKit };

package/dist/index.js

@@ -3,7 +3,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/ConnectModal.tsx
-import { useState as useState2, useEffect as useEffect4, useCallback as useCallback3, useRef as useRef3, useMemo as useMemo4 } from "react";
+import { useState as useState3, useEffect as useEffect4, useCallback as useCallback3, useRef as useRef3, useMemo as useMemo4 } from "react";
 
 // src/ConnectModal.scss
 var css = `.ck-root {
@@ -141,6 +141,42 @@ var css = `.ck-root {
 .ck-btn-primary:hover {
   background: rgba(255, 255, 255, 0.22);
 }
+.ck-btn-primary:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.ck-btn-secondary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 16px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  white-space: nowrap;
+  color: rgba(255, 255, 255, 0.75);
+  background: transparent;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+}
+.ck-btn-secondary:hover {
+  color: #fff;
+  border-color: rgba(255, 255, 255, 0.32);
+}
+
+.ck-view__actions {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+  margin-top: 16px;
+}
+
+.ck-view__caption--error {
+  color: #ff8080;
+  margin-top: 8px;
+}
 
 .ck-connector-list {
   display: flex;
@@ -584,7 +620,7 @@ var css = `.ck-root {
 document.head.appendChild(document.createElement("style")).appendChild(document.createTextNode(css));
 
 // src/ConnectModal.tsx
-import { useConfig as useConfig2 } from "wagmi";
+import { useAccount, useConfig as useConfig2, useDisconnect } from "wagmi";
 
 // assets/creditwallet.png
 var creditwallet_default = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACQAAAAkCAYAAADhAJiYAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAOdEVYdFNvZnR3YXJlAEZpZ21hnrGWYwAAAtNJREFUeAHVWDFs00AUfWe7oYVSWdAxQEfUCZiQqEQykDUdGBAL0IERlQGxMbAhBpDYGEBMMDCEtUtbqZXYuiHGCDEymDZqqZr4+N/OuW579jmO5aRPcs8+n68v/7//798BYwah65x23Rp8NOltjQa4UmIORfwzgbYE2kJSa+FTx/PWToyJP7iuO9eV+AiJGsqAQMsReOp5XvuwK0amJ7FalDWyc0LbtlBXpCz1gizzpmwyDHJh6JVDgpFmVjFKkJVYUw7fCx8P5GCfY/r9Ezjzl7TvvIVnGBg+FulvSEgKclUGRhM3r0b3cnsX/u8/xnE8ppcw7ggEbnMTWoj8aOJjVWdx/svz6Hnn3iscfP+pHXuhHUkCe2+/0dWCkY+E2+dC5p9xU/lMLjUgZs4e6dv/upFooanlxRN9+x9W4JNV09DZ9kQmQu7G66DNow0mN7XcDL71Da4zEjpzd4GuW2SNTXR//EKPrkHBrrbpqtA8bOXO43dII2SZJnNIoKyVPGQYbBX+noXuzF82jrcwZnB0nXbfMgwWLwxizIKDlS3KLObcotUQm5dD3BSylcYNbfTlBWvIwRCYXLoTWbIIQoyhCOmgUoQJOxRtukAZmaitY65WKNxCuRbWGIYixKK3qpsoEtoo48jhCOLEaFUvYu/lZ+M6ZMK5F/eDsN+luZKQmKm5tFDRwssHEvw9CCYa14MfacLpyNQKvA51aR2y+wtkUv2TBjtw+2zmQu10lR8KZRZoYQnLO8qULdA/mozNHs/C7MpkQs3oPnMJS/uzfhtYaIuaa6kfkIXi9QwXXKwPHZiEAuvGz1bkr3X+enUl6nUTIU4FcVFXKB1YCYTyiJ/3+yEvjNdGMchDwSkEmQyjAh06qJOQKDHSKcQjFjdKBouZT0DUc0SITx9sgTqzRVkgr8RPPsIuDVhTtN9/SFvsK8GuttgDK4/W2HUyRUt3YDV2+A99bkdtt/T4QQAAAABJRU5ErkJggg==";
@@ -1168,6 +1204,50 @@ var WalletQRView = /* @__PURE__ */ __name(({ wallet, qrUri }) => {
   }, "Download")));
 }, "WalletQRView");
 
+// src/views/SwitchChainView.tsx
+import { useState as useState2 } from "react";
+import { useSwitchChain } from "wagmi";
+var SwitchChainView = /* @__PURE__ */ __name(({ currentChainId, requiredChainId, requiredChainName, onDisconnect, onLog }) => {
+  const { switchChainAsync, isPending } = useSwitchChain();
+  const [error, setError] = useState2(null);
+  const targetLabel = requiredChainName != null ? requiredChainName : `chain ${requiredChainId}`;
+  const handleSwitch = /* @__PURE__ */ __name(() => {
+    setError(null);
+    switchChainAsync({
+      chainId: requiredChainId
+    }).catch((err) => {
+      const normalized = err instanceof Error ? err : new Error(String(err));
+      const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+      if (code === 4902) {
+        onLog == null ? void 0 : onLog("[connect-kit] chain not registered in wallet (4902)", normalized);
+      } else {
+        onLog == null ? void 0 : onLog(`[connect-kit] switch chain failed: ${normalized.message}`, normalized);
+      }
+      setError(normalized);
+    });
+  }, "handleSwitch");
+  return /* @__PURE__ */ React.createElement("div", {
+    className: "ck-view ck-view--switch-chain"
+  }, /* @__PURE__ */ React.createElement("h4", {
+    className: "ck-view__title"
+  }, "Wrong network"), /* @__PURE__ */ React.createElement("p", {
+    className: "ck-view__description"
+  }, currentChainId != null ? `Connected to chain ${currentChainId}. Please switch to ${targetLabel} to continue.` : `Please switch to ${targetLabel} to continue.`), /* @__PURE__ */ React.createElement("div", {
+    className: "ck-view__actions"
+  }, /* @__PURE__ */ React.createElement("button", {
+    type: "button",
+    className: "ck-btn-primary",
+    onClick: handleSwitch,
+    disabled: isPending
+  }, isPending ? "Waiting for wallet\u2026" : `Switch to ${targetLabel}`), /* @__PURE__ */ React.createElement("button", {
+    type: "button",
+    className: "ck-btn-secondary",
+    onClick: onDisconnect
+  }, "Disconnect")), error && /* @__PURE__ */ React.createElement("p", {
+    className: "ck-view__caption ck-view__caption--error"
+  }, error.message));
+}, "SwitchChainView");
+
 // src/ConnectModal.tsx
 var RECENT_KEY = "connect-kit:recent";
 var readRecentConnector = /* @__PURE__ */ __name(() => {
@@ -1183,6 +1263,15 @@ var writeRecentConnector = /* @__PURE__ */ __name((id) => {
   } catch {
   }
 }, "writeRecentConnector");
+var classifyError = /* @__PURE__ */ __name((error) => {
+  var _a, _b;
+  const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+  if (code === 4001) return "rejected";
+  const message = (_b = (_a = error.message) == null ? void 0 : _a.toLowerCase()) != null ? _b : "";
+  if (message.includes("user rejected") || message.includes("user denied")) return "rejected";
+  if (message.includes("unsupported") || message.includes("not installed")) return "unsupported";
+  return "unknown";
+}, "classifyError");
 var SelectorPane = /* @__PURE__ */ __name(({ connectors, selected, recentConnector, onSelect, onClose }) => {
   const hasRecent = recentConnector !== null && connectors.includes(recentConnector);
   const recentConnectors = hasRecent ? [
@@ -1248,7 +1337,7 @@ var ConnectorItem = /* @__PURE__ */ __name(({ id, isSelected, isRecent, onSelect
     className: "ck-connector-item__badge"
   }, "Recent"));
 }, "ConnectorItem");
-var DetailPane = /* @__PURE__ */ __name(({ selectedConnector, qrUri, hasMetaMaskExtension, connectorLogoMap, wc, onBack, onClose }) => {
+var DetailPane = /* @__PURE__ */ __name(({ selectedConnector, qrUri, hasMetaMaskExtension, connectorLogoMap, wc, errorOverride, onBack, onClose }) => {
   const title = getDetailTitle(selectedConnector, hasMetaMaskExtension, wc.subView, wc.selectedWallet);
   const showBack = selectedConnector !== null;
   return /* @__PURE__ */ React.createElement("div", {
@@ -1269,7 +1358,7 @@ var DetailPane = /* @__PURE__ */ __name(({ selectedConnector, qrUri, hasMetaMask
     "aria-label": "Close"
   })), /* @__PURE__ */ React.createElement("div", {
     className: "ck-pane__body"
-  }, !selectedConnector && /* @__PURE__ */ React.createElement(IdleView, null), (selectedConnector === "CREDIT_CONNECT" || selectedConnector === "CREDIT_WALLET") && /* @__PURE__ */ React.createElement(CreditWalletView, {
+  }, errorOverride || /* @__PURE__ */ React.createElement(React.Fragment, null, !selectedConnector && /* @__PURE__ */ React.createElement(IdleView, null), (selectedConnector === "CREDIT_CONNECT" || selectedConnector === "CREDIT_WALLET") && /* @__PURE__ */ React.createElement(CreditWalletView, {
     connectorId: selectedConnector,
     qrUri
   }), selectedConnector === "METAMASK" && /* @__PURE__ */ React.createElement(MetaMaskView, {
@@ -1289,7 +1378,7 @@ var DetailPane = /* @__PURE__ */ __name(({ selectedConnector, qrUri, hasMetaMask
     onSelectWallet: wc.onSelectWallet,
     onSearchChange: wc.onSearchChange,
     onFilterToggle: wc.onFilterToggle
-  })));
+  }))));
 }, "DetailPane");
 var getDetailTitle = /* @__PURE__ */ __name((connector, hasMetaMaskExtension, wcSubView, wcSelectedWallet) => {
   if (!connector) return "";
@@ -1324,14 +1413,27 @@ var ConnectModal = /* @__PURE__ */ __name((props) => {
     connectors: resolvedConnectors
   });
 }, "ConnectModal");
-var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, onClose, onLog, wcProjectId }) => {
+var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, onClose, onLog, wcProjectId, requiredChainId, renderConnectError }) => {
   var _a;
-  const [selectedConnector, setSelectedConnector] = useState2(null);
-  const [qrUriMap, setQrUriMap] = useState2({});
+  const [selectedConnector, setSelectedConnector] = useState3(null);
+  const [qrUriMap, setQrUriMap] = useState3({});
   const pendingQrConnectorRef = useRef3(null);
-  const [recentConnector, setRecentConnector] = useState2(null);
-  const [hasMetaMaskExtension, setHasMetaMaskExtension] = useState2(false);
+  const [recentConnector, setRecentConnector] = useState3(null);
+  const [hasMetaMaskExtension, setHasMetaMaskExtension] = useState3(false);
+  const [errorState, setErrorState] = useState3(null);
   const wc = useWCState();
+  const account = useAccount();
+  const { disconnectAsync } = useDisconnect();
+  const wagmiConfig = useConfig2();
+  const chainMismatch = requiredChainId != null && account.status === "connected" && account.chainId != null && account.chainId !== requiredChainId;
+  const requiredChainName = useMemo4(() => {
+    var _a2;
+    if (requiredChainId == null) return void 0;
+    return (_a2 = wagmiConfig.chains.find((chain) => chain.id === requiredChainId)) == null ? void 0 : _a2.name;
+  }, [
+    wagmiConfig.chains,
+    requiredChainId
+  ]);
   const handleQrUri = useCallback3((uri) => {
     if (uri) {
       const id = pendingQrConnectorRef.current;
@@ -1342,6 +1444,7 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     }
   }, []);
   const handleConnect = useCallback3((result) => {
+    setErrorState(null);
     onConnect(result);
     onClose();
   }, [
@@ -1349,8 +1452,8 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     onClose
   ]);
   const handleError = useCallback3((error, connectorId) => {
-    onLog == null ? void 0 : onLog(`[connect-kit] connection failed (${connectorId}): ${error.message}`, error);
-    setSelectedConnector(null);
+    const normalizedError = error instanceof Error ? error : new Error(String(error));
+    onLog == null ? void 0 : onLog(`[connect-kit] connection failed (${connectorId}): ${normalizedError.message}`, normalizedError);
     setQrUriMap((prev) => {
       const next = {
         ...prev
@@ -1359,16 +1462,24 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
       return next;
     });
     wc.resetView();
+    if (renderConnectError) {
+      setErrorState({
+        connectorId,
+        error: normalizedError
+      });
+    } else {
+      setSelectedConnector(null);
+    }
   }, [
     onLog,
-    wc.resetView
+    wc.resetView,
+    renderConnectError
   ]);
   const { triggerConnect, cancelConnect } = useWagmiConnect({
     onConnect: handleConnect,
     onError: handleError,
     onQrUri: handleQrUri
   });
-  const wagmiConfig = useConfig2();
   const connectorLogoMap = useMemo4(() => {
     const map = {};
     const connectorIds = [
@@ -1394,6 +1505,7 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
       setSelectedConnector(null);
       setQrUriMap({});
       pendingQrConnectorRef.current = null;
+      setErrorState(null);
       wc.reset();
       cancelConnect();
     }
@@ -1403,9 +1515,10 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     wc.reset
   ]);
   const handleSelectConnector = useCallback3((id) => {
-    if (id === selectedConnector) return;
+    if (id === selectedConnector && !errorState) return;
     pendingQrConnectorRef.current = id;
     setSelectedConnector(id);
+    setErrorState(null);
     wc.resetView();
     writeRecentConnector(id);
     setRecentConnector(id);
@@ -1416,6 +1529,7 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     triggerConnect(id);
   }, [
     selectedConnector,
+    errorState,
     triggerConnect,
     cancelConnect,
     wcProjectId,
@@ -1423,22 +1537,112 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     wc.loadWalletList
   ]);
   const handleBack = useCallback3(() => {
+    if (errorState) {
+      setErrorState(null);
+      setSelectedConnector(null);
+      return;
+    }
     if (selectedConnector === "WALLET_CONNECT" && wc.handleBack()) return;
     pendingQrConnectorRef.current = null;
     setSelectedConnector(null);
     cancelConnect();
   }, [
     selectedConnector,
+    errorState,
     wc.handleBack,
     cancelConnect
   ]);
+  const handleSwitchChainDisconnect = useCallback3(() => {
+    disconnectAsync().catch((err) => {
+      const normalized = err instanceof Error ? err : new Error(String(err));
+      onLog == null ? void 0 : onLog(`[connect-kit] disconnect failed: ${normalized.message}`, normalized);
+    });
+  }, [
+    disconnectAsync,
+    onLog
+  ]);
+  const handleOverlayClick = useCallback3(() => {
+    if (chainMismatch) return;
+    onClose();
+  }, [
+    chainMismatch,
+    onClose
+  ]);
+  const handleCloseClick = useCallback3(() => {
+    if (chainMismatch) {
+      handleSwitchChainDisconnect();
+      return;
+    }
+    onClose();
+  }, [
+    chainMismatch,
+    handleSwitchChainDisconnect,
+    onClose
+  ]);
+  const renderedError = useMemo4(() => {
+    if (!errorState || !renderConnectError) return null;
+    const ctx = {
+      connectorId: errorState.connectorId,
+      reason: classifyError(errorState.error),
+      error: errorState.error,
+      retry: /* @__PURE__ */ __name(() => {
+        const id = errorState.connectorId;
+        setErrorState(null);
+        pendingQrConnectorRef.current = id;
+        cancelConnect();
+        triggerConnect(id);
+      }, "retry"),
+      dismiss: /* @__PURE__ */ __name(() => {
+        setErrorState(null);
+        setSelectedConnector(null);
+      }, "dismiss")
+    };
+    return renderConnectError(ctx);
+  }, [
+    errorState,
+    renderConnectError,
+    triggerConnect,
+    cancelConnect
+  ]);
+  if (chainMismatch && requiredChainId != null) {
+    return /* @__PURE__ */ React.createElement("div", {
+      className: "ck-root"
+    }, /* @__PURE__ */ React.createElement("div", {
+      className: "ck-overlay",
+      onClick: handleOverlayClick
+    }), /* @__PURE__ */ React.createElement("div", {
+      className: "ck-modal ck-modal--switch-chain",
+      role: "dialog",
+      "aria-modal": "true",
+      "aria-label": "Switch network"
+    }, /* @__PURE__ */ React.createElement("div", {
+      className: "ck-pane"
+    }, /* @__PURE__ */ React.createElement("div", {
+      className: "ck-pane__header"
+    }, /* @__PURE__ */ React.createElement("h3", {
+      className: "ck-pane__title"
+    }, "Switch network"), /* @__PURE__ */ React.createElement("button", {
+      type: "button",
+      className: "ck-btn-close",
+      onClick: handleCloseClick,
+      "aria-label": "Cancel and disconnect"
+    })), /* @__PURE__ */ React.createElement("div", {
+      className: "ck-pane__body"
+    }, /* @__PURE__ */ React.createElement(SwitchChainView, {
+      currentChainId: account.chainId,
+      requiredChainId,
+      requiredChainName,
+      onDisconnect: handleSwitchChainDisconnect,
+      onLog
+    })))));
+  }
   return /* @__PURE__ */ React.createElement("div", {
     className: "ck-root"
   }, /* @__PURE__ */ React.createElement("div", {
     className: "ck-overlay",
-    onClick: onClose
+    onClick: handleOverlayClick
   }), /* @__PURE__ */ React.createElement("div", {
-    className: `ck-modal${selectedConnector ? " ck-modal--has-detail" : ""}`,
+    className: `ck-modal${(selectedConnector != null ? selectedConnector : errorState) ? " ck-modal--has-detail" : ""}`,
     role: "dialog",
     "aria-modal": "true",
     "aria-label": "Connect Wallet"
@@ -1447,18 +1651,120 @@ var ConnectModalInner = /* @__PURE__ */ __name(({ open, connectors, onConnect, o
     selected: selectedConnector,
     recentConnector,
     onSelect: handleSelectConnector,
-    onClose
+    onClose: handleCloseClick
   }), /* @__PURE__ */ React.createElement(DetailPane, {
     selectedConnector,
     qrUri: selectedConnector ? (_a = qrUriMap[selectedConnector]) != null ? _a : null : null,
     hasMetaMaskExtension,
     connectorLogoMap,
     wc,
+    errorOverride: renderedError,
     onBack: handleBack,
-    onClose
+    onClose: handleCloseClick
   })));
 }, "ConnectModalInner");
 
+// src/ConnectKitProvider.tsx
+import { createContext, useCallback as useCallback4, useContext, useEffect as useEffect5, useMemo as useMemo5, useRef as useRef4, useState as useState4 } from "react";
+import { useAccount as useAccount2, useDisconnect as useDisconnect2 } from "wagmi";
+var ConnectKitContext = /* @__PURE__ */ createContext(null);
+var resolveConnectorId = /* @__PURE__ */ __name((wagmiConnectorId) => {
+  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;
+}, "resolveConnectorId");
+var ConnectKitProvider = /* @__PURE__ */ __name(({ children, connectors, wcProjectId, requiredChainId, onConnect, onLog, renderConnectError }) => {
+  var _a;
+  const [isOpen, setIsOpen] = useState4(false);
+  const [pendingResult, setPendingResult] = useState4(null);
+  const account = useAccount2();
+  const { disconnectAsync } = useDisconnect2();
+  const onConnectRef = useRef4(onConnect);
+  useEffect5(() => {
+    onConnectRef.current = onConnect;
+  }, [
+    onConnect
+  ]);
+  const chainMismatch = requiredChainId != null && account.status === "connected" && account.chainId != null && account.chainId !== requiredChainId;
+  const effectiveOpen = isOpen || chainMismatch;
+  const open = useCallback4(() => {
+    setIsOpen(true);
+  }, []);
+  const close = useCallback4(() => {
+    setIsOpen(false);
+  }, []);
+  const disconnect = useCallback4(async () => {
+    await disconnectAsync();
+  }, [
+    disconnectAsync
+  ]);
+  const handleModalConnect = useCallback4((result) => {
+    setPendingResult(result);
+  }, []);
+  useEffect5(() => {
+    var _a2;
+    if (!pendingResult) return;
+    if (account.status !== "connected") {
+      setPendingResult(null);
+      return;
+    }
+    if (requiredChainId != null && account.chainId !== requiredChainId) {
+      return;
+    }
+    (_a2 = onConnectRef.current) == null ? void 0 : _a2.call(onConnectRef, pendingResult);
+    setPendingResult(null);
+    setIsOpen(false);
+  }, [
+    pendingResult,
+    account.status,
+    account.chainId,
+    requiredChainId
+  ]);
+  const value = useMemo5(() => {
+    var _a2;
+    return {
+      isOpen: effectiveOpen,
+      open,
+      close,
+      isConnected: account.status === "connected",
+      address: account.address,
+      connectorId: resolveConnectorId((_a2 = account.connector) == null ? void 0 : _a2.id),
+      disconnect
+    };
+  }, [
+    effectiveOpen,
+    open,
+    close,
+    account.status,
+    account.address,
+    (_a = account.connector) == null ? void 0 : _a.id,
+    disconnect
+  ]);
+  return /* @__PURE__ */ React.createElement(ConnectKitContext.Provider, {
+    value
+  }, children, /* @__PURE__ */ React.createElement(ConnectModal, {
+    open: effectiveOpen,
+    connectors,
+    wcProjectId,
+    requiredChainId,
+    renderConnectError,
+    onConnect: handleModalConnect,
+    onClose: close,
+    onLog
+  }));
+}, "ConnectKitProvider");
+var useConnectKit = /* @__PURE__ */ __name(() => {
+  const ctx = useContext(ConnectKitContext);
+  if (!ctx) {
+    throw new Error("useConnectKit must be used within a ConnectKitProvider");
+  }
+  return ctx;
+}, "useConnectKit");
+
 // src/creditConnectConnector.ts
 import { createConnector } from "@wagmi/core";
 import { getAddress } from "viem";
@@ -1850,6 +2156,8 @@ var creditConnectConnector = /* @__PURE__ */ __name((options) => {
   });
 }, "creditConnectConnector");
 export {
+  ConnectKitProvider,
   ConnectModal,
-  creditConnectConnector
+  creditConnectConnector,
+  useConnectKit
 };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gluwa/connect-kit",
-  "version": "0.1.0-next.1",
+  "version": "0.1.0-next.2",
   "type": "module",
   "exports": {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gluwa/connect-kit",
-  "version": "0.1.0-next.1",
+  "version": "0.1.0-next.2",
   "type": "module",
   "exports": {
     ".": {

package/src/ConnectKitProvider.tsx

@@ -0,0 +1,169 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type FC,
+  type ReactNode,
+} from 'react';
+import { useAccount, useDisconnect } from 'wagmi';
+import { ConnectModal } from './ConnectModal';
+import type { ConnectErrorContext, ConnectResult, ConnectorId, Connectors } from './types';
+
+export interface ConnectKitProviderProps {
+  children: ReactNode;
+  connectors: Connectors;
+  wcProjectId?: string;
+  /**
+   * 연결돼 있는 동안 강제할 체인 ID. 다른 체인에 연결돼 있으면
+   * 자동으로 스위치 모달이 떠서 사용자에게 전환 또는 disconnect를 요구.
+   */
+  requiredChainId?: number;
+  /**
+   * 연결이 정상적으로 끝나고(체인 검증까지 통과) "사용 가능한 상태"가 됐을 때 한 번 호출.
+   * 재연결(reconnect)에서는 호출되지 않음 — 그쪽은 dApp의 watchAccount 책임.
+   */
+  onConnect?: (result: ConnectResult) => void;
+  onLog?: (message: string, error?: Error) => void;
+  /**
+   * 연결 실패(거절/미설치/기타) 시 모달 안에 표시할 fallback UI를 dApp이 직접 그리고 싶을 때.
+   * 미제공 시 기본 동작은 selector로 복귀.
+   */
+  renderConnectError?: (ctx: ConnectErrorContext) => ReactNode;
+}
+
+export interface ConnectKitContextValue {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  isConnected: boolean;
+  address: `0x${string}` | undefined;
+  connectorId: ConnectorId | null;
+  disconnect: () => Promise<void>;
+}
+
+const ConnectKitContext = createContext<ConnectKitContextValue | null>(null);
+
+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;
+};
+
+export const ConnectKitProvider: FC<ConnectKitProviderProps> = ({
+  children,
+  connectors,
+  wcProjectId,
+  requiredChainId,
+  onConnect,
+  onLog,
+  renderConnectError,
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [pendingResult, setPendingResult] = useState<ConnectResult | null>(null);
+
+  const account = useAccount();
+  const { disconnectAsync } = useDisconnect();
+
+  // dApp의 onConnect는 ref로 잡아 effect 재실행 노이즈 차단
+  const onConnectRef = useRef(onConnect);
+  useEffect(() => {
+    onConnectRef.current = onConnect;
+  }, [onConnect]);
+
+  // chain mismatch invariant: 연결돼 있지만 요구 체인이 아니면 modal force-open
+  const chainMismatch =
+    requiredChainId != null &&
+    account.status === 'connected' &&
+    account.chainId != null &&
+    account.chainId !== requiredChainId;
+
+  const effectiveOpen = isOpen || chainMismatch;
+
+  const open = useCallback((): void => {
+    setIsOpen(true);
+  }, []);
+
+  const close = useCallback((): void => {
+    setIsOpen(false);
+  }, []);
+
+  const disconnect = useCallback(async (): Promise<void> => {
+    await disconnectAsync();
+  }, [disconnectAsync]);
+
+  // ConnectModal → Provider: 연결 결과를 일단 보류했다가
+  // chain 검증까지 통과한 후에만 dApp으로 forward
+  const handleModalConnect = useCallback((result: ConnectResult): void => {
+    setPendingResult(result);
+  }, []);
+
+  // pendingResult가 있고, 연결 + chain 매칭이 충족되면 dApp으로 발화
+  useEffect(() => {
+    if (!pendingResult) return;
+    if (account.status !== 'connected') {
+      // 연결이 끊겼거나 진행 중 — pending 폐기
+      setPendingResult(null);
+      return;
+    }
+    if (requiredChainId != null && account.chainId !== requiredChainId) {
+      // chain 아직 안 맞음 — switch 후 다시 평가
+      return;
+    }
+    onConnectRef.current?.(pendingResult);
+    setPendingResult(null);
+    setIsOpen(false);
+  }, [pendingResult, account.status, account.chainId, requiredChainId]);
+
+  const value = useMemo<ConnectKitContextValue>(
+    () => ({
+      isOpen: effectiveOpen,
+      open,
+      close,
+      isConnected: account.status === 'connected',
+      address: account.address,
+      connectorId: resolveConnectorId(account.connector?.id),
+      disconnect,
+    }),
+    [
+      effectiveOpen,
+      open,
+      close,
+      account.status,
+      account.address,
+      account.connector?.id,
+      disconnect,
+    ],
+  );
+
+  return (
+    <ConnectKitContext.Provider value={value}>
+      {children}
+      <ConnectModal
+        open={effectiveOpen}
+        connectors={connectors}
+        wcProjectId={wcProjectId}
+        requiredChainId={requiredChainId}
+        renderConnectError={renderConnectError}
+        onConnect={handleModalConnect}
+        onClose={close}
+        onLog={onLog}
+      />
+    </ConnectKitContext.Provider>
+  );
+};
+
+export const useConnectKit = (): ConnectKitContextValue => {
+  const ctx = useContext(ConnectKitContext);
+  if (!ctx) {
+    throw new Error('useConnectKit must be used within a ConnectKitProvider');
+  }
+  return ctx;
+};

package/src/ConnectModal.scss

@@ -140,6 +140,44 @@
   &:hover {
     background: rgba(255, 255, 255, 0.22);
   }
+
+  &:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+}
+
+.ck-btn-secondary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 16px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  white-space: nowrap;
+  color: rgba(255, 255, 255, 0.75);
+  background: transparent;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+
+  &:hover {
+    color: #fff;
+    border-color: rgba(255, 255, 255, 0.32);
+  }
+}
+
+.ck-view__actions {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+  margin-top: 16px;
+}
+
+.ck-view__caption--error {
+  color: #ff8080;
+  margin-top: 8px;
 }
 
 // ── Connector list ────────────────────────────────────────

package/src/ConnectModal.tsx

@@ -1,8 +1,10 @@
-import { useState, useEffect, useCallback, useRef, useMemo, type FC } from 'react';
+import { useState, useEffect, useCallback, useRef, useMemo, type FC, type ReactNode } from 'react';
 import './ConnectModal.scss';
-import { useConfig } from 'wagmi';
+import { useAccount, useConfig, useDisconnect } from 'wagmi';
 import {
   type ConnectModalProps,
+  type ConnectErrorContext,
+  type ConnectErrorReason,
   type Connectors,
   type ConnectorId,
   type WCWallet,
@@ -16,6 +18,7 @@ import { IdleView } from './views/IdleView';
 import { CreditWalletView } from './views/CreditWalletView';
 import { MetaMaskView } from './views/MetaMaskView';
 import { WalletConnectView } from './views/WalletConnectView';
+import { SwitchChainView } from './views/SwitchChainView';
 
 const RECENT_KEY = 'connect-kit:recent';
 const readRecentConnector = (): ConnectorId | null => {
@@ -32,6 +35,18 @@ const writeRecentConnector = (id: ConnectorId): void => {
   } catch {}
 };
 
+const classifyError = (error: Error): ConnectErrorReason => {
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? (error as unknown as { code: unknown }).code
+      : undefined;
+  if (code === 4001) return 'rejected';
+  const message = error.message?.toLowerCase() ?? '';
+  if (message.includes('user rejected') || message.includes('user denied')) return 'rejected';
+  if (message.includes('unsupported') || message.includes('not installed')) return 'unsupported';
+  return 'unknown';
+};
+
 interface SelectorPaneProps {
   connectors: ConnectorId[];
   selected: ConnectorId | null;
@@ -149,6 +164,7 @@ interface DetailPaneProps {
   hasMetaMaskExtension: boolean;
   connectorLogoMap: Partial<Record<ConnectorId, string>>;
   wc: WCState;
+  errorOverride: ReactNode | null;
   onBack: () => void;
   onClose: () => void;
 }
@@ -159,6 +175,7 @@ const DetailPane: FC<DetailPaneProps> = ({
   hasMetaMaskExtension,
   connectorLogoMap,
   wc,
+  errorOverride,
   onBack,
   onClose,
 }) => {
@@ -181,35 +198,39 @@ const DetailPane: FC<DetailPaneProps> = ({
       </div>
 
       <div className="ck-pane__body">
-        {!selectedConnector && <IdleView />}
+        {errorOverride || (
+          <>
+            {!selectedConnector && <IdleView />}
 
-        {(selectedConnector === 'CREDIT_CONNECT' || selectedConnector === 'CREDIT_WALLET') && (
-          <CreditWalletView connectorId={selectedConnector} qrUri={qrUri} />
-        )}
+            {(selectedConnector === 'CREDIT_CONNECT' || selectedConnector === 'CREDIT_WALLET') && (
+              <CreditWalletView connectorId={selectedConnector} qrUri={qrUri} />
+            )}
 
-        {selectedConnector === 'METAMASK' && (
-          <MetaMaskView
-            qrUri={qrUri}
-            hasExtension={hasMetaMaskExtension}
-            logoUrl={connectorLogoMap.METAMASK}
-          />
-        )}
+            {selectedConnector === 'METAMASK' && (
+              <MetaMaskView
+                qrUri={qrUri}
+                hasExtension={hasMetaMaskExtension}
+                logoUrl={connectorLogoMap.METAMASK}
+              />
+            )}
 
-        {selectedConnector === 'WALLET_CONNECT' && (
-          <WalletConnectView
-            subView={wc.subView}
-            qrUri={qrUri}
-            logoUrl={connectorLogoMap.WALLET_CONNECT}
-            walletList={wc.walletList}
-            walletListLoading={wc.walletListLoading}
-            walletListSearch={wc.walletListSearch}
-            walletListFilterActive={wc.filterActive}
-            selectedWallet={wc.selectedWallet}
-            onShowList={wc.onShowList}
-            onSelectWallet={wc.onSelectWallet}
-            onSearchChange={wc.onSearchChange}
-            onFilterToggle={wc.onFilterToggle}
-          />
+            {selectedConnector === 'WALLET_CONNECT' && (
+              <WalletConnectView
+                subView={wc.subView}
+                qrUri={qrUri}
+                logoUrl={connectorLogoMap.WALLET_CONNECT}
+                walletList={wc.walletList}
+                walletListLoading={wc.walletListLoading}
+                walletListSearch={wc.walletListSearch}
+                walletListFilterActive={wc.filterActive}
+                selectedWallet={wc.selectedWallet}
+                onShowList={wc.onShowList}
+                onSelectWallet={wc.onSelectWallet}
+                onSearchChange={wc.onSearchChange}
+                onFilterToggle={wc.onFilterToggle}
+              />
+            )}
+          </>
         )}
       </div>
     </div>
@@ -278,15 +299,36 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
   onClose,
   onLog,
   wcProjectId,
+  requiredChainId,
+  renderConnectError,
 }) => {
   const [selectedConnector, setSelectedConnector] = useState<ConnectorId | null>(null);
   const [qrUriMap, setQrUriMap] = useState<Partial<Record<ConnectorId, string>>>({});
   const pendingQrConnectorRef = useRef<ConnectorId | null>(null);
   const [recentConnector, setRecentConnector] = useState<ConnectorId | null>(null);
   const [hasMetaMaskExtension, setHasMetaMaskExtension] = useState<boolean>(false);
+  const [errorState, setErrorState] = useState<{ connectorId: ConnectorId; error: Error } | null>(
+    null,
+  );
 
   const wc = useWCState();
 
+  // wagmi 상태 — chain mismatch invariant 판정용
+  const account = useAccount();
+  const { disconnectAsync } = useDisconnect();
+  const wagmiConfig = useConfig();
+
+  const chainMismatch =
+    requiredChainId != null &&
+    account.status === 'connected' &&
+    account.chainId != null &&
+    account.chainId !== requiredChainId;
+
+  const requiredChainName = useMemo<string | undefined>(() => {
+    if (requiredChainId == null) return undefined;
+    return wagmiConfig.chains.find((chain) => chain.id === requiredChainId)?.name;
+  }, [wagmiConfig.chains, requiredChainId]);
+
   // QR URI 수신 — 커넥터별 캐시에 저장 (null은 무시하여 캐시 유지)
   const handleQrUri = useCallback((uri: string | null) => {
     if (uri) {
@@ -298,7 +340,10 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
   // 연결 완료
   const handleConnect = useCallback(
     (result: Parameters<typeof onConnect>[0]) => {
+      setErrorState(null);
       onConnect(result);
+      // chain mismatch가 있으면 모달은 SwitchChainView로 자동 전환됨 (닫지 않음)
+      // Provider 측에서 requiredChainId가 매칭될 때까지 force-open 유지
       onClose();
     },
     [onConnect, onClose],
@@ -306,17 +351,25 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
 
   // 연결 실패 — 실패한 커넥터의 QR 캐시만 삭제
   const handleError = useCallback(
-    (error: Error, connectorId: ConnectorId): void => {
-      onLog?.(`[connect-kit] connection failed (${connectorId}): ${error.message}`, error);
-      setSelectedConnector(null);
+    (error: unknown, connectorId: ConnectorId): void => {
+      const normalizedError = error instanceof Error ? error : new Error(String(error));
+      onLog?.(
+        `[connect-kit] connection failed (${connectorId}): ${normalizedError.message}`,
+        normalizedError,
+      );
       setQrUriMap((prev) => {
         const next = { ...prev };
         delete next[connectorId];
         return next;
       });
       wc.resetView();
+      if (renderConnectError) {
+        setErrorState({ connectorId, error: normalizedError });
+      } else {
+        setSelectedConnector(null);
+      }
     },
-    [onLog, wc.resetView],
+    [onLog, wc.resetView, renderConnectError],
   );
 
   // 연결 시도
@@ -327,7 +380,6 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
   });
 
   // wagmi connector icon 매핑
-  const wagmiConfig = useConfig();
   const connectorLogoMap = useMemo(() => {
     const map: Partial<Record<ConnectorId, string>> = {};
     const connectorIds: ConnectorId[] = [
@@ -355,18 +407,19 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
       setSelectedConnector(null);
       setQrUriMap({});
       pendingQrConnectorRef.current = null;
+      setErrorState(null);
       wc.reset();
       cancelConnect();
     }
   }, [open, cancelConnect, wc.reset]);
 
-  // 커넥터 선택 — 같은 커넥터 재선택 시 무시, 다른 커넥터 선택 시 이전 연결 취소 후 새 연결
+  // 커넥터 선택
   const handleSelectConnector = useCallback(
     (id: ConnectorId): void => {
-      if (id === selectedConnector) return;
-
+      if (id === selectedConnector && !errorState) return;
       pendingQrConnectorRef.current = id;
       setSelectedConnector(id);
+      setErrorState(null);
       wc.resetView();
       writeRecentConnector(id);
       setRecentConnector(id);
@@ -380,6 +433,7 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
     },
     [
       selectedConnector,
+      errorState,
       triggerConnect,
       cancelConnect,
       wcProjectId,
@@ -390,17 +444,103 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
 
   // 뒤로가기 — QR 캐시는 유지, wagmi만 reset
   const handleBack = useCallback((): void => {
+    if (errorState) {
+      setErrorState(null);
+      setSelectedConnector(null);
+      return;
+    }
     if (selectedConnector === 'WALLET_CONNECT' && wc.handleBack()) return;
     pendingQrConnectorRef.current = null;
     setSelectedConnector(null);
     cancelConnect();
-  }, [selectedConnector, wc.handleBack, cancelConnect]);
+  }, [selectedConnector, errorState, wc.handleBack, cancelConnect]);
+
+  // chain mismatch 상태에서의 disconnect (Switch chain pane의 cancel)
+  const handleSwitchChainDisconnect = useCallback((): void => {
+    disconnectAsync().catch((err: unknown) => {
+      const normalized = err instanceof Error ? err : new Error(String(err));
+      onLog?.(`[connect-kit] disconnect failed: ${normalized.message}`, normalized);
+    });
+  }, [disconnectAsync, onLog]);
+
+  // overlay 클릭 — chain mismatch 상태에선 무시 (실수 클릭 방어)
+  const handleOverlayClick = useCallback((): void => {
+    if (chainMismatch) return;
+    onClose();
+  }, [chainMismatch, onClose]);
+
+  // close 버튼 — chain mismatch 상태에선 disconnect
+  const handleCloseClick = useCallback((): void => {
+    if (chainMismatch) {
+      handleSwitchChainDisconnect();
+      return;
+    }
+    onClose();
+  }, [chainMismatch, handleSwitchChainDisconnect, onClose]);
+
+  const renderedError: ReactNode = useMemo(() => {
+    if (!errorState || !renderConnectError) return null;
+    const ctx: ConnectErrorContext = {
+      connectorId: errorState.connectorId,
+      reason: classifyError(errorState.error),
+      error: errorState.error,
+      retry: () => {
+        const id = errorState.connectorId;
+        setErrorState(null);
+        pendingQrConnectorRef.current = id;
+        cancelConnect();
+        triggerConnect(id);
+      },
+      dismiss: () => {
+        setErrorState(null);
+        setSelectedConnector(null);
+      },
+    };
+    return renderConnectError(ctx);
+  }, [errorState, renderConnectError, triggerConnect, cancelConnect]);
+
+  // chain mismatch면 단일 pane (selector/detail 숨김)
+  // requiredChainId != null 재확인은 TS narrowing용 — chainMismatch true면 이미 보장됨
+  if (chainMismatch && requiredChainId != null) {
+    return (
+      <div className="ck-root">
+        <div className="ck-overlay" onClick={handleOverlayClick} />
+        <div
+          className="ck-modal ck-modal--switch-chain"
+          role="dialog"
+          aria-modal="true"
+          aria-label="Switch network"
+        >
+          <div className="ck-pane">
+            <div className="ck-pane__header">
+              <h3 className="ck-pane__title">Switch network</h3>
+              <button
+                type="button"
+                className="ck-btn-close"
+                onClick={handleCloseClick}
+                aria-label="Cancel and disconnect"
+              />
+            </div>
+            <div className="ck-pane__body">
+              <SwitchChainView
+                currentChainId={account.chainId}
+                requiredChainId={requiredChainId}
+                requiredChainName={requiredChainName}
+                onDisconnect={handleSwitchChainDisconnect}
+                onLog={onLog}
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
 
   return (
     <div className="ck-root">
-      <div className="ck-overlay" onClick={onClose} />
+      <div className="ck-overlay" onClick={handleOverlayClick} />
       <div
-        className={`ck-modal${selectedConnector ? ' ck-modal--has-detail' : ''}`}
+        className={`ck-modal${(selectedConnector ?? errorState) ? ' ck-modal--has-detail' : ''}`}
         role="dialog"
         aria-modal="true"
         aria-label="Connect Wallet"
@@ -410,7 +550,7 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
           selected={selectedConnector}
           recentConnector={recentConnector}
           onSelect={handleSelectConnector}
-          onClose={onClose}
+          onClose={handleCloseClick}
         />
         <DetailPane
           selectedConnector={selectedConnector}
@@ -418,8 +558,9 @@ const ConnectModalInner: FC<ConnectModalInnerProps> = ({
           hasMetaMaskExtension={hasMetaMaskExtension}
           connectorLogoMap={connectorLogoMap}
           wc={wc}
+          errorOverride={renderedError}
           onBack={handleBack}
-          onClose={onClose}
+          onClose={handleCloseClick}
         />
       </div>
     </div>

package/src/index.ts

@@ -1,7 +1,11 @@
 export { ConnectModal } from './ConnectModal';
+export { ConnectKitProvider, useConnectKit } from './ConnectKitProvider';
+export type { ConnectKitContextValue, ConnectKitProviderProps } from './ConnectKitProvider';
 export { creditConnectConnector } from './creditConnectConnector';
 export type { CreditConnectConnectorOptions } from './creditConnectConnector';
 export type {
+  ConnectErrorContext,
+  ConnectErrorReason,
   ConnectModalProps,
   Connectors,
   ConnectResult,

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from 'react';
+
 export type ConnectorId = 'CREDIT_WALLET' | 'CREDIT_CONNECT' | 'METAMASK' | 'WALLET_CONNECT';
 
 export type CreditWalletStrategy = 'walletConnect' | 'creditConnect';
@@ -28,6 +30,16 @@ export interface ConnectResult {
   connectorId: ConnectorId;
 }
 
+export type ConnectErrorReason = 'rejected' | 'unsupported' | 'unknown';
+
+export interface ConnectErrorContext {
+  connectorId: ConnectorId;
+  reason: ConnectErrorReason;
+  error: Error;
+  retry: () => void;
+  dismiss: () => void;
+}
+
 export interface ConnectModalProps {
   open: boolean;
   connectors: Connectors;
@@ -35,4 +47,6 @@ export interface ConnectModalProps {
   onClose: () => void;
   onLog?: (message: string, error?: Error) => void;
   wcProjectId?: string;
+  requiredChainId?: number;
+  renderConnectError?: (ctx: ConnectErrorContext) => ReactNode;
 }

package/src/views/SwitchChainView.tsx

@@ -0,0 +1,67 @@
+import { useState, type FC } from 'react';
+import { useSwitchChain } from 'wagmi';
+
+interface SwitchChainViewProps {
+  currentChainId: number | undefined;
+  requiredChainId: number;
+  requiredChainName?: string;
+  onDisconnect: () => void;
+  onLog?: (message: string, error?: Error) => void;
+}
+
+export const SwitchChainView: FC<SwitchChainViewProps> = ({
+  currentChainId,
+  requiredChainId,
+  requiredChainName,
+  onDisconnect,
+  onLog,
+}) => {
+  const { switchChainAsync, isPending } = useSwitchChain();
+  const [error, setError] = useState<Error | null>(null);
+
+  const targetLabel = requiredChainName ?? `chain ${requiredChainId}`;
+
+  const handleSwitch = (): void => {
+    setError(null);
+    switchChainAsync({ chainId: requiredChainId }).catch((err: unknown) => {
+      const normalized = err instanceof Error ? err : new Error(String(err));
+      // wagmi's MetaMask connector handles 4902 (chain not added) via wallet_addEthereumChain
+      // automatically when chain metadata is configured. We only surface what reaches us.
+      const code =
+        typeof err === 'object' && err !== null && 'code' in err
+          ? (err as { code: unknown }).code
+          : undefined;
+      if (code === 4902) {
+        onLog?.('[connect-kit] chain not registered in wallet (4902)', normalized);
+      } else {
+        onLog?.(`[connect-kit] switch chain failed: ${normalized.message}`, normalized);
+      }
+      setError(normalized);
+    });
+  };
+
+  return (
+    <div className="ck-view ck-view--switch-chain">
+      <h4 className="ck-view__title">Wrong network</h4>
+      <p className="ck-view__description">
+        {currentChainId != null
+          ? `Connected to chain ${currentChainId}. Please switch to ${targetLabel} to continue.`
+          : `Please switch to ${targetLabel} to continue.`}
+      </p>
+      <div className="ck-view__actions">
+        <button
+          type="button"
+          className="ck-btn-primary"
+          onClick={handleSwitch}
+          disabled={isPending}
+        >
+          {isPending ? 'Waiting for wallet…' : `Switch to ${targetLabel}`}
+        </button>
+        <button type="button" className="ck-btn-secondary" onClick={onDisconnect}>
+          Disconnect
+        </button>
+      </div>
+      {error && <p className="ck-view__caption ck-view__caption--error">{error.message}</p>}
+    </div>
+  );
+};