cynx-lib 1.3.48 → 1.3.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cynx-lib",
-  "version": "1.3.48",
+  "version": "1.3.50",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/ui/components/ActionsMenu.jsx

@@ -120,11 +120,11 @@ export function ActionsMenu({ items, align = 'right' }) {
                   display: 'flex', alignItems: 'center', gap: 8,
                   padding: '6px 10px', borderRadius: 'var(--rads,8px)',
                   fontSize: 12, cursor: 'pointer', transition: 'all .14s',
-                  color: item.variant === 'danger' ? 'var(--danger, #f64747)' : item.variant === 'success' ? 'var(--success, #27ae60)' : item.variant === 'warning' ? 'var(--accent, #f99e2c)' : 'var(--text,#1a1a2e)',
+                  color: (item.variant === 'danger' || item.danger) ? 'var(--danger, #ef4444)' : item.variant === 'success' ? 'var(--success, #16a34a)' : item.variant === 'warning' ? 'var(--warning, #f59e0b)' : 'var(--primary-text, #18181b)',
                   fontWeight: 500,
                 }}
                 onMouseEnter={e => {
-                  e.currentTarget.style.background = item.variant === 'danger' ? 'var(--dd, rgba(246,71,71,.08))' : item.variant === 'warning' ? 'var(--pd, rgba(249,158,44,.08))' : 'var(--grey-1,#f5f5f8)';
+                  e.currentTarget.style.background = (item.variant === 'danger' || item.danger) ? 'var(--danger-bg, rgba(239,68,68,.10))' : item.variant === 'success' ? 'var(--success-bg, rgba(22,163,74,.10))' : item.variant === 'warning' ? 'var(--warning-bg, rgba(245,158,11,.12))' : 'var(--grey-1, #f4f4f5)';
                 }}
                 onMouseLeave={e => { e.currentTarget.style.background = 'transparent'; }}
               >

package/utils/utils/realtime.cjs

@@ -19,6 +19,9 @@ var realtime_exports = {};
 __export(realtime_exports, {
   ConnectedClient: () => ConnectedClient,
   EventBus: () => EventBus,
+  RealtimeClient: () => RealtimeClient,
+  RealtimeDispatcher: () => RealtimeDispatcher,
+  RealtimeProxy: () => RealtimeProxy,
   RealtimeServer: () => RealtimeServer,
   RealtimeSocket: () => RealtimeSocket,
   SSEStream: () => SSEStream,
@@ -26,11 +29,15 @@ __export(realtime_exports, {
   TabChannel: () => TabChannel,
   createEventBus: () => createEventBus,
   createPoller: () => createPoller,
+  createRealtimeClient: () => createRealtimeClient,
+  createRealtimeDispatcher: () => createRealtimeDispatcher,
+  createRealtimeProxy: () => createRealtimeProxy,
   createRealtimeServer: () => createRealtimeServer,
   createRealtimeSocket: () => createRealtimeSocket,
   createSSE: () => createSSE,
   createTabChannel: () => createTabChannel,
   default: () => realtime_default,
+  normalizeWsUrl: () => normalizeWsUrl,
   parseAIStream: () => parseAIStream
 });
 module.exports = __toCommonJS(realtime_exports);
@@ -844,10 +851,494 @@ class RealtimeServer {
 function createRealtimeServer(options) {
   return new RealtimeServer(options);
 }
+function normalizeWsUrl(rawUrl, defaultPath = "/ws") {
+  if (!rawUrl || typeof rawUrl !== "string") {
+    if (isBrowser) {
+      const isHttps2 = window.location.protocol === "https:";
+      const defaultScheme2 = isHttps2 ? "wss:" : "ws:";
+      return `${defaultScheme2}//${window.location.host}${defaultPath}`;
+    }
+    return "";
+  }
+  let url = rawUrl.trim();
+  const isHttps = isBrowser ? window.location.protocol === "https:" : false;
+  const defaultScheme = isHttps ? "wss:" : "ws:";
+  if (url.startsWith("//")) {
+    url = `${defaultScheme}${url}`;
+  } else if (url.startsWith("/")) {
+    if (isBrowser) {
+      url = `${defaultScheme}//${window.location.host}${url}`;
+    }
+  } else if (/^http:\/\//i.test(url)) {
+    url = url.replace(/^http:\/\//i, "ws://");
+  } else if (/^https:\/\//i.test(url)) {
+    url = url.replace(/^https:\/\//i, "wss://");
+  } else if (!/^wss?:\/\//i.test(url)) {
+    const isLocal = url.includes("localhost") || url.includes("127.0.0.1");
+    const scheme = isLocal && !isHttps ? "ws://" : "wss://";
+    url = `${scheme}${url}`;
+  }
+  try {
+    const httpEquivalent = url.replace(/^wss:/i, "https:").replace(/^ws:/i, "http:");
+    const parsed = new URL(httpEquivalent);
+    let pathname = parsed.pathname || defaultPath;
+    if (!pathname || pathname === "/") {
+      pathname = defaultPath;
+    }
+    pathname = pathname.replace(/\/+/g, "/").replace(/\/ws\/ws(\/|$)/g, "/ws$1");
+    const scheme = url.toLowerCase().startsWith("wss:") ? "wss:" : "ws:";
+    return `${scheme}//${parsed.host}${pathname}`;
+  } catch {
+    return url;
+  }
+}
+class RealtimeClient {
+  constructor(options = {}) {
+    const defaultUrl = isBrowser ? (window.location.protocol === "https:" ? "wss:" : "ws:") + "//" + window.location.host + "/ws" : "/ws";
+    this.options = {
+      url: defaultUrl,
+      token: void 0,
+      // string or function: () => token
+      room: void 0,
+      // optional room name or function: () => room
+      autoConnect: true,
+      reconnect: true,
+      maxRetries: Infinity,
+      initialRetryDelay: 1e3,
+      maxRetryDelay: 3e4,
+      backoffFactor: 1.5,
+      jitter: true,
+      heartbeatInterval: 2e4,
+      pingPayload: { type: "PING" },
+      ...options
+    };
+    this.events = new EventBus();
+    this.ws = null;
+    this.status = "DISCONNECTED";
+    this.retries = 0;
+    this._pingTimer = null;
+    this._reconnectTimer = null;
+    this._isExplicitClose = false;
+    this._connecting = false;
+    if (this.options.autoConnect) {
+      this.init();
+    }
+  }
+  getToken() {
+    if (typeof this.options.token === "function") {
+      return this.options.token();
+    }
+    if (typeof this.options.token === "string") {
+      return this.options.token;
+    }
+    if (isBrowser) {
+      return localStorage.getItem("token") || sessionStorage.getItem("token") || "";
+    }
+    return "";
+  }
+  getRoom() {
+    if (typeof this.options.room === "function") {
+      return this.options.room();
+    }
+    if (typeof this.options.room === "string") {
+      return this.options.room;
+    }
+    return "";
+  }
+  init() {
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) {
+      return;
+    }
+    const token = this.getToken();
+    if (!token && !this.options.anonymous) {
+      return;
+    }
+    this.connect();
+  }
+  connect() {
+    if (this._connecting) return;
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) return;
+    this._connecting = true;
+    this._isExplicitClose = false;
+    this.cleanup();
+    const WS = getWebSocketConstructor(this.options.WebSocket);
+    if (!WS) {
+      this._connecting = false;
+      console.warn("[cynx/realtime] WebSocket implementation not found in this environment.");
+      return;
+    }
+    try {
+      const rawUrl = typeof this.options.url === "function" ? this.options.url() : this.options.url;
+      const normalized = normalizeWsUrl(rawUrl);
+      const token = this.getToken();
+      const room = this.getRoom();
+      const urlObj = new URL(normalized.replace(/^ws:/i, "http:").replace(/^wss:/i, "https:"));
+      if (token && !urlObj.searchParams.has("token")) {
+        urlObj.searchParams.set("token", token);
+      }
+      if (room && !urlObj.searchParams.has("room")) {
+        urlObj.searchParams.set("room", room);
+      }
+      const finalScheme = normalized.toLowerCase().startsWith("wss:") ? "wss:" : "ws:";
+      const finalUrl = `${finalScheme}//${urlObj.host}${urlObj.pathname}${urlObj.search}`;
+      this.ws = new WS(finalUrl);
+      this.status = this.retries > 0 ? "RECONNECTING" : "CONNECTING";
+      this.ws.onopen = (e) => {
+        this._connecting = false;
+        this.retries = 0;
+        this.status = "CONNECTED";
+        this.events.emit("open", e);
+        this.events.emit("status", this.status);
+        this._startHeartbeat();
+      };
+      this.ws.onmessage = (event) => {
+        try {
+          const raw = typeof event.data === "string" ? event.data : String(event.data);
+          const parsed = safeJSONParse(raw, raw);
+          const eventType = parsed && typeof parsed === "object" ? parsed.type || parsed.event || "message" : "message";
+          if (parsed && parsed.type === "PONG") {
+            return;
+          }
+          this.events.emit(eventType, parsed);
+          this.events.emit("message", parsed);
+          this.events.emit("*", parsed);
+        } catch (err) {
+          console.warn("[cynx/realtime] Message parse warning:", err);
+        }
+      };
+      this.ws.onerror = (err) => {
+        this.events.emit("error", err);
+      };
+      this.ws.onclose = (e) => {
+        this._connecting = false;
+        this.status = "DISCONNECTED";
+        this._stopHeartbeat();
+        this.events.emit("close", e);
+        this.events.emit("status", this.status);
+        if (!this._isExplicitClose && this.options.reconnect && this.retries < this.options.maxRetries) {
+          this._handleReconnect();
+        }
+      };
+    } catch (err) {
+      this._connecting = false;
+      this._handleReconnect();
+    }
+  }
+  send(eventOrData, payload = void 0) {
+    if (!this.ws || this.ws.readyState !== 1) return false;
+    let message;
+    if (payload !== void 0) {
+      message = JSON.stringify({ type: eventOrData, payload });
+    } else if (typeof eventOrData === "object") {
+      message = JSON.stringify(eventOrData);
+    } else {
+      message = String(eventOrData);
+    }
+    this.ws.send(message);
+    return true;
+  }
+  emit(event, payload = void 0) {
+    return this.send(event, payload);
+  }
+  subscribe(callback) {
+    const unsub = this.events.on("*", callback);
+    this.init();
+    return unsub;
+  }
+  on(event, callback) {
+    const unsub = this.events.on(event, callback);
+    this.init();
+    return unsub;
+  }
+  once(event, callback) {
+    const unsub = this.events.once(event, callback);
+    this.init();
+    return unsub;
+  }
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+  disconnect(code = 1e3, reason = "Client disconnected") {
+    this._isExplicitClose = true;
+    this.cleanup();
+    if (this.ws) {
+      try {
+        this.ws.close(code, reason);
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.status = "DISCONNECTED";
+    this.events.emit("status", this.status);
+  }
+  cleanup() {
+    this._stopHeartbeat();
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+  }
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    if (!this.options.heartbeatInterval) return;
+    this._pingTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === 1) {
+        try {
+          this.ws.send(JSON.stringify(this.options.pingPayload));
+        } catch {
+        }
+      }
+    }, this.options.heartbeatInterval);
+  }
+  _stopHeartbeat() {
+    if (this._pingTimer) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+  }
+  _handleReconnect() {
+    if (this._reconnectTimer) return;
+    this.retries++;
+    const delay = Math.min(
+      this.options.initialRetryDelay * Math.pow(this.options.backoffFactor, this.retries - 1),
+      this.options.maxRetryDelay
+    );
+    const finalDelay = this.options.jitter ? delay * (0.8 + Math.random() * 0.4) : delay;
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.connect();
+    }, finalDelay);
+  }
+}
+function createRealtimeClient(options) {
+  return new RealtimeClient(options);
+}
+class RealtimeProxy {
+  constructor(server, options = {}) {
+    this.server = server;
+    this.options = {
+      path: "/ws",
+      upstreamUrl: void 0,
+      // process.env.WS_URL
+      upstreamKey: void 0,
+      // process.env.WS_KEY
+      room: "default",
+      // process.env.WS_ROOM
+      authenticate: void 0,
+      // async (req, token) => ({ userId })
+      WebSocket: void 0,
+      WebSocketServer: void 0,
+      ...options
+    };
+    this.wss = null;
+    this.events = new EventBus();
+    if (this.server) {
+      this.attach(this.server);
+    }
+  }
+  attach(server) {
+    this.server = server;
+    let WSS = this.options.WebSocketServer;
+    if (!WSS && typeof globalThis !== "undefined" && globalThis.WebSocketServer) {
+      WSS = globalThis.WebSocketServer;
+    }
+    if (!WSS) {
+      try {
+        const wsModule = typeof require === "function" ? require("ws") : null;
+        if (wsModule && wsModule.WebSocketServer) {
+          WSS = wsModule.WebSocketServer;
+        } else if (wsModule && wsModule.Server) {
+          WSS = wsModule.Server;
+        }
+      } catch {
+      }
+    }
+    if (!WSS) {
+      console.warn("[cynx/realtime] WebSocketServer not available for RealtimeProxy.");
+      return;
+    }
+    this.wss = new WSS({ noServer: true });
+    server.on("upgrade", async (request, socket, head) => {
+      try {
+        const url = new URL(request.url, `http://${request.headers.host || "localhost"}`);
+        if (url.pathname !== this.options.path) {
+          return;
+        }
+        const token = (url.searchParams.get("token") || request.headers["authorization"]?.replace(/^Bearer\s+/i, "") || request.headers["x-auth-token"] || "").trim();
+        let authData = null;
+        if (typeof this.options.authenticate === "function") {
+          authData = await this.options.authenticate(request, token);
+          if (!authData) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+          }
+        }
+        const room = (url.searchParams.get("room") || this.options.room || "default").trim().toLowerCase();
+        this.wss.handleUpgrade(request, socket, head, (clientWs) => {
+          this.wss.emit("connection", clientWs, request, { authData, room });
+        });
+      } catch (err) {
+        console.warn("[RealtimeProxy Upgrade Error]:", err.message);
+        try {
+          socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+          socket.destroy();
+        } catch {
+        }
+      }
+    });
+    this.wss.on("connection", (clientWs, request, { authData, room }) => {
+      this._handleConnection(clientWs, { authData, room });
+    });
+  }
+  _handleConnection(clientWs, { authData, room }) {
+    const WS_URL = this.options.upstreamUrl || (typeof process !== "undefined" ? process.env.WS_URL : "");
+    const WS_KEY = this.options.upstreamKey || (typeof process !== "undefined" ? process.env.WS_KEY : "");
+    const targetRoom = room || this.options.room || "default";
+    if (!WS_URL || !WS_KEY) {
+      clientWs.close(1011, "Real-Time upstream not configured");
+      return;
+    }
+    const upstreamBase = WS_URL.replace(/^http:\/\//i, "ws://").replace(/^https:\/\//i, "wss://").replace(/\/ws\/?$/i, "").replace(/\/$/, "");
+    const upstreamUrl = `${upstreamBase}/ws?room=${encodeURIComponent(targetRoom)}&token=${encodeURIComponent(WS_KEY)}`;
+    let WS = this.options.WebSocket;
+    if (!WS && typeof globalThis !== "undefined" && globalThis.WebSocket) {
+      WS = globalThis.WebSocket;
+    }
+    if (!WS) {
+      try {
+        const wsModule = typeof require === "function" ? require("ws") : null;
+        if (wsModule) WS = wsModule;
+      } catch {
+      }
+    }
+    if (!WS) {
+      clientWs.close(1011, "WebSocket client constructor not available");
+      return;
+    }
+    let upstreamWs = null;
+    try {
+      upstreamWs = new WS(upstreamUrl);
+    } catch (err) {
+      clientWs.close(1011, "Failed to connect upstream");
+      return;
+    }
+    upstreamWs.onmessage = (event) => {
+      if (clientWs.readyState === 1) {
+        clientWs.send(event.data);
+      }
+    };
+    if (typeof upstreamWs.on === "function") {
+      upstreamWs.on("message", (data, isBinary) => {
+        if (clientWs.readyState === 1) {
+          clientWs.send(data, { binary: isBinary });
+        }
+      });
+      upstreamWs.on("error", (err) => {
+        console.warn("[RealtimeProxy Upstream Error]:", err.message);
+        if (clientWs.readyState === 1) clientWs.close(1011, "Upstream error");
+      });
+      upstreamWs.on("close", (code, reason) => {
+        if (clientWs.readyState === 1) clientWs.close(code, reason);
+      });
+    }
+    if (typeof clientWs.on === "function") {
+      clientWs.on("message", (data, isBinary) => {
+        if (upstreamWs && upstreamWs.readyState === 1) {
+          upstreamWs.send(data, { binary: isBinary });
+        }
+      });
+      clientWs.on("error", () => {
+        if (upstreamWs && upstreamWs.readyState === 1) upstreamWs.close();
+      });
+      clientWs.on("close", () => {
+        if (upstreamWs && upstreamWs.readyState === 1) upstreamWs.close();
+      });
+    }
+  }
+}
+function createRealtimeProxy(server, options) {
+  return new RealtimeProxy(server, options);
+}
+class RealtimeDispatcher {
+  constructor(options = {}) {
+    this.options = {
+      url: void 0,
+      // process.env.WS_URL
+      key: void 0,
+      // process.env.WS_KEY
+      room: void 0,
+      // process.env.WS_ROOM
+      fetch: typeof globalThis !== "undefined" ? globalThis.fetch : void 0,
+      ...options
+    };
+  }
+  async broadcast(eventType, payload = {}, options = {}) {
+    const rawUrl = options.url || this.options.url || (typeof process !== "undefined" ? process.env.WS_URL : "");
+    const key = options.key || this.options.key || (typeof process !== "undefined" ? process.env.WS_KEY : "");
+    const room = (options.room || this.options.room || (typeof process !== "undefined" ? process.env.WS_ROOM : "") || "").trim().toLowerCase();
+    if (!rawUrl || !key || !room) {
+      return { ok: false, error: "Missing WS_URL, WS_KEY, or WS_ROOM configuration" };
+    }
+    const fetchFn = this.options.fetch || globalThis.fetch;
+    if (!fetchFn) {
+      return { ok: false, error: "fetch function not found in environment" };
+    }
+    const baseUrl = rawUrl.replace(/^ws:\/\//i, "http://").replace(/^wss:\/\//i, "https://").replace(/\/ws\/?$/i, "").replace(/\/$/, "");
+    const endpoint = `${baseUrl}/api/broadcast?room=${encodeURIComponent(room)}`;
+    const body = JSON.stringify({
+      type: eventType,
+      room,
+      payload,
+      timestamp: Date.now(),
+      ...options.extra
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Secret-Key": key,
+      "x-ws-token": key,
+      "x-room": room,
+      "Authorization": `Bearer ${key}`
+    };
+    try {
+      let res = await fetchFn(endpoint, {
+        method: "POST",
+        headers,
+        body
+      });
+      if (res.status === 404) {
+        const legacyEndpoint = `${baseUrl}/broadcast?room=${encodeURIComponent(room)}`;
+        res = await fetchFn(legacyEndpoint, { method: "POST", headers, body });
+      }
+      if (!res.ok) {
+        const errText = await res.text().catch(() => "");
+        console.warn(`[cynx/realtime] Broadcast warning (${res.status}):`, errText);
+        return { ok: false, status: res.status, error: errText };
+      }
+      const data = await res.json().catch(() => ({ status: "ok" }));
+      return { ok: true, data };
+    } catch (err) {
+      console.warn("[cynx/realtime] Broadcast network error:", err.message);
+      return { ok: false, error: err.message };
+    }
+  }
+  async broadcastSession(token, eventType, payload = {}, options = {}) {
+    return this.broadcast("session_event", payload, {
+      ...options,
+      extra: { token, eventType, sessionToken: token }
+    });
+  }
+}
+function createRealtimeDispatcher(options) {
+  return new RealtimeDispatcher(options);
+}
 var realtime_default = {
   // Client
   RealtimeSocket,
   createRealtimeSocket,
+  RealtimeClient,
+  createRealtimeClient,
+  normalizeWsUrl,
   SSEStream,
   createSSE,
   parseAIStream,
@@ -860,12 +1351,19 @@ var realtime_default = {
   // Server
   ConnectedClient,
   RealtimeServer,
-  createRealtimeServer
+  createRealtimeServer,
+  RealtimeProxy,
+  createRealtimeProxy,
+  RealtimeDispatcher,
+  createRealtimeDispatcher
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectedClient,
   EventBus,
+  RealtimeClient,
+  RealtimeDispatcher,
+  RealtimeProxy,
   RealtimeServer,
   RealtimeSocket,
   SSEStream,
@@ -873,9 +1371,13 @@ var realtime_default = {
   TabChannel,
   createEventBus,
   createPoller,
+  createRealtimeClient,
+  createRealtimeDispatcher,
+  createRealtimeProxy,
   createRealtimeServer,
   createRealtimeSocket,
   createSSE,
   createTabChannel,
+  normalizeWsUrl,
   parseAIStream
 });

package/utils/utils/realtime.js

@@ -1018,12 +1018,602 @@ export function createRealtimeServer(options) {
   return new RealtimeServer(options);
 }
 
+// ─── 7. UNIVERSAL URL NORMALIZER ────────────────────────────────────────────────
+/**
+ * Normalizes HTTP/HTTPS/WS/WSS and relative URLs into valid WebSocket endpoints.
+ * Automatically removes accidental duplicate /ws paths or trailing slashes.
+ */
+export function normalizeWsUrl(rawUrl, defaultPath = '/ws') {
+  if (!rawUrl || typeof rawUrl !== 'string') {
+    if (isBrowser) {
+      const isHttps = window.location.protocol === 'https:';
+      const defaultScheme = isHttps ? 'wss:' : 'ws:';
+      return `${defaultScheme}//${window.location.host}${defaultPath}`;
+    }
+    return '';
+  }
+
+  let url = rawUrl.trim();
+  const isHttps = isBrowser ? window.location.protocol === 'https:' : false;
+  const defaultScheme = isHttps ? 'wss:' : 'ws:';
+
+  // 1. Protocol-relative URL: //example.com/ws
+  if (url.startsWith('//')) {
+    url = `${defaultScheme}${url}`;
+  }
+  // 2. Relative path: /ws
+  else if (url.startsWith('/')) {
+    if (isBrowser) {
+      url = `${defaultScheme}//${window.location.host}${url}`;
+    }
+  }
+  // 3. HTTP -> WS
+  else if (/^http:\/\//i.test(url)) {
+    url = url.replace(/^http:\/\//i, 'ws://');
+  }
+  // 4. HTTPS -> WSS
+  else if (/^https:\/\//i.test(url)) {
+    url = url.replace(/^https:\/\//i, 'wss://');
+  }
+  // 5. Raw host without scheme
+  else if (!/^wss?:\/\//i.test(url)) {
+    const isLocal = url.includes('localhost') || url.includes('127.0.0.1');
+    const scheme = isLocal && !isHttps ? 'ws://' : 'wss://';
+    url = `${scheme}${url}`;
+  }
+
+  // Ensure path is normalized without duplicate /ws/ws
+  try {
+    const httpEquivalent = url.replace(/^wss:/i, 'https:').replace(/^ws:/i, 'http:');
+    const parsed = new URL(httpEquivalent);
+    let pathname = parsed.pathname || defaultPath;
+    if (!pathname || pathname === '/') {
+      pathname = defaultPath;
+    }
+    pathname = pathname.replace(/\/+/g, '/').replace(/\/ws\/ws(\/|$)/g, '/ws$1');
+    const scheme = url.toLowerCase().startsWith('wss:') ? 'wss:' : 'ws:';
+    return `${scheme}//${parsed.host}${pathname}`;
+  } catch {
+    return url;
+  }
+}
+
+// ─── 8. UNIVERSAL REALTIME FRONTEND CLIENT ──────────────────────────────────────
+/**
+ * Universal Realtime Client for frontends/browsers.
+ * Manages WebSocket connections through proxy or direct, user token resolution,
+ * automatic heartbeat ping-pong, typed event bus, and global subscriptions.
+ */
+export class RealtimeClient {
+  constructor(options = {}) {
+    const defaultUrl = isBrowser ? (window.location.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + window.location.host + '/ws' : '/ws';
+    this.options = {
+      url: defaultUrl,
+      token: undefined, // string or function: () => token
+      room: undefined,  // optional room name or function: () => room
+      autoConnect: true,
+      reconnect: true,
+      maxRetries: Infinity,
+      initialRetryDelay: 1000,
+      maxRetryDelay: 30000,
+      backoffFactor: 1.5,
+      jitter: true,
+      heartbeatInterval: 20000,
+      pingPayload: { type: 'PING' },
+      ...options,
+    };
+
+    this.events = new EventBus();
+    this.ws = null;
+    this.status = 'DISCONNECTED';
+    this.retries = 0;
+    this._pingTimer = null;
+    this._reconnectTimer = null;
+    this._isExplicitClose = false;
+    this._connecting = false;
+
+    if (this.options.autoConnect) {
+      this.init();
+    }
+  }
+
+  getToken() {
+    if (typeof this.options.token === 'function') {
+      return this.options.token();
+    }
+    if (typeof this.options.token === 'string') {
+      return this.options.token;
+    }
+    if (isBrowser) {
+      return localStorage.getItem('token') || sessionStorage.getItem('token') || '';
+    }
+    return '';
+  }
+
+  getRoom() {
+    if (typeof this.options.room === 'function') {
+      return this.options.room();
+    }
+    if (typeof this.options.room === 'string') {
+      return this.options.room;
+    }
+    return '';
+  }
+
+  init() {
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) {
+      return;
+    }
+    const token = this.getToken();
+    if (!token && !this.options.anonymous) {
+      return; // Wait until token is available
+    }
+    this.connect();
+  }
+
+  connect() {
+    if (this._connecting) return;
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) return;
+
+    this._connecting = true;
+    this._isExplicitClose = false;
+    this.cleanup();
+
+    const WS = getWebSocketConstructor(this.options.WebSocket);
+    if (!WS) {
+      this._connecting = false;
+      console.warn('[cynx/realtime] WebSocket implementation not found in this environment.');
+      return;
+    }
+
+    try {
+      const rawUrl = typeof this.options.url === 'function' ? this.options.url() : this.options.url;
+      const normalized = normalizeWsUrl(rawUrl);
+      const token = this.getToken();
+      const room = this.getRoom();
+
+      const urlObj = new URL(normalized.replace(/^ws:/i, 'http:').replace(/^wss:/i, 'https:'));
+      if (token && !urlObj.searchParams.has('token')) {
+        urlObj.searchParams.set('token', token);
+      }
+      if (room && !urlObj.searchParams.has('room')) {
+        urlObj.searchParams.set('room', room);
+      }
+
+      const finalScheme = normalized.toLowerCase().startsWith('wss:') ? 'wss:' : 'ws:';
+      const finalUrl = `${finalScheme}//${urlObj.host}${urlObj.pathname}${urlObj.search}`;
+
+      this.ws = new WS(finalUrl);
+      this.status = this.retries > 0 ? 'RECONNECTING' : 'CONNECTING';
+
+      this.ws.onopen = (e) => {
+        this._connecting = false;
+        this.retries = 0;
+        this.status = 'CONNECTED';
+        this.events.emit('open', e);
+        this.events.emit('status', this.status);
+        this._startHeartbeat();
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const raw = typeof event.data === 'string' ? event.data : String(event.data);
+          const parsed = safeJSONParse(raw, raw);
+          const eventType = (parsed && typeof parsed === 'object') ? (parsed.type || parsed.event || 'message') : 'message';
+
+          if (parsed && parsed.type === 'PONG') {
+            return;
+          }
+
+          this.events.emit(eventType, parsed);
+          this.events.emit('message', parsed);
+          this.events.emit('*', parsed);
+        } catch (err) {
+          console.warn('[cynx/realtime] Message parse warning:', err);
+        }
+      };
+
+      this.ws.onerror = (err) => {
+        this.events.emit('error', err);
+      };
+
+      this.ws.onclose = (e) => {
+        this._connecting = false;
+        this.status = 'DISCONNECTED';
+        this._stopHeartbeat();
+        this.events.emit('close', e);
+        this.events.emit('status', this.status);
+
+        if (!this._isExplicitClose && this.options.reconnect && this.retries < this.options.maxRetries) {
+          this._handleReconnect();
+        }
+      };
+    } catch (err) {
+      this._connecting = false;
+      this._handleReconnect();
+    }
+  }
+
+  send(eventOrData, payload = undefined) {
+    if (!this.ws || this.ws.readyState !== 1) return false;
+    let message;
+    if (payload !== undefined) {
+      message = JSON.stringify({ type: eventOrData, payload });
+    } else if (typeof eventOrData === 'object') {
+      message = JSON.stringify(eventOrData);
+    } else {
+      message = String(eventOrData);
+    }
+    this.ws.send(message);
+    return true;
+  }
+
+  emit(event, payload = undefined) {
+    return this.send(event, payload);
+  }
+
+  subscribe(callback) {
+    const unsub = this.events.on('*', callback);
+    this.init();
+    return unsub;
+  }
+
+  on(event, callback) {
+    const unsub = this.events.on(event, callback);
+    this.init();
+    return unsub;
+  }
+
+  once(event, callback) {
+    const unsub = this.events.once(event, callback);
+    this.init();
+    return unsub;
+  }
+
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  disconnect(code = 1000, reason = 'Client disconnected') {
+    this._isExplicitClose = true;
+    this.cleanup();
+    if (this.ws) {
+      try { this.ws.close(code, reason); } catch {}
+      this.ws = null;
+    }
+    this.status = 'DISCONNECTED';
+    this.events.emit('status', this.status);
+  }
+
+  cleanup() {
+    this._stopHeartbeat();
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    if (!this.options.heartbeatInterval) return;
+    this._pingTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === 1) {
+        try {
+          this.ws.send(JSON.stringify(this.options.pingPayload));
+        } catch {}
+      }
+    }, this.options.heartbeatInterval);
+  }
+
+  _stopHeartbeat() {
+    if (this._pingTimer) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+  }
+
+  _handleReconnect() {
+    if (this._reconnectTimer) return;
+    this.retries++;
+    const delay = Math.min(
+      this.options.initialRetryDelay * Math.pow(this.options.backoffFactor, this.retries - 1),
+      this.options.maxRetryDelay
+    );
+    const finalDelay = this.options.jitter ? delay * (0.8 + Math.random() * 0.4) : delay;
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.connect();
+    }, finalDelay);
+  }
+}
+
+export function createRealtimeClient(options) {
+  return new RealtimeClient(options);
+}
+
+// ─── 9. UNIVERSAL BACKEND WEBSOCKET PROXY / REPEATER ────────────────────────────
+/**
+ * Universal WebSocket Repeater/Proxy for application backends.
+ * Intercepts /ws upgrades, validates client sessions (protecting master WS_KEY),
+ * and safely pipes traffic to/from upstream ws-server.
+ */
+export class RealtimeProxy {
+  constructor(server, options = {}) {
+    this.server = server;
+    this.options = {
+      path: '/ws',
+      upstreamUrl: undefined, // process.env.WS_URL
+      upstreamKey: undefined, // process.env.WS_KEY
+      room: 'default',        // process.env.WS_ROOM
+      authenticate: undefined,// async (req, token) => ({ userId })
+      WebSocket: undefined,
+      WebSocketServer: undefined,
+      ...options,
+    };
+
+    this.wss = null;
+    this.events = new EventBus();
+
+    if (this.server) {
+      this.attach(this.server);
+    }
+  }
+
+  attach(server) {
+    this.server = server;
+    let WSS = this.options.WebSocketServer;
+    if (!WSS && typeof globalThis !== 'undefined' && globalThis.WebSocketServer) {
+      WSS = globalThis.WebSocketServer;
+    }
+
+    if (!WSS) {
+      try {
+        const wsModule = typeof require === 'function' ? require('ws') : null;
+        if (wsModule && wsModule.WebSocketServer) {
+          WSS = wsModule.WebSocketServer;
+        } else if (wsModule && wsModule.Server) {
+          WSS = wsModule.Server;
+        }
+      } catch {}
+    }
+
+    if (!WSS) {
+      console.warn('[cynx/realtime] WebSocketServer not available for RealtimeProxy.');
+      return;
+    }
+
+    this.wss = new WSS({ noServer: true });
+
+    server.on('upgrade', async (request, socket, head) => {
+      try {
+        const url = new URL(request.url, `http://${request.headers.host || 'localhost'}`);
+        if (url.pathname !== this.options.path) {
+          return;
+        }
+
+        const token = (
+          url.searchParams.get('token') ||
+          request.headers['authorization']?.replace(/^Bearer\s+/i, '') ||
+          request.headers['x-auth-token'] ||
+          ''
+        ).trim();
+
+        let authData = null;
+        if (typeof this.options.authenticate === 'function') {
+          authData = await this.options.authenticate(request, token);
+          if (!authData) {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+          }
+        }
+
+        const room = (url.searchParams.get('room') || this.options.room || 'default').trim().toLowerCase();
+
+        this.wss.handleUpgrade(request, socket, head, (clientWs) => {
+          this.wss.emit('connection', clientWs, request, { authData, room });
+        });
+      } catch (err) {
+        console.warn('[RealtimeProxy Upgrade Error]:', err.message);
+        try {
+          socket.write('HTTP/1.1 500 Internal Server Error\r\n\r\n');
+          socket.destroy();
+        } catch {}
+      }
+    });
+
+    this.wss.on('connection', (clientWs, request, { authData, room }) => {
+      this._handleConnection(clientWs, { authData, room });
+    });
+  }
+
+  _handleConnection(clientWs, { authData, room }) {
+    const WS_URL = this.options.upstreamUrl || (typeof process !== 'undefined' ? process.env.WS_URL : '');
+    const WS_KEY = this.options.upstreamKey || (typeof process !== 'undefined' ? process.env.WS_KEY : '');
+    const targetRoom = room || this.options.room || 'default';
+
+    if (!WS_URL || !WS_KEY) {
+      clientWs.close(1011, 'Real-Time upstream not configured');
+      return;
+    }
+
+    // Rock-solid URL normalization: strip duplicate /ws/
+    const upstreamBase = WS_URL
+      .replace(/^http:\/\//i, 'ws://')
+      .replace(/^https:\/\//i, 'wss://')
+      .replace(/\/ws\/?$/i, '')
+      .replace(/\/$/, '');
+
+    const upstreamUrl = `${upstreamBase}/ws?room=${encodeURIComponent(targetRoom)}&token=${encodeURIComponent(WS_KEY)}`;
+
+    let WS = this.options.WebSocket;
+    if (!WS && typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+      WS = globalThis.WebSocket;
+    }
+    if (!WS) {
+      try {
+        const wsModule = typeof require === 'function' ? require('ws') : null;
+        if (wsModule) WS = wsModule;
+      } catch {}
+    }
+
+    if (!WS) {
+      clientWs.close(1011, 'WebSocket client constructor not available');
+      return;
+    }
+
+    let upstreamWs = null;
+    try {
+      upstreamWs = new WS(upstreamUrl);
+    } catch (err) {
+      clientWs.close(1011, 'Failed to connect upstream');
+      return;
+    }
+
+    // Upstream -> Client
+    upstreamWs.onmessage = (event) => {
+      if (clientWs.readyState === 1) {
+        clientWs.send(event.data);
+      }
+    };
+    if (typeof upstreamWs.on === 'function') {
+      upstreamWs.on('message', (data, isBinary) => {
+        if (clientWs.readyState === 1) {
+          clientWs.send(data, { binary: isBinary });
+        }
+      });
+      upstreamWs.on('error', (err) => {
+        console.warn('[RealtimeProxy Upstream Error]:', err.message);
+        if (clientWs.readyState === 1) clientWs.close(1011, 'Upstream error');
+      });
+      upstreamWs.on('close', (code, reason) => {
+        if (clientWs.readyState === 1) clientWs.close(code, reason);
+      });
+    }
+
+    // Client -> Upstream
+    if (typeof clientWs.on === 'function') {
+      clientWs.on('message', (data, isBinary) => {
+        if (upstreamWs && upstreamWs.readyState === 1) {
+          upstreamWs.send(data, { binary: isBinary });
+        }
+      });
+      clientWs.on('error', () => {
+        if (upstreamWs && upstreamWs.readyState === 1) upstreamWs.close();
+      });
+      clientWs.on('close', () => {
+        if (upstreamWs && upstreamWs.readyState === 1) upstreamWs.close();
+      });
+    }
+  }
+}
+
+export function createRealtimeProxy(server, options) {
+  return new RealtimeProxy(server, options);
+}
+
+// ─── 10. UNIVERSAL REALTIME DISPATCHER (HTTP BROADCASTER) ───────────────────────
+/**
+ * Universal Event Broadcaster for backend services and microservices.
+ * Sends broadcast events to ws-server via HTTP REST (POST /api/broadcast and /broadcast).
+ */
+export class RealtimeDispatcher {
+  constructor(options = {}) {
+    this.options = {
+      url: undefined,  // process.env.WS_URL
+      key: undefined,  // process.env.WS_KEY
+      room: undefined, // process.env.WS_ROOM
+      fetch: typeof globalThis !== 'undefined' ? globalThis.fetch : undefined,
+      ...options,
+    };
+  }
+
+  async broadcast(eventType, payload = {}, options = {}) {
+    const rawUrl = options.url || this.options.url || (typeof process !== 'undefined' ? process.env.WS_URL : '');
+    const key = options.key || this.options.key || (typeof process !== 'undefined' ? process.env.WS_KEY : '');
+    const room = (options.room || this.options.room || (typeof process !== 'undefined' ? process.env.WS_ROOM : '') || '').trim().toLowerCase();
+
+    if (!rawUrl || !key || !room) {
+      return { ok: false, error: 'Missing WS_URL, WS_KEY, or WS_ROOM configuration' };
+    }
+
+    const fetchFn = this.options.fetch || globalThis.fetch;
+    if (!fetchFn) {
+      return { ok: false, error: 'fetch function not found in environment' };
+    }
+
+    const baseUrl = rawUrl
+      .replace(/^ws:\/\//i, 'http://')
+      .replace(/^wss:\/\//i, 'https://')
+      .replace(/\/ws\/?$/i, '')
+      .replace(/\/$/, '');
+
+    const endpoint = `${baseUrl}/api/broadcast?room=${encodeURIComponent(room)}`;
+    const body = JSON.stringify({
+      type: eventType,
+      room,
+      payload,
+      timestamp: Date.now(),
+      ...options.extra,
+    });
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-Secret-Key': key,
+      'x-ws-token': key,
+      'x-room': room,
+      'Authorization': `Bearer ${key}`,
+    };
+
+    try {
+      let res = await fetchFn(endpoint, {
+        method: 'POST',
+        headers,
+        body,
+      });
+
+      // Fallback to legacy /broadcast if /api/broadcast returned 404
+      if (res.status === 404) {
+        const legacyEndpoint = `${baseUrl}/broadcast?room=${encodeURIComponent(room)}`;
+        res = await fetchFn(legacyEndpoint, { method: 'POST', headers, body });
+      }
+
+      if (!res.ok) {
+        const errText = await res.text().catch(() => '');
+        console.warn(`[cynx/realtime] Broadcast warning (${res.status}):`, errText);
+        return { ok: false, status: res.status, error: errText };
+      }
+
+      const data = await res.json().catch(() => ({ status: 'ok' }));
+      return { ok: true, data };
+    } catch (err) {
+      console.warn('[cynx/realtime] Broadcast network error:', err.message);
+      return { ok: false, error: err.message };
+    }
+  }
+
+  async broadcastSession(token, eventType, payload = {}, options = {}) {
+    return this.broadcast('session_event', payload, {
+      ...options,
+      extra: { token, eventType, sessionToken: token },
+    });
+  }
+}
+
+export function createRealtimeDispatcher(options) {
+  return new RealtimeDispatcher(options);
+}
+
 // ─── MAIN EXPORT ────────────────────────────────────────────────────────────────
 
 export default {
   // Client
   RealtimeSocket,
   createRealtimeSocket,
+  RealtimeClient,
+  createRealtimeClient,
+  normalizeWsUrl,
   SSEStream,
   createSSE,
   parseAIStream,
@@ -1037,4 +1627,8 @@ export default {
   ConnectedClient,
   RealtimeServer,
   createRealtimeServer,
+  RealtimeProxy,
+  createRealtimeProxy,
+  RealtimeDispatcher,
+  createRealtimeDispatcher,
 };