@marianmeres/ws 0.4.1 → 0.5.0

package/dist/client/ws-client.d.ts

@@ -1,6 +1,13 @@
 /**
  * The WebSocket client.
  *
+ * Two ways to use it, freely mixed on one connection:
+ *
+ * - **Messages** (core): `send()` to the server, `on("message")` to receive.
+ *   Needs nothing from the server beyond the core protocol.
+ * - **Rooms** (extension): `subscribe()` / `publish()` / `broadcast()` and
+ *   presence, for servers that relay between clients.
+ *
  * @module
  */
 import { type Logger } from "@marianmeres/clog";
@@ -18,12 +25,19 @@ export type WSConnectionState = "idle" | "connecting" | "authenticating" | "open
 export interface WSEvents {
     /** Socket opened; authentication has not happened yet. */
     open: void;
-    /** Authenticated and ready. */
+    /**
+     * Authenticated and ready. `clientId` is `null` when the server assigned
+     * none — identity belongs to the rooms extension, and a core-only server
+     * may skip it.
+     */
     connected: {
-        clientId: string;
+        clientId: string | null;
         namespace: string;
     };
-    /** Firehose — every message, regardless of room. */
+    /**
+     * Every inbound message: direct messages from the server, and — with
+     * rooms — every room delivery regardless of room. `room` tells them apart.
+     */
     message: WSMessage;
     /** Membership change in a room subscribed with presence enabled. */
     presence: WSPresenceEvent;
@@ -62,6 +76,16 @@ export interface WSState {
     /** Most recent error, retained until the next successful connect. */
     lastError: Error | null;
 }
+/** Options for {@link WSClient.send}. */
+export interface WSSendOptions {
+    /**
+     * Wait for the server's acknowledgement and resolve with its reply.
+     *
+     * Default `false`: resolve as soon as the frame is written to the socket,
+     * with no confirmation that the server ever received it.
+     */
+    ack?: boolean;
+}
 /** Per-room subscription options. */
 export interface SubscribeOptions {
     /**
@@ -80,11 +104,14 @@ export interface WSClientOptions<TAuth = unknown> {
      * a path resolved against `location` in the browser. Default `/ws`.
      */
     url?: string | URL;
-    /** Isolation boundary. Default `"default"`. */
+    /**
+     * Isolation boundary for rooms. Default `"default"`. Sent to the server only
+     * when set here — a server without rooms has no use for it.
+     */
     namespace?: string;
-    /** Preferred client id; the server may override it. */
+    /** Preferred client id; the server may override or ignore it. */
     clientId?: string;
-    /** Rooms joined automatically on every (re)connect. */
+    /** Rooms joined automatically on every (re)connect (rooms extension). */
     rooms?: string[];
     /**
      * Produces the auth payload. Called before *every* (re)connect, so
@@ -92,7 +119,7 @@ export interface WSClientOptions<TAuth = unknown> {
      */
     auth?: () => TAuth | Promise<TAuth>;
     /**
-     * Let the first `subscribe()`/`publish()` start the connection.
+     * Let the first `send()`/`subscribe()`/`publish()` start the connection.
      * Default `true` — with an outbox and infinite retry, requiring an explicit
      * `connect()` first is ceremony whose only product is an error for people
      * who forgot.
@@ -127,9 +154,18 @@ export interface WSClientOptions<TAuth = unknown> {
     decode?: WSDecoder;
 }
 /**
- * A reconnecting WebSocket client with namespaces, rooms and presence.
+ * A reconnecting WebSocket client: plain messages to and from the server, and
+ * optionally namespaces, rooms and presence on top.
+ *
+ * @example Messages — the server is the peer
+ * ```ts
+ * const ws = createWSClient({ url: "/ws", auth: () => session.token });
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * await ws.send({ op: "typing" }); // fire-and-forget
+ * const doc = await ws.send({ op: "load", id: 42 }, { ack: true }); // reply
+ * ```
  *
- * @example
+ * @example Rooms — the server relays between clients
  * ```ts
  * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
  * const unsub = await ws.subscribe("chat", (msg) => console.log(msg.payload));
@@ -142,7 +178,7 @@ export declare class WSClient<TAuth = unknown> {
     logger: Logger | null;
     /**
      * Nothing connects here — the socket opens on the first `connect()`,
-     * `subscribe()` or `publish()`.
+     * `send()`, `subscribe()` or `publish()`.
      *
      * @param options - see {@link WSClientOptions}; every field has a default
      */
@@ -161,9 +197,15 @@ export declare class WSClient<TAuth = unknown> {
     get connected(): boolean;
     /** Current lifecycle state. See {@link WSConnectionState}. */
     get connectionState(): WSConnectionState;
-    /** Server-assigned id, available once connected. */
+    /**
+     * Server-assigned id, available once connected. Stays `null` when the
+     * server assigns none (a core-only server may not).
+     */
     get clientId(): string | null;
-    /** Active namespace — the server's assignment wins over the request. */
+    /**
+     * Active namespace — the server's assignment wins over the request. Falls
+     * back to the requested one when the server assigns none.
+     */
     get namespace(): string;
     /** Resolved endpoint. A copy — mutating it does not affect the client. */
     get url(): URL;
@@ -264,7 +306,8 @@ export declare class WSClient<TAuth = unknown> {
      * @param options - pass `presence` to enable membership tracking
      * @returns detaches this handler; also `Symbol.dispose`-compatible, and
      * idempotent, so calling it twice is harmless
-     * @throws {WSRemoteError} when connected and the server refuses
+     * @throws {WSRemoteError} when connected and the server refuses — with code
+     * `unsupported` when it does not implement rooms at all
      * @throws {WSDisposedError} when the client was disposed
      *
      * @example
@@ -300,6 +343,73 @@ export declare class WSClient<TAuth = unknown> {
      * @returns a copy of the members; empty when the room has no presence
      */
     members(room: string): string[];
+    /**
+     * Sends a message to the server — the room-free way to talk to it, and all
+     * a core-only server has to understand.
+     *
+     * Fire-and-forget: resolves as soon as the frame is written to the socket.
+     * While disconnected it is buffered and resolves when flushed after the
+     * next connect — bounded by `sendTimeout`, never indefinitely. 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`. Pass
+     * `{ ack: true }` when that matters.
+     *
+     * Safe to call without awaiting: the returned promise is marked handled,
+     * so a failure nobody awaits is not an unhandled rejection. Await it to
+     * learn about one.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - see {@link WSSendOptions}
+     * @returns resolves once the frame is written to the socket
+     * @throws {WSTimeoutError} still buffered when `sendTimeout` elapsed
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close
+     *
+     * @example
+     * ```ts
+     * ws.send({ op: "cursor", x: 10, y: 20 });
+     * ```
+     */
+    send<T = unknown>(payload: T, options?: WSSendOptions & {
+        ack?: false;
+    }): Promise<void>;
+    /**
+     * Sends a message to the server and waits for its acknowledgement.
+     *
+     * Resolves with the reply the server put in the ack — which makes this a
+     * request/response call — or with `undefined` when it sent a bare ack.
+     * Buffered while disconnected like any other send, and one `sendTimeout`
+     * spans queue, flight and ack.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - `{ ack: true }`
+     * @returns the server's reply, `undefined` when there was none
+     * @throws {WSRemoteError} the server rejected it with a `nack` — code
+     * `unsupported` when it accepts no messages at all
+     * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
+     * @throws {WSConnectionLostError} the socket closed before the ack arrived;
+     * the message was not resent
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close
+     *
+     * @example
+     * ```ts
+     * const doc = await ws.send<Doc>({ op: "load", id: 42 }, { ack: true });
+     * ```
+     */
+    send<R = unknown, T = unknown>(payload: T, options: WSSendOptions & {
+        ack: true;
+    }): Promise<R>;
+    /**
+     * Either of the above, decided at runtime by `options.ack`.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - see {@link WSSendOptions}
+     * @returns `undefined` without an ack, the server's reply with one
+     */
+    send<T = unknown>(payload: T, options?: WSSendOptions): Promise<unknown>;
     /**
      * Publishes to a room within this client's namespace.
      *
@@ -345,14 +455,21 @@ export declare class WSClient<TAuth = unknown> {
  * @param options - see {@link WSClientOptions}
  * @returns a client that has not connected yet
  *
- * @example
+ * @example Messages
  * ```ts
  * const ws = createWSClient({
  *     url: "wss://example.com/ws",
- *     namespace: "org-123",
  *     auth: () => session.token, // re-read on every reconnect
  * });
  *
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * const reply = await ws.send({ op: "ping" }, { ack: true });
+ * ```
+ *
+ * @example Rooms
+ * ```ts
+ * const ws = createWSClient({ url: "wss://example.com/ws", namespace: "org-123" });
+ *
  * await ws.subscribe("chat", (msg) => console.log(msg.from, msg.payload));
  * await ws.publish("chat", { text: "hello" });
  * ```

package/dist/client/ws-client.js

@@ -1,6 +1,13 @@
 /**
  * The WebSocket client.
  *
+ * Two ways to use it, freely mixed on one connection:
+ *
+ * - **Messages** (core): `send()` to the server, `on("message")` to receive.
+ *   Needs nothing from the server beyond the core protocol.
+ * - **Rooms** (extension): `subscribe()` / `publish()` / `broadcast()` and
+ *   presence, for servers that relay between clients.
+ *
  * @module
  */
 import { createClog } from "@marianmeres/clog";
@@ -59,9 +66,18 @@ function makeUnsubscriber(fn) {
     return u;
 }
 /**
- * A reconnecting WebSocket client with namespaces, rooms and presence.
+ * A reconnecting WebSocket client: plain messages to and from the server, and
+ * optionally namespaces, rooms and presence on top.
  *
- * @example
+ * @example Messages — the server is the peer
+ * ```ts
+ * const ws = createWSClient({ url: "/ws", auth: () => session.token });
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * await ws.send({ op: "typing" }); // fire-and-forget
+ * const doc = await ws.send({ op: "load", id: 42 }, { ack: true }); // reply
+ * ```
+ *
+ * @example Rooms — the server relays between clients
  * ```ts
  * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
  * const unsub = await ws.subscribe("chat", (msg) => console.log(msg.payload));
@@ -71,6 +87,8 @@ function makeUnsubscriber(fn) {
 export class WSClient {
     #url;
     #requestedNamespace;
+    /** Whether the application chose a namespace, i.e. whether `auth` carries it. */
+    #namespaceRequested;
     #requestedClientId;
     #authFn;
     #autoConnect;
@@ -114,7 +132,7 @@ export class WSClient {
     #wakeListeners = [];
     /**
      * Nothing connects here — the socket opens on the first `connect()`,
-     * `subscribe()` or `publish()`.
+     * `send()`, `subscribe()` or `publish()`.
      *
      * @param options - see {@link WSClientOptions}; every field has a default
      */
@@ -122,6 +140,7 @@ export class WSClient {
         this.logger = options.logger === undefined ? createClog("ws") : options.logger;
         this.#url = WSClient.resolveUrl(options.url ?? DEFAULTS.url);
         this.#requestedNamespace = options.namespace ?? DEFAULTS.namespace;
+        this.#namespaceRequested = options.namespace !== undefined;
         this.#requestedClientId = options.clientId;
         this.#authFn = options.auth;
         this.#autoConnect = options.autoConnect ?? DEFAULTS.autoConnect;
@@ -191,11 +210,17 @@ export class WSClient {
     get connectionState() {
         return this.#state;
     }
-    /** Server-assigned id, available once connected. */
+    /**
+     * Server-assigned id, available once connected. Stays `null` when the
+     * server assigns none (a core-only server may not).
+     */
     get clientId() {
         return this.#clientId;
     }
-    /** Active namespace — the server's assignment wins over the request. */
+    /**
+     * Active namespace — the server's assignment wins over the request. Falls
+     * back to the requested one when the server assigns none.
+     */
     get namespace() {
         return this.#namespace ?? this.#requestedNamespace;
     }
@@ -381,7 +406,8 @@ export class WSClient {
      * @param options - pass `presence` to enable membership tracking
      * @returns detaches this handler; also `Symbol.dispose`-compatible, and
      * idempotent, so calling it twice is harmless
-     * @throws {WSRemoteError} when connected and the server refuses
+     * @throws {WSRemoteError} when connected and the server refuses — with code
+     * `unsupported` when it does not implement rooms at all
      * @throws {WSDisposedError} when the client was disposed
      *
      * @example
@@ -470,7 +496,22 @@ export class WSClient {
     members(room) {
         return this.#rooms.members(room);
     }
-    // --------------------------------------------------------------- sending
+    send(payload, options = {}) {
+        this.#assertUsable();
+        if (options.ack) {
+            const id = this.#nextId();
+            return this.#send({ type: FRAME.MSG, id, payload }, id).then((r) => r.payload);
+        }
+        // No wire id: nothing is coming back. The outbox still needs a key to
+        // buffer it under while offline.
+        const sent = this.#send({ type: FRAME.MSG, payload }, this.#nextId(), false)
+            .then(noop);
+        // Fire-and-forget invites not awaiting, and an ignored rejection is
+        // fatal in Deno and Node. Marked handled, ignoring it is safe; awaiting
+        // it still reports the failure.
+        sent.catch(noop);
+        return sent;
+    }
     /**
      * Publishes to a room within this client's namespace.
      *
@@ -500,7 +541,7 @@ export class WSClient {
             room,
             payload,
             ...(namespace ? { namespace } : {}),
-        }, id);
+        }, id).then(({ recipients }) => ({ recipients }));
     }
     /**
      * Publishes to a room across **all** namespaces.
@@ -518,7 +559,8 @@ export class WSClient {
     broadcast(room, payload) {
         this.#assertUsable();
         const id = this.#nextId();
-        return this.#send({ type: FRAME.BROADCAST, id, room, payload }, id);
+        return this.#send({ type: FRAME.BROADCAST, id, room, payload }, id)
+            .then(({ recipients }) => ({ recipients }));
     }
     // -------------------------------------------------------------- internals
     #nextId() {
@@ -532,7 +574,13 @@ export class WSClient {
         if (this.#state === "idle")
             this.#open();
     }
-    #send(frame, id) {
+    /**
+     * Sends a frame through the outbox: now when connected, buffered otherwise.
+     *
+     * @param id - the frame's wire `id`, or a local key for a frame without one
+     * @param awaitAck - `false` completes the send once written, not once acked
+     */
+    #send(frame, id, awaitAck = true) {
         if (this.#autoConnect)
             this.#ensureStarted();
         // Nothing restarts from `terminated` except an explicit connect(), so
@@ -545,14 +593,19 @@ export class WSClient {
         if (!canSendNow && this.#outboxMaxSize === 0) {
             return Promise.reject(new WSNotConnectedError());
         }
-        const promise = this.#outbox.track(id, frame, !canSendNow);
-        if (canSendNow) {
-            const error = this.#sendRaw(frame);
-            if (error)
-                this.#outbox.fail(id, error);
-        }
+        const promise = this.#outbox.track(id, frame, !canSendNow, awaitAck);
+        if (canSendNow)
+            this.#transmit(id, frame);
         return promise;
     }
+    /** Writes a tracked frame and reports the outcome to the outbox. */
+    #transmit(id, frame) {
+        const error = this.#sendRaw(frame);
+        if (error)
+            this.#outbox.fail(id, error);
+        else
+            this.#outbox.transmitted(id);
+    }
     /**
      * Sends a control frame that must never be buffered.
      *
@@ -561,11 +614,10 @@ export class WSClient {
      * them twice.
      */
     #sendControl(frame) {
-        const id = "id" in frame ? frame.id : this.#nextId();
-        const promise = this.#outbox.track(id, frame, false);
+        const promise = this.#outbox.track(frame.id, frame, false);
         const error = this.#sendRaw(frame);
         if (error)
-            this.#outbox.fail(id, error);
+            this.#outbox.fail(frame.id, error);
         return promise;
     }
     /**
@@ -657,13 +709,14 @@ export class WSClient {
         // The await above yields; a close may have superseded this socket.
         if (generation !== this.#generation)
             return;
+        // Only what the application actually chose goes on the wire: a server
+        // without rooms should not have to wade through identity it never uses.
         this.#sendRaw({
             type: FRAME.AUTH,
-            id: this.#nextId(),
             protocol: PROTOCOL_VERSION,
             payload,
             ...(this.#requestedClientId ? { clientId: this.#requestedClientId } : {}),
-            namespace: this.#requestedNamespace,
+            ...(this.#namespaceRequested ? { namespace: this.#requestedNamespace } : {}),
         });
         // Without this, a server that accepts the socket then never replies
         // leaves us in `authenticating` forever — the heartbeat has not started
@@ -693,7 +746,7 @@ export class WSClient {
                 this.#onHello(frame.clientId, frame.namespace, frame.protocol);
                 break;
             case FRAME.ACK:
-                this.#outbox.settle(frame.id, frame.recipients ?? 0);
+                this.#outbox.settle(frame.id, frame.recipients ?? 0, frame.payload);
                 break;
             case FRAME.NACK:
                 this.#outbox.fail(frame.id, new WSRemoteError(frame.error));
@@ -701,7 +754,11 @@ export class WSClient {
             case FRAME.MSG: {
                 const { type: _t, ...message } = frame;
                 this.#emit("message", message);
-                this.#rooms.deliver(message.room, message, (e) => this.#fail(e, "message handler threw"));
+                // Only a room delivery carries `room`. A direct message from the
+                // server has no room to route by — the firehose is its only way in.
+                if (typeof message.room === "string") {
+                    this.#rooms.deliver(message.room, message, (e) => this.#fail(e, "message handler threw"));
+                }
                 break;
             }
             case FRAME.PRESENCE: {
@@ -725,14 +782,16 @@ export class WSClient {
         if (protocol !== PROTOCOL_VERSION) {
             this.logger?.warn?.(`protocol version mismatch (client ${PROTOCOL_VERSION}, server ${protocol})`);
         }
-        this.#clientId = clientId;
-        this.#namespace = namespace;
+        // Identity belongs to the rooms extension: a core-only server may
+        // assign none, and then there is none — not a stale one from before.
+        this.#clientId = typeof clientId === "string" && clientId ? clientId : null;
+        this.#namespace = typeof namespace === "string" && namespace ? namespace : null;
         this.#attempt = 0;
         this.#lastError = null;
         if (!this.#setState("open"))
             return;
-        this.logger?.debug?.(`connected as ${clientId} in "${namespace}"`);
-        this.#emit("connected", { clientId, namespace });
+        this.logger?.debug?.(`connected${this.#clientId ? ` as ${this.#clientId}` : ""} in "${this.namespace}"`);
+        this.#emit("connected", { clientId: this.#clientId, namespace: this.namespace });
         this.#heartbeat.start();
         this.#settleConnect(null);
         // Order matters and is not cosmetic: re-subscribe first, then flush.
@@ -749,11 +808,8 @@ export class WSClient {
         const buffered = this.#outbox.drain();
         if (buffered.length) {
             this.logger?.debug?.(`flushing ${buffered.length} buffered frame(s)`);
-            for (const frame of buffered) {
-                const error = this.#sendRaw(frame);
-                if (error && "id" in frame)
-                    this.#outbox.fail(frame.id, error);
-            }
+            for (const { id, frame } of buffered)
+                this.#transmit(id, frame);
         }
     }
     #onClose(code, reason) {
@@ -792,8 +848,10 @@ export class WSClient {
      * `sub`/`unsub` resolve: the room registry is authoritative locally and the
      * re-subscribe step will establish it on the next connection, which is
      * exactly the contract of a `subscribe()` issued while offline — and the
-     * server forgets its rooms on close anyway. Publishes reject: they were not
-     * delivered, and at-most-once means they will not be resent.
+     * server forgets its rooms on close anyway. Publishes and acked sends
+     * reject: they were not confirmed, and at-most-once means they will not be
+     * resent. (A send without an ack is never in flight — it completed when it
+     * was written.)
      */
     #settleInFlight() {
         this.#outbox.settleInFlight((frame) => frame.type === FRAME.SUB || frame.type === FRAME.UNSUB
@@ -943,14 +1001,21 @@ export class WSClient {
  * @param options - see {@link WSClientOptions}
  * @returns a client that has not connected yet
  *
- * @example
+ * @example Messages
  * ```ts
  * const ws = createWSClient({
  *     url: "wss://example.com/ws",
- *     namespace: "org-123",
  *     auth: () => session.token, // re-read on every reconnect
  * });
  *
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * const reply = await ws.send({ op: "ping" }, { ack: true });
+ * ```
+ *
+ * @example Rooms
+ * ```ts
+ * const ws = createWSClient({ url: "wss://example.com/ws", namespace: "org-123" });
+ *
  * await ws.subscribe("chat", (msg) => console.log(msg.from, msg.payload));
  * await ws.publish("chat", { text: "hello" });
  * ```

package/dist/mod.d.ts

@@ -1,6 +1,13 @@
 /**
- * `@marianmeres/ws` — a WebSocket client with namespaces, rooms, presence and
- * auto-reconnect.
+ * `@marianmeres/ws` — a WebSocket client with auto-reconnect, half-open
+ * detection and buffered sends, plus optional namespaces, rooms and presence.
+ *
+ * Two ways to use it, freely mixed on one connection:
+ *
+ * - **Messages** — `send()` to the server, `on("message")` to receive. The
+ *   server only has to implement the small core of the protocol.
+ * - **Rooms** — `subscribe()` / `publish()` / `broadcast()` and presence, for
+ *   a server that relays between clients (the rooms extension).
  *
  * The client is dependency-light and runs in browsers, Deno, Node 22+, Bun and
  * Workers — `WebSocket` is a global in all of them, so there is no polyfill and
@@ -9,7 +16,19 @@
  * The reference server lives behind a separate entry point,
  * `@marianmeres/ws/server`, so `demino` never lands in a browser bundle.
  *
- * @example
+ * @example Messages
+ * ```ts
+ * import { createWSClient } from "@marianmeres/ws";
+ *
+ * const ws = createWSClient({ url: "/ws", auth: () => session.token });
+ *
+ * ws.on("message", (msg) => console.log(msg.payload));
+ *
+ * ws.send({ op: "typing" }); // fire-and-forget
+ * const doc = await ws.send({ op: "load", id: 42 }, { ack: true }); // the reply
+ * ```
+ *
+ * @example Rooms
  * ```ts
  * import { createWSClient } from "@marianmeres/ws";
  *
@@ -24,7 +43,7 @@
  *
  * @module
  */
-export { createWSClient, type SubscribeOptions, WSClient, type WSClientOptions, type WSConnectionState, type WSEvents, type WSState, } from "./client/ws-client.js";
+export { createWSClient, type SubscribeOptions, WSClient, type WSClientOptions, type WSConnectionState, type WSEvents, type WSSendOptions, type WSState, } from "./client/ws-client.js";
 export type { MessageHandler, PresenceHandler } from "./client/rooms.js";
 export { backoffDelay } from "./client/backoff.js";
 export * from "./protocol/mod.js";

package/dist/mod.js

@@ -1,6 +1,13 @@
 /**
- * `@marianmeres/ws` — a WebSocket client with namespaces, rooms, presence and
- * auto-reconnect.
+ * `@marianmeres/ws` — a WebSocket client with auto-reconnect, half-open
+ * detection and buffered sends, plus optional namespaces, rooms and presence.
+ *
+ * Two ways to use it, freely mixed on one connection:
+ *
+ * - **Messages** — `send()` to the server, `on("message")` to receive. The
+ *   server only has to implement the small core of the protocol.
+ * - **Rooms** — `subscribe()` / `publish()` / `broadcast()` and presence, for
+ *   a server that relays between clients (the rooms extension).
  *
  * The client is dependency-light and runs in browsers, Deno, Node 22+, Bun and
  * Workers — `WebSocket` is a global in all of them, so there is no polyfill and
@@ -9,7 +16,19 @@
  * The reference server lives behind a separate entry point,
  * `@marianmeres/ws/server`, so `demino` never lands in a browser bundle.
  *
- * @example
+ * @example Messages
+ * ```ts
+ * import { createWSClient } from "@marianmeres/ws";
+ *
+ * const ws = createWSClient({ url: "/ws", auth: () => session.token });
+ *
+ * ws.on("message", (msg) => console.log(msg.payload));
+ *
+ * ws.send({ op: "typing" }); // fire-and-forget
+ * const doc = await ws.send({ op: "load", id: 42 }, { ack: true }); // the reply
+ * ```
+ *
+ * @example Rooms
  * ```ts
  * import { createWSClient } from "@marianmeres/ws";
  *