@vxil/realtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 techmaker.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @vxil/realtime
+
+Reconnecting realtime client for [Vxil](https://vxil.com) channels — auto-reconnect with backoff, pre-expiry token refresh, an offline send buffer, presence helpers, and a typed event API. Runs in the browser and in Node.
+
+```bash
+npm install @vxil/realtime
+```
+
+Or zero-install in the browser — the same client is served as a self-contained module:
+
+```html
+<script type="module">
+  import { RealtimeClient } from 'https://vxil.com/realtime.mjs';
+</script>
+```
+
+## The one rule: connect tokens, not API keys
+
+Your Vxil API key is a **server-side secret — never put it in a browser bundle**. A browser connects with a short-lived, scoped **connect token** instead: your backend (which holds the key) mints one via `POST /v1/realtime/tokens` and hands it to the client. `RealtimeClient` takes that minting step as a `tokenProvider` callback and re-mints automatically whenever the cached token nears expiry.
+
+```ts
+import { RealtimeClient } from '@vxil/realtime';
+
+const rt = new RealtimeClient({
+  // Implemented against YOUR backend — the browser never sees the API key.
+  tokenProvider: async ({ channel }) => {
+    const res = await fetch('/api/realtime-token', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ channel }),
+    });
+    return res.json(); // { connect_path, expires_at } from POST /v1/realtime/tokens
+  },
+});
+
+const room = rt.channel('room-7');
+await room.subscribe();
+
+room.on('message.created', (frame) => console.log(frame.data));
+room.send({ type: 'message', text: 'hello' }); // buffered while offline, flushed on reconnect
+```
+
+The `tokenProvider` result may be any one of `connect_url` (full URL), `connect_path` (as returned by the tokens endpoint), or a raw `token`; include `expires_at` to enable pre-expiry re-minting. Server-side (Node) callers can use the `vxil.realtime.tokenProvider({ user_id })` glue from `@vxil/sdk` — it returns a function matching this shape.
+
+## What it adds over a raw WebSocket
+
+- **Auto-reconnect** — exponential backoff with jitter, per channel (`reconnect: { baseDelayMs, maxDelayMs, maxAttempts }`); each channel owns its own socket, so reconnecting is re-subscribing.
+- **Token refresh** — re-mints via your `tokenProvider` before `expires_at` (tunable with `expirySkewMs`) and after any close, so an expired token never strands a client.
+- **Offline send buffer** — `send()` while disconnected buffers FIFO (default 100 frames, drop-oldest; `sendBufferSize: 0` disables) and flushes on the next open. `send()` returns `false` when a frame was dropped instead of queued.
+- **Presence** — `channel.presence.members` is a live roster map, re-synced from the server on every (re)connect; `channel.presence.on('sync' | 'join' | 'leave' | 'typing', cb)` for events. `channel.typing()` sends an ephemeral (never-buffered) typing signal.
+- **Typed events** — `channel.on('<event>', cb)` or `channel.on('*', cb)`, each returning a disposer; `channel.onState(cb)` observes `idle → connecting → open → reconnecting → closed`.
+
+## Node
+
+Node ≥ 22 has a global `WebSocket` and works out of the box. On older Node, inject a constructor:
+
+```ts
+import WebSocket from 'ws';
+const rt = new RealtimeClient({ tokenProvider, WebSocket });
+```
+
+(`ws` is **not** a dependency of this package.)
+
+Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard)
+
+MIT © techmaker.io

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+export type TokenProviderResult = {
+    /** Raw connect token — the client builds `/v1/realtime/connect?token=…`. */
+    token?: string;
+    /** As returned by POST /v1/realtime/tokens (starts with /v1/realtime/connect). */
+    connect_path?: string;
+    /** Full ws(s):// URL — wins over the other two if present. */
+    connect_url?: string;
+    /** ISO timestamp; enables pre-expiry re-mint. Absent ⇒ re-mint every attempt. */
+    expires_at?: string;
+};
+/** Your app implements this against YOUR backend (which holds the tenant API
+ *  key and calls POST /v1/realtime/tokens). Server-side (Node) callers can use
+ *  the `vxil.realtime.tokenProvider({ user_id })` glue from @vxil/sdk — it
+ *  returns a function matching this type structurally. */
+export type TokenProvider = (ctx: {
+    channel: string;
+}) => Promise<TokenProviderResult>;
+/** Minimal structural WebSocket surface the client needs — the real browser /
+ *  Node-22 `WebSocket` and the `ws` package both satisfy it. */
+export interface MinimalWebSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    /** WHATWG readyState (0..3). Optional so hand-rolled test fakes without it
+     *  still satisfy the interface — absent reads as "trust the state machine". */
+    readyState?: number;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (ev: {
+        data?: unknown;
+        code?: number;
+    }) => void): void;
+}
+export type WebSocketCtor = new (url: string) => MinimalWebSocket;
+export interface RealtimeOptions {
+    tokenProvider: TokenProvider;
+    /** REST/WS origin; default 'https://api.vxil.com' — the served realtime.mjs
+     *  env-bakes this literal to the right edge per environment, exactly like
+     *  sdk.mjs. */
+    baseUrl?: string;
+    /** Node<22 injection: `import WebSocket from 'ws'` and pass it here. */
+    WebSocket?: WebSocketCtor;
+    reconnect?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        /** default Infinity; exhausted → state 'closed' + error detail emit */
+        maxAttempts?: number;
+    };
+    /** Frames buffered by send() while disconnected; default 100; 0 disables. */
+    sendBufferSize?: number;
+    /** Re-mint when the cached token is within this of expires_at. Default 5000. */
+    expirySkewMs?: number;
+}
+export type ChannelState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
+export interface RealtimeFrame {
+    event: string;
+    data?: unknown;
+    ts?: number;
+}
+export type PresenceEventName = 'sync' | 'join' | 'leave' | 'typing';
+export interface PresenceEvent {
+    user_id?: string;
+    members?: ReadonlyMap<string, number>;
+}
+type FrameListener = (frame: RealtimeFrame) => void;
+type StateListener = (state: ChannelState, detail?: {
+    attempt?: number;
+    error?: unknown;
+}) => void;
+type PresenceListener = (d: PresenceEvent) => void;
+export declare class Channel {
+    readonly name: string;
+    private readonly opts;
+    private readonly WS;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly maxAttempts;
+    private readonly bufferSize;
+    private readonly expirySkewMs;
+    private _state;
+    private ws;
+    private attempt;
+    private timer;
+    private userClosed;
+    private cached;
+    private buffer;
+    /** true between (re)open and the first server frame — gates the buffer flush */
+    private awaitingFlush;
+    private flushFallback;
+    private openPromise;
+    private resolveOpen;
+    private rejectOpen;
+    private everOpened;
+    private readonly listeners;
+    private readonly stateListeners;
+    private readonly presenceListeners;
+    private readonly membersMap;
+    /** Presence helpers. `members` is client-side bookkeeping: seeded/replaced by
+     *  the server's `presence.state` on EVERY open, mutated by join/leave in
+     *  between — best-effort between syncs (multi-tab counts can drift; the next
+     *  reconnect re-syncs). */
+    readonly presence: {
+        members: ReadonlyMap<string, number>;
+        on(ev: PresenceEventName, cb: PresenceListener): () => void;
+    };
+    constructor(name: string, opts: RealtimeOptions, ws: WebSocketCtor);
+    get state(): ChannelState;
+    /** Open (or re-open after unsubscribe) the channel. Resolves on the first
+     *  'open'; rejects if maxAttempts is exhausted before ever opening, or on
+     *  unsubscribe()/close() while still connecting. */
+    subscribe(): Promise<void>;
+    /** Deliberate close: state → 'closed', no reconnect, buffer kept as-is. */
+    unsubscribe(): void;
+    /** Listen for frames by exact event name, or '*' for everything. Returns a
+     *  disposer. `pong` frames are internal and never dispatched. */
+    on(event: string, cb: FrameListener): () => void;
+    off(event: string, cb: FrameListener): void;
+    onState(cb: StateListener): () => void;
+    /** Send a client frame. Open → sent now (true). Disconnected → buffered
+     *  FIFO up to sendBufferSize, flushed on the next open; when the buffer
+     *  overflows the OLDEST frame is dropped and send() returns false (so does
+     *  a send with buffering disabled). Frames over 1024 chars are still sent
+     *  but the server will drop them (a console.warn flags it). */
+    send(frame: object): boolean;
+    /** Ephemeral typing signal — never buffered (replaying a stale typing
+     *  indicator after a reconnect would be wrong). Server-gated on presence. */
+    typing(): void;
+    /** Ephemeral keepalive — never buffered. Server replies `pong` (swallowed). */
+    ping(): void;
+    private sendEphemeral;
+    private setState;
+    private settleOpen;
+    /** Cached-or-fresh connect URL. Re-mints via the tokenProvider when the
+     *  cached token is absent, has no expires_at, or is within expirySkewMs of
+     *  expiry — which also covers the "server rejected the token" case: a
+     *  browser only ever sees close 1006, and by the time that matters the
+     *  token is expired or near-expiry and gets re-minted on the next attempt. */
+    private resolveUrl;
+    private urlFrom;
+    private connect;
+    private handleOpen;
+    /** Flush the offline buffer FIFO onto the current socket (idempotent). */
+    private flushBuffer;
+    private scheduleReconnect;
+    private handleMessage;
+    private dispatch;
+    private emitPresence;
+    private handlePresence;
+}
+export declare class RealtimeClient {
+    private readonly opts;
+    private readonly WS;
+    private readonly channels;
+    constructor(opts: RealtimeOptions);
+    /** Idempotent registry: the same name always returns the same handle. */
+    channel(name: string): Channel;
+    /** Unsubscribes every channel (deliberate close — no reconnects). */
+    close(): void;
+}
+/** Convenience mirroring the served-file import path. */
+export declare function createRealtimeClient(opts: RealtimeOptions): RealtimeClient;
+export {};

package/dist/index.js

@@ -0,0 +1,450 @@
+// @vxil/realtime — reconnecting client for Vxil realtime channels.
+//
+// ZERO-IMPORT SINGLE FILE — DO NOT ADD `import` STATEMENTS. This file is
+// compiled with plain tsc into one dist/index.js which workers/web copies
+// verbatim to public/realtime.mjs for the no-install browser path
+// (`import { RealtimeClient } from 'https://vxil.com/realtime.mjs'`). Any
+// import would leave a dangling module specifier in the served file and
+// break every zero-install user (same invariant as @vxil/sdk → sdk.mjs; the
+// staging e2e asserts the served asset stays self-contained).
+//
+// What it adds over the raw `vxil.realtime.connect()` socket:
+//   - auto-reconnect with exponential backoff + jitter,
+//   - token refresh: re-mints via the tokenProvider before TTL expiry and on
+//     any close (browsers cannot distinguish 401/429/network on a failed
+//     upgrade — every failure is close code 1006, so the client simply
+//     re-mints when the cached token is near/past expiry and keeps backing
+//     off; a channel at its connection cap looks identical and also resolves
+//     itself by backoff),
+//   - bounded offline send buffer flushed FIFO on reconnect,
+//   - automatic channel re-subscribe (each channel owns its own socket, so
+//     reconnecting IS re-subscribing),
+//   - presence helpers (roster map + join/leave/typing/sync events, re-synced
+//     from the server's presence.state seed on every open — counts between
+//     syncs are best-effort),
+//   - a typed event-emitter API.
+//
+// WebSocket: uses the global `WebSocket` (browser / Node ≥22). On older Node,
+// pass a constructor — `import WebSocket from 'ws'; new RealtimeClient({
+// ..., WebSocket })` — instead of failing with a silent `WebSocket is not
+// defined`. (The `ws` package is NOT a dependency of this package.)
+const DEFAULT_BASE = 'https://api.vxil.com';
+function resolveCtor(injected) {
+    const WS = injected ?? globalThis.WebSocket;
+    if (!WS) {
+        throw new Error('No WebSocket available. In the browser it is global; on Node <22 pass one: ' +
+            "import WebSocket from 'ws'; new RealtimeClient({ ..., WebSocket }).");
+    }
+    return WS;
+}
+export class Channel {
+    name;
+    opts;
+    WS;
+    baseDelayMs;
+    maxDelayMs;
+    maxAttempts;
+    bufferSize;
+    expirySkewMs;
+    _state = 'idle';
+    ws = null;
+    attempt = 0; // number of the UPCOMING retry; reset to 0 on open
+    timer = null;
+    userClosed = false;
+    cached = null;
+    buffer = [];
+    /** true between (re)open and the first server frame — gates the buffer flush */
+    awaitingFlush = false;
+    flushFallback;
+    openPromise = null;
+    resolveOpen = null;
+    rejectOpen = null;
+    everOpened = false;
+    listeners = new Map();
+    stateListeners = new Set();
+    presenceListeners = new Map();
+    membersMap = new Map();
+    /** Presence helpers. `members` is client-side bookkeeping: seeded/replaced by
+     *  the server's `presence.state` on EVERY open, mutated by join/leave in
+     *  between — best-effort between syncs (multi-tab counts can drift; the next
+     *  reconnect re-syncs). */
+    presence;
+    constructor(name, opts, ws) {
+        this.name = name;
+        this.opts = opts;
+        this.WS = ws;
+        this.baseDelayMs = opts.reconnect?.baseDelayMs ?? 500;
+        this.maxDelayMs = opts.reconnect?.maxDelayMs ?? 30_000;
+        this.maxAttempts = opts.reconnect?.maxAttempts ?? Infinity;
+        this.bufferSize = opts.sendBufferSize ?? 100;
+        this.expirySkewMs = opts.expirySkewMs ?? 5_000;
+        this.presence = {
+            members: this.membersMap,
+            on: (ev, cb) => {
+                const set = this.presenceListeners.get(ev) ?? new Set();
+                this.presenceListeners.set(ev, set);
+                set.add(cb);
+                return () => set.delete(cb);
+            },
+        };
+    }
+    get state() {
+        return this._state;
+    }
+    /** Open (or re-open after unsubscribe) the channel. Resolves on the first
+     *  'open'; rejects if maxAttempts is exhausted before ever opening, or on
+     *  unsubscribe()/close() while still connecting. */
+    subscribe() {
+        if (this._state === 'open')
+            return Promise.resolve();
+        if (this.openPromise)
+            return this.openPromise;
+        this.openPromise = new Promise((res, rej) => {
+            this.resolveOpen = res;
+            this.rejectOpen = rej;
+        });
+        // A pending subscribe() the caller chose not to await must not surface as
+        // an unhandled rejection; attaching one internal handler marks it handled
+        // for everyone while still rejecting awaiting callers.
+        this.openPromise.catch(() => { });
+        if (this._state === 'idle' || this._state === 'closed') {
+            this.userClosed = false;
+            this.attempt = 0;
+            this.everOpened = false;
+            void this.connect();
+        }
+        return this.openPromise;
+    }
+    /** Deliberate close: state → 'closed', no reconnect, buffer kept as-is. */
+    unsubscribe() {
+        this.userClosed = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        if (ws) {
+            try {
+                ws.close(1000, 'unsubscribe');
+            }
+            catch {
+                /* already closing */
+            }
+        }
+        this.settleOpen(new Error('unsubscribed'));
+        this.setState('closed');
+    }
+    /** Listen for frames by exact event name, or '*' for everything. Returns a
+     *  disposer. `pong` frames are internal and never dispatched. */
+    on(event, cb) {
+        const set = this.listeners.get(event) ?? new Set();
+        this.listeners.set(event, set);
+        set.add(cb);
+        return () => this.off(event, cb);
+    }
+    off(event, cb) {
+        this.listeners.get(event)?.delete(cb);
+    }
+    onState(cb) {
+        this.stateListeners.add(cb);
+        return () => this.stateListeners.delete(cb);
+    }
+    /** Send a client frame. Open → sent now (true). Disconnected → buffered
+     *  FIFO up to sendBufferSize, flushed on the next open; when the buffer
+     *  overflows the OLDEST frame is dropped and send() returns false (so does
+     *  a send with buffering disabled). Frames over 1024 chars are still sent
+     *  but the server will drop them (a console.warn flags it). */
+    send(frame) {
+        const text = JSON.stringify(frame);
+        if (text.length > 1024) {
+            console.warn(`[@vxil/realtime] frame is ${text.length} chars; the server drops frames over 1024`);
+        }
+        // readyState guard: WHATWG send() THROWS only on CONNECTING — on a
+        // CLOSING/CLOSED socket it silently discards. Between a transport-level
+        // close and the 'close' event reaching us (seen ~10s on staging: the DO
+        // completes the close handshake lazily) this client still believes it is
+        // 'open'; without the guard a send() in that window "succeeds" into the
+        // void instead of buffering (the frame is simply lost).
+        const wsOpen = this.ws && (this.ws.readyState === undefined || this.ws.readyState === 1);
+        if (this._state === 'open' && this.ws && wsOpen) {
+            try {
+                this.ws.send(text);
+                return true;
+            }
+            catch {
+                /* socket died under us — fall through to the buffer */
+            }
+        }
+        if (this.bufferSize <= 0)
+            return false;
+        this.buffer.push(text);
+        if (this.buffer.length > this.bufferSize) {
+            this.buffer.shift(); // drop-oldest
+            return false;
+        }
+        return true;
+    }
+    /** Ephemeral typing signal — never buffered (replaying a stale typing
+     *  indicator after a reconnect would be wrong). Server-gated on presence. */
+    typing() {
+        this.sendEphemeral('{"type":"typing"}');
+    }
+    /** Ephemeral keepalive — never buffered. Server replies `pong` (swallowed). */
+    ping() {
+        this.sendEphemeral('{"type":"ping"}');
+    }
+    // ---- internals -----------------------------------------------------------
+    sendEphemeral(text) {
+        if (this._state !== 'open' || !this.ws)
+            return;
+        try {
+            this.ws.send(text);
+        }
+        catch {
+            /* closing — the close handler reconnects */
+        }
+    }
+    setState(state, detail) {
+        this._state = state;
+        for (const cb of [...this.stateListeners])
+            cb(state, detail);
+    }
+    settleOpen(error) {
+        const res = this.resolveOpen;
+        const rej = this.rejectOpen;
+        this.openPromise = null;
+        this.resolveOpen = null;
+        this.rejectOpen = null;
+        if (error !== undefined)
+            rej?.(error);
+        else
+            res?.();
+    }
+    /** Cached-or-fresh connect URL. Re-mints via the tokenProvider when the
+     *  cached token is absent, has no expires_at, or is within expirySkewMs of
+     *  expiry — which also covers the "server rejected the token" case: a
+     *  browser only ever sees close 1006, and by the time that matters the
+     *  token is expired or near-expiry and gets re-minted on the next attempt. */
+    async resolveUrl() {
+        const c = this.cached;
+        if (c && c.expiresAt !== null && c.expiresAt - Date.now() > this.expirySkewMs) {
+            return c.url;
+        }
+        const r = await this.opts.tokenProvider({ channel: this.name });
+        const url = this.urlFrom(r);
+        const parsed = r.expires_at ? Date.parse(r.expires_at) : NaN;
+        this.cached = { url, expiresAt: Number.isNaN(parsed) ? null : parsed };
+        return url;
+    }
+    urlFrom(r) {
+        if (r.connect_url)
+            return r.connect_url;
+        const base = (this.opts.baseUrl ?? DEFAULT_BASE).replace(/^http/, 'ws');
+        if (r.connect_path)
+            return `${base}${r.connect_path}`;
+        if (r.token)
+            return `${base}/v1/realtime/connect?token=${encodeURIComponent(r.token)}`;
+        throw new Error('[@vxil/realtime] tokenProvider returned none of connect_url / connect_path / token');
+    }
+    async connect() {
+        if (this.userClosed)
+            return;
+        this.setState('connecting');
+        let url;
+        try {
+            url = await this.resolveUrl();
+        }
+        catch (error) {
+            // tokenProvider failure counts as a failed attempt: back off and retry.
+            if (!this.userClosed)
+                this.scheduleReconnect(error);
+            return;
+        }
+        if (this.userClosed)
+            return;
+        let ws;
+        try {
+            ws = new this.WS(url);
+        }
+        catch (error) {
+            this.scheduleReconnect(error);
+            return;
+        }
+        this.ws = ws;
+        ws.addEventListener('open', () => {
+            if (this.ws !== ws || this.userClosed)
+                return;
+            this.handleOpen();
+        });
+        ws.addEventListener('message', (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.handleMessage(typeof ev.data === 'string' ? ev.data : '');
+        });
+        ws.addEventListener('close', (ev) => {
+            if (this.ws !== ws || this.userClosed)
+                return;
+            this.ws = null;
+            // A pending deferred flush dies with its socket; the buffer is retained
+            // and re-armed on the next open.
+            this.awaitingFlush = false;
+            if (this.flushFallback !== undefined) {
+                clearTimeout(this.flushFallback);
+                this.flushFallback = undefined;
+            }
+            this.scheduleReconnect(new Error(`websocket closed (code ${ev.code ?? 'unknown'})`));
+        });
+        // In browsers every 'error' is followed by 'close' — counting both would
+        // double-step the backoff, so only 'close' drives the state machine.
+        ws.addEventListener('error', () => { });
+    }
+    handleOpen() {
+        this.attempt = 0;
+        this.everOpened = true;
+        this.setState('open');
+        // Flush the offline buffer on the server's presence.state seed, NOT in the
+        // open tick: the DO registers the socket's presence just after accept, and
+        // a frame that races that registration is dropped server-side (seen live
+        // on staging as a reconnect-flushed typing frame that never rebroadcast).
+        // The seed is pushed unconditionally on accept, so it doubles as the
+        // "server is ready for frames" signal; a short timer is the fallback in
+        // case a proxy eats it.
+        if (this.buffer.length > 0) {
+            this.awaitingFlush = true;
+            this.flushFallback = setTimeout(() => this.flushBuffer(), 500);
+        }
+        this.settleOpen();
+    }
+    /** Flush the offline buffer FIFO onto the current socket (idempotent). */
+    flushBuffer() {
+        if (!this.awaitingFlush)
+            return;
+        this.awaitingFlush = false;
+        if (this.flushFallback !== undefined) {
+            clearTimeout(this.flushFallback);
+            this.flushFallback = undefined;
+        }
+        // Socket died between open and flush: keep the buffer for the next open
+        // (handleOpen re-arms the deferred flush).
+        if (!this.ws || this._state !== 'open')
+            return;
+        const pending = this.buffer;
+        this.buffer = [];
+        for (const text of pending) {
+            try {
+                this.ws?.send(text);
+            }
+            catch {
+                break;
+            }
+        }
+    }
+    scheduleReconnect(error) {
+        this.attempt += 1;
+        if (this.attempt > this.maxAttempts) {
+            this.settleOpen(this.everOpened
+                ? undefined
+                : new Error(`[@vxil/realtime] gave up after ${this.maxAttempts} attempts`));
+            this.setState('closed', { attempt: this.attempt - 1, error });
+            return;
+        }
+        this.setState('reconnecting', { attempt: this.attempt, error });
+        const raw = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (this.attempt - 1));
+        const delay = raw * (0.5 + Math.random() * 0.5); // full-jitter-halved
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.connect();
+        }, delay);
+    }
+    handleMessage(text) {
+        // Any server frame proves the DO has fully registered this socket —
+        // release the deferred post-(re)connect buffer flush (see handleOpen).
+        if (this.awaitingFlush)
+            this.flushBuffer();
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!frame || typeof frame.event !== 'string')
+            return;
+        if (frame.event === 'pong')
+            return; // internal keepalive reply, not re-emitted
+        if (frame.event.startsWith('presence.'))
+            this.handlePresence(frame);
+        this.dispatch(frame);
+    }
+    dispatch(frame) {
+        const exact = this.listeners.get(frame.event);
+        if (exact)
+            for (const cb of [...exact])
+                cb(frame);
+        const wild = this.listeners.get('*');
+        if (wild)
+            for (const cb of [...wild])
+                cb(frame);
+    }
+    emitPresence(ev, d) {
+        const set = this.presenceListeners.get(ev);
+        if (set)
+            for (const cb of [...set])
+                cb(d);
+    }
+    handlePresence(frame) {
+        const data = (frame.data ?? {});
+        if (frame.event === 'presence.state') {
+            // Authoritative roster seed (sent by the server on every accept):
+            // REPLACES whatever the client accumulated — the drift-bounding re-sync.
+            this.membersMap.clear();
+            for (const u of data.users ?? [])
+                this.membersMap.set(u.user_id, u.connections);
+            this.emitPresence('sync', { members: this.membersMap });
+            return;
+        }
+        const user = data.user_id;
+        if (frame.event === 'presence.join' && user) {
+            // The server de-dupes multi-tab joins (only a user's FIRST socket emits
+            // join), so first sight = 1 connection; presence.state re-syncs truth.
+            if (!this.membersMap.has(user))
+                this.membersMap.set(user, 1);
+            this.emitPresence('join', { user_id: user, members: this.membersMap });
+        }
+        else if (frame.event === 'presence.leave' && user) {
+            this.membersMap.delete(user);
+            this.emitPresence('leave', { user_id: user, members: this.membersMap });
+        }
+        else if (frame.event === 'presence.typing' && user) {
+            this.emitPresence('typing', { user_id: user });
+        }
+    }
+}
+export class RealtimeClient {
+    opts;
+    WS;
+    channels = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        this.WS = resolveCtor(opts.WebSocket); // fail fast, actionably
+    }
+    /** Idempotent registry: the same name always returns the same handle. */
+    channel(name) {
+        let ch = this.channels.get(name);
+        if (!ch) {
+            ch = new Channel(name, this.opts, this.WS);
+            this.channels.set(name, ch);
+        }
+        return ch;
+    }
+    /** Unsubscribes every channel (deliberate close — no reconnects). */
+    close() {
+        for (const ch of this.channels.values())
+            ch.unsubscribe();
+    }
+}
+/** Convenience mirroring the served-file import path. */
+export function createRealtimeClient(opts) {
+    return new RealtimeClient(opts);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vxil/realtime",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "Reconnecting browser/Node WebSocket client for Vxil realtime channels (auto-reconnect, token refresh, offline buffer, presence helpers).",
+  "license": "MIT",
+  "homepage": "https://vxil.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techmakerdev/vxil.git",
+    "directory": "packages/realtime"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "vxil",
+    "realtime",
+    "websocket",
+    "presence",
+    "reconnect"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}