@mcpwarp/ws-mixer 0.6.0

package/dist/index.js

@@ -0,0 +1,2806 @@
+// src/client.ts
+import { EventEmitter as EventEmitter2 } from "events";
+import { WebSocket } from "ws";
+
+// src/errors.ts
+var ErrorCode = {
+  NO_ERROR: 0,
+  PROTOCOL_ERROR: 1,
+  INTERNAL_ERROR: 2,
+  FLOW_CONTROL_ERROR: 3,
+  FRAME_SIZE_ERROR: 4,
+  STREAM_CLOSED: 5,
+  REFUSED_STREAM: 6,
+  CANCEL: 7,
+  STREAM_LIMIT: 8,
+  ENHANCE_YOUR_CALM: 9,
+  UNSUPPORTED: 10,
+  UNAUTHORIZED: 11,
+  GOING_AWAY: 12,
+  KEEPALIVE_TIMEOUT: 13,
+  // Connection-level only, never emitted by ws-mixer itself: exists for the
+  // application above to close a connection for its own reason, carried in
+  // error.message / the WS close reason (WS close 4014).
+  APPLICATION_CLOSE: 14
+};
+var codeNames = {
+  [ErrorCode.NO_ERROR]: "NO_ERROR",
+  [ErrorCode.PROTOCOL_ERROR]: "PROTOCOL_ERROR",
+  [ErrorCode.INTERNAL_ERROR]: "INTERNAL_ERROR",
+  [ErrorCode.FLOW_CONTROL_ERROR]: "FLOW_CONTROL_ERROR",
+  [ErrorCode.FRAME_SIZE_ERROR]: "FRAME_SIZE_ERROR",
+  [ErrorCode.STREAM_CLOSED]: "STREAM_CLOSED",
+  [ErrorCode.REFUSED_STREAM]: "REFUSED_STREAM",
+  [ErrorCode.CANCEL]: "CANCEL",
+  [ErrorCode.STREAM_LIMIT]: "STREAM_LIMIT",
+  [ErrorCode.ENHANCE_YOUR_CALM]: "ENHANCE_YOUR_CALM",
+  [ErrorCode.UNSUPPORTED]: "UNSUPPORTED",
+  [ErrorCode.UNAUTHORIZED]: "UNAUTHORIZED",
+  [ErrorCode.GOING_AWAY]: "GOING_AWAY",
+  [ErrorCode.KEEPALIVE_TIMEOUT]: "KEEPALIVE_TIMEOUT",
+  [ErrorCode.APPLICATION_CLOSE]: "APPLICATION_CLOSE"
+};
+var namesToCode = Object.fromEntries(
+  Object.entries(codeNames).map(([code, name]) => [name, Number(code)])
+);
+function codeName(code) {
+  return codeNames[code] ?? "INTERNAL_ERROR";
+}
+function parseErrorCode(name) {
+  return namesToCode[name];
+}
+function closeCode(code) {
+  return code === ErrorCode.NO_ERROR ? 1e3 : 4e3 + code;
+}
+var WsMixerError = class extends Error {
+  code;
+  name = "WsMixerError";
+  fatal;
+  streamId;
+  /**
+   * The peer's observed WS close-frame code, set only when this error was
+   * built from an actually-observed close frame (e.g. MixerConn.onSocketClose)
+   * rather than a locally-raised protocol violation.
+   */
+  wsCode;
+  /** The peer's observed WS close-frame reason, verbatim, under the same condition as `wsCode`. */
+  closeReason;
+  constructor(code, message, opts) {
+    super(message);
+    this.code = code;
+    this.fatal = opts?.fatal ?? false;
+    this.streamId = opts?.streamId;
+    this.wsCode = opts?.wsCode;
+    this.closeReason = opts?.closeReason;
+  }
+  get codeName() {
+    return codeName(this.code);
+  }
+  toString() {
+    return `WsMixerError[${this.codeName}]: ${this.message}`;
+  }
+};
+var ConnError = class extends WsMixerError {
+  lastStreamId;
+  constructor(code, message, opts) {
+    super(code, message, opts);
+    this.name = "ConnError";
+    this.lastStreamId = opts?.lastStreamId;
+  }
+};
+var StreamError = class extends WsMixerError {
+  constructor(code, streamId, message) {
+    super(code, message, { streamId });
+    this.name = "StreamError";
+  }
+};
+var TokenUnavailableError = class extends Error {
+  name = "TokenUnavailableError";
+  constructor(message, options) {
+    super(message, options);
+  }
+};
+
+// src/conn.ts
+import { EventEmitter } from "events";
+
+// src/frame.ts
+var FrameType = {
+  OPEN: 0,
+  DATA: 1,
+  WINDOW: 2,
+  CLOSE: 3,
+  RESET: 4
+};
+var frameTypeNames = {
+  [FrameType.OPEN]: "OPEN",
+  [FrameType.DATA]: "DATA",
+  [FrameType.WINDOW]: "WINDOW",
+  [FrameType.CLOSE]: "CLOSE",
+  [FrameType.RESET]: "RESET"
+};
+function frameTypeName(t) {
+  const name = frameTypeNames[t];
+  if (name) return name;
+  return `UNKNOWN(0x${t.toString(16).padStart(2, "0")})`;
+}
+function frameTypeKnown(t) {
+  return t in frameTypeNames;
+}
+var FRAME_HEADER_SIZE = 8;
+var MAX_MESSAGE_SIZE = FRAME_HEADER_SIZE + 65536;
+var MAX_STREAM_ZERO_PAYLOAD = 16384;
+var MAX_CHUNK = 16384;
+var STREAM_ID_HIGH_BIT = 2147483648;
+var MAX_SEND_WINDOW = 2147483647;
+function decodeFrame(msg) {
+  if (msg.length < FRAME_HEADER_SIZE) {
+    throw new ConnError(
+      ErrorCode.PROTOCOL_ERROR,
+      `frame header too short: ${msg.length} bytes, need at least ${FRAME_HEADER_SIZE}`
+    );
+  }
+  if (msg.length > MAX_MESSAGE_SIZE) {
+    throw new ConnError(
+      ErrorCode.FRAME_SIZE_ERROR,
+      `message of ${msg.length} bytes exceeds the ${MAX_MESSAGE_SIZE} byte limit`
+    );
+  }
+  const view = new DataView(msg.buffer, msg.byteOffset, msg.byteLength);
+  const type = view.getUint8(0);
+  const flags = view.getUint8(1);
+  const streamId = view.getUint32(4);
+  const payload = msg.subarray(FRAME_HEADER_SIZE);
+  if ((streamId & STREAM_ID_HIGH_BIT) !== 0) {
+    throw new ConnError(ErrorCode.PROTOCOL_ERROR, `stream id 0x${streamId.toString(16)} has the reserved high bit set`);
+  }
+  const f = { type, flags, streamId, payload };
+  if (!frameTypeKnown(type)) {
+    return f;
+  }
+  if ((type === FrameType.OPEN || type === FrameType.CLOSE || type === FrameType.WINDOW || type === FrameType.RESET) && streamId === 0) {
+    throw new ConnError(ErrorCode.PROTOCOL_ERROR, `${frameTypeName(type)} is not legal on stream 0 (control channel)`);
+  }
+  switch (type) {
+    case FrameType.OPEN:
+      if (streamId % 2 === 0) {
+        throw new ConnError(
+          ErrorCode.PROTOCOL_ERROR,
+          `OPEN for even stream id ${streamId}: only the server opens streams and server ids are always odd`
+        );
+      }
+      break;
+    case FrameType.DATA:
+      if (streamId === 0 && payload.length > MAX_STREAM_ZERO_PAYLOAD) {
+        throw new ConnError(
+          ErrorCode.ENHANCE_YOUR_CALM,
+          `stream 0 payload of ${payload.length} bytes exceeds the ${MAX_STREAM_ZERO_PAYLOAD} byte control-channel limit`
+        );
+      }
+      break;
+    case FrameType.WINDOW: {
+      if (payload.length !== 4) {
+        throw new ConnError(ErrorCode.FRAME_SIZE_ERROR, `WINDOW payload is ${payload.length} bytes, must be exactly 4`);
+      }
+      const increment = new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint32(0);
+      if (increment === 0) {
+        throw new StreamError(ErrorCode.PROTOCOL_ERROR, streamId, "WINDOW increment of 0 is not legal (range is 1..2^31-1)");
+      }
+      if ((increment & STREAM_ID_HIGH_BIT) !== 0) {
+        throw new ConnError(ErrorCode.FLOW_CONTROL_ERROR, `WINDOW increment ${increment} would push the send window past 2^31-1`);
+      }
+      break;
+    }
+    case FrameType.RESET:
+      if (payload.length < 4) {
+        throw new ConnError(ErrorCode.FRAME_SIZE_ERROR, `RESET payload is ${payload.length} bytes, must be at least 4`);
+      }
+      break;
+  }
+  return f;
+}
+function windowIncrement(f) {
+  return new DataView(f.payload.buffer, f.payload.byteOffset, f.payload.byteLength).getUint32(0);
+}
+function resetCode(f) {
+  return new DataView(f.payload.buffer, f.payload.byteOffset, 4).getUint32(0);
+}
+var utf8Decoder = new TextDecoder("utf-8", { fatal: false });
+function resetMessage(f) {
+  return utf8Decoder.decode(f.payload.subarray(4));
+}
+function encodeFrame(f) {
+  const payload = f.payload ?? new Uint8Array(0);
+  const out = new Uint8Array(FRAME_HEADER_SIZE + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint8(0, f.type);
+  view.setUint8(1, 0);
+  view.setUint16(2, 0);
+  view.setUint32(4, f.streamId >>> 0);
+  out.set(payload, FRAME_HEADER_SIZE);
+  return out;
+}
+function encodeOpen(streamId) {
+  return encodeFrame({ type: FrameType.OPEN, streamId });
+}
+function encodeData(streamId, payload) {
+  return encodeFrame({ type: FrameType.DATA, streamId, payload });
+}
+function encodeWindow(streamId, increment) {
+  const payload = new Uint8Array(4);
+  new DataView(payload.buffer).setUint32(0, increment >>> 0);
+  return encodeFrame({ type: FrameType.WINDOW, streamId, payload });
+}
+function encodeClose(streamId) {
+  return encodeFrame({ type: FrameType.CLOSE, streamId });
+}
+var utf8Encoder = new TextEncoder();
+function encodeReset(streamId, code, message = "") {
+  const msgBytes = utf8Encoder.encode(message);
+  const payload = new Uint8Array(4 + msgBytes.length);
+  new DataView(payload.buffer).setUint32(0, code >>> 0);
+  payload.set(msgBytes, 4);
+  return encodeFrame({ type: FrameType.RESET, streamId, payload });
+}
+
+// src/control.ts
+var T_HELLO = "hello";
+var T_WELCOME = "welcome";
+var T_PING = "ping";
+var T_PONG = "pong";
+var T_DRAIN = "drain";
+var T_ERROR = "error";
+var T_APP = "app";
+var MAX_TOKEN_LEN = 4096;
+var MAX_AGENT_FIELD_LEN = 128;
+var WINDOW_MIN = 16384;
+var WINDOW_MAX = 2147483647;
+var MAX_STREAMS_MIN = 1;
+var MAX_STREAMS_MAX = 1e5;
+var MAX_SESSION_LEN = 64;
+var PING_INTERVAL_MIN = 5e3;
+var MAX_ERROR_MESSAGE = 1024;
+var MAX_DRAIN_MESSAGE = 256;
+var MAX_ID_VALUE = Number.MAX_SAFE_INTEGER;
+var MAX_STREAM_ID_VALUE = 2147483647;
+var CAPABILITY_RE = /^[a-z0-9_.-]{1,64}$/;
+var KNOWN_DRAIN_REASONS = /* @__PURE__ */ new Set(["rollout", "overload", "id_exhausted", "replaced", "maintenance", "client_requested"]);
+function knownDrainReason(reason) {
+  return KNOWN_DRAIN_REASONS.has(reason);
+}
+function connErr(message, code = ErrorCode.PROTOCOL_ERROR) {
+  return new ConnError(code, message);
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function jsonKind(v) {
+  if (v === null) return "null";
+  if (typeof v === "boolean") return "boolean";
+  if (typeof v === "number") return "number";
+  if (typeof v === "string") return "string";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "object") return "object";
+  return typeof v;
+}
+function requireField(top, name) {
+  if (!(name in top)) throw connErr(`missing required field "${name}"`);
+  return top[name];
+}
+function fieldString(raw, name) {
+  if (typeof raw !== "string") throw connErr(`field "${name}" must be a string`);
+  return raw;
+}
+function fieldInt(raw, name) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) throw connErr(`field "${name}" must be an integer`);
+  if (!Number.isInteger(raw)) throw connErr(`field "${name}" must be an integer, not a float`);
+  return raw;
+}
+function fieldObject(raw, name) {
+  if (!isPlainObject(raw)) throw connErr(`field "${name}" must be an object`);
+  return raw;
+}
+function fieldStringArray(raw, name) {
+  if (!Array.isArray(raw)) throw connErr(`field "${name}" must be an array of strings`);
+  return raw.map((item) => {
+    if (typeof item !== "string") throw connErr(`field "${name}" must be an array of strings`);
+    return item;
+  });
+}
+function requireString(top, name) {
+  return fieldString(requireField(top, name), name);
+}
+function requireInt(top, name) {
+  return fieldInt(requireField(top, name), name);
+}
+function validateCapabilities(caps) {
+  for (const c of caps) {
+    if (!CAPABILITY_RE.test(c)) throw connErr(`capability "${c}" does not match ^[a-z0-9_.-]{1,64}$`);
+  }
+}
+function parseAgentInfo(obj) {
+  const sdk = fieldString(requireField(obj, "sdk"), "agent.sdk");
+  const sdk_version = fieldString(requireField(obj, "sdk_version"), "agent.sdk_version");
+  if ([...sdk].length > MAX_AGENT_FIELD_LEN || [...sdk_version].length > MAX_AGENT_FIELD_LEN) {
+    throw connErr(`agent.sdk / agent.sdk_version must be <= ${MAX_AGENT_FIELD_LEN} characters`);
+  }
+  const a = { sdk, sdk_version };
+  if ("runtime" in obj) a.runtime = fieldString(obj.runtime, "agent.runtime");
+  if ("os" in obj) a.os = fieldString(obj.os, "agent.os");
+  return a;
+}
+function parseHello(top) {
+  const v = requireInt(top, "v");
+  if (v !== 1) throw connErr(`hello.v=${v} does not match ws-mixer.v1`, ErrorCode.UNSUPPORTED);
+  const token = requireString(top, "token");
+  if (token.length < 1 || token.length > MAX_TOKEN_LEN) {
+    throw connErr(`hello.token length ${token.length} out of range 1..${MAX_TOKEN_LEN}`);
+  }
+  const agent = parseAgentInfo(fieldObject(requireField(top, "agent"), "agent"));
+  let window = 262144;
+  if ("window" in top) {
+    window = fieldInt(top.window, "window");
+    if (window < WINDOW_MIN || window > WINDOW_MAX) {
+      throw connErr(`hello.window ${window} out of range ${WINDOW_MIN}..${WINDOW_MAX}`);
+    }
+  }
+  let max_streams = 64;
+  if ("max_streams" in top) {
+    max_streams = fieldInt(top.max_streams, "max_streams");
+    if (max_streams < MAX_STREAMS_MIN || max_streams > MAX_STREAMS_MAX) {
+      throw connErr(`hello.max_streams ${max_streams} out of range ${MAX_STREAMS_MIN}..${MAX_STREAMS_MAX}`);
+    }
+  }
+  const m = { t: "hello", v, token, agent, window, max_streams };
+  if ("capabilities" in top) {
+    const capabilities = fieldStringArray(top.capabilities, "capabilities");
+    validateCapabilities(capabilities);
+    m.capabilities = capabilities;
+  }
+  if ("meta" in top) m.meta = top.meta;
+  return m;
+}
+function parseWelcome(top) {
+  const v = requireInt(top, "v");
+  if (v !== 1) throw connErr(`welcome.v=${v} does not match ws-mixer.v1`, ErrorCode.UNSUPPORTED);
+  const session = requireString(top, "session");
+  if (session.length > MAX_SESSION_LEN) throw connErr(`welcome.session length ${session.length} exceeds ${MAX_SESSION_LEN}`);
+  const window = requireInt(top, "window");
+  if (window < WINDOW_MIN || window > WINDOW_MAX) throw connErr(`welcome.window ${window} out of range ${WINDOW_MIN}..${WINDOW_MAX}`);
+  const max_streams = requireInt(top, "max_streams");
+  if (max_streams < MAX_STREAMS_MIN || max_streams > MAX_STREAMS_MAX) {
+    throw connErr(`welcome.max_streams ${max_streams} out of range ${MAX_STREAMS_MIN}..${MAX_STREAMS_MAX}`);
+  }
+  const ping_interval = requireInt(top, "ping_interval");
+  if (ping_interval < PING_INTERVAL_MIN) throw connErr(`welcome.ping_interval ${ping_interval} is below the ${PING_INTERVAL_MIN}ms floor`);
+  const ping_timeout = requireInt(top, "ping_timeout");
+  if (ping_timeout < 2 * ping_interval) {
+    throw connErr(`welcome.ping_timeout (${ping_timeout}) must be at least 2x ping_interval (${ping_interval})`);
+  }
+  const m = { t: "welcome", v, session, window, max_streams, ping_interval, ping_timeout };
+  if ("server" in top) {
+    const obj = fieldObject(top.server, "server");
+    const si = {};
+    if ("name" in obj) si.name = fieldString(obj.name, "server.name");
+    if ("version" in obj) si.version = fieldString(obj.version, "server.version");
+    if ("node" in obj) si.node = fieldString(obj.node, "server.node");
+    m.server = si;
+  }
+  if ("capabilities" in top) {
+    const capabilities = fieldStringArray(top.capabilities, "capabilities");
+    validateCapabilities(capabilities);
+    m.capabilities = capabilities;
+  }
+  if ("meta" in top) m.meta = top.meta;
+  return m;
+}
+function parsePingPong(top, t) {
+  const id = requireInt(top, "id");
+  if (id < 0 || id > MAX_ID_VALUE) throw connErr(`${t}.id ${id} out of range 0..2^53-1`);
+  const m = { t, id };
+  if ("ts" in top) m.ts = fieldInt(top.ts, "ts");
+  return m;
+}
+function parseDrain(top) {
+  const reason = requireString(top, "reason");
+  const lastStreamId = requireInt(top, "last_stream_id");
+  if (lastStreamId < 0 || lastStreamId > MAX_STREAM_ID_VALUE) {
+    throw connErr(`drain.last_stream_id ${lastStreamId} out of range 0..2^31-1`);
+  }
+  const m = { t: "drain", reason, last_stream_id: lastStreamId };
+  if ("deadline_ms" in top) m.deadline_ms = fieldInt(top.deadline_ms, "deadline_ms");
+  if ("retry_after_ms" in top) m.retry_after_ms = fieldInt(top.retry_after_ms, "retry_after_ms");
+  if ("message" in top) {
+    m.message = fieldString(top.message, "message");
+    if (m.message.length > MAX_DRAIN_MESSAGE) throw connErr(`drain.message length ${m.message.length} exceeds ${MAX_DRAIN_MESSAGE}`);
+  }
+  return m;
+}
+function parseErrorMsg(top) {
+  const code = requireInt(top, "code");
+  if (code < 0 || code > 4294967295) throw connErr(`error.code ${code} out of range`);
+  const message = requireString(top, "message");
+  if (message.length > MAX_ERROR_MESSAGE) throw connErr(`error.message length ${message.length} exceeds ${MAX_ERROR_MESSAGE}`);
+  const m = { t: "error", code, message };
+  if ("stream_id" in top) {
+    const v = fieldInt(top.stream_id, "stream_id");
+    if (v < 0 || v > MAX_STREAM_ID_VALUE) throw connErr(`error.stream_id ${v} out of range 0..2^31-1`);
+    m.stream_id = v;
+  }
+  if ("last_stream_id" in top) {
+    const v = fieldInt(top.last_stream_id, "last_stream_id");
+    if (v < 0 || v > MAX_STREAM_ID_VALUE) throw connErr(`error.last_stream_id ${v} out of range 0..2^31-1`);
+    m.last_stream_id = v;
+  }
+  return m;
+}
+function parseApp(top) {
+  const body = requireField(top, "body");
+  if (!isPlainObject(body)) throw connErr(`app.body must be a JSON object, got ${jsonKind(body)}`);
+  return { t: "app", body };
+}
+function parseControl(raw) {
+  const bytes = typeof raw === "string" ? utf8Encoder2.encode(raw) : raw;
+  if (bytes.length > MAX_STREAM_ZERO_PAYLOAD) {
+    throw new ConnError(
+      ErrorCode.ENHANCE_YOUR_CALM,
+      `stream 0 payload of ${bytes.length} bytes exceeds the ${MAX_STREAM_ZERO_PAYLOAD} byte control-channel limit`
+    );
+  }
+  let text;
+  if (typeof raw === "string") {
+    text = raw;
+  } else {
+    try {
+      text = utf8Decoder2.decode(raw);
+    } catch (e) {
+      throw connErr(`malformed UTF-8 on stream 0: ${e.message}`);
+    }
+  }
+  let top;
+  try {
+    top = JSON.parse(text);
+  } catch (e) {
+    throw connErr(`malformed JSON on stream 0: ${e.message}`);
+  }
+  if (!isPlainObject(top)) {
+    throw connErr(`control message must be a JSON object, got ${jsonKind(top)}`);
+  }
+  if (!("t" in top)) throw connErr(`control message missing required field "t"`);
+  const t = fieldString(top.t, "t");
+  switch (t) {
+    case T_HELLO:
+      return parseHello(top);
+    case T_WELCOME:
+      return parseWelcome(top);
+    case T_PING:
+      return parsePingPong(top, "ping");
+    case T_PONG:
+      return parsePingPong(top, "pong");
+    case T_DRAIN:
+      return parseDrain(top);
+    case T_ERROR:
+      return parseErrorMsg(top);
+    case T_APP:
+      return parseApp(top);
+    default:
+      throw connErr(`unknown control message type "${t}"`);
+  }
+}
+var utf8Encoder2 = new TextEncoder();
+var utf8Decoder2 = new TextDecoder("utf-8", { fatal: true });
+function encodeControl(msg) {
+  return utf8Encoder2.encode(JSON.stringify(msg));
+}
+
+// src/stream.ts
+import { Duplex } from "stream";
+
+// src/util.ts
+function truncateUtf8(message, maxBytes) {
+  const bytes = new TextEncoder().encode(message);
+  if (bytes.length <= maxBytes) return message;
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 192) === 128) end--;
+  return new TextDecoder().decode(bytes.subarray(0, end));
+}
+
+// src/stream.ts
+var NOOP_ERROR_LISTENER = () => {
+};
+var MixerStream = class extends Duplex {
+  id;
+  host;
+  state = "open";
+  sendWindow;
+  recvWindow;
+  initialWindow;
+  unacked = 0;
+  remoteClosed = false;
+  terminalError = null;
+  /** Resolved when sendWindow becomes > 0 or the stream can no longer send. */
+  sendWaiters = [];
+  /** Bytes queued via _write, waiting on credit; drives backpressure. */
+  writeQueue = [];
+  draining = false;
+  /** Write callbacks (_write's own terminal-error branch, or drainWriteQueue's catch) whose error must wait until the read side has finished delivering buffered data and emitted 'end' -- see terminateNoThrow's doc comment. Non-null exactly while that wait is pending; flushed (and reset to null) from _destroy(), or from the 'end' listener drainWriteQueue's catch installs. */
+  heldWriteCallbacks = null;
+  /** Set once this stream is RESET -- by the peer (handleReset), the SDK (abort()), or the app itself (reset()); undefined until then. Set even when no `'error'` listener is attached. */
+  resetCode;
+  constructor(id, host, initialRecvWindow, initialSendWindow) {
+    super({ autoDestroy: false, emitClose: true, readableHighWaterMark: initialRecvWindow });
+    this.id = id;
+    this.host = host;
+    this.initialWindow = initialRecvWindow;
+    this.recvWindow = initialRecvWindow;
+    this.sendWindow = initialSendWindow;
+  }
+  getState() {
+    return this.state;
+  }
+  getSendWindow() {
+    return this.sendWindow;
+  }
+  getRecvWindow() {
+    return this.recvWindow;
+  }
+  // --- Duplex plumbing ------------------------------------------------------
+  _read(_size) {
+  }
+  _write(chunk, _encoding, callback) {
+    if (this.terminalError) {
+      if (this.heldWriteCallbacks) {
+        this.heldWriteCallbacks.push(callback);
+      } else {
+        callback(this.terminalError);
+      }
+      return;
+    }
+    if (this.state !== "open" && this.state !== "half_closed_remote") {
+      callback(new StreamError(ErrorCode.STREAM_CLOSED, this.id, "write on a stream that is not open for sending"));
+      return;
+    }
+    this.writeQueue.push({ chunk, callback });
+    this.pumpWriteQueue();
+  }
+  _final(callback) {
+    this.closeWrite();
+    callback();
+  }
+  _destroy(err, callback) {
+    if (this.state !== "closed") {
+      this.reset(ErrorCode.CANCEL, err ? String(err.message) : "local destroy");
+    }
+    if (this.heldWriteCallbacks) {
+      const held = this.heldWriteCallbacks;
+      this.heldWriteCallbacks = null;
+      for (const cb of held) cb(this.terminalError ?? err ?? void 0);
+    }
+    callback(err);
+  }
+  // --- outbound: send credit + chunking -------------------------------------
+  pumpWriteQueue() {
+    if (this.draining) return;
+    this.draining = true;
+    void this.drainWriteQueue().finally(() => {
+      this.draining = false;
+      if (this.writeQueue.length > 0) this.pumpWriteQueue();
+    });
+  }
+  async drainWriteQueue() {
+    while (this.writeQueue.length > 0) {
+      const item = this.writeQueue[0];
+      let { chunk } = item;
+      const { callback } = item;
+      try {
+        while (chunk.length > 0) {
+          const n = await this.reserveSendCredit(chunk.length);
+          const piece = chunk.subarray(0, n);
+          chunk = chunk.subarray(n);
+          await this.host.sendData(this.id, piece);
+        }
+        this.writeQueue.shift();
+        callback();
+      } catch (e) {
+        this.writeQueue.shift();
+        if (this.heldWriteCallbacks) {
+          this.heldWriteCallbacks.push(callback);
+          continue;
+        }
+        if (this.state === "half_closed_remote") {
+          const failure = e;
+          if (!this.hasErrorListener()) {
+            this.on("error", NOOP_ERROR_LISTENER);
+          }
+          if (this.readableEnded) {
+            callback(failure);
+            continue;
+          }
+          this.heldWriteCallbacks = [(err) => callback(err ?? failure)];
+          this.once(
+            "end",
+            () => process.nextTick(() => {
+              if (this.destroyed || !this.heldWriteCallbacks) return;
+              if (this.state === "closed") {
+                this.destroy();
+                return;
+              }
+              const held = this.heldWriteCallbacks;
+              this.heldWriteCallbacks = null;
+              for (const cb of held) cb(this.terminalError ?? void 0);
+            })
+          );
+          continue;
+        }
+        if (!this.hasErrorListener()) {
+          this.on("error", NOOP_ERROR_LISTENER);
+        }
+        callback(e);
+      }
+    }
+  }
+  /** Waits until send credit is available, then reserves and returns min(want, sendWindow, MAX_CHUNK). */
+  reserveSendCredit(want) {
+    return new Promise((resolve, reject) => {
+      const attempt = () => {
+        if (this.terminalError) {
+          reject(this.terminalError);
+          return true;
+        }
+        if (this.state !== "open" && this.state !== "half_closed_remote") {
+          reject(new StreamError(ErrorCode.STREAM_CLOSED, this.id, "write on a stream that is not open for sending"));
+          return true;
+        }
+        if (this.sendWindow > 0) {
+          const n = Math.min(want, this.sendWindow, MAX_CHUNK);
+          this.sendWindow -= n;
+          resolve(n);
+          return true;
+        }
+        return false;
+      };
+      if (attempt()) return;
+      this.sendWaiters.push(() => {
+        if (attempt()) return;
+      });
+    });
+  }
+  wakeSendWaiters() {
+    const waiters = this.sendWaiters;
+    this.sendWaiters = [];
+    for (const w of waiters) w();
+  }
+  // --- inbound: DATA / credit-on-consume -------------------------------------
+  /**
+   * Applies a received DATA frame. Throws a ConnError (FLOW_CONTROL_ERROR) if it exceeds recv credit.
+   * @internal
+   */
+  handleData(payload) {
+    if (this.state === "half_closed_remote") {
+      throw new StreamError(ErrorCode.STREAM_CLOSED, this.id, "DATA received after this stream's CLOSE");
+    }
+    if (this.state === "closed") {
+      throw new StreamError(ErrorCode.STREAM_CLOSED, this.id, "DATA received on a closed stream");
+    }
+    const n = payload.length;
+    if (n > this.recvWindow) {
+      throw new ConnError(
+        ErrorCode.FLOW_CONTROL_ERROR,
+        `stream ${this.id}: received ${n} DATA bytes with ${this.recvWindow} credit remaining`
+      );
+    }
+    this.recvWindow -= n;
+    const before = this.readableLength;
+    this.push(Buffer.from(payload));
+    const buffered = this.readableLength - before;
+    const bypassed = n - buffered;
+    if (bypassed > 0) this.creditConsumed(bypassed);
+  }
+  /**
+   * Credits the peer back once bytes leave the internal buffer, mirroring Go
+   * `Stream.creditConsumed` (stream.go) and its half-window threshold.
+   */
+  creditConsumed(n) {
+    this.unacked += n;
+    this.maybeDeliverEOF();
+    const threshold = this.initialWindow / 2;
+    if (this.unacked >= threshold && this.state !== "closed") {
+      const increment = this.unacked;
+      this.recvWindow += increment;
+      this.unacked = 0;
+      this.host.sendControlFrame(encodeWindow(this.id, increment));
+    }
+  }
+  eofDelivered = false;
+  internalBufferEmpty() {
+    return this.readableLength === 0;
+  }
+  /**
+   * Covers every consumption mode that goes through the buffer: explicit
+   * paused-mode `.read()` calls, and Node's internal flow loop -- which
+   * calls this same public `read()` method to back `on('data')`, `pipe()`
+   * and `for await` once bytes are actually sitting in the buffer (as
+   * opposed to handleData()'s synchronous fast-path bypass above, which
+   * never reaches the buffer at all). Between the two, every byte is
+   * credited exactly once: whatever left the buffer here, plus whatever
+   * never entered it there.
+   */
+  read(size) {
+    const before = this.readableLength;
+    const result = super.read(size);
+    const consumed = before - this.readableLength;
+    if (consumed > 0) this.creditConsumed(consumed);
+    return result;
+  }
+  // --- inbound: WINDOW / CLOSE / RESET ---------------------------------------
+  /**
+   * Applies a received WINDOW frame's credit increment. Throws ConnError on overflow past 2^31-1.
+   * @internal
+   */
+  handleWindow(increment) {
+    const newWindow = this.sendWindow + increment;
+    if (newWindow > MAX_SEND_WINDOW) {
+      throw new ConnError(ErrorCode.FLOW_CONTROL_ERROR, `stream ${this.id}: WINDOW would push the send window to ${newWindow}, past 2^31-1`);
+    }
+    if (this.state === "closed") return;
+    this.sendWindow = newWindow;
+    this.wakeSendWaiters();
+  }
+  /**
+   * Applies a received CLOSE frame: half-close-remote (peer will send no more DATA).
+   * @internal
+   */
+  handleClose() {
+    switch (this.state) {
+      case "open":
+        this.state = "half_closed_remote";
+        break;
+      case "half_closed_local":
+        this.state = "closed";
+        this.host.retireStream(this.id);
+        break;
+      case "half_closed_remote":
+        throw new StreamError(ErrorCode.STREAM_CLOSED, this.id, "duplicate CLOSE received");
+      case "closed":
+        return;
+    }
+    this.remoteClosed = true;
+    this.maybeDeliverEOF();
+  }
+  // CLOSE preserves buffered data; EOF (push(null)) only follows once every
+  // buffered byte has been delivered to the application (WIRE.md section
+  // 2.5: "deliver those bytes and *then* EOF"). Called both right after
+  // handleClose() (buffer may already be empty) and from creditConsumed() as
+  // the application keeps draining the buffer.
+  maybeDeliverEOF() {
+    if (!this.eofDelivered && this.remoteClosed && this.internalBufferEmpty()) {
+      this.eofDelivered = true;
+      this.push(null);
+    }
+  }
+  /** True once something is listening for `'error'`: gates attaching the internal no-op `'error'` listener (terminateNoThrow, drainWriteQueue). */
+  hasErrorListener() {
+    return this.listenerCount("error") > 0;
+  }
+  /**
+   * Applies a received RESET frame: any state, discard buffered data, go to
+   * closed (WIRE.md: RESET discards buffered data, unlike CLOSE). Node
+   * throws synchronously out of destroy()/a write callback when an 'error'
+   * is emitted with no listener -- terminateNoThrow's internal no-op
+   * listener is what keeps a peer RESET (including CANCEL, the ordinary path
+   * for a client-initiated `close()`) from crashing a consumer that never
+   * attached its own `'error'`, while still surfacing the code via
+   * `resetCode`/`'reset'`/`stream.errored` instead of a false clean end.
+   * @internal
+   */
+  handleReset(code, message) {
+    this.state = "closed";
+    const err = new StreamError(code, this.id, message);
+    this.terminalError = err;
+    this.resetCode = code;
+    this.wakeSendWaiters();
+    this.emit("reset", { code, message });
+    this.terminateNoThrow(err, { discardBuffered: true });
+    this.host.retireStream(this.id);
+  }
+  /**
+   * Tears this stream down with `err`. Used by handleReset()/applyReset() (a
+   * stream-level RESET, peer-sent or app-initiated -- both pass
+   * `{discardBuffered: true}`, per WIRE.md: "RESET discards buffered data")
+   * and by MixerConn.rejectOutstanding() (a connection-level failure aborts
+   * every stream still live when it hit -- no `discardBuffered`).
+   *
+   * Two different endings, per CLIENT-SDK.md's "Stream teardown on
+   * disconnect" row:
+   *
+   * Node's own 'error' event throws synchronously and crashes the process
+   * when nothing is listening for it -- an internal no-op 'error' listener is
+   * attached first, unconditionally, whenever nothing else is listening
+   * (harmless -- the stream is terminating either way): needed by the
+   * destroy(err) branch below directly, and by the push(null) branch too,
+   * since even there the WRITE side is still live from Node's own Writable
+   * machinery's point of view, and a later write's `_write` callback error
+   * (`terminalError`, set above) still makes Node itself try to emit
+   * 'error'.
+   *
+   * - `opts?.discardBuffered`, OR the peer's own CLOSE never arrived on this
+   *   stream (`!this.remoteClosed`): destroy(err) -- this stream's read side
+   *   never legitimately finished, so it ends with an error, never a clean
+   *   end-of-stream. 'end' is never emitted from this branch, so a consumer
+   *   with only 'data'/'end'/'close' listeners sees 'close' (and
+   *   `stream.errored`) but never a false clean end; pipe()/pipeline()/
+   *   for-await consumers see `err` exactly as they would with a real
+   *   'error' listener attached.
+   * - Otherwise (no `discardBuffered`, the peer's CLOSE already arrived --
+   *   `this.remoteClosed`): this stream's READ side genuinely ended cleanly
+   *   on the wire before the connection died, and CLIENT-SDK.md requires the
+   *   bytes it preserved to be delivered first, followed by 'end', followed
+   *   by 'close' -- never an 'error'. `push(null)` does NOT discard whatever
+   *   Node's Duplex still has buffered -- it marks EOF, and Node delivers the
+   *   buffered bytes to the consumer and only then emits 'end' (unlike
+   *   `destroy(err)`, which WOULD discard them). No 'error' event fires: the
+   *   response DID complete -- but `stream.errored` does NOT stay `null`
+   *   forever: once `heldWriteCallbacks` is flushed (see below), a write
+   *   callback is called with `err`, and Node's own Writable machinery marks
+   *   `stream.errored` from that alone, same as any other write error. Once
+   *   'end' has actually been delivered (immediately, if the buffer was
+   *   already empty; otherwise once the consumer has drained it), this
+   *   stream is `destroy()`'d with no error -- required for 'close' to ever
+   *   fire on an `autoDestroy: false` Duplex, which this stream is
+   *   (`emitClose: true` alone only arms the event, it doesn't schedule it).
+   *   `eofDelivered` guards against calling `push(null)` a second time if
+   *   `maybeDeliverEOF()` already did (buffer was already empty when CLOSE
+   *   arrived); in that case the buffer is still (and can only still be)
+   *   empty here too -- nothing can add to it once `remoteClosed` is set --
+   *   so this destroys right away rather than waiting on an 'end' that may
+   *   already have fired, or may never (a consumer that never reads never
+   *   sees Node's own 'end', the same way it never would on any other
+   *   Readable).
+   *
+   *   A write outstanding at this exact moment (`writeQueue` non-empty, one
+   *   item mid-`drainWriteQueue`, or one issued via `_write` after this call)
+   *   still needs its callback settled with `err` -- the caller is waiting on
+   *   it -- but calling it with an error *before* 'end' has fired would make
+   *   Node's own Writable/Duplex machinery mark the READABLE side `errored`
+   *   too, permanently blocking 'end' regardless of whether an 'error'
+   *   listener is attached. So instead of calling those callbacks here,
+   *   `heldWriteCallbacks` (non-null for exactly this stretch) collects them
+   *   -- pushed onto by `drainWriteQueue`'s catch and by `_write`'s
+   *   terminal-error branch -- and `_destroy()` flushes them with `err`
+   *   right after `destroy()` actually runs (whether that's the 'end'-
+   *   triggered `destroy()` below, or the read side never gets there because
+   *   something else destroys the stream first): by then the readable side
+   *   is already finished or was never going to finish anyway, so marking it
+   *   `errored` is no longer a concern.
+   *
+   *   Accepted tradeoff: a held write callback is settled only once the read
+   *   side has actually been drained ('end') or the stream is destroyed some
+   *   other way (app destroy(), reset()). An app that awaits a write's
+   *   callback without ever reading this stream will wait until it does one
+   *   or the other.
+   *
+   * `this.state = "closed"` up front (not just `terminalError`) matters for
+   * more than bookkeeping: `_destroy()`'s own guard (`if (this.state !==
+   * "closed") this.reset(...)`) would otherwise re-enter here through
+   * reset()/applyReset()/terminateNoThrow() a second time, overwriting the
+   * real `err` with a generic CANCEL, in the destroy(err) branch above.
+   *
+   * Setting `terminalError` and waking every sendWaiter (not just calling
+   * destroy()) is what makes a write already blocked on send credit
+   * (drainWriteQueue's reserveSendCredit) -- and everything still queued
+   * behind it -- fail promptly with `err` too, in EITHER branch: each
+   * rejection drains the next queued item in turn via drainWriteQueue's own
+   * loop, so no separate queue-flushing step is needed here.
+   *
+   * A stream already fully, cleanly closed (both directions CLOSE'd) has
+   * already called `retireStream()` and is no longer tracked by MixerConn,
+   * so `rejectOutstanding` never reaches it here at all -- only a stream
+   * still genuinely open, or half-closed one way, ever is.
+   *
+   * `resetCode` is set here too, but only when `err` is a `StreamError`
+   * (mirrors handleReset()/applyReset(), which construct one for exactly
+   * this): the drain-hand-over `streamErrorFactory` override (client.ts)
+   * hands a stream-scoped `StreamError(CANCEL, "connection drained")` for a
+   * CONNECTION teardown (no `discardBuffered`) -- deliberately NOT what
+   * gates the buffered-data decision above (that's `opts.discardBuffered`
+   * alone), since a `StreamError` here doesn't mean "discard": it would
+   * otherwise wrongly discard a response that had already completed on
+   * every drain hand-over. From the stream's own perspective a `StreamError`
+   * IS a fourth way it ends in RESET, on top of the three the class doc
+   * above lists, distinct from an ordinary `WsMixerError`/`ConnError`
+   * connection failure, which is not RESET-shaped and leaves `resetCode`
+   * unset.
+   * @internal
+   */
+  terminateNoThrow(err, opts) {
+    this.state = "closed";
+    this.terminalError = err;
+    if (err instanceof StreamError) this.resetCode = err.code;
+    const deferWriteErrors = !opts?.discardBuffered && this.remoteClosed;
+    if (deferWriteErrors) this.heldWriteCallbacks = this.heldWriteCallbacks ?? [];
+    this.wakeSendWaiters();
+    if (!this.hasErrorListener()) {
+      this.on("error", NOOP_ERROR_LISTENER);
+    }
+    if (deferWriteErrors) {
+      const hadBufferedData = !this.internalBufferEmpty();
+      if (!this.eofDelivered) {
+        this.eofDelivered = true;
+        this.push(null);
+      }
+      if (hadBufferedData) {
+        this.once("end", () => this.destroy());
+      } else {
+        this.destroy();
+      }
+      return;
+    }
+    this.destroy(err);
+  }
+  /**
+   * Reports whether this stream must no longer send DATA (CLOSE sent, or RESET).
+   * @internal
+   */
+  sendDone() {
+    if (this.state === "half_closed_local" || this.state === "closed") {
+      if (this.terminalError) return { done: true, error: this.terminalError };
+      return { done: true, error: new StreamError(ErrorCode.STREAM_CLOSED, this.id, "DATA not sent: CLOSE already sent on this stream") };
+    }
+    return { done: false };
+  }
+  // --- public half-close / reset API -----------------------------------------
+  /** Sends CLOSE: "I will send no more DATA on this stream." end() is sugar for this via _final. */
+  closeWrite() {
+    switch (this.state) {
+      case "open":
+        this.state = "half_closed_local";
+        break;
+      case "half_closed_remote":
+        this.state = "closed";
+        break;
+      case "half_closed_local":
+      case "closed":
+        return;
+    }
+    const closedNow = this.state === "closed";
+    this.host.sendControlFrame(encodeClose(this.id));
+    if (closedNow) this.host.retireStream(this.id);
+  }
+  /**
+   * Sends CLOSE (if not already sent) and stops delivering further reads. If
+   * the peer has not yet half-closed its own send side, a plain closeWrite()
+   * would leave it writing into a window nobody drains, so close() also
+   * RESETs with CANCEL in that case (mirrors go/wsmixer/stream.go Close()).
+   */
+  close() {
+    if (!this.remoteClosed) {
+      this.closeWrite();
+      this.reset(ErrorCode.CANCEL, "local close: peer had not finished sending");
+      return;
+    }
+    this.closeWrite();
+    this.destroy();
+  }
+  /**
+   * Aborts the stream in both directions with the given error code and
+   * message, discarding buffered data. `code` may be a numeric ws-mixer.v1
+   * error code or its wire name (e.g. `"CANCEL"`); `message` is truncated to
+   * 256 UTF-8 bytes on a character boundary (WIRE.md section 2.3: a RESET
+   * message SHOULD be <= 256 B).
+   *
+   * Same "don't throw with nobody listening" rule as handleReset(): an
+   * internal no-op 'error' listener (attached by terminateNoThrow() when
+   * nothing else is) keeps this from crashing a consumer with no 'error' of
+   * its own, while still surfacing the code via `resetCode`/`stream.errored`
+   * (buffered data discarded, per RESET's own semantics: terminateNoThrow()
+   * is called with `{discardBuffered: true}`).
+   *
+   * This is the app-facing API: calling code already knows why it's
+   * resetting its own stream, so unlike a peer-sent RESET (handleReset()) or
+   * an SDK-detected violation (abort()), `reset()` does NOT emit `'reset'`.
+   */
+  reset(code, message = "") {
+    this.applyReset(code, message);
+  }
+  /**
+   * Internal counterpart to reset(): used when the *connection* -- not
+   * application code -- is what decided to tear this stream down (an
+   * SDK-detected protocol violation surfaced as a `StreamError` from
+   * MixerConn's dispatch loop). Identical effect to reset(), but also emits
+   * `'reset'` the same way handleReset() does for a peer-sent RESET: in both
+   * cases the stream's owner didn't choose this, so it needs to hear about
+   * it. No-ops (and does not emit) if the stream is already closed.
+   * @internal
+   */
+  abort(code, message = "") {
+    if (this.applyReset(code, message)) {
+      this.emit("reset", { code: this.resetCode, message: this.terminalError.message });
+    }
+  }
+  /** Shared implementation behind reset()/abort(); returns false (no-op) if the stream was already closed. */
+  applyReset(code, message) {
+    if (this.state === "closed") {
+      if (this.heldWriteCallbacks && !this.destroyed) this.destroy();
+      return false;
+    }
+    const numericCode = typeof code === "string" ? parseErrorCode(code) : code;
+    if (numericCode === void 0) {
+      throw new Error(`unknown ws-mixer error code name: ${code}`);
+    }
+    const truncated = truncateUtf8(message, 256);
+    this.state = "closed";
+    this.terminalError = new StreamError(numericCode, this.id, truncated);
+    this.resetCode = numericCode;
+    this.wakeSendWaiters();
+    this.host.sendControlFrame(encodeReset(this.id, numericCode, truncated));
+    this.host.retireStream(this.id);
+    this.terminateNoThrow(this.terminalError, { discardBuffered: true });
+    return true;
+  }
+  /**
+   * Wraps this stream as Web Streams API `{ readable, writable }`, e.g. for
+   * `fetch`'s `duplex` option or any other Web Streams consumer.
+   */
+  toWeb() {
+    return Duplex.toWeb(this);
+  }
+};
+
+// src/conn.ts
+var DEFAULT_WINDOW = 262144;
+var DEFAULT_MAX_STREAMS = 64;
+var DEFAULT_HELLO_TIMEOUT_MS = 1e4;
+var DEFAULT_PING_INTERVAL_FLOOR_MS = 5e3;
+var STREAM0_RATE_PER_SEC = 50;
+var STREAM0_BURST = 100;
+var DELIVERY_QUEUE_MIN = 128;
+var DELIVERY_QUEUE_MARGIN = 64;
+function wireCloseCode(wsCode) {
+  return wsCode === 1e3 || wsCode >= 4e3 && wsCode <= 4999 ? wsCode : 4e3 + ErrorCode.INTERNAL_ERROR;
+}
+var TokenBucket = class {
+  constructor(capacity, ratePerSecond) {
+    this.capacity = capacity;
+    this.ratePerSecond = ratePerSecond;
+    this.tokens = capacity;
+  }
+  capacity;
+  ratePerSecond;
+  tokens;
+  last = Date.now();
+  /** Reports whether one token is available and, if so, consumes it. */
+  allow() {
+    const now = Date.now();
+    this.tokens = Math.min(this.capacity, this.tokens + (now - this.last) / 1e3 * this.ratePerSecond);
+    this.last = now;
+    if (this.tokens < 1) return false;
+    this.tokens -= 1;
+    return true;
+  }
+};
+var MixerConn = class extends EventEmitter {
+  ws;
+  opts;
+  closed = false;
+  handshakeDone = false;
+  session = "";
+  peerWindow = DEFAULT_WINDOW;
+  ourWindow;
+  maxStreams = DEFAULT_MAX_STREAMS;
+  pingIntervalMs = 3e4;
+  pingTimeoutMs = 9e4;
+  welcomeMeta;
+  draining = false;
+  /** The `last_stream_id` from the most recently received `drain`; set only once draining. */
+  lastStreamId;
+  streams = /* @__PURE__ */ new Map();
+  highestOpened = 0;
+  /**
+   * Minimal "ignore and count" counters (item 11 of the review: full
+   * escalation/STREAM_LIMIT bucketing is intentionally out of scope for v1 --
+   * see README.md and docs/DESIGN.md). Exposed via `stats()`.
+   */
+  counters = {
+    unknownFrameTypes: 0,
+    staleFrames: 0,
+    duplicatePongs: 0,
+    refusedOpens: 0,
+    /**
+     * OPENs received above the drain's `last_stream_id` (WIRE.md section
+     * 2.9 / the 2026-08-27 decision log): connection-fatal `PROTOCOL_ERROR`,
+     * not a stream-scoped refusal -- the server already promised not to send
+     * one, so this is it breaking that promise, not a benign race.
+     */
+    drainViolations: 0,
+    /** `drain.reason` values outside the closed enum, normalized to "maintenance" (WIRE.md section 2.7). */
+    unknownDrainReasons: 0,
+    /** A `'stream'`/`'app'`/`'drain'` listener that threw or rejected; delivery continued with the next event regardless. */
+    handlerErrors: 0,
+    /** ConnError-triggered connection failures: malformed/out-of-sequence control traffic (CLIENT-SDK.md's "Stats / counters" row). */
+    protocolViolations: 0,
+    /**
+     * Raw WS message bytes received/sent, cumulative (CLIENT-SDK.md's
+     * "Stats / counters" row): the full ws-mixer frame on the wire, header included, for every
+     * message -- not just DATA payload bytes. This differs from Go's
+     * `BytesTransferred` metric, which counts payload only; do not compare
+     * the two directly.
+     */
+    bytesIn: 0,
+    bytesOut: 0
+  };
+  /** Snapshot of the counters above. */
+  stats() {
+    return { ...this.counters };
+  }
+  /**
+   * The `StreamHost` a `MixerStream` actually talks to: a plain object of
+   * bound closures, not `this` -- so `sendData`/`sendControlFrame`/
+   * `retireStream` stay private implementation details of MixerConn instead
+   * of leaking onto its public (and `.d.ts`) surface (item 8).
+   */
+  #streamHost = {
+    sendData: (streamId, chunk) => this.sendData(streamId, chunk),
+    sendControlFrame: (frame) => this.sendControlFrame(frame),
+    retireStream: (streamId) => this.retireStream(streamId)
+  };
+  // --- write scheduler state ---
+  controlQueue = [];
+  rotation = [];
+  inRotation = /* @__PURE__ */ new Set();
+  outbox = /* @__PURE__ */ new Map();
+  wakeWaiters = [];
+  writerRunning = false;
+  /** Resolved once the stream table is empty; used by close() instead of polling. */
+  idleWaiters = [];
+  // --- ordered async delivery (item 2): stream/app/drain handlers fire in wire
+  // order, off one queue, so a slow handler cannot stall frame parsing. ---
+  deliveryQueue = [];
+  deliveryRunning = false;
+  // --- stream-0 flood limit (item 4), mirrors go/wsmixer's Conn.stream0Bucket ---
+  stream0Bucket = new TokenBucket(STREAM0_BURST, STREAM0_RATE_PER_SEC);
+  // --- keepalive state ---
+  nextPingId = 0;
+  /** Watermark: every id below this has been acked (or pruned as stale) at least once. Mirrors go/wsmixer's Conn.lowestUnacked. */
+  lowestUnacked = 0;
+  lastPongAt = 0;
+  outstandingPings = /* @__PURE__ */ new Map();
+  pingTimer = null;
+  watchdogTimer = null;
+  handshakeTimer = null;
+  jitterTimer = null;
+  /**
+   * The most recent pre-welcome `'error'` event's message, recorded so
+   * `onSocketClose`'s report -- the sole reporter, see its own doc comment
+   * -- can use it as `message` when `ws`'s own close carries no reason of
+   * its own.
+   */
+  pendingHandshakeErrorMessage;
+  constructor(ws, opts) {
+    super();
+    this.ws = ws;
+    this.opts = opts;
+    this.ourWindow = opts.window ?? DEFAULT_WINDOW;
+    this.maxStreams = opts.maxStreams ?? DEFAULT_MAX_STREAMS;
+    ws.on("message", (data) => this.onMessage(data));
+    ws.on("close", (code, reason) => this.onSocketClose(code, reason));
+    ws.on("error", (err) => this.onSocketError(err));
+  }
+  // --- handshake --------------------------------------------------------------
+  /** Sends `hello` and resolves once `welcome` is validated, or rejects (a WsMixerError, `fatal` set for UNSUPPORTED). */
+  handshake() {
+    return new Promise((resolve, reject) => {
+      const hello = {
+        t: "hello",
+        v: 1,
+        token: this.opts.token,
+        agent: this.opts.agent,
+        window: this.ourWindow,
+        max_streams: this.maxStreams,
+        ...this.opts.capabilities ? { capabilities: this.opts.capabilities } : {},
+        ...this.opts.meta !== void 0 ? { meta: this.opts.meta } : {}
+      };
+      const timeoutMs = this.opts.helloTimeoutMs ?? this.opts._timing?.helloTimeout ?? DEFAULT_HELLO_TIMEOUT_MS;
+      this.handshakeTimer = setTimeout(() => {
+        this.handshakeTimer = null;
+        const err = new ConnError(ErrorCode.PROTOCOL_ERROR, `no welcome within ${timeoutMs}ms of hello`);
+        this.fail(err);
+        reject(err);
+      }, timeoutMs);
+      this.once("__welcome_internal", (welcome) => {
+        if (this.handshakeTimer) {
+          clearTimeout(this.handshakeTimer);
+          this.handshakeTimer = null;
+        }
+        resolve(welcome);
+      });
+      this.once("__handshake_failed_internal", (err) => {
+        if (this.handshakeTimer) {
+          clearTimeout(this.handshakeTimer);
+          this.handshakeTimer = null;
+        }
+        reject(err);
+      });
+      void this.enqueueControl(encodeData(0, encodeControl(hello))).catch(() => {
+      });
+      this.startWriter();
+    });
+  }
+  applyWelcome(welcome) {
+    const minInterval = this.opts._timing?.minPingInterval ?? DEFAULT_PING_INTERVAL_FLOOR_MS;
+    if (welcome.ping_interval < minInterval) {
+      throw new ConnError(ErrorCode.PROTOCOL_ERROR, `welcome.ping_interval ${welcome.ping_interval} is below the ${minInterval}ms floor`);
+    }
+    const minTimeout = this.opts._timing?.minPingTimeout ?? 2 * welcome.ping_interval;
+    if (welcome.ping_timeout < minTimeout) {
+      throw new ConnError(
+        ErrorCode.PROTOCOL_ERROR,
+        `welcome.ping_timeout (${welcome.ping_timeout}) must be at least ${minTimeout}ms`
+      );
+    }
+    this.session = welcome.session;
+    this.peerWindow = welcome.window;
+    this.maxStreams = this.opts.maxStreams ? Math.min(this.opts.maxStreams, welcome.max_streams) : welcome.max_streams;
+    this.pingIntervalMs = welcome.ping_interval;
+    this.pingTimeoutMs = welcome.ping_timeout;
+    this.welcomeMeta = welcome.meta;
+    this.handshakeDone = true;
+    this.lastPongAt = Date.now();
+    this.emit("welcome", welcome);
+    this.emit("__welcome_internal", welcome);
+    this.startKeepalive();
+  }
+  // --- read dispatch (never blocks on application code) ------------------------
+  onMessage(data) {
+    this.counters.bytesIn += data.length;
+    try {
+      this.dispatchFrame(data instanceof Uint8Array ? data : new Uint8Array(data));
+    } catch (e) {
+      this.handleDispatchError(e);
+    }
+  }
+  handleDispatchError(e) {
+    if (e instanceof ConnError) {
+      this.counters.protocolViolations++;
+      this.fail(e);
+      return;
+    }
+    if (e instanceof StreamError) {
+      const stream = this.streams.get(e.streamId);
+      if (stream) {
+        stream.abort(e.code, e.message);
+      } else {
+        this.sendControlFrame(encodeReset(e.streamId, e.code, e.message));
+      }
+      return;
+    }
+    this.fail(new ConnError(ErrorCode.INTERNAL_ERROR, e instanceof Error ? e.message : String(e)));
+  }
+  dispatchFrame(msg) {
+    const frame = decodeFrame(msg);
+    const known = Object.values(FrameType).includes(frame.type);
+    if (!known) {
+      this.counters.unknownFrameTypes++;
+      return;
+    }
+    if (frame.streamId === 0) {
+      if (frame.type !== FrameType.DATA) {
+        return;
+      }
+      this.dispatchControl(frame.payload);
+      return;
+    }
+    if (!this.handshakeDone) {
+      throw new ConnError(ErrorCode.PROTOCOL_ERROR, `${frameTypeName(frame.type)} frame received before welcome completed the handshake`);
+    }
+    const id = frame.streamId;
+    if (frame.type === FrameType.OPEN) {
+      if (id <= this.highestOpened) {
+        throw new ConnError(ErrorCode.PROTOCOL_ERROR, `duplicate or out-of-order OPEN for stream ${id}`);
+      }
+      this.highestOpened = id;
+      if (this.draining && this.lastStreamId !== void 0 && id > this.lastStreamId) {
+        this.counters.drainViolations++;
+        throw new ConnError(
+          ErrorCode.PROTOCOL_ERROR,
+          `OPEN for stream ${id} received after drain (last_stream_id=${this.lastStreamId})`
+        );
+      }
+      if (this.streams.size >= this.maxStreams) {
+        this.counters.refusedOpens++;
+        this.sendControlFrame(encodeReset(id, ErrorCode.STREAM_LIMIT, `max_streams=${this.maxStreams} exceeded by stream ${id}`));
+        return;
+      }
+      const stream2 = new MixerStream(id, this.#streamHost, this.ourWindow, this.peerWindow);
+      this.streams.set(id, stream2);
+      this.enqueueDelivery({ kind: "stream", stream: stream2 });
+      return;
+    }
+    if (id > this.highestOpened) {
+      throw new ConnError(ErrorCode.PROTOCOL_ERROR, `${frame.type === FrameType.DATA ? "DATA" : "frame"} for stream ${id}, which was never opened`);
+    }
+    const stream = this.streams.get(id);
+    if (!stream) {
+      this.counters.staleFrames++;
+      return;
+    }
+    switch (frame.type) {
+      case FrameType.DATA:
+        stream.handleData(frame.payload);
+        break;
+      case FrameType.WINDOW:
+        stream.handleWindow(windowIncrement(frame));
+        break;
+      case FrameType.CLOSE:
+        stream.handleClose();
+        break;
+      case FrameType.RESET:
+        stream.handleReset(resetCode(frame), resetMessage(frame));
+        break;
+    }
+  }
+  dispatchControl(payload) {
+    if (!this.stream0Bucket.allow()) {
+      throw new ConnError(ErrorCode.ENHANCE_YOUR_CALM, `stream-0 message rate exceeded ${STREAM0_RATE_PER_SEC}/s (burst ${STREAM0_BURST})`);
+    }
+    const msg = parseControl(payload);
+    switch (msg.t) {
+      case "welcome":
+        if (this.handshakeDone) throw new ConnError(ErrorCode.PROTOCOL_ERROR, "duplicate welcome after handshake completed");
+        this.applyWelcome(msg);
+        return;
+      case "hello":
+        throw new ConnError(ErrorCode.PROTOCOL_ERROR, "unexpected hello: only the client sends hello");
+      case "ping":
+        if (!this.handshakeDone) {
+          throw new ConnError(ErrorCode.PROTOCOL_ERROR, "ping received before welcome completed the handshake");
+        }
+        void this.sendControlPriority({ t: "pong", id: msg.id, ...msg.ts !== void 0 ? { ts: msg.ts } : {} }).catch(() => {
+        });
+        return;
+      case "pong":
+        this.handlePong(msg.id);
+        return;
+      case "drain": {
+        if (!this.handshakeDone) {
+          throw new ConnError(ErrorCode.PROTOCOL_ERROR, "drain received before welcome completed the handshake");
+        }
+        let reason = msg.reason;
+        if (!knownDrainReason(reason)) {
+          this.counters.unknownDrainReasons++;
+          reason = "maintenance";
+        }
+        const normalized = reason === msg.reason ? msg : { ...msg, reason };
+        this.draining = true;
+        this.lastStreamId = this.lastStreamId === void 0 ? normalized.last_stream_id : Math.min(this.lastStreamId, normalized.last_stream_id);
+        this.enqueueDelivery({ kind: "drain", msg: normalized });
+        return;
+      }
+      case "error":
+        this.handlePeerError(msg.code, msg.message, msg.stream_id);
+        return;
+      case "app":
+        if (!this.handshakeDone) throw new ConnError(ErrorCode.PROTOCOL_ERROR, "app message received before welcome");
+        this.enqueueDelivery({ kind: "app", body: msg.body });
+        return;
+    }
+  }
+  // --- ordered async delivery (item 2) -------------------------------------
+  /**
+   * Queues one `'stream'`/`'app'`/`'drain'` event for in-order, async
+   * delivery, mirroring go/wsmixer's deliveryLoop: the read/dispatch path
+   * above never blocks on application code, but all three still fire in
+   * wire order, off a single loop, one at a time. Handlers registered via
+   * `on('stream'|'app'|'drain', ...)` must not block for long -- a handler
+   * that never returns/resolves permanently wedges this loop, exactly like
+   * the Go side. Throws ConnError(ENHANCE_YOUR_CALM) if the bounded queue
+   * (`max(128, max_streams + 64)`) is full, which the caller (dispatchFrame/
+   * dispatchControl, inside onMessage's try/catch) turns into fail().
+   *
+   * Refuses once `this.closed` (CLIENT-SDK.md's "Handler delivery" row):
+   * `dispatchFrame`/`dispatchControl` -- the only callers -- always run
+   * before whatever ends the connection sets `this.closed` (every
+   * fail()/close()/handlePeerError path runs teardownConn synchronously,
+   * `error` is always the last message on the wire), so nothing legitimate
+   * should ever reach here once closed; this is the defensive backstop that
+   * makes runDeliveryLoop's post-close drain below provably bounded and
+   * terminating regardless.
+   */
+  enqueueDelivery(ev) {
+    if (this.closed) return;
+    const capacity = Math.max(DELIVERY_QUEUE_MIN, this.maxStreams + DELIVERY_QUEUE_MARGIN);
+    if (this.deliveryQueue.length >= capacity) {
+      throw new ConnError(ErrorCode.ENHANCE_YOUR_CALM, `application delivery queue full (>${capacity} pending stream/app/drain callbacks)`);
+    }
+    this.deliveryQueue.push(ev);
+    if (!this.deliveryRunning) {
+      this.deliveryRunning = true;
+      void this.runDeliveryLoop();
+    }
+  }
+  /**
+   * Drains `deliveryQueue` until empty -- deliberately NOT gated on
+   * `!this.closed` (CLIENT-SDK.md's "Handler delivery" row): an event
+   * already queued when the connection ends is still owed to its handler
+   * (`error` is the last message on the wire, so a stream OPEN/`app`/`drain`
+   * queued ahead of it arrived before the connection ended), so this loop
+   * finishes flushing that backlog even after `teardownConn` has already set
+   * `this.closed` and emitted `'close'` -- a handler MAY therefore run
+   * shortly after `MixerClient.close()`/`MixerConn.close()`'s own promise has
+   * already resolved (see those methods' doc comments and README). `if
+   * (!ev) break` is what actually ends the loop; since `enqueueDelivery`
+   * above refuses once closed, the queue can only shrink from here, so this
+   * always terminates.
+   */
+  async runDeliveryLoop() {
+    for (; ; ) {
+      const ev = this.deliveryQueue.shift();
+      if (!ev) break;
+      switch (ev.kind) {
+        case "stream":
+          await this.emitOrdered("stream", ev.stream);
+          break;
+        case "app":
+          await this.emitOrdered("app", ev.body);
+          break;
+        case "drain":
+          await this.emitOrdered("drain", ev.msg);
+          break;
+      }
+    }
+    this.deliveryRunning = false;
+  }
+  /**
+   * Invokes every listener for `event` in registration order, awaiting each
+   * one's return value before starting the next -- unlike EventEmitter's own
+   * synchronous `emit`, which fires listeners back to back without waiting
+   * for a returned Promise to settle.
+   *
+   * A listener that throws synchronously or returns a rejected promise is
+   * caught here, counted (stats().handlerErrors) and surfaced via a guarded
+   * `'handlerError'` emit -- never an unhandled rejection, and never fatal
+   * to delivery: the next queued stream/app/drain event still runs.
+   */
+  async emitOrdered(event, arg) {
+    for (const listener of this.listeners(event)) {
+      try {
+        const result = listener.call(this, arg);
+        if (result instanceof Promise) await result;
+      } catch (e) {
+        this.counters.handlerErrors++;
+        const error = e instanceof Error ? e : new Error(String(e));
+        if (this.listenerCount("handlerError") > 0) this.emit("handlerError", { event, error });
+      }
+    }
+  }
+  // --- outbound: control priority + round-robin DATA scheduler ------------------
+  /**
+   * Queues one control-channel frame and returns a promise that resolves
+   * once `ws.send`'s callback confirms it was actually written (or rejects
+   * with the connection's terminal error if the conn fails first) --
+   * mirroring how `sendData()`'s per-stream outbox already works.
+   */
+  enqueueControl(frame, priority = false) {
+    return new Promise((resolve, reject) => {
+      if (this.closed) {
+        reject(new ConnError(ErrorCode.INTERNAL_ERROR, "connection closed"));
+        return;
+      }
+      const item = { frame, resolve, reject };
+      if (priority) this.controlQueue.unshift(item);
+      else this.controlQueue.push(item);
+      this.wake();
+    });
+  }
+  /**
+   * Sends a control message (hello/ping/pong/drain/app/error) as stream-0
+   * DATA, queued ahead of any DATA. Resolves once the frame is actually
+   * written to the socket.
+   */
+  sendControl(msg) {
+    return this.enqueueControl(encodeData(0, encodeControl(msg)));
+  }
+  /**
+   * Sends a control message at the head of the control queue, ahead of
+   * anything already queued (item 6: "A pong MUST ... jump ahead of queued
+   * DATA" -- and ahead of other queued control frames too).
+   */
+  sendControlPriority(msg) {
+    return this.enqueueControl(encodeData(0, encodeControl(msg)), true);
+  }
+  /** Backs `streamHost.sendControlFrame`: send a control-priority frame (WINDOW/CLOSE/RESET) immediately. */
+  sendControlFrame(frame) {
+    void this.enqueueControl(frame).catch(() => {
+    });
+  }
+  /** Backs `streamHost.sendData`: enqueue a DATA chunk for round-robin transmission. */
+  sendData(streamId, chunk) {
+    return new Promise((resolve, reject) => {
+      if (this.closed) {
+        reject(new ConnError(ErrorCode.INTERNAL_ERROR, "connection closed"));
+        return;
+      }
+      let q = this.outbox.get(streamId);
+      if (!q) {
+        q = [];
+        this.outbox.set(streamId, q);
+      }
+      q.push({ chunk, resolve, reject });
+      this.markReady(streamId);
+    });
+  }
+  /** Backs `streamHost.retireStream`: retire a fully-closed stream's id. */
+  retireStream(streamId) {
+    this.streams.delete(streamId);
+    this.outbox.delete(streamId);
+    if (this.streams.size === 0) this.notifyIdle();
+  }
+  /** Resolves every pending close()'s wait for the stream table to empty, instead of polling. */
+  notifyIdle() {
+    const waiters = this.idleWaiters;
+    this.idleWaiters = [];
+    for (const w of waiters) w();
+  }
+  waitForEmpty() {
+    return new Promise((resolve) => {
+      if (this.streams.size === 0) {
+        resolve();
+        return;
+      }
+      this.idleWaiters.push(resolve);
+    });
+  }
+  markReady(streamId) {
+    if (!this.inRotation.has(streamId)) {
+      this.inRotation.add(streamId);
+      this.rotation.push(streamId);
+    }
+    this.wake();
+  }
+  wake() {
+    const waiters = this.wakeWaiters;
+    this.wakeWaiters = [];
+    for (const w of waiters) w();
+  }
+  waitForWork() {
+    return new Promise((resolve) => this.wakeWaiters.push(resolve));
+  }
+  nextChunk() {
+    while (this.rotation.length > 0) {
+      const id = this.rotation.shift();
+      this.inRotation.delete(id);
+      const q = this.outbox.get(id);
+      if (!q || q.length === 0) continue;
+      const item = q.shift();
+      const stream = this.streams.get(id);
+      if (stream) {
+        const { done, error } = stream.sendDone();
+        if (done) {
+          item.reject(error);
+          continue;
+        }
+      }
+      if (q.length > 0) this.markReady(id);
+      return { streamId: id, item };
+    }
+    return null;
+  }
+  startWriter() {
+    if (this.writerRunning) return;
+    this.writerRunning = true;
+    void this.runWriter();
+  }
+  async runWriter() {
+    while (!this.closed) {
+      while (this.controlQueue.length > 0) {
+        const item = this.controlQueue.shift();
+        try {
+          await this.writeRaw(item.frame);
+          item.resolve();
+        } catch (e) {
+          item.reject(e);
+          return;
+        }
+      }
+      const next = this.nextChunk();
+      if (next) {
+        try {
+          await this.writeRaw(encodeData(next.streamId, next.item.chunk));
+          next.item.resolve();
+        } catch (e) {
+          next.item.reject(e);
+          return;
+        }
+        continue;
+      }
+      await this.waitForWork();
+    }
+  }
+  /**
+   * Writes one frame and resolves once `ws.send`'s callback reports it
+   * flushed. This is how rule 2 (§2.6, "gate the write loop on the socket
+   * send buffer") is satisfied without polling `bufferedAmount` on a timer:
+   * `ws`'s `send(data, cb)` callback fires only once the chunk has actually
+   * been handed to the socket, so awaiting it before writing the next frame
+   * already keeps exactly one write in flight and applies backpressure for
+   * free (runWriter's loop awaits writeRaw() before picking the next chunk).
+   */
+  writeRaw(frame) {
+    return new Promise((resolve, reject) => {
+      if (this.closed) {
+        reject(new Error("connection closed"));
+        return;
+      }
+      try {
+        this.ws.send(frame, (err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          this.counters.bytesOut += frame.length;
+          resolve();
+        });
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+  // --- app messages -------------------------------------------------------------
+  /** Resolves once the `app` frame is actually written to the socket, or rejects with the connection's terminal error if it fails first. */
+  sendApp(body) {
+    return this.sendControl({ t: "app", body });
+  }
+  // --- keepalive ------------------------------------------------------------------
+  startKeepalive() {
+    const jitter = Math.random() * this.pingIntervalMs;
+    this.jitterTimer = setTimeout(() => {
+      this.jitterTimer = null;
+      if (this.closed) return;
+      this.sendPing();
+      this.pingTimer = setInterval(() => this.sendPing(), this.pingIntervalMs);
+    }, jitter);
+    this.watchdogTimer = setInterval(() => this.checkWatchdog(), Math.min(1e3, this.pingTimeoutMs));
+  }
+  sendPing() {
+    if (this.closed) return;
+    const id = this.nextPingId++;
+    this.outstandingPings.set(id, Date.now());
+    void this.sendControl({ t: "ping", id, ts: Date.now() }).catch(() => {
+    });
+  }
+  /**
+   * Pong watermark scheme, mirroring go/wsmixer/dispatch.go's handlePong:
+   * every id below lowestUnacked has been acked (or pruned as stale) at
+   * least once, and no id >= nextPingId has ever been sent.
+   *  - id >= nextPingId: never sent -> PROTOCOL_ERROR, connection-fatal.
+   *  - id < lowestUnacked, or in-range but already absent from the map
+   *    (already acked, or pruned by the watchdog as stale/late): a
+   *    duplicate or late pong -- tolerated, just counted.
+   */
+  handlePong(id) {
+    if (id >= this.nextPingId) {
+      throw new ConnError(ErrorCode.PROTOCOL_ERROR, `pong for id ${id} that was never sent`);
+    }
+    if (id < this.lowestUnacked) {
+      this.counters.duplicatePongs++;
+      return;
+    }
+    const sentAt = this.outstandingPings.get(id);
+    if (sentAt === void 0) {
+      this.counters.duplicatePongs++;
+      return;
+    }
+    this.outstandingPings.delete(id);
+    if (id === this.lowestUnacked) {
+      this.lowestUnacked++;
+      while (this.lowestUnacked < this.nextPingId && !this.outstandingPings.has(this.lowestUnacked)) {
+        this.lowestUnacked++;
+      }
+    }
+    this.lastPongAt = Date.now();
+    this.emit("pong", { id, rttMs: Date.now() - sentAt });
+  }
+  checkWatchdog() {
+    if (this.closed) return;
+    const elapsed = Date.now() - this.lastPongAt;
+    for (const [id, sentAt] of this.outstandingPings) {
+      if (Date.now() - sentAt > this.pingTimeoutMs) this.outstandingPings.delete(id);
+    }
+    if (elapsed > this.pingTimeoutMs) {
+      this.fail(new ConnError(ErrorCode.KEEPALIVE_TIMEOUT, `no pong received for ${elapsed}ms`));
+    }
+  }
+  // --- shutdown -----------------------------------------------------------------
+  /**
+   * Shared teardown: WS close `4000 + code`, reject everything outstanding,
+   * emit `'fatal'`/`'error'` (guarded) then `'close'`, synchronously and in
+   * that order every time. `sendErrorFrame` controls whether an
+   * `error{code,message}` control frame is sent first -- true for a
+   * locally-detected failure (fail()), false when the peer already sent its
+   * own `error` and WIRE.md section 2.7 forbids replying with another
+   * one (handlePeerError()). Either way `this.closed` is set *before*
+   * `ws.close()` is called, so the peer's echo of this close (or any close
+   * frame it happens to send around the same time) is ignored by
+   * onSocketClose below rather than reported as `closeReason` -- per
+   * CLIENT-SDK.md's `closeReason` row, an outgoing reason this side sent is
+   * never legitimate `closeReason` data, and there is nothing to gain by
+   * waiting for the peer's own close frame here: WIRE.md section 2.7
+   * already allows closing on `error` "without reading the close frame that
+   * followed".
+   */
+  teardownConn(err, sendErrorFrame, streamErrorFactory) {
+    if (this.closed) return;
+    this.closed = true;
+    this.stopTimers();
+    if (sendErrorFrame) {
+      try {
+        const frame = encodeData(0, encodeControl({ t: "error", code: err.code, message: err.message }));
+        this.ws.send(frame);
+        this.counters.bytesOut += frame.length;
+      } catch {
+      }
+    }
+    const wsCode = closeCode(err.code);
+    const reason = truncateUtf8(err.message, 123);
+    try {
+      this.ws.close(wireCloseCode(wsCode), reason);
+    } catch {
+      this.ws.terminate?.();
+    }
+    this.rejectOutstanding(err, streamErrorFactory);
+    if (!this.handshakeDone) this.emit("__handshake_failed_internal", err);
+    const fatal = err.code === ErrorCode.UNSUPPORTED || err.code === ErrorCode.UNAUTHORIZED;
+    const evt = fatal ? "fatal" : "error";
+    if (this.listenerCount(evt) > 0) this.emit(evt, err);
+    this.emit("close", { wsCode, errorCode: err.code, message: err.message });
+  }
+  /**
+   * Connection-fatal failure path: error{code,message} on stream 0, WS close
+   * 4000+code, teardown. Three steps, in order (WIRE.md section 2.8).
+   *
+   * `streamErrorFactory`, when given, overrides the error every live stream
+   * is torn down with (`err` is still used for the connection-level frame/
+   * close/rejects) -- used by MixerClient when it fails a *superseded*
+   * (drained) conn: the streams on it aren't erroring, the conn they were
+   * riding on is being replaced, so each gets a stream-scoped CANCEL
+   * ("connection drained") instead of the connection's own NO_ERROR.
+   *
+   * Synchronous, but any stream/app/drain event still queued for delivery at
+   * this point is not: runDeliveryLoop keeps flushing it after this returns
+   * (see close()'s doc comment above for why).
+   */
+  fail(err, streamErrorFactory) {
+    this.teardownConn(err, true, streamErrorFactory);
+  }
+  /**
+   * The peer sent `error{code,message}`: record it and close with
+   * `4000 + code` immediately, without waiting for the peer to do anything
+   * else -- mirrors go/wsmixer/dispatch.go's handlePeerError. `error` is
+   * always the last message on the wire (WIRE.md section 2.7), so
+   * there is nothing left to negotiate.
+   */
+  handlePeerError(code, message, streamId) {
+    const err = new WsMixerError(code, message, { streamId });
+    this.teardownConn(err, false);
+  }
+  /**
+   * Graceful client shutdown: drain{client_requested}, brief grace period,
+   * then close(NO_ERROR). This resolves once teardownConn's synchronous
+   * steps are done (frame/WS close/rejects/'close' emitted) -- it does NOT
+   * wait for runDeliveryLoop to finish flushing whatever stream/app/drain
+   * backlog was still queued at that point. A handler for an event received
+   * before this close MAY therefore still be invoked shortly after this
+   * promise (and 'close') has already resolved/fired (CLIENT-SDK.md's
+   * "Handler delivery" row).
+   */
+  async close(graceMs = 5e3) {
+    if (this.closed) return;
+    if (this.handshakeDone) {
+      void this.sendControl({ t: "drain", reason: "client_requested", last_stream_id: this.highestOpened }).catch(() => {
+      });
+      if (this.streams.size > 0) {
+        let graceTimer;
+        let onClose;
+        try {
+          await Promise.race([
+            this.waitForEmpty(),
+            new Promise((resolve) => {
+              graceTimer = setTimeout(resolve, graceMs);
+            }),
+            new Promise((resolve) => {
+              onClose = () => resolve();
+              this.once("close", onClose);
+            })
+          ]);
+        } finally {
+          if (graceTimer) clearTimeout(graceTimer);
+          if (onClose) this.off("close", onClose);
+        }
+      }
+    }
+    if (this.closed) return;
+    this.fail(new WsMixerError(ErrorCode.NO_ERROR, "client closing"));
+  }
+  /**
+   * A close frame this side actually *received* from `ws`'s 'close' event.
+   * `code`/`reason` here are always the peer's, per `ws`'s own contract
+   * (`receiverOnConclude` in `ws/lib/websocket.js` only ever updates
+   * `_closeCode`/`_closeMessage` from a frame it parsed off the wire, never
+   * from what this side sent via `.close()`) -- so whenever `this.closed` is
+   * already `true`, this is a close frame arriving after teardownConn()
+   * already ran and reported (never our own echoed close winning a race),
+   * and is correctly ignored rather than folded in after the fact.
+   *
+   * Pre-welcome, this is also the SOLE reporter for a transport failure
+   * before `welcome` -- measured against real `ws` (8.21): a TCP reset,
+   * half-close or peer close frame after the 101 delivers a bare 'close'
+   * with no 'error' at all, and a protocol-level failure `ws` itself
+   * detects (an invalid frame: 1002, an oversized message: 1009, ...)
+   * delivers 'error' immediately followed by 'close' a macrotask or more
+   * later -- 'close' is never racing 'error' for which one wins; it always
+   * arrives after it, if it arrives at all. `onSocketError` below therefore
+   * never finalizes anything itself, only records the error's message here
+   * for `message` to fall back on when the close carries no reason of its
+   * own -- so this always reports the *actual* close code `ws` delivers
+   * (1006, or whatever real close code it sent), never a wsCode fabricated
+   * for a close that never happened.
+   */
+  onSocketClose(code, reason) {
+    if (this.closed) return;
+    this.closed = true;
+    this.stopTimers();
+    const reasonStr = reason.toString();
+    const handshakePhase = !this.handshakeDone;
+    const message = reasonStr || (handshakePhase ? this.pendingHandshakeErrorMessage : void 0) || `socket closed with code ${code}`;
+    const err = new WsMixerError(ErrorCode.INTERNAL_ERROR, message, {
+      wsCode: code,
+      closeReason: reasonStr || void 0
+    });
+    this.rejectOutstanding(err);
+    if (handshakePhase) this.emit("__handshake_failed_internal", err);
+    this.emit("close", { wsCode: code, message, closeReason: reasonStr || void 0 });
+  }
+  /**
+   * Pre-welcome, `'error'` never arrives in the same microtask as (or after)
+   * a 'close' that never comes -- see onSocketClose's own doc comment for
+   * what real `ws` actually does. So this deliberately does NOT reject or
+   * finalize the handshake itself; it just records the error's message for
+   * onSocketClose (the sole reporter) to use as `message` when the close
+   * that follows carries no reason of its own. If `'close'` somehow never
+   * follows at all (a transport that violates `ws`'s own contract), nothing
+   * here is left waiting on it: `handshake()`'s own hello/welcome timeout
+   * (`handshakeTimer`, 10s default) still fires and produces the one report
+   * (`wsCode` 4001) regardless -- deliberately the only fallback for that
+   * case, not a second mechanism grafted on here.
+   */
+  onSocketError(err) {
+    if (!this.handshakeDone && !this.closed) {
+      this.pendingHandshakeErrorMessage = err.message;
+    }
+    if (this.listenerCount("error") > 0) this.emit("error", new WsMixerError(ErrorCode.INTERNAL_ERROR, err.message));
+  }
+  stopTimers() {
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    if (this.watchdogTimer) clearInterval(this.watchdogTimer);
+    if (this.handshakeTimer) clearTimeout(this.handshakeTimer);
+    if (this.jitterTimer) clearTimeout(this.jitterTimer);
+    this.pingTimer = null;
+    this.watchdogTimer = null;
+    this.handshakeTimer = null;
+    this.jitterTimer = null;
+  }
+  rejectOutstanding(err, streamErrorFactory) {
+    for (const q of this.outbox.values()) {
+      for (const item of q) item.reject(err);
+    }
+    this.outbox.clear();
+    for (const item of this.controlQueue.splice(0, this.controlQueue.length)) {
+      item.reject(err);
+    }
+    this.wake();
+    for (const stream of this.streams.values()) {
+      stream.terminateNoThrow(
+        streamErrorFactory ? streamErrorFactory(stream.id) : err instanceof WsMixerError ? err : new ConnError(ErrorCode.INTERNAL_ERROR, err.message)
+      );
+    }
+  }
+  isDraining() {
+    return this.draining;
+  }
+  liveStreamCount() {
+    return this.streams.size;
+  }
+};
+
+// src/client.ts
+var SUBPROTOCOL = "ws-mixer.v1";
+var SDK_VERSION = "0.6.0";
+async function resolveToken(token) {
+  return typeof token === "function" ? await token() : token;
+}
+var DEFAULT_RECONNECT = {
+  base: 1e3,
+  cap: 6e4,
+  connectTimeout: 1e4,
+  maxAttempts: Infinity,
+  stableAfter: 1e4
+};
+var FATAL_WS_CODES = /* @__PURE__ */ new Set([4e3 + ErrorCode.UNSUPPORTED, 4e3 + ErrorCode.UNAUTHORIZED]);
+var GOING_AWAY_WS_CODE = 4e3 + ErrorCode.GOING_AWAY;
+var KEEPALIVE_TIMEOUT_WS_CODE = 4e3 + ErrorCode.KEEPALIVE_TIMEOUT;
+var ENHANCE_YOUR_CALM_WS_CODE = 4e3 + ErrorCode.ENHANCE_YOUR_CALM;
+var APPLICATION_CLOSE_WS_CODE = 4e3 + ErrorCode.APPLICATION_CLOSE;
+var ABNORMAL_CLOSURE_WS_CODE = 1001;
+var PROTOCOL_BUG_WS_CODES = /* @__PURE__ */ new Set([
+  4e3 + ErrorCode.PROTOCOL_ERROR,
+  // 4001
+  4e3 + ErrorCode.FLOW_CONTROL_ERROR,
+  // 4003
+  4e3 + ErrorCode.FRAME_SIZE_ERROR
+  // 4004
+]);
+function deriveErrorCodeName(wsCode, knownErrorCode) {
+  const errorCode = knownErrorCode ?? (wsCode !== void 0 && wsCode >= 4001 && wsCode <= 4999 ? wsCode - 4e3 : void 0);
+  return { errorCode, errorName: errorCode !== void 0 ? codeName(errorCode) : void 0 };
+}
+var MixerClient = class extends EventEmitter2 {
+  url;
+  opts;
+  reconnectOpts;
+  state = "idle";
+  /** The confirmed-live connection (welcome received). Null while dialing/backing off. */
+  conn = null;
+  /** A MixerConn mid-handshake, not yet promoted to `conn`. Tracked so close() can tear it down too. */
+  dialingConn = null;
+  /**
+   * Set only while a `drain`-triggered parallel reconnect is in flight: the
+   * connection that sent `drain`, still alive and finishing in-flight
+   * streams. Torn down (fail()) as soon as its replacement's `welcome`
+   * lands, so a superseded connection never lingers past that point.
+   */
+  retiringConn = null;
+  attempt = 0;
+  everConnected = false;
+  closing = false;
+  fatal = false;
+  /** Set when `drain` already started a parallel reconnect, so the close that follows it doesn't schedule a second one. */
+  drainReconnectScheduled = false;
+  /**
+   * Set when `drain` arrives with reconnect disabled (`maxAttempts:0`):
+   * WIRE.md section 2.9 says in-flight streams finish normally until the
+   * server's own deadline, at which point it closes with 4012 -- so the conn
+   * stays up and this flag just tells the eventual close handler to report
+   * that close as the one fatal "drained; reconnect disabled" disconnect
+   * instead of treating 4012 as an ordinary going-away reconnect trigger.
+   */
+  drainedNoReconnect = false;
+  /** WIRE.md section 2.9: close 4013 gets exactly one immediate retry before falling back to normal backoff. Re-armed at stability, not at welcome -- see armStabilityTimer. */
+  keepaliveImmediateRetryUsed = false;
+  /**
+   * CLIENT-SDK.md's "Rejected token" row: a pre-welcome token rejection (an HTTP 401 on
+   * the upgrade, or a handshake-phase UNAUTHORIZED/4011, with or without a
+   * preceding `error{}`) gets exactly one immediate provider refresh-retry
+   * -- ONE budget shared across both rejection shapes, and across every
+   * `connectOnce()` call, not reset on every dial/redial. Re-armed only at
+   * stability (armStabilityTimer), same as `keepaliveImmediateRetryUsed`:
+   * without that, a server that welcomes and then closes shortly after could
+   * make the client hit the token endpoint again on every single reconnect
+   * cycle forever, instead of only once per genuinely-unstable run. After a
+   * long healthy (stable) session, the budget is available again -- an
+   * ordinary token expiry on some later reconnect still gets its retry.
+   */
+  unauthorizedRetryUsed = false;
+  reconnectTimer = null;
+  /** Resolves connectOnce's backoff-delay await; settled directly by clearReconnectTimer() so close()/goFatal()/giveUp() during backoff don't leave that await dangling forever. */
+  reconnectTimerResolve = null;
+  /**
+   * One-shot timer armed on `welcome` (armStabilityTimer): fires once the
+   * *current* conn has stayed up for `reconnectOpts.stableAfter` ms, at
+   * which point `attempt` and the once-only retry budgets it gates
+   * (`keepaliveImmediateRetryUsed`, `unauthorizedRetryUsed`) reset.
+   * `unref()`'d so it never keeps the process alive, and cleared on every
+   * path that ends a conn or the client itself (conn close, close()/
+   * close({message}), goFatal, a drain hand-over's retired conn) so a stale
+   * timer can never fire against a conn that's no longer the active one --
+   * though the `this.conn === conn` check inside it is also always
+   * re-verified regardless, belt and suspenders. Per-connection: a
+   * drain-superseded predecessor closing well after its replacement's own
+   * `welcome` must never clear the replacement's still-ticking timer (see
+   * the `wasActive` guard in wireConn's 'close' handler below).
+   */
+  stabilityTimer = null;
+  startResolve = null;
+  startReject = null;
+  constructor(url, opts) {
+    super();
+    this.url = url;
+    this.opts = opts;
+    this.reconnectOpts = { ...DEFAULT_RECONNECT, ...opts.reconnect };
+    if (!Number.isFinite(this.reconnectOpts.stableAfter) || this.reconnectOpts.stableAfter < 0) {
+      throw new RangeError(
+        `ws-mixer: reconnect.stableAfter must be a finite number >= 0; got ${this.reconnectOpts.stableAfter}`
+      );
+    }
+  }
+  /** Starts the first connection attempt and resolves once `welcome` completes (or rejects if it never gets there and reconnecting is pointless: a fatal auth failure, or maxAttempts exhausted before the first success). */
+  async start() {
+    return new Promise((resolve, reject) => {
+      this.startResolve = resolve;
+      this.startReject = reject;
+      void this.connectOnce(0, "initial");
+    });
+  }
+  /** The currently active MixerConn, if connected. */
+  currentConn() {
+    return this.conn;
+  }
+  /** Current reconnect state machine position: idle/dialing/connected/backoff/closed. */
+  currentState() {
+    return this.state;
+  }
+  /**
+   * Writes an `app` frame; resolves once `ws.send`'s callback confirms it
+   * actually reached the socket (docs/DESIGN.md), or rejects with the
+   * connection's terminal error if it fails first -- conn.ts's control queue
+   * carries the same per-write resolver `sendData()` already uses for stream
+   * bytes.
+   */
+  sendApp(body) {
+    if (!this.conn) return Promise.reject(new Error("ws-mixer: sendApp called with no active connection"));
+    return this.conn.sendApp(body);
+  }
+  /** "Ignore and count" counters for the active connection (item 11); `undefined` when there is none. */
+  stats() {
+    return this.conn?.stats();
+  }
+  /**
+   * Graceful client shutdown: stops reconnecting for good and closes every
+   * live/in-flight connection. A dial already in flight when this is called
+   * is closed as soon as it resolves (see connectOnce); nothing reconnects
+   * after this returns.
+   *
+   * With `opts.message`, this is instead an application-initiated close
+   * (CLIENT-SDK.md's "Application close" row): `error{code:
+   * ErrorCode.APPLICATION_CLOSE, message}` on stream 0, WS close `4014`
+   * (message truncated to 123 UTF-8 bytes on a character boundary), then
+   * the socket -- `MixerConn.fail()`'s `teardownConn` already performs
+   * exactly those three steps in order. No `drain`, no grace period.
+   * `APPLICATION_CLOSE` is the only code an application may close a
+   * *connection* with (WIRE.md section 2.8), so there is no caller-chosen
+   * code here (D-2026-09-25-01): an `opts` with a `code` key (a plain-JS
+   * caller still on the old `close({code, message})` shape) throws a
+   * `TypeError` synchronously, before either connection is touched.
+   *
+   * A callback for a stream/`app`/`drain` event received before this close
+   * can still fire shortly after this promise resolves: it doesn't wait for
+   * `onStream`/`onApp`/`onDrain`'s delivery loop to finish flushing whatever
+   * was already queued (CLIENT-SDK.md's "Handler delivery" row) -- see those
+   * options' own doc comments.
+   */
+  close(opts) {
+    if (typeof opts === "object" && opts !== null && Object.prototype.hasOwnProperty.call(opts, "code")) {
+      throw new TypeError(
+        "ws-mixer: close() no longer takes a code (D-2026-09-25-01); use close({message}) -- it always closes with APPLICATION_CLOSE"
+      );
+    }
+    return this.closeImpl(opts);
+  }
+  async closeImpl(opts) {
+    this.closing = true;
+    this.state = "closed";
+    this.drainedNoReconnect = false;
+    this.rejectStartIfNeverConnected(new Error("ws-mixer: closed before the first connection completed"));
+    this.clearReconnectTimer();
+    this.clearStabilityTimer();
+    const closeErr = opts?.message !== void 0 ? new WsMixerError(ErrorCode.APPLICATION_CLOSE, opts.message) : new WsMixerError(ErrorCode.NO_ERROR, "client closing");
+    if (this.retiringConn) {
+      const old = this.retiringConn;
+      this.retiringConn = null;
+      old.fail(closeErr);
+    }
+    if (this.dialingConn) {
+      const dialing = this.dialingConn;
+      this.dialingConn = null;
+      dialing.fail(closeErr);
+    }
+    if (this.conn) {
+      if (opts?.message !== void 0) {
+        this.conn.fail(closeErr);
+      } else {
+        await this.conn.close();
+      }
+    }
+  }
+  // this.state is a plain string-literal-union property, and TS's control
+  // flow narrowing does *not* invalidate a narrowed `this.state === "x"`
+  // across an `await` (even though the awaited call can, and here does,
+  // reassign it) -- so connectOnce below reads it through this indirection
+  // to force a fresh, unnarrowed check every time.
+  isClosed() {
+    return this.state === "closed";
+  }
+  /** Cancels a pending backoff timer, if any, and settles connectOnce's awaited delay promise so it doesn't dangle. */
+  clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.reconnectTimerResolve) {
+      const resolve = this.reconnectTimerResolve;
+      this.reconnectTimerResolve = null;
+      resolve();
+    }
+  }
+  /** Cancels the pending stability timer, if any (see the field's own doc comment). Idempotent. */
+  clearStabilityTimer() {
+    if (this.stabilityTimer) {
+      clearTimeout(this.stabilityTimer);
+      this.stabilityTimer = null;
+    }
+  }
+  /**
+   * Arms the one-shot stability timer for `conn`, replacing (and so
+   * implicitly clearing) whatever timer was pending before -- there is only
+   * ever one conn worth timing at once: a drain-superseded predecessor is
+   * torn down as soon as the replacement's own `welcome` lands (connectOnce),
+   * which is exactly the moment this is called for the replacement, so the
+   * predecessor's own now-irrelevant timer never outlives this call.
+   */
+  armStabilityTimer(conn) {
+    this.clearStabilityTimer();
+    const timer = setTimeout(() => {
+      this.stabilityTimer = null;
+      if (this.conn === conn) {
+        this.attempt = 0;
+        this.keepaliveImmediateRetryUsed = false;
+        this.unauthorizedRetryUsed = false;
+      }
+    }, this.reconnectOpts.stableAfter);
+    timer.unref?.();
+    this.stabilityTimer = timer;
+  }
+  async connectOnce(delayMs, cause) {
+    if (this.closing || this.isClosed()) return;
+    if (delayMs > 0) {
+      this.state = "backoff";
+      this.emit("reconnecting", { attempt: this.attempt, delayMs, cause });
+      await new Promise((resolve) => {
+        this.reconnectTimerResolve = resolve;
+        this.reconnectTimer = setTimeout(resolve, delayMs);
+      });
+      this.reconnectTimer = null;
+      this.reconnectTimerResolve = null;
+      if (this.closing || this.isClosed()) return;
+    }
+    this.state = "dialing";
+    const isProvider = typeof this.opts.token === "function";
+    let attempt;
+    for (; ; ) {
+      attempt = await this.dialAndHandshakeOnce(this.reconnectOpts.connectTimeout);
+      if (attempt.ok || attempt.cancelled) break;
+      if (!this.unauthorizedRetryUsed && isProvider && attempt.unauthorized) {
+        if (this.closing || this.isClosed()) break;
+        this.unauthorizedRetryUsed = true;
+        continue;
+      }
+      break;
+    }
+    if (attempt.ok) {
+      const { conn, welcome } = attempt;
+      if (this.closing || this.isClosed()) {
+        if (this.dialingConn === conn) this.dialingConn = null;
+        conn.fail(new WsMixerError(ErrorCode.NO_ERROR, "client closing"));
+        return;
+      }
+      this.armStabilityTimer(conn);
+      this.everConnected = true;
+      this.dialingConn = null;
+      this.conn = conn;
+      this.state = "connected";
+      if (this.retiringConn && this.retiringConn !== conn) {
+        const old = this.retiringConn;
+        this.retiringConn = null;
+        this.drainReconnectScheduled = false;
+        old.fail(
+          new WsMixerError(ErrorCode.NO_ERROR, "superseded by a new connection"),
+          (streamId) => new StreamError(ErrorCode.CANCEL, streamId, "connection drained")
+        );
+      }
+      this.opts.onConnect?.(welcome);
+      if (this.startResolve) {
+        const resolve = this.startResolve;
+        this.startResolve = null;
+        this.startReject = null;
+        resolve();
+      }
+      return;
+    }
+    if (attempt.cancelled) return;
+    if (attempt.ctx.phase === "dial") {
+      if (this.closing || this.isClosed()) return;
+      if (attempt.fatal) {
+        this.goFatal(attempt.ctx);
+        return;
+      }
+      if (attempt.retryAfterMs !== void 0) {
+        this.reportAndSchedule(attempt.ctx, attempt.ctx.message, () => attempt.retryAfterMs);
+        return;
+      }
+      this.scheduleReconnect(attempt.ctx, attempt.ctx.message);
+      return;
+    }
+    if (attempt.fatal) {
+      this.goFatal(attempt.ctx);
+      return;
+    }
+    if (this.closing || this.isClosed()) return;
+    this.scheduleReconnect(attempt.ctx, "handshake failed: " + attempt.ctx.message);
+  }
+  /**
+   * One dial + handshake attempt: resolves the token provider (fresh, per
+   * CLIENT-SDK.md's "Token provider" row), opens the socket, and -- if that succeeds --
+   * builds a `MixerConn` and waits for `welcome`. Returns a discriminated
+   * result rather than throwing, so connectOnce's retry loop above can
+   * decide what to do with a failure (retry once, or finalize it) without a
+   * second round of reclassifying the same error: `unauthorized` is true for
+   * exactly the two pre-welcome rejection shapes eligible for that retry (an
+   * HTTP 401 on the upgrade, or a handshake-phase UNAUTHORIZED, 4011, with
+   * or without a preceding `error{}`); `cancelled` is true when `close()`
+   * raced the dial/handshake and there is nothing left to report.
+   */
+  async dialAndHandshakeOnce(connectTimeoutMs) {
+    let token;
+    try {
+      token = await resolveToken(this.opts.token);
+    } catch (err) {
+      const e = providerDialError(err);
+      return {
+        ok: false,
+        ctx: { phase: "dial", cause: e.cause, message: e.message },
+        // Fatal by default (CLIENT-SDK.md's "Provider failure" row) -- UNLESS the provider
+        // explicitly marked this as a temporary failure to obtain a token
+        // (TokenUnavailableError, thrown directly or reachable via `cause`),
+        // in which case it's treated exactly like a failed dial: normal
+        // backoff via the ordinary phase-"dial" path below, same as every
+        // other non-auth dial failure.
+        fatal: !isTokenUnavailable(err),
+        unauthorized: false
+      };
+    }
+    let ws;
+    try {
+      ws = await dialWebSocket(this.url, token, this.opts, connectTimeoutMs);
+    } catch (e) {
+      if (this.closing || this.isClosed()) return { ok: false, cancelled: true };
+      const err = e;
+      return {
+        ok: false,
+        ctx: {
+          phase: "dial",
+          httpStatus: err.httpStatus,
+          cause: err.cause,
+          message: err.message,
+          errorCode: err.errorCode,
+          errorName: err.errorCode !== void 0 ? codeName(err.errorCode) : void 0
+        },
+        fatal: err.fatal,
+        // Only an HTTP 401 is eligible for the refresh-retry -- 403/404 are
+        // fatal always, provider or not (dialWebSocket already marks both
+        // `fatal`, this just decides which of them also gets one retry).
+        unauthorized: err.httpStatus === 401,
+        retryAfterMs: err.retryAfterMs
+      };
+    }
+    if (this.closing || this.isClosed()) {
+      try {
+        ws.close(1e3, "client closing");
+      } catch {
+        ws.terminate?.();
+      }
+      return { ok: false, cancelled: true };
+    }
+    const conn = new MixerConn(ws, {
+      token,
+      agent: {
+        sdk: "ws-mixer-js",
+        sdk_version: SDK_VERSION,
+        runtime: `node/${process.version.replace(/^v/, "")}`,
+        os: `${process.platform}/${process.arch}`,
+        ...this.opts.agent
+      },
+      meta: this.opts.meta,
+      window: this.opts.window,
+      maxStreams: this.opts.maxStreams,
+      capabilities: this.opts.capabilities,
+      _timing: this.opts._timing
+    });
+    this.dialingConn = conn;
+    this.wireConn(conn);
+    try {
+      const welcome = await conn.handshake();
+      return { ok: true, conn, welcome };
+    } catch (e) {
+      this.dialingConn = null;
+      const err = e;
+      let wsCode = err.wsCode;
+      let knownErrorCode;
+      if (wsCode === void 0) {
+        knownErrorCode = err.code;
+        wsCode = closeCode(err.code);
+      }
+      const { errorCode, errorName } = deriveErrorCodeName(wsCode, knownErrorCode);
+      return {
+        ok: false,
+        ctx: {
+          phase: "handshake",
+          wsCode,
+          errorCode,
+          errorName,
+          message: err.message,
+          closeReason: err.closeReason
+        },
+        fatal: err.fatal || errorCode === ErrorCode.UNSUPPORTED || errorCode === ErrorCode.UNAUTHORIZED,
+        unauthorized: errorCode === ErrorCode.UNAUTHORIZED
+      };
+    }
+  }
+  wireConn(conn) {
+    conn.on("welcome", (w) => this.emit("welcome", w));
+    conn.on("stream", (s) => {
+      this.emit("stream", s);
+      return this.opts.onStream?.(s);
+    });
+    conn.on("app", (b) => {
+      this.emit("app", b);
+      return this.opts.onApp?.(b);
+    });
+    conn.on("pong", (p) => this.emit("pong", p));
+    conn.on("drain", (d) => {
+      if (this.conn === conn && !this.closing && this.state !== "closed" && !this.drainReconnectScheduled) {
+        if (this.reconnectOpts.maxAttempts > 0) {
+          this.drainReconnectScheduled = true;
+          this.retiringConn = conn;
+          void this.connectOnce(Math.random() * 2e3, "drain");
+        } else {
+          this.drainedNoReconnect = true;
+        }
+      }
+      this.emit("drain", d);
+      return this.opts.onDrain?.({ reason: d.reason, deadlineMs: d.deadline_ms, message: d.message, lastStreamId: d.last_stream_id });
+    });
+    conn.on("error", (err) => {
+      if (this.listenerCount("error") > 0) this.emit("error", err);
+    });
+    conn.on("close", (info) => {
+      const wasActive = this.conn === conn;
+      if (this.conn === conn) this.conn = null;
+      if (this.dialingConn === conn) this.dialingConn = null;
+      if (this.retiringConn === conn) this.retiringConn = null;
+      if (wasActive) this.clearStabilityTimer();
+      if (!wasActive) return;
+      const fatal = info.wsCode !== void 0 && FATAL_WS_CODES.has(info.wsCode);
+      const protocolBug = info.wsCode !== void 0 && PROTOCOL_BUG_WS_CODES.has(info.wsCode);
+      const ctx = protocolBug ? (
+        // errorCode is only set when MixerConn itself detected the failure
+        // (fail()'s teardownConn); a raw WS-level close (onSocketClose)
+        // never carries one, even though wsCode = 4000 + code still tells
+        // us exactly which one it was -- deriveErrorCodeName() derives it
+        // rather than falling back to something less informative than the
+        // wire already told us (PROTOCOL_BUG_WS_CODES is always a bare
+        // ws-mixer code, so this always agrees with `code`/`name` below).
+        (() => {
+          const { errorCode, errorName } = deriveErrorCodeName(info.wsCode, info.errorCode);
+          const code = errorCode;
+          return {
+            phase: "connected",
+            wsCode: info.wsCode,
+            errorCode,
+            errorName,
+            message: info.message,
+            closeReason: info.closeReason,
+            protocolError: true,
+            code,
+            name: codeName(code)
+          };
+        })()
+      ) : {
+        phase: "connected",
+        wsCode: info.wsCode,
+        // Same derivation as the protocolBug branch above: a raw
+        // ws-mixer close with no preceding `error` control frame (e.g.
+        // 4011 from onSocketClose) still tells us exactly which one it
+        // was, so deriveErrorCodeName() fills both errorCode/errorName
+        // from it instead of leaving them undefined just because
+        // MixerConn itself never set one.
+        ...deriveErrorCodeName(info.wsCode, info.errorCode),
+        message: info.message,
+        closeReason: info.closeReason
+      };
+      if (fatal) {
+        this.notifyDisconnect(this.buildPayload(ctx, true));
+        if (this.closing || this.fatal || this.state === "closed") return;
+        this.state = "closed";
+        this.fatal = true;
+        this.closing = true;
+        this.clearReconnectTimer();
+        const err = new WsMixerError(ctx.errorCode ?? ErrorCode.INTERNAL_ERROR, info.message, { fatal: true });
+        if (this.dialingConn && this.dialingConn !== conn) {
+          const dialing = this.dialingConn;
+          this.dialingConn = null;
+          dialing.fail(new WsMixerError(ErrorCode.NO_ERROR, "client closing"));
+        }
+        this.emit("fatal", err);
+        this.rejectStartIfNeverConnected(err);
+        return;
+      }
+      if (this.fatal) {
+        return;
+      }
+      if (this.closing || this.state === "closed") {
+        this.notifyDisconnect(this.buildPayload(ctx, false));
+        return;
+      }
+      if (this.drainedNoReconnect) {
+        this.drainedNoReconnect = false;
+        this.state = "closed";
+        this.fatal = true;
+        this.closing = true;
+        this.clearReconnectTimer();
+        this.notifyDisconnect(this.buildPayload(ctx, true, "drained; reconnect disabled"));
+        const err = new WsMixerError(ctx.errorCode ?? ErrorCode.GOING_AWAY, "drained; reconnect disabled", { fatal: true });
+        if (this.dialingConn && this.dialingConn !== conn) {
+          const dialing = this.dialingConn;
+          this.dialingConn = null;
+          dialing.fail(new WsMixerError(ErrorCode.NO_ERROR, "client closing"));
+        }
+        this.emit("fatal", err);
+        this.rejectStartIfNeverConnected(err);
+        return;
+      }
+      if (this.drainReconnectScheduled) {
+        this.notifyDisconnect(this.buildPayload(ctx, false));
+        this.drainReconnectScheduled = false;
+        return;
+      }
+      if (info.wsCode === GOING_AWAY_WS_CODE || info.wsCode === ABNORMAL_CLOSURE_WS_CODE) {
+        this.reconnectImmediately(ctx, "going_away");
+        return;
+      }
+      if (info.wsCode === KEEPALIVE_TIMEOUT_WS_CODE) {
+        this.scheduleReconnectAfterKeepaliveTimeout(ctx, "keepalive_timeout");
+        return;
+      }
+      if (info.wsCode === ENHANCE_YOUR_CALM_WS_CODE) {
+        this.scheduleReconnectAtCap(ctx, "enhance_your_calm");
+        return;
+      }
+      if (info.wsCode === APPLICATION_CLOSE_WS_CODE) {
+        this.scheduleReconnectAtCap(ctx, "application_close");
+        return;
+      }
+      this.scheduleReconnect(ctx, info.message);
+    });
+  }
+  notifyDisconnect(payload) {
+    this.opts.onDisconnect?.(payload);
+    this.emit("close", payload);
+  }
+  /** Builds the final `DisconnectPayload` for a `DisconnectContext`, filling in `fatal` and, when present, the exhaustion message override. */
+  buildPayload(ctx, fatal, messageOverride) {
+    const base = {
+      phase: ctx.phase,
+      wsCode: ctx.wsCode,
+      errorCode: ctx.errorCode,
+      errorName: ctx.errorName,
+      httpStatus: ctx.httpStatus,
+      cause: ctx.cause,
+      message: messageOverride ?? ctx.message,
+      closeReason: ctx.closeReason,
+      fatal
+    };
+    if (ctx.protocolError) {
+      return { ...base, protocolError: true, code: ctx.code, name: ctx.name };
+    }
+    return { ...base, protocolError: false };
+  }
+  rejectStartIfNeverConnected(err) {
+    if (!this.everConnected && this.startReject) {
+      const reject = this.startReject;
+      this.startResolve = null;
+      this.startReject = null;
+      reject(err);
+    }
+  }
+  /** Fatal per WIRE.md section 2.9: never reconnect, surface loudly, and fail start() if it never got a first connection. One report only. */
+  goFatal(ctx) {
+    if (this.state === "closed") return;
+    this.state = "closed";
+    this.fatal = true;
+    this.closing = true;
+    this.clearReconnectTimer();
+    this.clearStabilityTimer();
+    const conn = this.conn;
+    this.conn = null;
+    const err = new WsMixerError(ctx.errorCode ?? ErrorCode.INTERNAL_ERROR, ctx.message, { fatal: true });
+    if (conn) conn.fail(err);
+    this.emit("fatal", err);
+    this.notifyDisconnect(this.buildPayload(ctx, true));
+    this.rejectStartIfNeverConnected(err);
+  }
+  /**
+   * maxAttempts exhausted: stop, but connect() must reject if it never
+   * succeeded once. Reports exactly one `DisconnectReason` -- the merged
+   * exhaustion report, `fatal: true` with the exhaustion `message`, but
+   * carrying the underlying failure's `wsCode`/`errorCode`/`httpStatus`/
+   * `cause` from `ctx` -- never a second report on top of the one the
+   * failure itself would otherwise have gotten (blocker 1).
+   *
+   * Mirrors goFatal: clears the stability timer too (a live connection can
+   * still have one ticking, e.g. a drain hand-over's parallel dial failing
+   * while the old connection it was replacing is still up), and detaches
+   * every live/in-flight conn -- `conn`, `dialingConn`, `retiringConn`,
+   * which a drain hand-over can leave all pointing at the very same live
+   * connection, hence the reference-dedup below -- before failing it, so
+   * each one's own 'close' handler sees `this.conn`/`this.retiringConn`/
+   * `this.dialingConn` already cleared and produces no report of its own;
+   * this call is still the one report. Without this, an exhausted client
+   * left a still-live socket (and its ping/watchdog timers, and the
+   * now-orphaned stability timer) running past "closed".
+   */
+  giveUp(ctx, message) {
+    if (this.state === "closed") return;
+    this.state = "closed";
+    this.closing = true;
+    this.clearReconnectTimer();
+    this.clearStabilityTimer();
+    const conn = this.conn;
+    const dialing = this.dialingConn;
+    const retiring = this.retiringConn;
+    this.conn = null;
+    this.dialingConn = null;
+    this.retiringConn = null;
+    const err = new WsMixerError(ctx.errorCode ?? ErrorCode.INTERNAL_ERROR, message, { fatal: true });
+    if (conn) conn.fail(err);
+    if (dialing && dialing !== conn) dialing.fail(err);
+    if (retiring && retiring !== conn && retiring !== dialing) retiring.fail(err);
+    this.notifyDisconnect(this.buildPayload(ctx, true, message));
+    this.rejectStartIfNeverConnected(new Error(message));
+  }
+  /**
+   * The single point where a recoverable disconnect either gets its one
+   * report and a scheduled retry, or -- if `maxAttempts` is already
+   * exhausted -- gets folded into `giveUp`'s one merged exhaustion report
+   * instead. Exhaustion is checked *before* any report goes out, which is
+   * what makes "exactly one `DisconnectReason` per disconnect" (blocker 1)
+   * hold: the two outcomes are mutually exclusive, never both.
+   */
+  reportAndSchedule(ctx, cause, computeDelay) {
+    if (this.closing || this.fatal || this.state === "closed") return;
+    if (this.attempt >= this.reconnectOpts.maxAttempts) {
+      this.giveUp(ctx, `max reconnect attempts (${this.reconnectOpts.maxAttempts}) exhausted: ${cause}`);
+      return;
+    }
+    this.notifyDisconnect(this.buildPayload(ctx, false));
+    this.attempt++;
+    const delay = computeDelay();
+    void this.connectOnce(delay, cause);
+  }
+  /**
+   * Close 4012 / close 1001 with no preceding `drain`: reconnect
+   * immediately, jitter random(0, 2000)ms only -- but still counts toward
+   * `attempt`/`maxAttempts`, so a 4012 flap loop (a server stuck
+   * accepting-then-immediately-draining) still respects the ceiling instead
+   * of retrying forever. (The `drain`-triggered parallel reconnect is a
+   * separate, direct connectOnce() call in the `drain` handler above and
+   * does not bump `attempt` -- it is the server telling us to move, not a
+   * failure being retried.)
+   */
+  reconnectImmediately(ctx, cause) {
+    this.reportAndSchedule(ctx, cause, () => Math.random() * 2e3);
+  }
+  /**
+   * Close 4013 KEEPALIVE_TIMEOUT: one immediate attempt, then normal backoff
+   * (WIRE.md section 2.9). The immediate attempt goes through
+   * reportAndSchedule -- same as the 4012 path (reconnectImmediately) -- so
+   * it respects the maxAttempts ceiling too: a 4013 flap loop with no budget
+   * left gives up (one merged `fatal: true` report) instead of dialing a
+   * socket reportAndSchedule would otherwise have refused to allow.
+   *
+   * `keepaliveImmediateRetryUsed` is a once-only budget re-armed ONLY at
+   * stability (armStabilityTimer) -- deliberately never un-set here on the
+   * second (or any later) 4013: doing that would let the budget "spend then
+   * immediately un-spend itself" on the very next 4013, so four 4013s in a
+   * row with no intervening stable connection would go immediate, backoff,
+   * immediate, backoff... forever, instead of immediate once and backoff
+   * every time after that until the client actually goes stable.
+   */
+  scheduleReconnectAfterKeepaliveTimeout(ctx, cause) {
+    if (!this.keepaliveImmediateRetryUsed) {
+      this.keepaliveImmediateRetryUsed = true;
+      this.reportAndSchedule(ctx, cause, () => 0);
+      return;
+    }
+    this.scheduleReconnect(ctx, cause);
+  }
+  /** Close 4009 ENHANCE_YOUR_CALM: start backoff at the cap, not at base. */
+  scheduleReconnectAtCap(ctx, cause) {
+    this.reportAndSchedule(ctx, cause, () => Math.random() * this.reconnectOpts.cap);
+  }
+  /** Normal AWS full-jitter backoff: everything not covered by a more specific rule above. */
+  scheduleReconnect(ctx, cause) {
+    this.reportAndSchedule(ctx, cause, () => fullJitterDelay(this.attempt, this.reconnectOpts.base, this.reconnectOpts.cap));
+  }
+};
+function fullJitterDelay(attempt, base, cap) {
+  const exp = Math.min(cap, base * 2 ** attempt);
+  return Math.random() * exp;
+}
+function dialError(message, fatal, opts) {
+  const err = new Error(message);
+  err.fatal = fatal;
+  if (opts?.errorCode !== void 0) err.errorCode = opts.errorCode;
+  if (opts?.retryAfterMs !== void 0) err.retryAfterMs = opts.retryAfterMs;
+  if (opts?.httpStatus !== void 0) err.httpStatus = opts.httpStatus;
+  if (opts?.cause !== void 0) err.cause = opts.cause;
+  return err;
+}
+function providerDialError(err) {
+  let message;
+  try {
+    message = err instanceof Error ? err.message : String(err);
+  } catch {
+    message = "token provider failed";
+  }
+  return dialError(
+    message,
+    /* overridden by dialAndHandshakeOnce's isTokenUnavailable check */
+    true,
+    { cause: err }
+  );
+}
+var MAX_CAUSE_CHAIN_DEPTH = 10;
+function isTokenUnavailable(err) {
+  const seen = /* @__PURE__ */ new Set();
+  let cur = err;
+  for (let depth = 0; depth < MAX_CAUSE_CHAIN_DEPTH && cur != null && !seen.has(cur); depth++) {
+    if (cur instanceof TokenUnavailableError) return true;
+    seen.add(cur);
+    try {
+      cur = cur instanceof Error ? cur.cause : void 0;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function parseRetryAfter(value) {
+  const v = Array.isArray(value) ? value[0] : value;
+  if (v === void 0) return void 0;
+  const seconds = Number(v);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const dateMs = Date.parse(v);
+  if (!Number.isNaN(dateMs)) return Math.max(0, dateMs - Date.now());
+  return void 0;
+}
+function defaultWsFactory(url, protocols, options) {
+  return new WebSocket(url, protocols, options);
+}
+function dialWebSocket(url, token, opts, connectTimeoutMs) {
+  return new Promise((resolve, reject) => {
+    const factory = opts._wsFactory ?? defaultWsFactory;
+    const ws = factory(url, [SUBPROTOCOL], {
+      perMessageDeflate: false,
+      maxPayload: MAX_MESSAGE_SIZE,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "User-Agent": `ws-mixer-js/${SDK_VERSION} (node/${process.version.replace(/^v/, "")} ${process.platform}/${process.arch})`,
+        ...opts.headers
+      }
+    });
+    const timer = setTimeout(() => {
+      ws.terminate?.();
+      reject(dialError(`connect timed out after ${connectTimeoutMs}ms`, false));
+    }, connectTimeoutMs);
+    let settled = false;
+    ws.once("unexpected-response", (req, res) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        res?.resume?.();
+        req?.destroy?.();
+        res?.destroy?.();
+        ws.terminate?.();
+        const status = res?.statusCode;
+        if (status === 429) {
+          reject(
+            dialError(`HTTP 429 (rate limited) during handshake`, false, {
+              retryAfterMs: parseRetryAfter(res?.headers?.["retry-after"]),
+              httpStatus: 429
+            })
+          );
+          return;
+        }
+        if (status === 401 || status === 403) {
+          reject(
+            dialError(`unexpected HTTP response during handshake: ${status}`, true, {
+              httpStatus: status
+            })
+          );
+          return;
+        }
+        if (status === 404) {
+          reject(dialError(`unexpected HTTP response during handshake: ${status}`, true, { httpStatus: status }));
+          return;
+        }
+        reject(dialError(`unexpected HTTP response during handshake: ${status}`, false, { httpStatus: status }));
+      } catch (e) {
+        reject(dialError(e instanceof Error ? e.message : String(e), false));
+      }
+    });
+    ws.once("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(dialError(err.message, false));
+    });
+    ws.once("open", () => {
+      if (settled) return;
+      if (ws.protocol !== SUBPROTOCOL) {
+        settled = true;
+        clearTimeout(timer);
+        ws.close(1002);
+        reject(
+          dialError(`server did not echo the ${SUBPROTOCOL} subprotocol; failing fatally, do not retry`, true, {
+            errorCode: ErrorCode.UNSUPPORTED
+          })
+        );
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve(ws);
+    });
+  });
+}
+async function connect(url, opts) {
+  const client = new MixerClient(url, opts);
+  await client.start();
+  return client;
+}
+export {
+  ConnError,
+  ErrorCode,
+  FrameType,
+  MAX_CHUNK,
+  MAX_MESSAGE_SIZE,
+  MAX_SEND_WINDOW,
+  MAX_STREAM_ZERO_PAYLOAD,
+  MixerClient,
+  MixerConn,
+  MixerStream,
+  SDK_VERSION,
+  SUBPROTOCOL,
+  StreamError,
+  TokenUnavailableError,
+  WsMixerError,
+  closeCode,
+  codeName,
+  connect,
+  decodeFrame,
+  encodeClose,
+  encodeControl,
+  encodeData,
+  encodeFrame,
+  encodeOpen,
+  encodeReset,
+  encodeWindow,
+  frameTypeName,
+  fullJitterDelay,
+  knownDrainReason,
+  parseControl,
+  parseErrorCode,
+  resetCode,
+  resetMessage,
+  windowIncrement
+};
+//# sourceMappingURL=index.js.map