@tuwaio/satellite-react 0.5.0 → 0.6.0

package/README.md

@@ -1,157 +1,103 @@
-# Satellite Connect React
+# @tuwaio/satellite-react
 
 [![NPM Version](https://img.shields.io/npm/v/@tuwaio/satellite-react.svg)](https://www.npmjs.com/package/@tuwaio/satellite-react)
-[![License](https://img.shields.io/npm/l/@tuwaio/satellite-react.svg)](./LICENSE)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/satellite-connect/release.yml?branch=main)](https://github.com/TuwaIO/satellite-connect/actions)
+[![License](https://img.shields.io/npm/l/@tuwaio/satellite-react.svg)](https://github.com/TuwaIO/satellite-connect/blob/main/packages/satellite-react/LICENSE)
 
-React state hooks and context providers for orchestrating framework-agnostic Satellite wallet connector instances.
+`@tuwaio/satellite-react` is the React Layer 4 (L4) package of **Satellite Connect**, the wallet connection project of TUWA Stage 2 ("State & Connection", next to Pulsar). Built on **`react`**, **`zustand`** and [`@tuwaio/satellite-core`](https://satellite.docs.tuwa.io/packages/satellite-core), it provides a provider that creates the connection store, a hook to read it in components, and one headless watcher component per chain that keeps the store in sync with the wallets. It has no UI components: wallet modals and buttons live in Nova Connect.
 
 ---
 
-## 🏛️ What is `@tuwaio/satellite-react`?
+## 🏛️ Core Capabilities
 
-`@tuwaio/satellite-react` provides the React integration layer for the Satellite framework. It exposes optimized state hooks and context providers to orchestrate and watch framework-agnostic Satellite wallet connector instances.
-
-By mapping underlying Zustand store mutations to React's rendering lifecycle, it enables developers to maintain a synchronized, multi-chain connection state.
-
-Built on top of `@tuwaio/satellite-core`, this package offers a seamless developer experience for React applications requiring Web3 wallet integration.
-
----
-
-## ✨ Key Features
-
-- **Type Safety:** Full TypeScript support with proper type definitions
-- **Chain Agnostic:** Unified support for both EVM and Solana wallets
-- **Modern React:** Built with React 19+ features and best practices
-- **Multi-Chain Support:** Seamless integration with multiple blockchain networks
-- **State Management:** Zustand-based store for efficient state handling
+- **Provider:** `SatelliteConnectProvider` creates the store once, passes later `adapter` and `callbackAfterConnected` changes to it, and runs `initializeAutoConnect` after mount, so the last connected wallet is restored in the browser.
+- **Hook:** `useSatelliteConnectStore(selector)` reads a value from the store and re-renders when it changes. `SatelliteStoreContext` gives access to the store itself (`getState`, `subscribe`); it is shared on `globalThis`, so packages that bundle their own copy of `@tuwaio/satellite-react` see the same store.
+- **Chain watchers:** `EVMConnectorsWatcher` (`/evm`) and `SolanaConnectorsWatcher` (`/solana`) render nothing. They load the watcher of their chain package after mount and copy account and chain changes made in the wallet into the store. With the `siwx` prop, for example the result of `useSiwxSession()` from [`@tuwaio/siwx-react`](https://siwx.docs.tuwa.io/packages/siwx-react), they disconnect the wallet when the sign-in is rejected or fails, or when the wallet moves to another account (or EVM chain) than the session. They restart only when a field of `siwx` changes, not when a new but equal object is passed.
+- **Typed connections:** importing `/evm` or `/solana` adds the connection types of that chain to `AllConnections` and `AllConnectors`, so `activeConnection` is typed as `EVMConnection | SolanaConnection` in an app that imports both.
 
 ---
 
 ## 💾 Installation
 
-### Requirements
+The package has three entry points. Install the peer dependencies of the ones you import:
 
-- React 19+
-- Node.js 20-24
-- TypeScript 5.9+
+| Import path                      | Provides                                                               | Peer dependencies to install                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `@tuwaio/satellite-react`        | `SatelliteConnectProvider`, `useSatelliteConnectStore`, context, types | `@tuwaio/satellite-core` (>=0.5), `react` (>=19.2.3), `zustand` (5.x)                                    |
+| `@tuwaio/satellite-react/evm`    | `EVMConnectorsWatcher`                                                 | Also `@tuwaio/satellite-evm` (>=0.5), `@wagmi/core` (3.x) and `@tuwaio/orbit-core` (>=0.3)               |
+| `@tuwaio/satellite-react/solana` | `SolanaConnectorsWatcher`                                              | Also `@tuwaio/satellite-solana` (>=0.5), `@wallet-standard/react` (1.x) and `@tuwaio/orbit-core` (>=0.3) |
+
+The `/evm` and `/solana` peer dependencies are optional, so an EVM-only app does not install Solana packages. The chain packages bring their own peer dependencies, and `@tuwaio/satellite-core` needs `@tuwaio/orbit-core` and `immer`:
 
 ```bash
-# 1. Core React Integration (Mandatory)
+# @tuwaio/satellite-react
 pnpm add @tuwaio/satellite-react @tuwaio/satellite-core @tuwaio/orbit-core react zustand immer
 
-# 2. EVM Support (Optional)
+# @tuwaio/satellite-react/evm
 pnpm add @tuwaio/satellite-evm @tuwaio/orbit-evm @wagmi/core viem
 
-# 3. Solana Support (Optional)
-pnpm add @tuwaio/satellite-solana @tuwaio/orbit-solana @solana/kit @wallet-standard/react
-
-# 4. SIWX Authentication Integration (Optional)
-pnpm add @tuwaio/siwx-core @tuwaio/siwx-react
+# @tuwaio/satellite-react/solana
+pnpm add @tuwaio/satellite-solana @tuwaio/orbit-solana @solana/kit @wallet-standard/react @wallet-standard/base @wallet-standard/features @wallet-standard/ui @wallet-standard/ui-registry @wallet-standard/app @wallet-standard/ui-core react-dom
 ```
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Usage
 
-### Basic Setup
+Render the provider and the watchers once, around your app:
 
 ```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { satelliteEVMAdapter, createDefaultTransports } from '@tuwaio/satellite-evm';
-import { SatelliteConnectProvider } from '@tuwaio/satellite-react';
+'use client';
+
+import { satelliteEVMAdapter } from '@tuwaio/satellite-evm';
+import { SatelliteConnectProvider, useSatelliteConnectStore } from '@tuwaio/satellite-react';
 import { EVMConnectorsWatcher } from '@tuwaio/satellite-react/evm';
 import { SolanaConnectorsWatcher } from '@tuwaio/satellite-react/solana';
 import { satelliteSolanaAdapter } from '@tuwaio/satellite-solana';
-import { WagmiProvider } from 'wagmi';
-import { ReactNode } from 'react';
-import { createConfig } from '@wagmi/core';
-import { injected } from '@wagmi/connectors';
-import { mainnet, sepolia } from 'viem/chains';
-import type { Chain } from 'viem/chains';
-
-export const appEVMChains = [mainnet, sepolia] as readonly [Chain, ...Chain[]];
-
-export const wagmiConfig = createConfig({
-  connectors: [injected()],
-  transports: createDefaultTransports(appEVMChains), // Automatically creates http transports
-  chains: appEVMChains,
-  ssr: true, // Enable SSR support if needed (e.g., in Next.js)
-});
-
-export const solanaRPCUrls = {
-  devnet: 'https://api.devnet.solana.com',
-};
-
-const queryClient = new QueryClient();
-
-export function Providers({ children }: { children: ReactNode }) {
-  return (
-    <WagmiProvider config={wagmiConfig}>
-      <QueryClientProvider client={queryClient}>
-        <SatelliteConnectProvider
-          adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })]}
-          autoConnect={true}
-        >
-          <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
-          <SolanaConnectorsWatcher />
-          {children}
-        </SatelliteConnectProvider>
-      </QueryClientProvider>
-    </WagmiProvider>
-  );
-}
-```
-
-### Using Hooks
-
-```tsx
-import { useSatelliteConnectStore } from '@tuwaio/satellite-react';
-
-function ExampleGettingActiveWalletFromStore() {
-  const activeConnection = useSatelliteConnectStore((state) => state.activeConnection);
-  return <div>{activeConnection?.address}</div>;
-}
-```
-
----
-
-## 🔐 Sign-In With X (SIWX) Integration
-
-The `EVMConnectorsWatcher` and `SolanaConnectorsWatcher` components accept the `siwx` session state from `@tuwaio/siwx-react`. The watchers automatically monitor connection parity and disconnect the wallet if account switching occurs without a matching session, or if the user rejects signing:
-
-```tsx
 import { useSiwxSession } from '@tuwaio/siwx-react';
-import { SatelliteConnectProvider } from '@tuwaio/satellite-react';
-import { EVMConnectorsWatcher } from '@tuwaio/satellite-react/evm';
-import { SolanaConnectorsWatcher } from '@tuwaio/satellite-react/solana';
+import { createConfig, http, injected } from '@wagmi/core';
+import type { ReactNode } from 'react';
+import { mainnet } from 'viem/chains';
+
+const appChains = [mainnet] as const;
+const wagmiConfig = createConfig({ chains: appChains, connectors: [injected()], transports: { [mainnet.id]: http() } });
+const adapters = [
+  satelliteEVMAdapter(wagmiConfig, appChains),
+  satelliteSolanaAdapter({ rpcUrls: { devnet: 'https://api.devnet.solana.com' } }),
+];
 
 export function Providers({ children }: { children: ReactNode }) {
-  const siwxSession = useSiwxSession();
+  const siwxSession = useSiwxSession(); // optional: pass the SIWX session to the watchers
 
   return (
-    <SatelliteConnectProvider
-      adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })]}
-      autoConnect={true}
-    >
+    <SatelliteConnectProvider adapter={adapters} autoConnect>
       <EVMConnectorsWatcher wagmiConfig={wagmiConfig} siwx={siwxSession} />
       <SolanaConnectorsWatcher siwx={siwxSession} />
       {children}
     </SatelliteConnectProvider>
   );
 }
+
+export function ActiveAddress() {
+  const activeConnection = useSatelliteConnectStore((state) => state.activeConnection);
+  const connecting = useSatelliteConnectStore((state) => state.connecting);
+  return <span>{connecting ? 'Connecting…' : (activeConnection?.address ?? 'Not connected')}</span>;
+}
 ```
 
+Connect a wallet with `useSatelliteConnectStore((state) => state.connect)`. Ready-made connect modals are in Nova Connect ([storybook](https://stories.tuwa.io/)), and a full-stack app with Nova Connect, SIWX and Pulsar is in the **[TUWA SDK documentation](https://sdk.docs.tuwa.io/full-stack)**.
+
 ---
 
-## 🤝 Contributing & Support
+## 🗄️ Browser Storage
 
-Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
+The provider's store saves the last connection and the recently connected wallets to `localStorage`, and removes the impersonated address, through `@tuwaio/orbit-core`. The keys, their content and when they change are listed on the [`@tuwaio/satellite-core`](https://satellite.docs.tuwa.io/packages/satellite-core) page. The store state itself is not persisted: server rendering and the first client render start with no connection, and `initializeAutoConnect` restores it after mount (it waits 300 ms and disconnects the wallets of every adapter first).
+
+---
 
-If you find this library useful, please consider supporting its development. Every contribution helps!
+## 📚 API Reference
 
-[**➡️ View Support Options**](https://github.com/TuwaIO/workflows/blob/main/Donation.md)
+Every export, with signatures and types generated from the source, is documented at **[satellite.docs.tuwa.io/packages/satellite-react](https://satellite.docs.tuwa.io/packages/satellite-react)**.
 
 ## 📄 License
 
-This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
+Licensed under the **Apache-2.0 License**. See the [LICENSE](https://github.com/TuwaIO/satellite-connect/blob/main/packages/satellite-react/LICENSE) file for details.

package/dist/{chunk-EYVLQZ24.js → chunk-4A4PSLAK.js}

@@ -1 +1 @@
-import {createContext,useContext}from'react';import {useStore}from'zustand';var e=Symbol.for("tuwaio.satellite.context"),o=globalThis,a=o[e]||(o[e]=createContext(null)),m=n=>{let t=useContext(a);if(!t)throw new Error("useSatelliteConnectStore must be used within a SatelliteConnectProvider");return useStore(t,n)};export{a,m as b};
+import {createContext,useContext}from'react';import {useStore}from'zustand';var e=Symbol.for("tuwaio.satellite.context"),o=globalThis,a=o[e]||(o[e]=createContext(null)),u=n=>{let t=useContext(a);if(!t)throw new Error("useSatelliteConnectStore must be used within a SatelliteConnectProvider");return useStore(t,n)};export{a,u as b};

package/dist/chunk-FBHCKH6M.js

@@ -0,0 +1 @@
+import {useMemo}from'react';function m(e){let t=e!=null,s=e?.enabled,n=e?.isSignedIn,d=e?.isAuthenticated,i=e?.isRejected,a=e?.status,o=e?.address,c=e?.chainId,S=!!e?.session,l=e?.session?.address,u=e?.session?.chainId;return useMemo(()=>t?{enabled:s,isSignedIn:n,isAuthenticated:d,isRejected:i,status:a,address:o,chainId:c,session:S?{address:l,chainId:u}:null}:void 0,[t,s,n,d,i,a,o,c,S,l,u])}export{m as a};

package/dist/{chunk-G2YC6JBO.cjs → chunk-HEG6FP5Z.cjs}

@@ -1 +1 @@
-'use strict';var react=require('react'),zustand=require('zustand');var e=Symbol.for("tuwaio.satellite.context"),o=globalThis,a=o[e]||(o[e]=react.createContext(null)),u=n=>{let t=react.useContext(a);if(!t)throw new Error("useSatelliteConnectStore must be used within a SatelliteConnectProvider");return zustand.useStore(t,n)};exports.a=a;exports.b=u;
+'use strict';var react=require('react'),zustand=require('zustand');var e=Symbol.for("tuwaio.satellite.context"),o=globalThis,a=o[e]||(o[e]=react.createContext(null)),p=n=>{let t=react.useContext(a);if(!t)throw new Error("useSatelliteConnectStore must be used within a SatelliteConnectProvider");return zustand.useStore(t,n)};exports.a=a;exports.b=p;

package/dist/chunk-LSWAATDN.cjs

@@ -0,0 +1 @@
+'use strict';var react=require('react');function I(e){let t=e!=null,s=e?.enabled,n=e?.isSignedIn,d=e?.isAuthenticated,i=e?.isRejected,a=e?.status,o=e?.address,c=e?.chainId,S=!!e?.session,l=e?.session?.address,u=e?.session?.chainId;return react.useMemo(()=>t?{enabled:s,isSignedIn:n,isAuthenticated:d,isRejected:i,status:a,address:o,chainId:c,session:S?{address:l,chainId:u}:null}:void 0,[t,s,n,d,i,a,o,c,S,l,u])}exports.a=I;

package/dist/evm/index.cjs

@@ -1 +1 @@
-'use strict';require('../chunk-YTP4ADBV.cjs');var chunkG2YC6JBO_cjs=require('../chunk-G2YC6JBO.cjs'),react=require('react'),jsxRuntime=require('react/jsx-runtime');function M(t){let[r,f]=react.useState(null);return react.useEffect(()=>{(async()=>{try{let n=!1,i=null;try{let[c]=await Promise.all([import('@tuwaio/satellite-evm'),import('@wagmi/core'),import('viem')]);i=c.createEVMConnectionsWatcher,n=!0;}catch{n=!1;}if(n){let c=()=>{let a=chunkG2YC6JBO_cjs.b(e=>e.activeConnection),l=chunkG2YC6JBO_cjs.b(e=>e.disconnect),s=chunkG2YC6JBO_cjs.b(e=>e.connectionError),C=chunkG2YC6JBO_cjs.b(e=>e.updateActiveConnection);return react.useEffect(()=>i({wagmiConfig:t.wagmiConfig,siwx:t.siwx,siwe:t.siwe},{activeConnection:a,disconnect:l,connectionError:s,updateActiveConnection:C}),[a?.connectorType,t.siwx,t.siwe,s,t.wagmiConfig,l,C]),null};f(()=>c);}}catch(n){console.warn("Failed to load EVM watcher:",n);}})();},[]),r?jsxRuntime.jsx(r,{...t}):null}exports.EVMConnectorsWatcher=M;
+'use strict';var chunkLSWAATDN_cjs=require('../chunk-LSWAATDN.cjs'),chunkHEG6FP5Z_cjs=require('../chunk-HEG6FP5Z.cjs'),react=require('react'),jsxRuntime=require('react/jsx-runtime');function x({createWatcher:c,wagmiConfig:o,siwx:i,siwe:e}){let n=chunkHEG6FP5Z_cjs.b(t=>t.activeConnection),a=chunkHEG6FP5Z_cjs.b(t=>t.disconnect),s=chunkHEG6FP5Z_cjs.b(t=>t.connectionError),l=chunkHEG6FP5Z_cjs.b(t=>t.updateActiveConnection),C=react.useContext(chunkHEG6FP5Z_cjs.a),p=chunkLSWAATDN_cjs.a(i),d=e!==void 0,f=e?.enabled,u=e?.isSignedIn,S=e?.isRejected,m=react.useMemo(()=>d?{enabled:f,isSignedIn:u,isRejected:S}:void 0,[d,f,u,S]);return react.useEffect(()=>c({wagmiConfig:o,siwx:p,siwe:m},{disconnect:a,updateActiveConnection:l,getState:()=>C?.getState()??{activeConnection:n,connectionError:s}}),[c,C,o,p,m,n?.connectorType,s,a,l]),null}function I(c){let[o,i]=react.useState(null);return react.useEffect(()=>{let e=true;return import('@tuwaio/satellite-evm').then(n=>{e&&i(()=>n.createEVMConnectionsWatcher);}).catch(n=>console.warn("Failed to load EVM watcher:",n)),()=>{e=false;}},[]),o?jsxRuntime.jsx(x,{createWatcher:o,...c}):null}exports.EVMConnectorsWatcher=I;

package/dist/evm/index.d.cts

@@ -2,60 +2,77 @@ import { OrbitAdapter } from '@tuwaio/orbit-core';
 import { EVMConnection, ConnectorEVM } from '@tuwaio/satellite-evm';
 import * as react from 'react';
 import { SatelliteSiwxState } from '@tuwaio/satellite-core';
+import { Config } from '@wagmi/core';
 
 /**
  * Props for the {@link EVMConnectorsWatcher} component.
  */
 interface EVMConnectorsWatcherProps {
     /**
-     * The configuration object from `@wagmi/core`.
-     * This is required to initialize the account watcher.
+     * The wagmi `Config` from `@wagmi/core` that the EVM adapter uses. Its connections are watched with
+     * `watchConnections`.
      */
-    wagmiConfig: any;
+    wagmiConfig: Config;
     /**
-     * Optional Sign-In With X (SIWX) session state.
-     * If provided, the watcher will manage updates and disconnections based on SIWX status.
-     * Directly compatible with `useSiwxSession()` from `@tuwaio/siwx-react`.
+     * Optional Sign-In With X (SIWX) session state, for example the result of `useSiwxSession()` from
+     * `@tuwaio/siwx-react`. The watcher is restarted when one of its fields changes.
      */
     siwx?: SatelliteSiwxState;
     /**
-     * @deprecated Legacy SIWE prop alias for backwards compatibility
+     * Legacy SIWE state, used only when `siwx` is not passed.
+     *
+     * @deprecated Pass `siwx` instead.
      */
     siwe?: {
+        /** Whether the user rejected the sign-in or it failed. */
         isRejected?: boolean;
+        /** Whether the user is signed in. */
         isSignedIn?: boolean;
+        /** Whether sign-in is enabled. `false` turns off the disconnect on rejection. */
         enabled?: boolean;
     };
 }
 /**
- * A dynamic version of the EVMConnectorsWatcher component that avoids static imports.
- * This component dynamically imports the dependencies only when they are available.
+ * Headless component that keeps the Satellite Connect store in sync with wagmi. Render it once inside
+ * `SatelliteConnectProvider`, next to an EVM adapter created with the same `wagmiConfig`.
  *
- * @param props - The component's props. See {@link EVMConnectorsWatcherProps} for details.
- * @returns {null} This component does not render any UI.
+ * After mount it loads `@tuwaio/satellite-evm` with a dynamic import and runs its `createEVMConnectionsWatcher`: account
+ * and network changes made in the wallet update the active connection, a wallet disconnect removes it, and with `siwx`
+ * the connection is disconnected when the SIWX sign-in is rejected or fails, or when the account or chain no longer
+ * matches the signed-in session. The watcher restarts when `wagmiConfig`, a field of `siwx`, the active connector or
+ * the connection error changes, and stops on unmount. If the import fails, a warning is logged and nothing is watched.
+ *
+ * @param props - The component props. See {@link EVMConnectorsWatcherProps}.
+ * @returns `null`; the component renders nothing.
  *
  * @example
  * ```tsx
- * import { useSiwxSession } from '@tuwaio/siwx-react';
  * import { EVMConnectorsWatcher } from '@tuwaio/satellite-react/evm';
+ * import { useSiwxSession } from '@tuwaio/siwx-react';
+ * import type { Config } from '@wagmi/core';
  *
- * function WatcherContainer() {
+ * export function WatcherContainer({ wagmiConfig }: { wagmiConfig: Config }) {
  *   const siwxSession = useSiwxSession();
  *   return <EVMConnectorsWatcher wagmiConfig={wagmiConfig} siwx={siwxSession} />;
  * }
  * ```
- *
- * @remarks
- * Monitors Wagmi account and network changes. Automatically disconnects wallet state if SIWX
- * session validation fails or is rejected.
  */
 declare function EVMConnectorsWatcher(props: EVMConnectorsWatcherProps): react.JSX.Element | null;
 
+/**
+ * The EVM watcher component, imported from `@tuwaio/satellite-react/evm`. Importing this entry point also adds
+ * `EVMConnection` and `ConnectorEVM` from `@tuwaio/satellite-evm` to `AllConnections` and `AllConnectors`.
+ *
+ * @module evm
+ */
+
 declare module '@tuwaio/satellite-react' {
     interface AllConnections {
+        /** EVM connections (`EVMConnection` from `@tuwaio/satellite-evm`), added by `@tuwaio/satellite-react/evm`. */
         [OrbitAdapter.EVM]: EVMConnection;
     }
     interface AllConnectors {
+        /** wagmi connectors (`ConnectorEVM` from `@tuwaio/satellite-evm`), added by `@tuwaio/satellite-react/evm`. */
         [OrbitAdapter.EVM]: ConnectorEVM;
     }
 }

package/dist/evm/index.d.ts

@@ -2,60 +2,77 @@ import { OrbitAdapter } from '@tuwaio/orbit-core';
 import { EVMConnection, ConnectorEVM } from '@tuwaio/satellite-evm';
 import * as react from 'react';
 import { SatelliteSiwxState } from '@tuwaio/satellite-core';
+import { Config } from '@wagmi/core';
 
 /**
  * Props for the {@link EVMConnectorsWatcher} component.
  */
 interface EVMConnectorsWatcherProps {
     /**
-     * The configuration object from `@wagmi/core`.
-     * This is required to initialize the account watcher.
+     * The wagmi `Config` from `@wagmi/core` that the EVM adapter uses. Its connections are watched with
+     * `watchConnections`.
      */
-    wagmiConfig: any;
+    wagmiConfig: Config;
     /**
-     * Optional Sign-In With X (SIWX) session state.
-     * If provided, the watcher will manage updates and disconnections based on SIWX status.
-     * Directly compatible with `useSiwxSession()` from `@tuwaio/siwx-react`.
+     * Optional Sign-In With X (SIWX) session state, for example the result of `useSiwxSession()` from
+     * `@tuwaio/siwx-react`. The watcher is restarted when one of its fields changes.
      */
     siwx?: SatelliteSiwxState;
     /**
-     * @deprecated Legacy SIWE prop alias for backwards compatibility
+     * Legacy SIWE state, used only when `siwx` is not passed.
+     *
+     * @deprecated Pass `siwx` instead.
      */
     siwe?: {
+        /** Whether the user rejected the sign-in or it failed. */
         isRejected?: boolean;
+        /** Whether the user is signed in. */
         isSignedIn?: boolean;
+        /** Whether sign-in is enabled. `false` turns off the disconnect on rejection. */
         enabled?: boolean;
     };
 }
 /**
- * A dynamic version of the EVMConnectorsWatcher component that avoids static imports.
- * This component dynamically imports the dependencies only when they are available.
+ * Headless component that keeps the Satellite Connect store in sync with wagmi. Render it once inside
+ * `SatelliteConnectProvider`, next to an EVM adapter created with the same `wagmiConfig`.
  *
- * @param props - The component's props. See {@link EVMConnectorsWatcherProps} for details.
- * @returns {null} This component does not render any UI.
+ * After mount it loads `@tuwaio/satellite-evm` with a dynamic import and runs its `createEVMConnectionsWatcher`: account
+ * and network changes made in the wallet update the active connection, a wallet disconnect removes it, and with `siwx`
+ * the connection is disconnected when the SIWX sign-in is rejected or fails, or when the account or chain no longer
+ * matches the signed-in session. The watcher restarts when `wagmiConfig`, a field of `siwx`, the active connector or
+ * the connection error changes, and stops on unmount. If the import fails, a warning is logged and nothing is watched.
+ *
+ * @param props - The component props. See {@link EVMConnectorsWatcherProps}.
+ * @returns `null`; the component renders nothing.
  *
  * @example
  * ```tsx
- * import { useSiwxSession } from '@tuwaio/siwx-react';
  * import { EVMConnectorsWatcher } from '@tuwaio/satellite-react/evm';
+ * import { useSiwxSession } from '@tuwaio/siwx-react';
+ * import type { Config } from '@wagmi/core';
  *
- * function WatcherContainer() {
+ * export function WatcherContainer({ wagmiConfig }: { wagmiConfig: Config }) {
  *   const siwxSession = useSiwxSession();
  *   return <EVMConnectorsWatcher wagmiConfig={wagmiConfig} siwx={siwxSession} />;
  * }
  * ```
- *
- * @remarks
- * Monitors Wagmi account and network changes. Automatically disconnects wallet state if SIWX
- * session validation fails or is rejected.
  */
 declare function EVMConnectorsWatcher(props: EVMConnectorsWatcherProps): react.JSX.Element | null;
 
+/**
+ * The EVM watcher component, imported from `@tuwaio/satellite-react/evm`. Importing this entry point also adds
+ * `EVMConnection` and `ConnectorEVM` from `@tuwaio/satellite-evm` to `AllConnections` and `AllConnectors`.
+ *
+ * @module evm
+ */
+
 declare module '@tuwaio/satellite-react' {
     interface AllConnections {
+        /** EVM connections (`EVMConnection` from `@tuwaio/satellite-evm`), added by `@tuwaio/satellite-react/evm`. */
         [OrbitAdapter.EVM]: EVMConnection;
     }
     interface AllConnectors {
+        /** wagmi connectors (`ConnectorEVM` from `@tuwaio/satellite-evm`), added by `@tuwaio/satellite-react/evm`. */
         [OrbitAdapter.EVM]: ConnectorEVM;
     }
 }

package/dist/evm/index.js

@@ -1 +1 @@
-import'../chunk-UDS7MUYZ.js';import {b}from'../chunk-EYVLQZ24.js';import {useState,useEffect}from'react';import {jsx}from'react/jsx-runtime';function V(t){let[r,f]=useState(null);return useEffect(()=>{(async()=>{try{let n=!1,i=null;try{let[c]=await Promise.all([import('@tuwaio/satellite-evm'),import('@wagmi/core'),import('viem')]);i=c.createEVMConnectionsWatcher,n=!0;}catch{n=!1;}if(n){let c=()=>{let a=b(e=>e.activeConnection),l=b(e=>e.disconnect),s=b(e=>e.connectionError),C=b(e=>e.updateActiveConnection);return useEffect(()=>i({wagmiConfig:t.wagmiConfig,siwx:t.siwx,siwe:t.siwe},{activeConnection:a,disconnect:l,connectionError:s,updateActiveConnection:C}),[a?.connectorType,t.siwx,t.siwe,s,t.wagmiConfig,l,C]),null};f(()=>c);}}catch(n){console.warn("Failed to load EVM watcher:",n);}})();},[]),r?jsx(r,{...t}):null}export{V as EVMConnectorsWatcher};
+import {a as a$1}from'../chunk-FBHCKH6M.js';import {b,a}from'../chunk-4A4PSLAK.js';import {useState,useEffect,useContext,useMemo}from'react';import {jsx}from'react/jsx-runtime';function g({createWatcher:c,wagmiConfig:o,siwx:i,siwe:e}){let n=b(t=>t.activeConnection),a$2=b(t=>t.disconnect),s=b(t=>t.connectionError),l=b(t=>t.updateActiveConnection),C=useContext(a),p=a$1(i),d=e!==void 0,f=e?.enabled,u=e?.isSignedIn,S=e?.isRejected,m=useMemo(()=>d?{enabled:f,isSignedIn:u,isRejected:S}:void 0,[d,f,u,S]);return useEffect(()=>c({wagmiConfig:o,siwx:p,siwe:m},{disconnect:a$2,updateActiveConnection:l,getState:()=>C?.getState()??{activeConnection:n,connectionError:s}}),[c,C,o,p,m,n?.connectorType,s,a$2,l]),null}function R(c){let[o,i]=useState(null);return useEffect(()=>{let e=true;return import('@tuwaio/satellite-evm').then(n=>{e&&i(()=>n.createEVMConnectionsWatcher);}).catch(n=>console.warn("Failed to load EVM watcher:",n)),()=>{e=false;}},[]),o?jsx(g,{createWatcher:o,...c}):null}export{R as EVMConnectorsWatcher};

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var chunkYTP4ADBV_cjs=require('./chunk-YTP4ADBV.cjs'),chunkG2YC6JBO_cjs=require('./chunk-G2YC6JBO.cjs');Object.defineProperty(exports,"SatelliteConnectProvider",{enumerable:true,get:function(){return chunkYTP4ADBV_cjs.b}});Object.defineProperty(exports,"useInitializeAutoConnect",{enumerable:true,get:function(){return chunkYTP4ADBV_cjs.a}});Object.defineProperty(exports,"SatelliteStoreContext",{enumerable:true,get:function(){return chunkG2YC6JBO_cjs.a}});Object.defineProperty(exports,"useSatelliteConnectStore",{enumerable:true,get:function(){return chunkG2YC6JBO_cjs.b}});
+'use strict';var chunkHEG6FP5Z_cjs=require('./chunk-HEG6FP5Z.cjs'),react=require('react'),satelliteCore=require('@tuwaio/satellite-core'),jsxRuntime=require('react/jsx-runtime');var a=({initializeAutoConnect:n,onError:r})=>{let e=react.useEffectEvent(async()=>n()),t=react.useEffectEvent(o=>{(r??(s=>console.error("Failed to initialize auto connect:",s)))(o);});react.useEffect(()=>{e().catch(o=>t(o));},[]);};function g({children:n,autoConnect:r,adapter:e,callbackAfterConnected:t}){let o=react.useMemo(()=>satelliteCore.createSatelliteConnectStore({adapter:e,callbackAfterConnected:t}),[]);return react.useEffect(()=>{o.getState().updateParameters({adapter:e,callbackAfterConnected:t});},[o,e,t]),a({initializeAutoConnect:()=>o.getState().initializeAutoConnect(r??false)}),jsxRuntime.jsx(chunkHEG6FP5Z_cjs.a.Provider,{value:o,children:n})}Object.defineProperty(exports,"SatelliteStoreContext",{enumerable:true,get:function(){return chunkHEG6FP5Z_cjs.a}});Object.defineProperty(exports,"useSatelliteConnectStore",{enumerable:true,get:function(){return chunkHEG6FP5Z_cjs.b}});exports.SatelliteConnectProvider=g;exports.useInitializeAutoConnect=a;