@emeryld/rrroutes-client 2.0.10 → 2.0.12

package/dist/index.cjs

@@ -32,6 +32,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SocketClient: () => SocketClient,
+  buildRoomPayloadSchema: () => buildRoomPayloadSchema,
   buildSocketProvider: () => buildSocketProvider,
   createRouteClient: () => createRouteClient,
   defaultFetcher: () => defaultFetcher
@@ -462,6 +463,14 @@ function toFormData(body) {
   return fd;
 }
 
+// src/sockets/socket.client.sys.ts
+var import_zod = require("zod");
+var roomValueSchema = import_zod.z.union([import_zod.z.array(import_zod.z.string()), import_zod.z.string()]);
+var buildRoomPayloadSchema = (metaSchema) => import_zod.z.object({
+  rooms: roomValueSchema,
+  meta: metaSchema
+});
+
 // src/sockets/socket.client.context.tsx
 var React = __toESM(require("react"), 1);
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -487,7 +496,7 @@ function buildSocketProvider(args) {
   };
 }
 function SocketProvider(props) {
-  const { events, baseOptions, children, fallback, providerDebug } = props;
+  const { events, baseOptions, children, fallback, providerDebug, destroyLeaveMeta } = props;
   const [resolvedSocket, setResolvedSocket] = React.useState(null);
   const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
   React.useEffect(() => {
@@ -527,7 +536,7 @@ function SocketProvider(props) {
   React.useEffect(() => {
     return () => {
       if (client) {
-        client.destroy();
+        client.destroy(destroyLeaveMeta);
         dbg(providerDebug, { type: "client", phase: "destroy" });
       }
     };
@@ -552,11 +561,11 @@ function useSocketConnection(args) {
     [rooms]
   );
   React.useEffect(() => {
-    if (autoJoin && normalizedRooms.length > 0) client.joinRooms(normalizedRooms);
+    if (autoJoin && normalizedRooms.length > 0) client.joinRooms(normalizedRooms, args.joinMeta);
     const unsubscribe = client.on(event, onMessage);
     return () => {
       unsubscribe();
-      if (autoLeave && normalizedRooms.length > 0) client.leaveRooms(normalizedRooms);
+      if (autoLeave && normalizedRooms.length > 0) client.leaveRooms(normalizedRooms, args.leaveMeta);
       if (onCleanup) onCleanup();
     };
   }, args.deps ?? [client, event, onMessage, autoJoin, autoLeave, ...normalizedRooms]);
@@ -573,151 +582,145 @@ var SocketClient = class {
     this.socket = opts.socket ?? null;
     this.environment = opts.environment ?? "development";
     this.debug = opts.debug ?? {};
-    this.sysEvents = opts.sys ?? {};
+    this.config = opts.config;
+    this.sysEvents = opts.sys;
+    this.roomJoinSchema = buildRoomPayloadSchema(this.config.joinMetaMessage);
+    this.roomLeaveSchema = buildRoomPayloadSchema(this.config.leaveMetaMessage);
     const hb = opts.heartbeat ?? {};
     this.hb = {
       intervalMs: hb.intervalMs ?? 15e3,
-      timeoutMs: hb.timeoutMs ?? 7500,
-      onPong: hb.onPong
+      timeoutMs: hb.timeoutMs ?? 7500
     };
+    this.dbg({
+      type: "lifecycle",
+      phase: "init_start",
+      socketId: this.socket?.id ?? void 0,
+      details: {
+        environment: this.environment
+      }
+    });
+    if (!this.socket) {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init_socket_missing",
+        err: "Socket reference is null during initialization"
+      });
+    } else {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init_ready",
+        socketId: this.socket.id,
+        details: {
+          heartbeatIntervalMs: this.hb.intervalMs,
+          heartbeatTimeoutMs: this.hb.timeoutMs
+        }
+      });
+      this.logSocketConfigSnapshot("init", "constructor");
+    }
     this.onConnect = () => {
-      const sys = this.getSysEvent("sys:connect");
-      const defaultHandler = () => {
-        this.dbg({
-          type: "connection",
-          phase: "connect",
-          id: this.socket?.id ?? ""
-        });
-        this.startHeartbeat();
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:connect",
-          phase: "connect",
-          socket: this.socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
-        });
-      } else {
-        defaultHandler();
+      if (!this.socket) {
+        this.dbg({ type: "connection", phase: "connect", err: "Socket is null" });
+        throw new Error("Socket is null in onConnect handler");
       }
+      this.dbg({
+        type: "connection",
+        phase: "connect",
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
+        }
+      });
+      this.logSocketConfigSnapshot("update", "connect_event");
+      this.getSysEvent("sys:connect")({
+        socket: this.socket,
+        client: this
+      });
     };
     this.onReconnect = (attempt) => {
-      const sys = this.getSysEvent("sys:reconnect");
-      const defaultHandler = () => {
-        this.dbg({
-          type: "connection",
-          phase: "reconnect",
-          attempt
-        });
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:reconnect",
-          phase: "reconnect",
-          attempt,
-          socket: this.socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
-        });
-      } else {
-        defaultHandler();
+      if (!this.socket) {
+        this.dbg({ type: "connection", phase: "reconnect", err: "Socket is null" });
+        throw new Error("Socket is null in onReconnect handler");
       }
+      this.dbg({
+        type: "connection",
+        phase: "reconnect",
+        attempt,
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
+        }
+      });
+      this.logSocketConfigSnapshot("update", "reconnect_event");
+      this.getSysEvent("sys:reconnect")({
+        attempt,
+        socket: this.socket,
+        client: this
+      });
     };
     this.onDisconnect = (reason) => {
-      const sys = this.getSysEvent("sys:disconnect");
-      const defaultHandler = () => {
-        this.dbg({
-          type: "connection",
-          phase: "disconnect",
-          reason: String(reason)
-        });
-        this.stopHeartbeat();
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:disconnect",
-          phase: "disconnect",
-          reason: String(reason),
-          socket: this.socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
-        });
-      } else {
-        defaultHandler();
+      if (!this.socket) {
+        this.dbg({ type: "connection", phase: "disconnect", err: "Socket is null" });
+        throw new Error("Socket is null in onDisconnect handler");
       }
+      this.dbg({
+        type: "connection",
+        phase: "disconnect",
+        reason: String(reason),
+        details: {
+          roomsTracked: this.roomCounts.size
+        }
+      });
+      this.logSocketConfigSnapshot("update", "disconnect_event");
+      this.getSysEvent("sys:disconnect")({
+        reason: String(reason),
+        socket: this.socket,
+        client: this
+      });
     };
     this.onConnectError = (err) => {
-      const sys = this.getSysEvent("sys:connect_error");
-      const defaultHandler = () => {
-        this.dbg({
-          type: "connection",
-          phase: "connect_error",
-          err: String(err)
-        });
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:connect_error",
-          phase: "connect_error",
-          error: err,
-          socket: this.socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
-        });
-      } else {
-        defaultHandler();
+      if (!this.socket) {
+        this.dbg({ type: "connection", phase: "connect_error", err: "Socket is null" });
+        throw new Error("Socket is null in onConnectError handler");
       }
+      this.dbg({
+        type: "connection",
+        phase: "connect_error",
+        err: String(err),
+        details: this.getVerboseDetails({ rawError: err })
+      });
+      this.logSocketConfigSnapshot("update", "connect_error_event");
+      this.getSysEvent("sys:connect_error")({
+        error: String(err),
+        socket: this.socket,
+        client: this
+      });
     };
     this.onPong = (raw) => {
-      const sys = this.getSysEvent("sys:pong");
-      const schema = sys?.message;
-      let validated = raw;
-      if (schema) {
-        const ok = schema.safeParse(raw);
-        if (!ok.success) return;
-        validated = ok.data;
+      if (!this.socket) {
+        this.dbg({ type: "heartbeat", action: "pong_recv", err: "Socket is null" });
+        throw new Error("Socket is null in onPong handler");
       }
-      const receivedAt = Date.now();
-      const clientSentIso = validated?.clientEcho?.__clientSentAt;
-      let latencyMs;
-      if (clientSentIso) {
-        const sent = Date.parse(clientSentIso);
-        if (!Number.isNaN(sent)) latencyMs = Math.max(0, receivedAt - sent);
-      }
-      const latency = latencyMs ?? validated?.sinceMs ?? 0;
-      const defaultHandler = () => {
+      const parsed = this.config.pongPayload.safeParse(raw);
+      if (!parsed.success) {
         this.dbg({
           type: "heartbeat",
-          action: "pong_recv",
-          latencyMs: latency,
-          payload: validated
-        });
-        if (this.hb.onPong) {
-          this.hb.onPong({
-            latencyMs: latency,
-            payload: validated,
-            socket: this.socket
-          });
-        }
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:pong",
-          socket: this.socket,
-          raw: validated,
-          latencyMs: latency,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
+          action: "validation_failed",
+          err: `pong payload validation failed: ${parsed.error.message}`,
+          details: this.getValidationDetails(parsed.error)
         });
-      } else {
-        defaultHandler();
+        return;
       }
+      const validated = parsed.data;
+      this.dbg({
+        type: "heartbeat",
+        action: "pong_recv",
+        payload: validated
+      });
+      this.getSysEvent("sys:pong")({
+        socket: this.socket,
+        payload: validated,
+        client: this
+      });
     };
     if (this.socket) {
       this.socket.on("connect", this.onConnect);
@@ -727,6 +730,61 @@ var SocketClient = class {
       this.socket.on("sys:pong", this.onPong);
     }
   }
+  snapshotSocketConfig(socket) {
+    if (!socket) return null;
+    const manager = socket.io ?? null;
+    const base = {
+      nsp: this.getNamespace(socket)
+    };
+    if (!manager) return base;
+    const opts = manager.opts ?? {};
+    const transports = Array.isArray(opts.transports) ? opts.transports.filter((t) => typeof t === "string") : void 0;
+    const transportName = typeof manager.engine?.transport?.name === "string" ? manager.engine.transport?.name : void 0;
+    const readyState = typeof manager._readyState === "string" ? manager._readyState : void 0;
+    const uri = typeof manager.uri === "string" ? manager.uri : void 0;
+    return {
+      ...base,
+      url: uri,
+      path: typeof opts.path === "string" ? opts.path : void 0,
+      transport: transportName ?? transports?.[0],
+      transports,
+      readyState,
+      autoConnect: typeof opts.autoConnect === "boolean" ? opts.autoConnect : void 0,
+      reconnection: typeof opts.reconnection === "boolean" ? opts.reconnection : void 0,
+      reconnectionAttempts: typeof opts.reconnectionAttempts === "number" ? opts.reconnectionAttempts : void 0,
+      reconnectionDelay: typeof opts.reconnectionDelay === "number" ? opts.reconnectionDelay : void 0,
+      reconnectionDelayMax: typeof opts.reconnectionDelayMax === "number" ? opts.reconnectionDelayMax : void 0,
+      timeout: typeof opts.timeout === "number" ? opts.timeout : void 0,
+      hostname: typeof opts.hostname === "string" ? opts.hostname : void 0,
+      port: typeof opts.port === "number" || typeof opts.port === "string" ? opts.port : void 0,
+      secure: typeof opts.secure === "boolean" ? opts.secure : void 0
+    };
+  }
+  logSocketConfigSnapshot(phase, reason) {
+    if (!this.debug.logger || !this.debug.config) return;
+    const snapshot = this.snapshotSocketConfig(this.socket);
+    this.dbg({
+      type: "config",
+      phase,
+      reason,
+      socketId: this.socket?.id,
+      snapshot: snapshot ?? void 0,
+      err: snapshot ? void 0 : "Socket unavailable for config snapshot"
+    });
+  }
+  getValidationDetails(error) {
+    if (!this.debug.verbose) return void 0;
+    return { issues: error.issues };
+  }
+  getVerboseDetails(details) {
+    if (!this.debug.verbose) return void 0;
+    return details;
+  }
+  getNamespace(socket) {
+    if (!socket) return void 0;
+    const nsp = socket.nsp;
+    return typeof nsp === "string" ? nsp : void 0;
+  }
   getSysEvent(name) {
     return this.sysEvents[name];
   }
@@ -754,6 +812,20 @@ var SocketClient = class {
   toArray(rooms) {
     return rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms];
   }
+  rollbackJoinIncrement(rooms) {
+    for (const room of rooms) {
+      const curr = this.roomCounts.get(room) ?? 0;
+      const next = Math.max(0, curr - 1);
+      if (next === 0) this.roomCounts.delete(room);
+      else this.roomCounts.set(room, next);
+    }
+  }
+  rollbackLeaveDecrement(rooms) {
+    for (const room of rooms) {
+      const curr = this.roomCounts.get(room) ?? 0;
+      this.roomCounts.set(room, curr + 1);
+    }
+  }
   /**
    * Public: start the heartbeat loop manually.
    *
@@ -762,55 +834,56 @@ var SocketClient = class {
    */
   startHeartbeat() {
     this.stopHeartbeat();
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "heartbeat",
+        action: "start",
+        err: "Socket is null"
+      });
+      return;
+    }
     const socket = this.socket;
+    this.dbg({
+      type: "heartbeat",
+      action: "start",
+      details: {
+        intervalMs: this.hb.intervalMs,
+        timeoutMs: this.hb.timeoutMs
+      }
+    });
     const tick = () => {
-      if (!socket) return;
-      const sysPing = this.getSysEvent("sys:ping");
-      const schema = sysPing?.message;
-      const buildDefaultPayload = () => ({
-        clientEcho: { __clientSentAt: (/* @__PURE__ */ new Date()).toISOString() }
-      });
-      const send = (payload) => {
-        let dataToSend = payload;
-        if (schema) {
-          const check = schema.safeParse(payload);
-          if (!check.success) {
-            if (this.environment === "development") {
-              console.warn("[socket] ping schema validation failed", check.error.issues);
-            }
-            return;
-          }
-          dataToSend = check.data;
-        }
-        const timer = setTimeout(() => {
-        }, this.hb.timeoutMs);
-        socket.timeout(this.hb.timeoutMs).emit("sys:ping", dataToSend, () => {
-          clearTimeout(timer);
-        });
+      if (!socket) {
         this.dbg({
           type: "heartbeat",
-          action: "ping_emit",
-          payload: dataToSend
+          action: "tick_skip",
+          err: "Socket missing during heartbeat tick"
         });
-      };
-      const defaultHandler = () => {
-        const payload = buildDefaultPayload();
-        send(payload);
-      };
-      if (sysPing?.sysHandler) {
-        sysPing.sysHandler({
-          name: "sys:ping",
-          socket,
-          buildDefaultPayload,
-          send,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
+        return;
+      }
+      const payload = this.getSysEvent("sys:ping")({
+        socket,
+        client: this
+      });
+      const check = this.config.pingPayload.safeParse(payload);
+      if (!check.success) {
+        this.dbg({
+          type: "heartbeat",
+          action: "validation_failed",
+          err: "ping payload validation failed",
+          details: this.getValidationDetails(check.error)
         });
-      } else {
-        defaultHandler();
+        if (this.environment === "development") {
+          console.warn("[socket] ping schema validation failed", check.error.issues);
+        }
+        return;
       }
+      const dataToSend = check.data;
+      socket.emit("sys:ping", dataToSend);
+      this.dbg({
+        type: "heartbeat",
+        action: "ping_emit",
+        payload: dataToSend
+      });
     };
     this.hbTimer = setInterval(tick, this.hb.intervalMs);
     tick();
@@ -822,38 +895,56 @@ var SocketClient = class {
    * call it yourself from any sysHandler to fully control heartbeat lifecycle.
    */
   stopHeartbeat() {
+    const hadTimer = Boolean(this.hbTimer);
     if (this.hbTimer) {
       clearInterval(this.hbTimer);
       this.hbTimer = null;
     }
+    this.dbg({
+      type: "heartbeat",
+      action: "stop",
+      details: {
+        hadTimer
+      }
+    });
   }
-  emit(event, payload, metadata, onAck, timeoutMs) {
-    const schema = this.events[event].message;
-    const parsed = schema.safeParse(payload);
-    if (!parsed.success) throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
+  emit(event, payload, metadata) {
     if (!this.socket) {
-      if (this.environment === "development") {
-        console.warn(`[socket] emit("${String(event)}") skipped because socket is null`);
-      }
+      this.dbg({ type: "emit", event, err: "Socket is null" });
       return;
     }
-    if (onAck) {
-      this.socket.timeout(timeoutMs ?? this.hb.timeoutMs).emit(String(event), parsed.data, (ack) => {
-        try {
-          onAck(ack);
-        } catch {
-        }
+    const schema = this.events[event].message;
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      this.dbg({
+        type: "emit",
+        event,
+        err: "payload_validation_failed",
+        details: this.getValidationDetails(parsed.error)
       });
-    } else {
-      this.socket.emit(String(event), parsed.data);
+      throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
     }
+    this.socket.emit(String(event), parsed.data);
     this.dbg({
       type: "emit",
       event,
-      metadata: this.debug.verbose ? metadata : void 0
+      metadata
     });
   }
-  joinRooms(rooms) {
+  joinRooms(rooms, meta) {
+    if (!this.socket) {
+      this.dbg({ type: "room", action: "join", rooms: this.toArray(rooms), err: "Socket is null" });
+      throw new Error("Socket is null in joinRooms method");
+    }
+    if (!this.getSysEvent("sys:room_join")({
+      rooms,
+      meta,
+      socket: this.socket,
+      client: this
+    })) {
+      this.dbg({ type: "room", action: "join", rooms: this.toArray(rooms), err: "sys:room_join handler aborted join" });
+      return;
+    }
     const list = this.toArray(rooms);
     const toJoin = [];
     for (const r of list) {
@@ -862,27 +953,41 @@ var SocketClient = class {
       if (next === 1) toJoin.push(r);
     }
     if (toJoin.length > 0 && this.socket) {
-      const socket = this.socket;
-      const sys = this.getSysEvent("sys:room_join");
-      const defaultHandler = () => {
-        socket.emit("sys:room_join", { rooms: toJoin });
-        this.dbg({ type: "room", action: "join", rooms: toJoin });
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:room_join",
+      const payloadResult = this.roomJoinSchema.safeParse({
+        rooms: toJoin,
+        meta
+      });
+      if (!payloadResult.success) {
+        this.rollbackJoinIncrement(toJoin);
+        this.dbg({
+          type: "room",
+          action: "join",
           rooms: toJoin,
-          socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
         });
-      } else {
-        defaultHandler();
+        return;
       }
+      const payload = payloadResult.data;
+      const normalizedRooms = this.toArray(payload.rooms);
+      this.socket.emit("sys:room_join", payload);
+      this.dbg({ type: "room", action: "join", rooms: normalizedRooms });
     }
   }
-  leaveRooms(rooms) {
+  leaveRooms(rooms, meta) {
+    if (!this.socket) {
+      this.dbg({ type: "room", action: "leave", rooms: this.toArray(rooms), err: "Socket is null" });
+      throw new Error("Socket is null in leaveRooms method");
+    }
+    if (!this.getSysEvent("sys:room_leave")({
+      rooms,
+      meta,
+      socket: this.socket,
+      client: this
+    })) {
+      this.dbg({ type: "room", action: "leave", rooms: this.toArray(rooms), err: "sys:room_leave handler aborted leave" });
+      return;
+    }
     const list = this.toArray(rooms);
     const toLeave = [];
     for (const r of list) {
@@ -893,42 +998,49 @@ var SocketClient = class {
       else this.roomCounts.set(r, next);
     }
     if (toLeave.length > 0 && this.socket) {
-      const socket = this.socket;
-      const sys = this.getSysEvent("sys:room_leave");
-      const defaultHandler = () => {
-        socket.emit("sys:room_leave", { rooms: toLeave });
-        this.dbg({ type: "room", action: "leave", rooms: toLeave });
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:room_leave",
+      const payloadResult = this.roomLeaveSchema.safeParse({
+        rooms: toLeave,
+        meta
+      });
+      if (!payloadResult.success) {
+        this.rollbackLeaveDecrement(toLeave);
+        this.dbg({
+          type: "room",
+          action: "leave",
           rooms: toLeave,
-          socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
         });
-      } else {
-        defaultHandler();
+        return;
       }
+      const payload = payloadResult.data;
+      const normalizedRooms = this.toArray(payload.rooms);
+      this.socket.emit("sys:room_leave", payload);
+      this.dbg({ type: "room", action: "leave", rooms: normalizedRooms });
     }
   }
   on(event, handler) {
     const schema = this.events[event].message;
     this.dbg({ type: "register", action: "register", event });
     if (!this.socket) {
-      if (this.environment === "development") {
-        console.warn(`[socket] on("${String(event)}") skipped because socket is null`);
-      }
+      this.dbg({ type: "register", action: "register", event, err: "Socket is null" });
       return () => {
       };
     }
     const socket = this.socket;
-    const wrapped = (envelopeOrRaw, maybeAck) => {
+    const wrapped = (envelopeOrRaw) => {
       const maybeEnvelope = envelopeOrRaw;
       const rawData = maybeEnvelope?.data ?? maybeEnvelope;
       const parsed = schema.safeParse(rawData);
-      if (!parsed.success) return;
+      if (!parsed.success) {
+        this.dbg({
+          type: "receive",
+          event,
+          err: "payload_validation_failed",
+          details: this.getValidationDetails(parsed.error)
+        });
+        return;
+      }
       const receivedAt = /* @__PURE__ */ new Date();
       const sentAt = maybeEnvelope?.sentAt ? new Date(maybeEnvelope.sentAt) : void 0;
       const meta = {
@@ -942,15 +1054,9 @@ var SocketClient = class {
         ctx: {
           receivedAt,
           latencyMs: sentAt ? Math.max(0, receivedAt.getTime() - sentAt.getTime()) : void 0,
-          nsp: socket.nsp,
+          nsp: this.getNamespace(socket),
           socketId: socket.id,
-          socket,
-          reply: typeof maybeAck === "function" ? (d) => {
-            try {
-              maybeAck(d);
-            } catch {
-            }
-          } : void 0
+          socket
         }
       };
       this.dbg({
@@ -966,9 +1072,7 @@ var SocketClient = class {
       handler(parsed.data, meta);
     };
     const errorWrapped = (e) => {
-      if (this.environment === "development") {
-        console.warn(`[socket] ${String(event)}:error`, e);
-      }
+      this.dbg({ type: "receive", event, err: String(e) });
     };
     socket.on(String(event), wrapped);
     socket.on(`${String(event)}:error`, errorWrapped);
@@ -994,9 +1098,18 @@ var SocketClient = class {
    * Remove all listeners, stop timers, and leave rooms.
    * Call when disposing the client instance.
    */
-  destroy() {
+  destroy(leaveMeta) {
     this.stopHeartbeat();
     const socket = this.socket;
+    this.dbg({
+      type: "lifecycle",
+      phase: "destroy_begin",
+      socketId: socket?.id,
+      details: {
+        roomsTracked: this.roomCounts.size,
+        handlerEvents: this.handlerMap.size
+      }
+    });
     if (socket) {
       socket.off("connect", this.onConnect);
       socket.off("reconnect", this.onReconnect);
@@ -1013,42 +1126,67 @@ var SocketClient = class {
     this.handlerMap.clear();
     const toLeave = Array.from(this.roomCounts.entries()).filter(([, count]) => count > 0).map(([room]) => room);
     if (toLeave.length > 0 && socket) {
-      const sys = this.getSysEvent("sys:room_leave");
-      const defaultHandler = () => {
-        socket.emit("sys:room_leave", { rooms: toLeave });
-        this.dbg({ type: "room", action: "leave", rooms: toLeave });
-      };
-      if (sys?.sysHandler) {
-        sys.sysHandler({
-          name: "sys:room_leave",
-          rooms: toLeave,
-          socket,
-          next: defaultHandler,
-          startHeartbeat: () => this.startHeartbeat(),
-          stopHeartbeat: () => this.stopHeartbeat()
-        });
-      } else {
-        defaultHandler();
-      }
+      this.leaveRooms(toLeave, leaveMeta);
     }
     this.roomCounts.clear();
+    this.dbg({
+      type: "lifecycle",
+      phase: "destroy_complete",
+      socketId: socket?.id,
+      details: {
+        roomsTracked: this.roomCounts.size,
+        handlerEvents: this.handlerMap.size
+      }
+    });
   }
   /** Pass-throughs. Managing connection is the caller’s responsibility. */
   disconnect() {
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "connection",
+        phase: "disconnect",
+        reason: "client_disconnect",
+        err: "Socket is null"
+      });
+      return;
+    }
     this.stopHeartbeat();
     this.socket.disconnect();
-    this.dbg({ type: "connection", phase: "disconnect", reason: "client_disconnect" });
+    this.dbg({
+      type: "connection",
+      phase: "disconnect",
+      reason: "client_disconnect",
+      details: {
+        nsp: this.getNamespace(this.socket)
+      }
+    });
+    this.logSocketConfigSnapshot("update", "disconnect_call");
   }
   connect() {
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "connection",
+        phase: "connect",
+        err: "Socket is null"
+      });
+      return;
+    }
     this.socket.connect();
-    this.dbg({ type: "connection", phase: "connect", id: this.socket.id ?? "" });
+    this.dbg({
+      type: "connection",
+      phase: "connect",
+      id: this.socket.id ?? "",
+      details: {
+        nsp: this.getNamespace(this.socket)
+      }
+    });
+    this.logSocketConfigSnapshot("update", "connect_call");
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SocketClient,
+  buildRoomPayloadSchema,
   buildSocketProvider,
   createRouteClient,
   defaultFetcher