docs: refresh developer guides

docs/astro.config.mjs

@@ -175,6 +175,10 @@ export default defineConfig({
           ecTwoSlash({
             twoslashOptions: {
               lib: ['esnext', 'dom'],
+              compilerOptions: {
+                jsx: 4, // react-jsx
+                jsxImportSource: 'react',
+              },
             },
           }),
         ],

docs/package.json

@@ -11,11 +11,14 @@
   },
   "dependencies": {
     "@filoz/synapse-core": "workspace:*",
+    "@filoz/synapse-react": "workspace:*",
     "@filoz/synapse-sdk": "workspace:*",
     "starlight-auto-sidebar": "^0.1.3",
     "starlight-changelogs": "^0.4.0",
     "starlight-links-validator": "^0.19.2",
-    "viem": "catalog:"
+    "viem": "catalog:",
+    "wagmi": "catalog:",
+    "@tanstack/react-query": "5.x"
   },
   "devDependencies": {
     "@astrojs/starlight": "^0.37.5",

docs/src/content/docs/developer-guides/components.mdx

@@ -1,109 +1,64 @@
 ---
 title: Components
-description: Learn about the Synapse SDK architecture and components.
+description: Learn about the available Synapse packages and how they relate.
 sidebar:
   order: 1
 ---
 
-This page describes the components of the Synapse SDK and how they work together. You'll learn how each component can be used independently, how they are organized within the SDK architecture, and how they interact with the underlying smart contracts and storage providers.
+This page describes the available Synapse packages and how to choose the one that fits your use case.
 
-The SDK is built from these core components:
+## Packages
 
-- **`Synapse`** - Main SDK entry point with simple, high-level API
-- **`PaymentsService`** - SDK client for managing deposits, approvals, and payment rails (interacts with Filecoin Pay contract)
-- **`StorageManager`**, **`StorageContext`** - Storage operation classes
-- **`WarmStorageService`** - SDK client for storage coordination and pricing (interacts with WarmStorage contract)
+| Package | Best For |
+|---------|----------|
+| **[Synapse SDK](/developer-guides/synapse/)** | CLI tools, scripts, Node.js backends |
+| **[Synapse Core](/developer-guides/synapse-core/)** | Fine-grained control, custom integrations |
+| **[Synapse React](/developer-guides/react-integration/)** | React applications |
 
-The following diagram illustrates how these components relate to each other and the external systems they interact with:
+The packages form three layers:
 
-```mermaid
-graph LR
-    subgraph "Public API"
-        Synapse
-    end
-
-    subgraph "Payment Services"
-        PS[PaymentsService]
-    end
-
-    subgraph "Storage Services"
-        SM[StorageManager]
-    end
-
-    subgraph "Lower-Level"
-        WSS[WarmStorageService]
-        SC[StorageContext]
-    end
-    Synapse --> SM
-    Synapse --> PS
-    SM --> SC
-    SM --> WSS
-    PS --> SC
-```
-
-The SDK architecture is guided by several key principles that ensure maintainability, flexibility, and ease of use:
-
-**Design Principles**:
-
-- **Separation of Concerns**: Protocol, business logic, and application layers are distinct
-- **Composability**: Each component can be used independently or together
-- **Abstraction**: SDK hides blockchain complexity from applications
-- **Verification**: All storage backed by cryptographic proofs
-
-## SDK Components
-
-The SDK is organized into three layers, each serving a specific purpose:
-
-- **High-Level API**: The `Synapse` class provides a simple interface for common operations.
-- **Service Layer**: `PaymentsService` and `StorageManager` handle domain-specific logic.
-- **Lower-Level Clients**: Direct access to contracts and providers for advanced use cases.
-
-### Synapse
-
-**Purpose**: Main SDK entry point with simple, high-level API
-
-**API Reference**: [Synapse API Reference](/reference/filoz/synapse-sdk/synapse/classes/synapse/)
-
-### PaymentsService
-
-The PaymentsService provides direct access to the Filecoin Pay contract, enabling you to:
-
-- Manage token deposits and withdrawals
-- Approve operators for automated payments
-- Query and settle payment rails
-- Monitor account health and balance
+1. **Core** - Composable modules for each filecoin onchain cloud operation. Both the SDK and React packages build on Core.
+2. **SDK** - Wraps Core into a single `Synapse` entry point that manages payments, storage, and provider discovery.
+3. **React** - Wraps Core into React hooks.
 
-This is your primary interface for all payment-related operations in the SDK.
+## Synapse SDK
 
-**API Reference**: [PaymentsService API Reference](/reference/filoz/synapse-sdk/payments/classes/paymentsservice/)
+**Synapse SDK** is the recommended starting point. A single `Synapse` class coordinates payments, storage, provider discovery, and session keys behind a high-level API.
 
-Check out the [Payment Operations](/developer-guides/payments/payment-operations/) guide for more details.
+- **Payments**: Deposits, withdrawals, operator approvals ([Payments Operations Guide →](/developer-guides/payments/payment-operations/))
+- **Storage**: Upload and download files to storage providers ([Storage Operations Guide →](/developer-guides/storage/storage-operations/))
+- **Provider Discovery**: Query registered storage providers and products
+- **Session Keys**: Delegate signing authority for automated workflows
 
-### StorageManager
+[**Synapse SDK Guide →**](/developer-guides/synapse/)
 
-**Purpose**: High-level, auto-managed storage operations - upload and download data to and from the Filecoin Onchain Cloud.
+[**Synapse SDK Reference →**](/reference/filoz/synapse-sdk/toc/)
 
-**API Reference**: [StorageManager API Reference](/reference/filoz/synapse-sdk/storage/classes/storagemanager/)
+## Synapse Core
 
-Check out the [Storage Operations](/developer-guides/storage/storage-operations/) guide for more details.
+**Synapse Core** is a low-level building blocks that the SDK and React packages build on. Use when you need direct control over individual operations.
 
-### StorageContext
+- **Contract functions** - Filecoin Pay, Warm Storage, PDP Verifier, Service Provider Registry
+- **Storage provider HTTP API**: Data set creation, piece uploads, deletions
+- **PieceCID utilities** - Calculate, parse, and validate piece identifiers
+- **EIP-712 typed data** - Sign operations for data set and piece management
+- **Chain configuration** - Mainnet, calibration, and devnet definitions
 
-**Purpose**: Provider-specific storage operations - upload and download data to and from the Filecoin Onchain Cloud.
+[**Synapse Core Guide →**](/developer-guides/synapse-core/)
 
-**API Reference**: [StorageContext API Reference](/reference/filoz/synapse-sdk/storage/classes/storagecontext/)
+[**Synapse Core Reference →**](/reference/filoz/synapse-core/toc/)
 
-Check out the [Storage Context](/developer-guides/storage/storage-context/) guide for more details.
+## Synapse React
 
-### WarmStorageService
+React hooks for payments, storage, and provider operations. Built on [Wagmi](https://wagmi.sh) and [TanStack Query](https://tanstack.com/query).
 
-**Purpose**: SDK client for storage coordination and pricing - storage pricing and cost calculations, data set management and queries, metadata operations (data sets and pieces), service provider approval management, contract address discovery, data set creation verification.
+[**Synapse React Guide →**](/developer-guides/react-integration/)
 
-**API Reference**: [WarmStorageService API Reference](/reference/filoz/synapse-sdk/warmstorage/classes/warmstorageservice/)
+[**Synapse React Reference →**](/reference/filoz/synapse-react/toc/)
 
 ## Complete Data Flow
 
-This sequence diagram shows the complete lifecycle of a file upload operation, from initialization through verification. Each step represents an actual blockchain transaction or API call.
+The sequence below shows the complete lifecycle of a file upload — from initialization through on-chain verification.
 
 ```mermaid
 sequenceDiagram
@@ -158,16 +113,17 @@ sequenceDiagram
 
 Choose your learning path based on your immediate needs:
 
-### Ready to Build?
+#### Ready to Build?
 
 Jump straight to code with the [**Getting Started Guide →**](/getting-started/)
 
 - [**Storage Operations →**](/developer-guides/storage/storage-operations/) - Upload and download your first file
 - [**Storage Context →**](/developer-guides/storage/storage-context/) - Advanced storage operations and batch uploads
 - [**Payment Operations →**](/developer-guides/payments/payment-operations/) - Fund your account and manage payments
 - [**Rails & Settlement →**](/developer-guides/payments/rails-settlement/) - Payment mechanics and settlement strategies
+- [**React Integration →**](/developer-guides/react-integration/) - Use Synapse React hooks in your React app
 
-### Want to Learn More?
+#### Want to Learn More?
 
 - [**Architecture →**](/core-concepts/architecture/) - Understanding how all components work together
 - [**PDP Overview →**](/core-concepts/pdp-overview/) - Proof verification and data integrity

docs/src/content/docs/developer-guides/payments/payment-operations.mdx

@@ -58,9 +58,17 @@ await synapse.client.waitForTransactionReceipt({ hash });
 
 If you cannot use permit-based deposits, you can use the traditional two-transaction approach:
 
-```ts
+```ts twoslash
+// @lib: esnext,dom
+import { Synapse, parseUnits } from "@filoz/synapse-sdk";
+import { privateKeyToAccount } from 'viem/accounts'
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+// ---cut---
+const filecoinpay = synapse.chain.contracts.filecoinPay.address
+const amount = parseUnits("100");
+
 // 1. Approve USDFC spending
-await usdfc.approve(paymentAddress, depositAmount);
+await synapse.payments.approve({spender: filecoinpay, amount});
 
 // 2. Deposit
 await synapse.payments.deposit({ amount });