@emeryld/rrroutes-client 2.6.3 → 2.6.4

package/dist/index.cjs

@@ -1339,1355 +1339,1369 @@ var buildRoomPayloadSchema = (metaSchema) => import_zod.z.object({
   meta: metaSchema
 });
 
-// src/sockets/socket.client.context.tsx
-var React = __toESM(require("react"), 1);
-var import_jsx_runtime = require("react/jsx-runtime");
-var SocketCtx = React.createContext(null);
-function dbg(dbgOpts, e) {
-  if (!dbgOpts?.logger) return;
-  if (!dbgOpts[e.type]) return;
-  dbgOpts.logger(e);
-}
-function isProbablySocket(value) {
-  if (!value || typeof value !== "object") return false;
-  const anyVal = value;
-  const ctorName = anyVal.constructor?.name;
-  if (ctorName === "Socket") return true;
-  return ("connected" in anyVal || "recovered" in anyVal) && typeof anyVal.on === "function" && typeof anyVal.emit === "function";
-}
-function describeSocketLike(value) {
-  if (!value) return null;
-  const id = value.id ?? "unknown";
-  const connected = value.connected ?? false;
-  const recovered = typeof value.recovered === "boolean" ? ` recovered=${value.recovered}` : "";
-  return `[Socket id=${id} connected=${connected}${recovered}]`;
-}
-function safeDescribeHookValue(value) {
-  if (value == null) return value;
-  const valueType = typeof value;
-  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
-    return value;
-  }
-  if (valueType === "bigint" || valueType === "symbol") return String(value);
-  if (valueType === "function")
-    return `[function ${value.name || "anonymous"}]`;
-  if (Array.isArray(value)) return `[array length=${value.length}]`;
-  if (isProbablySocket(value)) {
-    return describeSocketLike(value);
-  }
-  const ctorName = value.constructor?.name ?? "object";
-  const keys = Object.keys(value);
-  const keyPreview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  return `[${ctorName} keys=${keyPreview}${suffix}]`;
-}
-function summarizeEvents(events) {
-  if (!events || typeof events !== "object")
-    return safeDescribeHookValue(events);
-  const keys = Object.keys(events);
-  if (!keys.length) return "[events empty]";
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  return `[events count=${keys.length} keys=${preview}${suffix}]`;
-}
-function summarizeBaseOptions(options) {
-  if (!options || typeof options !== "object")
-    return safeDescribeHookValue(options);
-  const obj = options;
-  const keys = Object.keys(obj);
-  if (!keys.length) return "[baseOptions empty]";
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  const hasDebug = "debug" in obj;
-  return `[baseOptions keys=${preview}${suffix} debug=${hasDebug}]`;
-}
-function summarizeMeta(meta, label) {
-  if (meta == null) return null;
-  if (typeof meta !== "object") return safeDescribeHookValue(meta);
-  const keys = Object.keys(meta);
-  if (!keys.length) return `[${label} empty]`;
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  return `[${label} keys=${preview}${suffix}]`;
-}
-function createHookDebugEvent(prev, next, hook) {
-  const reason = prev ? "change" : "init";
-  const changed = Object.keys(next).reduce((acc, dependency) => {
-    const prevValue = prev ? prev[dependency] : void 0;
-    const nextValue = next[dependency];
-    if (!prev || !Object.is(prevValue, nextValue)) {
-      acc.push({
-        dependency,
-        previous: safeDescribeHookValue(prevValue),
-        next: safeDescribeHookValue(nextValue)
+// src/sockets/socket.client.core.ts
+var SocketClient = class {
+  constructor(events, opts) {
+    this.hbTimer = null;
+    // stats
+    this.roomCounts = /* @__PURE__ */ new Map();
+    this.handlerMap = /* @__PURE__ */ new Map();
+    this.events = events;
+    this.socket = opts.socket ?? null;
+    this.environment = opts.environment ?? "development";
+    this.debug = opts.debug ?? {};
+    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
+    };
+    if (!this.socket) {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init",
+        err: "Socket reference is null during initialization"
+      });
+    } else {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init",
+        heartbeatIntervalMs: this.hb.intervalMs,
+        heartbeatTimeoutMs: this.hb.timeoutMs,
+        environment: this.environment
       });
+      this.logSocketConfigSnapshot("constructor");
     }
-    return acc;
-  }, []);
-  if (!changed.length) return null;
-  return { type: "hook", phase: hook, reason, changes: changed };
-}
-function trackHookTrigger({
-  ref,
-  hook,
-  providerDebug,
-  snapshot
-}) {
-  const prev = ref.current;
-  ref.current = snapshot;
-  if (!providerDebug?.logger || !providerDebug?.hook) return;
-  const event = createHookDebugEvent(prev, snapshot, hook);
-  if (event) dbg(providerDebug, event);
-}
-function buildSocketProvider(args) {
-  const { events, options: baseOptions } = args;
-  return {
-    SocketProvider: (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-      SocketProvider,
-      {
-        events,
-        baseOptions,
-        providerDebug: baseOptions.debug,
-        ...props
-      }
-    ),
-    useSocketClient: () => useSocketClient(),
-    useSocketConnection: (p) => useSocketConnection(p)
-  };
-}
-function SocketProvider(props) {
-  const {
-    events,
-    baseOptions,
-    children,
-    fallback,
-    providerDebug,
-    destroyLeaveMeta
-  } = props;
-  const [resolvedSocket, setResolvedSocket] = React.useState(
-    null
-  );
-  const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
-  const providerDebugRef = React.useRef();
-  providerDebugRef.current = providerDebug;
-  const resolveEffectDebugRef = React.useRef(null);
-  const clientMemoDebugRef = React.useRef(null);
-  const destroyEffectDebugRef = React.useRef(null);
-  React.useEffect(() => {
-    trackHookTrigger({
-      ref: resolveEffectDebugRef,
-      hook: "resolve_effect",
-      providerDebug: providerDebugRef.current,
-      snapshot: {
-        resolvedSocket: describeSocketLike(resolvedSocket)
+    this.onConnect = async () => {
+      if (!this.socket) {
+        this.dbg({
+          type: "connection",
+          phase: "connect_event",
+          err: "Socket is null"
+        });
+        throw new Error("Socket is null in onConnect handler");
       }
-    });
-    if (!("getSocket" in props)) return;
-    let cancelled = false;
-    dbg(providerDebugRef.current, { type: "resolve", phase: "start" });
-    if (!resolvedSocket) {
-      Promise.resolve(props.getSocket()).then((s) => {
-        if (cancelled) {
-          dbg(providerDebugRef.current, {
-            type: "resolve",
-            phase: "cancelled"
-          });
-          return;
-        }
-        if (!s) {
-          dbg(providerDebugRef.current, {
-            type: "resolve",
-            phase: "socketMissing"
-          });
-          return;
+      this.dbg({
+        type: "connection",
+        phase: "connect_event",
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
         }
-        setResolvedSocket(s);
-        dbg(providerDebugRef.current, { type: "resolve", phase: "ok" });
-      }).catch((err) => {
-        if (cancelled) return;
-        dbg(providerDebugRef.current, {
-          type: "resolve",
-          phase: "error",
-          err: String(err)
-        });
       });
-    }
-    return () => {
-      cancelled = true;
+      this.logSocketConfigSnapshot("connect_event");
+      await this.getSysEvent("sys:connect")({
+        socket: this.socket,
+        client: this
+      });
     };
-  }, [resolvedSocket]);
-  trackHookTrigger({
-    ref: clientMemoDebugRef,
-    hook: "client_memo",
-    providerDebug: providerDebugRef.current,
-    snapshot: {
-      events: summarizeEvents(events),
-      baseOptions: summarizeBaseOptions(baseOptions),
-      socket: describeSocketLike(socket)
-    }
-  });
-  const client = React.useMemo(() => {
-    if (!socket) {
-      dbg(providerDebugRef.current, {
-        type: "client",
-        phase: "init",
-        missing: true
+    this.onReconnect = async (attempt) => {
+      if (!this.socket) {
+        this.dbg({
+          type: "connection",
+          phase: "reconnect_event",
+          err: "Socket is null"
+        });
+        throw new Error("Socket is null in onReconnect handler");
+      }
+      this.dbg({
+        type: "connection",
+        phase: "reconnect_event",
+        attempt,
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
+        }
       });
-      return null;
-    }
-    const c = new SocketClient(events, { ...baseOptions, socket });
-    dbg(providerDebugRef.current, {
-      type: "client",
-      phase: "init",
-      missing: false
-    });
-    return c;
-  }, [events, baseOptions, socket]);
-  const destroyLeaveMetaRef = React.useRef(destroyLeaveMeta);
-  React.useEffect(() => {
-    destroyLeaveMetaRef.current = destroyLeaveMeta;
-  }, [destroyLeaveMeta]);
-  React.useEffect(() => {
-    trackHookTrigger({
-      ref: destroyEffectDebugRef,
-      hook: "destroy_effect",
-      providerDebug: providerDebugRef.current,
-      snapshot: {
-        hasClient: !!client,
-        destroyLeaveMeta: summarizeMeta(
-          destroyLeaveMetaRef.current,
-          "destroyLeaveMeta"
-        )
+      this.logSocketConfigSnapshot("reconnect_event");
+      await this.getSysEvent("sys:reconnect")({
+        attempt,
+        socket: this.socket,
+        client: this
+      });
+    };
+    this.onDisconnect = async (reason) => {
+      if (!this.socket) {
+        this.dbg({
+          type: "connection",
+          phase: "disconnect_event",
+          err: "Socket is null"
+        });
+        throw new Error("Socket is null in onDisconnect handler");
       }
-    });
-    return () => {
-      if (client) {
-        client.destroy(destroyLeaveMetaRef.current);
-        dbg(providerDebugRef.current, { type: "client", phase: "destroy" });
+      this.dbg({
+        type: "connection",
+        phase: "disconnect_event",
+        reason: String(reason),
+        details: {
+          roomsTracked: this.roomCounts.size
+        }
+      });
+      this.logSocketConfigSnapshot("disconnect_event");
+      await this.getSysEvent("sys:disconnect")({
+        reason: String(reason),
+        socket: this.socket,
+        client: this
+      });
+    };
+    this.onConnectError = async (err) => {
+      if (!this.socket) {
+        this.dbg({
+          type: "connection",
+          phase: "connect_error_event",
+          err: "Socket is null"
+        });
+        throw new Error("Socket is null in onConnectError handler");
       }
+      this.dbg({
+        type: "connection",
+        phase: "connect_error_event",
+        err: String(err),
+        details: this.getVerboseDetails({ rawError: err })
+      });
+      this.logSocketConfigSnapshot("connect_error_event");
+      await this.getSysEvent("sys:connect_error")({
+        error: String(err),
+        socket: this.socket,
+        client: this
+      });
     };
-  }, [client]);
-  dbg(providerDebugRef.current, { type: "render", hasClient: !!client });
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SocketCtx.Provider, { value: client, children: client == null ? fallback ?? children : children });
-}
-function useSocketClient() {
-  const ctx = React.useContext(SocketCtx);
-  if (!ctx)
-    throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
-  return ctx;
-}
-function useSocketConnection(args) {
-  const {
-    event,
-    rooms,
-    onMessage,
-    onCleanup,
-    autoJoin = true,
-    autoLeave = true
-  } = args;
-  const client = useSocketClient();
-  const normalizedRooms = React.useMemo(
-    () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
-    [rooms]
-  );
-  React.useEffect(() => {
-    if (autoJoin && normalizedRooms.length > 0)
-      client.joinRooms(normalizedRooms, args.joinMeta);
-    const unsubscribe = client.on(event, (payload, meta) => {
-      onMessage(payload, meta);
-    });
-    return () => {
-      unsubscribe();
-      if (autoLeave && normalizedRooms.length > 0)
-        client.leaveRooms(normalizedRooms, args.leaveMeta);
-      if (onCleanup) onCleanup();
+    this.onPong = async (raw) => {
+      if (!this.socket) {
+        this.dbg({
+          type: "heartbeat",
+          phase: "pong_recv",
+          err: "Socket is null"
+        });
+        throw new Error("Socket is null in onPong handler");
+      }
+      const parsed = this.config.pongPayload.safeParse(raw);
+      if (!parsed.success) {
+        this.dbg({
+          type: "heartbeat",
+          phase: "validation_failed",
+          err: `pong payload validation failed: ${parsed.error.message}`,
+          details: this.getValidationDetails(parsed.error)
+        });
+        return;
+      }
+      const validated = parsed.data;
+      this.dbg({
+        type: "heartbeat",
+        phase: "pong_recv",
+        payload: validated
+      });
+      await this.getSysEvent("sys:pong")({
+        socket: this.socket,
+        payload: validated,
+        client: this
+      });
     };
-  }, [client, event, onMessage, autoJoin, autoLeave, ...normalizedRooms]);
-}
-
-// src/sockets/socketedRoute/socket.client.helper.ts
-var import_react4 = require("react");
-function normalizeRooms(rooms) {
-  if (rooms == null) return [];
-  const list = Array.isArray(rooms) ? rooms : [rooms];
-  const seen = /* @__PURE__ */ new Set();
-  const normalized = [];
-  for (const r of list) {
-    if (typeof r !== "string") continue;
-    if (seen.has(r)) continue;
-    seen.add(r);
-    normalized.push(r);
+    if (this.socket) {
+      this.socket.on("connect", this.onConnect);
+      this.socket.on("reconnect", this.onReconnect);
+      this.socket.on("disconnect", this.onDisconnect);
+      this.socket.on("connect_error", this.onConnectError);
+      this.socket.on("sys:pong", this.onPong);
+    }
   }
-  return normalized;
-}
-var objectReferenceIds = /* @__PURE__ */ new WeakMap();
-var objectReferenceCounter = 0;
-function describeObjectReference(value) {
-  if (value == null) return null;
-  const valueType = typeof value;
-  if (valueType !== "object" && valueType !== "function") return null;
-  const obj = value;
-  let id = objectReferenceIds.get(obj);
-  if (!id) {
-    id = ++objectReferenceCounter;
-    objectReferenceIds.set(obj, id);
+  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
+    };
   }
-  return `ref#${id}`;
-}
-function safeJsonKey(value) {
-  try {
-    const serialized = JSON.stringify(value ?? null);
-    return serialized ?? "null";
-  } catch {
-    return "[unserializable]";
+  logSocketConfigSnapshot(reason) {
+    if (!this.debug.logger || !this.debug.config) return;
+    const snapshot = this.snapshotSocketConfig(this.socket);
+    this.dbg({
+      type: "config",
+      phase: reason,
+      ...snapshot == null ? { err: "Socket is missing. " } : {
+        socketId: this.socket?.id,
+        snapshot
+      }
+    });
   }
-}
-function arrayShallowEqual(a, b) {
-  if (a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i += 1) {
-    if (a[i] !== b[i]) return false;
+  getValidationDetails(error) {
+    if (!this.debug.verbose) return void 0;
+    return { issues: error.issues };
   }
-  return true;
-}
-function roomStateEqual(prev, next) {
-  return arrayShallowEqual(prev.rooms, next.rooms) && safeJsonKey(prev.joinMeta) === safeJsonKey(next.joinMeta) && safeJsonKey(prev.leaveMeta) === safeJsonKey(next.leaveMeta);
-}
-function isSameObjectReference(prev, next) {
-  if (prev !== next) return false;
-  if (next == null) return false;
-  const valueType = typeof next;
-  return valueType === "object" || valueType === "function";
-}
-function shouldWarnSocketMutationGuard() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function safeDescribeHookValue2(value) {
-  if (value == null) return value;
-  const valueType = typeof value;
-  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
-    return value;
+  getVerboseDetails(details) {
+    if (!this.debug.verbose) return void 0;
+    return details;
   }
-  if (valueType === "bigint" || valueType === "symbol") return String(value);
-  if (valueType === "function")
-    return `[function ${value.name || "anonymous"}]`;
-  if (Array.isArray(value)) return `[array length=${value.length}]`;
-  const ctorName = value.constructor?.name ?? "object";
-  const keys = Object.keys(value);
-  const keyPreview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  const ref = describeObjectReference(value);
-  return `[${ctorName}${ref ? ` ${ref}` : ""} keys=${keyPreview}${suffix}]`;
-}
-function createHookDebugEvent2(prev, next, phase) {
-  const reason = prev ? "change" : "init";
-  const changed = Object.keys(next).reduce((acc, dependency) => {
-    const prevValue = prev ? prev[dependency] : void 0;
-    const nextValue = next[dependency];
-    if (!prev || !Object.is(prevValue, nextValue)) {
-      acc.push({
-        dependency,
-        previous: safeDescribeHookValue2(prevValue),
-        next: safeDescribeHookValue2(nextValue)
-      });
-    }
-    return acc;
-  }, []);
-  if (!changed.length) return null;
-  return { type: "hook", phase, reason, changes: changed };
-}
-function dbg2(debug, event) {
-  if (!debug?.logger) return;
-  if (!debug[event.type]) return;
-  debug.logger(event);
-}
-function trackHookTrigger2({
-  ref,
-  phase,
-  debug,
-  snapshot
-}) {
-  const prev = ref.current;
-  ref.current = snapshot;
-  if (!debug?.logger || !debug?.hook) return;
-  const event = createHookDebugEvent2(prev, snapshot, phase);
-  if (event) dbg2(debug, event);
-}
-function isSocketClientUnavailableError(err) {
-  return err instanceof Error && err.message.includes("SocketClient not found");
-}
-function mergeRoomState(prev, toRoomsResult) {
-  const merged = new Set(prev.rooms);
-  for (const r of normalizeRooms(toRoomsResult.rooms)) merged.add(r);
-  return {
-    rooms: Array.from(merged),
-    joinMeta: toRoomsResult.joinMeta ?? prev.joinMeta,
-    leaveMeta: toRoomsResult.leaveMeta ?? prev.leaveMeta
-  };
-}
-function roomsFromData(data, toRooms) {
-  if (data == null) return { rooms: [] };
-  let state = { rooms: [] };
-  const add = (input) => {
-    const mergeForValue = (value) => {
-      state = mergeRoomState(state, toRooms(value));
+  getNamespace(socket) {
+    if (!socket) return void 0;
+    const nsp = socket.nsp;
+    return typeof nsp === "string" ? nsp : void 0;
+  }
+  getSysEvent(name) {
+    return this.sysEvents[name];
+  }
+  dbg(e) {
+    const d = this.debug;
+    if (!d.logger) return;
+    if (!d[e.type]) return;
+    if (d.only && "event" in e && !d.only.includes(e.event)) return;
+    d.logger(e);
+  }
+  /** internal stats snapshot */
+  stats() {
+    const rooms = Array.from(this.roomCounts.entries()).map(
+      ([room, count]) => ({ room, count })
+    );
+    const handlers = Array.from(this.handlerMap.entries()).map(
+      ([event, set]) => ({
+        event,
+        handlers: set.size
+      })
+    );
+    return {
+      roomsCount: rooms.length,
+      totalHandlers: handlers.reduce((a, b) => a + b.handlers, 0),
+      rooms,
+      handlers
     };
-    if (Array.isArray(input)) {
-      input.forEach((entry) => mergeForValue(entry));
-      return;
-    }
-    if (input && typeof input === "object") {
-      const maybeItems = input.items;
-      if (Array.isArray(maybeItems)) {
-        maybeItems.forEach((entry) => mergeForValue(entry));
-        return;
-      }
+  }
+  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);
     }
-    mergeForValue(input);
-  };
-  const maybePages = data?.pages;
-  if (Array.isArray(maybePages)) {
-    for (const page of maybePages) add(page);
-    return state;
   }
-  add(data);
-  return state;
-}
-function buildSocketedRoute(options) {
-  const { built, toRooms, applySocket, useSocketClient: useSocketClient2, debug } = options;
-  const { useEndpoint: useInnerEndpoint, ...rest } = built;
-  const useEndpoint = (...useArgs) => {
-    let client = null;
-    let socketClientError = null;
-    try {
-      client = useSocketClient2();
-    } catch (err) {
-      if (!isSocketClientUnavailableError(err)) throw err;
-      socketClientError = err;
+  rollbackLeaveDecrement(rooms) {
+    for (const room of rooms) {
+      const curr = this.roomCounts.get(room) ?? 0;
+      this.roomCounts.set(room, curr + 1);
     }
-    const endpointResult = useInnerEndpoint(
-      ...useArgs
-    );
-    const argsKey = (0, import_react4.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
-    const [roomState, setRoomState] = (0, import_react4.useState)(
-      () => roomsFromData(endpointResult.data, toRooms)
-    );
-    const renderCountRef = (0, import_react4.useRef)(0);
-    const clientReadyRef = (0, import_react4.useRef)(null);
-    const onReceiveEffectDebugRef = (0, import_react4.useRef)(null);
-    const deriveRoomsEffectDebugRef = (0, import_react4.useRef)(null);
-    const joinRoomsEffectDebugRef = (0, import_react4.useRef)(null);
-    const applySocketEffectDebugRef = (0, import_react4.useRef)(null);
-    renderCountRef.current += 1;
-    const roomsKey = (0, import_react4.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
-    const joinMetaKey = (0, import_react4.useMemo)(
-      () => safeJsonKey(roomState.joinMeta ?? null),
-      [roomState.joinMeta]
-    );
-    const leaveMetaKey = (0, import_react4.useMemo)(
-      () => safeJsonKey(roomState.leaveMeta ?? null),
-      [roomState.leaveMeta]
-    );
-    const hasClient = !!client;
-    if (clientReadyRef.current !== hasClient) {
-      clientReadyRef.current = hasClient;
-      dbg2(debug, {
-        type: "client",
-        phase: hasClient ? "ready" : "missing",
-        err: hasClient ? void 0 : String(socketClientError)
+  }
+  /**
+   * Public: start the heartbeat loop manually.
+   *
+   * This is called by the default 'sys:connect' handler, but you can also
+   * call it yourself from any sysHandler to change when heartbeats start.
+   */
+  startHeartbeat() {
+    this.stopHeartbeat("stop_before_start");
+    if (!this.socket) {
+      this.dbg({
+        type: "heartbeat",
+        phase: "start",
+        err: "Socket is null"
       });
+      return;
     }
-    dbg2(debug, {
-      type: "render",
-      renderCount: renderCountRef.current,
-      hasClient,
-      argsKey,
-      rooms: roomState.rooms,
-      roomsKey,
-      joinMetaKey,
-      leaveMetaKey
+    const socket = this.socket;
+    this.dbg({
+      type: "heartbeat",
+      phase: "start",
+      details: {
+        intervalMs: this.hb.intervalMs,
+        timeoutMs: this.hb.timeoutMs
+      }
     });
-    (0, import_react4.useEffect)(() => {
-      trackHookTrigger2({
-        ref: onReceiveEffectDebugRef,
-        phase: "endpoint_on_receive_effect",
-        debug,
-        snapshot: {
-          endpointResultRef: describeObjectReference(endpointResult),
-          endpointDataRef: describeObjectReference(endpointResult.data),
-          toRoomsRef: describeObjectReference(toRooms)
-        }
-      });
-      const unsubscribe = endpointResult.onReceive((data) => {
-        setRoomState((prev) => {
-          const next = mergeRoomState(prev, toRooms(data));
-          return roomStateEqual(prev, next) ? prev : next;
+    const tick = async () => {
+      if (!socket) {
+        this.dbg({
+          type: "heartbeat",
+          phase: "tick_skip",
+          err: "Socket missing during heartbeat tick"
         });
+        return;
+      }
+      const payload = await this.getSysEvent("sys:ping")({
+        socket,
+        client: this
       });
-      return unsubscribe;
-    }, [endpointResult, toRooms, debug]);
-    (0, import_react4.useEffect)(() => {
-      trackHookTrigger2({
-        ref: deriveRoomsEffectDebugRef,
-        phase: "derive_rooms_effect",
-        debug,
-        snapshot: {
-          endpointDataRef: describeObjectReference(endpointResult.data),
-          toRoomsRef: describeObjectReference(toRooms)
+      const check = this.config.pingPayload.safeParse(payload);
+      if (!check.success) {
+        this.dbg({
+          type: "heartbeat",
+          phase: "validation_failed",
+          err: "ping payload validation failed",
+          details: this.getValidationDetails(check.error)
+        });
+        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",
+        phase: "ping_emit",
+        payload: dataToSend
       });
-      const next = roomsFromData(
-        endpointResult.data,
-        toRooms
-      );
-      setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
-    }, [endpointResult.data, toRooms, debug]);
-    (0, import_react4.useEffect)(() => {
-      trackHookTrigger2({
-        ref: joinRoomsEffectDebugRef,
-        phase: "join_rooms_effect",
-        debug,
-        snapshot: {
-          hasClient: !!client,
-          clientRef: describeObjectReference(client),
-          roomsKey,
-          joinMetaKey,
-          leaveMetaKey
-        }
+    };
+    this.hbTimer = setInterval(tick, this.hb.intervalMs);
+    tick();
+  }
+  /**
+   * Public: stop the heartbeat loop.
+   *
+   * This is called by the default 'sys:disconnect' handler, but you can also
+   * call it yourself from any sysHandler to fully control heartbeat lifecycle.
+   */
+  stopHeartbeat(reason) {
+    const hadTimer = Boolean(this.hbTimer);
+    if (this.hbTimer) {
+      clearInterval(this.hbTimer);
+      this.hbTimer = null;
+    }
+    this.dbg({
+      type: "heartbeat",
+      phase: "stop",
+      reason,
+      hadTimer
+    });
+  }
+  emit(event, payload, metadata) {
+    if (!this.socket) {
+      this.dbg({ type: "emit", event, err: "Socket is null" });
+      return;
+    }
+    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)
       });
-      if (!client) {
-        dbg2(debug, {
+      throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
+    }
+    this.socket.emit(String(event), parsed.data);
+    this.dbg({
+      type: "emit",
+      event,
+      metadata
+    });
+  }
+  async joinRooms(rooms, meta) {
+    if (!this.socket) {
+      this.dbg({
+        type: "room",
+        phase: "join",
+        rooms: this.toArray(rooms),
+        err: "Socket is null"
+      });
+      throw new Error("Socket is null in joinRooms method");
+    }
+    if (!await this.getSysEvent("sys:room_join")({
+      rooms,
+      meta,
+      socket: this.socket,
+      client: this
+    })) {
+      this.dbg({
+        type: "room",
+        phase: "join",
+        rooms: this.toArray(rooms),
+        err: "sys:room_join handler aborted join"
+      });
+      return async () => {
+      };
+    }
+    const list = this.toArray(rooms);
+    const toJoin = [];
+    for (const r of list) {
+      const next = (this.roomCounts.get(r) ?? 0) + 1;
+      this.roomCounts.set(r, next);
+      if (next === 1) toJoin.push(r);
+    }
+    if (toJoin.length > 0 && this.socket) {
+      const payloadResult = this.roomJoinSchema.safeParse({
+        rooms: toJoin,
+        meta
+      });
+      if (!payloadResult.success) {
+        this.rollbackJoinIncrement(toJoin);
+        this.dbg({
           type: "room",
-          phase: "join_skip",
-          rooms: roomState.rooms,
-          reason: "socket_client_missing"
+          phase: "join",
+          rooms: toJoin,
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
         });
-        return;
+        return async () => {
+        };
       }
-      if (roomState.rooms.length === 0) {
-        dbg2(debug, {
+      const payload = payloadResult.data;
+      const normalizedRooms = this.toArray(payload.rooms);
+      this.socket.emit("sys:room_join", payload);
+      this.dbg({ type: "room", phase: "join", rooms: normalizedRooms });
+    }
+    return async () => {
+      await this.leaveRooms(rooms, meta);
+    };
+  }
+  async leaveRooms(rooms, meta) {
+    if (!this.socket) {
+      this.dbg({
+        type: "room",
+        phase: "leave",
+        rooms: this.toArray(rooms),
+        err: "Socket is null"
+      });
+      throw new Error("Socket is null in leaveRooms method");
+    }
+    if (!await this.getSysEvent("sys:room_leave")({
+      rooms,
+      meta,
+      socket: this.socket,
+      client: this
+    })) {
+      this.dbg({
+        type: "room",
+        phase: "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) {
+      const curr = this.roomCounts.get(r) ?? 0;
+      const next = Math.max(0, curr - 1);
+      if (next === 0 && curr > 0) toLeave.push(r);
+      if (next === 0) this.roomCounts.delete(r);
+      else this.roomCounts.set(r, next);
+    }
+    if (toLeave.length > 0 && this.socket) {
+      const payloadResult = this.roomLeaveSchema.safeParse({
+        rooms: toLeave,
+        meta
+      });
+      if (!payloadResult.success) {
+        this.rollbackLeaveDecrement(toLeave);
+        this.dbg({
           type: "room",
-          phase: "join_skip",
-          rooms: [],
-          reason: "no_rooms"
+          phase: "leave",
+          rooms: toLeave,
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
         });
         return;
       }
-      const { joinMeta, leaveMeta } = roomState;
-      if (!joinMeta || !leaveMeta) {
-        dbg2(debug, {
-          type: "room",
-          phase: "join_skip",
-          rooms: roomState.rooms,
-          reason: "missing_meta"
+      const payload = payloadResult.data;
+      const normalizedRooms = this.toArray(payload.rooms);
+      this.socket.emit("sys:room_leave", payload);
+      this.dbg({ type: "room", phase: "leave", rooms: normalizedRooms });
+    }
+  }
+  on(event, handler) {
+    const schema = this.events[event].message;
+    this.dbg({ type: "register", phase: "register", event });
+    if (!this.socket) {
+      this.dbg({
+        type: "register",
+        phase: "register",
+        event,
+        err: "Socket is null"
+      });
+      return () => {
+      };
+    }
+    const socket = this.socket;
+    const toStringList = (value) => Array.isArray(value) ? value.filter((entry2) => typeof entry2 === "string") : [];
+    const wrappedEnv = (envelope) => {
+      const rawData = envelope.data;
+      const parsed = schema.safeParse(rawData);
+      if (!parsed.success) {
+        this.dbg({
+          type: "receive",
+          event,
+          err: "payload_validation_failed",
+          details: this.getValidationDetails(parsed.error)
         });
         return;
       }
-      let active = true;
-      dbg2(debug, {
-        type: "room",
-        phase: "join_attempt",
-        rooms: roomState.rooms
-      });
-      (async () => {
-        try {
-          await client.joinRooms(roomState.rooms, joinMeta);
-        } catch (err) {
-          dbg2(debug, {
-            type: "room",
-            phase: "join_error",
-            rooms: roomState.rooms,
-            err: String(err)
-          });
-        }
-      })();
-      return () => {
-        if (!active) return;
-        active = false;
-        if (roomState.rooms.length === 0) {
-          dbg2(debug, {
-            type: "room",
-            phase: "leave_skip",
-            rooms: [],
-            reason: "no_rooms"
-          });
-          return;
+      const data = parsed.data;
+      const receivedAt = /* @__PURE__ */ new Date();
+      const sentAt = envelope?.sentAt ? new Date(envelope.sentAt) : void 0;
+      const meta = {
+        envelope: {
+          eventName: typeof envelope?.eventName === "string" ? envelope.eventName : event,
+          sentAt: envelope?.sentAt ?? receivedAt.toISOString(),
+          sentTo: toStringList(envelope?.sentTo),
+          data,
+          metadata: envelope?.metadata,
+          rooms: toStringList(envelope?.rooms)
+        },
+        ctx: {
+          receivedAt,
+          latencyMs: sentAt ? Math.max(0, receivedAt.getTime() - sentAt.getTime()) : void 0,
+          nsp: this.getNamespace(socket),
+          socketId: socket.id,
+          socket
         }
-        dbg2(debug, {
-          type: "room",
-          phase: "leave_attempt",
-          rooms: roomState.rooms
-        });
-        void client.leaveRooms(roomState.rooms, leaveMeta).catch((err) => {
-          dbg2(debug, {
-            type: "room",
-            phase: "leave_error",
-            rooms: roomState.rooms,
-            err: String(err)
-          });
-        });
-      };
-    }, [client, roomsKey, joinMetaKey, leaveMetaKey, debug]);
-    (0, import_react4.useEffect)(() => {
-      trackHookTrigger2({
-        ref: applySocketEffectDebugRef,
-        phase: "apply_socket_effect",
-        debug,
-        snapshot: {
-          hasClient: !!client,
-          clientRef: describeObjectReference(client),
-          applySocketKeys: Object.keys(applySocket).sort().join(","),
-          argsKey,
-          toRoomsRef: describeObjectReference(toRooms)
-        }
-      });
-      if (!client) return;
-      const queue = [];
-      const sameRefWarnedEvents = /* @__PURE__ */ new Set();
-      let draining = false;
-      let active = true;
-      const drainQueue = () => {
-        if (!active || draining) return;
-        draining = true;
-        try {
-          while (active && queue.length > 0) {
-            const nextUpdate = queue.shift();
-            if (!nextUpdate) continue;
-            built.setData(
-              (prev) => {
-                const next = nextUpdate.fn(
-                  prev,
-                  nextUpdate.payload,
-                  nextUpdate.meta ? { ...nextUpdate.meta, args: useArgs } : { args: useArgs }
-                );
-                if (next === null) return prev;
-                if (shouldWarnSocketMutationGuard() && isSameObjectReference(prev, next) && !sameRefWarnedEvents.has(nextUpdate.event)) {
-                  sameRefWarnedEvents.add(nextUpdate.event);
-                  console.warn(
-                    `[socketedRoute] applySocket("${nextUpdate.event}") returned the previous reference. Return a new object/array for updates, or return null for no change.`
-                  );
-                }
-                const nextRoomState = roomsFromData(
-                  next,
-                  toRooms
-                );
-                setRoomState(
-                  (prevRoomState) => roomStateEqual(prevRoomState, nextRoomState) ? prevRoomState : nextRoomState
-                );
-                return next;
-              },
-              ...useArgs
-            );
-          }
-        } finally {
-          draining = false;
-          if (active && queue.length > 0) drainQueue();
-        }
-      };
-      const entries = Object.entries(applySocket).filter(
-        ([_event, fn]) => typeof fn === "function"
-      );
-      const unsubscribes = entries.map(
-        ([ev, fn]) => client.on(ev, (payload, meta) => {
-          queue.push({
-            event: ev,
-            fn,
-            payload,
-            ...meta ? { meta } : {}
-          });
-          drainQueue();
-        })
-      );
-      return () => {
-        active = false;
-        queue.length = 0;
-        unsubscribes.forEach((u) => u?.());
       };
-    }, [client, applySocket, built, argsKey, toRooms, debug]);
-    return { ...endpointResult, rooms: roomState.rooms };
-  };
-  return {
-    ...rest,
-    useEndpoint
-  };
-}
-
-// src/sockets/socket.client.index.ts
-var SocketClient = class {
-  constructor(events, opts) {
-    this.hbTimer = null;
-    // stats
-    this.roomCounts = /* @__PURE__ */ new Map();
-    this.handlerMap = /* @__PURE__ */ new Map();
-    this.events = events;
-    this.socket = opts.socket ?? null;
-    this.environment = opts.environment ?? "development";
-    this.debug = opts.debug ?? {};
-    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
-    };
-    if (!this.socket) {
-      this.dbg({
-        type: "lifecycle",
-        phase: "init",
-        err: "Socket reference is null during initialization"
-      });
-    } else {
-      this.dbg({
-        type: "lifecycle",
-        phase: "init",
-        heartbeatIntervalMs: this.hb.intervalMs,
-        heartbeatTimeoutMs: this.hb.timeoutMs,
-        environment: this.environment
-      });
-      this.logSocketConfigSnapshot("constructor");
-    }
-    this.onConnect = async () => {
-      if (!this.socket) {
-        this.dbg({
-          type: "connection",
-          phase: "connect_event",
-          err: "Socket is null"
-        });
-        throw new Error("Socket is null in onConnect handler");
-      }
       this.dbg({
-        type: "connection",
-        phase: "connect_event",
-        id: this.socket.id,
-        details: {
-          nsp: this.getNamespace(this.socket)
-        }
-      });
-      this.logSocketConfigSnapshot("connect_event");
-      await this.getSysEvent("sys:connect")({
-        socket: this.socket,
-        client: this
+        type: "receive",
+        event,
+        envelope: this.debug.verbose ? {
+          eventName: meta.envelope.eventName,
+          sentAt: meta.envelope.sentAt,
+          sentTo: meta.envelope.sentTo,
+          metadata: meta.envelope.metadata
+        } : void 0
       });
+      handler(data, meta);
     };
-    this.onReconnect = async (attempt) => {
-      if (!this.socket) {
+    const wrappedDispatcher = (envelopeOrRaw) => {
+      if (typeof envelopeOrRaw === "object" && envelopeOrRaw !== null && "eventName" in envelopeOrRaw && "sentAt" in envelopeOrRaw && "sentTo" in envelopeOrRaw && "data" in envelopeOrRaw) {
+        wrappedEnv(envelopeOrRaw);
+      } else {
         this.dbg({
-          type: "connection",
-          phase: "reconnect_event",
-          err: "Socket is null"
+          type: "receive",
+          event,
+          envelope: void 0
         });
-        throw new Error("Socket is null in onReconnect handler");
+        handler(envelopeOrRaw, void 0);
       }
-      this.dbg({
-        type: "connection",
-        phase: "reconnect_event",
-        attempt,
-        id: this.socket.id,
-        details: {
-          nsp: this.getNamespace(this.socket)
-        }
-      });
-      this.logSocketConfigSnapshot("reconnect_event");
-      await this.getSysEvent("sys:reconnect")({
-        attempt,
-        socket: this.socket,
-        client: this
-      });
     };
-    this.onDisconnect = async (reason) => {
-      if (!this.socket) {
-        this.dbg({
-          type: "connection",
-          phase: "disconnect_event",
-          err: "Socket is null"
-        });
-        throw new Error("Socket is null in onDisconnect handler");
-      }
-      this.dbg({
-        type: "connection",
-        phase: "disconnect_event",
-        reason: String(reason),
-        details: {
-          roomsTracked: this.roomCounts.size
-        }
-      });
-      this.logSocketConfigSnapshot("disconnect_event");
-      await this.getSysEvent("sys:disconnect")({
-        reason: String(reason),
-        socket: this.socket,
-        client: this
-      });
+    const errorWrapped = (e) => {
+      this.dbg({ type: "receive", event, err: String(e) });
     };
-    this.onConnectError = async (err) => {
-      if (!this.socket) {
-        this.dbg({
-          type: "connection",
-          phase: "connect_error_event",
-          err: "Socket is null"
-        });
-        throw new Error("Socket is null in onConnectError handler");
-      }
-      this.dbg({
-        type: "connection",
-        phase: "connect_error_event",
-        err: String(err),
-        details: this.getVerboseDetails({ rawError: err })
-      });
-      this.logSocketConfigSnapshot("connect_error_event");
-      await this.getSysEvent("sys:connect_error")({
-        error: String(err),
-        socket: this.socket,
-        client: this
-      });
+    socket.on(String(event), wrappedDispatcher);
+    socket.on(`${String(event)}:error`, errorWrapped);
+    let set = this.handlerMap.get(String(event));
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlerMap.set(String(event), set);
+    }
+    const entry = {
+      orig: handler,
+      wrapped: wrappedDispatcher,
+      errorWrapped
     };
-    this.onPong = async (raw) => {
-      if (!this.socket) {
-        this.dbg({
-          type: "heartbeat",
-          phase: "pong_recv",
-          err: "Socket is null"
-        });
-        throw new Error("Socket is null in onPong handler");
+    set.add(entry);
+    return () => {
+      socket.off(String(event), wrappedDispatcher);
+      socket.off(`${String(event)}:error`, errorWrapped);
+      const s = this.handlerMap.get(String(event));
+      if (s) {
+        s.delete(entry);
+        if (s.size === 0) this.handlerMap.delete(String(event));
       }
-      const parsed = this.config.pongPayload.safeParse(raw);
-      if (!parsed.success) {
-        this.dbg({
-          type: "heartbeat",
-          phase: "validation_failed",
-          err: `pong payload validation failed: ${parsed.error.message}`,
-          details: this.getValidationDetails(parsed.error)
-        });
-        return;
-      }
-      const validated = parsed.data;
-      this.dbg({
-        type: "heartbeat",
-        phase: "pong_recv",
-        payload: validated
-      });
-      await this.getSysEvent("sys:pong")({
-        socket: this.socket,
-        payload: validated,
-        client: this
-      });
-    };
-    if (this.socket) {
-      this.socket.on("connect", this.onConnect);
-      this.socket.on("reconnect", this.onReconnect);
-      this.socket.on("disconnect", this.onDisconnect);
-      this.socket.on("connect_error", this.onConnectError);
-      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
+      this.dbg({ type: "register", phase: "unregister", event });
     };
   }
-  logSocketConfigSnapshot(reason) {
-    if (!this.debug.logger || !this.debug.config) return;
-    const snapshot = this.snapshotSocketConfig(this.socket);
+  /**
+   * Remove all listeners, stop timers, and leave rooms.
+   * Call when disposing the client instance.
+   */
+  async destroy(leaveMeta) {
+    const socket = this.socket;
     this.dbg({
-      type: "config",
-      phase: reason,
-      ...snapshot == null ? { err: "Socket is missing. " } : {
-        socketId: this.socket?.id,
-        snapshot
+      type: "lifecycle",
+      phase: "destroy_begin",
+      socketId: socket?.id,
+      details: {
+        roomsTracked: this.roomCounts.size,
+        handlerEvents: this.handlerMap.size
       }
     });
-  }
-  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];
-  }
-  dbg(e) {
-    const d = this.debug;
-    if (!d.logger) return;
-    if (!d[e.type]) return;
-    if (d.only && "event" in e && !d.only.includes(e.event)) return;
-    d.logger(e);
-  }
-  /** internal stats snapshot */
-  stats() {
-    const rooms = Array.from(this.roomCounts.entries()).map(
-      ([room, count]) => ({ room, count })
-    );
-    const handlers = Array.from(this.handlerMap.entries()).map(
-      ([event, set]) => ({
-        event,
-        handlers: set.size
-      })
-    );
-    return {
-      roomsCount: rooms.length,
-      totalHandlers: handlers.reduce((a, b) => a + b.handlers, 0),
-      rooms,
-      handlers
-    };
-  }
-  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);
+    this.stopHeartbeat("destroy");
+    if (socket) {
+      socket.off("connect", this.onConnect);
+      socket.off("reconnect", this.onReconnect);
+      socket.off("disconnect", this.onDisconnect);
+      socket.off("connect_error", this.onConnectError);
+      socket.off("sys:pong", this.onPong);
+      for (const [event, set] of this.handlerMap.entries()) {
+        for (const entry of set) {
+          socket.off(String(event), entry.wrapped);
+          socket.off(`${String(event)}:error`, entry.errorWrapped);
+        }
+      }
     }
-  }
-  rollbackLeaveDecrement(rooms) {
-    for (const room of rooms) {
-      const curr = this.roomCounts.get(room) ?? 0;
-      this.roomCounts.set(room, curr + 1);
+    this.handlerMap.clear();
+    const toLeave = Array.from(this.roomCounts.entries()).filter(([, count]) => count > 0).map(([room]) => room);
+    if (toLeave.length > 0 && socket) {
+      await 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
+      }
+    });
   }
-  /**
-   * Public: start the heartbeat loop manually.
-   *
-   * This is called by the default 'sys:connect' handler, but you can also
-   * call it yourself from any sysHandler to change when heartbeats start.
-   */
-  startHeartbeat() {
-    this.stopHeartbeat("stop_before_start");
+  /** Pass-throughs. Managing connection is the caller’s responsibility. */
+  disconnect() {
     if (!this.socket) {
       this.dbg({
-        type: "heartbeat",
-        phase: "start",
+        type: "connection",
+        phase: "disconnect",
+        reason: "client_disconnect",
         err: "Socket is null"
       });
       return;
     }
-    const socket = this.socket;
+    this.stopHeartbeat("disconnect");
+    this.socket.disconnect();
     this.dbg({
-      type: "heartbeat",
-      phase: "start",
+      type: "connection",
+      phase: "disconnect",
+      reason: "client_disconnect",
       details: {
-        intervalMs: this.hb.intervalMs,
-        timeoutMs: this.hb.timeoutMs
+        nsp: this.getNamespace(this.socket)
       }
     });
-    const tick = async () => {
-      if (!socket) {
-        this.dbg({
-          type: "heartbeat",
-          phase: "tick_skip",
-          err: "Socket missing during heartbeat tick"
-        });
-        return;
-      }
-      const payload = await this.getSysEvent("sys:ping")({
-        socket,
-        client: this
-      });
-      const check = this.config.pingPayload.safeParse(payload);
-      if (!check.success) {
-        this.dbg({
-          type: "heartbeat",
-          phase: "validation_failed",
-          err: "ping payload validation failed",
-          details: this.getValidationDetails(check.error)
-        });
-        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.logSocketConfigSnapshot("disconnect_call");
+  }
+  connect() {
+    if (!this.socket) {
       this.dbg({
-        type: "heartbeat",
-        phase: "ping_emit",
-        payload: dataToSend
+        type: "connection",
+        phase: "connect",
+        err: "Socket is null"
       });
-    };
-    this.hbTimer = setInterval(tick, this.hb.intervalMs);
-    tick();
-  }
-  /**
-   * Public: stop the heartbeat loop.
-   *
-   * This is called by the default 'sys:disconnect' handler, but you can also
-   * call it yourself from any sysHandler to fully control heartbeat lifecycle.
-   */
-  stopHeartbeat(reason) {
-    const hadTimer = Boolean(this.hbTimer);
-    if (this.hbTimer) {
-      clearInterval(this.hbTimer);
-      this.hbTimer = null;
+      return;
     }
+    this.socket.connect();
     this.dbg({
-      type: "heartbeat",
-      phase: "stop",
-      reason,
-      hadTimer
+      type: "connection",
+      phase: "connect",
+      id: this.socket.id ?? "",
+      details: {
+        nsp: this.getNamespace(this.socket)
+      }
     });
+    this.logSocketConfigSnapshot("connect_call");
   }
-  emit(event, payload, metadata) {
-    if (!this.socket) {
-      this.dbg({ type: "emit", event, err: "Socket is null" });
-      return;
-    }
-    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)
-      });
-      throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
-    }
-    this.socket.emit(String(event), parsed.data);
-    this.dbg({
-      type: "emit",
-      event,
-      metadata
+};
+
+// src/sockets/socket.client.context.provider.tsx
+var React3 = __toESM(require("react"), 1);
+
+// src/sockets/socket.client.context.client.ts
+var React = __toESM(require("react"), 1);
+var SocketCtx = React.createContext(null);
+function useSocketClient() {
+  const ctx = React.useContext(SocketCtx);
+  if (!ctx)
+    throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
+  return ctx;
+}
+
+// src/sockets/socket.client.context.connection.ts
+var React2 = __toESM(require("react"), 1);
+function useSocketConnection(args) {
+  const {
+    event,
+    rooms,
+    onMessage,
+    onCleanup,
+    autoJoin = true,
+    autoLeave = true
+  } = args;
+  const client = useSocketClient();
+  const normalizedRooms = React2.useMemo(
+    () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
+    [rooms]
+  );
+  React2.useEffect(() => {
+    if (autoJoin && normalizedRooms.length > 0)
+      client.joinRooms(normalizedRooms, args.joinMeta);
+    const unsubscribe = client.on(event, (payload, meta) => {
+      onMessage(payload, meta);
     });
+    return () => {
+      unsubscribe();
+      if (autoLeave && normalizedRooms.length > 0)
+        client.leaveRooms(normalizedRooms, args.leaveMeta);
+      if (onCleanup) onCleanup();
+    };
+  }, [client, event, onMessage, autoJoin, autoLeave, ...normalizedRooms]);
+}
+
+// src/sockets/socket.client.context.debug.ts
+function dbg(dbgOpts, e) {
+  if (!dbgOpts?.logger) return;
+  if (!dbgOpts[e.type]) return;
+  dbgOpts.logger(e);
+}
+function isProbablySocket(value) {
+  if (!value || typeof value !== "object") return false;
+  const anyVal = value;
+  const ctorName = anyVal.constructor?.name;
+  if (ctorName === "Socket") return true;
+  return ("connected" in anyVal || "recovered" in anyVal) && typeof anyVal.on === "function" && typeof anyVal.emit === "function";
+}
+function describeSocketLike(value) {
+  if (!value) return null;
+  const id = value.id ?? "unknown";
+  const connected = value.connected ?? false;
+  const recovered = typeof value.recovered === "boolean" ? ` recovered=${value.recovered}` : "";
+  return `[Socket id=${id} connected=${connected}${recovered}]`;
+}
+function safeDescribeHookValue(value) {
+  if (value == null) return value;
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
+    return value;
   }
-  async joinRooms(rooms, meta) {
-    if (!this.socket) {
-      this.dbg({
-        type: "room",
-        phase: "join",
-        rooms: this.toArray(rooms),
-        err: "Socket is null"
+  if (valueType === "bigint" || valueType === "symbol") return String(value);
+  if (valueType === "function")
+    return `[function ${value.name || "anonymous"}]`;
+  if (Array.isArray(value)) return `[array length=${value.length}]`;
+  if (isProbablySocket(value)) return describeSocketLike(value);
+  const ctorName = value.constructor?.name ?? "object";
+  const keys = Object.keys(value);
+  const keyPreview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[${ctorName} keys=${keyPreview}${suffix}]`;
+}
+function summarizeEvents(events) {
+  if (!events || typeof events !== "object")
+    return safeDescribeHookValue(events);
+  const keys = Object.keys(events);
+  if (!keys.length) return "[events empty]";
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[events count=${keys.length} keys=${preview}${suffix}]`;
+}
+function summarizeBaseOptions(options) {
+  if (!options || typeof options !== "object")
+    return safeDescribeHookValue(options);
+  const obj = options;
+  const keys = Object.keys(obj);
+  if (!keys.length) return "[baseOptions empty]";
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  const hasDebug = "debug" in obj;
+  return `[baseOptions keys=${preview}${suffix} debug=${hasDebug}]`;
+}
+function summarizeMeta(meta, label) {
+  if (meta == null) return null;
+  if (typeof meta !== "object") return safeDescribeHookValue(meta);
+  const keys = Object.keys(meta);
+  if (!keys.length) return `[${label} empty]`;
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[${label} keys=${preview}${suffix}]`;
+}
+function createHookDebugEvent(prev, next, hook) {
+  const reason = prev ? "change" : "init";
+  const changed = Object.keys(next).reduce((acc, dependency) => {
+    const prevValue = prev ? prev[dependency] : void 0;
+    const nextValue = next[dependency];
+    if (!prev || !Object.is(prevValue, nextValue)) {
+      acc.push({
+        dependency,
+        previous: safeDescribeHookValue(prevValue),
+        next: safeDescribeHookValue(nextValue)
       });
-      throw new Error("Socket is null in joinRooms method");
     }
-    if (!await this.getSysEvent("sys:room_join")({
-      rooms,
-      meta,
-      socket: this.socket,
-      client: this
-    })) {
-      this.dbg({
-        type: "room",
-        phase: "join",
-        rooms: this.toArray(rooms),
-        err: "sys:room_join handler aborted join"
+    return acc;
+  }, []);
+  if (!changed.length) return null;
+  return { type: "hook", phase: hook, reason, changes: changed };
+}
+function trackHookTrigger({
+  ref,
+  hook,
+  providerDebug,
+  snapshot
+}) {
+  const prev = ref.current;
+  ref.current = snapshot;
+  if (!providerDebug?.logger || !providerDebug?.hook) return;
+  const event = createHookDebugEvent(prev, snapshot, hook);
+  if (event) dbg(providerDebug, event);
+}
+
+// src/sockets/socket.client.context.provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function buildSocketProvider(args) {
+  const { events, options: baseOptions } = args;
+  return {
+    SocketProvider: (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      SocketProvider,
+      {
+        events,
+        baseOptions,
+        providerDebug: baseOptions.debug,
+        ...props
+      }
+    ),
+    useSocketClient: () => useSocketClient(),
+    useSocketConnection: (p) => useSocketConnection(p)
+  };
+}
+function SocketProvider(props) {
+  const {
+    events,
+    baseOptions,
+    children,
+    fallback,
+    providerDebug,
+    destroyLeaveMeta
+  } = props;
+  const [resolvedSocket, setResolvedSocket] = React3.useState(
+    null
+  );
+  const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
+  const providerDebugRef = React3.useRef();
+  providerDebugRef.current = providerDebug;
+  const resolveEffectDebugRef = React3.useRef(null);
+  const clientMemoDebugRef = React3.useRef(null);
+  const destroyEffectDebugRef = React3.useRef(null);
+  React3.useEffect(() => {
+    trackHookTrigger({
+      ref: resolveEffectDebugRef,
+      hook: "resolve_effect",
+      providerDebug: providerDebugRef.current,
+      snapshot: {
+        resolvedSocket: describeSocketLike(resolvedSocket)
+      }
+    });
+    if (!("getSocket" in props)) return;
+    let cancelled = false;
+    dbg(providerDebugRef.current, { type: "resolve", phase: "start" });
+    if (!resolvedSocket) {
+      Promise.resolve(props.getSocket()).then((s) => {
+        if (cancelled) {
+          dbg(providerDebugRef.current, {
+            type: "resolve",
+            phase: "cancelled"
+          });
+          return;
+        }
+        if (!s) {
+          dbg(providerDebugRef.current, {
+            type: "resolve",
+            phase: "socketMissing"
+          });
+          return;
+        }
+        setResolvedSocket(s);
+        dbg(providerDebugRef.current, { type: "resolve", phase: "ok" });
+      }).catch((err) => {
+        if (cancelled) return;
+        dbg(providerDebugRef.current, {
+          type: "resolve",
+          phase: "error",
+          err: String(err)
+        });
       });
-      return async () => {
-      };
     }
-    const list = this.toArray(rooms);
-    const toJoin = [];
-    for (const r of list) {
-      const next = (this.roomCounts.get(r) ?? 0) + 1;
-      this.roomCounts.set(r, next);
-      if (next === 1) toJoin.push(r);
+    return () => {
+      cancelled = true;
+    };
+  }, [resolvedSocket]);
+  trackHookTrigger({
+    ref: clientMemoDebugRef,
+    hook: "client_memo",
+    providerDebug: providerDebugRef.current,
+    snapshot: {
+      events: summarizeEvents(events),
+      baseOptions: summarizeBaseOptions(baseOptions),
+      socket: describeSocketLike(socket)
     }
-    if (toJoin.length > 0 && this.socket) {
-      const payloadResult = this.roomJoinSchema.safeParse({
-        rooms: toJoin,
-        meta
+  });
+  const client = React3.useMemo(() => {
+    if (!socket) {
+      dbg(providerDebugRef.current, {
+        type: "client",
+        phase: "init",
+        missing: true
       });
-      if (!payloadResult.success) {
-        this.rollbackJoinIncrement(toJoin);
-        this.dbg({
-          type: "room",
-          phase: "join",
-          rooms: toJoin,
-          err: "payload validation failed",
-          details: this.getValidationDetails(payloadResult.error)
-        });
-        return async () => {
-        };
-      }
-      const payload = payloadResult.data;
-      const normalizedRooms = this.toArray(payload.rooms);
-      this.socket.emit("sys:room_join", payload);
-      this.dbg({ type: "room", phase: "join", rooms: normalizedRooms });
+      return null;
     }
-    return async () => {
-      await this.leaveRooms(rooms, meta);
+    const c = new SocketClient(events, { ...baseOptions, socket });
+    dbg(providerDebugRef.current, {
+      type: "client",
+      phase: "init",
+      missing: false
+    });
+    return c;
+  }, [events, baseOptions, socket]);
+  const destroyLeaveMetaRef = React3.useRef(destroyLeaveMeta);
+  React3.useEffect(() => {
+    destroyLeaveMetaRef.current = destroyLeaveMeta;
+  }, [destroyLeaveMeta]);
+  React3.useEffect(() => {
+    trackHookTrigger({
+      ref: destroyEffectDebugRef,
+      hook: "destroy_effect",
+      providerDebug: providerDebugRef.current,
+      snapshot: {
+        hasClient: !!client,
+        destroyLeaveMeta: summarizeMeta(
+          destroyLeaveMetaRef.current,
+          "destroyLeaveMeta"
+        )
+      }
+    });
+    return () => {
+      if (client) {
+        client.destroy(destroyLeaveMetaRef.current);
+        dbg(providerDebugRef.current, { type: "client", phase: "destroy" });
+      }
     };
+  }, [client]);
+  dbg(providerDebugRef.current, { type: "render", hasClient: !!client });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SocketCtx.Provider, { value: client, children: client == null ? fallback ?? children : children });
+}
+
+// src/sockets/socketedRoute/socket.client.helper.route.ts
+var import_react4 = require("react");
+
+// src/sockets/socketedRoute/socket.client.helper.debug.ts
+var objectReferenceIds = /* @__PURE__ */ new WeakMap();
+var objectReferenceCounter = 0;
+function describeObjectReference(value) {
+  if (value == null) return null;
+  const valueType = typeof value;
+  if (valueType !== "object" && valueType !== "function") return null;
+  const obj = value;
+  let id = objectReferenceIds.get(obj);
+  if (!id) {
+    id = ++objectReferenceCounter;
+    objectReferenceIds.set(obj, id);
   }
-  async leaveRooms(rooms, meta) {
-    if (!this.socket) {
-      this.dbg({
-        type: "room",
-        phase: "leave",
-        rooms: this.toArray(rooms),
-        err: "Socket is null"
+  return `ref#${id}`;
+}
+function safeJsonKey(value) {
+  try {
+    const serialized = JSON.stringify(value ?? null);
+    return serialized ?? "null";
+  } catch {
+    return "[unserializable]";
+  }
+}
+function isSameObjectReference(prev, next) {
+  if (prev !== next) return false;
+  if (next == null) return false;
+  const valueType = typeof next;
+  return valueType === "object" || valueType === "function";
+}
+function shouldWarnSocketMutationGuard() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function safeDescribeHookValue2(value) {
+  if (value == null) return value;
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
+    return value;
+  }
+  if (valueType === "bigint" || valueType === "symbol") return String(value);
+  if (valueType === "function")
+    return `[function ${value.name || "anonymous"}]`;
+  if (Array.isArray(value)) return `[array length=${value.length}]`;
+  const ctorName = value.constructor?.name ?? "object";
+  const keys = Object.keys(value);
+  const keyPreview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  const ref = describeObjectReference(value);
+  return `[${ctorName}${ref ? ` ${ref}` : ""} keys=${keyPreview}${suffix}]`;
+}
+function createHookDebugEvent2(prev, next, phase) {
+  const reason = prev ? "change" : "init";
+  const changed = Object.keys(next).reduce((acc, dependency) => {
+    const prevValue = prev ? prev[dependency] : void 0;
+    const nextValue = next[dependency];
+    if (!prev || !Object.is(prevValue, nextValue)) {
+      acc.push({
+        dependency,
+        previous: safeDescribeHookValue2(prevValue),
+        next: safeDescribeHookValue2(nextValue)
       });
-      throw new Error("Socket is null in leaveRooms method");
     }
-    if (!await this.getSysEvent("sys:room_leave")({
-      rooms,
-      meta,
-      socket: this.socket,
-      client: this
-    })) {
-      this.dbg({
-        type: "room",
-        phase: "leave",
-        rooms: this.toArray(rooms),
-        err: "sys:room_leave handler aborted leave"
-      });
+    return acc;
+  }, []);
+  if (!changed.length) return null;
+  return { type: "hook", phase, reason, changes: changed };
+}
+function dbg2(debug, event) {
+  if (!debug?.logger) return;
+  if (!debug[event.type]) return;
+  debug.logger(event);
+}
+function trackHookTrigger2({
+  ref,
+  phase,
+  debug,
+  snapshot
+}) {
+  const prev = ref.current;
+  ref.current = snapshot;
+  if (!debug?.logger || !debug?.hook) return;
+  const event = createHookDebugEvent2(prev, snapshot, phase);
+  if (event) dbg2(debug, event);
+}
+
+// src/sockets/socketedRoute/socket.client.helper.rooms.ts
+function normalizeRooms(rooms) {
+  if (rooms == null) return [];
+  const list = Array.isArray(rooms) ? rooms : [rooms];
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const r of list) {
+    if (typeof r !== "string") continue;
+    if (seen.has(r)) continue;
+    seen.add(r);
+    normalized.push(r);
+  }
+  return normalized;
+}
+function arrayShallowEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function roomStateEqual(prev, next) {
+  return arrayShallowEqual(prev.rooms, next.rooms) && safeJsonKey(prev.joinMeta) === safeJsonKey(next.joinMeta) && safeJsonKey(prev.leaveMeta) === safeJsonKey(next.leaveMeta);
+}
+function mergeRoomState(prev, toRoomsResult) {
+  const merged = new Set(prev.rooms);
+  for (const r of normalizeRooms(toRoomsResult.rooms)) merged.add(r);
+  return {
+    rooms: Array.from(merged),
+    joinMeta: toRoomsResult.joinMeta ?? prev.joinMeta,
+    leaveMeta: toRoomsResult.leaveMeta ?? prev.leaveMeta
+  };
+}
+function roomsFromData(data, toRooms) {
+  if (data == null) return { rooms: [] };
+  let state = { rooms: [] };
+  const add = (input) => {
+    const mergeForValue = (value) => {
+      state = mergeRoomState(state, toRooms(value));
+    };
+    if (Array.isArray(input)) {
+      input.forEach((entry) => mergeForValue(entry));
       return;
     }
-    const list = this.toArray(rooms);
-    const toLeave = [];
-    for (const r of list) {
-      const curr = this.roomCounts.get(r) ?? 0;
-      const next = Math.max(0, curr - 1);
-      if (next === 0 && curr > 0) toLeave.push(r);
-      if (next === 0) this.roomCounts.delete(r);
-      else this.roomCounts.set(r, next);
-    }
-    if (toLeave.length > 0 && this.socket) {
-      const payloadResult = this.roomLeaveSchema.safeParse({
-        rooms: toLeave,
-        meta
-      });
-      if (!payloadResult.success) {
-        this.rollbackLeaveDecrement(toLeave);
-        this.dbg({
-          type: "room",
-          phase: "leave",
-          rooms: toLeave,
-          err: "payload validation failed",
-          details: this.getValidationDetails(payloadResult.error)
-        });
+    if (input && typeof input === "object") {
+      const maybeItems = input.items;
+      if (Array.isArray(maybeItems)) {
+        maybeItems.forEach((entry) => mergeForValue(entry));
         return;
       }
-      const payload = payloadResult.data;
-      const normalizedRooms = this.toArray(payload.rooms);
-      this.socket.emit("sys:room_leave", payload);
-      this.dbg({ type: "room", phase: "leave", rooms: normalizedRooms });
     }
+    mergeForValue(input);
+  };
+  const maybePages = data?.pages;
+  if (Array.isArray(maybePages)) {
+    for (const page of maybePages) add(page);
+    return state;
   }
-  on(event, handler) {
-    const schema = this.events[event].message;
-    this.dbg({ type: "register", phase: "register", event });
-    if (!this.socket) {
-      this.dbg({
-        type: "register",
-        phase: "register",
-        event,
-        err: "Socket is null"
-      });
-      return () => {
-      };
-    }
-    const socket = this.socket;
-    const toStringList = (value) => Array.isArray(value) ? value.filter((entry2) => typeof entry2 === "string") : [];
-    const wrappedEnv = (envelope) => {
-      const rawData = envelope.data;
-      const parsed = schema.safeParse(rawData);
-      if (!parsed.success) {
-        this.dbg({
-          type: "receive",
-          event,
-          err: "payload_validation_failed",
-          details: this.getValidationDetails(parsed.error)
+  add(data);
+  return state;
+}
+
+// src/sockets/socketedRoute/socket.client.helper.route.ts
+function isSocketClientUnavailableError(err) {
+  return err instanceof Error && err.message.includes("SocketClient not found");
+}
+function buildSocketedRoute(options) {
+  const { built, toRooms, applySocket, useSocketClient: useSocketClient2, debug } = options;
+  const { useEndpoint: useInnerEndpoint, ...rest } = built;
+  const useEndpoint = (...useArgs) => {
+    let client = null;
+    let socketClientError = null;
+    try {
+      client = useSocketClient2();
+    } catch (err) {
+      if (!isSocketClientUnavailableError(err)) throw err;
+      socketClientError = err;
+    }
+    const endpointResult = useInnerEndpoint(
+      ...useArgs
+    );
+    const argsKey = (0, import_react4.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
+    const [roomState, setRoomState] = (0, import_react4.useState)(
+      () => roomsFromData(endpointResult.data, toRooms)
+    );
+    const renderCountRef = (0, import_react4.useRef)(0);
+    const clientReadyRef = (0, import_react4.useRef)(null);
+    const onReceiveEffectDebugRef = (0, import_react4.useRef)(null);
+    const deriveRoomsEffectDebugRef = (0, import_react4.useRef)(null);
+    const joinRoomsEffectDebugRef = (0, import_react4.useRef)(null);
+    const applySocketEffectDebugRef = (0, import_react4.useRef)(null);
+    renderCountRef.current += 1;
+    const roomsKey = (0, import_react4.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
+    const joinMetaKey = (0, import_react4.useMemo)(
+      () => safeJsonKey(roomState.joinMeta ?? null),
+      [roomState.joinMeta]
+    );
+    const leaveMetaKey = (0, import_react4.useMemo)(
+      () => safeJsonKey(roomState.leaveMeta ?? null),
+      [roomState.leaveMeta]
+    );
+    const hasClient = !!client;
+    if (clientReadyRef.current !== hasClient) {
+      clientReadyRef.current = hasClient;
+      dbg2(debug, {
+        type: "client",
+        phase: hasClient ? "ready" : "missing",
+        err: hasClient ? void 0 : String(socketClientError)
+      });
+    }
+    dbg2(debug, {
+      type: "render",
+      renderCount: renderCountRef.current,
+      hasClient,
+      argsKey,
+      rooms: roomState.rooms,
+      roomsKey,
+      joinMetaKey,
+      leaveMetaKey
+    });
+    (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: onReceiveEffectDebugRef,
+        phase: "endpoint_on_receive_effect",
+        debug,
+        snapshot: {
+          endpointResultRef: describeObjectReference(endpointResult),
+          endpointDataRef: describeObjectReference(endpointResult.data),
+          toRoomsRef: describeObjectReference(toRooms)
+        }
+      });
+      const unsubscribe = endpointResult.onReceive((data) => {
+        setRoomState((prev) => {
+          const next = mergeRoomState(prev, toRooms(data));
+          return roomStateEqual(prev, next) ? prev : next;
         });
-        return;
-      }
-      const data = parsed.data;
-      const receivedAt = /* @__PURE__ */ new Date();
-      const sentAt = envelope?.sentAt ? new Date(envelope.sentAt) : void 0;
-      const meta = {
-        envelope: {
-          eventName: typeof envelope?.eventName === "string" ? envelope.eventName : event,
-          sentAt: envelope?.sentAt ?? receivedAt.toISOString(),
-          sentTo: toStringList(envelope?.sentTo),
-          data,
-          metadata: envelope?.metadata,
-          rooms: toStringList(envelope?.rooms)
-        },
-        ctx: {
-          receivedAt,
-          latencyMs: sentAt ? Math.max(0, receivedAt.getTime() - sentAt.getTime()) : void 0,
-          nsp: this.getNamespace(socket),
-          socketId: socket.id,
-          socket
+      });
+      return unsubscribe;
+    }, [endpointResult, toRooms, debug]);
+    (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: deriveRoomsEffectDebugRef,
+        phase: "derive_rooms_effect",
+        debug,
+        snapshot: {
+          endpointDataRef: describeObjectReference(endpointResult.data),
+          toRoomsRef: describeObjectReference(toRooms)
         }
-      };
-      this.dbg({
-        type: "receive",
-        event,
-        envelope: this.debug.verbose ? {
-          eventName: meta.envelope.eventName,
-          sentAt: meta.envelope.sentAt,
-          sentTo: meta.envelope.sentTo,
-          metadata: meta.envelope.metadata
-        } : void 0
       });
-      handler(data, meta);
-    };
-    const wrappedDispatcher = (envelopeOrRaw) => {
-      if (typeof envelopeOrRaw === "object" && envelopeOrRaw !== null && "eventName" in envelopeOrRaw && "sentAt" in envelopeOrRaw && "sentTo" in envelopeOrRaw && "data" in envelopeOrRaw) {
-        wrappedEnv(envelopeOrRaw);
-      } else {
-        this.dbg({
-          type: "receive",
-          event,
-          envelope: void 0
+      const next = roomsFromData(
+        endpointResult.data,
+        toRooms
+      );
+      setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
+    }, [endpointResult.data, toRooms, debug]);
+    (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: joinRoomsEffectDebugRef,
+        phase: "join_rooms_effect",
+        debug,
+        snapshot: {
+          hasClient: !!client,
+          clientRef: describeObjectReference(client),
+          roomsKey,
+          joinMetaKey,
+          leaveMetaKey
+        }
+      });
+      if (!client) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: roomState.rooms,
+          reason: "socket_client_missing"
         });
-        handler(envelopeOrRaw, void 0);
-      }
-    };
-    const errorWrapped = (e) => {
-      this.dbg({ type: "receive", event, err: String(e) });
-    };
-    socket.on(String(event), wrappedDispatcher);
-    socket.on(`${String(event)}:error`, errorWrapped);
-    let set = this.handlerMap.get(String(event));
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.handlerMap.set(String(event), set);
-    }
-    const entry = {
-      orig: handler,
-      wrapped: wrappedDispatcher,
-      errorWrapped
-    };
-    set.add(entry);
-    return () => {
-      socket.off(String(event), wrappedDispatcher);
-      socket.off(`${String(event)}:error`, errorWrapped);
-      const s = this.handlerMap.get(String(event));
-      if (s) {
-        s.delete(entry);
-        if (s.size === 0) this.handlerMap.delete(String(event));
-      }
-      this.dbg({ type: "register", phase: "unregister", event });
-    };
-  }
-  /**
-   * Remove all listeners, stop timers, and leave rooms.
-   * Call when disposing the client instance.
-   */
-  async destroy(leaveMeta) {
-    const socket = this.socket;
-    this.dbg({
-      type: "lifecycle",
-      phase: "destroy_begin",
-      socketId: socket?.id,
-      details: {
-        roomsTracked: this.roomCounts.size,
-        handlerEvents: this.handlerMap.size
+        return;
       }
-    });
-    this.stopHeartbeat("destroy");
-    if (socket) {
-      socket.off("connect", this.onConnect);
-      socket.off("reconnect", this.onReconnect);
-      socket.off("disconnect", this.onDisconnect);
-      socket.off("connect_error", this.onConnectError);
-      socket.off("sys:pong", this.onPong);
-      for (const [event, set] of this.handlerMap.entries()) {
-        for (const entry of set) {
-          socket.off(String(event), entry.wrapped);
-          socket.off(`${String(event)}:error`, entry.errorWrapped);
-        }
+      if (roomState.rooms.length === 0) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: [],
+          reason: "no_rooms"
+        });
+        return;
       }
-    }
-    this.handlerMap.clear();
-    const toLeave = Array.from(this.roomCounts.entries()).filter(([, count]) => count > 0).map(([room]) => room);
-    if (toLeave.length > 0 && socket) {
-      await 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
+      const { joinMeta, leaveMeta } = roomState;
+      if (!joinMeta || !leaveMeta) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: roomState.rooms,
+          reason: "missing_meta"
+        });
+        return;
       }
-    });
-  }
-  /** Pass-throughs. Managing connection is the caller’s responsibility. */
-  disconnect() {
-    if (!this.socket) {
-      this.dbg({
-        type: "connection",
-        phase: "disconnect",
-        reason: "client_disconnect",
-        err: "Socket is null"
+      let active = true;
+      dbg2(debug, {
+        type: "room",
+        phase: "join_attempt",
+        rooms: roomState.rooms
       });
-      return;
-    }
-    this.stopHeartbeat("disconnect");
-    this.socket.disconnect();
-    this.dbg({
-      type: "connection",
-      phase: "disconnect",
-      reason: "client_disconnect",
-      details: {
-        nsp: this.getNamespace(this.socket)
-      }
-    });
-    this.logSocketConfigSnapshot("disconnect_call");
-  }
-  connect() {
-    if (!this.socket) {
-      this.dbg({
-        type: "connection",
-        phase: "connect",
-        err: "Socket is null"
+      (async () => {
+        try {
+          await client.joinRooms(roomState.rooms, joinMeta);
+        } catch (err) {
+          dbg2(debug, {
+            type: "room",
+            phase: "join_error",
+            rooms: roomState.rooms,
+            err: String(err)
+          });
+        }
+      })();
+      return () => {
+        if (!active) return;
+        active = false;
+        if (roomState.rooms.length === 0) {
+          dbg2(debug, {
+            type: "room",
+            phase: "leave_skip",
+            rooms: [],
+            reason: "no_rooms"
+          });
+          return;
+        }
+        dbg2(debug, {
+          type: "room",
+          phase: "leave_attempt",
+          rooms: roomState.rooms
+        });
+        void client.leaveRooms(roomState.rooms, leaveMeta).catch((err) => {
+          dbg2(debug, {
+            type: "room",
+            phase: "leave_error",
+            rooms: roomState.rooms,
+            err: String(err)
+          });
+        });
+      };
+    }, [client, roomsKey, joinMetaKey, leaveMetaKey, debug]);
+    (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: applySocketEffectDebugRef,
+        phase: "apply_socket_effect",
+        debug,
+        snapshot: {
+          hasClient: !!client,
+          clientRef: describeObjectReference(client),
+          applySocketKeys: Object.keys(applySocket).sort().join(","),
+          argsKey,
+          toRoomsRef: describeObjectReference(toRooms)
+        }
       });
-      return;
-    }
-    this.socket.connect();
-    this.dbg({
-      type: "connection",
-      phase: "connect",
-      id: this.socket.id ?? "",
-      details: {
-        nsp: this.getNamespace(this.socket)
-      }
-    });
-    this.logSocketConfigSnapshot("connect_call");
-  }
-};
+      if (!client) return;
+      const queue = [];
+      const sameRefWarnedEvents = /* @__PURE__ */ new Set();
+      let draining = false;
+      let active = true;
+      const drainQueue = () => {
+        if (!active || draining) return;
+        draining = true;
+        try {
+          while (active && queue.length > 0) {
+            const nextUpdate = queue.shift();
+            if (!nextUpdate) continue;
+            built.setData(
+              (prev) => {
+                const next = nextUpdate.fn(
+                  prev,
+                  nextUpdate.payload,
+                  nextUpdate.meta ? { ...nextUpdate.meta, args: useArgs } : { args: useArgs }
+                );
+                if (next === null) return prev;
+                if (shouldWarnSocketMutationGuard() && isSameObjectReference(prev, next) && !sameRefWarnedEvents.has(nextUpdate.event)) {
+                  sameRefWarnedEvents.add(nextUpdate.event);
+                  console.warn(
+                    `[socketedRoute] applySocket("${nextUpdate.event}") returned the previous reference. Return a new object/array for updates, or return null for no change.`
+                  );
+                }
+                const nextRoomState = roomsFromData(
+                  next,
+                  toRooms
+                );
+                setRoomState(
+                  (prevRoomState) => roomStateEqual(prevRoomState, nextRoomState) ? prevRoomState : nextRoomState
+                );
+                return next;
+              },
+              ...useArgs
+            );
+          }
+        } finally {
+          draining = false;
+          if (active && queue.length > 0) drainQueue();
+        }
+      };
+      const entries = Object.entries(applySocket).filter(
+        ([_event, fn]) => typeof fn === "function"
+      );
+      const unsubscribes = entries.map(
+        ([ev, fn]) => client.on(ev, (payload, meta) => {
+          queue.push({
+            event: ev,
+            fn,
+            payload,
+            ...meta ? { meta } : {}
+          });
+          drainQueue();
+        })
+      );
+      return () => {
+        active = false;
+        queue.length = 0;
+        unsubscribes.forEach((u) => u?.());
+      };
+    }, [client, applySocket, built, argsKey, toRooms, debug]);
+    return { ...endpointResult, rooms: roomState.rooms };
+  };
+  return {
+    ...rest,
+    useEndpoint
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HttpError,