@firtoz/socka 2.0.0 → 2.1.0

package/docs/client.md

@@ -28,8 +28,14 @@ const rows = await session.send.list();
 
 Use **`SockaWebSocketClient`** directly if you need **`onResponse` / `onServerError` / `onEvent`** frame hooks without **`SockaSession`**’s typed **`send`** / **`subscribe`**; most apps use **`SockaSession`**.
 
+**Connection status** — **`SockaWebSocketClient`** and **`SockaSession`** expose **`status`** (`"idle" | "connecting" | "open" | "reconnecting" | "closed"`) and **`onStatusChange`** for UI (e.g. “Reconnecting…”). Same fields power the React hooks below.
+
 ## React
 
+### `useSockaSession` — typed `send`
+
+Use **`useSockaSession(contract, options, deps)`** when you want **`send.*`** RPC methods directly (same shape as **`session.send`**). **`ready`** flips to **`true`** after the socket opens; **`deps`** remount the connection when identity (e.g. room id) changes. Also returns **`status`**, **`reconnecting`**, and **`reconnectAttempt`** (see **`useSocka`**).
+
 ```ts
 import { useSockaSession } from "@firtoz/socka/react";
 import { myContract } from "./contract";
@@ -44,6 +50,41 @@ function App() {
 useSockaSession(myContract, { url: "wss://...", wireFormat: "msgpack" }, []);
 ```
 
+### `useSocka` — hold a `SockaSession` ref
+
+Use **`useSocka(options, deps)`** when you need the full **`SockaSession`** (e.g. **`session.subscribe`**, **`session.client`**, **`waitForPush`**, or passing the session into non-React helpers). It returns **`{ ready, sessionRef, status, reconnecting, reconnectAttempt }`** — read **`sessionRef.current`** in effects or callbacks (it is **`null`** until the effect runs). Use **`reconnecting`** or **`status === "reconnecting"`** for banners; **`reconnectAttempt`** counts backoff attempts.
+
+| | **`useSockaSession`** | **`useSocka`** |
+|--|------------------------|----------------|
+| **Returns** | **`{ ready, send, status, reconnecting, reconnectAttempt }`** | **`{ ready, sessionRef, status, reconnecting, reconnectAttempt }`** |
+| **Best for** | Most React UIs that only call RPCs | Subscriptions, low-level client access, imperative APIs |
+
+```tsx
+import { useEffect } from "react";
+import { useSocka } from "@firtoz/socka/react";
+import { myContract } from "./contract";
+
+function App() {
+  const { ready, sessionRef } = useSocka({ contract: myContract, url: "ws://..." }, []);
+
+  useEffect(() => {
+    const s = sessionRef.current;
+    if (!ready || !s) return;
+    const onNotify = (p: { msg: string }) => console.log(p.msg);
+    s.subscribe.on("notify", onNotify);
+    return () => s.subscribe.off("notify", onNotify);
+  }, [ready, sessionRef]);
+
+  return null;
+}
+```
+
+*(Example assumes your contract defines a **`notify`** push; use the real push names from **`myContract`**.)*
+
+### `useSockaPresence` — snapshot + join/leave deltas
+
+Call **`useSockaPresence(sessionRef, ready, options, deps)`** after **`useSocka`** / **`useSockaSession`**: it runs your **`snapshot`** RPC once, subscribes to **`joinPush`** / **`leavePush`**, and returns **`{ users, selfUserId, loading }`**. Pass the same **`deps`** as the connection when room identity changes.
+
 ### One WebSocket for the whole tree
 
 If many components need **`send`**, avoid calling **`useSockaSession`** in each one (each call owns a connection). Mount a provider once and read the session from context:
@@ -65,7 +106,7 @@ function Layout({ roomId }: { roomId: string }) {
 }
 
 function Child() {
-  const { ready, send } = useSockaSessionContext(myContract);
+  const { ready, send, status, reconnecting } = useSockaSessionContext(myContract);
   // ...
 }
 ```
@@ -78,8 +119,8 @@ Use **`autoConnect: false`** on **`SockaWebSocketClient`** / **`SockaSession`**
 
 ## Client lifecycle
 
-Treat each **`SockaSession`** / **`SockaWebSocketClient`** as bound to **one** underlying **`WebSocket`**. When the socket closes, pending calls reject and should not be retried on the same instance. For reconnect or room changes, construct a **new** client (in React, remount **`useSockaSession`** / **`SockaSessionProvider`** when **`url`** or identity **`deps`** change). Use **`ready`** / **`waitForOpen()`** before assuming the connection is usable; use **`onClose`** / **`onError`** (or **`reportError`**) for backoff, toasts, or logging.
+Treat each **`SockaSession`** / **`SockaWebSocketClient`** as bound to **one** underlying **`WebSocket`**. When the socket closes, pending calls reject on that instance unless you opt into client-side reconnect (see **[Reconnection](./reconnection.md)**). For a deliberate room/url change, construct a **new** client (in React, remount **`useSockaSession`** / **`SockaSessionProvider`** when **`url`** or identity **`deps`** change). Use **`ready`** / **`waitForOpen()`** before assuming the connection is usable; use **`onClose`** / **`onError`** (or **`reportError`**) for telemetry.
 
 ## Pushes
 
-Server push and client subscriptions are covered in [Pushes](./events.md).
+Server push and client subscriptions are covered in **[Pushes](./pushes.md)**.

package/docs/comparison.md

@@ -33,4 +33,4 @@ Most apps model messages as large discriminated unions (`type` + `id`), validate
 
 ## When socka is a good fit
 
-You want **schema-first WebSocket RPC** with **correlated request/response** and optional **typed server push** from a **single contract module**—and you are fine with **socka v1** frames (see **[Reference](./reference.md)**) so you can swap runtimes (Bun, Hono, Durable Objects, Node **`ws`**) behind the same procedures.
+You want **schema-first WebSocket RPC** with **correlated request/response** and optional **typed server push** from a **single contract module**—and you are fine with **socka v1** frames (see **[Internals](./internals.md)**) so you can swap runtimes (Bun, Hono, Durable Objects, Node **`ws`**) behind the same procedures.

package/docs/durable-objects.md

@@ -14,11 +14,11 @@ This is the **Cloudflare** side (bindings, Wrangler, generated types)—not sock
 1. **Wrangler** — `wrangler.jsonc` / `wrangler.toml` with a **Durable Object** binding and a **migration** for the DO class (see Cloudflare docs and the runnable **[tic-tac-toe-do example](https://github.com/firtoz/fullstack-toolkit/tree/main/examples/tic-tac-toe-do)** in this repo).
 2. **Typed `Env`** — After you change bindings or `wrangler` config, regenerate env types (**`bun run typegen`** / **`cf-typegen`** via [`@firtoz/worker-helper`](https://github.com/firtoz/fullstack-toolkit/tree/main/packages/worker-helper)); **do not hand-edit** `worker-configuration.d.ts`. Workflow reference: [Cloudflare / Wrangler typegen skill](https://github.com/firtoz/fullstack-toolkit/blob/main/.cursor/skills/cloudflare-wrangler-typegen/SKILL.md) in this monorepo.
 3. **Run locally** — `wrangler dev` (optionally pin a port—e.g. **3463** in the tic-tac-toe example so it does not clash with other apps).
-4. **Peers** — **`@firtoz/socka/do`** needs **`@firtoz/websocket-do`**, **`hono`**, **`@cloudflare/workers-types`**—see **[Peers](./peers.md)**.
+4. **Peers** — **`@firtoz/socka/do`** needs **`@firtoz/websocket-do`** and **`hono`** — see **[Peers](./peers.md)**. Use **`wrangler types`** (or your app’s typegen) for Cloudflare/DO bindings in TypeScript.
 
 ### Wire format
 
-**`wireFormat`** defaults to **`"json"`** (text frames). Use **`"msgpack"`** only if the client also uses **`msgpack`**. Mismatched **`wireFormat`** between client and session config will fail to decode. Details: **[Reference — Wire encoding](./reference.md#wire-encoding-json-and-msgpack)**.
+**`wireFormat`** defaults to **`"json"`** (text frames). Use **`"msgpack"`** only if the client also uses **`msgpack`**. Mismatched **`wireFormat`** between client and session config will fail to decode. See **[Reference](./reference.md#wire-encoding-json-and-msgpack)** and **[Internals](./internals.md)**.
 
 ## `SockaDoSession`
 

package/docs/getting-started.md

@@ -1,10 +1,25 @@
 # Getting started
 
-The **[README](../README.md)** opens with a **complete Bun example**: shared contract, **`createSockaBunWebSocketHandlers`**, and **`SockaSession`**. Start there if you want something runnable in one minute.
+This guide walks through a **multi-room chat** on one **`defineSocka`** contract: **typed RPCs** (`listHistory`, `listPresence`, `sendMessage`, `clearHistory`) and **typed pushes** (`userJoined`, `userLeft`, `roomMessage`, `historyCleared`). The **[README](../README.md)** has the shortest runnable **Bun** slice (in-memory history).
 
-## Quickest path (Bun)
+**Runnable apps** with persistence and a **multi-room browser client**: **[chatroom-bun](../../../examples/chatroom-bun)** (Bun SQLite), **[chatroom-hono](../../../examples/chatroom-hono)** (JSON files), **[chatroom-do](../../../examples/chatroom-do)** (Durable Object SQLite + Drizzle).
 
-Save three files next to each other, then run **`bun run server.ts`**. Point a client at **`ws://localhost:3450/ws`** (same contract as the README).
+For API tables, see **[Reference](./reference.md)**. For wire details, **[Internals](./internals.md)**.
+
+---
+
+## Step 1 — What you are building
+
+1. Clients connect to **`ws://host/ws/<roomId>?name=<displayName>`** (path and query are conventions you control).
+2. Each **room** has its own **`sessionMap`** and **config** — see **[Multi-room](./multi-room.md)**.
+3. **Join/leave** are **`pushes`** to everyone else in the room; **chat lines** are **`pushes`** too (after you persist).
+4. **History** is loaded with a **call** (`listHistory`) so reconnects and new panes can hydrate from storage (SQLite, JSON files, or DO SQLite in the examples).
+
+---
+
+## Step 2 — Shared contract
+
+Use one module on the client and every server:
 
 **`contract.ts`**
 
@@ -12,127 +27,171 @@ Save three files next to each other, then run **`bun run server.ts`**. Point a c
 import { defineSocka } from "@firtoz/socka/core";
 import * as z from "zod";
 
-export const myContract = defineSocka({
-	calls: {
-		echo: {
-			input: z.object({ text: z.string() }),
-			output: z.object({ text: z.string() }),
-		},
-	},
+export const messageRow = z.object({
+	id: z.string(),
+	ts: z.number(),
+	userId: z.string(),
+	displayName: z.string(),
+	text: z.string(),
 });
-```
-
-**`server.ts`**
 
-```ts
-import { createSockaBunWebSocketHandlers } from "@firtoz/socka/bun";
-import { myContract } from "./contract";
+export type ChatMessageRow = z.infer<typeof messageRow>;
 
-const { websocket } = createSockaBunWebSocketHandlers({
-	contract: myContract,
-	handlers: {
-		echo: async (input) => ({ text: input.text }),
-	},
-	handleClose: async () => {},
+const onlineUser = z.object({
+	userId: z.string(),
+	displayName: z.string(),
 });
 
-Bun.serve({
-	port: 3450,
-	fetch(req, server) {
-		if (new URL(req.url).pathname === "/ws") {
-			if (server.upgrade(req)) return undefined;
-			return new Response("WebSocket upgrade failed", { status: 400 });
-		}
-		return new Response("OK");
+export const chatContract = defineSocka({
+	calls: {
+		listHistory: {
+			input: z.object({ limit: z.number().int().min(1).max(500).optional() }),
+			output: z.object({ messages: z.array(messageRow) }),
+		},
+		listPresence: {
+			input: z.object({}).optional(),
+			output: z.object({
+				selfUserId: z.string(),
+				users: z.array(onlineUser),
+			}),
+		},
+		sendMessage: {
+			input: z.object({ text: z.string().min(1) }),
+			output: z.object({ ok: z.literal(true) }),
+		},
+		clearHistory: {
+			input: z.object({}).optional(),
+			output: z.object({ ok: z.literal(true) }),
+		},
+	},
+	pushes: {
+		userJoined: z.object({ userId: z.string(), displayName: z.string() }),
+		userLeft: z.object({
+			userId: z.string(),
+			displayName: z.string(),
+		}),
+		roomMessage: messageRow,
+		historyCleared: z.object({
+			ts: z.number(),
+			clearedByUserId: z.string(),
+			clearedByDisplayName: z.string(),
+		}),
 	},
-	websocket,
 });
 ```
 
-**`client.ts`**
+---
+
+## Step 3 — Client: subscribe, hydrate, send
+
+1. Open **`SockaSession`** with **`url`** pointing at your upgrade path (same **`roomId`** and **`name`** the server parses in **`createData`**).
+2. After the socket is ready, **`await session.send.listHistory({})`** (or `{ limit: 100 }`) and render **`messages`**, then **`await session.send.listPresence({})`** to show **who is online** (compare **`selfUserId`** to highlight the current user).
+3. Register **`session.subscribe.on("userJoined" | "userLeft" | "roomMessage" | "historyCleared", …)`** for live updates (merge joins/leaves into your presence UI; on **`historyCleared`**, drop or redraw stored chat lines for that room).
+4. Send **`await session.send.sendMessage({ text: "…" })`**. Optional: **`await session.send.clearHistory({})`** to wipe persisted messages for the room (server should **`broadcastPush("historyCleared", …)`** so every client updates).
+
+**Minimal client**
 
 ```ts
 import { SockaSession } from "@firtoz/socka/client";
-import { myContract } from "./contract";
+import { chatContract } from "./contract";
 
 const session = new SockaSession({
-	contract: myContract,
-	url: "ws://localhost:3450/ws",
+	contract: chatContract,
+	url: "ws://localhost:3464/ws/lobby?name=Ada",
 });
-const { text } = await session.send.echo({ text: "hello" });
+
+session.subscribe.on("userJoined", (p) => console.log("in", p.displayName));
+session.subscribe.on("userLeft", (p) => console.log("out", p.displayName));
+session.subscribe.on("roomMessage", (m) => console.log(`${m.displayName}: ${m.text}`));
+session.subscribe.on("historyCleared", (p) =>
+	console.log("cleared by", p.clearedByDisplayName),
+);
+
+const { messages } = await session.send.listHistory({ limit: 50 });
+for (const m of messages) console.log(`[hist] ${m.displayName}: ${m.text}`);
+
+const { selfUserId, users } = await session.send.listPresence({});
+console.log("online", selfUserId, users);
+
+await session.send.sendMessage({ text: "hello" });
 ```
 
-## What socka is
+**Multiple rooms on one page** — use **one `SockaSession` per room** (see the chat example **`public/index.html`** + **`src/client.ts`**): each pane builds its own URL and keeps its own subscriptions.
 
-**Socka** is the library; the **npm package name is [`@firtoz/socka`](https://www.npmjs.com/package/@firtoz/socka)** (scoped). It is **schema-first WebSocket RPC**: one **`defineSocka`** contract gives you typed **`session.send.*`** in the browser and **`handlers`** on the server, with Socka **v1** frames on the wire.
+By default, **`wireFormat`** is JSON — see **[Reference](./reference.md#wire-encoding-json-and-msgpack)** if you use **`msgpack`**.
 
-For frame shapes and options, see **[Reference](./reference.md)**.
+---
 
-## Other runtimes
+## Step 4 — Server behavior (all runtimes)
 
-Pick **how** the socket is upgraded, then use the matching subpath:
+For each **`SockaWebSocketSessionConfig`** / **`SockaDoSessionConfig`**:
 
-| You want to… | Read this first | Import path |
-|--------------|-----------------|-------------|
-| **Node** + **`ws`**, or any standard **`WebSocket`** after upgrade | **[Server](./server.md)** — **`attachSockaWebSocket`** | `@firtoz/socka/server` |
-| **Bun** **`Bun.serve`** / **`ServerWebSocket`** | **[Server](./server.md)** — **`@firtoz/socka/bun`** | `@firtoz/socka/bun` |
-| **Hono** on **Node** (`@hono/node-ws`) | **[Server](./server.md)** — **`sockaHonoNodeWs`** | `@firtoz/socka/hono` |
-| **Hono** on **Cloudflare Workers** | **[Server](./server.md)** — **`sockaHonoCloudflare`** | `@firtoz/socka/hono/cloudflare` |
-| **Cloudflare Durable Objects** | **[Durable Objects](./durable-objects.md)** | `@firtoz/socka/do` |
+1. **`createData`** — Parse **`roomId`** from the upgrade URL (path) and **`displayName`** from **`name`** query; set **`userId`** (e.g. **`crypto.randomUUID()`**). Same shape as the README **`SockaWebSocketInit`** / Hono **`Context`** on DO.
+2. **`onAttached`** — `await session.broadcastPush("userJoined", { userId, displayName }, true)` (**`excludeSelf: true`** so only peers see the join).
+3. **`handlers.listHistory`** — Read from your store for **`session.data.roomId`** (Bun: SQLite; Hono: JSON file; DO: SQLite in the object).
+4. **`handlers.listPresence`** — Walk the room’s **`sessionMap`** (or DO **`this.sessions`**) and return **`{ selfUserId: session.data.userId, users: [{ userId, displayName }, …] }`** sorted for display.
+5. **`handlers.sendMessage`** — Persist the line, then **`await session.broadcastPush("roomMessage", row)`** (everyone in the room, including the sender, unless you choose **`excludeSelf`**).
+6. **`handlers.clearHistory`** — Delete persisted messages for **`session.data.roomId`**, then **`await session.broadcastPush("historyCleared", { ts, clearedByUserId, clearedByDisplayName })`** so all clients refresh their UI.
+7. **`handleClose`** — `await session.broadcastPush("userLeft", { userId, displayName: session.data.displayName }, true)` — **`displayName`** is the **session’s name at disconnect** (same field as in **`userJoined`** / messages), so clients can render a leave line without guessing from **`userId`** alone. Session is still in **`sessions`** until **`handleClose`** finishes — see **[Lifecycle](./lifecycle.md)**.
 
-**Multiple rooms or scopes?** See **[Multi-room](./multi-room.md)**.
+---
 
-## Install
+## Step 5 — Wire the server by runtime
 
-```bash
-npm install @firtoz/socka
-```
+Pick a row, then follow the numbered steps in that subsection.
 
-Add **only** the peers for the subpaths you import—**[Peers](./peers.md)**.
+| Runtime | Install | Full example |
+|---------|---------|--------------|
+| **Bun** | `npm install @firtoz/socka` (+ **`bun-types`** dev if needed) | [chatroom-bun](../../../examples/chatroom-bun) |
+| **Node + `ws`** | `npm install @firtoz/socka ws` (+ **`@types/ws`** dev) | Same contract; attach pattern below |
+| **Hono (Node)** | `npm install @firtoz/socka hono @hono/node-ws @hono/node-server ws` | [chatroom-hono](../../../examples/chatroom-hono) |
+| **Hono (Workers)** | `npm install @firtoz/socka hono` | **[Server](./server.md#firtoz-socka-hono-cloudflare-workers)** — usually **`sockaHonoCloudflare`**; session often starts on first message |
+| **Durable Objects** | `npm install @firtoz/socka hono @firtoz/websocket-do` | [chatroom-do](../../../examples/chatroom-do) |
 
-## Shared contract
+More installs: **[Peers](./peers.md)**. Cloudflare typings: **`wrangler types`**.
 
-Use one module for client and server (same as the README):
+### Bun (`Bun.serve`)
 
-```ts
-import { defineSocka } from "@firtoz/socka/core";
-import * as z from "zod";
+1. **Open** a **`Database`** from **`bun:sqlite`** (one file; table keyed by **`room_id`**), **`CREATE TABLE IF NOT EXISTS`** for messages.
+2. **`getOrCreateRoom(roomId)`** returns **`{ sessionMap, config }`** where **`config`** closes over **`roomId`** and **`db`**.
+3. **`createSockaBunWebSocketHandlers({ resolveScope })`** — **`resolveScope(ws)`** reads **`ws.data.roomId`** (set in **`fetch`** via **`server.upgrade(req, { data: { roomId } })`**).
+4. **`fetch`** upgrades **`/ws/:roomId`** (decode the segment).
 
-export const myContract = defineSocka({
-	calls: {
-		echo: {
-			input: z.object({ text: z.string() }),
-			output: z.object({ text: z.string() }),
-		},
-	},
-});
-```
+### Node + `ws`
 
-For richer examples (list/insert, optional inputs), see **[Server](./server.md)** and the tic-tac-toe apps under `examples/`.
+1. **`new WebSocketServer({ port })`**.
+2. On **`connection`**, parse **`roomId`** from **`req.url`**, **`getOrCreateRoom`**, then **`attachSockaWebSocket( ws, room.sessionMap, room.config, { request: req } )`** so **`createData`** sees the URL.
 
-## Wire the server, then the client
+### Hono on Node
 
-You already have the **client** shape (`SockaSession` with the same contract). Now:
+1. **`createNodeWebSocket({ app })`** from **`@hono/node-ws`**.
+2. **`app.get("/ws/:roomId", upgradeWebSocket((c) => { const room = getOrCreateRoom(c.req.param("roomId")); return sockaHonoNodeWs(room.config, { sessions: room.sessionMap })(c); }))`**.
+3. **`serve`** + **`injectWebSocket(server)`**.
 
-1. **Server** — Open the guide from **Other runtimes** and implement **`handlers`** + **`handleClose`** for **`myContract`**. Use **`SockaWebSocketSession`** / **`attachSockaWebSocket`** (Node/Bun/Hono) or **`SockaDoSession`** / **`SockaWebSocketDO`** (Durable Objects).
-2. **Client** — Keep **`SockaSession`** (or **`useSockaSession`** / **`SockaSessionProvider`**—**[Client](./client.md)**) with the **same** **`wireFormat`** as the server.
+### Hono on Cloudflare Workers
 
-### Wire format (short)
+1. Use **`upgradeWebSocket`** from **`hono/cloudflare-workers`** with **`sockaHonoCloudflare`** — see **[Server](./server.md)**.
+2. For **room routing** without a DO, put **`roomId`** in the path and parse it in **`createData`** from **`init.request`**.
 
-Default is **JSON text** frames. **`wireFormat: "msgpack"`** must match on **both** sides. Details: **[Reference — Wire encoding](./reference.md#wire-encoding-json-and-msgpack)**.
+### Cloudflare Durable Objects
 
-## Run a full-stack demo
+1. **Worker** — route **`/ws/:roomId`** to **`env.CHAT_ROOM.idFromName(roomId).get(id).fetch(...)`** (stub forwards WebSocket upgrade to the DO).
+2. **DO class** — extend **`SockaWebSocketDO`**; **`SockaDoSession`** handlers use **Drizzle** on **`drizzle(ctx.storage)`** (see [chatroom-do](../../../examples/chatroom-do)).
+3. **One DO instance per room** — history lives in that object’s SQLite; no **`room_id`** column needed if the table is per-DO.
 
-Same **tic-tac-toe** contract and game logic, three servers in this repo:
+---
 
-| Stack | Folder | Port |
-|-------|--------|------|
-| **Bun** | [`tic-tac-toe-bun`](../../../examples/tic-tac-toe-bun) | **3461** |
-| **Hono + Node** | [`tic-tac-toe-hono`](../../../examples/tic-tac-toe-hono) | **3462** |
-| **Durable Objects** | [`tic-tac-toe-do`](../../../examples/tic-tac-toe-do) | **3463** |
+## Full-stack examples (chat + tic-tac-toe)
 
-From the folder: **`bun run dev`**. The DO example uses **`wrangler dev`**.
+| Topic | Stack | Folder | Port |
+|-------|--------|--------|------|
+| Chat + history | **Bun** + SQLite | [`chatroom-bun`](../../../examples/chatroom-bun) | **3464** |
+| Chat + history | **Hono + Node** + JSON | [`chatroom-hono`](../../../examples/chatroom-hono) | **3465** |
+| Chat + history | **DO** + Drizzle SQLite | [`chatroom-do`](../../../examples/chatroom-do) | **3466** |
+| Tic-tac-toe | **Bun** | [`tic-tac-toe-bun`](../../../examples/tic-tac-toe-bun) | **3461** |
+| Tic-tac-toe | **Hono + Node** | [`tic-tac-toe-hono`](../../../examples/tic-tac-toe-hono) | **3462** |
+| Tic-tac-toe | **DO** | [`tic-tac-toe-do`](../../../examples/tic-tac-toe-do) | **3463** |
 
 ---
 
-Next: [Peers](./peers.md) · [Server](./server.md) · [Durable Objects](./durable-objects.md) · [Client](./client.md) · [Reference](./reference.md)
+Next: [Peers](./peers.md) · [Multi-room](./multi-room.md) · [Server](./server.md) · [Durable Objects](./durable-objects.md) · [Client](./client.md) · [Reference](./reference.md) · [Internals](./internals.md)

package/docs/history.md

@@ -0,0 +1,26 @@
+# History (pagination, retention, invalidation)
+
+Long-lived rooms often keep a **message log** on the server. Patterns that work well with socka:
+
+## Pagination / cursor
+
+Expose an RPC such as **`listHistory({ limit?, before? })`** where **`before`** is an opaque cursor (e.g. oldest **`ts`** or **`id`** already shown). Return **`messages`** newest-first or oldest-first consistently, and document which end **`before`** anchors.
+
+Clients load an initial page after connect, then **prepend** older pages when the user scrolls up.
+
+## Retention
+
+Enforce **max rows per room** or **time-based pruning** in the handler that **writes** history (e.g. after **`sendMessage`**). Truncation stays a **server policy**; clients learn about bulk wipes via a **push**.
+
+## `historyCleared` (or equivalent)
+
+When one client clears history for everyone, **mutate storage** then **`broadcastPush("historyCleared", { ts, … })`**. Other clients should **drop local message lists** (or refetch **`listHistory`**) so UIs stay consistent.
+
+## Reconnect
+
+After a reconnect, **re-run** **`listHistory`** (or your snapshot RPC) — see **[Reconnection](./reconnection.md)**.
+
+## See also
+
+- **[Getting started](./getting-started.md)** — chat flow.
+- **[Pushes](./pushes.md)** — broadcasting invalidation events.

package/docs/internals.md

@@ -0,0 +1,56 @@
+# Library internals
+
+This page is for **contributors** and readers who want the **wire protocol** and implementation edges. If you only need to **use** socka, start with **[Getting started](./getting-started.md)** and **[Reference](./reference.md)**.
+
+**Source (monorepo paths):**
+
+- Logical frames and **`decodeSockaWire`** — [`packages/socka/src/core/envelope.ts`](../../src/core/envelope.ts)
+- JSON vs msgpack **transport** (`encodeSockaWire`, **`parseWirePayload`**) — [`packages/socka/src/core/wire-codec.ts`](../../src/core/wire-codec.ts)
+- Inbound dispatch — [`packages/socka/src/server/dispatchSockaInboundMessage.ts`](../../src/server/dispatchSockaInboundMessage.ts)
+
+---
+
+## Wire encoding: JSON and msgpack
+
+Socka has two layers: **transport encoding** (how each WebSocket frame is serialized) and **logical frames** (the socka v1 object inside). Both sides must agree on **`wireFormat`** or decoding fails immediately (wrong frame type or parse errors).
+
+| `wireFormat` | WebSocket frame | Bytes on the wire |
+|--------------|-----------------|-------------------|
+| **`"json"`** (default) | **Text** — `send(string)` | UTF-8 JSON of the **whole** envelope (one JSON object per frame). Uses **`serializeJson`** / **`deserializeJson`** when set, otherwise `JSON.stringify` / `JSON.parse`. |
+| **`"msgpack"`** | **Binary** — `send(ArrayBuffer)` | [msgpack](https://msgpack.org/) of the same envelope object graph. In the browser, **`SockaWebSocketClient`** sets **`binaryType = "arraybuffer"`** so binary frames decode correctly. |
+
+**Rules**
+
+- Set **`wireFormat`** to the **same value** on the **client** (`SockaSession` / `SockaWebSocketClient` / `useSockaSession` options) and on **every server session** that talks to that client (`SockaWebSocketSessionConfig`, `SockaDoSessionConfig`, and the `config` passed to **`createSockaBunWebSocketHandlers`**, **`sockaHonoNodeWs`**, **`sockaHonoCloudflare`**, etc.).
+- **RPCs and contract pushes** share one encoding: `clientRequest` / `serverResponse` / `serverError` / `serverEvent` are all wrapped the same way.
+- If you use **`dispatchSockaInboundMessage`** manually, pass the same **`wireFormat`** as the peer used to **encode** the frame.
+- Optional **`serializeJson`** / **`deserializeJson`** on client or server config only affect **JSON mode** (the outer envelope). Call **`body`** and push **`body`** values are still whatever your **Standard Schema** accepts after JSON/msgpack decode.
+
+---
+
+## Logical frames (socka v1)
+
+Every decoded payload is one logical socka **v1** object. **`decodeSockaWire`** checks shape after `JSON.parse` (text) or msgpack unpack (binary).
+
+| Kind | Role |
+|------|------|
+| `clientRequest` | Client → server RPC (`id`, `rpc`, `body`) |
+| `serverResponse` | Success reply (correlated by `id`) |
+| `serverError` | Correlated failure (`id`, `error` message string) |
+| `serverEvent` | Server push (`event`, `body`) — **not** tied to an RPC `id` |
+
+Clients generate **`id`** strings per request; servers echo them on **`serverResponse`** and **`serverError`** so concurrent RPCs never mix results. **`serverEvent`** uses the contract **`pushes`** map and **`session.subscribe`** on the client.
+
+---
+
+## TypeScript: `SockaWebSocketDO` and contract erasure
+
+`@firtoz/socka/do` **erases** the contract slot on **`SockaWebSocketDO`** so concrete `defineSocka(...)` contracts stay strict under TypeScript. If a generic base class rejects your session type, keep using **your** contract type from the module where you called **`defineSocka`**—do not expect an unconstrained `SockaContract<SockaContractConfig>` to accept every concrete contract without that erasure.
+
+---
+
+## Inbound path (server)
+
+**`attachSockaWebSocket`** uses **`dispatchSockaInboundMessage`** with the same `data` shape as a DOM **`MessageEvent`** (`string`, **`ArrayBuffer`**, **`Blob`**, **`ArrayBufferView`**, or **`Buffer`** on Node/Bun). If you handle **`message`** yourself, call **`dispatchSockaInboundMessage(session, wireFormat, data)`** with matching **`wireFormat`**.
+
+See also [Reference](./reference.md) for **`SockaWebSocketSessionConfig`** fields and [Server](./server.md) for adapters.

package/docs/lifecycle.md

@@ -5,21 +5,21 @@ Join, message, and **leave** ordering for socka sessions—whether you use **`@f
 ## Registration and `onAttached`
 
 1. The adapter accepts or upgrades a **`WebSocket`** and constructs a session (**`SockaWebSocketSession`** or **`SockaDoSession`**).
-2. The session is **registered** in the shared **`sessions`** map (the map **`broadcastContractEvent`** uses).
+2. The session is **registered** in the shared **`sessions`** map (the map **`broadcastPush`** and peer iteration use).
 3. On the next microtask, **`onAttached`** runs (if you provided it). Other sessions in the map can see this socket—use this for join broadcasts, not the constructor.
 
 If **`onAttached`** throws or returns a rejected promise, the failure is reported via **`reportError`** (or **`console.error`** by default) with kind **`serverOnAttached`**.
 
 ## Inbound RPCs
 
-While the socket is open, inbound data is decoded ( **`handleRawMessage`**, **`dispatchSockaInboundMessage`**, or Bun/Hono wrappers), inputs are validated, and **`handlers[procedure]`** runs. Handler exceptions → **`onHandlerError`**; bad wire payloads → **`onValidationError`** before your handler—see **[Reference](./reference.md)**.
+While the socket is open, inbound data is decoded and validated, then **`handlers[procedure]`** runs. Handler exceptions → **`onHandlerError`**; bad wire payloads → **`onValidationError`** before your handler—see **[Reference](./reference.md)**.
 
 ## Close and `handleClose`
 
 When the transport closes:
 
 1. The adapter calls **`await session.invokeHandleClose()`**, which runs **your** **`handleClose(session)`**.
-2. **Until that finishes, the session remains in **`sessions`**—so peer iteration and **`broadcastContractEvent`** can still see the closing peer (e.g. “last player left”).
+2. **Until that finishes, the session remains in **`sessions`**—so peer iteration and **`broadcastPush`** can still see the closing peer (e.g. “last player left”).
 3. Then the adapter removes the socket from the map.
 
 **`SockaDoSession`** delegates teardown through **`@firtoz/websocket-do`**; see **[Durable Objects](./durable-objects.md)** for **`BaseSession`** details.

package/docs/multi-room.md

@@ -2,30 +2,32 @@
 
 A **room** (channel, game, namespace) is a **scope** where every client shares one **`sessionMap`** and one session **config** (the object you pass to **`attachSockaWebSocket`**, **`sockaHonoNodeWs`**, **`createSockaBunWebSocketHandlers`**, …).
 
-That shared **config** includes **`wireFormat`** (`"json"` or `"msgpack"`). Everyone connecting into that scope must use the same encoding—see **[Reference — Wire encoding](./reference.md#wire-encoding-json-and-msgpack)**.
+If you care about **encoding** (`json` vs `msgpack`), everyone in that scope must use the same **`wireFormat`** — see **[Reference](./reference.md#wire-encoding-json-and-msgpack)** (details in **[Internals](./internals.md)**).
 
 **Durable Objects** — Often one **Durable Object instance** per room (e.g. **`idFromName(roomId)`**), with one **`sessions`** map per instance. See **[Durable Objects](./durable-objects.md)**.
 
 Within a scope:
 
 - All **`WebSocket`** instances are keys in the same **`Map<WebSocket, Session>`**.
-- **`broadcastContractEvent`** walks that map, so “everyone in this room” means “every session in this scope’s map.”
+- **`broadcastPush`** (and anything else that iterates **`sessions`**) only reaches sockets in **that** map — “everyone in this room” means “every session in this scope’s map.”
 - **`handleClose(session)`** runs when a socket leaves; use **`session.websocket`** and **`session.data`** for cleanup. See **[Lifecycle](./lifecycle.md)** for ordering (your handler runs **before** the socket is removed from the map).
 
 ## Choosing a pattern
 
 | Runtime | Pattern | When it fits |
 |--------|---------|----------------|
-| **Bun** | **`createSockaBunWebSocketHandlers({ resolveScope })`** | One **`Bun.serve`** `websocket` handler; **`resolveScope(ws)`** returns **`{ sessionMap, config }`**—often from **`ws.data`** set during the HTTP upgrade. |
+| **Bun** | **`createSockaBunWebSocketHandlers({ resolveScope })`** | One **`Bun.serve`** `websocket` handler; **`resolveScope(ws)`** returns **`{ sessionMap, config }`**—often **`registry.get(roomId)`** from **`createSockaRoomRegistry`** plus **`ws.data`** from the HTTP upgrade. |
 | **Hono (Node)** | **A)** One route per room (`/ws/:roomId`) with **`getOrCreateRoom`** and **`sockaHonoNodeWs(room.config, { sessions: room.sessionMap })`**. **B)** Single upgrade route + **`resolveScope(c)`** returning **`{ sessions, config }`**. |
 | **Durable Objects** | **One DO instance per room** via **`idFromName(roomId)`** (or similar). Each instance has its own **`sessions`** map. |
 
-Demos: [`tic-tac-toe-bun`](../../../examples/tic-tac-toe-bun), [`tic-tac-toe-hono`](../../../examples/tic-tac-toe-hono), [`tic-tac-toe-do`](../../../examples/tic-tac-toe-do).
+**Chat + persisted history (good multi-room reference):** [`chatroom-bun`](../../../examples/chatroom-bun) (SQLite), [`chatroom-hono`](../../../examples/chatroom-hono) (JSON files), [`chatroom-do`](../../../examples/chatroom-do) (Durable Object SQLite). **Games:** [`tic-tac-toe-bun`](../../../examples/tic-tac-toe-bun), [`tic-tac-toe-hono`](../../../examples/tic-tac-toe-hono), [`tic-tac-toe-do`](../../../examples/tic-tac-toe-do).
 
-## Pitfalls
+If you persist messages **per room**, keep storage keyed by **room** (or one DO per room) so history cannot leak across scopes.
 
-- **Mixing rooms in one map** — Two logical rooms sharing a **`sessionMap`** leak broadcasts and presence. Partition maps per room or use separate DO instances.
-- **Stale `config`** — Handlers close over **`config`**; mutating shared objects inside it affects every connection using that config. Prefer immutable snapshots or room-scoped instances (e.g. one **`Game`** per room).
-- **Very large rooms on a Durable Object** — One DO is one isolate; huge fan-in can hit limits. Shard by room id (multiple DOs) if needed.
+## Pitfalls (for app authors)
+
+- **Mixing rooms in one map** — If two logical rooms share a **`sessionMap`**, **`broadcastPush`** and “who’s online” can leak across rooms. Give each room its own map (or its own DO instance).
+- **Mutating shared `config`** — Handlers close over **`config`**; changing a shared object inside it affects every connection using that config. Prefer immutable snapshots or a **per-room** config instance (e.g. one **`Game`** object per room).
+- **Very large rooms on a Durable Object** — One DO is one isolate; huge fan-in can hit CPU or memory limits. Split traffic across multiple DOs (e.g. shard by room id) if needed.
 
 See also [Lifecycle](./lifecycle.md) and [Server](./server.md) for **`createData`** and **`session.data`**.

package/docs/peers.md

@@ -41,15 +41,19 @@ Add **`bun-types`** as a dev dependency for TypeScript if you type-check Bun API
 ### Cloudflare Workers + Hono upgrade (`@firtoz/socka/hono/cloudflare`)
 
 ```bash
-npm install @firtoz/socka hono @cloudflare/workers-types
+npm install @firtoz/socka hono
 ```
 
+For **TypeScript** on Workers, run **`wrangler types`** (or your app’s **`cf-typegen`** / equivalent) so globals and bindings match your Worker — see [Cloudflare’s TypeScript guide](https://developers.cloudflare.com/workers/languages/typescript). The legacy **`@cloudflare/workers-types`** package still exists and **`@firtoz/socka`** lists it as an **optional** peer for compatibility, but **generated types from your Wrangler config are preferred**.
+
 ### Cloudflare Durable Objects (`@firtoz/socka/do`)
 
 ```bash
-npm install @firtoz/socka hono @firtoz/websocket-do @cloudflare/workers-types
+npm install @firtoz/socka hono @firtoz/websocket-do
 ```
 
+Use **`wrangler types`** (or your project’s typegen) for Worker/DO globals — same as above. **`@cloudflare/workers-types`** is optional if you are not using generated types yet.
+
 **Version pairing:** `@firtoz/socka/do` subclasses **`@firtoz/websocket-do`** (`BaseSession`, `BaseWebSocketDO`). The two packages use **different** version numbers on npm—there is no rule like “same major as socka.” Use a **websocket-do** version that **socka**’s **`peerDependencies`** (and changelog, if you hit edge cases) allow for your **socka** release. You can upgrade **either** package on its own while the integration stays compatible; coordinate when **`BaseSession` / `BaseWebSocketDO`** or socka’s DO layer changes (often **TypeScript** errors first).
 
 ### Portable `ws` / `attachSockaWebSocket` only (`@firtoz/socka/server`)
@@ -62,14 +66,14 @@ Add **`@types/ws`** as a dev dependency when you use **`ws`** on Node. (Omit **`
 
 ---
 
-`@firtoz/websocket-do` is marked **optional** in **`@firtoz/socka`’s** `package.json` so browser-only clients do not pull Durable Object code. **`@cloudflare/workers-types`** is also **optional** unless you import **`@firtoz/socka/do`** or **`@firtoz/socka/hono/cloudflare`**, where Workers globals are part of the story.
+`@firtoz/websocket-do` is marked **optional** in **`@firtoz/socka`’s** `package.json` so browser-only clients do not pull Durable Object code.
 
 **Any Worker that imports `@firtoz/socka/do` must add `@firtoz/websocket-do` explicitly:** `npm install @firtoz/websocket-do`. Choose a version that **satisfies socka’s stated peer range** (and your app’s lockfile); you do not need one-off “lockstep” bumps for every unrelated release—only when integration or types break.
 
 ## Practical notes
 
-- **Only install peers for paths you use.** A Vite SPA that only imports `@firtoz/socka/client` does not need `hono`, **`@cloudflare/workers-types`**, or `@firtoz/websocket-do`.
-- **TypeScript:** For Workers code, add **`@cloudflare/workers-types`** to `compilerOptions.types` (or use your framework’s defaults). For **`@firtoz/socka/bun`** handlers, add **`bun-types`** when you author against Bun APIs.
+- **Only install peers for paths you use.** A Vite SPA that only imports `@firtoz/socka/client` does not need `hono` or `@firtoz/websocket-do`.
+- **TypeScript on Cloudflare:** Prefer **`wrangler types`** output (or your framework’s generated **`Env`**) over manually installing **`@cloudflare/workers-types`** alone — generated types follow your **bindings** and **compatibility date**. For **`@firtoz/socka/bun`** handlers, add **`bun-types`** when you author against Bun APIs.
 - **socka + websocket-do:** If **`@firtoz/websocket-do`** is **outside** what your **socka** version expects (or websocket-do ships a breaking `BaseSession` / `BaseWebSocketDO` change), you may see **type errors** on `SockaDoSession` / `SockaWebSocketDO` or runtime issues—then bump **one or both** until the pairing in the docs / peer range works again.
 
 ## By entrypoint (reference)
@@ -78,8 +82,8 @@ Add **`@types/ws`** as a dev dependency when you use **`ws`** on Node. (Omit **`
 |--------|----------------|-----|
 | `@firtoz/socka/core`, `@firtoz/socka/client` | **None** | Uses Standard Schema, **`WebSocket`**, and shared frame types—**`lib: ["DOM"]`** (or your bundler defaults) is enough. |
 | `@firtoz/socka/react` | `react` **≥ 18** | Hooks and provider API. |
-| `@firtoz/socka/do` | **`@firtoz/websocket-do`** (version range per **socka** `peerDependencies` / changelog), **`@cloudflare/workers-types`**, **`hono`** | `SockaDoSession` extends **`BaseSession`** from **websocket-do**; **`SockaWebSocketDO`** uses **Hono**-shaped routing on top of **`BaseWebSocketDO`**. |
+| `@firtoz/socka/do` | **`@firtoz/websocket-do`** (version range per **socka** `peerDependencies` / changelog), **`hono`** | `SockaDoSession` extends **`BaseSession`** from **websocket-do**; **`SockaWebSocketDO`** uses **Hono**-shaped routing on top of **`BaseWebSocketDO`**. Add Cloudflare typings via **`wrangler types`**, not only the generic **`@cloudflare/workers-types`** package. |
 | `@firtoz/socka/server` | None beyond `@firtoz/socka/core` (standard **`WebSocket`** + same contract types) | Portable **`attachSockaWebSocket`** path. |
 | `@firtoz/socka/bun` | Same as `@firtoz/socka/server` (**`bun-types`** for TypeScript) | **`Bun.serve`** / **`ServerWebSocket`** integration. |
 | `@firtoz/socka/hono` | **`hono`**, **`@hono/node-ws`**, **`@hono/node-server`**, **`ws`** (runtime + types) | Node **`upgradeWebSocket`** pipeline. |
-| `@firtoz/socka/hono/cloudflare` | **`hono`**, **`@cloudflare/workers-types`** (**`upgradeWebSocket`** from `hono/cloudflare-workers`) | Workers WebSocket upgrade (session often starts on first message—see **[Server](./server.md)**). |
+| `@firtoz/socka/hono/cloudflare` | **`hono`** | Workers WebSocket upgrade via **`hono/cloudflare-workers`** (session often starts on first message—see **[Server](./server.md)**). Use **`wrangler types`** for Worker globals. |