@orkestrel/websocket 0.0.11 → 0.0.12

package/dist/src/server/index.d.cts

@@ -1,7 +1,7 @@
-import { Duplex } from 'node:stream';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { Duplex } from 'node:stream';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
  * Computes the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
@@ -17,27 +17,25 @@ import { EmitterInterface } from '@orkestrel/emitter';
 export declare function computeWebSocketAccept(key: string): string;
 
 /**
- * Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket.
+ * Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket —
+ * server mode when a `key` is given, client mode otherwise.
  *
  * @remarks
- * The construction entry point for the {@link NodeWebSocketInterface}. Pass
- * the upgraded `socket` plus the client's `Sec-WebSocket-Key` as `key` to run in SERVER
- * mode — the wrapper writes the `101 Switching Protocols` handshake and sends unmasked
- * frames; omit `key` for CLIENT mode (no handshake, masked frames). This is the
- * lean-native handle; it speaks only the WebSocket wire protocol — an MCP transport (the
- * later chunk) is built ON it. It is the WebSocket counterpart to
- * `createSQLiteDatabase` / `createIndexedDBDatabase`.
+ * The construction entry point for the {@link NodeWebSocketInterface}. In server mode the
+ * wrapper writes the `101 Switching Protocols` handshake and sends unmasked frames; in
+ * client mode it writes no handshake and masks every outgoing frame. This is the
+ * lean-native handle: it speaks the WebSocket wire protocol and nothing above it, so a
+ * message transport is built on it rather than into it.
  *
  * @param options - The {@link NodeWebSocketOptions} (`socket`, optional `key` / `head` /
  *   `protocol` / `on`)
  * @returns A typed {@link NodeWebSocketInterface}
  * @throws A `WebSocketError` coded `OPTION` when `payload`, `timeout`, `key`, or `protocol` is refused, thrown before the wrapper writes to or assumes ownership of the `socket`
  *
- * @example
+ * @example Accept an upgrade and echo messages (server mode)
  * ```ts
- * import { createNodeWebSocket } from '@src/server'
+ * import { createNodeWebSocket } from '@orkestrel/websocket'
  *
- * // In a node:http 'upgrade' handler — server mode, identified by the client key:
  * server.on('upgrade', (request, socket, head) => {
  * 	const key = request.headers['sec-websocket-key']
  * 	if (typeof key !== 'string') {
@@ -46,10 +44,12 @@ export declare function computeWebSocketAccept(key: string): string;
  * 	}
  * 	const ws = createNodeWebSocket({
  * 		socket,
- * 		key, // present => server mode + 101 handshake
- * 		head,
- * 		on: { message: (text) => ws.send(`echo: ${text}`) },
+ * 		key,
+ * 		head, // any bytes already buffered after the upgrade headers
+ * 		on: { message: (text) => ws.send(`echo: ${text}`) }, // wired before the first frame arrives
  * 	})
+ * 	ws.emitter.on('message', (text) => log('echoed', text)) // a second observer of the same event
+ * 	ws.emitter.on('close', (code, reason) => log('closed', code, reason))
  * })
  * ```
  */
@@ -64,7 +64,7 @@ export declare function createNodeWebSocket(options: NodeWebSocketOptions): Node
  * the 7-bit form below 126, the `126` + 16-bit form below 65 536, or the `127` +
  * 64-bit form beyond; when `masked` is set the mask bit is set, a 4-byte key (supplied
  * through `options.mask`, else random) is written, and the payload is XOR-masked. Server→
- * client frames are unmasked (the default); pass `masked: true` to encode a CLIENT
+ * client frames are unmasked (the default); pass `masked: true` to encode a client
  * frame (for example to feed the parser in a test). A `string` payload is encoded as
  * UTF-8. Returns one contiguous `Buffer` (header + payload), so the wrapper writes it
  * with a single `socket.write`. Pure.
@@ -78,7 +78,8 @@ export declare function createNodeWebSocket(options: NodeWebSocketOptions): Node
 export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | string, options?: WebSocketEncodeOptions): Buffer;
 
 /**
- * Checks whether a numeric value is a valid RFC 6455 close status code to RECEIVE (§7.4.1).
+ * Checks whether a numeric value is a close status code an RFC 6455 endpoint may
+ * receive (§7.4.1).
  *
  * @remarks
  * True for `1000`–`1003`, `1007`–`1014`, and the application range `3000`–`4999`; false
@@ -101,7 +102,8 @@ export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | s
 export declare function isCloseCode(code: number): boolean;
 
 /**
- * Checks whether a value is a {@link WebSocketError}.
+ * Checks whether a caught value is a {@link WebSocketError}, narrowing it so a `catch` can
+ * branch on `error.code`.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a `WebSocketError`; false otherwise
@@ -157,14 +159,14 @@ export declare function isWebSocketKey(key: string): boolean;
 export declare function isWebSocketProtocol(protocol: string): boolean;
 
 /**
- * Checks whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
+ * Checks whether the next frame uses the shortest valid RFC 6455 payload-length
+ * encoding, answering `undefined` until its length prefix is complete.
  *
  * @remarks
- * Returns `undefined` until the complete length prefix is buffered. The 16-bit form
- * is canonical only for lengths at least 126; the 64-bit form only for lengths at
- * least 65,536 and with its most-significant bit clear (RFC 6455 §5.2). Reads the same
- * length prefix as {@link measureWebSocketFrame}, under the same incomplete-buffer
- * contract. Pure; never throws.
+ * The 16-bit form is canonical only for lengths at least 126; the 64-bit form only for
+ * lengths at least 65,536 and with its most-significant bit clear (RFC 6455 §5.2). Reads
+ * the same length prefix as {@link measureWebSocketFrame}, under the same
+ * incomplete-buffer contract. Pure; never throws.
  *
  * @param buffer - The accumulation buffer containing the next frame header
  * @returns Its canonicality, or `undefined` while the length prefix is incomplete
@@ -177,15 +179,15 @@ export declare function isWebSocketProtocol(protocol: string): boolean;
 export declare function matchesWebSocketCanonical(buffer: Buffer): boolean | undefined;
 
 /**
- * Reads the declared payload length off the front of a buffer, without buffering or
- * reading the payload itself.
+ * Reads the declared payload length off the front of a buffer without buffering or
+ * reading the payload itself, answering `undefined` until the length field is complete.
  *
  * @remarks
  * Decodes only byte 1's 7-bit length field, extended by the 16-bit (`126`) or 64-bit
  * (`127`) form exactly like `parseWebSocketFrame` — but stops there, so a caller
  * can reject an over-cap frame the moment its length is known, before the payload
- * bytes have even arrived. Returns `undefined` until the length field itself is fully
- * buffered (mirrors the parser's incomplete-buffer contract). Pure; never throws.
+ * bytes have even arrived. The incomplete-buffer contract mirrors the parser's. Pure;
+ * never throws.
  *
  * @param buffer - The accumulation buffer to read the next frame's length from
  * @returns The declared payload length, or `undefined` when the buffer is too short to know it yet
@@ -199,18 +201,19 @@ export declare function matchesWebSocketCanonical(buffer: Buffer): boolean | und
 export declare function measureWebSocketFrame(buffer: Buffer): number | undefined;
 
 /**
- * Represents a server-native WebSocket over a raw upgraded `node:stream` Duplex — the lean
- * wrapper around the RFC 6455 wire protocol.
+ * Implements the wrapper contract over a raw upgraded `node:stream` Duplex socket,
+ * driving the RFC 6455 handshake, the frame codec, auto-pong, and the close handshake,
+ * and surfacing every event on an owned `emitter`.
  *
  * @remarks
- * Created by `createNodeWebSocket`. When given a client `key` it runs in SERVER mode —
+ * Created by `createNodeWebSocket`. When given a client `key` it runs in server mode —
  * it writes the `101 Switching Protocols` handshake (`computeWebSocketAccept(key)`) and
- * emits `open`; given no key it runs in CLIENT mode (no handshake, frames masked). It
+ * emits `open`; given no key it runs in client mode (no handshake, frames masked). It
  * then listens on the socket's `data`, accumulating bytes in `#buffer` and decoding
  * every complete frame with {@link parseWebSocketFrame} (slicing `consumed` and
- * re-parsing the remainder): a TEXT frame — reassembling continuation fragments across
- * `fin: false` frames — decodes to UTF-8 and emits `message`; a PING is auto-answered
- * with a PONG and emits `ping`; a PONG emits `pong`; a CLOSE is echoed and ends the
+ * re-parsing the remainder): a text frame — reassembling continuation fragments across
+ * `fin: false` frames — decodes to UTF-8 and emits `message`; a ping is auto-answered
+ * with a pong and emits `ping`; a pong emits `pong`; a close frame is echoed and ends the
  * socket, emitting `close`. `send` writes a text frame, `ping` a ping, `close` a close
  * frame; `destroy` tears down immediately. It owns a typed `#emitter` by composition, and
  * the emitter isolates a throwing listener and routes the error to its own `error` handler
@@ -238,8 +241,8 @@ export declare class NodeWebSocket implements NodeWebSocketInterface {
      * Creates a WebSocket wrapper over an already-upgraded Duplex socket.
      *
      * @remarks
-     * `key` selects the mode: present runs SERVER mode and writes the `101 Switching
-     * Protocols` handshake, omitted runs CLIENT mode and masks every outgoing frame.
+     * `key` selects the mode: present runs server mode and writes the `101 Switching
+     * Protocols` handshake, omitted runs client mode and masks every outgoing frame.
      * {@link NodeWebSocketOptions} describes every member.
      *
      * @param options - The {@link NodeWebSocketOptions} the wrapper is built from
@@ -255,13 +258,13 @@ export declare class NodeWebSocket implements NodeWebSocketInterface {
 }
 
 /**
- * Represents the event map of a {@link NodeWebSocketInterface}.
+ * Represents the event map a {@link NodeWebSocketInterface} emitter carries.
  *
  * @remarks
  * `open` — the handshake completed and the socket is ready. `message` — a text frame
  * arrived (its decoded UTF-8 string). `close` — the connection ended, carrying the
  * labeled `[code, reason]` tuple (each `undefined` when the peer sent none). `error` —
- * the underlying socket faulted (a DOMAIN event and then terminates the wrapper).
+ * the underlying socket faulted (a domain event, and then terminates the wrapper).
  * `ping` / `pong` — a control frame arrived (a ping is auto-answered with a pong).
  * Listener isolation is the emitter's: a listener throw is routed to the emitter's
  * `error` handler (the `error` option), never onto this map, so a buggy observer
@@ -277,7 +280,8 @@ export declare type NodeWebSocketEventMap = {
 };
 
 /**
- * Represents a server-native WebSocket over a raw upgraded socket — the behavioral contract.
+ * Represents the behavioral contract a server-native WebSocket exposes over a raw
+ * upgraded socket.
  *
  * @remarks
  * Created by `createNodeWebSocket`. In server mode it writes the RFC 6455 handshake
@@ -297,25 +301,68 @@ export declare type NodeWebSocketEventMap = {
 export declare interface NodeWebSocketInterface {
     readonly emitter: EmitterInterface<NodeWebSocketEventMap>;
     readonly readyState: WebSocketReadyState;
+    /**
+     * Writes a message as a UTF-8 text frame, masked in client mode and unmasked in server
+     * mode, and does nothing unless `readyState` is open.
+     *
+     * @remarks
+     * The peer's reply arrives back as a `message` event.
+     *
+     * @param message - The text to carry as the frame's payload
+     */
     send(message: string): void;
+    /**
+     * Writes a ping frame with an optional payload, which the peer answers with a pong, and
+     * does nothing unless `readyState` is open.
+     *
+     * @remarks
+     * The answering pong arrives as the `pong` event.
+     *
+     * @param payload - The optional UTF-8 payload to carry
+     * @throws A `WebSocketError` coded `LIMIT` when the UTF-8 payload exceeds
+     *   `WEBSOCKET_CONTROL_MAX_LENGTH`
+     */
     ping(payload?: string): void;
+    /**
+     * Starts the closing handshake: moves to the closing ready state, writes a close frame
+     * carrying the two-byte big-endian `code` and an optional `reason`, and ends the
+     * writable side.
+     *
+     * @remarks
+     * The final `close` event fires after the peer echoes or the socket ends, and a second
+     * call is a no-op. Each refusal leaves `readyState` unchanged.
+     *
+     * @param code - The close status code, defaulting to `WEBSOCKET_CLOSE_NORMAL`
+     * @param reason - The optional UTF-8 reason to carry after the code
+     * @throws A `WebSocketError` coded `CLOSE` for an invalid or fractional `code`, and one
+     *   coded `LIMIT` for a `reason` over `WEBSOCKET_CLOSE_REASON_MAX_LENGTH`
+     */
     close(code?: number, reason?: string): void;
+    /**
+     * Tears the socket down immediately: detaches the wrapper's domain socket listeners,
+     * destroys the socket, emits a final `close`, and tears the emitter down.
+     *
+     * @remarks
+     * Idempotent, and a hard stop rather than a handshake.
+     */
     destroy(): void;
 }
 
 /**
- * Represents the options for `createNodeWebSocket`.
+ * Represents the options for `createNodeWebSocket` — the upgraded `socket`, the `key`
+ * that selects server or client mode, and the listeners, caps, and cancellation signal
+ * the wrapper runs under.
  *
  * @remarks
  * `socket` is the upgraded `node:stream` Duplex (the raw TCP stream after the HTTP
- * upgrade). `key` is the client's `Sec-WebSocket-Key`: present it to run in SERVER
- * mode — the wrapper writes the `101 Switching Protocols` handshake and sends UNMASKED
- * frames; omit it for CLIENT mode — no handshake is written and frames are MASKED (RFC
+ * upgrade). `key` is the client's `Sec-WebSocket-Key`: present it to run in server
+ * mode — the wrapper writes the `101 Switching Protocols` handshake and sends unmasked
+ * frames; omit it for client mode — no handshake is written and frames are masked (RFC
  * 6455 §5.3). `head` is any bytes buffered after the upgrade headers (replayed through
  * the parser). `protocol` is a negotiated subprotocol to echo in the handshake. `on`
  * wires initial listeners at construction — the reserved `on` option; `error` is the
  * emitter's listener-error handler, where a listener throw routes. `payload` caps
- * both a single inbound frame's declared length AND the total bytes of a reassembled
+ * both a single inbound frame's declared length and the total bytes of a reassembled
  * fragmented message (default `WEBSOCKET_MAX_PAYLOAD`) — a breach closes 1009. `timeout`
  * is how long the wrapper waits, after sending a close frame, for the peer's echo before
  * it gives up and tears the socket down (default `WEBSOCKET_CLOSE_TIMEOUT_MS`). `signal`
@@ -339,12 +386,13 @@ export declare interface NodeWebSocketOptions {
 }
 
 /**
- * Decodes a byte sequence as strict UTF-8, or signals it is malformed.
+ * Decodes a byte sequence as strict UTF-8, answering `undefined` when the sequence is
+ * malformed.
  *
  * @remarks
- * Wraps `TextDecoder('utf-8', { fatal: true })` in a try/catch so a malformed sequence
- * returns `undefined` instead of throwing — a guard-adjacent coercer never throws on bad
- * input. Pure.
+ * Wraps `TextDecoder('utf-8', { fatal: true })` in a try/catch, so a malformed sequence
+ * returns rather than throwing — a guard-adjacent coercer never throws on bad input.
+ * Pure.
  *
  * @param bytes - The raw bytes to decode
  * @returns The decoded string, or `undefined` when `bytes` is not valid UTF-8
@@ -358,18 +406,19 @@ export declare interface NodeWebSocketOptions {
 export declare function parseUTF8(bytes: Buffer): string | undefined;
 
 /**
- * Decodes a single RFC 6455 frame from the front of a buffer.
+ * Decodes a single RFC 6455 frame from the front of a buffer, answering `undefined`
+ * while the buffer is incomplete so the caller accumulates and retries.
  *
  * @remarks
  * Reads the FIN bit and opcode (byte 0), the mask bit and 7-bit payload length (byte
  * 1) — extended to a 16-bit length when the 7-bit field is `126`, or a 64-bit length
  * when it is `127` — the optional 4-byte mask key, then the payload, XOR-unmasking it
- * against the key when the mask bit is set (client→server frames MUST be masked, RFC
+ * against the key when the mask bit is set (client→server frames must be masked, RFC
  * 6455 §5.3; an unmasked frame still decodes, leaving the payload as-is, so the caller
- * can enforce policy). Returns `undefined` the moment the buffer is too short for the
- * part it is up to (the length prefix, the mask, or the full payload) — the signal to
- * the caller to read more bytes and retry. `consumed` is the total bytes the frame
- * occupied, so the caller slices the remainder. Pure; never throws on a short buffer.
+ * can enforce policy). The incomplete answer comes the moment the buffer is too short
+ * for the part it is up to: the length prefix, the mask, or the full payload.
+ * `consumed` is the total bytes the frame occupied, so the caller slices the remainder.
+ * Pure; never throws on a short buffer.
  *
  * @param buffer - The accumulation buffer to decode the next frame from
  * @returns The parsed {@link WebSocketFrame}, or `undefined` when the buffer is incomplete
@@ -382,85 +431,200 @@ export declare function parseUTF8(bytes: Buffer): string | undefined;
  */
 export declare function parseWebSocketFrame(buffer: Buffer): WebSocketFrame | undefined;
 
-/** Names the invalid-frame-payload-data status code (RFC 6455 §7.4.1) — for example non-UTF-8 text or an unparseable close reason. */
+/**
+ * Names the invalid-frame-payload-data status code, 1007.
+ *
+ * @remarks
+ * Sent for non-UTF-8 text or an unparseable close reason (RFC 6455 §7.4.1).
+ */
 export declare const WEBSOCKET_CLOSE_INVALID = 1007;
 
-/** Names the normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
+/**
+ * Names the normal-closure status code, 1000.
+ *
+ * @remarks
+ * The default `close` code (RFC 6455 §7.4.1).
+ */
 export declare const WEBSOCKET_CLOSE_NORMAL = 1000;
 
-/** Names the protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
+/**
+ * Names the protocol-error status code, 1002.
+ *
+ * @remarks
+ * Sent when a framing or state rule was violated (RFC 6455 §7.4.1).
+ */
 export declare const WEBSOCKET_CLOSE_PROTOCOL = 1002;
 
-/** Names the maximum UTF-8 close-reason length after the two-byte status code. */
+/**
+ * Names the maximum UTF-8 close-reason length after the two-byte status code, 123.
+ *
+ * @remarks
+ * What is left of {@link WEBSOCKET_CONTROL_MAX_LENGTH} after the close frame's status
+ * code.
+ */
 export declare const WEBSOCKET_CLOSE_REASON_MAX_LENGTH: number;
 
-/** Names the default close-handshake timeout in milliseconds — how long `close()` waits for the peer's echo before tearing the socket down. */
+/**
+ * Names the default close-handshake timeout, 30,000 milliseconds — how long `close` waits
+ * for the peer's echo.
+ *
+ * @remarks
+ * After it expires the wrapper tears the socket down, so a silent peer cannot leak the
+ * handle open.
+ */
 export declare const WEBSOCKET_CLOSE_TIMEOUT_MS = 30000;
 
-/** Names the message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
+/**
+ * Names the message-too-big status code, 1009.
+ *
+ * @remarks
+ * Sent when a reassembled message exceeded the payload cap (RFC 6455 §7.4.1).
+ */
 export declare const WEBSOCKET_CLOSE_TOO_BIG = 1009;
 
-/** Names the unsupported-data status code (RFC 6455 §7.4.1) — the endpoint received a data type it cannot accept, for example binary on a text-only endpoint. */
+/**
+ * Names the unsupported-data status code, 1003.
+ *
+ * @remarks
+ * Sent when the endpoint received a data type it cannot accept (RFC 6455 §7.4.1), for
+ * example binary on a text-only endpoint.
+ */
 export declare const WEBSOCKET_CLOSE_UNSUPPORTED = 1003;
 
-/** Names the maximum control-frame payload length in bytes (RFC 6455 §5.5). */
+/**
+ * Names the maximum control-frame payload length, 125 bytes.
+ *
+ * @remarks
+ * The cap RFC 6455 §5.5 sets on every control frame's payload.
+ */
 export declare const WEBSOCKET_CONTROL_MAX_LENGTH = 125;
 
-/** Names the post-`#fail` flush grace in milliseconds — how long a validation-breach close frame is given to flush through the socket's write buffer before the hard `destroy()` fallback fires (the normal path destroys sooner, on the `end()` flush callback). */
+/**
+ * Names the flush grace, 1,000 milliseconds, a validation-breach close frame is given
+ * before the hard teardown fallback destroys the socket.
+ *
+ * @remarks
+ * Armed after `#fail` writes the close frame, so the frame drains through the socket's
+ * write buffer rather than being discarded. The normal path destroys sooner, on the
+ * `end()` flush callback.
+ */
 export declare const WEBSOCKET_FAIL_TIMEOUT_MS = 1000;
 
 /**
- * Names the RFC 6455 GUID concatenated to a client's `Sec-WebSocket-Key` before the SHA-1
- * hash that yields the `Sec-WebSocket-Accept` response value.
+ * Names the accept GUID concatenated to a client's `Sec-WebSocket-Key` before the accept
+ * hash, '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'.
  *
  * @remarks
- * A fixed, spec-mandated constant (RFC 6455 §4.2.2) — read only by
+ * The base64-encoded SHA-1 of that concatenation is the `Sec-WebSocket-Accept` response
+ * value. A fixed, spec-mandated constant (RFC 6455 §4.2.2) — read only by
  * {@link computeWebSocketAccept}.
  */
 export declare const WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 
-/** Names the default maximum inbound single-frame length AND reassembled-message total byte count (100 MiB — the `ws` package default). */
+/**
+ * Names the default cap on both an inbound frame's declared length and a reassembled
+ * message's total byte count, 104,857,600 bytes (100 MiB).
+ *
+ * @remarks
+ * The same value the `ws` package defaults to. Either breach closes
+ * {@link WEBSOCKET_CLOSE_TOO_BIG}.
+ */
 export declare const WEBSOCKET_MAX_PAYLOAD = 104857600;
 
-/** Names the binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
+/**
+ * Names the binary frame opcode, 0x02.
+ *
+ * @remarks
+ * A raw byte payload (RFC 6455 §5.6).
+ */
 export declare const WEBSOCKET_OPCODE_BINARY = 2;
 
-/** Names the close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
+/**
+ * Names the close frame opcode, 0x08.
+ *
+ * @remarks
+ * A control frame ending the connection (RFC 6455 §5.5.1).
+ */
 export declare const WEBSOCKET_OPCODE_CLOSE = 8;
 
-/** Names the continuation frame opcode — the next fragment of an open data message (RFC 6455 §5.4). */
+/**
+ * Names the continuation frame opcode, 0x00.
+ *
+ * @remarks
+ * The next fragment of an open data message (RFC 6455 §5.4).
+ */
 export declare const WEBSOCKET_OPCODE_CONTINUATION = 0;
 
-/** Names the ping frame opcode — a control frame the peer must answer with a pong (RFC 6455 §5.5.2). */
+/**
+ * Names the ping frame opcode, 0x09.
+ *
+ * @remarks
+ * A control frame the peer must answer with a pong (RFC 6455 §5.5.2).
+ */
 export declare const WEBSOCKET_OPCODE_PING = 9;
 
-/** Names the pong frame opcode — a control frame answering a ping (RFC 6455 §5.5.3). */
+/**
+ * Names the pong frame opcode, 0x0a.
+ *
+ * @remarks
+ * A control frame answering a ping (RFC 6455 §5.5.3).
+ */
 export declare const WEBSOCKET_OPCODE_PONG = 10;
 
-/** Names the text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
+/**
+ * Names the text frame opcode, 0x01.
+ *
+ * @remarks
+ * A UTF-8 payload (RFC 6455 §5.6).
+ */
 export declare const WEBSOCKET_OPCODE_TEXT = 1;
 
-/** Names the ready state for a closed WebSocket (the socket ended). */
+/**
+ * Names the closed ready state, 3.
+ *
+ * @remarks
+ * The state a WebSocket holds after the socket ends.
+ */
 export declare const WEBSOCKET_READY_CLOSED: WebSocketReadyState;
 
-/** Names the ready state for a closing WebSocket (a close frame was sent or received). */
+/**
+ * Names the closing ready state, 2.
+ *
+ * @remarks
+ * The state a WebSocket holds after a close frame is sent or received.
+ */
 export declare const WEBSOCKET_READY_CLOSING: WebSocketReadyState;
 
-/** Names the ready state for a connecting WebSocket (before the handshake completes). */
+/**
+ * Names the connecting ready state, 0.
+ *
+ * @remarks
+ * The state a WebSocket holds before its handshake completes.
+ */
 export declare const WEBSOCKET_READY_CONNECTING: WebSocketReadyState;
 
-/** Names the ready state for an open WebSocket (the handshake completed; frames flow). */
+/**
+ * Names the open ready state, 1.
+ *
+ * @remarks
+ * The state a WebSocket holds after the handshake completes and while frames flow.
+ */
 export declare const WEBSOCKET_READY_OPEN: WebSocketReadyState;
 
-/** Names the WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
+/**
+ * Names the supported protocol version, '13'.
+ *
+ * @remarks
+ * The value this wrapper speaks, carried by the `Sec-WebSocket-Version` handshake header.
+ */
 export declare const WEBSOCKET_VERSION = "13";
 
 /**
  * Represents the options for {@link encodeWebSocketFrame} — how a frame is masked on the wire.
  *
  * @remarks
- * `masked` toggles the mask bit (server→client frames are NOT masked, the default;
- * client→server frames MUST be, RFC 6455 §5.3). `mask` supplies an explicit 4-byte
+ * `masked` toggles the mask bit (server→client frames are not masked, the default;
+ * client→server frames must be, RFC 6455 §5.3). `mask` supplies an explicit 4-byte
  * mask key (deterministic, for tests); when `masked` is true and `mask` is omitted a
  * random key is generated.
  */
@@ -470,15 +634,15 @@ export declare interface WebSocketEncodeOptions {
 }
 
 /**
- * Represents an error thrown by the WebSocket wrapper for a refused caller-supplied value.
+ * Represents an error the WebSocket wrapper throws for a refused caller-supplied value,
+ * carrying a machine-readable `code` and an optional `context`.
  *
  * @remarks
- * Carries a {@link WebSocketErrorCode} and an optional `context` record holding the
- * refused value under a key naming it: an `'OPTION'` carries the offending option
- * (`payload`, `timeout`, `key`, or `protocol`), a `'LIMIT'` carries `size` and the
- * `limit` it exceeded, a `'CLOSE'` carries the refused close `code`, and a `'FRAME'`
- * carries `opcode` or the mask's `size`. Narrow a caught value with
- * {@link isWebSocketError}.
+ * The `code` is a {@link WebSocketErrorCode}; the `context` record holds the refused
+ * value under a key naming it: an `'OPTION'` carries the offending option (`payload`,
+ * `timeout`, `key`, or `protocol`), a `'LIMIT'` carries `size` and the `limit` it
+ * exceeded, a `'CLOSE'` carries the refused close `code`, and a `'FRAME'` carries
+ * `opcode` or the mask's `size`. Narrow a caught value with {@link isWebSocketError}.
  *
  * @example
  * ```ts
@@ -505,7 +669,7 @@ export declare class WebSocketError extends Error {
 }
 
 /**
- * Represents the subject an {@link import('./errors.js').WebSocketError} names as refused.
+ * Represents the subject a `WebSocketError` names as refused.
  *
  * @remarks
  * `OPTION` — a {@link NodeWebSocketOptions} member was refused at construction
@@ -528,7 +692,7 @@ export declare type WebSocketErrorCode = 'OPTION' | 'LIMIT' | 'CLOSE' | 'FRAME';
  * the already-unmasked application data; `consumed` is the total byte count the frame
  * occupied (header + mask + payload), so the caller slices it off the front of its
  * accumulation buffer and re-parses the remainder. `masked` is the mask bit off byte 1
- * (client→server frames MUST be masked, RFC 6455 §5.1); `rsv` is the three reserved
+ * (client→server frames must be masked, RFC 6455 §5.1); `rsv` is the three reserved
  * bits off byte 0 packed into a single 0–7 value (RFC 6455 §5.2) — non-zero means an
  * extension the wrapper does not negotiate, so the caller rejects it. Produced by
  * {@link parseWebSocketFrame}.
@@ -543,12 +707,12 @@ export declare interface WebSocketFrame {
 }
 
 /**
- * Represents a WebSocket ready state — the four browser-compatible lifecycle values.
+ * Represents a WebSocket ready state — the stage a connection has reached between the
+ * handshake and the socket's end.
  *
  * @remarks
- * `0` connecting, `1` open, `2` closing, `3` closed — the same numbering the DOM
- * `WebSocket.readyState` uses, so the wrapper reads like the platform API. The named
- * `WEBSOCKET_READY_*` constants spell each value.
+ * The same numbering the DOM `WebSocket.readyState` uses, so the wrapper reads like the
+ * platform API. The named `WEBSOCKET_READY_*` constants spell each value.
  */
 export declare type WebSocketReadyState = 0 | 1 | 2 | 3;