api-ape 1.0.1 → 1.0.2

package/README.md

@@ -1,53 +1,25 @@
 # 🦍 api-ape
 
-**Remote Procedure Events (RPE)** — A lightweight WebSocket framework for real-time APIs.
+[![npm version](https://img.shields.io/npm/v/api-ape.svg)](https://www.npmjs.com/package/api-ape)
+[![license](https://img.shields.io/npm/l/api-ape.svg)](https://github.com/codemeasandwich/api-ape/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/codemeasandwich/api-ape)](https://github.com/codemeasandwich/api-ape/issues)
 
-Call server functions from the browser like local methods. Get real-time broadcasts with zero setup.
-
-```js
-// Client: call server function, get result
-const pets = await ape.pets.list()
-
-// Client: listen for broadcasts
-ape.on('newPet', ({ data }) => console.log('New pet:', data))
-```
-
-file: api/pets/list.js
-```js
-// Server: define function, broadcast to others
-module.exports = function list() {
-  return getPetList()
-}
-```
-
-file: api/pets/newPet.js
-```js
-// Server: define function, broadcast to others
-module.exports = function newPet(data) {
-    // broadcast to all other clients
-  this.broadcastOthers('newPet', data)
-  return savePet(data)
-}
-```
+**Remote Procedure Events (RPE)** — A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods. Get real-time broadcasts with zero setup.
 
 ---
 
-## Features
-
-- **🔌 Auto-wiring** — Drop JS files in a folder, they become API endpoints
-- **📡 Real-time** — Built-in broadcast to all or other clients
-- **🔄 Reconnection** — Client auto-reconnects on disconnect
-- **📦 JJS Encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
-- **🎯 Simple API** — Promise-based calls with chainable paths
-
----
-
-## Installation
+## Install
 
 ```bash
 npm install api-ape
+# or
+pnpm add api-ape
+# or
+yarn add api-ape
 ```
 
+**Requirements:** Node.js 14+ (for server), modern browsers (for client)
+
 ---
 
 ## Quick Start
@@ -66,9 +38,9 @@ ape(app, { where: 'api' })
 app.listen(3000)
 ```
 
-### Controllers
+### Create a Controller
 
-Create files in your `api/` folder. Each export becomes an endpoint:
+Drop a file in your `api/` folder — it automatically becomes an endpoint:
 
 ```js
 // api/hello.js
@@ -77,24 +49,16 @@ module.exports = function(name) {
 }
 ```
 
-```js
-// api/message.js
-module.exports = function(data) {
-  // Broadcast to all OTHER connected clients
-  this.broadcastOthers('message', data)
-  return data
-}
-```
-
 ### Client (Browser)
 
-Include the bundled client:
+Include the bundled client and start calling:
 
 ```html
 <script src="/api/ape.js"></script>
 <script>
-  // Call server functions
-  ape.hello('World').then(result => console.log(result)) // "Hello, World!"
+  // Call server functions like local methods
+  const result = await ape.hello('World')
+  console.log(result) // "Hello, World!"
   
   // Listen for broadcasts
   ape.on('message', ({ data }) => {
@@ -103,6 +67,19 @@ Include the bundled client:
 </script>
 ```
 
+**That's it!** Your server function is now callable from the browser.
+
+---
+
+## Key Concepts
+
+* **Auto-wiring** — Drop JS files in a folder, they become API endpoints automatically
+* **Real-time broadcasts** — Built-in `broadcast()` and `broadcastOthers()` methods for pushing to clients
+* **Promise-based calls** — Chainable paths like `ape.users.list()` map to `api/users/list.js`
+* **Automatic reconnection** — Client auto-reconnects on disconnect with exponential backoff
+* **JJS Encoding** — Extended JSON supporting Date, RegExp, Error, Set, Map, undefined, and circular refs
+* **Connection lifecycle hooks** — Customize behavior on connect, receive, send, error, and disconnect
+
 ---
 
 ## API Reference
@@ -115,8 +92,8 @@ Initialize api-ape on an Express app.
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `where` | `string` | Directory containing controller files |
-| `onConnent` | `function` | Connection lifecycle hook (see below) |
+| `where` | `string` | Directory containing controller files (default: `'api'`) |
+| `onConnent` | `function` | Connection lifecycle hook (see [Connection Lifecycle](#connection-lifecycle)) |
 
 #### Controller Context (`this`)
 
@@ -124,8 +101,8 @@ Inside controller functions, `this` provides:
 
 | Property | Description |
 |----------|-------------|
-| `this.broadcast(type, data)` | Send to ALL connected clients |
-| `this.broadcastOthers(type, data)` | Send to all EXCEPT the caller |
+| `this.broadcast(type, data)` | Send to **ALL** connected clients |
+| `this.broadcastOthers(type, data)` | Send to all **EXCEPT** the caller |
 | `this.online()` | Get count of connected clients |
 | `this.getClients()` | Get array of connected hostIds |
 | `this.hostId` | Unique ID of the calling client |
@@ -133,17 +110,61 @@ Inside controller functions, `this` provides:
 | `this.socket` | WebSocket instance |
 | `this.agent` | Parsed user-agent (browser, OS, device) |
 
-#### Connection Lifecycle
+### Client
+
+#### `ape.<path>.<method>(...args)`
+
+Call a server function. Returns a Promise.
+
+```js
+// Calls api/users/list.js
+const users = await ape.users.list()
+
+// Calls api/users/create.js with data
+const user = await ape.users.create({ name: 'Alice' })
+
+// Nested paths work too
+// ape.admin.users -> api/admin/users.js
+// ape.admin.users.delete -> api/admin/users/delete.js
+await ape.admin.users.delete(userId)
+```
+
+#### `ape.on(type, handler)`
+
+Listen for server broadcasts.
+
+```js
+ape.on('notification', ({ data, err, type }) => {
+  console.log('Received:', data)
+})
+```
+
+---
+
+## Configuration
+
+### Default Options
+
+```js
+ape(app, {
+  where: 'api',           // Controller directory
+  onConnent: undefined    // Lifecycle hook (optional)
+})
+```
+
+### Connection Lifecycle Hook
+
+Customize behavior per connection:
 
 ```js
 ape(app, {
   where: 'api',
-  onConnent(socket, req, send) {
+  onConnent(socket, req, hostId) {
     return {
       // Embed values into `this` for all controllers
       embed: {
         userId: req.session?.userId,
-        clientId: send + '' // hostId as string
+        clientId: String(hostId)
       },
       
       // Before/after hooks
@@ -164,31 +185,81 @@ ape(app, {
 })
 ```
 
-### Client
+---
 
-#### `ape.<path>.<method>(data)`
+## Common Recipes
 
-Call a server function. Returns a Promise.
+### Broadcast to Other Clients
 
 ```js
-// Calls api/users/list.js
-ape.users.list().then(users => ...)
+// api/message.js
+module.exports = function(data) {
+  // Broadcast to all OTHER connected clients (not the sender)
+  this.broadcastOthers('message', data)
+  return { success: true }
+}
+```
 
-// Calls api/users/create.js with data
-ape.users.create({ name: 'Alice' }).then(user => ...)
+### Broadcast to All Clients
 
-// Nested paths work too
-ape.admin.users.delete(userId).then(() => ...)
+```js
+// api/announcement.js
+module.exports = function(announcement) {
+  // Broadcast to ALL connected clients including sender
+  this.broadcast('announcement', announcement)
+  return { sent: true }
+}
 ```
 
-#### `ape.on(type, handler)`
+### Get Online Count
 
-Listen for server broadcasts.
+```js
+// api/stats.js
+module.exports = function() {
+  return {
+    online: this.online(),
+    clients: this.getClients()
+  }
+}
+```
+
+### Access Request Data
 
 ```js
-ape.on('notification', ({ data, err, type }) => {
-  console.log('Received:', data)
-})
+// api/profile.js
+module.exports = function() {
+  // Access original HTTP request
+  const userId = this.req.session?.userId
+  const userAgent = this.agent.browser.name
+  
+  return { userId, userAgent }
+}
+```
+
+### Error Handling
+
+```js
+// api/data.js
+module.exports = async function(id) {
+  try {
+    const data = await fetchData(id)
+    return data
+  } catch (err) {
+    // Errors are automatically sent to client
+    throw new Error(`Failed to fetch: ${err.message}`)
+  }
+}
+```
+
+### Client-Side Error Handling
+
+```js
+try {
+  const result = await ape.data.get(id)
+  console.log(result)
+} catch (err) {
+  console.error('Server error:', err)
+}
 ```
 
 ---
@@ -207,25 +278,143 @@ api-ape uses **JJS (JSON SuperSet)** encoding, which extends JSON to support:
 | `Map` | ✅ Preserved as Map |
 | Circular refs | ✅ Handled via pointers |
 
-This is automatic — send a Date, receive a Date.
+This is automatic — send a Date, receive a Date. No configuration needed.
 
 ---
 
-## Examples
+## Examples & Demos
+
+The repository contains working examples:
 
-See the [`example/`](./example) folder:
+* **`example/ExpressJs/`** — Simple real-time chat app
+  - Minimal setup with Express.js
+  - Broadcast messages to other clients
+  - Message history
 
-- **ExpressJs/** — Simple chat app with broadcast
-- **NextJs/** — Integration with Next.js
+* **`example/NextJs/`** — Production-ready chat application
+  - Custom Next.js server integration
+  - React hooks integration
+  - User presence tracking
+  - Docker support
+  - Connection lifecycle hooks
 
-Run the Express example:
+### Run an Example
 
+**ExpressJs:**
 ```bash
 cd example/ExpressJs
 npm install
 npm start
+# Open http://localhost:3000
+```
+
+**NextJs:**
+```bash
+cd example/NextJs
+npm install
+npm run dev
+# Open http://localhost:3000
+```
+
+Or with Docker:
+```bash
+cd example/NextJs
+docker-compose up --build
+```
+
+---
+
+## Troubleshooting & FAQ
+
+### CORS Errors in Browser
+
+Ensure your Express server allows WebSocket connections from your origin. api-ape uses `express-ws` which handles CORS automatically, but verify your Express CORS middleware allows WebSocket upgrade requests.
+
+### Controller Not Found
+
+* Check that your controller file is in the `where` directory (default: `api/`)
+* Ensure the file exports a function: `module.exports = function(...) { ... }`
+* File paths map directly: `api/users/list.js` → `ape.users.list()`
+
+### Connection Drops Frequently
+
+The client automatically reconnects with exponential backoff. If connections drop often:
+* Check server WebSocket timeout settings
+* Verify network stability
+* Check server logs for errors
+
+### Binary Data / File Uploads
+
+JJS encoding supports complex types, but for large binary data, consider:
+* Sending file URLs instead of raw data
+* Using a separate file upload endpoint
+* Chunking large payloads
+
+### TypeScript Support
+
+Type definitions are included (`index.d.ts`). For full type safety, you may need to:
+* Define interfaces for your controller parameters and return types
+* Use type assertions when calling `ape.<path>.<method>()`
+
+---
+
+## Tests & CI
+
+```bash
+npm test            # Run test suite
+npm run test:watch  # Watch mode
+npm run test:cover  # Coverage report
 ```
 
+**Test Commands:**
+- `npm test` — Run all tests
+- `npm run test:watch` — Watch mode for development
+- `npm run test:cover` — Generate coverage report
+- `npm run test:update` — Update snapshots
+
+**Supported:** Node.js 14+, modern browsers (Chrome, Firefox, Safari, Edge)
+
+---
+
+## Contributing
+
+Contributions welcome! Here's how to help:
+
+1. **Fork the repository**
+2. **Create a branch:** `git checkout -b feature/your-feature-name`
+3. **Make your changes** and add tests
+4. **Run tests:** `npm test`
+5. **Commit:** Follow conventional commit messages
+6. **Push and open a PR** with a clear description
+
+**Guidelines:**
+* Add tests for new features
+* Keep code style consistent
+* Update documentation if needed
+* Ensure all tests pass
+
+---
+
+## Releases / Changelog
+
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+**Current version:** See `package.json` or npm registry
+
+**Release notes:** Check [GitHub releases](https://github.com/codemeasandwich/api-ape/releases) for detailed changelog.
+
+---
+
+## Security
+
+**Reporting vulnerabilities:** Please report security issues via [GitHub Security Advisories](https://github.com/codemeasandwich/api-ape/security/advisories) or email the maintainer.
+
+**Security considerations:**
+* Validate all input in controllers
+* Use authentication/authorization in `onConnent` hooks
+* Sanitize data before broadcasting
+* Keep dependencies up to date
+
 ---
 
 ## Project Structure
@@ -245,7 +434,7 @@ api-ape/
 │   │   ├── receive.js   # Incoming message handler
 │   │   └── send.js      # Outgoing message handler
 │   └── security/
-│       └── reply.js     # Duplicate request protection
+│       └── reply.js      # Duplicate request protection
 ├── utils/
 │   ├── jss.js           # JSON SuperSet encoder/decoder
 │   └── messageHash.js   # Request deduplication
@@ -256,6 +445,14 @@ api-ape/
 
 ---
 
-## License
+## License & Authors
+
+**License:** MIT
+
+**Author:** [Brian Shannon](https://github.com/codemeasandwich)
+
+**Repository:** [github.com/codemeasandwich/api-ape](https://github.com/codemeasandwich/api-ape)
+
+---
 
-MIT © [Brian Shannon](https://github.com/codemeasandwich)
+**Made with 🦍 by the api-ape community**

package/example/NextJs/pages/Info.tsx

@@ -0,0 +1,153 @@
+import styles from '../styles/Chat.module.css'
+
+export default function Info() {
+  return (
+    <div className={styles.codeSection}>
+      <h3 className={styles.codeTitle}>📚 How api-ape Works</h3>
+      
+      <div className={styles.gridContainer}>
+        <div className={styles.gridLayout}>
+          {/* Top Left: Key Concepts */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              💡 Key Concepts
+            </h4>
+            <pre className={styles.code}>
+              {`• Proxy Pattern: api.message() → api/message.js
+• Auto-wiring: Drop files in api/ folder, they become endpoints
+• Promises: All calls return Promises automatically
+• Broadcasts: Use this.broadcast() or this.broadcastOthers()
+• Context: this.broadcast, this.hostId, this.req available in controllers
+• Auto-reconnect: Client reconnects automatically on disconnect`}
+            </pre>
+          </div>
+
+          {/* Top Right: Data Flow */}
+          <div>
+            <h4 className={styles.sectionHeadingLarge}>
+              🔄 Data Flow
+            </h4>
+            <div className={styles.dataFlowGrid}>
+              {/* Column Headers */}
+              <div className={styles.columnHeaderClient}>
+                Client
+              </div>
+              <div className={styles.gridCell}></div>
+              <div className={styles.columnHeaderServer}>
+                Server
+              </div>
+
+              {/* Step 1: Client sends */}
+              <div className={styles.clientBoxSpan3}>
+                api.message(data)
+              </div>
+              <div className={styles.arrowContainerRow2}>
+                <div className={styles.arrowLineSend}></div>
+                <span className={styles.arrowLabelBlue}>Send</span>
+                <div className={styles.arrowHeadRight}></div>
+              </div>
+              <div className={styles.emptyGridCell}></div>
+
+              {/* Step 2: Server receives */}
+              <div className={styles.emptyGridCellRow3}></div>
+              <div className={styles.arrowContainerRow3}>
+                <div className={styles.arrowHeadLeft}></div>
+                <span className={styles.arrowLabelGreen}>Return</span>
+                <div className={styles.arrowLineReturn}></div>
+              </div>
+              <div className={styles.serverBoxSpan2}>
+                api/message.js
+              </div>
+
+              {/* Step 3: Server broadcasts */}
+              <div className={styles.emptyGridCellRow4}></div>
+              <div className={styles.arrowContainerRow4}>
+                <div className={styles.arrowLineBroadcast}></div>
+                <span className={styles.arrowLabelGreen}>Broadcast</span>
+                <div className={styles.arrowHeadRight}></div>
+              </div>
+              <div className={styles.serverBoxSpan3}>
+                Broadcast to others
+              </div>
+
+              {/* Step 4: Other clients receive */}
+              <div className={styles.clientBoxSingle}>
+                Other clients
+              </div>
+              <div className={styles.arrowContainerRow5}>
+                <div className={styles.arrowHeadLeftBlue}></div>
+                <span className={styles.arrowLabelBlue}>Broadcast</span>
+                <div className={styles.arrowLineBroadcastReturn}></div>
+              </div>
+              <div className={styles.emptyGridCellRow5}></div>
+
+            </div>
+          </div>
+
+          {/* Bottom Left: Client-Side */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              🔵 Client-Side (Browser)
+            </h4>
+            <pre className={styles.code}>
+              {`// 1. Initialize api-ape client
+const client = await getApeClient()
+const api = client.sender  // Proxy object
+
+// 2. Call server function - property name = file path
+//    api.message() → calls api/message.js
+api.message({ user: 'Alice', text: 'Hello!' })
+  .then(response => {
+    // Server returned: { ok: true, message: {...} }
+    console.log('Response:', response)
+  })
+  .catch(err => {
+    // Server threw an error
+    console.error('Error:', err)
+  })
+
+// 3. Listen for server broadcasts
+client.setOnReciver('message', ({ data }) => {
+  // Server called: this.broadcastOthers('message', data)
+  // This fires for ALL clients except the sender
+  console.log('Broadcast received:', data.message)
+})`}
+            </pre>
+          </div>
+
+          {/* Bottom Right: Server-Side */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              🟢 Server-Side (api/message.js)
+            </h4>
+            <pre className={styles.code}>
+              {`// File: api/message.js
+// This function is called when client does: api.message(data)
+
+module.exports = function message(data) {
+  const { user, text } = data
+  
+  // Validate input
+  if (!user || !text) {
+    throw new Error('Missing user or text')
+  }
+  
+  const msg = {
+    user,
+    text,
+    time: new Date().toISOString()
+  }
+  
+  // Broadcast to ALL OTHER clients (not the sender)
+  this.broadcastOthers('message', { message: msg })
+  
+  // Return response to sender (fulfills Promise)
+  return { ok: true, message: msg }
+}`}
+            </pre>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/example/NextJs/pages/index.tsx

@@ -1,9 +1,31 @@
+/**
+ * 🦍 api-ape Next.js Chat Example
+ * 
+ * This component demonstrates how to use api-ape in a React/Next.js application:
+ * 
+ * 1. **Client Initialization**: Connect to api-ape WebSocket server
+ * 2. **Proxy Pattern**: Use `client.sender` as a Proxy to call server functions
+ * 3. **Event Listeners**: Listen for server broadcasts using `setOnReciver`
+ * 4. **Promise-based Calls**: Server functions return Promises automatically
+ * 
+ * Server-side: api/message.js handles incoming messages and broadcasts to other clients
+ * Client-side: This component sends messages and receives broadcasts
+ * 
+ * Key api-ape concepts:
+ * - `client.sender` is a Proxy - accessing `sender.message()` calls server function
+ * - Property name (`message`) maps to server file: `api/message.js`
+ * - `setOnReciver(type, handler)` listens for server broadcasts
+ * - All calls return Promises - server response is automatically matched by queryId
+ */
+
 import Head from 'next/head'
 import { useState, useEffect, useRef } from 'react'
 import styles from '../styles/Chat.module.css'
 import { getApeClient } from '../ape/client'
+import Info from './Info'
 
 export default function Home() {
+  // Component state
   const [messages, setMessages] = useState([])
   const [input, setInput] = useState('')
   const [username, setUsername] = useState('')
@@ -11,67 +33,133 @@ export default function Home() {
   const [userCount, setUserCount] = useState(0)
   const [sending, setSending] = useState(false)
   const [connected, setConnected] = useState(false)
-  const messagesEndRef = useRef(null)
-  const apiRef = useRef(null) // The sender proxy
+  
+  // Refs
+  const apiRef = useRef(null) // Stores the api-ape sender Proxy
 
-  // Initialize api-ape client on mount (before join)
+  /**
+   * Initialize api-ape client on component mount
+   * 
+   * This effect:
+   * 1. Gets the api-ape client singleton (connects to WebSocket)
+   * 2. Stores the `sender` Proxy in a ref for later use
+   * 3. Sets up event listeners for server broadcasts
+   * 
+   * The client auto-reconnects if the connection drops.
+   */
   useEffect(() => {
+    // Skip on server-side rendering
     if (typeof window === 'undefined') return
 
     getApeClient().then((client) => {
       if (!client) return
 
-      // Store the sender proxy - ready to use!
+      /**
+       * Store the sender Proxy
+       * 
+       * `client.sender` is a Proxy object that allows you to call server functions
+       * by accessing properties. For example:
+       * - `sender.message(data)` calls `api/message.js` on the server
+       * - The property name (`message`) maps to the server file path
+       * - All calls return Promises that resolve with the server's response
+       */
       apiRef.current = client.sender
       setConnected(true)
-      console.log('🦍 api-ape ready')
+      console.log('🦍 api-ape client connected')
 
-      // Set up message listeners
+      /**
+       * Set up event listeners for server broadcasts
+       * 
+       * `setOnReciver(type, handler)` listens for broadcasts from the server.
+       * The server can broadcast using `this.broadcast()` or `this.broadcastOthers()`
+       * in controller functions (see api/message.js).
+       * 
+       * Broadcast types:
+       * - 'init': Initial data when client connects (history, user count)
+       * - 'message': New message from another client
+       * - 'users': Updated user count
+       */
       client.setOnReciver('init', ({ data }) => {
+        // Server sent initial data (happens on connect)
         setMessages(data.history || [])
         setUserCount(data.users || 0)
-        console.log('🦍 Initialized')
+        console.log('🦍 Initialized with', data.history?.length || 0, 'messages')
       })
 
       client.setOnReciver('message', ({ data }) => {
+        // Server broadcasted a new message from another client
+        // This is NOT the response to our own send - it's a broadcast!
         setMessages(prev => [...prev, data.message])
       })
 
       client.setOnReciver('users', ({ data }) => {
+        // Server broadcasted updated user count
         setUserCount(data.count)
       })
     })
   }, [])
 
-  // Auto-scroll to bottom
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
-  }, [messages])
-
-  // Send message using the proxy pattern
-  // api.message(data) -> sends type="message" with data
-  // Returns a Promise - server can reply with matching queryId
+  /**
+   * Send a message to the server
+   * 
+   * This demonstrates the api-ape Proxy pattern:
+   * 
+   * 1. Access `api.message()` - the property name 'message' maps to `api/message.js`
+   * 2. Call it with data - returns a Promise
+   * 3. Server processes the request in `api/message.js`
+   * 4. Server can:
+   *    - Return a value (fulfills the Promise)
+   *    - Broadcast to other clients using `this.broadcastOthers()`
+   *    - Throw an error (rejects the Promise)
+   * 
+   * The Promise resolves with whatever the server function returns.
+   * The server also broadcasts to other clients (see api/message.js).
+   */
   const sendMessage = (e) => {
     e.preventDefault()
     if (!input.trim() || !apiRef.current || sending) return
 
     const api = apiRef.current
-
     setSending(true)
 
-    // api.message({ user, text }) - "message" is the type!
-    // createdAt is auto-added by client
-    // queryId hash is auto-generated for request/response matching
+    /**
+     * Call server function using Proxy pattern
+     * 
+     * `api.message({ user, text })`:
+     * - Calls the `message` function in `api/message.js`
+     * - Sends `{ user, text }` as the function argument
+     * - Returns a Promise that resolves with the server's return value
+     * - Server automatically broadcasts to other clients (see api/message.js)
+     * 
+     * The server function receives the data and can:
+     * - Validate input
+     * - Store the message
+     * - Broadcast to others: `this.broadcastOthers('message', { message: msg })`
+     * - Return a response: `return { ok: true, message: msg }`
+     */
     api.message({ user: username, text: input })
       .then((response) => {
-        // Server replied with matching queryId
-        // Add our own message to the list (we sent it, so we add it)
+        /**
+         * Server responded successfully
+         * 
+         * The response is whatever the server function returned.
+         * In this case, api/message.js returns: `{ ok: true, message: msg }`
+         * 
+         * Note: Other clients receive the message via broadcast (setOnReciver above),
+         * but we add it here from the server's response to show it immediately.
+         */
         if (response?.message) {
           setMessages(prev => [...prev, response.message])
         }
         setSending(false)
       })
       .catch((err) => {
+        /**
+         * Server function threw an error or connection failed
+         * 
+         * Errors from server functions are automatically caught and
+         * the Promise is rejected with the error.
+         */
         console.error('Send failed:', err)
         setSending(false)
       })
@@ -79,6 +167,10 @@ export default function Home() {
     setInput('')
   }
 
+  /**
+   * Handle user joining the chat
+   * Simply sets the joined state to show the chat interface
+   */
   const handleJoin = (e) => {
     e.preventDefault()
     if (username.trim()) {
@@ -98,7 +190,13 @@ export default function Home() {
           🦍 <span className={styles.gradient}>api-ape</span> Chat
         </h1>
         <p className={styles.subtitle}>
-          {connected ? '✅ Connected' : '⏳ Connecting...'} • Pure WebSocket
+          {connected ? (
+            userCount === 1 
+              ? '✅ Connected • Only You are online'
+              : userCount > 1
+              ? `✅ Connected • You + ${userCount - 1} are online`
+              : '✅ Connected'
+          ) : '⏳ Connecting...'}
         </p>
 
         {!joined ? (
@@ -140,7 +238,6 @@ export default function Home() {
                   </span>
                 </div>
               ))}
-              <div ref={messagesEndRef} />
             </div>
 
             <form onSubmit={sendMessage} className={styles.inputForm}>
@@ -160,22 +257,7 @@ export default function Home() {
           </div>
         )}
 
-        <div className={styles.codeSection}>
-          <h3 className={styles.codeTitle}>✨ api-ape Proxy Pattern</h3>
-          <pre className={styles.code}>
-            {`// Sender is a Proxy - prop name = type
-const api = client.sender
-
-// Send with Promise - queryId auto-matched
-setSending(true)
-api.message({ user, text })
-  .then(() => setSending(false))
-  .catch(err => console.error(err))
-
-// createdAt auto-added by client
-// queryId hash matches request/response`}
-          </pre>
-        </div>
+        <Info />
       </main>
     </div>
   )

package/example/NextJs/styles/Chat.module.css

@@ -6,9 +6,10 @@
 }
 
 .main {
-  max-width: 600px;
+  max-width: 1400px;
   margin: 0 auto;
   padding: 2rem;
+  width: 100%;
 }
 
 .title {
@@ -192,3 +193,256 @@
   padding: 0.2rem 0.5rem;
   border-radius: 4px;
 }
+
+.gridContainer {
+  max-width: 1200px;
+  margin: 1.5rem auto 0;
+  padding: 0 1rem;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.gridLayout {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 2rem;
+  width: 100%;
+}
+
+@media (min-width: 768px) {
+  .gridLayout {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+@media (max-width: 767px) {
+  .gridContainer {
+    padding: 0 0.5rem;
+  }
+  
+  .main {
+    padding: 1rem;
+  }
+}
+
+/* Info component styles */
+.sectionHeading {
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  font-weight: bold;
+}
+
+.sectionHeadingLarge {
+  margin-bottom: 1rem;
+  font-size: 0.9rem;
+  font-weight: bold;
+}
+
+.dataFlowGrid {
+  display: grid;
+  grid-template-columns: 200px 1fr 200px;
+  grid-template-rows: auto auto auto auto auto;
+  gap: 1rem;
+  align-items: stretch;
+}
+
+.columnHeaderClient {
+  font-size: 0.8rem;
+  font-weight: bold;
+  text-align: center;
+  grid-row: 1;
+  grid-column: 1;
+  color: #00d2ff;
+}
+
+.columnHeaderServer {
+  font-size: 0.8rem;
+  font-weight: bold;
+  text-align: center;
+  grid-row: 1;
+  grid-column: 3;
+  color: #00e676;
+}
+
+.gridCell {
+  grid-row: 1;
+  grid-column: 2;
+}
+
+.clientBoxSpan3 {
+  background: linear-gradient(135deg, #3a7bd5, #00d2ff);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(58, 123, 213, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 1;
+  grid-row: 2 / 5;
+}
+
+.clientBoxSingle {
+  background: linear-gradient(135deg, #3a7bd5, #00d2ff);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(58, 123, 213, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 1;
+  grid-row: 5;
+}
+
+.serverBoxSpan2 {
+  background: linear-gradient(135deg, #00c851, #00e676);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(0, 200, 81, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 3;
+  grid-row: 2 / 4;
+}
+
+.serverBoxSpan3 {
+  background: linear-gradient(135deg, #00c851, #00e676);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(0, 200, 81, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 3;
+  grid-row: 4 / 6;
+}
+
+.arrowContainerRow2 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  grid-column: 2;
+  grid-row: 2;
+}
+
+.arrowContainerRow3 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  grid-column: 2;
+  grid-row: 3;
+}
+
+.arrowContainerRow4 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  grid-column: 2;
+  grid-row: 4;
+}
+
+.arrowContainerRow5 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  grid-column: 2;
+  grid-row: 5;
+}
+
+.arrowLineSend {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00d2ff, #00e676);
+}
+
+.arrowLineReturn {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00e676, transparent);
+}
+
+.arrowLineBroadcast {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, transparent, #00e676);
+}
+
+.arrowLineBroadcastReturn {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00d2ff, transparent);
+}
+
+.arrowLabelBlue {
+  font-size: 0.7rem;
+  white-space: nowrap;
+  padding: 0 0.5rem;
+  color: #00d2ff;
+}
+
+.arrowLabelGreen {
+  font-size: 0.7rem;
+  white-space: nowrap;
+  padding: 0 0.5rem;
+  color: #00e676;
+}
+
+.arrowHeadRight {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-left: 8px solid #00e676;
+}
+
+.arrowHeadLeft {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-right: 8px solid #00e676;
+}
+
+.arrowHeadLeftBlue {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-right: 8px solid #00d2ff;
+}
+
+.emptyGridCell {
+  grid-row: 2;
+  grid-column: 3;
+}
+
+.emptyGridCellRow3 {
+  grid-row: 3;
+  grid-column: 1;
+}
+
+.emptyGridCellRow4 {
+  grid-row: 4;
+  grid-column: 1;
+}
+
+.emptyGridCellRow5 {
+  grid-row: 5;
+  grid-column: 3;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Remote procedure events",
   "main": "index.js",
   "types": "index.d.ts",