cynx-lib 1.3.83 → 1.3.85

package/utils/utils/realtime.js

@@ -1,1634 +1,1634 @@
-/**
- * cynx/utils — Universal Realtime Engine (realtime.js)
- *
- * All-in-one realtime utility covering:
- *  1. Smart WebSocket client (auto-reconnect with backoff, heartbeat/ping-pong, offline queue, pub/sub, request-response)
- *  2. SSE (Server-Sent Events) streamer with AI stream parser
- *  3. Cross-Tab / Cross-Window Synchronization (BroadcastChannel + LocalStorage fallback)
- *  4. Smart Poller (pause on hidden tab, backoff, jitter)
- *  5. Lightweight Event Bus / PubSub
- *
- * Compatible with Browser, Node.js, SSR, Web Workers.
- * Zero external dependencies.
- */
-
-import { uid } from './uid.js';
-
-// ─── UTILITIES & HELPERS ────────────────────────────────────────────────────────
-
-const isBrowser = typeof window !== 'undefined';
-const isDocAvailable = typeof document !== 'undefined';
-
-function safeJSONParse(str, fallback = null) {
-  try {
-    return JSON.parse(str);
-  } catch {
-    return fallback !== null ? fallback : str;
-  }
-}
-
-function getWebSocketConstructor(customWs) {
-  if (customWs) return customWs;
-  if (typeof WebSocket !== 'undefined') return WebSocket;
-  if (typeof globalThis !== 'undefined' && globalThis.WebSocket) return globalThis.WebSocket;
-  return null;
-}
-
-// ─── 1. EVENT BUS (LIGHTWEIGHT PUB/SUB) ─────────────────────────────────────────
-
-export class EventBus {
-  constructor() {
-    this._listeners = new Map();
-  }
-
-  on(event, callback) {
-    if (typeof callback !== 'function') return () => {};
-    if (!this._listeners.has(event)) {
-      this._listeners.set(event, new Set());
-    }
-    this._listeners.get(event).add(callback);
-    return () => this.off(event, callback);
-  }
-
-  once(event, callback) {
-    const unsub = this.on(event, (...args) => {
-      unsub();
-      callback(...args);
-    });
-    return unsub;
-  }
-
-  off(event, callback) {
-    if (!this._listeners.has(event)) return;
-    if (!callback) {
-      this._listeners.delete(event);
-      return;
-    }
-    const set = this._listeners.get(event);
-    set.delete(callback);
-    if (set.size === 0) this._listeners.delete(event);
-  }
-
-  emit(event, ...args) {
-    // Direct matches
-    if (this._listeners.has(event)) {
-      for (const cb of this._listeners.get(event)) {
-        try {
-          cb(...args);
-        } catch (err) {
-          console.error(`[cynx/realtime] Error in handler for event "${event}":`, err);
-        }
-      }
-    }
-    // Wildcard matches (e.g. '*')
-    if (event !== '*' && this._listeners.has('*')) {
-      for (const cb of this._listeners.get('*')) {
-        try {
-          cb(event, ...args);
-        } catch (err) {
-          console.error('[cynx/realtime] Error in wildcard handler:', err);
-        }
-      }
-    }
-  }
-
-  clear() {
-    this._listeners.clear();
-  }
-}
-
-export function createEventBus() {
-  return new EventBus();
-}
-
-// ─── 2. SMART WEBSOCKET CLIENT ──────────────────────────────────────────────────
-
-/**
- * Universal WebSocket Client with:
- * - Auto-reconnect with exponential backoff & random jitter
- * - Heartbeat (Ping/Pong keep-alive)
- * - Offline message queue
- * - Event-based messaging (topic/event pub-sub)
- * - Request-Response pattern over WebSocket
- */
-export class RealtimeSocket {
-  constructor(url, options = {}) {
-    this.url = url;
-    this.options = {
-      reconnect: true,
-      maxRetries: Infinity,
-      initialRetryDelay: 1000,
-      maxRetryDelay: 30000,
-      backoffFactor: 1.5,
-      jitter: true,
-      protocols: undefined,
-      heartbeat: {
-        enabled: true,
-        interval: 25000,
-        pingPayload: JSON.stringify({ type: 'ping' }),
-        pongPattern: 'pong',
-        timeout: 10000,
-      },
-      queueOffline: true,
-      maxQueueSize: 100,
-      autoConnect: true,
-      WebSocket: undefined,
-      ...options,
-    };
-
-    this.events = new EventBus();
-    this.ws = null;
-    this.status = 'DISCONNECTED'; // 'CONNECTING' | 'CONNECTED' | 'DISCONNECTED' | 'RECONNECTING'
-    this.retries = 0;
-    this._offlineQueue = [];
-    this._pendingRequests = new Map();
-    this._heartbeatTimer = null;
-    this._heartbeatTimeoutTimer = null;
-    this._reconnectTimer = null;
-    this._isExplicitClose = false;
-
-    if (this.options.autoConnect) {
-      this.connect();
-    }
-  }
-
-  connect() {
-    if (!isBrowser && !this.options.WebSocket && typeof globalThis.WebSocket === 'undefined') {
-      return;
-    }
-    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) {
-      return;
-    }
-
-    this._isExplicitClose = false;
-    this._setStatus(this.retries > 0 ? 'RECONNECTING' : 'CONNECTING');
-
-    const WS = getWebSocketConstructor(this.options.WebSocket);
-    if (!WS) {
-      console.warn('[cynx/realtime] WebSocket implementation not found in this environment.');
-      return;
-    }
-
-    try {
-      const targetUrl = typeof this.url === 'function' ? this.url() : this.url;
-      this.ws = this.options.protocols
-        ? new WS(targetUrl, this.options.protocols)
-        : new WS(targetUrl);
-
-      this.ws.onopen = (e) => this._onOpen(e);
-      this.ws.onmessage = (e) => this._onMessage(e);
-      this.ws.onerror = (e) => this._onError(e);
-      this.ws.onclose = (e) => this._onClose(e);
-    } catch (err) {
-      this._handleReconnect();
-    }
-  }
-
-  disconnect(code = 1000, reason = 'Client disconnected') {
-    this._isExplicitClose = true;
-    this._clearTimers();
-    if (this.ws) {
-      this.ws.close(code, reason);
-      this.ws = null;
-    }
-    this._setStatus('DISCONNECTED');
-  }
-
-  /**
-   * Send data or a typed event payload.
-   * If offline and queueOffline=true, queues the message until reconnect.
-   */
-  send(eventOrData, payload = undefined) {
-    let message;
-    if (payload !== undefined) {
-      message = JSON.stringify({ event: eventOrData, data: payload });
-    } else if (typeof eventOrData === 'object') {
-      message = JSON.stringify(eventOrData);
-    } else {
-      message = String(eventOrData);
-    }
-
-    if (this.isConnected()) {
-      this.ws.send(message);
-      return true;
-    }
-
-    if (this.options.queueOffline) {
-      if (this._offlineQueue.length >= this.options.maxQueueSize) {
-        this._offlineQueue.shift(); // Drop oldest message
-      }
-      this._offlineQueue.push(message);
-      return false;
-    }
-
-    return false;
-  }
-
-  /**
-   * Perform a Request-Response interaction over WebSocket.
-   * Attaches a correlation `requestId` and resolves when server replies.
-   */
-  request(action, data = {}, { timeout = 10000 } = {}) {
-    return new Promise((resolve, reject) => {
-      const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
-      const timer = setTimeout(() => {
-        if (this._pendingRequests.has(requestId)) {
-          this._pendingRequests.delete(requestId);
-          reject(new Error(`[cynx/realtime] Request "${action}" timed out after ${timeout}ms`));
-        }
-      }, timeout);
-
-      this._pendingRequests.set(requestId, { resolve, reject, timer });
-
-      const sent = this.send({
-        action,
-        requestId,
-        data,
-      });
-
-      if (!sent && !this.options.queueOffline) {
-        clearTimeout(timer);
-        this._pendingRequests.delete(requestId);
-        reject(new Error('[cynx/realtime] WebSocket not connected'));
-      }
-    });
-  }
-
-  on(event, callback) {
-    return this.events.on(event, callback);
-  }
-
-  once(event, callback) {
-    return this.events.once(event, callback);
-  }
-
-  off(event, callback) {
-    this.events.off(event, callback);
-  }
-
-  isConnected() {
-    return this.ws !== null && this.ws.readyState === 1;
-  }
-
-  getState() {
-    return this.status;
-  }
-
-  // ── Private Handlers ──
-
-  _setStatus(status) {
-    if (this.status !== status) {
-      this.status = status;
-      this.events.emit('status', status);
-    }
-  }
-
-  _onOpen(event) {
-    this.retries = 0;
-    this._setStatus('CONNECTED');
-    this.events.emit('open', event);
-    this.events.emit('connect', event);
-
-    this._startHeartbeat();
-    this._flushQueue();
-  }
-
-  _onMessage(event) {
-    this._resetHeartbeatTimeout();
-    const raw = event.data;
-    const parsed = safeJSONParse(raw, null);
-
-    // Handle Request-Response correlation
-    if (parsed && typeof parsed === 'object' && parsed.requestId && this._pendingRequests.has(parsed.requestId)) {
-      const req = this._pendingRequests.get(parsed.requestId);
-      clearTimeout(req.timer);
-      this._pendingRequests.delete(parsed.requestId);
-      if (parsed.error) {
-        req.reject(parsed.error);
-      } else {
-        req.resolve(parsed.data !== undefined ? parsed.data : parsed);
-      }
-      return;
-    }
-
-    // Handle typed events: { event: 'name', data: ... } or { type: 'name', ... }
-    if (parsed && typeof parsed === 'object') {
-      const eventName = parsed.event || parsed.type;
-      if (eventName) {
-        this.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed);
-      }
-    }
-
-    // General message event
-    this.events.emit('message', parsed !== null ? parsed : raw, raw);
-  }
-
-  _onError(event) {
-    this.events.emit('error', event);
-  }
-
-  _onClose(event) {
-    this._clearTimers();
-    this._setStatus('DISCONNECTED');
-    this.events.emit('close', event);
-    this.events.emit('disconnect', event);
-
-    if (!this._isExplicitClose && this.options.reconnect) {
-      this._handleReconnect();
-    }
-  }
-
-  _flushQueue() {
-    while (this._offlineQueue.length > 0 && this.isConnected()) {
-      const msg = this._offlineQueue.shift();
-      this.ws.send(msg);
-    }
-  }
-
-  _handleReconnect() {
-    if (this.retries >= this.options.maxRetries) {
-      this.events.emit('max_retries_reached', this.retries);
-      return;
-    }
-
-    let delay = this.options.initialRetryDelay * Math.pow(this.options.backoffFactor, this.retries);
-    delay = Math.min(delay, this.options.maxRetryDelay);
-
-    if (this.options.jitter) {
-      delay = delay * (0.8 + Math.random() * 0.4); // ±20% jitter
-    }
-
-    this.retries += 1;
-    this._setStatus('RECONNECTING');
-    this.events.emit('reconnect_attempt', { attempt: this.retries, delay: Math.round(delay) });
-
-    clearTimeout(this._reconnectTimer);
-    this._reconnectTimer = setTimeout(() => {
-      this.connect();
-    }, delay);
-  }
-
-  _startHeartbeat() {
-    if (!this.options.heartbeat || !this.options.heartbeat.enabled) return;
-    this._clearHeartbeat();
-
-    this._heartbeatTimer = setInterval(() => {
-      if (this.isConnected()) {
-        try {
-          this.ws.send(this.options.heartbeat.pingPayload);
-          this._heartbeatTimeoutTimer = setTimeout(() => {
-            // Server did not reply in time, force reconnect
-            if (this.ws) {
-              this.ws.close(4000, 'Heartbeat timeout');
-            }
-          }, this.options.heartbeat.timeout);
-        } catch {
-          // ignore
-        }
-      }
-    }, this.options.heartbeat.interval);
-  }
-
-  _resetHeartbeatTimeout() {
-    if (this._heartbeatTimeoutTimer) {
-      clearTimeout(this._heartbeatTimeoutTimer);
-      this._heartbeatTimeoutTimer = null;
-    }
-  }
-
-  _clearHeartbeat() {
-    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
-    if (this._heartbeatTimeoutTimer) clearTimeout(this._heartbeatTimeoutTimer);
-    this._heartbeatTimer = null;
-    this._heartbeatTimeoutTimer = null;
-  }
-
-  _clearTimers() {
-    this._clearHeartbeat();
-    if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
-    this._reconnectTimer = null;
-  }
-}
-
-export function createRealtimeSocket(url, options) {
-  return new RealtimeSocket(url, options);
-}
-
-// ─── 3. SERVER-SENT EVENTS (SSE) & AI STREAMING ─────────────────────────────────
-
-/**
- * Universal SSE (Server-Sent Events) client with AI text stream support.
- */
-export class SSEStream {
-  constructor(url, options = {}) {
-    this.url = url;
-    this.options = {
-      withCredentials: false,
-      reconnect: true,
-      maxRetries: Infinity,
-      retryDelay: 3000,
-      autoConnect: true,
-      ...options,
-    };
-
-    this.events = new EventBus();
-    this.eventSource = null;
-    this._isClosed = false;
-    this.retries = 0;
-
-    if (this.options.autoConnect) {
-      this.connect();
-    }
-  }
-
-  connect() {
-    if (typeof EventSource === 'undefined') {
-      console.warn('[cynx/realtime] EventSource is not supported in this environment.');
-      return;
-    }
-    if (this.eventSource) this.close();
-
-    this._isClosed = false;
-    this.eventSource = new EventSource(this.url, {
-      withCredentials: this.options.withCredentials,
-    });
-
-    this.eventSource.onopen = (e) => {
-      this.retries = 0;
-      this.events.emit('open', e);
-    };
-
-    this.eventSource.onmessage = (e) => {
-      const parsed = safeJSONParse(e.data, e.data);
-      this.events.emit('message', parsed, e);
-    };
-
-    this.eventSource.onerror = (e) => {
-      this.events.emit('error', e);
-      if (this.eventSource.readyState === 2 && !this._isClosed && this.options.reconnect) {
-        this.eventSource.close();
-        this._retry();
-      }
-    };
-  }
-
-  addEventListener(eventName, handler) {
-    if (!this.eventSource) return;
-    this.eventSource.addEventListener(eventName, (e) => {
-      const parsed = safeJSONParse(e.data, e.data);
-      handler(parsed, e);
-    });
-  }
-
-  on(event, callback) {
-    return this.events.on(event, callback);
-  }
-
-  close() {
-    this._isClosed = true;
-    if (this.eventSource) {
-      this.eventSource.close();
-      this.eventSource = null;
-    }
-    this.events.emit('close');
-  }
-
-  _retry() {
-    if (this.retries >= this.options.maxRetries) return;
-    this.retries += 1;
-    setTimeout(() => {
-      if (!this._isClosed) this.connect();
-    }, this.options.retryDelay);
-  }
-}
-
-export function createSSE(url, options) {
-  return new SSEStream(url, options);
-}
-
-/**
- * Helper to consume async AI/LLM readable streams (Fetch SSE / NDJSON streams).
- * 
- * Example:
- *   await parseAIStream(response, {
- *     onChunk: (text) => console.log(text),
- *     onDone: (full) => console.log('Finished:', full),
- *   });
- */
-export async function parseAIStream(response, { onChunk, onDone, onError } = {}) {
-  if (!response || !response.body) {
-    throw new Error('[cynx/realtime] Invalid response object for streaming');
-  }
-
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder('utf-8');
-  let accumulated = '';
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      const chunk = decoder.decode(value, { stream: true });
-      accumulated += chunk;
-      if (onChunk) onChunk(chunk, accumulated);
-    }
-    if (onDone) onDone(accumulated);
-    return accumulated;
-  } catch (err) {
-    if (onError) onError(err);
-    throw err;
-  }
-}
-
-// ─── 4. CROSS-TAB / WINDOW SYNCHRONIZATION ──────────────────────────────────────
-
-/**
- * Cross-Tab realtime sync channel using BroadcastChannel with LocalStorage fallback.
- * Allows instant communication between open browser tabs/windows on the same domain.
- */
-export class TabChannel {
-  constructor(name = 'cynx_channel') {
-    this.name = name;
-    this.events = new EventBus();
-    this.hasBroadcast = isBrowser && typeof BroadcastChannel !== 'undefined';
-    this._bc = null;
-    this._storageHandler = null;
-
-    if (this.hasBroadcast) {
-      this._bc = new BroadcastChannel(this.name);
-      this._bc.onmessage = (e) => {
-        const { event, data } = e.data || {};
-        if (event) {
-          this.events.emit(event, data);
-        }
-        this.events.emit('message', e.data);
-      };
-    } else if (isBrowser) {
-      // Fallback to localStorage storage event
-      this._storageKey = `cynx_tab_msg_${this.name}`;
-      this._storageHandler = (e) => {
-        if (e.key === this._storageKey && e.newValue) {
-          const parsed = safeJSONParse(e.newValue, {});
-          const { event, data } = parsed;
-          if (event) {
-            this.events.emit(event, data);
-          }
-          this.events.emit('message', parsed);
-        }
-      };
-      window.addEventListener('storage', this._storageHandler);
-    }
-  }
-
-  emit(event, data = {}) {
-    const payload = { event, data, _t: Date.now() };
-    if (this._bc) {
-      this._bc.postMessage(payload);
-    } else if (isBrowser && window.localStorage) {
-      try {
-        localStorage.setItem(this._storageKey, JSON.stringify(payload));
-      } catch {
-        // ignore quota errors
-      }
-    }
-  }
-
-  on(event, callback) {
-    return this.events.on(event, callback);
-  }
-
-  off(event, callback) {
-    this.events.off(event, callback);
-  }
-
-  close() {
-    if (this._bc) {
-      this._bc.close();
-      this._bc = null;
-    }
-    if (this._storageHandler && isBrowser) {
-      window.removeEventListener('storage', this._storageHandler);
-      this._storageHandler = null;
-    }
-    this.events.clear();
-  }
-}
-
-export function createTabChannel(channelName) {
-  return new TabChannel(channelName);
-}
-
-// ─── 5. SMART POLLER (BATTERY & TAB-AWARE) ──────────────────────────────────────
-
-/**
- * Smart Poller that automatically pauses when the browser tab is hidden/inactive,
- * and handles execution delays safely without interval drift.
- */
-export class SmartPoller {
-  constructor(taskFn, options = {}) {
-    this.taskFn = taskFn;
-    this.options = {
-      interval: 5000,
-      immediate: true,
-      pauseWhenHidden: true,
-      ...options,
-    };
-
-    this.isRunning = false;
-    this._timer = null;
-    this._visibilityHandler = null;
-
-    if (isDocAvailable && this.options.pauseWhenHidden) {
-      this._visibilityHandler = () => {
-        if (document.hidden) {
-          this._stopTimer();
-        } else if (this.isRunning) {
-          this._tick();
-        }
-      };
-      document.addEventListener('visibilitychange', this._visibilityHandler);
-    }
-
-    if (this.options.immediate) {
-      this.start();
-    }
-  }
-
-  start() {
-    if (this.isRunning) return;
-    this.isRunning = true;
-    this._tick();
-  }
-
-  stop() {
-    this.isRunning = false;
-    this._stopTimer();
-  }
-
-  destroy() {
-    this.stop();
-    if (this._visibilityHandler && isDocAvailable) {
-      document.removeEventListener('visibilitychange', this._visibilityHandler);
-      this._visibilityHandler = null;
-    }
-  }
-
-  async _tick() {
-    this._stopTimer();
-    if (!this.isRunning) return;
-
-    if (isDocAvailable && this.options.pauseWhenHidden && document.hidden) {
-      return;
-    }
-
-    try {
-      await this.taskFn();
-    } catch (err) {
-      console.error('[cynx/realtime] Error during poll execution:', err);
-    }
-
-    if (this.isRunning) {
-      this._timer = setTimeout(() => this._tick(), this.options.interval);
-    }
-  }
-
-  _stopTimer() {
-    if (this._timer) {
-      clearTimeout(this._timer);
-      this._timer = null;
-    }
-  }
-}
-
-export function createPoller(taskFn, options) {
-  return new SmartPoller(taskFn, options);
-}
-
-// ─── 6. BACKEND WEBSOCKET SERVER MANAGER ────────────────────────────────────────
-
-/**
- * Server-side wrapper around a connected client.
- */
-export class ConnectedClient {
-  constructor(socket, server, options = {}) {
-    this.id = options.id || (typeof uid === 'function' ? uid(12) : `client_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
-    this.socket = socket;
-    this.server = server;
-    this.req = options.req || null;
-    this.isAlive = true;
-    this.rooms = new Set();
-    this.data = {}; // user-defined state/metadata (e.g. userId, roles, session)
-    this.events = new EventBus();
-
-    this._bindEvents();
-  }
-
-  send(eventOrData, payload = undefined) {
-    if (this.socket.readyState !== 1) return false;
-    let message;
-    if (payload !== undefined) {
-      message = JSON.stringify({ event: eventOrData, data: payload });
-    } else if (typeof eventOrData === 'object') {
-      message = JSON.stringify(eventOrData);
-    } else {
-      message = String(eventOrData);
-    }
-    this.socket.send(message);
-    return true;
-  }
-
-  reply(requestId, data = null, error = null) {
-    return this.send({ requestId, data, error });
-  }
-
-  join(room) {
-    this.server.join(this, room);
-    return this;
-  }
-
-  leave(room) {
-    this.server.leave(this, room);
-    return this;
-  }
-
-  broadcast(eventOrData, payload = undefined) {
-    this.server.broadcast(eventOrData, payload, this);
-    return this;
-  }
-
-  broadcastTo(room, eventOrData, payload = undefined) {
-    this.server.broadcastTo(room, eventOrData, payload, this);
-    return this;
-  }
-
-  on(event, callback) {
-    return this.events.on(event, callback);
-  }
-
-  once(event, callback) {
-    return this.events.once(event, callback);
-  }
-
-  off(event, callback) {
-    this.events.off(event, callback);
-  }
-
-  close(code = 1000, reason = 'Server closed connection') {
-    if (this.socket.readyState === 1 || this.socket.readyState === 0) {
-      this.socket.close(code, reason);
-    }
-  }
-
-  _bindEvents() {
-    if (typeof this.socket.on === 'function') {
-      this.socket.on('message', (raw) => {
-        this.isAlive = true;
-        const str = raw instanceof Buffer ? raw.toString('utf-8') : String(raw);
-        const parsed = safeJSONParse(str, null);
-
-        if (parsed && typeof parsed === 'object') {
-          // Heartbeat ping/pong response
-          if (parsed.type === 'ping') {
-            this.send({ type: 'pong' });
-            return;
-          }
-
-          // Typed event handling
-          const eventName = parsed.event || parsed.type;
-          if (eventName) {
-            this.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed, this);
-            this.server.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed, this);
-          }
-        }
-
-        this.events.emit('message', parsed !== null ? parsed : str, this);
-        this.server.events.emit('message', parsed !== null ? parsed : str, this);
-      });
-
-      this.socket.on('pong', () => {
-        this.isAlive = true;
-      });
-
-      this.socket.on('close', (code, reason) => {
-        this.server._handleClientDisconnect(this, code, reason);
-      });
-
-      this.socket.on('error', (err) => {
-        this.events.emit('error', err, this);
-        this.server.events.emit('client_error', err, this);
-      });
-    }
-  }
-}
-
-/**
- * Universal WebSocket Server Manager for Node.js / Bun / Express / Fastify / HTTP Server.
- * Supports rooms, broadcasting, automatic heartbeat cleanup, and request-response handling.
- */
-export class RealtimeServer {
-  constructor(options = {}) {
-    this.options = {
-      server: undefined,           // HTTP/HTTPS server instance
-      port: undefined,             // Standalone port
-      path: '/ws',
-      heartbeatInterval: 30000,
-      WebSocketServer: undefined,  // ws.WebSocketServer constructor
-      wss: undefined,              // Existing WebSocketServer instance
-      authenticate: undefined,     // (req) => Promise<boolean|object>
-      ...options,
-    };
-
-    this.clients = new Map(); // id -> ConnectedClient
-    this.rooms = new Map();   // room -> Set<ConnectedClient>
-    this.events = new EventBus();
-    this.wss = null;
-    this._heartbeatTimer = null;
-
-    if (this.options.wss) {
-      this.attachWSS(this.options.wss);
-    } else if (this.options.server || this.options.port || this.options.WebSocketServer) {
-      this.initServer();
-    }
-  }
-
-  initServer() {
-    let WSS = this.options.WebSocketServer;
-    if (!WSS && typeof globalThis !== 'undefined' && globalThis.WebSocketServer) {
-      WSS = globalThis.WebSocketServer;
-    }
-
-    if (!WSS) {
-      throw new Error(
-        '[cynx/realtime] WebSocketServer constructor not found. Pass `{ WebSocketServer: ws.WebSocketServer }` or an existing `wss` instance.'
-      );
-    }
-
-    const wssOptions = {};
-    if (this.options.server) wssOptions.server = this.options.server;
-    if (this.options.port) wssOptions.port = this.options.port;
-    if (this.options.path) wssOptions.path = this.options.path;
-
-    this.wss = new WSS(wssOptions);
-    this.attachWSS(this.wss);
-  }
-
-  attachWSS(wss) {
-    this.wss = wss;
-
-    this.wss.on('connection', async (rawSocket, req) => {
-      try {
-        if (typeof this.options.authenticate === 'function') {
-          const authResult = await this.options.authenticate(req);
-          if (!authResult) {
-            rawSocket.close(4001, 'Unauthorized');
-            return;
-          }
-          if (typeof authResult === 'object') {
-            rawSocket._authData = authResult;
-          }
-        }
-
-        const client = new ConnectedClient(rawSocket, this, { req });
-        if (rawSocket._authData) {
-          client.data = { ...rawSocket._authData };
-        }
-
-        this.clients.set(client.id, client);
-        this.events.emit('connection', client);
-        client.events.emit('connect', client);
-      } catch (err) {
-        this.events.emit('error', err);
-        rawSocket.close(4000, 'Connection error');
-      }
-    });
-
-    this.wss.on('error', (err) => {
-      this.events.emit('error', err);
-    });
-
-    this._startHeartbeat();
-  }
-
-  broadcast(eventOrData, payload = undefined, excludeClient = null) {
-    const excludeId = excludeClient ? (excludeClient.id || excludeClient) : null;
-    for (const client of this.clients.values()) {
-      if (client.id !== excludeId) {
-        client.send(eventOrData, payload);
-      }
-    }
-  }
-
-  broadcastTo(room, eventOrData, payload = undefined, excludeClient = null) {
-    if (!this.rooms.has(room)) return;
-    const excludeId = excludeClient ? (excludeClient.id || excludeClient) : null;
-    for (const client of this.rooms.get(room)) {
-      if (client.id !== excludeId) {
-        client.send(eventOrData, payload);
-      }
-    }
-  }
-
-  join(clientOrId, room) {
-    const client = typeof clientOrId === 'string' ? this.clients.get(clientOrId) : clientOrId;
-    if (!client) return;
-
-    if (!this.rooms.has(room)) {
-      this.rooms.set(room, new Set());
-    }
-    this.rooms.get(room).add(client);
-    client.rooms.add(room);
-    this.events.emit('join_room', { client, room });
-  }
-
-  leave(clientOrId, room) {
-    const client = typeof clientOrId === 'string' ? this.clients.get(clientOrId) : clientOrId;
-    if (!client) return;
-
-    if (this.rooms.has(room)) {
-      const roomSet = this.rooms.get(room);
-      roomSet.delete(client);
-      if (roomSet.size === 0) this.rooms.delete(room);
-    }
-    client.rooms.delete(room);
-    this.events.emit('leave_room', { client, room });
-  }
-
-  getClient(id) {
-    return this.clients.get(id);
-  }
-
-  getRoomClients(room) {
-    return Array.from(this.rooms.get(room) || []);
-  }
-
-  getOnlineCount() {
-    return this.clients.size;
-  }
-
-  on(event, callback) {
-    return this.events.on(event, callback);
-  }
-
-  off(event, callback) {
-    this.events.off(event, callback);
-  }
-
-  close() {
-    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
-    for (const client of this.clients.values()) {
-      client.close(1000, 'Server shutdown');
-    }
-    this.clients.clear();
-    this.rooms.clear();
-    if (this.wss && typeof this.wss.close === 'function') {
-      this.wss.close();
-    }
-  }
-
-  _handleClientDisconnect(client, code, reason) {
-    for (const room of client.rooms) {
-      this.leave(client, room);
-    }
-    this.clients.delete(client.id);
-    client.events.emit('close', code, reason);
-    this.events.emit('disconnection', client, code, reason);
-  }
-
-  _startHeartbeat() {
-    if (!this.options.heartbeatInterval) return;
-    this._heartbeatTimer = setInterval(() => {
-      for (const client of this.clients.values()) {
-        if (!client.isAlive) {
-          client.close(4000, 'Heartbeat timeout');
-          continue;
-        }
-        client.isAlive = false;
-        if (typeof client.socket.ping === 'function') {
-          client.socket.ping();
-        } else {
-          client.send({ type: 'ping' });
-        }
-      }
-    }, this.options.heartbeatInterval);
-  }
-}
-
-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,
-  TabChannel,
-  createTabChannel,
-  SmartPoller,
-  createPoller,
-  EventBus,
-  createEventBus,
-  // Server
-  ConnectedClient,
-  RealtimeServer,
-  createRealtimeServer,
-  RealtimeProxy,
-  createRealtimeProxy,
-  RealtimeDispatcher,
-  createRealtimeDispatcher,
-};
+/**
+ * cynx/utils — Universal Realtime Engine (realtime.js)
+ *
+ * All-in-one realtime utility covering:
+ *  1. Smart WebSocket client (auto-reconnect with backoff, heartbeat/ping-pong, offline queue, pub/sub, request-response)
+ *  2. SSE (Server-Sent Events) streamer with AI stream parser
+ *  3. Cross-Tab / Cross-Window Synchronization (BroadcastChannel + LocalStorage fallback)
+ *  4. Smart Poller (pause on hidden tab, backoff, jitter)
+ *  5. Lightweight Event Bus / PubSub
+ *
+ * Compatible with Browser, Node.js, SSR, Web Workers.
+ * Zero external dependencies.
+ */
+
+import { uid } from './uid.js';
+
+// ─── UTILITIES & HELPERS ────────────────────────────────────────────────────────
+
+const isBrowser = typeof window !== 'undefined';
+const isDocAvailable = typeof document !== 'undefined';
+
+function safeJSONParse(str, fallback = null) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback !== null ? fallback : str;
+  }
+}
+
+function getWebSocketConstructor(customWs) {
+  if (customWs) return customWs;
+  if (typeof WebSocket !== 'undefined') return WebSocket;
+  if (typeof globalThis !== 'undefined' && globalThis.WebSocket) return globalThis.WebSocket;
+  return null;
+}
+
+// ─── 1. EVENT BUS (LIGHTWEIGHT PUB/SUB) ─────────────────────────────────────────
+
+export class EventBus {
+  constructor() {
+    this._listeners = new Map();
+  }
+
+  on(event, callback) {
+    if (typeof callback !== 'function') return () => {};
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    this._listeners.get(event).add(callback);
+    return () => this.off(event, callback);
+  }
+
+  once(event, callback) {
+    const unsub = this.on(event, (...args) => {
+      unsub();
+      callback(...args);
+    });
+    return unsub;
+  }
+
+  off(event, callback) {
+    if (!this._listeners.has(event)) return;
+    if (!callback) {
+      this._listeners.delete(event);
+      return;
+    }
+    const set = this._listeners.get(event);
+    set.delete(callback);
+    if (set.size === 0) this._listeners.delete(event);
+  }
+
+  emit(event, ...args) {
+    // Direct matches
+    if (this._listeners.has(event)) {
+      for (const cb of this._listeners.get(event)) {
+        try {
+          cb(...args);
+        } catch (err) {
+          console.error(`[cynx/realtime] Error in handler for event "${event}":`, err);
+        }
+      }
+    }
+    // Wildcard matches (e.g. '*')
+    if (event !== '*' && this._listeners.has('*')) {
+      for (const cb of this._listeners.get('*')) {
+        try {
+          cb(event, ...args);
+        } catch (err) {
+          console.error('[cynx/realtime] Error in wildcard handler:', err);
+        }
+      }
+    }
+  }
+
+  clear() {
+    this._listeners.clear();
+  }
+}
+
+export function createEventBus() {
+  return new EventBus();
+}
+
+// ─── 2. SMART WEBSOCKET CLIENT ──────────────────────────────────────────────────
+
+/**
+ * Universal WebSocket Client with:
+ * - Auto-reconnect with exponential backoff & random jitter
+ * - Heartbeat (Ping/Pong keep-alive)
+ * - Offline message queue
+ * - Event-based messaging (topic/event pub-sub)
+ * - Request-Response pattern over WebSocket
+ */
+export class RealtimeSocket {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = {
+      reconnect: true,
+      maxRetries: Infinity,
+      initialRetryDelay: 1000,
+      maxRetryDelay: 30000,
+      backoffFactor: 1.5,
+      jitter: true,
+      protocols: undefined,
+      heartbeat: {
+        enabled: true,
+        interval: 25000,
+        pingPayload: JSON.stringify({ type: 'ping' }),
+        pongPattern: 'pong',
+        timeout: 10000,
+      },
+      queueOffline: true,
+      maxQueueSize: 100,
+      autoConnect: true,
+      WebSocket: undefined,
+      ...options,
+    };
+
+    this.events = new EventBus();
+    this.ws = null;
+    this.status = 'DISCONNECTED'; // 'CONNECTING' | 'CONNECTED' | 'DISCONNECTED' | 'RECONNECTING'
+    this.retries = 0;
+    this._offlineQueue = [];
+    this._pendingRequests = new Map();
+    this._heartbeatTimer = null;
+    this._heartbeatTimeoutTimer = null;
+    this._reconnectTimer = null;
+    this._isExplicitClose = false;
+
+    if (this.options.autoConnect) {
+      this.connect();
+    }
+  }
+
+  connect() {
+    if (!isBrowser && !this.options.WebSocket && typeof globalThis.WebSocket === 'undefined') {
+      return;
+    }
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) {
+      return;
+    }
+
+    this._isExplicitClose = false;
+    this._setStatus(this.retries > 0 ? 'RECONNECTING' : 'CONNECTING');
+
+    const WS = getWebSocketConstructor(this.options.WebSocket);
+    if (!WS) {
+      console.warn('[cynx/realtime] WebSocket implementation not found in this environment.');
+      return;
+    }
+
+    try {
+      const targetUrl = typeof this.url === 'function' ? this.url() : this.url;
+      this.ws = this.options.protocols
+        ? new WS(targetUrl, this.options.protocols)
+        : new WS(targetUrl);
+
+      this.ws.onopen = (e) => this._onOpen(e);
+      this.ws.onmessage = (e) => this._onMessage(e);
+      this.ws.onerror = (e) => this._onError(e);
+      this.ws.onclose = (e) => this._onClose(e);
+    } catch (err) {
+      this._handleReconnect();
+    }
+  }
+
+  disconnect(code = 1000, reason = 'Client disconnected') {
+    this._isExplicitClose = true;
+    this._clearTimers();
+    if (this.ws) {
+      this.ws.close(code, reason);
+      this.ws = null;
+    }
+    this._setStatus('DISCONNECTED');
+  }
+
+  /**
+   * Send data or a typed event payload.
+   * If offline and queueOffline=true, queues the message until reconnect.
+   */
+  send(eventOrData, payload = undefined) {
+    let message;
+    if (payload !== undefined) {
+      message = JSON.stringify({ event: eventOrData, data: payload });
+    } else if (typeof eventOrData === 'object') {
+      message = JSON.stringify(eventOrData);
+    } else {
+      message = String(eventOrData);
+    }
+
+    if (this.isConnected()) {
+      this.ws.send(message);
+      return true;
+    }
+
+    if (this.options.queueOffline) {
+      if (this._offlineQueue.length >= this.options.maxQueueSize) {
+        this._offlineQueue.shift(); // Drop oldest message
+      }
+      this._offlineQueue.push(message);
+      return false;
+    }
+
+    return false;
+  }
+
+  /**
+   * Perform a Request-Response interaction over WebSocket.
+   * Attaches a correlation `requestId` and resolves when server replies.
+   */
+  request(action, data = {}, { timeout = 10000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+      const timer = setTimeout(() => {
+        if (this._pendingRequests.has(requestId)) {
+          this._pendingRequests.delete(requestId);
+          reject(new Error(`[cynx/realtime] Request "${action}" timed out after ${timeout}ms`));
+        }
+      }, timeout);
+
+      this._pendingRequests.set(requestId, { resolve, reject, timer });
+
+      const sent = this.send({
+        action,
+        requestId,
+        data,
+      });
+
+      if (!sent && !this.options.queueOffline) {
+        clearTimeout(timer);
+        this._pendingRequests.delete(requestId);
+        reject(new Error('[cynx/realtime] WebSocket not connected'));
+      }
+    });
+  }
+
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+
+  once(event, callback) {
+    return this.events.once(event, callback);
+  }
+
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === 1;
+  }
+
+  getState() {
+    return this.status;
+  }
+
+  // ── Private Handlers ──
+
+  _setStatus(status) {
+    if (this.status !== status) {
+      this.status = status;
+      this.events.emit('status', status);
+    }
+  }
+
+  _onOpen(event) {
+    this.retries = 0;
+    this._setStatus('CONNECTED');
+    this.events.emit('open', event);
+    this.events.emit('connect', event);
+
+    this._startHeartbeat();
+    this._flushQueue();
+  }
+
+  _onMessage(event) {
+    this._resetHeartbeatTimeout();
+    const raw = event.data;
+    const parsed = safeJSONParse(raw, null);
+
+    // Handle Request-Response correlation
+    if (parsed && typeof parsed === 'object' && parsed.requestId && this._pendingRequests.has(parsed.requestId)) {
+      const req = this._pendingRequests.get(parsed.requestId);
+      clearTimeout(req.timer);
+      this._pendingRequests.delete(parsed.requestId);
+      if (parsed.error) {
+        req.reject(parsed.error);
+      } else {
+        req.resolve(parsed.data !== undefined ? parsed.data : parsed);
+      }
+      return;
+    }
+
+    // Handle typed events: { event: 'name', data: ... } or { type: 'name', ... }
+    if (parsed && typeof parsed === 'object') {
+      const eventName = parsed.event || parsed.type;
+      if (eventName) {
+        this.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed);
+      }
+    }
+
+    // General message event
+    this.events.emit('message', parsed !== null ? parsed : raw, raw);
+  }
+
+  _onError(event) {
+    this.events.emit('error', event);
+  }
+
+  _onClose(event) {
+    this._clearTimers();
+    this._setStatus('DISCONNECTED');
+    this.events.emit('close', event);
+    this.events.emit('disconnect', event);
+
+    if (!this._isExplicitClose && this.options.reconnect) {
+      this._handleReconnect();
+    }
+  }
+
+  _flushQueue() {
+    while (this._offlineQueue.length > 0 && this.isConnected()) {
+      const msg = this._offlineQueue.shift();
+      this.ws.send(msg);
+    }
+  }
+
+  _handleReconnect() {
+    if (this.retries >= this.options.maxRetries) {
+      this.events.emit('max_retries_reached', this.retries);
+      return;
+    }
+
+    let delay = this.options.initialRetryDelay * Math.pow(this.options.backoffFactor, this.retries);
+    delay = Math.min(delay, this.options.maxRetryDelay);
+
+    if (this.options.jitter) {
+      delay = delay * (0.8 + Math.random() * 0.4); // ±20% jitter
+    }
+
+    this.retries += 1;
+    this._setStatus('RECONNECTING');
+    this.events.emit('reconnect_attempt', { attempt: this.retries, delay: Math.round(delay) });
+
+    clearTimeout(this._reconnectTimer);
+    this._reconnectTimer = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+
+  _startHeartbeat() {
+    if (!this.options.heartbeat || !this.options.heartbeat.enabled) return;
+    this._clearHeartbeat();
+
+    this._heartbeatTimer = setInterval(() => {
+      if (this.isConnected()) {
+        try {
+          this.ws.send(this.options.heartbeat.pingPayload);
+          this._heartbeatTimeoutTimer = setTimeout(() => {
+            // Server did not reply in time, force reconnect
+            if (this.ws) {
+              this.ws.close(4000, 'Heartbeat timeout');
+            }
+          }, this.options.heartbeat.timeout);
+        } catch {
+          // ignore
+        }
+      }
+    }, this.options.heartbeat.interval);
+  }
+
+  _resetHeartbeatTimeout() {
+    if (this._heartbeatTimeoutTimer) {
+      clearTimeout(this._heartbeatTimeoutTimer);
+      this._heartbeatTimeoutTimer = null;
+    }
+  }
+
+  _clearHeartbeat() {
+    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
+    if (this._heartbeatTimeoutTimer) clearTimeout(this._heartbeatTimeoutTimer);
+    this._heartbeatTimer = null;
+    this._heartbeatTimeoutTimer = null;
+  }
+
+  _clearTimers() {
+    this._clearHeartbeat();
+    if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
+    this._reconnectTimer = null;
+  }
+}
+
+export function createRealtimeSocket(url, options) {
+  return new RealtimeSocket(url, options);
+}
+
+// ─── 3. SERVER-SENT EVENTS (SSE) & AI STREAMING ─────────────────────────────────
+
+/**
+ * Universal SSE (Server-Sent Events) client with AI text stream support.
+ */
+export class SSEStream {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = {
+      withCredentials: false,
+      reconnect: true,
+      maxRetries: Infinity,
+      retryDelay: 3000,
+      autoConnect: true,
+      ...options,
+    };
+
+    this.events = new EventBus();
+    this.eventSource = null;
+    this._isClosed = false;
+    this.retries = 0;
+
+    if (this.options.autoConnect) {
+      this.connect();
+    }
+  }
+
+  connect() {
+    if (typeof EventSource === 'undefined') {
+      console.warn('[cynx/realtime] EventSource is not supported in this environment.');
+      return;
+    }
+    if (this.eventSource) this.close();
+
+    this._isClosed = false;
+    this.eventSource = new EventSource(this.url, {
+      withCredentials: this.options.withCredentials,
+    });
+
+    this.eventSource.onopen = (e) => {
+      this.retries = 0;
+      this.events.emit('open', e);
+    };
+
+    this.eventSource.onmessage = (e) => {
+      const parsed = safeJSONParse(e.data, e.data);
+      this.events.emit('message', parsed, e);
+    };
+
+    this.eventSource.onerror = (e) => {
+      this.events.emit('error', e);
+      if (this.eventSource.readyState === 2 && !this._isClosed && this.options.reconnect) {
+        this.eventSource.close();
+        this._retry();
+      }
+    };
+  }
+
+  addEventListener(eventName, handler) {
+    if (!this.eventSource) return;
+    this.eventSource.addEventListener(eventName, (e) => {
+      const parsed = safeJSONParse(e.data, e.data);
+      handler(parsed, e);
+    });
+  }
+
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+
+  close() {
+    this._isClosed = true;
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.events.emit('close');
+  }
+
+  _retry() {
+    if (this.retries >= this.options.maxRetries) return;
+    this.retries += 1;
+    setTimeout(() => {
+      if (!this._isClosed) this.connect();
+    }, this.options.retryDelay);
+  }
+}
+
+export function createSSE(url, options) {
+  return new SSEStream(url, options);
+}
+
+/**
+ * Helper to consume async AI/LLM readable streams (Fetch SSE / NDJSON streams).
+ * 
+ * Example:
+ *   await parseAIStream(response, {
+ *     onChunk: (text) => console.log(text),
+ *     onDone: (full) => console.log('Finished:', full),
+ *   });
+ */
+export async function parseAIStream(response, { onChunk, onDone, onError } = {}) {
+  if (!response || !response.body) {
+    throw new Error('[cynx/realtime] Invalid response object for streaming');
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let accumulated = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = decoder.decode(value, { stream: true });
+      accumulated += chunk;
+      if (onChunk) onChunk(chunk, accumulated);
+    }
+    if (onDone) onDone(accumulated);
+    return accumulated;
+  } catch (err) {
+    if (onError) onError(err);
+    throw err;
+  }
+}
+
+// ─── 4. CROSS-TAB / WINDOW SYNCHRONIZATION ──────────────────────────────────────
+
+/**
+ * Cross-Tab realtime sync channel using BroadcastChannel with LocalStorage fallback.
+ * Allows instant communication between open browser tabs/windows on the same domain.
+ */
+export class TabChannel {
+  constructor(name = 'cynx_channel') {
+    this.name = name;
+    this.events = new EventBus();
+    this.hasBroadcast = isBrowser && typeof BroadcastChannel !== 'undefined';
+    this._bc = null;
+    this._storageHandler = null;
+
+    if (this.hasBroadcast) {
+      this._bc = new BroadcastChannel(this.name);
+      this._bc.onmessage = (e) => {
+        const { event, data } = e.data || {};
+        if (event) {
+          this.events.emit(event, data);
+        }
+        this.events.emit('message', e.data);
+      };
+    } else if (isBrowser) {
+      // Fallback to localStorage storage event
+      this._storageKey = `cynx_tab_msg_${this.name}`;
+      this._storageHandler = (e) => {
+        if (e.key === this._storageKey && e.newValue) {
+          const parsed = safeJSONParse(e.newValue, {});
+          const { event, data } = parsed;
+          if (event) {
+            this.events.emit(event, data);
+          }
+          this.events.emit('message', parsed);
+        }
+      };
+      window.addEventListener('storage', this._storageHandler);
+    }
+  }
+
+  emit(event, data = {}) {
+    const payload = { event, data, _t: Date.now() };
+    if (this._bc) {
+      this._bc.postMessage(payload);
+    } else if (isBrowser && window.localStorage) {
+      try {
+        localStorage.setItem(this._storageKey, JSON.stringify(payload));
+      } catch {
+        // ignore quota errors
+      }
+    }
+  }
+
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  close() {
+    if (this._bc) {
+      this._bc.close();
+      this._bc = null;
+    }
+    if (this._storageHandler && isBrowser) {
+      window.removeEventListener('storage', this._storageHandler);
+      this._storageHandler = null;
+    }
+    this.events.clear();
+  }
+}
+
+export function createTabChannel(channelName) {
+  return new TabChannel(channelName);
+}
+
+// ─── 5. SMART POLLER (BATTERY & TAB-AWARE) ──────────────────────────────────────
+
+/**
+ * Smart Poller that automatically pauses when the browser tab is hidden/inactive,
+ * and handles execution delays safely without interval drift.
+ */
+export class SmartPoller {
+  constructor(taskFn, options = {}) {
+    this.taskFn = taskFn;
+    this.options = {
+      interval: 5000,
+      immediate: true,
+      pauseWhenHidden: true,
+      ...options,
+    };
+
+    this.isRunning = false;
+    this._timer = null;
+    this._visibilityHandler = null;
+
+    if (isDocAvailable && this.options.pauseWhenHidden) {
+      this._visibilityHandler = () => {
+        if (document.hidden) {
+          this._stopTimer();
+        } else if (this.isRunning) {
+          this._tick();
+        }
+      };
+      document.addEventListener('visibilitychange', this._visibilityHandler);
+    }
+
+    if (this.options.immediate) {
+      this.start();
+    }
+  }
+
+  start() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    this._tick();
+  }
+
+  stop() {
+    this.isRunning = false;
+    this._stopTimer();
+  }
+
+  destroy() {
+    this.stop();
+    if (this._visibilityHandler && isDocAvailable) {
+      document.removeEventListener('visibilitychange', this._visibilityHandler);
+      this._visibilityHandler = null;
+    }
+  }
+
+  async _tick() {
+    this._stopTimer();
+    if (!this.isRunning) return;
+
+    if (isDocAvailable && this.options.pauseWhenHidden && document.hidden) {
+      return;
+    }
+
+    try {
+      await this.taskFn();
+    } catch (err) {
+      console.error('[cynx/realtime] Error during poll execution:', err);
+    }
+
+    if (this.isRunning) {
+      this._timer = setTimeout(() => this._tick(), this.options.interval);
+    }
+  }
+
+  _stopTimer() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+}
+
+export function createPoller(taskFn, options) {
+  return new SmartPoller(taskFn, options);
+}
+
+// ─── 6. BACKEND WEBSOCKET SERVER MANAGER ────────────────────────────────────────
+
+/**
+ * Server-side wrapper around a connected client.
+ */
+export class ConnectedClient {
+  constructor(socket, server, options = {}) {
+    this.id = options.id || (typeof uid === 'function' ? uid(12) : `client_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
+    this.socket = socket;
+    this.server = server;
+    this.req = options.req || null;
+    this.isAlive = true;
+    this.rooms = new Set();
+    this.data = {}; // user-defined state/metadata (e.g. userId, roles, session)
+    this.events = new EventBus();
+
+    this._bindEvents();
+  }
+
+  send(eventOrData, payload = undefined) {
+    if (this.socket.readyState !== 1) return false;
+    let message;
+    if (payload !== undefined) {
+      message = JSON.stringify({ event: eventOrData, data: payload });
+    } else if (typeof eventOrData === 'object') {
+      message = JSON.stringify(eventOrData);
+    } else {
+      message = String(eventOrData);
+    }
+    this.socket.send(message);
+    return true;
+  }
+
+  reply(requestId, data = null, error = null) {
+    return this.send({ requestId, data, error });
+  }
+
+  join(room) {
+    this.server.join(this, room);
+    return this;
+  }
+
+  leave(room) {
+    this.server.leave(this, room);
+    return this;
+  }
+
+  broadcast(eventOrData, payload = undefined) {
+    this.server.broadcast(eventOrData, payload, this);
+    return this;
+  }
+
+  broadcastTo(room, eventOrData, payload = undefined) {
+    this.server.broadcastTo(room, eventOrData, payload, this);
+    return this;
+  }
+
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+
+  once(event, callback) {
+    return this.events.once(event, callback);
+  }
+
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  close(code = 1000, reason = 'Server closed connection') {
+    if (this.socket.readyState === 1 || this.socket.readyState === 0) {
+      this.socket.close(code, reason);
+    }
+  }
+
+  _bindEvents() {
+    if (typeof this.socket.on === 'function') {
+      this.socket.on('message', (raw) => {
+        this.isAlive = true;
+        const str = raw instanceof Buffer ? raw.toString('utf-8') : String(raw);
+        const parsed = safeJSONParse(str, null);
+
+        if (parsed && typeof parsed === 'object') {
+          // Heartbeat ping/pong response
+          if (parsed.type === 'ping') {
+            this.send({ type: 'pong' });
+            return;
+          }
+
+          // Typed event handling
+          const eventName = parsed.event || parsed.type;
+          if (eventName) {
+            this.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed, this);
+            this.server.events.emit(eventName, parsed.data !== undefined ? parsed.data : parsed, this);
+          }
+        }
+
+        this.events.emit('message', parsed !== null ? parsed : str, this);
+        this.server.events.emit('message', parsed !== null ? parsed : str, this);
+      });
+
+      this.socket.on('pong', () => {
+        this.isAlive = true;
+      });
+
+      this.socket.on('close', (code, reason) => {
+        this.server._handleClientDisconnect(this, code, reason);
+      });
+
+      this.socket.on('error', (err) => {
+        this.events.emit('error', err, this);
+        this.server.events.emit('client_error', err, this);
+      });
+    }
+  }
+}
+
+/**
+ * Universal WebSocket Server Manager for Node.js / Bun / Express / Fastify / HTTP Server.
+ * Supports rooms, broadcasting, automatic heartbeat cleanup, and request-response handling.
+ */
+export class RealtimeServer {
+  constructor(options = {}) {
+    this.options = {
+      server: undefined,           // HTTP/HTTPS server instance
+      port: undefined,             // Standalone port
+      path: '/ws',
+      heartbeatInterval: 30000,
+      WebSocketServer: undefined,  // ws.WebSocketServer constructor
+      wss: undefined,              // Existing WebSocketServer instance
+      authenticate: undefined,     // (req) => Promise<boolean|object>
+      ...options,
+    };
+
+    this.clients = new Map(); // id -> ConnectedClient
+    this.rooms = new Map();   // room -> Set<ConnectedClient>
+    this.events = new EventBus();
+    this.wss = null;
+    this._heartbeatTimer = null;
+
+    if (this.options.wss) {
+      this.attachWSS(this.options.wss);
+    } else if (this.options.server || this.options.port || this.options.WebSocketServer) {
+      this.initServer();
+    }
+  }
+
+  initServer() {
+    let WSS = this.options.WebSocketServer;
+    if (!WSS && typeof globalThis !== 'undefined' && globalThis.WebSocketServer) {
+      WSS = globalThis.WebSocketServer;
+    }
+
+    if (!WSS) {
+      throw new Error(
+        '[cynx/realtime] WebSocketServer constructor not found. Pass `{ WebSocketServer: ws.WebSocketServer }` or an existing `wss` instance.'
+      );
+    }
+
+    const wssOptions = {};
+    if (this.options.server) wssOptions.server = this.options.server;
+    if (this.options.port) wssOptions.port = this.options.port;
+    if (this.options.path) wssOptions.path = this.options.path;
+
+    this.wss = new WSS(wssOptions);
+    this.attachWSS(this.wss);
+  }
+
+  attachWSS(wss) {
+    this.wss = wss;
+
+    this.wss.on('connection', async (rawSocket, req) => {
+      try {
+        if (typeof this.options.authenticate === 'function') {
+          const authResult = await this.options.authenticate(req);
+          if (!authResult) {
+            rawSocket.close(4001, 'Unauthorized');
+            return;
+          }
+          if (typeof authResult === 'object') {
+            rawSocket._authData = authResult;
+          }
+        }
+
+        const client = new ConnectedClient(rawSocket, this, { req });
+        if (rawSocket._authData) {
+          client.data = { ...rawSocket._authData };
+        }
+
+        this.clients.set(client.id, client);
+        this.events.emit('connection', client);
+        client.events.emit('connect', client);
+      } catch (err) {
+        this.events.emit('error', err);
+        rawSocket.close(4000, 'Connection error');
+      }
+    });
+
+    this.wss.on('error', (err) => {
+      this.events.emit('error', err);
+    });
+
+    this._startHeartbeat();
+  }
+
+  broadcast(eventOrData, payload = undefined, excludeClient = null) {
+    const excludeId = excludeClient ? (excludeClient.id || excludeClient) : null;
+    for (const client of this.clients.values()) {
+      if (client.id !== excludeId) {
+        client.send(eventOrData, payload);
+      }
+    }
+  }
+
+  broadcastTo(room, eventOrData, payload = undefined, excludeClient = null) {
+    if (!this.rooms.has(room)) return;
+    const excludeId = excludeClient ? (excludeClient.id || excludeClient) : null;
+    for (const client of this.rooms.get(room)) {
+      if (client.id !== excludeId) {
+        client.send(eventOrData, payload);
+      }
+    }
+  }
+
+  join(clientOrId, room) {
+    const client = typeof clientOrId === 'string' ? this.clients.get(clientOrId) : clientOrId;
+    if (!client) return;
+
+    if (!this.rooms.has(room)) {
+      this.rooms.set(room, new Set());
+    }
+    this.rooms.get(room).add(client);
+    client.rooms.add(room);
+    this.events.emit('join_room', { client, room });
+  }
+
+  leave(clientOrId, room) {
+    const client = typeof clientOrId === 'string' ? this.clients.get(clientOrId) : clientOrId;
+    if (!client) return;
+
+    if (this.rooms.has(room)) {
+      const roomSet = this.rooms.get(room);
+      roomSet.delete(client);
+      if (roomSet.size === 0) this.rooms.delete(room);
+    }
+    client.rooms.delete(room);
+    this.events.emit('leave_room', { client, room });
+  }
+
+  getClient(id) {
+    return this.clients.get(id);
+  }
+
+  getRoomClients(room) {
+    return Array.from(this.rooms.get(room) || []);
+  }
+
+  getOnlineCount() {
+    return this.clients.size;
+  }
+
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  close() {
+    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
+    for (const client of this.clients.values()) {
+      client.close(1000, 'Server shutdown');
+    }
+    this.clients.clear();
+    this.rooms.clear();
+    if (this.wss && typeof this.wss.close === 'function') {
+      this.wss.close();
+    }
+  }
+
+  _handleClientDisconnect(client, code, reason) {
+    for (const room of client.rooms) {
+      this.leave(client, room);
+    }
+    this.clients.delete(client.id);
+    client.events.emit('close', code, reason);
+    this.events.emit('disconnection', client, code, reason);
+  }
+
+  _startHeartbeat() {
+    if (!this.options.heartbeatInterval) return;
+    this._heartbeatTimer = setInterval(() => {
+      for (const client of this.clients.values()) {
+        if (!client.isAlive) {
+          client.close(4000, 'Heartbeat timeout');
+          continue;
+        }
+        client.isAlive = false;
+        if (typeof client.socket.ping === 'function') {
+          client.socket.ping();
+        } else {
+          client.send({ type: 'ping' });
+        }
+      }
+    }, this.options.heartbeatInterval);
+  }
+}
+
+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,
+  TabChannel,
+  createTabChannel,
+  SmartPoller,
+  createPoller,
+  EventBus,
+  createEventBus,
+  // Server
+  ConnectedClient,
+  RealtimeServer,
+  createRealtimeServer,
+  RealtimeProxy,
+  createRealtimeProxy,
+  RealtimeDispatcher,
+  createRealtimeDispatcher,
+};