@orkestrel/websocket 0.0.11 → 0.0.13

package/README.md

@@ -1,9 +1,14 @@
 # @orkestrel/websocket
 
-A dependency-light RFC 6455 WebSocket for Node — native handshake and framing
-over duplex streams, with a typed emitter surface. Part of the `@orkestrel`
-line. Its sole runtime dependency is `@orkestrel/emitter`, used for the typed
-`emitter` every connection exposes.
+> The server-native bidirectional transport: a lean, typed wrapper over a raw upgraded
+> `node:stream` Duplex socket that speaks only the RFC 6455 wire protocol, owning the
+> handshake, the masked and unmasked frame codec, ping and pong, and the close handshake,
+> and surfacing every message on an owned `emitter`.
+
+Take the socket a `node:http` upgrade handler gives you, pass it to the
+`createNodeWebSocket` function, and read every message off the returned handle's
+`emitter`. Its sole runtime dependency is `@orkestrel/emitter`, which supplies that
+typed emitter. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -24,7 +29,7 @@ import { createServer } from 'node:http'
 import { createNodeWebSocket } from '@orkestrel/websocket'
 
 // A node:http server hands every upgrade request a raw socket; this wrapper takes it
-// from there. Passing the client's `sec-websocket-key` selects SERVER mode — the
+// from there. Passing the client's `sec-websocket-key` selects server mode — the
 // wrapper writes the 101 handshake, marks the connection open, and decodes frames.
 createServer().on('upgrade', (request, socket, head) => {
 	const key = request.headers['sec-websocket-key']

package/dist/src/server/index.cjs

@@ -1,70 +1,186 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/server/constants.ts
 /**
-* 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}.
 */
 var WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-/** 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.
+*/
 var WEBSOCKET_VERSION = "13";
-/** 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).
+*/
 var WEBSOCKET_OPCODE_TEXT = 1;
-/** 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).
+*/
 var WEBSOCKET_OPCODE_BINARY = 2;
-/** 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).
+*/
 var WEBSOCKET_OPCODE_CONTINUATION = 0;
-/** 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).
+*/
 var WEBSOCKET_OPCODE_CLOSE = 8;
-/** 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).
+*/
 var 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).
+*/
 var WEBSOCKET_OPCODE_PONG = 10;
-/** 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.
+*/
 var WEBSOCKET_READY_CONNECTING = 0;
-/** 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.
+*/
 var WEBSOCKET_READY_OPEN = 1;
-/** 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.
+*/
 var WEBSOCKET_READY_CLOSING = 2;
-/** 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.
+*/
 var WEBSOCKET_READY_CLOSED = 3;
-/** 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).
+*/
 var WEBSOCKET_CLOSE_NORMAL = 1e3;
-/** 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).
+*/
 var WEBSOCKET_CLOSE_PROTOCOL = 1002;
-/** 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.
+*/
 var WEBSOCKET_CLOSE_UNSUPPORTED = 1003;
-/** 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).
+*/
 var WEBSOCKET_CLOSE_INVALID = 1007;
-/** 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).
+*/
 var WEBSOCKET_CLOSE_TOO_BIG = 1009;
-/** 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}.
+*/
 var WEBSOCKET_MAX_PAYLOAD = 104857600;
-/** 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.
+*/
 var WEBSOCKET_CLOSE_TIMEOUT_MS = 3e4;
-/** 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.
+*/
 var WEBSOCKET_FAIL_TIMEOUT_MS = 1e3;
-/** 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.
+*/
 var WEBSOCKET_CONTROL_MAX_LENGTH = 125;
-/** 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.
+*/
 var WEBSOCKET_CLOSE_REASON_MAX_LENGTH = 123;
 //#endregion
 //#region src/server/errors.ts
 /**
-* 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
@@ -95,7 +211,8 @@ var WebSocketError = class extends Error {
 	}
 };
 /**
-* 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
@@ -112,7 +229,7 @@ var WebSocketError = class extends Error {
 * ```
 */
 function isWebSocketError(value) {
-	return value instanceof WebSocketError;
+	return (0, _orkestrel_contract.isInstance)(value, WebSocketError);
 }
 //#endregion
 //#region src/server/helpers.ts
@@ -131,15 +248,15 @@ function computeWebSocketAccept(key) {
 	return (0, node_crypto.createHash)("sha1").update(key + WEBSOCKET_GUID).digest("base64");
 }
 /**
-* 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
@@ -166,14 +283,14 @@ function measureWebSocketFrame(buffer) {
 	return length;
 }
 /**
-* 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
@@ -206,7 +323,7 @@ function matchesWebSocketCanonical(buffer) {
 * 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.
@@ -218,10 +335,10 @@ function matchesWebSocketCanonical(buffer) {
 * @throws A {@link WebSocketError} coded `FRAME` when `opcode` is outside the four-bit wire field, when `options.mask` is not 4 bytes, or when `options.mask` is supplied without `masked: true`
 */
 function encodeWebSocketFrame(opcode, payload, options) {
-	if (!Number.isInteger(opcode) || opcode < 0 || opcode > 15) throw new WebSocketError("FRAME", "opcode must be an integer between 0 and 15", { opcode });
+	if (!(0, _orkestrel_contract.isInteger)(opcode) || opcode < 0 || opcode > 15) throw new WebSocketError("FRAME", "opcode must be an integer between 0 and 15", { opcode });
 	if (options?.mask !== void 0 && options.mask.length !== 4) throw new WebSocketError("FRAME", "mask must contain exactly 4 bytes", { size: options.mask.length });
 	if (options?.mask !== void 0 && options.masked !== true) throw new WebSocketError("FRAME", "mask requires masked: true");
-	const body = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+	const body = (0, _orkestrel_contract.isString)(payload) ? Buffer.from(payload, "utf-8") : payload;
 	const length = body.length;
 	const masked = options?.masked === true;
 	const mask = masked ? options?.mask ?? (0, node_crypto.randomBytes)(4) : void 0;
@@ -285,7 +402,8 @@ function isWebSocketProtocol(protocol) {
 	return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(protocol);
 }
 /**
-* 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
@@ -306,7 +424,7 @@ function isWebSocketProtocol(protocol) {
 * ```
 */
 function isCloseCode(code) {
-	if (!Number.isInteger(code)) return false;
+	if (!(0, _orkestrel_contract.isInteger)(code)) return false;
 	if (code >= 1e3 && code <= 1003) return true;
 	if (code >= 1007 && code <= 1014) return true;
 	if (code >= 3e3 && code <= 4999) return true;
@@ -315,18 +433,19 @@ function isCloseCode(code) {
 //#endregion
 //#region src/server/parsers.ts
 /**
-* 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
@@ -378,12 +497,13 @@ function parseWebSocketFrame(buffer) {
 	};
 }
 /**
-* 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
@@ -404,18 +524,19 @@ function parseUTF8(bytes) {
 //#endregion
 //#region src/server/NodeWebSocket.ts
 /**
-* 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
@@ -462,8 +583,8 @@ var NodeWebSocket = class {
 	* 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
@@ -471,9 +592,9 @@ var NodeWebSocket = class {
 	*/
 	constructor(options) {
 		const payload = options.payload ?? 104857600;
-		if (!Number.isSafeInteger(payload) || payload < 0) throw new WebSocketError("OPTION", "payload must be a non-negative safe integer", { payload });
+		if (!(0, _orkestrel_contract.isNumber)(payload) || !Number.isSafeInteger(payload) || payload < 0) throw new WebSocketError("OPTION", "payload must be a non-negative safe integer", { payload });
 		const timeout = options.timeout ?? 3e4;
-		if (!Number.isSafeInteger(timeout) || timeout < 0) throw new WebSocketError("OPTION", "timeout must be a non-negative safe integer", { timeout });
+		if (!(0, _orkestrel_contract.isNumber)(timeout) || !Number.isSafeInteger(timeout) || timeout < 0) throw new WebSocketError("OPTION", "timeout must be a non-negative safe integer", { timeout });
 		if (options.key !== void 0 && !isWebSocketKey(options.key)) throw new WebSocketError("OPTION", "key must be the canonical base64 encoding of 16 bytes", { key: options.key });
 		if (options.protocol !== void 0 && !isWebSocketProtocol(options.protocol)) throw new WebSocketError("OPTION", "protocol must be a valid WebSocket subprotocol token", { protocol: options.protocol });
 		if (options.protocol !== void 0 && options.key === void 0) throw new WebSocketError("OPTION", "protocol requires a server key", { protocol: options.protocol });
@@ -743,33 +864,31 @@ var NodeWebSocket = class {
 	}
 	#bytes(chunk) {
 		if (Buffer.isBuffer(chunk)) return chunk;
-		if (typeof chunk === "string") return Buffer.from(chunk, "utf-8");
+		if ((0, _orkestrel_contract.isString)(chunk)) return Buffer.from(chunk, "utf-8");
 	}
 };
 //#endregion
 //#region src/server/factories.ts
 /**
-* 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') {
@@ -778,10 +897,12 @@ var NodeWebSocket = class {
 * 	}
 * 	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))
 * })
 * ```
 */