@marianmeres/ws 0.4.1 → 0.5.0

package/AGENTS.md

@@ -1,7 +1,9 @@
 # @marianmeres/ws — Agent Guide
 
-WebSocket client with namespaces, rooms, presence and reconnect, plus a
-demino-mountable reference server.
+WebSocket client with reconnect, half-open detection and buffered sends, used
+two ways: plain messages to/from the server (protocol **core**), or namespaces,
+rooms and presence (the optional **rooms extension**). Plus a demino-mountable
+reference server implementing both.
 
 ## Quick Reference
 
@@ -16,6 +18,8 @@ test: "deno task test"
 | Task                         | File                      | Key export                            |
 | ---------------------------- | ------------------------- | ------------------------------------- |
 | Client                       | `src/client/ws-client.ts` | `createWSClient`, `WSClient`          |
+| Messages (core), client      | `src/client/ws-client.ts` | `WSClient.send`, `message` event      |
+| Messages (core), server      | `src/server/service.ts`   | `onMessage` option, `WSService.send`  |
 | Reconnect curve              | `src/client/backoff.ts`   | `backoffDelay`                        |
 | Outbox + pending acks        | `src/client/outbox.ts`    | `Outbox`                              |
 | Room refcounting             | `src/client/rooms.ts`     | `RoomRegistry`                        |
@@ -33,7 +37,7 @@ src/
 ├── protocol.ts            # ./protocol entry -> protocol/mod.ts
 ├── protocol/              # dependency-free; imported by BOTH sides
 │   ├── constants.ts       # PROTOCOL_VERSION, FRAME, CLOSE, ERROR_CODE, PRESENCE
-│   ├── frames.ts          # ClientFrame / ServerFrame unions, WSMessage
+│   ├── frames.ts          # ClientFrame / ServerFrame unions, WSMessage, WSRoomMessage
 │   └── errors.ts          # typed errors
 ├── client/
 └── server/
@@ -66,8 +70,34 @@ to compensate — do not reintroduce that.
 frame shape means changing it there, and bumping `PROTOCOL_VERSION` if the
 change is breaking.
 
+**The protocol is two layers; keep them apart.** Core: `auth`/`hello`, `msg`
+(both directions), `ack`/`nack`, `ping`/`pong`, `error`. Rooms extension: `sub`,
+`unsub`, `pub`, `broadcast`, `presence`, and the routing fields (`room`,
+`namespace`, `from`, `timestamp`) on a delivered `msg`. A core-only server
+(PROTOCOL.md §8) must stay sufficient: never make a rooms concept — room,
+namespace, `clientId` — required in the core. That is why `hello` identity is
+optional, `auth` sends `clientId`/`namespace` only when the app set them, and
+`WSMessage` has only `payload` required (`WSRoomMessage` is the room-delivery
+refinement room handlers get). `tests/core.test.ts` runs the client against a
+core-only server (`startCoreServer`) and fails if the core stops being enough.
+
+**Every frame with an `id` gets exactly one answer.** A server answers an unknown
+or unimplemented frame type with `unsupported` — `nack` when it has a string
+`id`, `error` when not. Ignoring it would leave the client waiting out
+`sendTimeout`; answering it is what makes the rooms extension safely optional.
+
+**A `send()` without `{ ack: true }` completes when written.** It carries no
+wire id; the outbox tracks it under a local key with `awaitAck: false` only so
+it can be buffered and bounded offline, and `Outbox.transmitted()` resolves it.
+It is therefore never "in flight" — `settleInFlight` never sees it. Its returned
+promise is marked handled (`.catch(noop)` on it, then returned): fire-and-forget
+invites not awaiting, and it can still reject (queue timeout, outbox drop,
+terminal close). Removing that makes an ignored send fatal in Deno/Node; a
+resilience test fails if you do.
+
 **Ordering on reconnect is load-bearing.** `#onHello` must re-subscribe _before_
-flushing the outbox, and the server must handle `sub`/`unsub` **synchronously**.
+flushing the outbox (which holds `pub`, `broadcast` and `msg` frames alike), and
+the server must handle `sub`/`unsub` **synchronously**.
 Together these guarantee a buffered publish cannot land in a room the server has
 not registered yet. There is a test that fails if you break it
 (`buffered publishes flush *after* re-subscribe`).
@@ -85,7 +115,16 @@ or Node process.
 dispatch.** A malformed but parseable frame is a `nack`/`error` `bad_request`
 and the socket stays open; an unexpected throw is `error` `internal` and a 1011
 close. Both paths, including the async one, end in a `.catch()` — a handler that
-throws must never be able to take the process down.
+throws must never be able to take the process down. The one exception is the
+application's `onMessage`: its throw is an application failure, not broken
+bookkeeping, so it is answered (`WSRemoteError` → its own `code`/`message`,
+anything else → `internal` with no text) and the socket stays open.
+
+**`onMessage` is not serialized.** It is called in arrival order but not awaited
+before the next frame, like every other async path in the service. The Python
+servers in PROTOCOL.md do serialize (a per-connection worker) — both are
+documented as such; do not "fix" either to match the other without updating
+PROTOCOL.md §3.2.
 
 **Every send carries one deadline** spanning queue + flight + ack — not an
 ack-only timeout. Combining acks with infinite retry otherwise produces promises
@@ -145,13 +184,20 @@ run `deno publish` then the npm build.
 
 ## Before Making Changes
 
-1. `deno task test` — 66 tests, mostly real sockets against a real server:
-   `unit`, `integration`, `resilience`, `protocol` (server input hardening,
-   raw sockets) and `codec` (custom encode/decode, binary frames)
+1. `deno task test` — 83 tests, mostly real sockets against a real server:
+   `unit`, `integration`, `resilience`, `core` (messages: a core-only server,
+   `onMessage`, `service.send`), `protocol` (server input hardening, raw
+   sockets) and `codec` (custom encode/decode, binary frames)
 2. `deno lint && deno fmt --check && deno check src/mod.ts src/server.ts src/protocol.ts`
 3. Touched a public signature? `deno doc --lint src/mod.ts src/server.ts
    src/protocol.ts` **and** `deno publish --dry-run --allow-dirty`
-4. Touching the wire? Update `src/protocol/` first, then both sides
+4. Touching the wire? Update `src/protocol/` first, then both sides, then
+   PROTOCOL.md — including its two Python servers and the Appendix A script.
+   Re-verify them, don't eyeball them: copy each code block out, point the
+   script's `jsr:@marianmeres/ws` import at `src/mod.ts`, run each server with
+   `WS_AUTH_TIMEOUT=1 WS_IDLE_TIMEOUT=2` (Python 3.10+, `websockets>=13`, in a
+   venv) and run the script — core server without `WS_ROOMS`, full one with
+   `WS_ROOMS=1`
 5. Touching reconnect, outbox or heartbeat? Read `tests/resilience.test.ts`
    first — those tests encode the failure modes the design exists to handle
 6. `deno task npm:build` if packaging changed (npm ships the **client only**;
@@ -167,6 +213,8 @@ run `deno publish` then the npm build.
 - No server-side replay, so no at-least-once delivery
 - `recipients` counts are instance-local; they stay that way under a
   distributed adapter
+- Direct messages (`WSService.send`) are instance-local; the adapter carries
+  room messages only
 - Only `WSPubSubLocal` exists — Redis/Deno-KV adapters are an unimplemented seam
 - Presence is scoped to `(room, namespace)`; broadcast crosses namespaces but
   presence does not
@@ -175,12 +223,12 @@ run `deno publish` then the npm build.
 
 ## Documentation Index
 
-| Document            | Purpose                                                       |
-| ------------------- | ------------------------------------------------------------- |
-| `README.md`         | Human-facing overview and usage                               |
-| `API.md`            | Complete API reference — every public export                  |
-| `PROTOCOL.md`       | Wire protocol spec + Python server, for other implementations |
-| `example/README.md` | The reference app: what it demonstrates, and how              |
+| Document            | Purpose                                                                             |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| `README.md`         | Human-facing overview and usage                                                     |
+| `API.md`            | Complete API reference — every public export                                        |
+| `PROTOCOL.md`       | Wire protocol spec (core + rooms extension), two Python servers, conformance script |
+| `example/README.md` | The reference app: what it demonstrates, and how                                    |
 
 `tmp/spec.md` (design spec and decision log) is referenced in some commits but
 is **untracked** — `tmp/*` is gitignored, so it does not exist in a fresh clone.

package/API.md

@@ -2,11 +2,11 @@
 
 Three entry points:
 
-| Import                     | Contains                                  | Runtime   |
-| -------------------------- | ----------------------------------------- | --------- |
-| `@marianmeres/ws`          | the client, plus everything from protocol | any       |
-| `@marianmeres/ws/server`   | the reference server                      | Deno only |
-| `@marianmeres/ws/protocol` | wire definitions only, dependency-free    | any       |
+| Import                     | Contains                                   | Runtime   |
+| -------------------------- | ------------------------------------------ | --------- |
+| `@marianmeres/ws`          | the client, plus everything from protocol  | any       |
+| `@marianmeres/ws/server`   | the reference server, plus `WSRemoteError` | Deno only |
+| `@marianmeres/ws/protocol` | wire definitions only, dependency-free     | any       |
 
 ---
 
@@ -14,8 +14,13 @@ Three entry points:
 
 ### `createWSClient(options?)`
 
-Creates a client. Nothing connects until the first `connect()`, `subscribe()`
-or `publish()`.
+Creates a client. Nothing connects until the first `connect()`, `send()`,
+`subscribe()` or `publish()`.
+
+The client works two ways, freely mixed on one connection — **messages**
+(`send()` / the `message` event; the server only has to implement the protocol
+core) and **rooms** (`subscribe()` / `publish()` / `broadcast()` / presence;
+the rooms extension). See [Messages](#messages) and [Rooms](#rooms) below.
 
 `WSClient` is exported too — `new WSClient(options)` is the same thing,
 following the `PubSub` / `createPubSub` precedent.
@@ -25,11 +30,11 @@ following the `PubSub` / `createPubSub` precedent.
 | Name                 | Type                                | Default            | Description                                                                   |
 | -------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------------- |
 | `url`                | `string \| URL`                     | `"/ws"`            | `ws(s)://`, or `http(s)://` (upgraded), or a path resolved against `location` |
-| `namespace`          | `string`                            | `"default"`        | Isolation boundary                                                            |
-| `clientId`           | `string`                            | generated          | Preferred id; the server may override                                         |
+| `namespace`          | `string`                            | `"default"`        | Isolation boundary for rooms. Sent to the server only when set                |
+| `clientId`           | `string`                            | —                  | Preferred id; the server may override or ignore it                            |
 | `rooms`              | `string[]`                          | `[]`               | Rooms joined on every (re)connect                                             |
 | `auth`               | `() => unknown \| Promise<unknown>` | —                  | Auth payload; called before _every_ (re)connect                               |
-| `autoConnect`        | `boolean`                           | `true`             | First `subscribe()`/`publish()` starts the connection                         |
+| `autoConnect`        | `boolean`                           | `true`             | First `send()`/`subscribe()`/`publish()` starts the connection                |
 | `logger`             | `Logger \| null`                    | `createClog("ws")` | `null` silences                                                               |
 | `reconnectDelay`     | `number`                            | `500`              | Initial backoff, ms                                                           |
 | `reconnectDelayMax`  | `number`                            | `30_000`           | Backoff ceiling, ms                                                           |
@@ -56,14 +61,17 @@ import { createWSClient } from "@marianmeres/ws";
 
 const ws = createWSClient({
 	url: "wss://example.com/ws",
-	namespace: "org-123",
 	auth: () => session.token, // re-read on every reconnect
 });
 
+// messages
+ws.on("message", (msg) => console.log(msg.payload));
+const reply = await ws.send({ op: "load", id: 42 }, { ack: true });
+
+// rooms
 const unsub = await ws.subscribe("chat", (msg) => {
 	console.log(msg.from, msg.payload, msg.timestamp);
 });
-
 const { recipients } = await ws.publish("chat", { text: "hello" });
 
 unsub();
@@ -116,7 +124,67 @@ Terminal teardown: disconnects, then drops every handler, room, timer and
 pending promise. Pending sends reject with `WSDisposedError`. The instance is
 unusable afterwards.
 
-#### Subscriptions
+#### Messages
+
+The core of the protocol: the client and the server talk to each other
+directly. Incoming messages arrive through the [`message`](#wsevents) event.
+
+##### `send<T>(payload, options?): Promise<void>` / `send<R, T>(payload, { ack: true }): Promise<R>`
+
+Sends a message to the server — all a core-only server has to understand.
+
+**Fire-and-forget** by default: resolves as soon as the frame is written to the
+socket. There is no delivery confirmation — a frame written into a connection
+that turns out to be dead is lost, exactly as with a plain `WebSocket`. Calling
+it without `await` is safe: the promise is marked handled, so a failure nobody
+awaits (the queue timing out while offline, say) is not an unhandled rejection.
+Await it to learn about one.
+
+**With `{ ack: true }`** the frame carries an id and the promise waits for the
+server's acknowledgement. It resolves with the reply the server put in the ack —
+which makes this a request/response call — or with `undefined` for a bare ack. A
+refusal (`nack`) rejects with `WSRemoteError` carrying the server's `code`, which
+can be one of the server application's own. An acknowledged send in flight when
+the socket closes rejects there and then with `WSConnectionLostError`; it is not
+resent.
+
+Either way, while disconnected the frame is buffered and flushed after the next
+connect, in order — bounded by `sendTimeout`, which spans queue, flight and (with
+an ack) acknowledgement. After a terminal close nothing is buffered: the promise
+rejects immediately with `WSTerminatedError`.
+
+A third overload, `send<T>(payload, options?: WSSendOptions): Promise<unknown>`,
+covers an `ack` flag decided at runtime.
+
+**Parameters**
+
+- `payload` (`T`) — opaque application data; never inspected or mutated
+- `options.ack` (boolean, optional) — wait for the server's acknowledgement and
+  its reply. Default `false`
+
+**Throws** `WSRemoteError` (ack only), `WSTimeoutError`, `WSConnectionLostError`
+(ack only), `WSOutboxDropError`, `WSNotConnectedError`, `WSTerminatedError`,
+`WSDisposedError`
+
+**Example**
+
+```typescript
+ws.send({ op: "cursor", x: 10, y: 20 }); // fire-and-forget
+
+const doc = await ws.send<Doc>({ op: "load", id: 42 }, { ack: true });
+
+try {
+	await ws.send({ op: "delete", id: 42 }, { ack: true });
+} catch (e) {
+	if (e instanceof WSRemoteError && e.code === "forbidden") showNotAllowed();
+}
+```
+
+#### Rooms
+
+The rooms extension: namespaces, rooms, presence and broadcast. A server that
+does not implement it answers these with `unsupported`, so they fail with
+`WSRemoteError` code `"unsupported"` at once rather than after `sendTimeout`.
 
 ##### `subscribe<T>(room, handler, options?): Promise<Unsubscriber>`
 
@@ -137,7 +205,8 @@ connect, and a failure there surfaces as an `error` event.
 **Parameters**
 
 - `room` (string) — room name, scoped to this client's namespace
-- `handler` (`MessageHandler<T>`) — receives every message published to the room
+- `handler` (`MessageHandler<T>`) — receives every message published to the
+  room, as a `WSRoomMessage<T>`
 - `options.presence` (`PresenceHandler`, optional) — enables presence for this
   room
 
@@ -167,8 +236,6 @@ room registered while offline reads `true` before the wire subscription exists.
 Last known membership of a presence-enabled room. Empty for rooms without
 presence.
 
-#### Sending
-
 ##### `publish<T>(room, payload, namespace?): Promise<WSPublishResult>`
 
 Publishes to a room within this client's namespace. Resolves with the recipient
@@ -208,18 +275,18 @@ unsubscriber is `Symbol.dispose`-compatible.
 
 #### Properties
 
-| Member            | Type                      | Notes                                           |
-| ----------------- | ------------------------- | ----------------------------------------------- |
-| `state`           | Svelte store of `WSState` | Fires immediately, then on every change         |
-| `connected`       | `boolean`                 | `true` only in `open` — not merely socket-open  |
-| `connectionState` | `WSConnectionState`       |                                                 |
-| `clientId`        | `string \| null`          | Server-assigned; `null` until connected         |
-| `namespace`       | `string`                  | The server's assignment wins over the request   |
-| `rooms`           | `string[]`                | Rooms currently held                            |
-| `socket`          | `WebSocket \| null`       | Escape hatch; sending on it bypasses the outbox |
-| `url`             | `URL`                     | A copy — mutating it does nothing               |
-| `logger`          | `Logger \| null`          | Assignable; set to `null` to silence            |
-| `dump()`          | `Record<string, unknown>` | Debug snapshot; shape is not stable API         |
+| Member            | Type                      | Notes                                                                     |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `state`           | Svelte store of `WSState` | Fires immediately, then on every change                                   |
+| `connected`       | `boolean`                 | `true` only in `open` — not merely socket-open                            |
+| `connectionState` | `WSConnectionState`       |                                                                           |
+| `clientId`        | `string \| null`          | Server-assigned; `null` until connected, and when the server assigns none |
+| `namespace`       | `string`                  | The server's assignment wins over the request; else the requested one     |
+| `rooms`           | `string[]`                | Rooms currently held                                                      |
+| `socket`          | `WebSocket \| null`       | Escape hatch; sending on it bypasses the outbox                           |
+| `url`             | `URL`                     | A copy — mutating it does nothing                                         |
+| `logger`          | `Logger \| null`          | Assignable; set to `null` to silence                                      |
+| `dump()`          | `Record<string, unknown>` | Debug snapshot; shape is not stable API                                   |
 
 ##### `WSClient.resolveUrl(input): URL` (static)
 
@@ -258,6 +325,17 @@ Exported mainly so the curve is testable.
 The options object documented under
 [`createWSClient`](#createwsclientoptions).
 
+### `WSSendOptions`
+
+```typescript
+{
+	ack?: boolean; // default false
+}
+```
+
+Options for [`send()`](#messages). `ack: true` waits for the server's
+acknowledgement and resolves with its reply.
+
 ### `SubscribeOptions`
 
 ```typescript
@@ -274,28 +352,41 @@ time the fleet reconnects.
 ### `MessageHandler<T>` / `PresenceHandler`
 
 ```typescript
-type MessageHandler<T = unknown> = (msg: WSMessage<T>) => void;
+type MessageHandler<T = unknown> = (msg: WSRoomMessage<T>) => void;
 type PresenceHandler = (event: WSPresenceEvent) => void;
 ```
 
+A room handler receives a `WSRoomMessage` — every routing field present. The
+[`message`](#wsevents) event receives the looser `WSMessage`, because it also
+carries direct messages from the server.
+
 A throwing handler is caught, reported through the `error` event, and does not
 stop delivery to the others.
 
 ### `WSEvents`
 
-| Event          | Payload                            |
-| -------------- | ---------------------------------- |
-| `open`         | `void` — socket open, pre-auth     |
-| `connected`    | `{ clientId, namespace }`          |
-| `message`      | `WSMessage` — firehose, every room |
-| `presence`     | `WSPresenceEvent`                  |
-| `close`        | `{ code, reason, willReconnect }`  |
-| `reconnecting` | `{ attempt, delay }`               |
-| `terminated`   | `{ code, reason }` — gave up       |
-| `error`        | `Error`                            |
+| Event          | Payload                                                      |
+| -------------- | ------------------------------------------------------------ |
+| `open`         | `void` — socket open, pre-auth                               |
+| `connected`    | `{ clientId: string \| null, namespace }`                    |
+| `message`      | `WSMessage` — every inbound message, direct or from any room |
+| `presence`     | `WSPresenceEvent`                                            |
+| `close`        | `{ code, reason, willReconnect }`                            |
+| `reconnecting` | `{ attempt, delay }`                                         |
+| `terminated`   | `{ code, reason }` — gave up                                 |
+| `error`        | `Error`                                                      |
+
+`message` is the receiving side of [messages](#messages): a direct message from
+the server carries only `payload`; a room delivery also carries `room`,
+`namespace`, `from` and `timestamp`. Check `msg.room` to tell them apart.
+
+`connected.clientId` is `null` when the server assigns no identity — a
+core-only server need not.
 
 `error` means something failed but the client carried on (a decode failure, a
-throwing handler). `terminated` is the only non-retrying exit.
+throwing handler, an `error` frame from the server — for instance a
+fire-and-forget `send()` the server refused). `terminated` is the only
+non-retrying exit.
 
 A local `disconnect()` is a `close` too: code `4900`, `willReconnect: false` —
 that pair is how a deliberate teardown is told apart from a lost connection.
@@ -348,6 +439,7 @@ Creates a mountable demino app plus the service it is wired to.
 | `middlewares`                | `DeminoHandler[]`                                 | `[]`                      | Applied to all routes                                                                                                                                                         |
 | `options.verify`             | `(payload, req, requested) => AuthResult \| null` | —                         | Return `null` (or throw) to reject with `4001`. Absent means no authentication. `requested` is the identity the client asked for — see [below](#security-namespace-isolation) |
 | `options.allowedOrigins`     | `string[] \| (origin, req) => boolean`            | — (no check)              | Origins allowed to upgrade → `403` — see [below](#security-cross-site-websocket-hijacking)                                                                                    |
+| `options.onMessage`          | `(ctx, payload) => unknown`                       | — (**unsupported**)       | Receives every client `send()`; the return value is the reply — see [below](#messages-onmessage)                                                                              |
 | `options.allowBroadcast`     | `(ctx, room) => boolean`                          | **deny**                  | Gate for cross-namespace broadcast                                                                                                                                            |
 | `options.httpAuth`           | `DeminoHandler`                                   | —                         | Guards the HTTP routes. **Without it they are not mounted**                                                                                                                   |
 | `options.deminoOptions`      | `DeminoOptions`                                   | —                         | Passed through to `demino()`                                                                                                                                                  |
@@ -392,6 +484,42 @@ await service.publish("notifications", { text: "deploy finished" }, "org-123");
 Deno.serve(app);
 ```
 
+#### Messages: `onMessage`
+
+Every client `send()` reaches `onMessage(ctx, payload)`, with the sender's
+[`WSConnectionContext`](#wsconnectioncontext).
+
+- **The return value is the reply.** For a send with `{ ack: true }` it travels
+  back in the `ack` and resolves the client's promise (`undefined` makes a bare
+  ack). For a fire-and-forget send it is discarded. It may be a promise.
+- **Throw a `WSRemoteError`** to refuse the message with your own `code` and
+  `message` — the client's `send()` rejects with exactly those. Any other throw
+  is logged and answered `internal`, without its text. The connection stays open
+  either way.
+- **Called in arrival order, not awaited before the next frame.** An async hook
+  may finish out of order; chain the work yourself where order matters.
+- **Unset, the server accepts no messages**: every `send()` is answered
+  `unsupported`.
+
+To send a client a message of your own — now or later — use
+[`service.send()`](#sendclientid-payload-boolean).
+
+```typescript
+import { createWSApp, WSRemoteError } from "@marianmeres/ws/server";
+
+const { app, service } = createWSApp("/ws", [], {
+	verify: (payload) => authenticate(payload),
+	onMessage: async (ctx, payload) => {
+		const { op, id } = payload as { op: string; id: number };
+		if (op !== "load") {
+			throw new WSRemoteError({ code: "unknown_op", message: `unknown op ${op}` });
+		}
+		service.send(ctx.clientId, { op: "progress", stage: "loading" });
+		return await loadDoc(id); // the reply
+	},
+});
+```
+
 #### Security: namespace isolation
 
 Namespace is the isolation boundary and `clientId` is the identity peers see in
@@ -453,7 +581,8 @@ site's page cannot read your token, only ride your cookies.
 
 ### `WSService`
 
-Owns every connection, the room index, presence and delivery. Usable standalone
+Owns every connection, direct messages, the room index, presence and delivery.
+Usable standalone
 — `new WSService(options)`, driven from any `Deno.serve` handler — or through
 `createWSApp`, which mounts it as a demino app.
 
@@ -463,9 +592,19 @@ Upgrades an HTTP request and takes ownership of the socket. Return the 101
 response from your route handler unmodified. With `allowedOrigins` set, a
 disallowed request is answered `403` instead and nothing is upgraded.
 
+##### `send(clientId, payload): boolean`
+
+Sends a direct message to one connected client — the server-to-client half of
+the protocol core. It arrives with nothing but `payload`, through the client's
+`message` event; no room handler sees it.
+
+Returns `true` when handed to an open socket, `false` when no such client is
+connected **to this instance** (or the payload could not be encoded).
+Instance-local: nothing is propagated through the adapter.
+
 ##### `publish(room, payload, namespace?, from?): Promise<number>`
 
-Injects a message from server-side code. Delivered messages carry `from: null`
+Injects a message into a room from server-side code. Delivered messages carry `from: null`
 unless you pass one, which is how clients tell server pushes from peer traffic.
 
 `namespace` defaults to `"default"`. Resolves with the recipients on **this
@@ -533,7 +672,7 @@ Everything in that table except `httpAuth` and `deminoOptions`.
 }
 ```
 
-Passed to `allowBroadcast`.
+Passed to `onMessage` and `allowBroadcast`.
 
 ### `WSStats`
 
@@ -573,10 +712,12 @@ unimplemented seam.
 ```typescript
 {
 	namespace: string | null; // null for a cross-namespace broadcast
-	message: WSMessage;
+	message: WSRoomMessage;
 }
 ```
 
+Room messages only — direct messages (`service.send()`) never cross instances.
+
 ---
 
 ## Protocol
@@ -588,20 +729,39 @@ implementing this protocol against a different server or client.
 
 ```typescript
 {
+	payload: T;
+	room?: string;        // present on a room delivery only
+	namespace?: string;   // 〃
+	from?: string | null; // 〃
+	timestamp?: number;   // 〃
+}
+```
+
+Any message, as the [`message`](#wsevents) event delivers it. Only `payload` is
+guaranteed: a direct message from the server carries nothing else, a room
+delivery carries all of it (see `WSRoomMessage`). `room` tells them apart.
+
+`payload` is **opaque**: never inspected, never mutated. Your payload may carry
+its own `type` field and nothing collides.
+
+### `WSRoomMessage<T>`
+
+```typescript
+{
+	payload: T;
 	room: string;
 	namespace: string;
 	from: string | null;
-	payload: T;
 	timestamp: number; // server-assigned epoch ms
 }
 ```
 
+A message delivered through a room — what room handlers receive, and a
+`WSMessage` with every routing field present.
+
 `from` is `null` when the message was injected server-side. For a broadcast,
 `namespace` is the receiver's own — not the sender's.
 
-`payload` is **opaque**: never inspected, never mutated. Your payload may carry
-its own `type` field and nothing collides.
-
 ### `WSPresenceEvent`
 
 ```typescript
@@ -627,8 +787,9 @@ away.
 }
 ```
 
-Sockets the message was handed to **on the receiving server instance**.
-Best-effort telemetry, never a delivery guarantee.
+Sockets the message was handed to **on the receiving server instance**, as
+reported for `publish()` / `broadcast()`. Best-effort telemetry, never a
+delivery guarantee.
 
 ### `AuthResult`
 
@@ -679,13 +840,14 @@ Discriminated unions over `FRAME`, keyed on `type`. `WSFrame` is either
 direction. You need these only to write a custom `encode`/`decode` or a
 third-party implementation.
 
-| Direction       | Frames                                                     |
-| --------------- | ---------------------------------------------------------- |
-| client → server | `auth`, `sub`, `unsub`, `pub`, `broadcast`, `ping`         |
-| server → client | `hello`, `ack`, `nack`, `msg`, `presence`, `pong`, `error` |
+| Direction       | Core                                           | Rooms extension                    |
+| --------------- | ---------------------------------------------- | ---------------------------------- |
+| client → server | `auth`, `msg`, `ping`                          | `sub`, `unsub`, `pub`, `broadcast` |
+| server → client | `hello`, `msg`, `ack`, `nack`, `pong`, `error` | `presence`                         |
 
 A `msg` frame minus its `type` field _is_ a `WSMessage` — no translation layer,
-no divergence between wire names and API names.
+no divergence between wire names and API names. See [PROTOCOL.md](PROTOCOL.md)
+for every frame's fields.
 
 ### `PresenceEventType`
 
@@ -712,20 +874,26 @@ string-matching messages.
 | ----------------------- | ----------------------------------------------- | ---------------- |
 | `WSTerminatedError`     | Terminal close code                             | `code`, `reason` |
 | `WSConnectTimeoutError` | `connectTimeout` elapsed (retrying continues)   |                  |
-| `WSTimeoutError`        | `sendTimeout` elapsed with no acknowledgement   |                  |
-| `WSConnectionLostError` | Socket closed while the frame was in flight     |                  |
+| `WSTimeoutError`        | `sendTimeout` elapsed — still queued, or no ack |                  |
+| `WSConnectionLostError` | Socket closed while the frame awaited its ack   |                  |
 | `WSOutboxDropError`     | Evicted from a full outbox                      |                  |
-| `WSRemoteError`         | Server sent a `nack`                            | `code`           |
+| `WSRemoteError`         | Server sent a `nack` (or an `error` frame)      | `code`           |
 | `WSNotConnectedError`   | Sent while disconnected with `outboxMaxSize: 0` |                  |
 | `WSDisposedError`       | Client was disposed                             |                  |
 
+`WSRemoteError` is also what a server-side `onMessage` throws to refuse a
+message: `new WSRemoteError({ code, message })`. Its `code` and `message` reach
+the client unchanged. It is re-exported from `@marianmeres/ws/server` for that.
+
 ---
 
 ## Constants
 
 ### `PROTOCOL_VERSION`
 
-`1`. Announced by the server in `hello`; a mismatch warns rather than fails.
+`2`. Announced by the server in `hello`; a mismatch warns rather than fails.
+Version 2 split the protocol into a required core and the optional rooms
+extension; a version-1 server still works for rooms.
 
 ### `DEFAULT_NAMESPACE`
 
@@ -763,8 +931,11 @@ Frame type discriminators — the `type` field of every frame. See
 
 ### `ERROR_CODE`
 
-`"unauthorized" | "forbidden" | "bad_request" | "rate_limited" | "internal"` —
-the `code` on `WSErrorInfo` and `WSRemoteError`.
+`"unauthorized" | "forbidden" | "bad_request" | "rate_limited" | "unsupported" | "internal"`
+— the standard `code` values on `WSErrorInfo` and `WSRemoteError`.
+`"unsupported"` answers a frame type the server does not implement, e.g. rooms
+against a core-only server. A server application may also use codes of its own
+when it refuses a message.
 
 ### `PRESENCE`