@marianmeres/ws 0.3.0 → 0.5.0

package/dist/client/ws-client.js

@@ -1,13 +1,20 @@
 /**
  * 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";
 import { createPubSub } from "@marianmeres/pubsub";
 import { base36 } from "@marianmeres/uid";
 import { CLOSE, DEFAULT_NAMESPACE, DEFAULT_TERMINAL_CLOSE_CODES, FRAME, PROTOCOL_VERSION, } from "../protocol/constants.js";
-import { WSConnectTimeoutError, WSDisposedError, WSError, WSNotConnectedError, WSRemoteError, WSTerminatedError, } from "../protocol/errors.js";
+import { WSConnectionLostError, WSConnectTimeoutError, WSDisposedError, WSError, WSNotConnectedError, WSRemoteError, WSTerminatedError, } from "../protocol/errors.js";
 import { backoffDelay } from "./backoff.js";
 import { Heartbeat } from "./heartbeat.js";
 import { Outbox } from "./outbox.js";
@@ -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 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));
@@ -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;
@@ -96,7 +114,12 @@ export class WSClient {
     #namespace = null;
     #attempt = 0;
     #lastError = null;
-    #intentional = false;
+    /**
+     * Kept apart from `#lastError` on purpose: a handler that throws after the
+     * terminal close would overwrite `#lastError` and a send rejected from the
+     * `terminated` state would then blame the wrong thing.
+     */
+    #terminalError = null;
     #rooms = new RoomRegistry();
     #outbox;
     #heartbeat;
@@ -109,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
      */
@@ -117,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;
@@ -186,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;
     }
@@ -303,7 +333,6 @@ export class WSClient {
                 this.#settleConnect(new WSConnectTimeoutError(this.#connectTimeout));
             }, this.#connectTimeout);
         }
-        this.#intentional = false;
         if (this.#state === "idle" || this.#state === "terminated")
             this.#open();
         return promise;
@@ -314,16 +343,29 @@ export class WSClient {
      * Resumable: handlers, room subscriptions and buffered sends all survive,
      * so a later `connect()` picks up exactly where this left off. Use
      * {@link dispose} for terminal teardown.
+     *
+     * Emits `close` with {@link CLOSE.CLIENT_GONE} and `willReconnect: false`
+     * when there was a socket to close; nothing when already idle, reconnecting
+     * or terminated.
      */
     disconnect() {
         if (this.#state === "disposed")
             return;
         this.logger?.debug?.("disconnect()");
-        this.#intentional = true;
         this.#clearTimers();
         this.#heartbeat.stop();
         this.#settleConnect(new WSTerminatedError(CLOSE.CLIENT_GONE, "disconnect() called"));
-        this.#closeSocket(CLOSE.CLIENT_GONE, "client disconnect");
+        const reason = "client disconnect";
+        const closed = this.#socket !== null;
+        this.#closeSocket(CLOSE.CLIENT_GONE, reason);
+        if (closed) {
+            this.#emit("close", {
+                code: CLOSE.CLIENT_GONE,
+                reason,
+                willReconnect: false,
+            });
+        }
+        this.#settleInFlight();
         this.#setState("idle");
     }
     /**
@@ -364,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
@@ -386,6 +429,10 @@ export class WSClient {
                     type: FRAME.UNSUB,
                     id: this.#nextId(),
                     rooms: [room],
+                }).catch((e) => {
+                    // Not actionable: the handler is already detached locally and
+                    // the server drops the room on close anyway.
+                    this.logger?.debug?.(`unsub "${room}" unconfirmed: ${e.message}`);
                 });
             }
         });
@@ -449,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.
      *
@@ -466,6 +528,8 @@ export class WSClient {
      * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
      * @throws {WSOutboxDropError} evicted from a full outbox
      * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close, which only an
+     * explicit `connect()` recovers from — rejected at once, not buffered
      * @throws {WSRemoteError} the server rejected it with a `nack`
      */
     publish(room, payload, namespace) {
@@ -477,7 +541,7 @@ export class WSClient {
             room,
             payload,
             ...(namespace ? { namespace } : {}),
-        }, id);
+        }, id).then(({ recipients }) => ({ recipients }));
     }
     /**
      * Publishes to a room across **all** namespaces.
@@ -495,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() {
@@ -509,19 +574,38 @@ 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
+        // buffering here would only defer the same answer by `sendTimeout`.
+        if (this.#terminalError && this.#state === "terminated") {
+            return Promise.reject(this.#terminalError);
+        }
         const canSendNow = this.connected &&
             this.#socket?.readyState === WebSocket.OPEN;
         if (!canSendNow && this.#outboxMaxSize === 0) {
             return Promise.reject(new WSNotConnectedError());
         }
-        const promise = this.#outbox.track(id, frame, !canSendNow);
+        const promise = this.#outbox.track(id, frame, !canSendNow, awaitAck);
         if (canSendNow)
-            this.#sendRaw(frame);
+            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.
      *
@@ -530,21 +614,28 @@ export class WSClient {
      * them twice.
      */
     #sendControl(frame) {
-        const id = "id" in frame ? frame.id : this.#nextId();
-        const promise = this.#outbox.track(id, frame, false);
-        this.#sendRaw(frame);
+        const promise = this.#outbox.track(frame.id, frame, false);
+        const error = this.#sendRaw(frame);
+        if (error)
+            this.#outbox.fail(frame.id, error);
         return promise;
     }
+    /**
+     * @returns the error the send failed with — a frame that never left cannot
+     * be acknowledged, so the caller settles its promise instead of letting it
+     * wait out `sendTimeout`.
+     */
     #sendRaw(frame) {
         const socket = this.#socket;
         if (!socket || socket.readyState !== WebSocket.OPEN)
-            return;
+            return null;
         try {
             socket.send(this.#encode(frame));
         }
         catch (e) {
-            this.#fail(e, "send failed");
+            return this.#fail(e, "send failed");
         }
+        return null;
     }
     #open() {
         // Defensive: every caller already guards this, but a second socket
@@ -556,7 +647,7 @@ export class WSClient {
         }
         if (!this.#setState("connecting"))
             return;
-        this.#intentional = false;
+        this.#terminalError = null;
         const generation = ++this.#generation;
         let socket;
         try {
@@ -568,6 +659,9 @@ export class WSClient {
             return;
         }
         this.#socket = socket;
+        // Without this a binary frame arrives as a Blob, which no synchronous
+        // decoder can read — the `WSDecoder` contract promises an `ArrayBuffer`.
+        socket.binaryType = "arraybuffer";
         this.logger?.debug?.(`connecting to ${this.#url.href}`);
         socket.onopen = () => {
             if (generation !== this.#generation)
@@ -601,6 +695,13 @@ export class WSClient {
             payload = (await this.#authFn?.()) ?? null;
         }
         catch (e) {
+            // The await yields, so this rejection may belong to a socket that a
+            // later connect() already replaced — closing on it would kill the
+            // healthy socket that took its place.
+            if (generation !== this.#generation) {
+                this.logger?.debug?.("superseded auth attempt failed");
+                return;
+            }
             this.#fail(e, "auth payload failed");
             this.#forceClose(CLOSE.PROTOCOL_ERROR, "auth payload failed");
             return;
@@ -608,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
@@ -644,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));
@@ -652,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: {
@@ -676,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.
@@ -700,8 +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)
-                this.#sendRaw(frame);
+            for (const { id, frame } of buffered)
+                this.#transmit(id, frame);
         }
     }
     #onClose(code, reason) {
@@ -710,14 +818,14 @@ export class WSClient {
         this.#heartbeat.stop();
         this.#socket = null;
         const terminal = this.#terminalCodes.includes(code);
-        const willReconnect = !this.#intentional && !terminal &&
-            this.#state !== "disposed";
+        const willReconnect = !terminal && this.#state !== "disposed";
         this.logger?.debug?.(`closed (${code}${reason ? ` ${reason}` : ""}), reconnect=${willReconnect}`);
         this.#emit("close", { code, reason, willReconnect });
         if (terminal) {
             this.#setState("terminated");
             const error = new WSTerminatedError(code, reason);
             this.#lastError = error;
+            this.#terminalError = error;
             // Loud on purpose: this is the only path where a client that
             // otherwise retries forever gives up, and a silent one looks
             // exactly like a network that never came back.
@@ -727,12 +835,29 @@ export class WSClient {
             this.#emit("terminated", { code, reason });
             return;
         }
+        this.#settleInFlight();
         if (!willReconnect) {
             this.#setState("idle");
             return;
         }
         this.#scheduleReconnect();
     }
+    /**
+     * Answers the frames that were on the wire when the socket went away.
+     *
+     * `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 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
+            ? null
+            : new WSConnectionLostError());
+    }
     #scheduleReconnect() {
         if (!this.#setState("reconnecting"))
             return;
@@ -864,6 +989,7 @@ export class WSClient {
         this.#lastError = err;
         this.logger?.error?.(`${context}: ${err.message}`);
         this.#emit("error", err);
+        return err;
     }
 }
 /**
@@ -875,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";
  *

package/dist/protocol/constants.d.ts

@@ -11,8 +11,13 @@
  *
  * It costs nothing today and it is the only thing that makes a breaking
  * protocol change survivable later.
+ *
+ * Version 2 split the protocol into a required **core** (handshake, messages
+ * in both directions, heartbeat) and an optional **rooms extension**
+ * (subscriptions, publishing, presence, broadcast), so a server that only
+ * needs a data channel implements the core and nothing else.
  */
-export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_VERSION = 2;
 /** Namespace used when the client does not specify one. */
 export declare const DEFAULT_NAMESPACE = "default";
 /**
@@ -21,34 +26,43 @@ export declare const DEFAULT_NAMESPACE = "default";
  * Note these are *protocol* types and have nothing to do with whatever the
  * application puts inside `payload` — the payload is opaque and is never
  * inspected nor mutated by this library.
+ *
+ * Every server implements the **core** frames. The **rooms extension**
+ * frames are sent only when the application uses rooms (`subscribe()`,
+ * `publish()`, `broadcast()`, presence), so a server that does not support
+ * them never sees one.
  */
 export declare const FRAME: {
     /** Handshake. Always the first frame; carries the auth payload. */
     readonly AUTH: "auth";
-    /** Join one or more rooms, optionally with presence. */
-    readonly SUB: "sub";
-    /** Leave one or more rooms. */
-    readonly UNSUB: "unsub";
-    /** Publish into a room within the connection's own namespace. */
-    readonly PUB: "pub";
-    /** Publish into a room across every namespace. Gated server-side. */
-    readonly BROADCAST: "broadcast";
     /** Liveness probe. Answered with `pong`. */
     readonly PING: "ping";
-    /** Handshake accepted; carries the assigned id, namespace and version. */
+    /** Handshake accepted; carries the protocol version (and, with rooms, identity). */
     readonly HELLO: "hello";
-    /** Positive acknowledgement of a correlated request. */
+    /** Positive acknowledgement of a frame that carried an `id`; may carry a reply. */
     readonly ACK: "ack";
     /** Negative acknowledgement; carries a `WSErrorInfo`. */
     readonly NACK: "nack";
-    /** A message delivered to a subscribed room. */
-    readonly MSG: "msg";
-    /** A membership change in a presence-enabled room. */
-    readonly PRESENCE: "presence";
     /** Reply to `ping`. */
     readonly PONG: "pong";
     /** Uncorrelated error — not tied to any request id. */
     readonly ERROR: "error";
+    /**
+     * A message. Client -> server it is addressed to the server itself;
+     * server -> client it is either a direct message (core) or a room delivery
+     * (rooms extension, recognisable by its `room` field).
+     */
+    readonly MSG: "msg";
+    /** Join one or more rooms, optionally with presence. */
+    readonly SUB: "sub";
+    /** Leave one or more rooms. */
+    readonly UNSUB: "unsub";
+    /** Publish into a room within the connection's own namespace. */
+    readonly PUB: "pub";
+    /** Publish into a room across every namespace. Gated server-side. */
+    readonly BROADCAST: "broadcast";
+    /** A membership change in a presence-enabled room. */
+    readonly PRESENCE: "presence";
 };
 /**
  * WebSocket close codes.
@@ -99,10 +113,15 @@ export declare const ERROR_CODE: {
     readonly BAD_REQUEST: "bad_request";
     /** Frame rate cap exceeded. */
     readonly RATE_LIMITED: "rate_limited";
+    /**
+     * A frame type this server does not implement — typically a rooms frame
+     * sent to a core-only server, or a `msg` to a server with no handler.
+     */
+    readonly UNSUPPORTED: "unsupported";
     /** Unexpected server-side failure. */
     readonly INTERNAL: "internal";
 };
-/** Presence event kinds. */
+/** Presence event kinds (rooms extension). */
 export declare const PRESENCE: {
     /** Full membership snapshot, sent on every (re)subscribe. */
     readonly SYNC: "sync";