@sodax/wallet-sdk-react 2.0.0-rc.2 → 2.0.0-rc.4

package/docs/SUB_PATH_EXPORTS.md

@@ -109,35 +109,26 @@ If a cross-cutting type genuinely needs to be available from the barrel (typing
 [`tsup.config.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/tsup.config.ts) declares one entry per public boundary:
 
 ```typescript
-const sharedConfig = {
+export default defineConfig({
   entry: [
     'src/index.ts',
     'src/xchains/*/index.ts',     // glob — picks up new chain folders automatically
     'src/xchains/*/index.tsx',
   ],
+  format: ['esm'],
   outDir: 'dist',
   external: ['react', 'react-dom', '@tanstack/react-query'],
   // ...
-};
-
-export default defineConfig([
-  { ...sharedConfig, format: ['esm'], splitting: true,  outExtension: () => ({ js: '.mjs' }) },
-  { ...sharedConfig, format: ['cjs'], splitting: false, outExtension: () => ({ js: '.cjs' }) },
-]);
+});
 ```
 
-Two production builds:
-
-| Build | `splitting` | Output |
-|-------|-------------|--------|
-| ESM | `true` | `.mjs` files share class instances across entry points |
-| CJS | `false` | One `.cjs` per entry, no chunk-sharing |
+The build is ESM-only with `splitting: true` so chunks are shared across entry points and `instanceof XverseXConnector` works regardless of which entry the connector was imported from. React-only consumers (Vite, Next.js, esbuild, Webpack) all resolve ESM by default — no CJS output is shipped.
 
-**Why ESM splitting matters** — without it, the same class would be defined twice (once in `dist/index.mjs`, once in `dist/xchains/bitcoin/index.mjs`), and `instanceof XverseXConnector` would return `false` if the connector was constructed in one entry and tested in another. With splitting on, both entries import the class from a shared chunk, preserving identity.
+DTS is generated by tsup's internal `rollup-plugin-dts` integration (`dts: true`), which emits `.d.ts` declarations. The build script wraps tsup in `NODE_OPTIONS=--max-old-space-size=8192` because rollup-plugin-dts inlines transitive dep types and otherwise OOMs the default V8 heap on this package's type graph.
 
 ### Adding a new chain
 
-The glob `src/xchains/*/index.ts` is **auto-discovering** — creating `src/xchains/aptos/index.ts` automatically produces `dist/xchains/aptos/index.{mjs,cjs,d.ts}` on next build. No `tsup.config.ts` edit required. See [`ADDING_A_NEW_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md#step-4--xchainschainindexts-barrel-for-sub-path-export).
+The glob `src/xchains/*/index.ts` is **auto-discovering** — creating `src/xchains/aptos/index.ts` automatically produces `dist/xchains/aptos/index.{mjs,d.ts}` on next build. No `tsup.config.ts` edit required. See [`ADDING_A_NEW_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md#step-4--xchainschainindexts-barrel-for-sub-path-export).
 
 ---
 
@@ -150,13 +141,11 @@ Two fields work together to support modern bundlers and legacy `moduleResolution
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs"
     },
     "./xchains/*": {
       "types": "./dist/xchains/*/index.d.ts",
-      "import": "./dist/xchains/*/index.mjs",
-      "require": "./dist/xchains/*/index.cjs"
+      "import": "./dist/xchains/*/index.mjs"
     }
   },
   "typesVersions": {
@@ -169,8 +158,8 @@ Two fields work together to support modern bundlers and legacy `moduleResolution
 
 | Field | Read by | Purpose |
 |-------|---------|---------|
-| `exports['.']` | All bundlers (Vite, Webpack, esbuild, Next.js), modern Node | Resolves `@sodax/wallet-sdk-react` to the right artifact per condition (ESM/CJS/types) |
-| `exports['./xchains/*']` | Same | Wildcard maps `@sodax/wallet-sdk-react/xchains/<chain>` to the matching `dist/xchains/<chain>/index.<ext>` |
+| `exports['.']` | All bundlers (Vite, Webpack, esbuild, Next.js), modern Node | Resolves `@sodax/wallet-sdk-react` to the ESM artifact + types |
+| `exports['./xchains/*']` | Same | Wildcard maps `@sodax/wallet-sdk-react/xchains/<chain>` to the matching `dist/xchains/<chain>/index.mjs` |
 | `typesVersions['xchains/*']` | TypeScript with `moduleResolution: "node"` (legacy) | Fallback for TS configs that don't honor the `exports` field's `types` condition |
 
 Modern projects with `"moduleResolution": "bundler"` or `"node16"` only need `exports`. `typesVersions` ensures sub-path types resolve for older configs that still see `@sodax/wallet-sdk-react/xchains/bitcoin` as a path traversal.
@@ -181,32 +170,15 @@ If a consumer reports "Cannot find module" for sub-paths in TypeScript, check th
 
 ## `instanceof` semantics across entry points
 
-Class identity is preserved across barrel and sub-path entries **only in ESM**:
+Class identity is preserved across barrel and sub-path entries by tsup's `splitting: true`, which emits shared chunks:
 
 ```typescript
-// ESM — works
 import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
 const connectors = useXConnectors({ xChainType: 'BITCOIN' });
 const xverse = connectors.find(c => c instanceof XverseXConnector); // ✅ may be true
-
-// CJS — broken (in theory)
-// require('@sodax/wallet-sdk-react') and require('@sodax/wallet-sdk-react/xchains/bitcoin')
-// load XverseXConnector from separate compiled files; instanceof returns false.
 ```
 
-In practice this **doesn't break browser consumers** — Vite, Next.js, esbuild, Webpack all resolve ESM by default. CJS-only Node.js scripts that mix barrel and sub-path imports would hit the issue, but those scripts typically don't need `instanceof XverseXConnector` (they wouldn't run in a browser-extension context).
-
-If you're a Node.js consumer running CJS and need cross-entry `instanceof`, either:
-- Switch your project to ESM (`"type": "module"` in your `package.json`), or
-- Stick to **one** entry point — only the sub-path or only the barrel, never both for the same class.
-
-The `tsup.config.ts` comment documents this trade-off:
-
-```typescript
-// CJS does not support code splitting — instanceof across barrel and sub-path
-// entries will fail. In practice this is not an issue because browser apps (Vite,
-// Next.js) resolve ESM, and Node.js scripts don't use sub-path instanceof checks.
-```
+The package is ESM-only — browser apps (Vite, Next.js) and Node consumers both resolve through the same `.mjs` chunks, so `instanceof` holds regardless of whether the connector was imported via the barrel or via a sub-path.
 
 ---
 
@@ -229,7 +201,7 @@ The error message can also appear if you tried `import type { XverseXConnector }
 
 ### `instanceof XverseXConnector` returns `false` for a connector that should match
 
-Likely a CJS / dual-import issue. Verify that the connector instance came from the same entry point you're testing against. Switching to ESM resolution fixes this for all bundlers.
+Likely caused by the package being loaded twice (e.g. duplicate copies under different `node_modules` paths, or a bundler config that splits the dependency across chunks without dedup). Verify there is exactly one `@sodax/wallet-sdk-react` in your dependency tree (`pnpm why @sodax/wallet-sdk-react`).
 
 ### `Module not found: '@sodax/wallet-sdk-react/xchains/aptos'` after adding a new chain
 
@@ -242,5 +214,5 @@ Run `pnpm build:packages` — `dist/xchains/aptos/` only exists after a build. T
 - [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — full sub-path map per chain
 - [Adding a New Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md) — Step 4 covers the barrel that powers a new sub-path
 - [Architecture](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ARCHITECTURE.md) — store-first hooks consume only barrel exports
-- [tsup splitting docs](https://tsup.egoist.dev/#code-splitting) — official docs on the ESM splitting behavior
+- [tsup reference](https://tsup.egoist.dev/) — bundler config reference
 - [Node.js subpath exports](https://nodejs.org/api/packages.html#subpath-exports) — the spec behind `package.json` `exports`

package/package.json

@@ -1,32 +1,46 @@
 {
   "name": "@sodax/wallet-sdk-react",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.4",
   "description": "Wallet SDK of Sodax",
+  "keywords": [
+    "sodax",
+    "wallet",
+    "sdk",
+    "react",
+    "multichain",
+    "web3"
+  ],
+  "homepage": "https://github.com/icon-project/sodax-sdks/tree/main/packages/wallet-sdk-react",
+  "bugs": {
+    "url": "https://github.com/icon-project/sodax-sdks/issues"
+  },
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.12.0"
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "README.md",
-    "docs",
-    "skills",
-    "ai-exported"
+    "docs"
   ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs"
     },
     "./xchains/*": {
       "types": "./dist/xchains/*/index.d.ts",
-      "import": "./dist/xchains/*/index.mjs",
-      "require": "./dist/xchains/*/index.cjs"
+      "import": "./dist/xchains/*/index.mjs"
     }
   },
   "typesVersions": {
@@ -52,37 +66,35 @@
     "@injectivelabs/wallet-base": "1.18.14",
     "@injectivelabs/wallet-core": "1.18.14",
     "@injectivelabs/wallet-cosmos": "1.18.14",
-    "@injectivelabs/wallet-evm": "1.18.14",
     "@injectivelabs/wallet-strategy": "1.18.14",
     "@mysten/dapp-kit": "0.14.18",
     "@mysten/sui": "1.21.2",
     "near-api-js": "7.2.0",
     "@solana/spl-token": "0.4.9",
     "@solana/wallet-adapter-react": "0.15.35",
-    "@solana/wallet-adapter-wallets": "0.19.30",
     "@solana/web3.js": "1.98.0",
     "@stellar/stellar-sdk": "15.1.0",
-    "@walletconnect/ethereum-provider": "^2.23.9",
     "icon-sdk-js": "1.5.3",
     "immer": "10.1.1",
     "sats-connect": "^4.2.1",
     "viem": "2.29.2",
     "wagmi": "2.16.9",
     "zustand": "4.5.2",
-    "bs58": "6.0.0",
-    "@sodax/wallet-sdk-core": "2.0.0-rc.2",
-    "@sodax/types": "2.0.0-rc.2"
+    "@sodax/wallet-sdk-core": "2.0.0-rc.4",
+    "@sodax/types": "2.0.0-rc.4"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.17.4",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
     "happy-dom": "^20.8.9",
     "knip": "5.30.5",
     "react-dom": "19.1.4",
+    "tslib": "2.8.1",
     "tsup": "8.5.0",
     "typescript": "5.5.4",
-    "vitest": "2.1.9"
+    "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@tanstack/react-query": "5.x",
@@ -94,12 +106,9 @@
     "clean": "rm -rf dist && rm -rf node_modules && rm -rf .turbo",
     "pretty": "biome format . --write",
     "checkTs": "tsc --noEmit",
-    "checkTs:examples": "tsc --noEmit -p tsconfig.examples.json",
+    "check-exports": "attw --pack --profile esm-only",
     "test": "vitest run",
-    "knip": "knip",
-    "lint": "biome lint . --write",
-    "check:ai-exported": "bash ./scripts/check-ai-exported.sh",
-    "check:ai-links": "bash ./scripts/check-ai-links.sh",
-    "check:ai-imports": "bash ./scripts/check-ai-imports.sh"
+    "check:knip": "knip",
+    "lint": "biome lint . --write"
   }
 }

package/ai-exported/AGENTS.md

@@ -1,122 +0,0 @@
-# AGENTS.md — `@sodax/wallet-sdk-react` AI Export
-
-You are a coding agent helping a developer **integrate** or **migrate** the `@sodax/wallet-sdk-react` package. This document is your entry point. Read this first, then route to the right sub-folder.
-
-The files in this `ai-exported/` directory are designed for AI consumption: short, table-heavy, self-contained recipes, and machine-checkable checklists. Human-readable narrative lives in each folder's `README.md`.
-
----
-
-## Step 1 — Identify the task
-
-| User says... | Path | Start at |
-|---|---|---|
-| "upgrade to v2", "migrate from v1", "old hooks no longer work", "useXWagmiStore is gone" | **migration** | `migration/ai-rules.md` |
-| "add wallet connect", "set up SodaxWalletProvider", "first time using this lib" | **integration** | `integration/ai-rules.md` |
-| Looking up a v1 → v2 symbol mapping | direct | `migration/reference/*.md` |
-| Looking up a hook signature or available connector | direct | `integration/reference/*.md` |
-
-The package name **did not change** between v1 and v2 — both versions publish as `@sodax/wallet-sdk-react`. Migration is detected by import surface (`useXWagmiStore`, positional hook args, `rpcConfig` / `options` / `initialState` props on `SodaxWalletProvider`), not by package name.
-
-If both signals appear (project has v1 patterns AND wants new features), **migration first, then integration**.
-
----
-
-## Step 2 — Load the right context
-
-**For migration tasks:**
-
-1. `migration/ai-rules.md` — DO/DON'T + workflow + stop conditions
-2. `migration/breaking-changes.md` — narrative WHY behind each change
-3. `migration/reference/*.md` — lookup tables (imports, hooks, config, components)
-4. `migration/recipes/<task>.md` — paired before/after for the specific use case
-5. `migration/checklist.md` — verification loop
-
-**For integration tasks:**
-
-1. `integration/ai-rules.md` — DO/DON'T + workflow
-2. `integration/recipes/setup.md` — always read this first (everything else depends on it)
-3. `integration/recipes/<task>.md` — task-specific guide
-4. `integration/reference/*.md` — API surface lookup
-
----
-
-## Step 3 — Honor flow-specific stop conditions
-
-Each flow has its own list of conditions that **HARD STOP** code generation and require asking the user:
-
-- Migration stops → [`migration/ai-rules.md`](./migration/ai-rules.md) § "Stop conditions"
-- Integration stops → [`integration/ai-rules.md`](./integration/ai-rules.md) § "Stop conditions"
-
-Read the relevant list **before** applying any change. When stopping, quote the offending file/line and present the user with concrete options. Do **not** guess.
-
-Cross-flow signals (true regardless of flow):
-
-- User explicitly requests a behavior that v2 does not support (custom chain not in [`integration/reference/chain-support.md`](./integration/reference/chain-support.md), custom `XService` / `XConnector` subclass with non-trivial logic).
-- User mixes both v1 and v2 patterns in new code being written — do migration first, then integration.
-
----
-
-## Step 4 — Verification protocol
-
-After **every** code change you make:
-
-1. Run `pnpm checkTs` from the user's app root (or the package the change touched).
-2. If errors mention `@sodax/wallet-sdk-react`, look up the symbol in `migration/reference/` or `integration/reference/`.
-3. If a symbol isn't in any reference file, **stop and ask**. Do not invent migrations.
-4. After all errors resolve, mark the relevant items in `migration/checklist.md` (for migrations) or move to the next recipe.
-
-You are **done** when:
-- `pnpm checkTs` exits clean for the user's project.
-- All items in `migration/checklist.md` are checked (migration only).
-- The user has confirmed the changed flow works in their dev environment.
-
----
-
-## Conventions in this directory
-
-- **Recipes are self-contained.** A recipe file in `recipes/` contains everything needed to apply the change — before/after code, steps, verification. Do not jump between files.
-- **Reference files are tables.** `reference/*.md` contains markdown tables and paired code blocks marked `// v1 ❌` and `// v2 ✅`. Treat them as lookup, not narrative.
-- **Token budget**: Each file is sized to fit comfortably in your context. If you find yourself loading more than 3 files for a single task, you are probably doing it wrong — re-route via the table above.
-- **Single source of truth**: Behavioral / breaking-change *explanations* live only in `migration/breaking-changes.md`. Other files reference it but do not duplicate the prose.
-
----
-
-## Quick symbol lookup
-
-If the user mentions a symbol you don't recognize, grep these files in order:
-
-```
-migration/reference/imports.md      — import path changes
-migration/reference/hooks.md        — hook renames + signature changes
-migration/reference/config.md       — SodaxWalletProvider config changes
-migration/reference/components.md   — component / provider renames
-integration/reference/hooks.md      — full v2 hook surface
-integration/reference/connectors.md — available wallet connectors per chain
-integration/reference/chain-support.md — supported chains + slots
-```
-
-If still not found: the symbol may be **internal** (not exported from v2) or **removed**. Ask the user to share the v1 file/line so you can decide.
-
----
-
-## Package context
-
-- **Name**: `@sodax/wallet-sdk-react` (same package name in v1 and v2)
-- **Version target**: v2.x (current).
-- **Peer deps**: `react >= 19`, `@tanstack/react-query 5.x`
-- **Install**: `pnpm add @sodax/wallet-sdk-react @tanstack/react-query`
-- **Audience**: dApp builders integrating multi-chain wallet connectivity (9 chain types: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks).
-
-For internal architecture (only relevant if you're modifying the package itself, not consuming it), see `../CLAUDE.md` in the parent directory.
-
----
-
-## Pointers
-
-- [`integration/README.md`](./integration/README.md) — start here for new integrations: file index, recommended reading order, install snippet, provider-stack ordering.
-- [`migration/README.md`](./migration/README.md) — start here for v1 → v2 ports: file index, reading order, cross-cutting checklist pointer.
-- [`integration/recipes/setup.md`](./integration/recipes/setup.md) — install, mount `SodaxWalletProvider`, pick chain slots.
-- [`integration/architecture.md`](./integration/architecture.md) — mental model: provider mount tree, frozen config, EVM single-connection, `xChainType` vs `xChainId`.
-- [`integration/reference/`](./integration/reference/) — hooks, connectors, chain-support, wallet-brand identifiers lookup tables.
-- [`integration/reference/wallet-brands.md`](./integration/reference/wallet-brands.md) — known wallet brand identifiers (`'hana'`, `'phantom'`, `'xverse'`, …) for batch hooks, plus a runtime discovery snippet.
-- [`migration/breaking-changes.md`](./migration/breaking-changes.md) — full narrative of every v1 → v2 change.

package/ai-exported/integration/README.md

@@ -1,102 +0,0 @@
-# Integration: First-time setup (Human-readable overview)
-
-This folder helps you integrate `@sodax/wallet-sdk-react` into a fresh React app. It is the **human-facing** entry point for new integrations. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first.
-
-If you are migrating from v1 instead, see `../migration/`.
-
----
-
-## What this package does
-
-`@sodax/wallet-sdk-react` is the React layer over `@sodax/wallet-sdk-core`. It gives you:
-
-- **Multi-chain wallet connect** across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks).
-- **Hooks** (`useXConnect`, `useXAccount`, `useXDisconnect`, `useXSignMessage`, etc.) backed by a Zustand store — composable and SSR-safe.
-- **Headless modal primitives** (`useWalletModal`, `useChainGroups`, `useBatchConnect`) — bring your own UI.
-- **Typed wallet providers** for hand-off to `@sodax/sdk` calls (`useWalletProvider`).
-
----
-
-## Recommended path (in order)
-
-If this is your first time using the package:
-
-1. [`recipes/setup.md`](./recipes/setup.md) — install, wire `SodaxWalletProvider`, pick chain slots. **Always do this first**.
-2. Pick a connect UX (one, not both):
-   - [`recipes/connect-button.md`](./recipes/connect-button.md) — single chain, simplest UX.
-   - [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) — chain picker + connector picker, headless.
-3. [`recipes/sign-message.md`](./recipes/sign-message.md) — sign messages cross-chain (auth flows).
-4. [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls (swaps, lending, staking, etc.).
-5. [`recipes/switch-chain.md`](./recipes/switch-chain.md) — switch the active EVM network when source chain doesn't match.
-6. [`recipes/chain-detection.md`](./recipes/chain-detection.md) — list enabled chains, render connected list with hydration gate, install detection.
-7. Add advanced features as needed:
-   - [`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md) — enable WalletConnect for enterprise-custody / mobile-only wallets.
-   - [`recipes/batch-operations.md`](./recipes/batch-operations.md) — batch connect / disconnect across multiple chains.
-   - [`recipes/sub-path-imports.md`](./recipes/sub-path-imports.md) — deep imports from `xchains/<chain>` for `instanceof` checks or custom connector lists.
-8. Reference docs (lookup as needed):
-   - [`reference/hooks.md`](./reference/hooks.md) — full hook surface with signatures.
-   - [`reference/connectors.md`](./reference/connectors.md) — available wallet connectors per chain.
-   - [`reference/chain-support.md`](./reference/chain-support.md) — supported chains, slots, and adapter notes.
-9. Copy-paste examples (runnable code, minimal narrative):
-   - [`examples/`](./examples/) — 4 self-contained `.tsx` files: minimal EVM setup, multi-chain modal, Next.js App Router, WalletConnect setup.
-
----
-
-## Install
-
-```bash
-pnpm add @sodax/wallet-sdk-react @tanstack/react-query
-```
-
-Peer dependencies:
-
-```json
-{
-  "react": ">=19",
-  "@tanstack/react-query": "5.x"
-}
-```
-
----
-
-## Pair with `@sodax/sdk` and `@sodax/dapp-kit`
-
-Most apps integrate this package together with the SDK and dapp-kit:
-
-```
-@sodax/sdk            ← business logic (swaps, lending, staking, etc.)
-@sodax/dapp-kit       ← high-level React hooks combining SDK + wallet-sdk
-@sodax/wallet-sdk-react  ← wallet connectivity (this package)
-```
-
-If you are using all three, mount providers in this order at the app root:
-
-```tsx
-<SodaxProvider config={sodaxConfig}>            {/* @sodax/dapp-kit */}
-  <QueryClientProvider client={queryClient}>
-    <SodaxWalletProvider config={walletConfig}>  {/* this package */}
-      {children}
-    </SodaxWalletProvider>
-  </QueryClientProvider>
-</SodaxProvider>
-```
-
-`SodaxProvider` (from dapp-kit) wraps the lot. `QueryClientProvider` must wrap `SodaxWalletProvider` because hooks inside use React Query.
-
----
-
-## Conventions worth knowing
-
-- **Hooks use a single options object.** `useXConnectors({ xChainType: 'EVM' })`, not positional args.
-- **`xChainId` (chain key) and `xChainType` (family) are both accepted** by `useXAccount` and `useWalletProvider`. Pass one, not both.
-- **`useXConnect` is a React Query mutation.** Pass an `IXConnector` to `mutateAsync`.
-- **Persisted connections.** Connections survive reload via `localStorage` key `xwagmi-store`. Gate UI on `useConnectedChains().status === 'ready'` to avoid hydration flicker.
-- **EVM is one connection across all networks.** wagmi treats every configured EVM chain as part of one connector — there is no per-network connect/disconnect.
-
----
-
-## Getting help
-
-- API surface lookup: [`reference/`](./reference/).
-- Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).
-- Internal architecture (only relevant for SODAX maintainers): `../CLAUDE.md` in the package root.

package/ai-exported/integration/ai-rules.md

@@ -1,136 +0,0 @@
-# AI Rules — Fresh Integration
-
-You are integrating `@sodax/wallet-sdk-react` into a user's React app for the first time. Follow this protocol exactly.
-
----
-
-## Workflow (do these in order)
-
-### 1. Survey the project
-
-Before changing anything, gather context:
-
-```bash
-# Framework — Next.js (App Router or Pages)? Vite? CRA?
-cat <user>/package.json | grep -E '"next|"vite|"react-scripts'
-
-# React version — must be >= 19
-cat <user>/package.json | grep '"react"'
-
-# React Query already installed?
-cat <user>/package.json | grep '"@tanstack/react-query'
-
-# Existing wallet libraries that may conflict
-grep -l "wagmi\|@solana/wallet-adapter\|@mysten/dapp-kit" <user>/package.json
-```
-
-**If React < 19**, stop and tell the user — this package requires React 19.
-
-**If wagmi / @solana/wallet-adapter / @mysten/dapp-kit are already direct dependencies**, stop and ask the user — this package mounts those internally; running both will cause duplicate provider context errors.
-
-### 2. Always start with `setup.md`
-
-Read [`recipes/setup.md`](./recipes/setup.md) and apply it. **Do not skip ahead** — every subsequent recipe assumes `SodaxWalletProvider` is already mounted.
-
-### 3. Pick exactly one connect UX
-
-Connect UX is **either / or**, not additive:
-
-- [`recipes/connect-button.md`](./recipes/connect-button.md) — pick this when the app needs to connect one chain at a time, and the UX is a single button per chain.
-- [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) — pick this when the app needs a chain-picker → connector-picker modal, or when one wallet should connect multiple chains in sequence.
-
-Ask the user which UX they want before applying. If unsure, default to `connect-button.md` (simpler).
-
-### 4. Add advanced features as separate steps
-
-Only after the connect UX works should you add:
-
-- Sign-message flows ([`recipes/sign-message.md`](./recipes/sign-message.md))
-- Bridge to `@sodax/sdk` calls ([`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md))
-- Switch active EVM network ([`recipes/switch-chain.md`](./recipes/switch-chain.md))
-- Chain & wallet detection patterns ([`recipes/chain-detection.md`](./recipes/chain-detection.md))
-- WalletConnect ([`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md))
-- Batch connect / disconnect ([`recipes/batch-operations.md`](./recipes/batch-operations.md))
-
-Each is independent — apply only what the user asked for.
-
-### Copy-paste templates
-
-If the user wants a full working starter file rather than narrative steps, point them at [`examples/`](./examples/):
-
-- `01-minimal-evm.tsx` — provider + 1 connect button
-- `02-multi-chain-modal.tsx` — full headless modal
-- `03-nextjs-app-router.tsx` — Next.js 15 SSR setup
-- `04-walletconnect-setup.tsx` — WalletConnect setup (optional single-wallet filter)
-
-Always combine with the narrative recipe — examples are skeletons, recipes explain why each piece exists.
-
----
-
-## DO
-
-- **DO** put `SodaxWalletProvider` at the app root, inside `QueryClientProvider`. Order matters.
-- **DO** include only the chain slots the user actually needs in `walletConfig`. Each slot mounts a real React provider — unused slots waste bundle size.
-- **DO** use the chain-typed hooks: `useXAccount({ xChainType: 'EVM' })`, not `useXAccount({ xChainId: someId })` unless the user specifically needs per-chain-id resolution.
-- **DO** gate UI on `useConnectedChains().status === 'ready'` whenever you render based on connection state — prevents hydration flicker on Next.js.
-- **DO** use the headless primitives (`useWalletModal`, `useChainGroups`) and let the user style the UI. Do not hand-roll a hidden chain registry.
-- **DO** if Next.js, set `EVM.ssr: true` in `walletConfig`.
-
----
-
-## DO NOT
-
-- **DO NOT** import from `@sodax/wallet-sdk-react/xchains/<chain>` unless you specifically need a concrete class (e.g. `instanceof XverseXConnector`). Default to barrel imports.
-- **DO NOT** instantiate `XService` or `XConnector` subclasses manually — `SodaxWalletProvider` does this via the chain registry.
-- **DO NOT** call `useXConnect` outside a React component / custom hook.
-- **DO NOT** read from `useXWalletStore` directly. Use the public hooks. The store shape is internal.
-- **DO NOT** stack multiple `SodaxWalletProvider` instances. One per app.
-- **DO NOT** pass changing config references on every render — `SodaxWalletProvider` freezes config on first render. To swap config at runtime, remount with a new `key`.
-- **DO NOT** mock `useXConnect` / `useXAccount` in tests by stubbing the store. Use the real provider with a test config.
-
----
-
-## Stop conditions (defer to user)
-
-| Signal | Why stop |
-|---|---|
-| User asks for a chain not in the [chain support list](./reference/chain-support.md) | Adding a new chain requires package-level changes (see `../../CLAUDE.md`), not user-app integration. |
-| User wants to use `@sodax/sdk` for swaps / lending / etc. | This package only handles wallet connectivity. Direct user to also install `@sodax/dapp-kit`. |
-| User wants Server Components to use `useXAccount` directly | Hooks are client-only. Must wrap consumer in `'use client'`. |
-| User mentions Next.js Pages Router | Setup differs slightly — confirm before applying App Router defaults. |
-| User asks "how do I connect wallet X" but the connector isn't built in | Check [`reference/connectors.md`](./reference/connectors.md). If absent, the connector doesn't exist yet — flag as out of scope. |
-| User wants custom chains (e.g. EVM testnet not in the default list) | `EVM.chains` accepts custom chain configs, but ChainKey enum is fixed. Confirm before extending. |
-
----
-
-## Verification protocol (after every recipe)
-
-```bash
-# 1. Type check passes
-pnpm checkTs
-
-# 2. Provider is mounted exactly once
-grep -rn "SodaxWalletProvider" <user-src>           # expect one match
-
-# 3. QueryClientProvider wraps SodaxWalletProvider
-# (manual — open the provider file, confirm nesting order)
-
-# 4. Connect/disconnect works in dev
-# (manual — start dev server, click connect, verify localStorage has `xwagmi-store` key after success)
-```
-
-If steps 1–3 pass and the user confirms step 4, the recipe is done.
-
----
-
-## Done criteria
-
-The integration is complete when:
-
-- [ ] `pnpm checkTs` exits clean.
-- [ ] `SodaxWalletProvider` is mounted at the app root with the user's chosen `walletConfig`.
-- [ ] `QueryClientProvider` wraps `SodaxWalletProvider`.
-- [ ] At least one connect UX (button or modal) is wired and works in the user's dev environment.
-- [ ] If using `@sodax/sdk` features: `useWalletProvider` is used to bridge to SDK calls (see `recipes/setup.md` § "Pair with `@sodax/sdk`").
-
-Do not declare integration done before all of the above are true.