request-iframe 0.0.2 → 0.0.4

package/README.md

@@ -34,6 +34,13 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
   - [Trace Mode](#trace-mode)
   - [Internationalization](#internationalization)
 - [API Reference](#api-reference)
+- [React Hooks](#react-hooks)
+  - [useClient](#useclienttargetfnorref-options-deps)
+  - [useServer](#useserveroptions-deps)
+  - [useServerHandler](#useserverhandlerserver-path-handler-deps)
+  - [useServerHandlerMap](#useserverhandlermapserver-map-deps)
+  - [Complete Example](#complete-example)
+  - [Best Practices](#best-practices)
 - [Error Handling](#error-handling)
 - [FAQ](#faq)
 - [Development](#development)
@@ -67,7 +74,7 @@ In micro-frontend and iframe nesting scenarios, parent-child page communication
 - ⏱️ **Smart Timeout** - Three-stage timeout (connection/sync/async), automatically detects long tasks
 - 📦 **TypeScript** - Complete type definitions and IntelliSense
 - 🔒 **Message Isolation** - secretKey mechanism prevents message cross-talk between multiple instances
-- 📁 **File Transfer** - Support for base64-encoded file sending
+- 📁 **File Transfer** - Support for file sending via stream (client→server)
 - 🌊 **Streaming** - Support for large file chunked transfer, supports async iterators
 - 🌍 **Internationalization** - Error messages can be customized for i18n
 - ✅ **Protocol Versioning** - Built-in version control for upgrade compatibility
@@ -136,7 +143,8 @@ In micro-frontend architecture, the main application needs to communicate with c
 const client = requestIframeClient(iframe, { secretKey: 'main-app' });
 
 // Get user info from child application
-const userInfo = await client.send('/api/user/info', {});
+const userInfoResponse = await client.send('/api/user/info', {});
+console.log(userInfoResponse.data); // User info data
 
 // Notify child application to refresh data
 await client.send('/api/data/refresh', { timestamp: Date.now() });
@@ -180,7 +188,8 @@ server.on('/api/data', async (req, res) => {
 
 // Parent page (cross-origin)
 const client = requestIframeClient(iframe, { secretKey: 'data-api' });
-const data = await client.send('/api/data', {}); // Successfully fetch cross-origin data
+const response = await client.send('/api/data', {});
+const data = response.data; // Successfully fetch cross-origin data
 ```
 
 ### File Preview and Download
@@ -202,8 +211,8 @@ server.on('/api/processFile', async (req, res) => {
 
 // Parent page: download file
 const response = await client.send('/api/processFile', { fileId: '123' });
-if (response.fileData) {
-  downloadFile(response.fileData);
+if (response.data instanceof File || response.data instanceof Blob) {
+  downloadFile(response.data);
 }
 ```
 
@@ -251,7 +260,7 @@ request-iframe uses a three-stage timeout strategy to intelligently adapt to dif
 
 ```typescript
 client.send('/api/getData', data, {
-  ackTimeout: 500,        // Stage 1: ACK timeout (default 500ms)
+  ackTimeout: 1000,       // Stage 1: ACK timeout (default 1000ms)
   timeout: 5000,          // Stage 2: Request timeout (default 5s)
   asyncTimeout: 120000    // Stage 3: Async request timeout (default 120s)
 });
@@ -291,7 +300,7 @@ Send REQUEST
 
 | Stage | Timeout | Scenario |
 |-------|---------|----------|
-| ackTimeout | Short (500ms) | Quickly detect if Server is online, avoid long waits for unreachable iframes |
+| ackTimeout | Short (1000ms) | Quickly detect if Server is online, avoid long waits for unreachable iframes. Increased from 500ms to accommodate slower environments or busy browsers |
 | timeout | Medium (5s) | Suitable for simple synchronous processing, like reading data, parameter validation |
 | asyncTimeout | Long (120s) | Suitable for complex async operations, like file processing, batch operations, third-party API calls |
 
@@ -471,10 +480,12 @@ server.on('/api/logout', (req, res) => {
 await client.send('/api/login', { username: 'tom', password: '123' });
 
 // Client side: Subsequent request to /api/getUserInfo (automatically carries authToken and userId)
-const userInfo = await client.send('/api/getUserInfo', {});
+const userInfoResponse = await client.send('/api/getUserInfo', {});
+const userInfo = userInfoResponse.data;
 
 // Client side: Request root path (only carries userId, because authToken's path is /api)
-const rootData = await client.send('/other', {});
+const rootResponse = await client.send('/other', {});
+const rootData = rootResponse.data;
 ```
 
 #### Client Cookie Management API
@@ -533,6 +544,8 @@ server.on('/api/data', (req, res) => {
 
 ### File Transfer
 
+#### Server → Client (Server sends file to client)
+
 ```typescript
 // Server side: Send file
 server.on('/api/download', async (req, res) => {
@@ -549,32 +562,60 @@ server.on('/api/download', async (req, res) => {
 
 // Client side: Receive
 const response = await client.send('/api/download', {});
-if (response.fileData) {
-  const { content, mimeType, fileName } = response.fileData;
-  
-  // content is base64-encoded string
-  const binaryString = atob(content);
-  const blob = new Blob([binaryString], { type: mimeType });
+if (response.data instanceof File || response.data instanceof Blob) {
+  const file = response.data instanceof File ? response.data : null;
+  const fileName = file?.name || 'download';
   
-  // Download file
-  const url = URL.createObjectURL(blob);
+  // Download file directly using File/Blob
+  const url = URL.createObjectURL(response.data);
   const a = document.createElement('a');
   a.href = url;
-  a.download = fileName || 'download';
+  a.download = fileName;
   a.click();
+  URL.revokeObjectURL(url);
 }
 ```
 
+#### Client → Server (Client sends file to server)
+
+Client sends file via stream only. Use `sendFile()` (or `send(path, file)`); server receives either `req.body` as File/Blob when `autoResolve: true` (default), or `req.stream` as `IframeFileReadableStream` when `autoResolve: false`.
+
+```typescript
+// Client side: Send file (stream, autoResolve defaults to true)
+const file = new File(['Hello Upload'], 'upload.txt', { type: 'text/plain' });
+const response = await client.send('/api/upload', file);
+
+// Or use sendFile explicitly
+const blob = new Blob(['binary data'], { type: 'application/octet-stream' });
+const response2 = await client.sendFile('/api/upload', blob, {
+  fileName: 'data.bin',
+  mimeType: 'application/octet-stream',
+  autoResolve: true  // optional, default true: server gets File/Blob in req.body
+});
+
+// Server side: Receive file (autoResolve true → req.body is File/Blob)
+server.on('/api/upload', async (req, res) => {
+  const blob = req.body as Blob;  // or File when client sent File
+  const text = await blob.text();
+  console.log('Received file content:', text);
+  res.send({ success: true, size: blob.size });
+});
+```
+
+**Note:** When using `client.send()` with a `File` or `Blob`, it automatically dispatches to `client.sendFile()`, which sends the file via stream. Server gets `req.body` as File/Blob when `autoResolve` is true (default), or `req.stream` / `req.body` as `IframeFileReadableStream` when `autoResolve` is false.
+
 ### Streaming
 
 For large files or scenarios requiring chunked transfer, you can use streaming:
 
+#### Server → Client (Server sends stream to client)
+
 ```typescript
 import { 
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
-  isIframeFileStream 
+  isIframeFileReadableStream 
 } from 'request-iframe';
 
 // Server side: Send data stream using iterator
@@ -622,6 +663,55 @@ if (isIframeReadableStream(response.stream)) {
 }
 ```
 
+#### Client → Server (Client sends stream to server)
+
+```typescript
+import { IframeWritableStream } from 'request-iframe';
+
+// Client side: Send stream to server
+const stream = new IframeWritableStream({
+  chunked: true,
+  iterator: async function* () {
+    for (let i = 0; i < 5; i++) {
+      yield `Chunk ${i}`;
+      await new Promise(r => setTimeout(r, 50));
+    }
+  }
+});
+
+// Use sendStream to send stream as request body
+const response = await client.sendStream('/api/uploadStream', stream);
+console.log('Upload result:', response.data);
+
+// Or use send() - it automatically dispatches to sendStream for IframeWritableStream
+const stream2 = new IframeWritableStream({
+  next: async () => ({ data: 'single chunk', done: true })
+});
+const response2 = await client.send('/api/uploadStream', stream2);
+
+// Server side: Receive stream
+server.on('/api/uploadStream', async (req, res) => {
+  // req.stream is available when client sends stream
+  if (req.stream) {
+    const chunks: string[] = [];
+    
+    // Read stream chunk by chunk
+    for await (const chunk of req.stream) {
+      chunks.push(chunk);
+      console.log('Received chunk:', chunk);
+    }
+    
+    res.send({ 
+      success: true, 
+      chunkCount: chunks.length,
+      chunks 
+    });
+  } else {
+    res.status(400).send({ error: 'Expected stream body' });
+  }
+});
+```
+
 **Stream Types:**
 
 | Type | Description |
@@ -712,7 +802,7 @@ Create a Client instance.
 | `target` | `HTMLIFrameElement \| Window` | Target iframe element or window object |
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
-| `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 500 |
+| `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Global default request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Global default async timeout (ms), default 120000 |
 
@@ -728,7 +818,7 @@ Create a Server instance.
 |-----------|------|-------------|
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
-| `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 5000 |
+| `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 1000 |
 
 **Returns:** `RequestIframeServer`
 
@@ -736,15 +826,15 @@ Create a Server instance.
 
 #### client.send(path, body?, options?)
 
-Send a request.
+Send a request. Automatically dispatches to `sendFile()` or `sendStream()` based on body type.
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `path` | `string` | Request path |
-| `body` | `object` | Request data (optional) |
-| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 500 |
+| `body` | `any` | Request data (optional). Can be plain object, File, Blob, or IframeWritableStream. Automatically dispatches: File/Blob → `sendFile()`, IframeWritableStream → `sendStream()` |
+| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
 | `options.headers` | `object` | Request headers (optional) |
@@ -755,20 +845,78 @@ Send a request.
 
 ```typescript
 interface Response<T = any> {
-  data: T;                    // Response data
+  data: T;                    // Response data (File/Blob for auto-resolved file streams)
   status: number;             // Status code
   statusText: string;         // Status text
   requestId: string;          // Request ID
   headers?: Record<string, string | string[]>;  // Response headers (Set-Cookie is array)
-  fileData?: {                // File data (if any)
-    content: string;          // base64-encoded content
-    mimeType?: string;
-    fileName?: string;
-  };
   stream?: IIframeReadableStream<T>;  // Stream response (if any)
 }
 ```
 
+**Examples:**
+
+```typescript
+// Send plain object (auto Content-Type: application/json)
+await client.send('/api/data', { name: 'test' });
+
+// Send string (auto Content-Type: text/plain)
+await client.send('/api/text', 'Hello');
+
+// Send File/Blob (auto-dispatches to sendFile)
+const file = new File(['content'], 'test.txt');
+await client.send('/api/upload', file);
+
+// Send stream (auto-dispatches to sendStream)
+const stream = new IframeWritableStream({ iterator: async function* () { yield 'data'; } });
+await client.send('/api/uploadStream', stream);
+```
+
+#### client.sendFile(path, content, options?)
+
+Send file as request body (via stream; server receives File/Blob when autoResolve is true).
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | Request path |
+| `content` | `string \| Blob \| File` | File content to send |
+| `options.mimeType` | `string` | File MIME type (optional, uses content.type if available) |
+| `options.fileName` | `string` | File name (optional) |
+| `options.autoResolve` | `boolean` | If true (default), server receives File/Blob in `req.body`; if false, server gets `req.stream` / `req.body` as `IframeFileReadableStream` |
+| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
+| `options.timeout` | `number` | Request timeout (ms), default 5000 |
+| `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.headers` | `object` | Request headers (optional) |
+| `options.cookies` | `object` | Request cookies (optional) |
+| `options.requestId` | `string` | Custom request ID (optional) |
+
+**Returns:** `Promise<Response>`
+
+**Note:** The file is sent via stream. When `autoResolve` is true (default), the server receives `req.body` as File/Blob; when false, the server receives `req.stream` / `req.body` as `IframeFileReadableStream`.
+
+#### client.sendStream(path, stream, options?)
+
+Send stream as request body (server receives readable stream).
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | Request path |
+| `stream` | `IframeWritableStream` | Writable stream to send |
+| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
+| `options.timeout` | `number` | Request timeout (ms), default 5000 |
+| `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.headers` | `object` | Request headers (optional) |
+| `options.cookies` | `object` | Request cookies (optional) |
+| `options.requestId` | `string` | Custom request ID (optional) |
+
+**Returns:** `Promise<Response>`
+
+**Note:** On the server side, the stream is available as `req.stream` (an `IIframeReadableStream`). You can iterate over it using `for await (const chunk of req.stream)`.
+
 #### client.isConnect()
 
 Detect if Server is reachable.
@@ -804,6 +952,71 @@ Register route handler.
 type ServerHandler = (req: ServerRequest, res: ServerResponse) => any | Promise<any>;
 ```
 
+**ServerRequest interface:**
+
+```typescript
+interface ServerRequest {
+  body: any;                    // Request body (plain data, or File/Blob when client sendFile with autoResolve true)
+  stream?: IIframeReadableStream; // Request stream (when client sends via sendStream or sendFile with autoResolve false)
+  headers: Record<string, string>; // Request headers
+  cookies: Record<string, string>;  // Request cookies
+  path: string;                 // Request path
+  params: Record<string, string>; // Path parameters extracted from route pattern (e.g., { id: '123' } for '/api/users/:id' and '/api/users/123')
+  requestId: string;            // Request ID
+  origin: string;               // Sender origin
+  source: Window;                // Sender window
+  res: ServerResponse;          // Response object
+}
+```
+
+**Note:** 
+- When client sends a file via `sendFile()` (or `send(path, file)`), the file is sent via stream. If `autoResolve` is true (default), `req.body` is the resolved File/Blob; if false, `req.stream` / `req.body` is an `IIframeReadableStream` (e.g. `IframeFileReadableStream`).
+- When client sends a stream via `sendStream()`, `req.stream` is available as an `IIframeReadableStream`. You can iterate over it using `for await (const chunk of req.stream)`.
+- **Path parameters**: You can use Express-style route parameters (e.g., `/api/users/:id`) to extract path segments. The extracted parameters are available in `req.params`. For example, registering `/api/users/:id` and receiving `/api/users/123` will set `req.params.id` to `'123'`.
+
+**Path Parameters Example:**
+
+```typescript
+// Register route with parameter
+server.on('/api/users/:id', (req, res) => {
+  const userId = req.params.id; // '123' when path is '/api/users/123'
+  res.send({ userId });
+});
+
+// Multiple parameters
+server.on('/api/users/:userId/posts/:postId', (req, res) => {
+  const { userId, postId } = req.params;
+  res.send({ userId, postId });
+});
+```
+
+**Handler return value behavior**
+
+- If your handler **does not call** `res.send()` / `res.json()` / `res.sendFile()` / `res.sendStream()`, but it **returns a value that is not `undefined`**, then the server will treat it as a successful result and automatically send it back to the client (equivalent to `res.send(returnValue)`).
+- For **async handlers** (`Promise`): if the promise **resolves to a value that is not `undefined`** and no response has been sent yet, it will also be auto-sent.
+- If the handler (or resolved promise) returns `undefined` **and** no response method was called, the server will respond with error code `NO_RESPONSE`.
+
+Examples:
+
+```typescript
+// Sync: auto-send return value
+server.on('/api/hello', () => {
+  return { message: 'hello' };
+});
+
+// Async: auto-send resolved value
+server.on('/api/user', async (req) => {
+  const user = await getUser(req.body.userId);
+  return user; // auto-send if not undefined
+});
+
+// If you manually send, return value is ignored
+server.on('/api/manual', (req, res) => {
+  res.send({ ok: true });
+  return { ignored: true };
+});
+```
+
 #### server.off(path)
 
 Remove route handler.
@@ -840,6 +1053,259 @@ Destroy Server instance, remove all listeners.
 
 ---
 
+## React Hooks
+
+request-iframe provides React hooks for easy integration in React applications. Import hooks from `request-iframe/react`:
+
+```typescript
+import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
+```
+
+### useClient(targetFnOrRef, options?, deps?)
+
+React hook for using request-iframe client.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetFnOrRef` | `(() => HTMLIFrameElement \| Window \| null) \| RefObject<HTMLIFrameElement \| Window>` | Function that returns iframe element or Window object, or a React ref object |
+| `options` | `RequestIframeClientOptions` | Client options (optional) |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-creating client when dependencies change) |
+
+**Returns:** `RequestIframeClient | null`
+
+**Example:**
+
+```tsx
+import { useClient } from 'request-iframe/react';
+import { useRef } from 'react';
+
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+
+  const handleClick = async () => {
+    if (client) {
+      const response = await client.send('/api/data', { id: 1 });
+      console.log(response.data);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={handleClick}>Send Request</button>
+    </div>
+  );
+};
+```
+
+**Using function instead of ref:**
+
+```tsx
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(() => iframeRef.current, { secretKey: 'my-app' });
+  // ...
+};
+```
+
+### useServer(options?, deps?)
+
+React hook for using request-iframe server.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `RequestIframeServerOptions` | Server options (optional) |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-creating server when dependencies change) |
+
+**Returns:** `RequestIframeServer | null`
+
+**Example:**
+
+```tsx
+import { useServer } from 'request-iframe/react';
+
+const MyComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+
+  useEffect(() => {
+    if (!server) return;
+
+    const off = server.on('/api/data', (req, res) => {
+      res.send({ data: 'Hello' });
+    });
+
+    return off; // Cleanup on unmount
+  }, [server]);
+
+  return <div>Server Component</div>;
+};
+```
+
+### useServerHandler(server, path, handler, deps?)
+
+React hook for registering a single server handler with automatic cleanup and closure handling.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `RequestIframeServer \| null` | Server instance (from `useServer`) |
+| `path` | `string` | Route path |
+| `handler` | `ServerHandler` | Handler function |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-registering when dependencies change) |
+
+**Example:**
+
+```tsx
+import { useServer, useServerHandler } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Handler automatically uses latest userId value
+  useServerHandler(server, '/api/user', (req, res) => {
+    res.send({ userId, data: 'Hello' });
+  }, [userId]); // Re-register when userId changes
+
+  return <div>Server Component</div>;
+};
+```
+
+**Key Features:**
+- Automatically handles closure issues - always uses latest values from dependencies
+- Automatically unregisters handler on unmount or when dependencies change
+- No need to manually manage handler registration/cleanup
+
+### useServerHandlerMap(server, map, deps?)
+
+React hook for registering multiple server handlers at once with automatic cleanup.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `RequestIframeServer \| null` | Server instance (from `useServer`) |
+| `map` | `Record<string, ServerHandler>` | Map of route paths and handler functions |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-registering when dependencies change) |
+
+**Example:**
+
+```tsx
+import { useServer, useServerHandlerMap } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Register multiple handlers at once
+  useServerHandlerMap(server, {
+    '/api/user': (req, res) => {
+      res.send({ userId, data: 'User data' });
+    },
+    '/api/posts': (req, res) => {
+      res.send({ userId, data: 'Posts data' });
+    }
+  }, [userId]); // Re-register all handlers when userId changes
+
+  return <div>Server Component</div>;
+};
+```
+
+**Key Features:**
+- Batch registration of multiple handlers
+- Automatically handles closure issues - always uses latest values from dependencies
+- Automatically unregisters all handlers on unmount or when dependencies change
+- Efficient - only re-registers when map keys change
+
+### Complete Example
+
+Here's a complete example showing how to use React hooks in a real application:
+
+```tsx
+import { useClient, useServer, useServerHandler } from 'request-iframe/react';
+import { useRef, useState } from 'react';
+
+// Parent Component (Client)
+const ParentComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+  const [data, setData] = useState(null);
+
+  const fetchData = async () => {
+    if (!client) return;
+    
+    try {
+      const response = await client.send('/api/data', { id: 1 });
+      setData(response.data);
+    } catch (error) {
+      console.error('Request failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={fetchData}>Fetch Data</button>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+};
+
+// Iframe Component (Server)
+const IframeComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+  const [userId, setUserId] = useState(1);
+
+  // Register handler with automatic cleanup
+  useServerHandler(server, '/api/data', async (req, res) => {
+    // Handler always uses latest userId value
+    const userData = await fetchUserData(userId);
+    res.send(userData);
+  }, [userId]);
+
+  return (
+    <div>
+      <p>User ID: {userId}</p>
+      <button onClick={() => setUserId(userId + 1)}>Increment</button>
+    </div>
+  );
+};
+```
+
+### Best Practices
+
+1. **Always check for null**: Client and server hooks may return `null` initially or when target is unavailable:
+   ```tsx
+   const client = useClient(iframeRef);
+   if (!client) return null; // Handle null case
+   ```
+
+2. **Use dependency arrays**: Pass dependencies to hooks to ensure handlers use latest values:
+   ```tsx
+   useServerHandler(server, '/api/data', (req, res) => {
+     res.send({ userId }); // Always uses latest userId
+   }, [userId]); // Re-register when userId changes
+   ```
+
+3. **Cleanup is automatic**: Hooks automatically clean up on unmount, but you can also manually unregister:
+   ```tsx
+   useEffect(() => {
+     if (!server) return;
+     const off = server.on('/api/data', handler);
+     return off; // Manual cleanup (optional, hooks do this automatically)
+   }, [server]);
+   ```
+
+---
+
 ## Error Handling
 
 ### Error Codes