cynx-lib 1.3.35 → 1.3.36

package/utils/utils/realtime.js

@@ -1,1040 +1,1040 @@
-/**
- * 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);
-}
-
-// ─── MAIN EXPORT ────────────────────────────────────────────────────────────────
-
-export default {
-  // Client
-  RealtimeSocket,
-  createRealtimeSocket,
-  SSEStream,
-  createSSE,
-  parseAIStream,
-  TabChannel,
-  createTabChannel,
-  SmartPoller,
-  createPoller,
-  EventBus,
-  createEventBus,
-  // Server
-  ConnectedClient,
-  RealtimeServer,
-  createRealtimeServer,
-};
+/**
+ * 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);
+}
+
+// ─── MAIN EXPORT ────────────────────────────────────────────────────────────────
+
+export default {
+  // Client
+  RealtimeSocket,
+  createRealtimeSocket,
+  SSEStream,
+  createSSE,
+  parseAIStream,
+  TabChannel,
+  createTabChannel,
+  SmartPoller,
+  createPoller,
+  EventBus,
+  createEventBus,
+  // Server
+  ConnectedClient,
+  RealtimeServer,
+  createRealtimeServer,
+};