@firtoz/socka 2.0.0 → 3.0.0

package/docs/recipes.md

@@ -0,0 +1,77 @@
+# Recipes (copy-paste)
+
+Minimal wiring per runtime. Each assumes a **`defineSocka`** contract and matching client **`SockaSession`**. Full apps: **[chatroom-bun](../../examples/chatroom-bun)** (Bun SQLite), **[chatroom-hono](../../examples/chatroom-hono)** (Hono JSON), **[chatroom-do](../../examples/chatroom-do)** (Durable Object SQLite).
+
+## Multi-room Bun (`Bun.serve`)
+
+Use **`createSockaRoomRegistry`** + **`createSockaBunWebSocketHandlers({ resolveScope })`** — see **[chatroom-bun](../../examples/chatroom-bun/src/server.ts)**.
+
+```ts
+import { createSockaBunWebSocketHandlers, sockaBunUpgrade } from "@firtoz/socka/bun";
+import { createSockaRoomRegistry } from "@firtoz/socka/server";
+
+const rooms = createSockaRoomRegistry((roomId, _sessionMap) => ({
+  contract: myContract,
+  createData: (init) => { /* parse init.request */ return { roomId: "…" }; },
+  handlers: { /* … */ },
+  handleClose: async () => {},
+}));
+
+const { websocket } = createSockaBunWebSocketHandlers({
+  resolveScope(ws) {
+    const room = rooms.get(ws.data.roomId);
+    return { sessionMap: room.sessionMap, config: room.config };
+  },
+});
+
+Bun.serve({
+  fetch(req, srv) {
+    if (req.url.includes("/ws/")) {
+      const roomId = "…";
+      if (sockaBunUpgrade(srv, req, { roomId })) return undefined;
+      return new Response("upgrade failed", { status: 400 });
+    }
+    return new Response("OK");
+  },
+  websocket,
+});
+```
+
+## Single-room Bun
+
+One **`sessionMap`** and one **`config`** — use **`createSockaBunWebSocketHandlers(myConfig)`** without **`resolveScope`**.
+
+## Hono on Node (`@hono/node-ws`)
+
+**`createNodeWebSocket`** + **`sockaHonoNodeWs`** — see **[chatroom-hono](../../examples/chatroom-hono/src/server.ts)**.
+
+```ts
+import { sockaHonoNodeWs } from "@firtoz/socka/hono";
+import { createSockaRoomRegistry } from "@firtoz/socka/server";
+
+const rooms = createSockaRoomRegistry((roomId) => ({ /* config */ }));
+
+app.get("/ws/:roomId", upgradeWebSocket((c) => {
+  const room = rooms.get(c.req.param("roomId") ?? "default");
+  return sockaHonoNodeWs(room.config, { sessions: room.sessionMap })(c);
+}));
+```
+
+## Hono on Cloudflare Workers
+
+**`upgradeWebSocket`** from **`hono/cloudflare-workers`** + **`sockaHonoCloudflare`** — session often starts on first **`onMessage`**; see **[Server](./server.md#firtoz-socka-hono-cloudflare-workers)**.
+
+## Durable Objects
+
+Subclass **`SockaWebSocketDO`**, implement **`createSockaSession`** returning **`SockaDoSession`** — see **[Durable Objects](./durable-objects.md)** and **[chatroom-do](../../examples/chatroom-do/src/do.ts)**.
+
+## Client (browser)
+
+```ts
+import { SockaSession } from "@firtoz/socka/client";
+
+const session = new SockaSession({ contract: myContract, url: "wss://…/ws/room" });
+await session.send.list();
+```
+
+React: **`useSockaSession`** / **`useSocka`** / **`useSockaPresence`** — see **[Client](./client.md)**.

package/docs/reconnection.md

@@ -0,0 +1,44 @@
+# Reconnection
+
+**`SockaWebSocketClient`** and **`SockaSession`** share the same reconnect options (sessions forward them to the client).
+
+## Defaults
+
+- **`url` mode** — Reconnect is **on** with exponential backoff + jitter, **infinite** attempts, and **pause while `document.hidden`** (when **`document`** exists).
+- **Injected `webSocket`** — Reconnect is **off** by default (typical for tests). Pass an explicit **`reconnect`** object to enable it for a mocked socket.
+
+Set **`reconnect: false`** to disable entirely.
+
+## Options (`SockaReconnectConfig`)
+
+| Field | Default | Notes |
+|-------|---------|--------|
+| **`initialDelayMs`** | `1000` | First delay after a close that triggers reconnect. |
+| **`maxDelayMs`** | `30000` | Cap for the backoff curve. |
+| **`jitter`** | `0.2` | Fraction of the delay to randomize (0–1). |
+| **`maxAttempts`** | *omitted* | Omit for **infinite** attempts. |
+| **`pauseWhenHidden`** | `true` | Wait until the tab is visible again before reconnecting (browser). |
+
+Delay grows exponentially from **`initialDelayMs`** up to **`maxDelayMs`**, then jitter is applied.
+
+## Lifecycle callbacks
+
+| Callback | When |
+|----------|------|
+| **`onReconnecting`** | Before a delayed attempt is scheduled (**`attempt`**, **`delayMs`**). |
+| **`onReconnected`** | After a **new** socket reaches **`open`** following a reconnect (**`attempt`**). |
+
+Use **`onReconnected`** to **re-hydrate** client state: call **`listHistory`**, **`listPresence`**, or your own snapshot RPCs — in-memory UI state may be stale across a new socket.
+
+## Stopping the loop
+
+**`session.close()`** / **`client.close()`** performs a **manual** close: the client sets an internal flag so **abnormal-close reconnect** does not run afterward. Use this for user-driven “disconnect” or cleanup.
+
+## Pending RPCs
+
+Pending calls at disconnect time **reject** (same as without reconnect). There is no built-in queue across disconnects; re-issue work after **`onReconnected`** or **`waitForOpen()`** if needed.
+
+## See also
+
+- **[Client](./client.md)** — lifecycle and React remounting when changing URL/room.
+- **[Testing](./testing.md)** — injected **`WebSocket`** fakes in tests.

package/docs/reference.md

@@ -1,5 +1,7 @@
 # Reference
 
+User-facing **API** and **configuration**. For **wire protocol details** (frame kinds, transport layers, `decodeSockaWire`), see **[Internals](./internals.md)**.
+
 ## Type inference
 
 ```ts
@@ -14,52 +16,39 @@ type Handlers = InferSockaHandlers<
 
 **`InferSockaSend`** — Call names become methods on **`session.send`**; inputs/outputs follow the contract. **`InferSockaHandlers`** — Server handler arity matches **`calls`** (with or without `input`).
 
+### Optional output (fire-and-forget)
+
+If a call omits **`output`**, the server sends **no** **`serverResponse`** on success, and the client **`send`** method returns **`Promise<void>`** that resolves after the request is queued to the socket (not after the server runs the handler). **`output: z.void()`** keeps full request/response: the server still sends **`serverResponse`** and the client **`await`** waits for it. For output-less calls, server **`serverError`** frames include an optional **`rpc`** field so **`reportError`** can attribute failures when there is no pending promise.
+
 ## Errors and observability
 
 | Concern | Hook |
 |--------|------|
 | Exceptions inside **RPC handlers** | `onHandlerError` on `SockaWebSocketSessionConfig` / `SockaDoSessionConfig` |
 | Invalid **inbound wire** payloads (before your handler runs) | `onValidationError` on the same config |
-| Everything else ( **`onAttached`** failures, adapter I/O, **client** push listener throws, **client** push payload validation) | Optional **`reportError(event)`** on `SockaWebSocketSessionConfig`, `SockaDoSessionConfig`, or `SockaSession` / `useSockaSession` options |
+| Everything else ( **`onAttached`** failures, adapter I/O, **client** push listener throws, **client** push payload validation, **fire-and-forget RPC errors** without a pending promise) | Optional **`reportError(event)`** on `SockaWebSocketSessionConfig`, `SockaDoSessionConfig`, or `SockaSession` / `useSockaSession` options |
 
-Each **`event`** is **`SockaReportError`**: one discriminated union (`kind` narrows context; **`error`** is the thrown/rejected value; **`eventName`** / **`adapter`** where relevant). Export: **`@firtoz/socka/core`** (`defaultReportError`, `reportSockaError`). If you omit **`reportError`**, socka uses **`console.error`** with the same **`socka:`**-prefixed messages as before.
-
-## TypeScript: Durable Objects and session types
-
-`@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.
+Each **`event`** is **`SockaReportError`**: one discriminated union (`kind` narrows context; **`error`** is the thrown/rejected value where applicable; **`eventName`** / **`adapter`** where relevant). Kinds include **`clientFireAndForgetRpcError`**, **`clientOrphanServerError`**, and **`clientUnexpectedServerResponse`** for client-side RPC edge cases. Export: **`@firtoz/socka/core`** (`defaultReportError`, `reportSockaError`). If you omit **`reportError`**, socka uses **`console.error`** with the same **`socka:`**-prefixed messages as before.
 
 ## 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. |
+- Set **`wireFormat`** to the **same value** on the **client** and on **every server session** for that connection. Default is **`"json"`** (UTF-8 **text** WebSocket frames).
+- **`"msgpack"`** uses **binary** frames; use it only when **both** ends opt in.
+- **RPCs and typed pushes** share one encoding — there is no separate “push encoding.”
 
-**Rules**
+Tradeoffs (bundle size, CPU, debuggability): **[Wire format](./wire-format.md)**.
 
-- 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.
+Tables, logical frame kinds (`clientRequest`, `serverResponse`, …), and **`dispatchSockaInboundMessage`** details: **[Internals](./internals.md)**.
 
-## Logical frames (socka v1)
+## RPC handler errors
 
-Every decoded payload is one logical socka **v1** object. **`decodeSockaWire`** checks shape after `JSON.parse` (text) or msgpack unpack (binary).
+Throw **`SockaError`** from handlers when you control the **message** sent on the **`serverError`** frame. Pass optional **`code`** and **`data`** so clients can branch without parsing **`message`**:
 
-| 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.
-
-### Handler errors
+```ts
+throw new SockaError("Not allowed", { code: "FORBIDDEN", data: { reason: "…" } });
+```
 
-Throw **`SockaError`** from handlers when you control the **message** sent on the **`serverError`** frame. Any other thrown value is wrapped in **`SockaError`** using the original **`Error.message`** when possible, otherwise **`"Handler failed"`**. The client rejects the matching RPC with **`SockaError`**; the wire carries a string **message** only.
+Any other thrown value is wrapped in **`SockaError`** using the original **`Error.message`** when possible, otherwise **`"Handler failed"`**. For calls **with** **`output`**, the client rejects the matching RPC with **`SockaError`**. For **output-less** (fire-and-forget) calls, there is no pending promise; the client surfaces **`SockaError`** via **`reportError`** (`kind`: **`clientFireAndForgetRpcError`**). The wire carries **`error`** (string) plus optional **`code`**, **`data`**, and **`rpc`** (procedure name). Older peers that only read **`error`** are unchanged.
 
 ## Server session configuration
 
@@ -71,7 +60,8 @@ Throw **`SockaError`** from handlers when you control the **message** sent on th
 | **`wireFormat`** | `"json"` (default) or `"msgpack"` — must match clients. |
 | **`handlers`** | Typed call implementations; arity follows input schema (see [Getting started](./getting-started.md)). |
 | **`handleClose`** | Async per-socket teardown; runs **before** removal from `sessions` (see [Lifecycle](./lifecycle.md)). |
-| **`createData`** | Builds **`session.data`**. **`SockaWebSocketSession`**: **`(init: SockaWebSocketInit) => T`** (e.g. **`init.request`** from upgrade). **`SockaDoSession`**: **`(ctx: Context) => T`** — see **[Durable Objects](./durable-objects.md)**. |
+| **`createData`** | Builds **`session.data`**. **`SockaWebSocketSession`**: **`SockaWebSocketSessionConfig`** uses **`(init: SockaStrictWebSocketInit) => T`**; **`SockaWebSocketSessionConfigLoose`** uses **`(init: SockaWebSocketInit) => T`** — see **[Server](./server.md)**. **`SockaDoSession`**: **`(ctx: Context) => T`** — see **[Durable Objects](./durable-objects.md)**. |
+| **`SockaWebSocketSessionConfig` / `Loose` / `Union`** | Default **`SockaWebSocketSessionConfig`** is strict ( **`init.request` required** ). **`SockaWebSocketSessionConfigLoose`** sets **`strictUpgradeRequest: false`**. **`SockaWebSocketSessionConfigUnion`** is the union of strict and loose (what **`attachSockaWebSocket`** and Bun/Hono helpers accept). See **[Server — Strict upgrade request](./server.md#strict-upgrade-request)**. |
 | **`onAttached`** | Optional: after registration in `sessions` (safe for broadcasts). |
 | **`onHandlerError`** | Observes thrown errors in handlers (after optional `SockaError` wrapping for the wire). |
 | **`onValidationError`** | Inbound frame failed schema / wire decode before your handler. |
@@ -89,12 +79,16 @@ Throw **`SockaError`** from handlers when you control the **message** sent on th
 | **`autoConnect`** | Default **`true`**. If **`false`**, call **`connect()`** before **`session.send`** (or rely on implicit open from **`send`**). |
 | **`serializeJson` / `deserializeJson`** | Same as server — JSON wire mode only. |
 | **`onOpen` / `onClose` / `onError`** | WebSocket lifecycle. |
+| **`reconnect`** | **`false`** or backoff options — default **on** for **`url`**, **off** for injected **`webSocket`** unless overridden. See **[Reconnection](./reconnection.md)**. |
+| **`onReconnecting` / `onReconnected`** | Reconnect lifecycle (**`SockaWebSocketClient`** / **`SockaSession`**). |
 | **`onValidationError`** | Inbound frame failed validation (**`SockaWebSocketClient`**). |
 | **`pushHandlers`** | Initial **`session.subscribe`** subscriptions (**`SockaSession`** only). |
 | **`reportError`** | Client pipeline failures (listeners, validation); see **Errors and observability**. |
 
 **`SockaSession`** passes unrecognized options through to **`SockaWebSocketClient`** except **`pushHandlers`** and **`reportError`** (handled at the session layer). React hooks mirror these options — see **[Client](./client.md)**.
 
+**`SockaSession`** / **`SockaWebSocketClient`** also expose **`status`** and **`onStatusChange`** (connection lifecycle, reconnect UI).
+
 ## Schema libraries
 
 Anything that implements **Standard Schema v1** works — **Zod**, **Valibot**, **ArkType**, or a custom implementation. Pass schemas straight into **`defineSocka`**; no adapter helpers required.
@@ -115,7 +109,8 @@ Anything that implements **Standard Schema v1** works — **Zod**, **Valibot**,
 | `@firtoz/socka` | Same as **`@firtoz/socka/core`** — `defineSocka`, wire helpers, errors, types (prefer explicit **`/core`** in examples) |
 | `@firtoz/socka/core` | `defineSocka`, wire helpers, `SockaError`, `SockaReportError`, `reportSockaError`, types |
 | `@firtoz/socka/client` | `SockaSession`, `SockaWebSocketClient` (also re-exports `SockaReportError`, `reportSockaError`) |
-| `@firtoz/socka/react` | `useSocka`, `useSockaSession`, provider + context |
+| `@firtoz/socka/test` | `createFakeWebSocket` for unit tests — see **[Testing](./testing.md)** |
+| `@firtoz/socka/react` | `useSocka`, `useSockaSession`, `useSockaPresence`, provider + context |
 | `@firtoz/socka/do` | `SockaDoSession`, `SockaWebSocketDO` |
 | `@firtoz/socka/server` | `SockaWebSocketSession`, `attachSockaWebSocket`, `dispatchSockaInboundMessage`, `broadcastSockaEventToPeers` |
 | `@firtoz/socka/bun` | `createSockaBunWebSocketHandlers` for **`Bun.serve`** |

package/docs/server.md

@@ -42,16 +42,29 @@ attachSockaWebSocket(
 
 Optional fourth argument **`{ request }`** is passed to **`createData`** when you define per-connection state. Use **`InferSockaHandlers<typeof myContract, SockaWebSocketSession<typeof myContract, YourData>>`** (or omit the second generic and let inference fill it from your handlers).
 
-**Inbound frames without `attachSockaWebSocket`** — use **`dispatchSockaInboundMessage(session, wireFormat, data)`** with the same `data` shape as a DOM **`MessageEvent`** (`string`, **`ArrayBuffer`**, **`Blob`**, **`ArrayBufferView`**, or **`Buffer`** on Node/Bun). This is what **`attachSockaWebSocket`** uses internally.
+**Inbound frames without `attachSockaWebSocket`** — use **`dispatchSockaInboundMessage(session, wireFormat, data)`** with the same `data` shape as a DOM **`MessageEvent`**. See **[Internals](./internals.md)** for how this fits the wire pipeline.
 
 ## `createData` and session-only state
 
 | | |
 |---:|---|
-| **`createData`** runs in the **`SockaWebSocketSession`** constructor. | You receive **`SockaWebSocketInit`** (e.g. **`{ request }`** from **`attachSockaWebSocket`**). |
+| **`createData`** runs in the **`SockaWebSocketSession`** constructor. | By default you receive **`SockaStrictWebSocketInit`** ( **`init.request`** is the upgrade **`Request`** ). Set **`strictUpgradeRequest: false`** for **`SockaWebSocketInit`** when **`request`** may be missing. |
 | **Result** is stored in **`session.data`**. | Lives in **process memory** unless you persist it yourself. |
 
-Calls **with** an input schema use **`(input, session) => output`**. Calls **without** input use **`(session) => output`** only (no `undefined` first argument). The **`session`** argument is the **`SockaWebSocketSession`** instance: read **`session.data`**, call **`await session.emitPush`**, **`await session.broadcastPush`** (payloads are validated against the contract **`pushes`** schemas before send).
+## Strict upgrade request
+
+**Strict vs loose:** **`SockaWebSocketSessionConfig`** (default) requires the upgrade **`Request`**. Use **`SockaWebSocketSessionConfigLoose`** with **`strictUpgradeRequest: false`** when **`init.request`** may be missing — it does not change the wire protocol, only **`createData`** typing and runtime checks.
+
+| Mode | Type passed to **`createData`** | When to use it |
+|------|----------------------------------|----------------|
+| **Omitted** (default) | **`SockaStrictWebSocketInit`** — **`init.request` is always a `Request`** | Normal **Bun** / **Hono** upgrades and **`attachSockaWebSocket(..., { request })`**. **`createData`** can use **`new URL(init.request.url)`** and read headers. If the adapter omits **`request`**, socka throws at session construction. |
+| **`false`** | **`SockaWebSocketInit`** — **`init.request` may be `undefined`** | Tests, **Node `ws`** without a **`Request`**, or adapters that only have a bare **`WebSocket`**. Handle a missing **`request`** in **`createData`** or omit **`createData`** usage of **`init`**. |
+
+**Typical wiring:** Bun stores **`request`** on **`ServerWebSocket` `data`**; use **`sockaBunInitFromWsData`** (strict is the default). Hono **`sockaHonoNodeWs`** can omit **`sockaInit`** — the default builds a **`Request`** from the Hono context. See JSDoc on **`SockaWebSocketSessionConfig`**, **`SockaWebSocketInit`**, and **`SockaStrictWebSocketInit`** in **`@firtoz/socka/server`**.
+
+Calls **with** an input schema use **`(input, session) => …`**. Calls **without** input use **`(session) => …`** only (no `undefined` first argument). When the call has **`output`** in the contract, the handler return value is validated and sent as **`serverResponse`**. When **`output` is omitted** (fire-and-forget), the handler should return **`void`**; socka sends **no** success **`serverResponse`** (failures still become **`serverError`**). See **[Reference — Optional output (fire-and-forget)](./reference.md#optional-output-fire-and-forget)** and **[Client](./client.md)**.
+
+The **`session`** argument is the **`SockaWebSocketSession`** instance: read **`session.data`**, call **`await session.emitPush`**, **`await session.broadcastPush`** (payloads are validated against the contract **`pushes`** schemas before send).
 
 **`onAttached`** — optional. Runs after the session is registered in the shared **`sessions`** map (safe to broadcast to peers).
 
@@ -78,6 +91,7 @@ type GameData = { health: number };
 
 const session = new SockaWebSocketSession(websocket, sessions, {
   contract: gameContract,
+  strictUpgradeRequest: false,
   createData: () => ({ health: 100 }),
   handlers: {
     getHealth: async (s) => ({ health: s.data.health }),
@@ -111,6 +125,8 @@ Bun.serve({ fetch, websocket });
 
 **Multi-room** — use the overload **`createSockaBunWebSocketHandlers({ resolveScope })`** so each **`ServerWebSocket`** picks the correct **`sessionMap`** and shared **`config`** (see [Multi-room](./multi-room.md) and the tic-tac-toe example).
 
+**Upgrade query params** — `createData` only sees **`init.request`** when the adapter passes it. For Bun, merge the upgrade **`Request`** into **`ServerWebSocket` `data`** so **`?name=`** and other query params are available. Prefer **`sockaBunUpgrade(server, req, { roomId })`** from **`@firtoz/socka/bun`**, which sets **`data: { …extras, request: req }`**. Alternatively call **`server.upgrade(req, { data: { roomId, request: req } })`** yourself. **`sockaBunInitFromWsData`** reads **`data.request`** and builds **`SockaWebSocketInit`** for the session constructor.
+
 ## `@firtoz/socka/hono` (Node — `@hono/node-ws`)
 
 Use **`createNodeWebSocket`** from [**`@hono/node-ws`**](https://github.com/honojs/middleware/tree/main/packages/node-ws) with **`serve`** from **`@hono/node-server`**, then **`upgradeWebSocket(sockaHonoNodeWs({ contract, handlers, handleClose }))`**. **`sockaHonoNodeWs`** returns the callback Hono expects for **`upgradeWebSocket`**.

package/docs/testing.md

@@ -0,0 +1,20 @@
+# Testing
+
+## Client: inject a `WebSocket`
+
+In tests, pass **`webSocket`** into **`SockaSession`** or **`SockaWebSocketClient`** with a **fake implementation** of the **`WebSocket`** API (no real network). Import **`createFakeWebSocket`** from **`@firtoz/socka/test`** (same helper the package tests use). Drive **`send`** / **`subscribe`** by delivering **encoded socka frames** (JSON or msgpack per **`wireFormat`**) through the fake’s **`onmessage`** path.
+
+**Reconnect:** With an injected socket, reconnect defaults to **off**; set **`reconnect`** explicitly if you need to test backoff behavior.
+
+## Server: `SockaWebSocketSession` in isolation
+
+Construct **`SockaWebSocketSession`** with a **`SockaWebSocketSessionConfig`** and call **`handleRawMessage`** / **`dispatchSockaInboundMessage`** with encoded frames (see package tests under **`packages/socka/src/server/`**).
+
+## Integration-style
+
+The monorepo may include **`tests/socka-server-test`** (or similar) for end-to-end handler checks against a real upgrade path — run the workspace test target that applies to your change.
+
+## See also
+
+- **[Reference](./reference.md)** — client/server configuration tables.
+- **[Internals](./internals.md)** — frame shapes for manual encoding.

package/docs/wire-format.md

@@ -0,0 +1,29 @@
+# Wire format tradeoffs (JSON vs msgpack)
+
+Socka uses one **`wireFormat`** per connection for **both** RPCs and pushes (**default `"json"`**).
+
+## JSON (`"json"`)
+
+- **Pros** — Easy to debug in DevTools; text frames; no extra binary codec in the browser.
+- **Cons** — Larger payloads than msgpack for repetitive objects; UTF-8 string overhead.
+
+## MessagePack (`"msgpack"`)
+
+Implemented with **msgpackr** (bundled dependency size ~tens of kb — see your bundler report).
+
+- **Pros** — Smaller frames for structured data; binary **`ArrayBuffer`** WebSocket frames.
+- **Cons** — Harder to read in network tabs; must set **`wireFormat: "msgpack"`** on **client and server** for that connection.
+
+## Binary payloads
+
+If you send **raw binary** application data, msgpack mode is a natural fit; keep contract fields as **byte arrays** or **base64** depending on how you want to validate (Standard Schema still applies to decoded values).
+
+## Switching
+
+Set **`wireFormat: "msgpack"`** on **`SockaSession`** / **`SockaWebSocketClient`** and on **`SockaWebSocketSessionConfig`** / **`SockaDoSessionConfig`** for every session that speaks to that client.
+
+**Details:** **[Reference — Wire encoding](./reference.md#wire-encoding-json-and-msgpack)** · **[Internals](./internals.md)**.
+
+## `serverError` and `rpc`
+
+On **`serverError`** frames, **`rpc`** is an optional string naming the procedure when the failure is tied to a client RPC. Servers built on **`SockaWebSocketSession`** include it on correlated errors so clients can attribute failures without relying on a pending **`Map`** entry (needed for fire-and-forget calls that omit **`output`**). Older servers may omit **`rpc`**; clients still receive **`id`** and **`error`**.

package/examples/minimal-socka.ts

@@ -8,12 +8,59 @@ import {
 	type InferSockaHandlers,
 } from "../src/core/contract";
 
+const messageRow = z.object({
+	id: z.string(),
+	ts: z.number(),
+	userId: z.string(),
+	displayName: z.string(),
+	text: z.string(),
+});
+
+const onlineUser = z.object({
+	userId: z.string(),
+	displayName: z.string(),
+});
+
 const contract = defineSocka({
 	calls: {
-		echo: {
+		sendMessage: {
 			input: z.object({ text: z.string() }),
-			output: z.object({ text: z.string() }),
+			output: z.object({ ok: z.literal(true) }),
 		},
+		listHistory: {
+			input: z.object({ limit: z.number().optional() }),
+			output: z.object({ messages: z.array(messageRow) }),
+		},
+		listPresence: {
+			input: z.object({}).optional(),
+			output: z.object({
+				selfUserId: z.string(),
+				users: z.array(onlineUser),
+			}),
+		},
+		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: z.object({
+			id: z.string(),
+			ts: z.number(),
+			userId: z.string(),
+			displayName: z.string(),
+			text: z.string(),
+		}),
+		historyCleared: z.object({
+			ts: z.number(),
+			clearedByUserId: z.string(),
+			clearedByDisplayName: z.string(),
+		}),
 	},
 });
 
@@ -23,7 +70,13 @@ type Handlers = InferSockaHandlers<typeof contract, unknown>;
 void (async () => {
 	const _send: Send = {} as Send;
 	const _handlers: Handlers = {
-		echo: async (input) => ({ text: input.text }),
+		sendMessage: async () => ({ ok: true }),
+		listHistory: async () => ({ messages: [] }),
+		listPresence: async () => ({
+			selfUserId: "demo-user",
+			users: [{ userId: "demo-user", displayName: "Demo" }],
+		}),
+		clearHistory: async () => ({ ok: true }),
 	};
 	void _send;
 	void _handlers;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/socka",
-	"version": "2.0.0",
+	"version": "3.0.0",
 	"type": "module",
 	"description": "Standard Schema–first WebSocket RPC for TypeScript — Bun, Hono, Node ws, Cloudflare Workers, Durable Objects",
 	"main": "./dist/core/index.js",
@@ -42,6 +42,10 @@
 		"./hono/cloudflare": {
 			"types": "./dist/hono/cloudflare-workers.d.ts",
 			"import": "./dist/hono/cloudflare-workers.js"
+		},
+		"./test": {
+			"types": "./dist/test/index.d.ts",
+			"import": "./dist/test/index.js"
 		}
 	},
 	"files": [
@@ -92,17 +96,17 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/maybe-error": "^1.6.0",
+		"@firtoz/maybe-error": "^1.6.1",
 		"@standard-schema/spec": "^1.1.0",
 		"msgpackr": "^1.11.9"
 	},
 	"peerDependencies": {
-		"@cloudflare/workers-types": "^4.20260329.1",
+		"@cloudflare/workers-types": "^4.20260416.2",
 		"@firtoz/websocket-do": "^13.0.0",
 		"@hono/node-server": "^1.19.2",
 		"@hono/node-ws": "^1.3.0",
 		"hono": "^4.12.9",
-		"react": "^19.2.4",
+		"react": "^19.2.5",
 		"ws": "^8.18.0"
 	},
 	"peerDependenciesMeta": {
@@ -129,17 +133,17 @@
 		}
 	},
 	"devDependencies": {
-		"@cloudflare/workers-types": "^4.20260329.1",
-		"@happy-dom/global-registrator": "^20.8.9",
-		"@hono/node-server": "^1.19.2",
+		"@cloudflare/workers-types": "^4.20260416.2",
+		"@happy-dom/global-registrator": "^20.9.0",
+		"@hono/node-server": "^1.19.14",
 		"@hono/node-ws": "^1.3.0",
 		"@tanstack/intent": "^0.0.29",
 		"@testing-library/react": "^16.3.2",
 		"@types/react": "^19.2.14",
 		"@types/ws": "^8.18.1",
-		"bun-types": "^1.3.11",
-		"happy-dom": "^20.8.9",
-		"react-dom": "19.2.4",
+		"bun-types": "^1.3.12",
+		"happy-dom": "^20.9.0",
+		"react-dom": "19.2.5",
 		"tsup": "^8.5.1",
 		"typescript": "^6.0.2",
 		"valibot": "^1.3.1",

package/roadmap.md

@@ -1,8 +1,8 @@
-# Roadmap (post–socka v1)
+# Roadmap
 
 Deferred work and ideas—not a commitment order.
 
 - **npm metadata** — Keywords, README polish, and release notes that match positioning (WebSocket RPC, Standard Schema, Durable Objects).
-- **Release communication** — Short announcement (optional blog or dev.to), comparison vs hand-rolled protocols and adjacent tools.
+- **Release communication** — Short announcement (optional blog or dev.to), comparison vs custom protocols and adjacent tools.
 - **`create-socka-app` / `bun create`** — After the public API is stable enough, a scaffold for contract + client + server/DO choice.
 - **Ecosystem** — Tutorials, Stack Overflow presence, example repos as the community asks.

package/skills/socka/core-rpc/SKILL.md

@@ -7,7 +7,7 @@ description: Standard Schema socka contracts (defineSocka), v1 wire envelopes, S
 
 ## Contract
 
-- **`defineSocka`** in **`@firtoz/socka/core`**: pass **`calls`** (and optional **`pushes`**) with **`StandardSchemaV1`** `input` / `output` per call. Types flow from **`InferSockaSend`**, **`InferSockaHandlers`**, **`InferSockaPushHandlers`**.
+- **`defineSocka`** in **`@firtoz/socka/core`**: pass **`calls`** (and optional **`pushes`**) with **`StandardSchemaV1`** `input` and optional **`output`** per call. Omit **`output`** for fire-and-forget (no **`serverResponse`** on success; client **`send`** resolves after send; failures use **`serverError`** + **`reportError`**). Use **`output: z.void()`** for a correlated ACK. Types flow from **`InferSockaSend`**, **`InferSockaHandlers`**, **`InferSockaPushHandlers`**.
 - There is **no** `defineSockaProtocol` / `defineSockaRpcSpec` in socka—those names belong to other stacks; use **`defineSocka`** only.
 
 ## Browser client
@@ -24,7 +24,7 @@ description: Standard Schema socka contracts (defineSocka), v1 wire envelopes, S
 ## Wire
 
 - Every frame is a **socka v1** object validated by **`decodeSockaWire`** (`socka`, **`v`**, discriminators, **`id`**, **`rpc`**, **`body`**, …). Invalid payloads become **`SockaWireError`** (or **`onValidationError`** on the client).
-- RPC success → **`serverResponse`**; RPC failure → **`serverError`**; server pushes → **`serverEvent`** with event name + **`body`**.
+- RPC success → **`serverResponse`** (unless the call omits **`output`**, then no success frame); RPC failure → **`serverError`** (optional **`rpc`** field for procedure name); server pushes → **`serverEvent`** with event name + **`body`**.
 - **JSON vs msgpack** is a transport choice only; the logical shape is identical. **Client and DO must use the same `wireFormat`.**
 
 ## Durable Objects

package/skills/socka/do-session/SKILL.md

@@ -7,7 +7,7 @@ description: SockaDoSession and SockaWebSocketDO on Cloudflare Durable Objects
 
 ## Components
 
-- **`SockaDoSession`** (**`@firtoz/socka/do`**): extends **`BaseSession`** from **`@firtoz/websocket-do`**. Incoming messages are decoded with **`decodeSockaWire`** after JSON parse (text) or **`parseWirePayload`** (msgpack). Valid **`clientRequest`** frames are dispatched to **`handlers`** (typed **`InferSockaHandlers<typeof contract>`**). Responses use **`encodeServerResponse`** / **`encodeServerError`**; optional **`encodeServerEvent`** for contract pushes.
+- **`SockaDoSession`** (**`@firtoz/socka/do`**): extends **`BaseSession`** from **`@firtoz/websocket-do`**. Incoming messages are decoded with **`decodeSockaWire`** after JSON parse (text) or **`parseWirePayload`** (msgpack). Valid **`clientRequest`** frames are dispatched to **`handlers`** (typed **`InferSockaHandlers<typeof contract>`**). Calls **with** **`output`** get **`encodeServerResponse`** on success; calls **without** **`output`** send **`encodeServerError`** only on failure; optional **`encodeServerEvent`** for contract pushes.
 - **`SockaWebSocketDO`**: thin **`BaseWebSocketDO`** wrapper; you supply **`createSockaSession(ctx, websocket)`** returning a **`SockaDoSession`** (or subclass).
 
 ## Session config (`SockaDoSessionConfig`)
@@ -15,7 +15,7 @@ description: SockaDoSession and SockaWebSocketDO on Cloudflare Durable Objects
 - **`contract`**: from **`defineSocka`**.
 - **`wireFormat`**: **`"json"`** (default) or **`"msgpack"`**—must match the browser **`SockaWebSocketClient`/`SockaSession`** **`wireFormat`**.
 - **`createData`**: optional when session **`TData`** is empty (**`Record<string, never>`**); defaults to **`{}`**. Otherwise Hono **`Context`** → per-connection state.
-- **`handlers`**: call name → async/sync handler; inputs/outputs validated with Standard Schema via **`parseStandardSchema`**.
+- **`handlers`**: call name → async/sync handler; inputs and optional outputs validated with Standard Schema via **`parseStandardSchema`** (omit **`output`** in the contract for fire-and-forget success; handler still runs on the server).
 - **`handleClose`**: cleanup when the socket closes.
 - **`onHandlerError`**, **`onValidationError`**: optional hooks (validation and handler failures are also mapped to **`serverError`** frames).
 - **`serializeJson`**, **`deserializeJson`**: optional; default **`JSON.stringify`/`JSON.parse`** for JSON mode.

package/skills/socka/standard-schema/SKILL.md

@@ -7,7 +7,7 @@ description: Standard Schema v1 for socka contracts and wire validation—Zod, V
 
 ## When to use
 
-You define **call** `input` / `output` (and optional **push** payloads) for **`@firtoz/socka/core`**, **`@firtoz/socka/client`**, **`@firtoz/socka/react`**, and **`@firtoz/socka/do`**. Every schema slot expects **`StandardSchemaV1`** from **`@standard-schema/spec`** so callers can use **Zod**, **Valibot**, **ArkType**, etc., without socka-specific adapters.
+You define **call** `input` and optional **`output`** (and optional **push** payloads) for **`@firtoz/socka/core`**, **`@firtoz/socka/client`**, **`@firtoz/socka/react`**, and **`@firtoz/socka/do`**. Omit **`output`** only for intentional fire-and-forget success semantics; **`output`** slots that are present use **`StandardSchemaV1`** from **`@standard-schema/spec`** so callers can use **Zod**, **Valibot**, **ArkType**, etc., without socka-specific adapters.
 
 ## Rules