@firtoz/socka 2.0.0

package/docs/multi-room.md

@@ -0,0 +1,31 @@
+# Multi-room
+
+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)**.
+
+**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.”
+- **`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. |
+| **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).
+
+## Pitfalls
+
+- **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.
+
+See also [Lifecycle](./lifecycle.md) and [Server](./server.md) for **`createData`** and **`session.data`**.

package/docs/peers.md

@@ -0,0 +1,85 @@
+# Peers
+
+Install **`@firtoz/socka`** first, then add **only** the peers for the code paths you import.
+
+## Pick your flow, then install
+
+Choose one row and install for your app (`npm install`, `pnpm add`, `bun add`, etc.). Adjust versions to match your stack.
+
+### Browser or Vite SPA (client only)
+
+You use **`@firtoz/socka/client`** (and maybe **`@firtoz/socka/core`** for types). No server adapters. **No Cloudflare types required**—standard DOM / `lib` typings are enough for `WebSocket`.
+
+```bash
+npm install @firtoz/socka
+```
+
+### React client (`@firtoz/socka/react`)
+
+```bash
+npm install @firtoz/socka react
+```
+
+Add **`@types/react`** as a dev dependency if TypeScript asks for them.
+
+### Node + Hono + `@hono/node-ws` (`@firtoz/socka/hono`)
+
+```bash
+npm install @firtoz/socka hono @hono/node-ws @hono/node-server ws
+```
+
+Add **`@types/ws`** as a dev dependency when you use the **`ws`** package on Node.
+
+### Bun + `Bun.serve` (`@firtoz/socka/bun`)
+
+```bash
+npm install @firtoz/socka
+```
+
+Add **`bun-types`** as a dev dependency for TypeScript if you type-check Bun APIs.
+
+### Cloudflare Workers + Hono upgrade (`@firtoz/socka/hono/cloudflare`)
+
+```bash
+npm install @firtoz/socka hono @cloudflare/workers-types
+```
+
+### Cloudflare Durable Objects (`@firtoz/socka/do`)
+
+```bash
+npm install @firtoz/socka hono @firtoz/websocket-do @cloudflare/workers-types
+```
+
+**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`)
+
+```bash
+npm install @firtoz/socka ws
+```
+
+Add **`@types/ws`** as a dev dependency when you use **`ws`** on Node. (Omit **`ws`** if your runtime already provides a typed **`WebSocket`**.)
+
+---
+
+`@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.
+
+**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.
+- **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)
+
+| Entry | Required peers | Why |
+|--------|----------------|-----|
+| `@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/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)**). |

package/docs/reference.md

@@ -0,0 +1,123 @@
+# Reference
+
+## Type inference
+
+```ts
+import type { InferSockaSend, InferSockaHandlers } from "@firtoz/socka/core";
+
+type Send = InferSockaSend<typeof myContract>;
+type Handlers = InferSockaHandlers<
+  typeof myContract,
+  SockaWebSocketSession<typeof myContract>
+>;
+```
+
+**`InferSockaSend`** — Call names become methods on **`session.send`**; inputs/outputs follow the contract. **`InferSockaHandlers`** — Server handler arity matches **`calls`** (with or without `input`).
+
+## 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 |
+
+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.
+
+## 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.
+
+### Handler errors
+
+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.
+
+## Server session configuration
+
+**`SockaWebSocketSessionConfig`** (`@firtoz/socka/server`, Bun, Hono) and **`SockaDoSessionConfig`** (`@firtoz/socka/do`) share the same fields except **`createData`** (see below).
+
+| Field | Purpose |
+|--------|---------|
+| **`contract`** | `defineSocka(...)` — `calls`, optional `pushes`. |
+| **`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)**. |
+| **`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. |
+| **`reportError`** | Non-RPC failures (`onAttached`, adapters, …); see **Errors and observability** above. |
+| **`serializeJson` / `deserializeJson`** | Replace JSON stringify/parse for **JSON wire mode** only. |
+
+## Client configuration
+
+| Field | Purpose |
+|--------|---------|
+| **`contract`** | Same module reference as the server. |
+| **`url`** | `new WebSocket(url)` when **`webSocket`** is omitted. |
+| **`webSocket`** | Inject an existing socket (tests or custom setup); **`url`** not required if set. |
+| **`wireFormat`** | Must match the server session (**default `"json"`**). |
+| **`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. |
+| **`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)**.
+
+## 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.
+
+## At a glance
+
+| | |
+|---:|---|
+| **Contract** | `defineSocka({ calls, pushes? })` — Zod, Valibot, ArkType, or any [Standard Schema v1](https://standardschema.dev/) |
+| **Client** | `SockaSession` / `useSockaSession` / `SockaSessionProvider` + `useSockaSessionContext` |
+| **Server** | `SockaDoSession` + `SockaWebSocketDO` on Durable Objects, or **`@firtoz/socka/server`** / **`@firtoz/socka/bun`** / **`@firtoz/socka/hono`** on any supported runtime |
+| **Wire** | JSON text frames by default; optional **msgpack** binary — same logical frames, both ends must use the same `wireFormat` |
+
+### Imports
+
+| Path | Use for |
+|------|---------|
+| `@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/do` | `SockaDoSession`, `SockaWebSocketDO` |
+| `@firtoz/socka/server` | `SockaWebSocketSession`, `attachSockaWebSocket`, `dispatchSockaInboundMessage`, `broadcastSockaEventToPeers` |
+| `@firtoz/socka/bun` | `createSockaBunWebSocketHandlers` for **`Bun.serve`** |
+| `@firtoz/socka/hono` | `sockaHonoNodeWs` for **`@hono/node-ws`** |
+| `@firtoz/socka/hono/cloudflare` | `sockaHonoCloudflare` for **`hono/cloudflare-workers`** |

package/docs/server.md

@@ -0,0 +1,124 @@
+# Server: Node, Bun, Hono, and ws
+
+This guide is for a **normal WebSocket** in your own process: **Node** (including the **`ws`** package), **Bun** **`Bun.serve`**, **Hono** on Node (**`@hono/node-ws`**) or on **Cloudflare Workers** (**`hono/cloudflare-workers`**). You supply **`contract`**, **`handlers`**, and **`handleClose`**; socka decodes frames, validates inputs, and dispatches RPCs.
+
+**Cloudflare Durable Objects** ( **`SockaDoSession`**, **`SockaWebSocketDO`** ) are covered in **[Durable Objects](./durable-objects.md)**.
+
+With **`@firtoz/socka/server`**, pass a **`SockaWebSocketSessionConfig`** and wire the socket with **`attachSockaWebSocket`**, or call **`dispatchSockaInboundMessage`**, **`handleRawMessage`**, or **`handleBinaryMessage`** on **`SockaWebSocketSession`** yourself if you already handle **`message`** events.
+
+### `wireFormat` and session config
+
+The third argument to **`attachSockaWebSocket`** is a **`SockaWebSocketSessionConfig`**: at minimum **`contract`**, **`handlers`**, and **`handleClose`**. Optional **`wireFormat`** defaults to **`"json"`** (UTF-8 **text** WebSocket frames). Use **`wireFormat: "msgpack"`** only if clients use the same mode (**binary** frames). Optional **`serializeJson` / `deserializeJson`** customize JSON encoding of the **outer envelope** (not a substitute for matching `wireFormat`). Full field list: **[Reference — Server session configuration](./reference.md#server-session-configuration)**.
+
+```ts
+import {
+  attachSockaWebSocket,
+  type SockaWebSocketSession,
+} from "@firtoz/socka/server";
+import { myContract } from "./contract";
+
+const sessions = new Map<
+  WebSocket,
+  SockaWebSocketSession<typeof myContract>
+>();
+
+// After the upgrade (shape depends on runtime — see below):
+attachSockaWebSocket(
+  websocket,
+  sessions,
+  {
+    contract: myContract,
+    handlers: {
+      list: async (session) => fetchMessages(),
+      insert: async (input, session) => saveMessage(input.message),
+    },
+    handleClose: async (session) => {
+      // cleanup for this socket; session is still in `sessions` during the call
+    },
+  },
+  { request: upgradeRequest },
+);
+```
+
+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.
+
+## `createData` and session-only state
+
+| | |
+|---:|---|
+| **`createData`** runs in the **`SockaWebSocketSession`** constructor. | You receive **`SockaWebSocketInit`** (e.g. **`{ request }`** from **`attachSockaWebSocket`**). |
+| **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).
+
+**`onAttached`** — optional. Runs after the session is registered in the shared **`sessions`** map (safe to broadcast to peers).
+
+**Example — `session.data`:**
+
+```ts
+import { defineSocka } from "@firtoz/socka/core";
+import { SockaWebSocketSession } from "@firtoz/socka/server";
+import * as z from "zod";
+
+const gameContract = defineSocka({
+  calls: {
+    getHealth: {
+      output: z.object({ health: z.number() }),
+    },
+    damage: {
+      input: z.object({ amount: z.number() }),
+      output: z.object({ health: z.number() }),
+    },
+  },
+});
+
+type GameData = { health: number };
+
+const session = new SockaWebSocketSession(websocket, sessions, {
+  contract: gameContract,
+  createData: () => ({ health: 100 }),
+  handlers: {
+    getHealth: async (s) => ({ health: s.data.health }),
+    damage: async (input, s) => {
+      s.data.health = Math.max(0, s.data.health - input.amount);
+      return { health: s.data.health };
+    },
+  },
+  handleClose: async (session) => {
+    // optional per-socket cleanup
+  },
+});
+sessions.set(websocket, session);
+```
+
+## `@firtoz/socka/bun` (Bun.serve)
+
+**Bun** `Bun.serve` uses **`ServerWebSocket`**, which does **not** implement **`addEventListener`**, so **`attachSockaWebSocket`** does not apply. Use **`createSockaBunWebSocketHandlers`** and pass the returned **`websocket`** into **`Bun.serve`**:
+
+```ts
+import { createSockaBunWebSocketHandlers } from "@firtoz/socka/bun";
+
+const { websocket } = createSockaBunWebSocketHandlers({
+  contract: myContract,
+  handlers: { /* ... */ },
+  handleClose: async (session) => {},
+});
+
+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).
+
+## `@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`**.
+
+## `@firtoz/socka/hono/cloudflare` (Workers)
+
+Use **`upgradeWebSocket`** from **`hono/cloudflare-workers`** with **`sockaHonoCloudflare({ contract, handlers, handleClose })`**. The session is created on the first **`onMessage`** (Workers helpers omit **`onOpen`**).
+
+**Node with [`ws`](https://github.com/websockets/ws)** — in the **`connection`** handler, pass the socket into **`attachSockaWebSocket`**. The `ws` package’s socket is not always identical to the browser **`WebSocket`** type; if TypeScript complains, cast to the global **`WebSocket`** type your build targets. **`attachSockaWebSocket`** and **`dispatchSockaInboundMessage`** accept JSON frames delivered as UTF-8 **`ArrayBuffer`** slices (some runtimes send text that way) as well as strings.
+
+**Integration tests in this repo:** [`tests/socka-server-test`](https://github.com/firtoz/fullstack-toolkit/tree/main/tests/socka-server-test) (Node **`ws`**, **Bun.serve**, **Hono + `@hono/node-ws`**).

package/examples/minimal-socka.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal runnable example: `bun run example:minimal` from `packages/socka`.
+ */
+import * as z from "zod";
+import {
+	defineSocka,
+	type InferSockaSend,
+	type InferSockaHandlers,
+} from "../src/core/contract";
+
+const contract = defineSocka({
+	calls: {
+		echo: {
+			input: z.object({ text: z.string() }),
+			output: z.object({ text: z.string() }),
+		},
+	},
+});
+
+type Send = InferSockaSend<typeof contract>;
+type Handlers = InferSockaHandlers<typeof contract, unknown>;
+
+void (async () => {
+	const _send: Send = {} as Send;
+	const _handlers: Handlers = {
+		echo: async (input) => ({ text: input.text }),
+	};
+	void _send;
+	void _handlers;
+	console.log("minimal socka types OK");
+})();

package/package.json

@@ -0,0 +1,148 @@
+{
+	"name": "@firtoz/socka",
+	"version": "2.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",
+	"module": "./dist/core/index.js",
+	"types": "./dist/core/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/core/index.d.ts",
+			"import": "./dist/core/index.js"
+		},
+		"./core": {
+			"types": "./dist/core/index.d.ts",
+			"import": "./dist/core/index.js"
+		},
+		"./client": {
+			"types": "./dist/client/index.d.ts",
+			"import": "./dist/client/index.js"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.ts",
+			"import": "./dist/react/index.js"
+		},
+		"./do": {
+			"types": "./dist/do/index.d.ts",
+			"import": "./dist/do/index.js"
+		},
+		"./server": {
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js"
+		},
+		"./bun": {
+			"types": "./dist/bun/index.d.ts",
+			"import": "./dist/bun/index.js"
+		},
+		"./hono": {
+			"types": "./dist/hono/index.d.ts",
+			"import": "./dist/hono/index.js"
+		},
+		"./hono/cloudflare": {
+			"types": "./dist/hono/cloudflare-workers.d.ts",
+			"import": "./dist/hono/cloudflare-workers.js"
+		}
+	},
+	"files": [
+		"dist/**/*.js",
+		"dist/**/*.js.map",
+		"dist/**/*.d.ts",
+		"examples/**/*.ts",
+		"skills",
+		"docs/**/*.md",
+		"assets/banner.png",
+		"README.md",
+		"roadmap.md"
+	],
+	"scripts": {
+		"build": "tsup",
+		"prepack": "bun run build",
+		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
+		"example:minimal": "bun ./examples/minimal-socka.ts",
+		"test": "bun test",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src && bun run intent:validate",
+		"format": "biome format src --write",
+		"intent:validate": "intent validate"
+	},
+	"keywords": [
+		"websocket",
+		"rpc",
+		"standard-schema",
+		"durable-objects",
+		"cloudflare",
+		"tanstack-intent"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/socka"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@firtoz/maybe-error": "^1.6.0",
+		"@standard-schema/spec": "^1.1.0",
+		"msgpackr": "^1.11.9"
+	},
+	"peerDependencies": {
+		"@cloudflare/workers-types": "^4.20260329.1",
+		"@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",
+		"ws": "^8.18.0"
+	},
+	"peerDependenciesMeta": {
+		"@cloudflare/workers-types": {
+			"optional": true
+		},
+		"@firtoz/websocket-do": {
+			"optional": true
+		},
+		"@hono/node-server": {
+			"optional": true
+		},
+		"@hono/node-ws": {
+			"optional": true
+		},
+		"hono": {
+			"optional": true
+		},
+		"react": {
+			"optional": true
+		},
+		"ws": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20260329.1",
+		"@happy-dom/global-registrator": "^20.8.9",
+		"@hono/node-server": "^1.19.2",
+		"@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",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.2",
+		"valibot": "^1.3.1",
+		"zod": "^4.3.6"
+	}
+}

package/roadmap.md

@@ -0,0 +1,8 @@
+# Roadmap (post–socka v1)
+
+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.
+- **`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

@@ -0,0 +1,36 @@
+---
+name: socka/core-rpc
+description: Standard Schema socka contracts (defineSocka), v1 wire envelopes, SockaSession/SockaWebSocketClient, React useSockaSession and SockaSessionProvider, SockaError.
+---
+
+# Socka core: RPC
+
+## Contract
+
+- **`defineSocka`** in **`@firtoz/socka/core`**: pass **`calls`** (and optional **`pushes`**) with **`StandardSchemaV1`** `input` / `output` per call. Types flow from **`InferSockaSend`**, **`InferSockaHandlers`**, **`InferSockaPushHandlers`**.
+- There is **no** `defineSockaProtocol` / `defineSockaRpcSpec` in socka—those names belong to other stacks; use **`defineSocka`** only.
+
+## Browser client
+
+- **`SockaWebSocketClient`** / **`SockaSession`** in **`@firtoz/socka/client`**: constructed with **`contract`**, **`url`** or **`webSocket`**, optional **`wireFormat`**: **`"json"`** (default, text frames) or **`"msgpack"`** (binary `ArrayBuffer`—must match the server). Optional **`pushHandlers`** for server **`serverEvent`** frames (typed from the contract). On **`SockaSession`**, call contract methods as **`await session.send.echo(...)`** (same shape as **`useSockaSession`**’s **`send`**); use **`session.subscribe`** for push subscriptions.
+- **`SockaError`**: thrown on correlated RPC failures when using **`SockaSession`** (check **`instanceof SockaError`**).
+
+## React
+
+- **`useSockaSession(contract, options, deps)`** in **`@firtoz/socka/react`**: returns **`{ ready, send, sessionRef }`**. **`send`** exposes typed call methods (e.g. **`send.list()`**). Pass **`pushHandlers`** in **`options`** for contract **pushes** (not a separate “server push” table).
+- **`useSocka(options, deps)`**: lower level; **`sessionRef`** to **`SockaSession`** if you build **`send`** yourself.
+- **Single shared socket**: wrap the tree with **`SockaSessionProvider`** (same props as **`useSockaSession`** plus **`children`**), then call **`useSockaSessionContext(contract)`** in descendants. Pass the **same `contract` reference** as the provider; the hook checks reference equality.
+
+## 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`**.
+- **JSON vs msgpack** is a transport choice only; the logical shape is identical. **Client and DO must use the same `wireFormat`.**
+
+## Durable Objects
+
+- **`SockaDoSession`** / **`SockaWebSocketDO`** in **`@firtoz/socka/do`**—see **`@firtoz/socka/do-session`** skill.
+
+## Low-level
+
+- Use **`@firtoz/socka/core`** helpers (**`encodeClientRequest`**, **`decodeSockaWire`**, **`encodeSockaWire`**, **`parseWirePayload`**) only if you bypass **`SockaSession`** / **`SockaDoSession`**.

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

@@ -0,0 +1,33 @@
+---
+name: socka/do-session
+description: SockaDoSession and SockaWebSocketDO on Cloudflare Durable Objects—contract, handlers, wireFormat, SockaError; extends websocket-do BaseSession.
+---
+
+# Socka 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.
+- **`SockaWebSocketDO`**: thin **`BaseWebSocketDO`** wrapper; you supply **`createSockaSession(ctx, websocket)`** returning a **`SockaDoSession`** (or subclass).
+
+## Session config (`SockaDoSessionConfig`)
+
+- **`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`**.
+- **`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.
+
+## Errors
+
+- Throw **`SockaError`** from handlers for domain failures; the session maps the message to a **`serverError`** frame so the client can **`instanceof SockaError`** when using **`SockaSession`**.
+
+## Client parity
+
+- Same **`defineSocka`** contract on the client: **`useSockaSession`**, **`SockaSessionProvider`**, or **`SockaSession`** with matching **`wireFormat`**.
+
+## Transport
+
+- Raw WebSocket lifecycle stays in **`@firtoz/websocket-do`**. Socka adds schema validation and socka v1 framing at the session boundary. Do **not** re-export websocket-do symbols from socka—import **`BaseWebSocketDO`** / **`BaseSession`** from **`@firtoz/websocket-do`** when you need them.