@firtoz/socka 2.0.0

package/dist/socka-report-error-DzFI2Tr7.d.ts

@@ -0,0 +1,206 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * Call names that cannot be used in {@link defineSocka} `calls` because they would
+ * make {@link SockaSession} `send` look Promise-like or clash with ordinary object
+ * shape (`constructor`, `Object.prototype`). Call names live only under `send`, so
+ * session fields like `client` / `close` need not be reserved.
+ */
+declare const RESERVED_SOCKA_PROCEDURE_NAMES: readonly ["then", "catch", "finally", "constructor", "toString", "valueOf", "toLocaleString", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable"];
+/** Union of {@link RESERVED_SOCKA_PROCEDURE_NAMES}. */
+type ReservedSockaProcedureName = (typeof RESERVED_SOCKA_PROCEDURE_NAMES)[number];
+
+/**
+ * Defines one client-initiated call: an optional input schema and a required output schema.
+ * Both must be Standard Schema v1 compliant (Zod v4, Valibot, ArkType, etc.).
+ */
+type SockaProcedureDef = {
+    readonly input?: StandardSchemaV1;
+    readonly output: StandardSchemaV1;
+};
+/** Configuration object accepted by {@link defineSocka}. */
+type SockaContractConfig = {
+    readonly calls: Record<string, SockaProcedureDef>;
+    readonly pushes?: Record<string, StandardSchemaV1>;
+};
+/**
+ * When call keys are a **narrow** object type, rejects keys in
+ * {@link ReservedSockaProcedureName} (thenable / `Object.prototype` hazards on
+ * `session.send`). Wide `Record<string, SockaProcedureDef>` is unchanged so
+ * dynamic maps still typecheck; use runtime validation (see {@link SockaSession}
+ * `send`).
+ */
+type ValidateSockaCallKeys<P extends Record<string, SockaProcedureDef>> = string extends keyof P ? P : keyof P & ReservedSockaProcedureName extends never ? P : never;
+/** Runtime contract returned by {@link defineSocka}, preserving full generic types. */
+type SockaContract<T extends SockaContractConfig = SockaContractConfig> = {
+    readonly calls: T["calls"];
+    readonly pushes: T extends {
+        pushes: Record<string, StandardSchemaV1>;
+    } ? T["pushes"] : Record<string, never>;
+};
+type CallFn<P extends SockaProcedureDef> = P extends {
+    input: infer I extends StandardSchemaV1;
+} ? (input: StandardSchemaV1.InferInput<I>) => Promise<StandardSchemaV1.InferOutput<P["output"]>> : () => Promise<StandardSchemaV1.InferOutput<P["output"]>>;
+/**
+ * Infers the typed `session.send.*` method map for a contract.
+ */
+type InferSockaSend<C extends SockaContract> = {
+    [K in keyof C["calls"]]: CallFn<C["calls"][K]>;
+};
+type HandlerOut<P extends SockaProcedureDef> = StandardSchemaV1.InferOutput<P["output"]> | Promise<StandardSchemaV1.InferOutput<P["output"]>>;
+type HandlerFn<P extends SockaProcedureDef, TSession> = P extends {
+    input: infer I extends StandardSchemaV1;
+} ? (input: StandardSchemaV1.InferInput<I>, session: TSession) => HandlerOut<P> : (session: TSession) => HandlerOut<P>;
+/**
+ * Infers the typed server handler map for a contract. Handlers with an input
+ * schema take `(input, session)`; calls without input take `(session)` only.
+ * Each handler returns the output that will be validated before sending.
+ */
+type InferSockaHandlers<C extends SockaContract, TSession> = {
+    [K in keyof C["calls"]]: HandlerFn<C["calls"][K], TSession>;
+};
+type InferPushPayload<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+/**
+ * Payload type for a contract push (output of the push's Standard Schema).
+ */
+type InferSockaPushPayload<C extends SockaContract<SockaContractConfig>, K extends keyof C["pushes"]> = C["pushes"][K] extends StandardSchemaV1 ? InferPushPayload<C["pushes"][K]> : never;
+/**
+ * Infers the typed push subscription handler map for a contract's `pushes`.
+ */
+type InferSockaPushHandlers<C extends SockaContract> = {
+    [K in keyof C["pushes"]]: C["pushes"][K] extends StandardSchemaV1 ? (payload: InferPushPayload<C["pushes"][K]>) => void | Promise<void> : never;
+};
+/**
+ * Creates a socka contract from call and push definitions. Pass Zod, Valibot,
+ * ArkType, or any Standard Schema v1 schemas directly — no adapters needed.
+ *
+ * ```ts
+ * export const myContract = defineSocka({
+ *   calls: {
+ *     list: { output: z.array(itemSchema) },
+ *     insert: { input: z.object({ item: itemSchema }), output: z.void() },
+ *   },
+ * });
+ * ```
+ *
+ * Call names must not be {@link ReservedSockaProcedureName} — they would make
+ * `session.send` thenable or unsafe as a plain method bag.
+ */
+declare function defineSocka<const T extends SockaContractConfig>(config: T & {
+    calls: ValidateSockaCallKeys<T["calls"]>;
+}): SockaContract<T>;
+
+/**
+ * Versioned socka wire framing. After JSON parse or msgpack unpack, every frame
+ * must satisfy {@link decodeSockaWire}; procedure bodies are validated with Standard Schema on each side.
+ */
+declare const SOCKA_WIRE_VERSION: 1;
+declare class SockaWireError extends Error {
+    readonly name = "SockaWireError";
+}
+type SockaClientRequestFrame = {
+    readonly socka: "clientRequest";
+    readonly v: typeof SOCKA_WIRE_VERSION;
+    readonly id: string;
+    readonly rpc: string;
+    readonly body: Record<string, unknown>;
+};
+type SockaServerResponseFrame = {
+    readonly socka: "serverResponse";
+    readonly v: typeof SOCKA_WIRE_VERSION;
+    readonly id: string;
+    readonly rpc: string;
+    readonly body: unknown;
+};
+type SockaServerErrorFrame = {
+    readonly socka: "serverError";
+    readonly v: typeof SOCKA_WIRE_VERSION;
+    readonly id: string;
+    readonly error: string;
+};
+type SockaServerEventFrame = {
+    readonly socka: "serverEvent";
+    readonly v: typeof SOCKA_WIRE_VERSION;
+    readonly event: string;
+    readonly body: unknown;
+};
+type SockaWireFrame = SockaClientRequestFrame | SockaServerResponseFrame | SockaServerErrorFrame | SockaServerEventFrame;
+type DecodedSockaWire = {
+    readonly kind: "clientRequest";
+    readonly frame: SockaClientRequestFrame;
+} | {
+    readonly kind: "serverResponse";
+    readonly frame: SockaServerResponseFrame;
+} | {
+    readonly kind: "serverError";
+    readonly frame: SockaServerErrorFrame;
+} | {
+    readonly kind: "serverEvent";
+    readonly frame: SockaServerEventFrame;
+};
+/**
+ * Decodes a parsed wire object (from JSON or msgpack). Throws {@link SockaWireError}
+ * if the payload is not a valid socka v1 frame.
+ */
+declare function decodeSockaWire(parsed: unknown): DecodedSockaWire;
+/** Builds a socka v1 client request frame. */
+declare function encodeClientRequest(id: string, rpc: string, body: Record<string, unknown>): SockaClientRequestFrame;
+/** Builds a socka v1 server response frame. */
+declare function encodeServerResponse(id: string, rpc: string, body: unknown): SockaServerResponseFrame;
+/** Builds a socka v1 server error frame. */
+declare function encodeServerError(id: string, error: string): SockaServerErrorFrame;
+/** Builds a socka v1 server event frame. */
+declare function encodeServerEvent(event: string, body: unknown): SockaServerEventFrame;
+
+/**
+ * JSON text frames vs msgpack binary frames for the same socka v1 object graph.
+ * Matches {@link decodeSockaWire} after parse/unpack.
+ */
+
+/** Wire encoding: UTF-8 JSON strings (default) or msgpack `ArrayBuffer` frames. */
+type SockaWireFormat = "json" | "msgpack";
+/**
+ * Encodes a socka frame for the wire. JSON returns a string; msgpack returns bytes
+ * suitable for `WebSocket.send`.
+ */
+declare function encodeSockaWire(frame: SockaWireFrame, format: SockaWireFormat, serializeJson?: (value: unknown) => string): string | Uint8Array;
+/**
+ * Decodes a wire payload to a plain object before {@link decodeSockaWire}.
+ * Msgpack mode accepts `ArrayBuffer` or `Uint8Array` (e.g. from `msgpackr` / `WebSocket`).
+ */
+declare function parseWirePayload(data: string | ArrayBuffer | Uint8Array, format: SockaWireFormat, deserializeJson?: (raw: string) => unknown): unknown;
+
+/**
+ * Single discriminated union for optional `reportError` on session config and
+ * `SockaSession` options: `kind` narrows context; `error` is what was thrown or rejected.
+ */
+type SockaReportError = {
+    kind: "clientEventListener";
+    eventName: string;
+    error: unknown;
+} | {
+    kind: "clientEventValidation";
+    eventName: string;
+    error: unknown;
+} | {
+    kind: "serverOnAttached";
+    error: unknown;
+} | {
+    kind: "serverInboundMessage";
+    /** `hono` uses the same log line as the Hono adapters; others use attach-style. */
+    adapter: "attach" | "hono" | "bun";
+    error: unknown;
+} | {
+    kind: "serverHandleClose";
+    error: unknown;
+} | {
+    kind: "serverShutdown";
+    adapter: "attach" | "hono";
+    error: unknown;
+};
+/** Default `console.error` behavior; same messages as pre–`reportError` socka. */
+declare function defaultReportError(event: SockaReportError): void;
+/** Invokes the optional `reportError` callback when provided, otherwise `defaultReportError`. */
+declare function reportSockaError(reportError: ((event: SockaReportError) => void) | undefined, event: SockaReportError): void;
+
+export { type DecodedSockaWire as D, type InferSockaSend as I, RESERVED_SOCKA_PROCEDURE_NAMES as R, type SockaContract as S, type ValidateSockaCallKeys as V, type SockaContractConfig as a, type SockaWireFormat as b, type SockaProcedureDef as c, defineSocka as d, type InferSockaHandlers as e, type InferSockaPushHandlers as f, type InferSockaPushPayload as g, type ReservedSockaProcedureName as h, SOCKA_WIRE_VERSION as i, SockaWireError as j, type SockaClientRequestFrame as k, type SockaServerErrorFrame as l, type SockaServerEventFrame as m, type SockaServerResponseFrame as n, type SockaWireFrame as o, decodeSockaWire as p, encodeClientRequest as q, encodeServerResponse as r, encodeServerError as s, encodeServerEvent as t, encodeSockaWire as u, parseWirePayload as v, defaultReportError as w, reportSockaError as x, type SockaReportError as y };

package/docs/README.md

@@ -0,0 +1,18 @@
+# @firtoz/socka — documentation
+
+In-repo guides for the **[Socka](../README.md)** library (**npm** [`@firtoz/socka`](https://www.npmjs.com/package/@firtoz/socka)). For Cursor agents, see also [`../skills/`](../skills/).
+
+| Doc | Description |
+|-----|-------------|
+| [Getting started](./getting-started.md) | Quickest Bun path, other runtimes, install, wire-up, tic-tac-toe demos |
+| [Peers](./peers.md) | Which peers to install per import path and why |
+| [Multi-room](./multi-room.md) | Scopes, patterns per runtime, pitfalls |
+| [Lifecycle](./lifecycle.md) | `onAttached`, inbound RPCs, `handleClose` ordering |
+| [Server](./server.md) | Node `ws`, Bun, Hono, `attachSockaWebSocket`, `createData`, `session.data` |
+| [Durable Objects](./durable-objects.md) | `SockaDoSession`, `SockaWebSocketDO`, routing, hibernation |
+| [Client](./client.md) | `SockaSession`, React, deferred connect, reconnect |
+| [Pushes](./events.md) | `emitPush` / `broadcastPush`, `session.subscribe`, ordering notes |
+| [Reference](./reference.md) | Wire encoding (JSON/msgpack), frame kinds, server/client config tables, types, errors, imports |
+| [Comparison](./comparison.md) | vs DIY WS, **socket.io**, **tRPC** |
+
+**Roadmap** — [Deferred and post–v1 ideas](../roadmap.md).

package/docs/client.md

@@ -0,0 +1,85 @@
+# Client
+
+## Vanilla (`SockaSession`)
+
+Outside React, construct **`SockaSession`** from **`@firtoz/socka/client`** with the same **`contract`** as the server and a **`url`** (or a prebuilt **`webSocket`**). **`wireFormat`** defaults to **`"json"`** and must match every server session that receives this connection.
+
+| Option | Typical use |
+|--------|-------------|
+| **`contract`**, **`url`** / **`webSocket`** | Required pairing: open socket to your upgrade URL, or inject a socket for tests. |
+| **`wireFormat`** | **`"json"`** (text frames) vs **`"msgpack"`** (binary); must match the **server** session config for this connection. |
+| **`autoConnect: false`** | Defer opening until **`await session.connect()`** (or first **`send`**). |
+| **`serializeJson` / `deserializeJson`** | Custom JSON handling for the **outer** frame in JSON mode (e.g. replacers). |
+| **`onOpen` / `onClose` / `onError`** | Lifecycle and telemetry. |
+| **`pushHandlers`** | Up-front subscriptions for contract **`pushes`** (same as **`session.subscribe.on`**). |
+| **`reportError`** | Non-RPC client pipeline failures; defaults to **`console.error`**. |
+
+Full list: **[Reference — Client configuration](./reference.md#client-configuration)**.
+
+**Call names** — For literal `calls` objects, **`defineSocka`** rejects names that would make **`session.send`** Promise-like or clash with object shape (e.g. **`then`**, **`toString`**). If you use a wide **`Record<string, SockaProcedureDef>`**, TypeScript cannot apply that check; **`SockaSession`** still validates at construction (see **`RESERVED_SOCKA_PROCEDURE_NAMES`** in **`@firtoz/socka/core`**).
+
+```ts
+import { SockaSession } from "@firtoz/socka/client";
+import { myContract } from "./contract";
+
+const session = new SockaSession({ contract: myContract, url: "wss://example.com/ws" });
+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`**.
+
+## React
+
+```ts
+import { useSockaSession } from "@firtoz/socka/react";
+import { myContract } from "./contract";
+
+function App() {
+  const { ready, send } = useSockaSession(myContract, { url: "ws://..." }, []);
+  // After `ready`, call `send.list()` / `send.insert(...)` from effects or event handlers (not during render).
+  return null;
+}
+
+// Binary frames — set the same `wireFormat` on the server session
+useSockaSession(myContract, { url: "wss://...", wireFormat: "msgpack" }, []);
+```
+
+### 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:
+
+```tsx
+import { SockaSessionProvider, useSockaSessionContext } from "@firtoz/socka/react";
+import { myContract } from "./contract";
+
+function Layout({ roomId }: { roomId: string }) {
+  return (
+    <SockaSessionProvider
+      contract={myContract}
+      deps={[roomId]}
+      url={`wss://example.com/ws/${roomId}`}
+    >
+      <Child />
+    </SockaSessionProvider>
+  );
+}
+
+function Child() {
+  const { ready, send } = useSockaSessionContext(myContract);
+  // ...
+}
+```
+
+Use the **same `contract` reference** on the provider and in **`useSockaSessionContext`** (checked at runtime).
+
+## Deferred WebSocket connect
+
+Use **`autoConnect: false`** on **`SockaWebSocketClient`** / **`SockaSession`** when you want to open the socket later (e.g. after user action). Call **`await session.connect()`** or **`await client.connect()`** before calls; each **`send`** call also awaits connect when the socket is not open yet.
+
+## 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.
+
+## Pushes
+
+Server push and client subscriptions are covered in [Pushes](./events.md).

package/docs/comparison.md

@@ -0,0 +1,36 @@
+# Compared to hand-rolled WebSocket RPC (and common alternatives)
+
+Most apps model messages as large discriminated unions (`type` + `id`), validate twice (once on the wire, once in the handler), and maintain a **pending `Map<string, Deferred>`** for every RPC. That works, but types drift between client and server, correlation IDs are easy to get wrong, and pushing **server events** becomes a second, parallel protocol.
+
+## socka vs typical custom protocol
+
+| | Typical custom protocol | socka |
+|---|------------------------|--------|
+| **Strengths** | Total control; any framing; no shared spec | One contract drives **client + server** types; **Standard Schema** everywhere; socka v1 **envelopes** + correlation built in; inferred **`rpc`** / **`handlers`** |
+| **Tradeoffs** | Boilerplate, duplicated schemas, `Promise<unknown>` unless you invest | Opinionated **socka v1** frame shape; **named procedures** (not a free-form message bus) |
+
+## socket.io
+
+| | socket.io | socka |
+|---|-----------|--------|
+| **Model** | Named events + optional ack callbacks; rooms/namespaces are first-class | **Schema-first RPC**: one `defineSocka` contract drives typed **`session.send.*`** and **`handlers`**; optional typed **pushes** |
+| **Typing** | Largely **string-based** event names; no built-in shared input/output schema layer across client and server | **Standard Schema v1** on every procedure; **no duplicate schema** layer |
+| **When socket.io wins** | Broad ecosystem, Redis adapters, fallbacks, “emit anything” ergonomics | **When you want** correlated request/response + typed contracts in TypeScript on **both** ends |
+
+## tRPC
+
+| | tRPC | socka |
+|---|------|--------|
+| **Transport** | **HTTP-first** (batching, subscriptions via adapters); WebSocket is **not** the core story | **WebSocket-first** RPC: socka v1 frames on the wire |
+| **Contract** | **Router** + procedures; great for HTTP/JSON | **Single shared contract** (`defineSocka`) for **WS** frames (JSON or msgpack) |
+| **When tRPC wins** | Same-process or HTTP-first APIs, huge React ecosystem | **When the real transport is WebSocket** (including Durable Objects, Bun, Hono, Node `ws`) and you want **one schema** for the socket |
+
+## When a custom protocol still wins
+
+- You must match **legacy bytes**, a **binary codec** outside JSON/msgpack, or a **non-JSON** framing already deployed in the field.
+- You need a **generic pub/sub** bus where message types are not known at compile time.
+- You are **not** using TypeScript on both ends and do not benefit from shared inference.
+
+## 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.

package/docs/durable-objects.md

@@ -0,0 +1,74 @@
+# Durable Objects
+
+On Cloudflare **Durable Objects**, socka splits into two pieces:
+
+1. **`SockaDoSession`** — one instance per connected **`WebSocket`**. You pass **`handlers`**, **`handleClose`**, and optional **`onAttached`**; **`broadcastPush`** uses the shared **`sessions`** map you pass into the constructor.
+2. **`SockaWebSocketDO`** — subclasses **`BaseWebSocketDO`** from **`@firtoz/websocket-do`**. It connects HTTP → WebSocket upgrade → **`createSockaSession(ctx, websocket)`** so your session class gets the right **`sessions`** map and, when needed, a Hono **`Context`**.
+
+You still define one **`defineSocka`** contract; this page is only about hosting it on a **Durable Object**.
+
+## Cloudflare Worker checklist
+
+This is the **Cloudflare** side (bindings, Wrangler, generated types)—not socka-specific, but you need it before **`SockaWebSocketDO`** can run.
+
+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)**.
+
+### 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)**.
+
+## `SockaDoSession`
+
+```ts
+import { SockaDoSession } from "@firtoz/socka/do";
+import { myContract } from "./contract";
+
+new SockaDoSession(websocket, sessions, {
+  contract: myContract,
+  // wireFormat: "msgpack", // optional; default JSON text — must match client
+  handlers: {
+    list: async (session) => fetchMessages(),
+    insert: async (input, session) => saveMessage(input.message),
+  },
+  handleClose: async (session) => {
+    // e.g. remove session.websocket from your game / presence tables
+  },
+});
+```
+
+Handler types use **`InferSockaHandlers<typeof myContract, SockaDoSession<typeof myContract, …>>`**. Throw **`SockaError`** for expected domain failures (bad move, permission denied) so the client receives a structured **`serverError`** frame; see **[Reference](./reference.md)** for other failure paths.
+
+**`createData`** — If your session needs typed **`session.data`**, provide **`createData: (ctx) => …`** where **`ctx`** is a Hono **`Context`** (bindings, request, etc.). That runs when the DO accepts the socket; data participates in **hibernation** via **`@firtoz/websocket-do`** **`BaseSession`** (see **`session.update()`** below).
+
+## `SockaWebSocketDO` and routing
+
+Subclass **`SockaWebSocketDO`** and pass **`createSockaSession`** to connect upgrades to your session class. The base class exposes **`getBaseApp()`** for a Hono app that matches **`BaseWebSocketDO`** routing (see **`@firtoz/websocket-do`** for env typing and routes).
+
+Minimal shape (full game example: [`examples/tic-tac-toe-do`](../../../examples/tic-tac-toe-do/src/do.ts)):
+
+```ts
+export class MyDO extends SockaWebSocketDO<MySession, Env> {
+  app = this.getBaseApp();
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env, {
+      createSockaSession: (_ctx, websocket) =>
+        new MySession(websocket, this.sessions /*, … */),
+    });
+  }
+}
+```
+
+**One Durable Object instance per room** is a common pattern: derive the DO id from your room key so each instance has its own **`sessions`** map—see **[Multi-room](./multi-room.md)**.
+
+## Hibernation and `session.data`
+
+After you mutate **`session.data`**, call **`await session.update()`** (from **`@firtoz/websocket-do`**) so the attachment is rewritten for **hibernation**. If you skip **`update`**, **resume** can observe stale **`session.data`**. For large or authoritative state, keep a **stable id** in **`session.data`** and use **D1 / KV / SQLite** as the source of truth—the attachment is for small, session-scoped working state.
+
+## See also
+
+- **[Lifecycle](./lifecycle.md)** — **`onAttached`** and **`handleClose`** ordering.
+- **[Server](./server.md)** — **`attachSockaWebSocket`**, Bun, and Hono when the socket is **not** on a Durable Object.

package/docs/events.md

@@ -0,0 +1,48 @@
+# Pushes (server-initiated)
+
+Contracts can declare **`pushes`** alongside **`calls`**. Each push name maps to a **Standard Schema** payload. The server validates payloads **before** sending; the client decodes and validates **before** your listeners run—so **`InferSockaPushPayload`** stays honest end to end.
+
+**Wire format** — Push uses the **`serverEvent`** logical frame type. It is encoded with the session’s **`wireFormat`** (**JSON text** or **msgpack binary**) like RPC traffic. Switching to msgpack affects **calls and pushes** together—there is no separate “push encoding.”
+
+```ts
+export const myContract = defineSocka({
+  calls: { /* ... */ },
+  pushes: {
+    itemsChanged: z.array(messageSchema),
+  },
+});
+```
+
+## Server: emit and broadcast
+
+- **`await session.emitPush("itemsChanged", payload)`** — send one **validated** push to **this** socket (typical for private notifications).
+- **`await session.broadcastPush("itemsChanged", payload, excludeSelf?)`** — send to **every session in the same **`sessions`** map**, optionally skipping the caller.
+
+Lower-level helpers (for example **`broadcastSockaEventToPeers`** from **`@firtoz/socka/server`**) exist for advanced cases; prefer **`broadcastPush`** when you already have a session so schemas stay centralized.
+
+**Ordering** — Delivery order is per connection; there is no cross-client guarantee beyond your own handler ordering. For causal ordering across clients, include a **version** or **timestamp** in the payload.
+
+## Client: `session.subscribe`
+
+```ts
+// Optional `pushHandlers` on SockaSession / useSockaSession (same as session.subscribe.on(...))
+// Or subscribe imperatively:
+session.subscribe.on("itemsChanged", (payload) => { /* ... */ });
+session.subscribe.once("itemsChanged", (payload) => { /* ... */ });
+const payload = await session.subscribe.waitForPush("itemsChanged", {
+  timeoutMs: 5000,
+  signal: ac.signal,
+  predicate: (p) => p.length > 0,
+});
+```
+
+Use **`InferSockaPushPayload<typeof myContract, "itemsChanged">`** (from **`@firtoz/socka/core`**) when typing callbacks or reducers. If the server never emits a push your client subscribed to, **`waitForPush`** can time out—handle **`AbortSignal`** and UI loading states.
+
+## Who receives `broadcastPush`?
+
+Only sessions in the **`sessions`** map you passed into that session’s constructor.
+
+- **Bun / Hono multi-room** — **`resolveScope`** (or per-room routes) must put each socket in the map for the right room—see **[Multi-room](./multi-room.md)**.
+- **Durable Objects** — Everyone connected to **that** Durable Object instance shares one map—see **[Durable Objects](./durable-objects.md)**.
+
+See also [Client](./client.md) and [Reference](./reference.md) for observability when push validation fails on the client.

package/docs/getting-started.md

@@ -0,0 +1,138 @@
+# 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.
+
+## Quickest path (Bun)
+
+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).
+
+**`contract.ts`**
+
+```ts
+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() }),
+		},
+	},
+});
+```
+
+**`server.ts`**
+
+```ts
+import { createSockaBunWebSocketHandlers } from "@firtoz/socka/bun";
+import { myContract } from "./contract";
+
+const { websocket } = createSockaBunWebSocketHandlers({
+	contract: myContract,
+	handlers: {
+		echo: async (input) => ({ text: input.text }),
+	},
+	handleClose: async () => {},
+});
+
+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");
+	},
+	websocket,
+});
+```
+
+**`client.ts`**
+
+```ts
+import { SockaSession } from "@firtoz/socka/client";
+import { myContract } from "./contract";
+
+const session = new SockaSession({
+	contract: myContract,
+	url: "ws://localhost:3450/ws",
+});
+const { text } = await session.send.echo({ text: "hello" });
+```
+
+## What socka is
+
+**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.
+
+For frame shapes and options, see **[Reference](./reference.md)**.
+
+## Other runtimes
+
+Pick **how** the socket is upgraded, then use the matching subpath:
+
+| 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` |
+
+**Multiple rooms or scopes?** See **[Multi-room](./multi-room.md)**.
+
+## Install
+
+```bash
+npm install @firtoz/socka
+```
+
+Add **only** the peers for the subpaths you import—**[Peers](./peers.md)**.
+
+## Shared contract
+
+Use one module for client and server (same as the README):
+
+```ts
+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() }),
+		},
+	},
+});
+```
+
+For richer examples (list/insert, optional inputs), see **[Server](./server.md)** and the tic-tac-toe apps under `examples/`.
+
+## Wire the server, then the client
+
+You already have the **client** shape (`SockaSession` with the same contract). Now:
+
+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.
+
+### Wire format (short)
+
+Default is **JSON text** frames. **`wireFormat: "msgpack"`** must match on **both** sides. Details: **[Reference — Wire encoding](./reference.md#wire-encoding-json-and-msgpack)**.
+
+## Run a full-stack demo
+
+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** |
+
+From the folder: **`bun run dev`**. The DO example uses **`wrangler dev`**.
+
+---
+
+Next: [Peers](./peers.md) · [Server](./server.md) · [Durable Objects](./durable-objects.md) · [Client](./client.md) · [Reference](./reference.md)

package/docs/lifecycle.md

@@ -0,0 +1,31 @@
+# Lifecycle
+
+Join, message, and **leave** ordering for socka sessions—whether you use **`@firtoz/socka/server`**, **`@firtoz/socka/bun`**, **`@firtoz/socka/hono`**, or **`@firtoz/socka/do`**.
+
+## 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).
+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)**.
+
+## 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”).
+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.
+
+## Hibernation (Durable Objects only)
+
+If you use **`SockaDoSession`**, mutating **`session.data`** may require **`await session.update()`** so hibernation attachments stay consistent. See **[Durable Objects](./durable-objects.md)**.
+
+See also [Multi-room](./multi-room.md).