@velajs/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+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/dist/connection.d.ts

@@ -0,0 +1,43 @@
+import type { SubscriptionState } from './subscription';
+import type { ConnectionStatus, ReconnectOptions, WebSocketFactory } from './types';
+export interface ConnectionDeps {
+    makeSocket: WebSocketFactory;
+    authToken?: () => string | undefined | Promise<string | undefined>;
+    heartbeatIntervalMs: number;
+    reconnect?: ReconnectOptions;
+    onStatusChange: () => void;
+}
+/**
+ * One socket per room (vela's node transport auto-joins the `:id` route
+ * param's room; Cloudflare is one-DO≈one-room), multiplexing every live
+ * subscription for that room. Owns: connect/reconnect (decorrelated jitter),
+ * resubscribe-with-cursor on open, app-level ping keepalive (self-rescheduling
+ * setTimeout — never setInterval), and inbound `$live` frame routing into the
+ * pure frame reducer.
+ */
+export declare class RoomConnection {
+    private readonly url;
+    private readonly deps;
+    status: ConnectionStatus;
+    private socket?;
+    private readonly bySub;
+    private readonly reconnectState;
+    private reconnectTimer?;
+    private heartbeatTimer?;
+    private closedByUser;
+    private generation;
+    constructor(url: string, deps: ConnectionDeps);
+    register(state: SubscriptionState): void;
+    unregister(state: SubscriptionState): void;
+    sendPresence(room: string, meta?: unknown): void;
+    close(): void;
+    private ensureConnected;
+    private connect;
+    private handleMessage;
+    private sendSub;
+    private sendFrame;
+    private scheduleReconnect;
+    private scheduleHeartbeat;
+    private clearTimers;
+    private setStatus;
+}

package/dist/connection.js

@@ -0,0 +1,215 @@
+import { LIVE_PROTOCOL, encodeLiveEnvelope, isServerLiveFrame, readLiveEnvelope } from "@velajs/live-protocol";
+import { applyServerFrame } from "./frame-reducer.js";
+import { nextReconnectDelay, resetReconnect } from "./reconnect.js";
+import { notify } from "./subscription.js";
+const OPEN = 1;
+/**
+ * One socket per room (vela's node transport auto-joins the `:id` route
+ * param's room; Cloudflare is one-DO≈one-room), multiplexing every live
+ * subscription for that room. Owns: connect/reconnect (decorrelated jitter),
+ * resubscribe-with-cursor on open, app-level ping keepalive (self-rescheduling
+ * setTimeout — never setInterval), and inbound `$live` frame routing into the
+ * pure frame reducer.
+ */ export class RoomConnection {
+    url;
+    deps;
+    status = 'idle';
+    socket;
+    bySub = new Map();
+    reconnectState = {};
+    reconnectTimer;
+    heartbeatTimer;
+    closedByUser = false;
+    generation = 0;
+    constructor(url, deps){
+        this.url = url;
+        this.deps = deps;
+    }
+    register(state) {
+        this.bySub.set(state.sub, state);
+        if (this.socket?.readyState === OPEN) {
+            this.sendSub(state);
+        } else {
+            this.ensureConnected();
+        }
+    }
+    unregister(state) {
+        this.bySub.delete(state.sub);
+        this.sendFrame({
+            t: 'unsub',
+            sub: state.sub
+        });
+    }
+    sendPresence(room, meta) {
+        this.ensureConnected();
+        this.sendFrame({
+            t: 'presence',
+            room,
+            meta
+        });
+    }
+    close() {
+        this.closedByUser = true;
+        this.clearTimers();
+        this.socket?.close(1000, 'client closed');
+        this.socket = undefined;
+        this.setStatus('closed');
+    }
+    ensureConnected() {
+        if (this.closedByUser) return;
+        if (this.socket && this.socket.readyState <= OPEN) return; // CONNECTING or OPEN
+        void this.connect();
+    }
+    async connect() {
+        this.setStatus('connecting');
+        const generation = ++this.generation;
+        let token;
+        try {
+            token = await this.deps.authToken?.();
+        } catch  {
+            // A failing token provider is treated as a connection failure: back off
+            // and retry — the next attempt re-invokes it (rotation-friendly).
+            if (generation === this.generation) this.scheduleReconnect();
+            return;
+        }
+        if (generation !== this.generation || this.closedByUser) return;
+        const url = token === undefined ? this.url : `${this.url}${this.url.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`;
+        let socket;
+        try {
+            socket = this.deps.makeSocket(url);
+        } catch  {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = ()=>{
+            if (generation !== this.generation) return;
+            resetReconnect(this.reconnectState);
+            this.setStatus('connected');
+            // Resubscribe everything with resume watermarks — the server answers
+            // each with data (re-run), resume (untouched), or a cold snapshot.
+            for (const state of this.bySub.values())this.sendSub(state);
+            this.scheduleHeartbeat();
+        };
+        socket.onmessage = (event)=>{
+            if (typeof event.data !== 'string') return;
+            this.handleMessage(event.data);
+        };
+        socket.onclose = ()=>{
+            if (generation !== this.generation) return;
+            this.clearTimers();
+            this.socket = undefined;
+            if (this.closedByUser) return;
+            this.setStatus('offline');
+            this.scheduleReconnect();
+        };
+        socket.onerror = ()=>{
+        // onclose follows; nothing to do here.
+        };
+    }
+    handleMessage(raw) {
+        let envelope;
+        try {
+            envelope = JSON.parse(raw);
+        } catch  {
+            return;
+        }
+        const frame = readLiveEnvelope(envelope);
+        if (frame === undefined || !isServerLiveFrame(frame)) return; // classic gateway events / pong / unknown frames
+        const sub = 'sub' in frame ? frame.sub : undefined;
+        const state = sub === undefined ? undefined : this.bySub.get(sub);
+        if (!state) return;
+        const effect = applyServerFrame(state, frame);
+        switch(effect){
+            case 'notify':
+                notify(state);
+                return;
+            case 'error':
+                if (frame.t === 'error') {
+                    for (const callback of state.errorCallbacks){
+                        callback({
+                            code: frame.code,
+                            message: frame.message,
+                            fatal: frame.fatal
+                        });
+                    }
+                }
+                return;
+            case 'resubscribe':
+                // Unusable cache (epoch fork mid-delta / unmergeable delta): start
+                // cold. Same wire id ⇒ unsub first so the server replaces the record.
+                state.hasBase = false;
+                state.serverBase = undefined;
+                state.serverCursor = undefined;
+                state.serverEpoch = undefined;
+                this.sendFrame({
+                    t: 'unsub',
+                    sub: state.sub
+                });
+                this.sendSub(state);
+                return;
+            case 'none':
+                return;
+        }
+    }
+    sendSub(state) {
+        const frame = {
+            t: 'sub',
+            sub: state.sub,
+            query: state.query,
+            ...state.args === undefined ? {} : {
+                args: state.args
+            },
+            ...state.serverCursor !== undefined && state.serverEpoch !== undefined ? {
+                sinceCursor: state.serverCursor,
+                sinceEpoch: state.serverEpoch
+            } : {},
+            ...state.key === undefined ? {} : {
+                key: state.key
+            },
+            v: LIVE_PROTOCOL
+        };
+        this.sendFrame(frame);
+    }
+    sendFrame(frame) {
+        if (this.socket?.readyState !== OPEN) return; // onopen resends subscriptions
+        try {
+            this.socket.send(encodeLiveEnvelope(frame));
+        } catch  {
+        // socket died between the readyState check and send — onclose recovers
+        }
+    }
+    scheduleReconnect() {
+        if (this.closedByUser || this.reconnectTimer) return;
+        const delay = nextReconnectDelay(this.reconnectState, this.deps.reconnect?.baseMs, this.deps.reconnect?.capMs);
+        this.reconnectTimer = setTimeout(()=>{
+            this.reconnectTimer = undefined;
+            void this.connect();
+        }, delay);
+    }
+    scheduleHeartbeat() {
+        if (this.heartbeatTimer) return;
+        const tick = ()=>{
+            this.heartbeatTimer = undefined;
+            if (this.socket?.readyState !== OPEN) return;
+            try {
+                this.socket.send('{"event":"ping"}');
+            } catch  {
+                return;
+            }
+            this.heartbeatTimer = setTimeout(tick, this.deps.heartbeatIntervalMs);
+        };
+        this.heartbeatTimer = setTimeout(tick, this.deps.heartbeatIntervalMs);
+    }
+    clearTimers() {
+        if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+        if (this.heartbeatTimer) clearTimeout(this.heartbeatTimer);
+        this.reconnectTimer = undefined;
+        this.heartbeatTimer = undefined;
+    }
+    setStatus(status) {
+        if (this.status === status) return;
+        this.status = status;
+        this.deps.onStatusChange();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The client's error surface — three tiers:
+ * - connection-level: surfaced through `onConnectionStatus('offline')`;
+ * - subscription-level: `error` frames → `SubscribeOptions.onError`;
+ * - mutation-level: `mutate()` rejects with a {@link VelaLiveError}.
+ *
+ * Follows lunora's zero-dep catalog pattern (one error class, a small code
+ * union, structural guards) inlined rather than published separately.
+ */
+export declare class VelaLiveError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+export declare const isVelaLiveError: (value: unknown) => value is VelaLiveError;
+export declare const getErrorCode: (value: unknown) => string | undefined;
+/** Decode an HTTP error response into a VelaLiveError (vela's `{ error | message }` shapes tolerated). */
+export declare const toMutationError: (response: Response) => Promise<VelaLiveError>;

package/dist/errors.js

@@ -0,0 +1,36 @@
+/**
+ * The client's error surface — three tiers:
+ * - connection-level: surfaced through `onConnectionStatus('offline')`;
+ * - subscription-level: `error` frames → `SubscribeOptions.onError`;
+ * - mutation-level: `mutate()` rejects with a {@link VelaLiveError}.
+ *
+ * Follows lunora's zero-dep catalog pattern (one error class, a small code
+ * union, structural guards) inlined rather than published separately.
+ */ export class VelaLiveError extends Error {
+    code;
+    status;
+    constructor(code, message, status){
+        super(message), this.code = code, this.status = status;
+        this.name = 'VelaLiveError';
+    }
+}
+export const isVelaLiveError = (value)=>value instanceof VelaLiveError || typeof value === 'object' && value !== null && value.name === 'VelaLiveError' && typeof value.code === 'string';
+export const getErrorCode = (value)=>isVelaLiveError(value) ? value.code : undefined;
+/** Decode an HTTP error response into a VelaLiveError (vela's `{ error | message }` shapes tolerated). */ export const toMutationError = async (response)=>{
+    let code = `http_${response.status}`;
+    let message = response.statusText || `mutation failed with status ${response.status}`;
+    try {
+        const body = await response.json();
+        if (typeof body.error === 'object' && body.error !== null) {
+            code = body.error.code ?? code;
+            message = body.error.message ?? message;
+        } else if (typeof body.error === 'string') {
+            message = body.error;
+        } else if (typeof body.message === 'string') {
+            message = body.message;
+        }
+    } catch  {
+    // non-JSON body — keep the status-derived error
+    }
+    return new VelaLiveError(code, message, response.status);
+};

package/dist/frame-reducer.d.ts

@@ -0,0 +1,17 @@
+import type { ServerLiveFrame } from '@velajs/live-protocol';
+import type { SubscriptionState } from './subscription';
+/**
+ * What the connection layer must do after a frame was applied:
+ * - `notify` — the displayed value changed, fire callbacks;
+ * - `resubscribe` — the cache is unusable (epoch fork mid-delta, unmergeable
+ *   delta); send a fresh cold `sub` for this state;
+ * - `error` — an error frame; route to error callbacks;
+ * - `none` — bookkeeping only.
+ */
+export type FrameEffect = 'none' | 'notify' | 'resubscribe' | 'error';
+/**
+ * The pure per-subscription frame state machine (adapts lunora's
+ * `handleDataMessage`/`handleResumeMessage`/`handleSettledMessage`).
+ * Deliberately socket-free so the protocol semantics are unit-testable.
+ */
+export declare function applyServerFrame(state: SubscriptionState, frame: ServerLiveFrame): FrameEffect;

package/dist/frame-reducer.js

@@ -0,0 +1,66 @@
+import { DEFAULT_KEY_FIELD, applyListDelta } from "@velajs/live-protocol";
+import { dropConfirmedLayers } from "./optimistic.js";
+import { refold } from "./subscription.js";
+/**
+ * The pure per-subscription frame state machine (adapts lunora's
+ * `handleDataMessage`/`handleResumeMessage`/`handleSettledMessage`).
+ * Deliberately socket-free so the protocol semantics are unit-testable.
+ */ export function applyServerFrame(state, frame) {
+    switch(frame.t){
+        case 'ack':
+            state.acked = true;
+            return 'none';
+        case 'error':
+            return 'error';
+        case 'resume':
+            {
+                // Nothing relevant changed while away: keep the cached value, advance
+                // the watermark. Confirmed layers the new cursor covers still drop.
+                state.serverCursor = frame.cursor;
+                state.serverEpoch = frame.epoch;
+                const dropped = dropConfirmedLayers(state, frame.cursor, frame.epoch);
+                return dropped && refold(state) ? 'notify' : 'none';
+            }
+        case 'settled':
+            {
+                // Byte-identical re-run: no payload, but the cursor advance is what
+                // drops optimistic layers for writes that didn't change this query.
+                advanceWatermark(state, frame.cursor, frame.epoch);
+                const dropped = dropConfirmedLayers(state, frame.cursor, frame.epoch);
+                return dropped && refold(state) ? 'notify' : 'none';
+            }
+        case 'data':
+            {
+                if (epochForked(state, frame.epoch)) {
+                    // New timeline: every optimistic gate is void. The snapshot itself is
+                    // authoritative, so apply it as a cold first frame.
+                    state.layers = [];
+                }
+                state.serverBase = frame.snapshot;
+                state.hasBase = true;
+                advanceWatermark(state, frame.cursor, frame.epoch);
+                dropConfirmedLayers(state, frame.cursor, frame.epoch);
+                refold(state);
+                return 'notify';
+            }
+        case 'delta':
+            {
+                // A delta diffs against the baseline the server believes we confirmed —
+                // across an epoch fork or without a base that belief is wrong by
+                // construction: start over.
+                if (epochForked(state, frame.epoch) || !state.hasBase) return 'resubscribe';
+                const merged = applyListDelta(state.serverBase, frame.ops, state.key ?? DEFAULT_KEY_FIELD);
+                if (merged === undefined) return 'resubscribe';
+                state.serverBase = merged;
+                advanceWatermark(state, frame.cursor, frame.epoch);
+                dropConfirmedLayers(state, frame.cursor, frame.epoch);
+                refold(state);
+                return 'notify';
+            }
+    }
+}
+const epochForked = (state, epoch)=>epoch !== undefined && state.serverEpoch !== undefined && epoch !== state.serverEpoch;
+function advanceWatermark(state, cursor, epoch) {
+    if (cursor !== undefined) state.serverCursor = cursor;
+    if (epoch !== undefined) state.serverEpoch = epoch;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { LiveClient } from './live-client';
+export { RoomConnection } from './connection';
+export { applyServerFrame } from './frame-reducer';
+export type { FrameEffect } from './frame-reducer';
+export { applyOptimisticLayer, dropConfirmedLayers, foldOptimistic, } from './optimistic';
+export type { CommitStamp, LayerHandle, OptimisticHost, OptimisticLayer } from './optimistic';
+export { argsKeyOf, createSubscriptionState, refold, subscriptionKey, } from './subscription';
+export type { SubscriptionState } from './subscription';
+export { VelaLiveError, getErrorCode, isVelaLiveError } from './errors';
+export { DEFAULT_RECONNECT_BASE_MS, DEFAULT_RECONNECT_CAP_MS, nextReconnectDelay, resetReconnect, } from './reconnect';
+export { stableStringify } from './stable-key';
+export type { ArgsOf, ConnectionStatus, HydrationEntry, LiveClientOptions, LiveContract, LiveStore, MutateOptions, OptimisticTarget, OutboxSink, ReadCacheAdapter, ReconnectOptions, ResultOf, SubscribeOptions, Unsubscribe, WebSocketFactory, WebSocketLike, } from './types';
+export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, LIVE_EVENT, LIVE_PROTOCOL, applyListDelta, encodeListDelta, } from '@velajs/live-protocol';
+export type { ClientLiveFrame, RowOp, ServerLiveFrame } from '@velajs/live-protocol';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { LiveClient } from "./live-client.js";
+export { RoomConnection } from "./connection.js";
+export { applyServerFrame } from "./frame-reducer.js";
+export { applyOptimisticLayer, dropConfirmedLayers, foldOptimistic } from "./optimistic.js";
+export { argsKeyOf, createSubscriptionState, refold, subscriptionKey } from "./subscription.js";
+export { VelaLiveError, getErrorCode, isVelaLiveError } from "./errors.js";
+export { DEFAULT_RECONNECT_BASE_MS, DEFAULT_RECONNECT_CAP_MS, nextReconnectDelay, resetReconnect } from "./reconnect.js";
+export { stableStringify } from "./stable-key.js";
+// The wire contract, re-exported for tooling/tests.
+export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, LIVE_EVENT, LIVE_PROTOCOL, applyListDelta, encodeListDelta } from "@velajs/live-protocol";

package/dist/live-client.d.ts

@@ -0,0 +1,44 @@
+import type { ArgsOf, ConnectionStatus, HydrationEntry, LiveClientOptions, LiveContract, MutateOptions, ResultOf, SubscribeOptions, Unsubscribe } from './types';
+/**
+ * The framework-neutral Vela live client.
+ *
+ * ```ts
+ * const client = new LiveClient<AppLive>({ url: 'https://api.example.com' });
+ * const stop = client.subscribe('todos.list', { listId: 'l1' }, (todos) => render(todos));
+ * await client.mutate('/todos', { text: 'hi' }, {
+ *   optimistic: { query: 'todos.list', args: { listId: 'l1' }, apply: (t = []) => [...t, temp] },
+ * });
+ * ```
+ *
+ * Identical `(query, args, room)` subscriptions share one wire registration;
+ * reconnects resubscribe with the last cursor+epoch so untouched
+ * subscriptions resume without a re-run; optimistic updates are rebaseable
+ * layers gated on the mutation's `Vela-Commit-Cursor` response header.
+ */
+export declare class LiveClient<C extends LiveContract = LiveContract> {
+    private readonly options;
+    private readonly registry;
+    private readonly connections;
+    private readonly statusListeners;
+    private lastStatus;
+    constructor(options: LiveClientOptions);
+    subscribe<Q extends keyof C & string>(query: Q, args: ArgsOf<C, Q>, callback: (value: ResultOf<C, Q> | undefined) => void, subscribeOptions?: SubscribeOptions): Unsubscribe;
+    /** The current cached (folded) value — referentially stable between notifications. */
+    peek<Q extends keyof C & string>(query: Q, args: ArgsOf<C, Q>, room?: string): ResultOf<C, Q> | undefined;
+    /**
+     * Fire an HTTP mutation. Optimistic targets paint immediately; the layer
+     * drops when a subscription frame's cursor passes the response's
+     * `Vela-Commit-Cursor` (missing header ⇒ one-shot optimism); a rejection
+     * rolls back. Resolves with the parsed JSON body (undefined when empty).
+     */
+    mutate<R = unknown>(path: string, body?: unknown, mutateOptions?: MutateOptions): Promise<R>;
+    /** Presence heartbeat for a room (see `@velajs/client/presence` for the managed preset). */
+    presenceBeat(room: string, meta?: unknown): void;
+    /** Seed subscription state before connecting (SSR hydration). Subscribes then resume from the seeded cursor. */
+    hydrate(entries: HydrationEntry[]): void;
+    connectionStatus(): ConnectionStatus;
+    onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+    close(): void;
+    private makeStore;
+    private connectionFor;
+}

package/dist/live-client.js

@@ -0,0 +1,210 @@
+import { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER } from "@velajs/live-protocol";
+import { RoomConnection } from "./connection.js";
+import { toMutationError } from "./errors.js";
+import { applyOptimisticLayer } from "./optimistic.js";
+import { argsKeyOf, createSubscriptionState, notify, refold, subscriptionKey } from "./subscription.js";
+const DEFAULT_WS_PATH = '/rooms/:room/ws';
+const DEFAULT_ROOM = 'default';
+const DEFAULT_HEARTBEAT_MS = 30_000;
+/**
+ * The framework-neutral Vela live client.
+ *
+ * ```ts
+ * const client = new LiveClient<AppLive>({ url: 'https://api.example.com' });
+ * const stop = client.subscribe('todos.list', { listId: 'l1' }, (todos) => render(todos));
+ * await client.mutate('/todos', { text: 'hi' }, {
+ *   optimistic: { query: 'todos.list', args: { listId: 'l1' }, apply: (t = []) => [...t, temp] },
+ * });
+ * ```
+ *
+ * Identical `(query, args, room)` subscriptions share one wire registration;
+ * reconnects resubscribe with the last cursor+epoch so untouched
+ * subscriptions resume without a re-run; optimistic updates are rebaseable
+ * layers gated on the mutation's `Vela-Commit-Cursor` response header.
+ */ export class LiveClient {
+    options;
+    registry = new Map();
+    connections = new Map();
+    statusListeners = new Set();
+    lastStatus = 'idle';
+    constructor(options){
+        this.options = options;
+    }
+    subscribe(query, args, callback, subscribeOptions) {
+        const room = subscribeOptions?.room ?? this.options.defaultRoom ?? DEFAULT_ROOM;
+        const key = subscriptionKey(query, argsKeyOf(args), room);
+        let state = this.registry.get(key);
+        let fresh = false;
+        if (!state) {
+            state = createSubscriptionState(query, args, room, subscribeOptions?.key);
+            this.registry.set(key, state);
+            fresh = true;
+        }
+        const cb = callback;
+        state.callbacks.add(cb);
+        if (subscribeOptions?.onError) state.errorCallbacks.add(subscribeOptions.onError);
+        // Late joiners get the cached value synchronously (lunora parity).
+        if (state.hasBase || state.layers.length > 0) cb(state.lastValue);
+        if (fresh) this.connectionFor(room).register(state);
+        return ()=>{
+            state.callbacks.delete(cb);
+            if (subscribeOptions?.onError) state.errorCallbacks.delete(subscribeOptions.onError);
+            if (state.callbacks.size === 0) {
+                this.registry.delete(key);
+                this.connectionFor(room).unregister(state);
+            }
+        };
+    }
+    /** The current cached (folded) value — referentially stable between notifications. */ peek(query, args, room) {
+        const state = this.registry.get(subscriptionKey(query, argsKeyOf(args), room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
+        return state?.lastValue;
+    }
+    /**
+   * Fire an HTTP mutation. Optimistic targets paint immediately; the layer
+   * drops when a subscription frame's cursor passes the response's
+   * `Vela-Commit-Cursor` (missing header ⇒ one-shot optimism); a rejection
+   * rolls back. Resolves with the parsed JSON body (undefined when empty).
+   */ async mutate(path, body, mutateOptions) {
+        const handles = [];
+        const paint = (state, transform)=>{
+            const handle = applyOptimisticLayer(state, transform);
+            handles.push({
+                state,
+                handle
+            });
+            if (refold(state)) notify(state);
+        };
+        if (mutateOptions?.optimistic) {
+            const target = mutateOptions.optimistic;
+            const state = this.registry.get(subscriptionKey(target.query, argsKeyOf(target.args), target.room ?? mutateOptions.room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
+            // No live subscription for the target ⇒ nothing displays it: no-op.
+            if (state) paint(state, target.apply);
+        }
+        if (mutateOptions?.optimisticUpdate) {
+            mutateOptions.optimisticUpdate(this.makeStore(mutateOptions, paint));
+        }
+        try {
+            const doFetch = this.options.fetch ?? fetch;
+            const token = await this.options.authToken?.();
+            const headers = {
+                ...body === undefined ? {} : {
+                    'content-type': 'application/json'
+                },
+                ...token === undefined ? {} : {
+                    authorization: `Bearer ${token}`
+                },
+                ...mutateOptions?.headers
+            };
+            const response = await doFetch(new URL(path, this.options.url).toString(), {
+                method: mutateOptions?.method ?? 'POST',
+                headers,
+                ...body === undefined ? {} : {
+                    body: JSON.stringify(body)
+                }
+            });
+            if (!response.ok) throw await toMutationError(response);
+            const stamp = readCommitStamp(response);
+            for (const { state, handle } of handles){
+                // confirm() reports true when the covering frame already arrived —
+                // drop is immediate, re-fold now.
+                if (handle.confirm(stamp) && refold(state)) notify(state);
+            }
+            if (response.status === 204 || response.status === 205) return undefined;
+            try {
+                return await response.json();
+            } catch  {
+                return undefined;
+            }
+        } catch (error) {
+            for (const { state, handle } of handles){
+                if (handle.rollback() && refold(state)) notify(state);
+            }
+            throw error;
+        }
+    }
+    /** Presence heartbeat for a room (see `@velajs/client/presence` for the managed preset). */ presenceBeat(room, meta) {
+        this.connectionFor(room).sendPresence(room, meta);
+    }
+    /** Seed subscription state before connecting (SSR hydration). Subscribes then resume from the seeded cursor. */ hydrate(entries) {
+        for (const entry of entries){
+            const room = entry.room ?? this.options.defaultRoom ?? DEFAULT_ROOM;
+            const key = subscriptionKey(entry.query, argsKeyOf(entry.args), room);
+            if (this.registry.has(key)) continue;
+            const state = createSubscriptionState(entry.query, entry.args, room);
+            state.serverBase = entry.value;
+            state.hasBase = true;
+            state.lastValue = entry.value;
+            state.serverCursor = entry.cursor;
+            state.serverEpoch = entry.epoch;
+            this.registry.set(key, state);
+        }
+    }
+    connectionStatus() {
+        const statuses = [
+            ...this.connections.values()
+        ].map((connection)=>connection.status);
+        if (statuses.includes('connected')) return 'connected';
+        if (statuses.includes('connecting')) return 'connecting';
+        if (statuses.includes('offline')) return 'offline';
+        if (statuses.length > 0 && statuses.every((status)=>status === 'closed')) return 'closed';
+        return 'idle';
+    }
+    onConnectionStatus(listener) {
+        this.statusListeners.add(listener);
+        return ()=>this.statusListeners.delete(listener);
+    }
+    close() {
+        for (const connection of this.connections.values())connection.close();
+    }
+    makeStore(mutateOptions, paint) {
+        const resolve = (query, args, room)=>this.registry.get(subscriptionKey(query, argsKeyOf(args), room ?? mutateOptions.room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
+        return {
+            get: (query, args, room)=>resolve(query, args, room)?.lastValue,
+            set: (query, args, next, room)=>{
+                const state = resolve(query, args, room);
+                if (!state) return;
+                const transform = typeof next === 'function' ? next : ()=>next;
+                paint(state, transform);
+            }
+        };
+    }
+    connectionFor(room) {
+        const wsBase = (this.options.wsUrl ?? this.options.url).replace(/^http/, 'ws');
+        const template = this.options.wsPath ?? DEFAULT_WS_PATH;
+        const path = template.includes(':room') ? template.replace(':room', encodeURIComponent(room)) : template;
+        const url = new URL(path, wsBase).toString();
+        let connection = this.connections.get(url);
+        if (!connection) {
+            connection = new RoomConnection(url, {
+                makeSocket: this.options.WebSocket ?? ((socketUrl)=>{
+                    const WS = globalThis.WebSocket;
+                    if (!WS) {
+                        throw new Error('No WebSocket implementation available — pass one via LiveClientOptions.WebSocket');
+                    }
+                    return new WS(socketUrl);
+                }),
+                authToken: this.options.authToken,
+                heartbeatIntervalMs: this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS,
+                reconnect: this.options.reconnect,
+                onStatusChange: ()=>{
+                    const status = this.connectionStatus();
+                    if (status === this.lastStatus) return;
+                    this.lastStatus = status;
+                    for (const listener of this.statusListeners)listener(status);
+                }
+            });
+            this.connections.set(url, connection);
+        }
+        return connection;
+    }
+}
+function readCommitStamp(response) {
+    const cursor = response.headers.get(COMMIT_CURSOR_HEADER);
+    const epoch = response.headers.get(COMMIT_EPOCH_HEADER);
+    if (cursor === null || epoch === null) return undefined;
+    const parsed = Number(cursor);
+    return Number.isFinite(parsed) ? {
+        cursor: parsed,
+        epoch
+    } : undefined;
+}

package/dist/optimistic.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Rebaseable, cursor-gated optimistic layers (lunora `optimistic-layers.ts`
+ * port). The displayed value is ALWAYS the authoritative server base folded
+ * through the pending layers, so:
+ *
+ * - an unrelated server frame re-folds the layers onto the new base instead of
+ *   clobbering the optimistic state ("rebasing");
+ * - a layer drops only when a subscription frame arrives whose cursor passes
+ *   the mutation's commit cursor (same epoch) — NEVER on HTTP-response
+ *   timing, which races the broadcast;
+ * - confirm without a stamp (a non-live-aware endpoint) degrades to one-shot
+ *   optimism: the layer drops silently and the next authoritative frame
+ *   reconciles;
+ * - rollback removes the layer and re-folds so the failed write's effect
+ *   disappears immediately.
+ */
+export interface CommitStamp {
+    cursor: number;
+    epoch: string;
+}
+export interface OptimisticLayer {
+    readonly id: symbol;
+    readonly transform: (current: unknown) => unknown;
+    /** Set by confirm(); the layer is dropped by the first frame whose cursor passes it. */
+    commitCursor?: number;
+    commitEpoch?: string;
+}
+/** The slice of subscription state the optimistic engine operates on. */
+export interface OptimisticHost {
+    layers: OptimisticLayer[];
+    serverBase: unknown;
+    hasBase: boolean;
+    serverCursor?: number;
+    serverEpoch?: string;
+}
+export declare const foldOptimistic: (host: OptimisticHost) => unknown;
+export interface LayerHandle {
+    /**
+     * Record the mutation's commit stamp. With a stamp, the layer survives
+     * until a frame's cursor passes it (dropping immediately when the current
+     * frame already has). Without one, the layer is removed silently — no
+     * re-fold, the incoming authoritative frame reconciles.
+     */
+    confirm(stamp?: CommitStamp): boolean;
+    /** Remove the layer and report whether the host must re-fold + notify. */
+    rollback(): boolean;
+}
+export declare function applyOptimisticLayer(host: OptimisticHost, transform: (current: unknown) => unknown): LayerHandle;
+/**
+ * Drop every confirmed layer the frame at (cursor, epoch) covers. A layer
+ * confirmed under a DIFFERENT epoch is also dropped — its gate can never fire
+ * on this timeline. Returns whether any layer was removed (host re-folds).
+ */
+export declare function dropConfirmedLayers(host: OptimisticHost, cursor?: number, epoch?: string): boolean;

package/dist/optimistic.js

@@ -0,0 +1,67 @@
+/**
+ * Rebaseable, cursor-gated optimistic layers (lunora `optimistic-layers.ts`
+ * port). The displayed value is ALWAYS the authoritative server base folded
+ * through the pending layers, so:
+ *
+ * - an unrelated server frame re-folds the layers onto the new base instead of
+ *   clobbering the optimistic state ("rebasing");
+ * - a layer drops only when a subscription frame arrives whose cursor passes
+ *   the mutation's commit cursor (same epoch) — NEVER on HTTP-response
+ *   timing, which races the broadcast;
+ * - confirm without a stamp (a non-live-aware endpoint) degrades to one-shot
+ *   optimism: the layer drops silently and the next authoritative frame
+ *   reconciles;
+ * - rollback removes the layer and re-folds so the failed write's effect
+ *   disappears immediately.
+ */ export const foldOptimistic = (host)=>host.layers.reduce((value, layer)=>layer.transform(value), host.hasBase ? host.serverBase : undefined);
+export function applyOptimisticLayer(host, transform) {
+    const layer = {
+        id: Symbol('optimistic'),
+        transform
+    };
+    host.layers.push(layer);
+    const remove = ()=>{
+        const index = host.layers.indexOf(layer);
+        if (index === -1) return false;
+        host.layers.splice(index, 1);
+        return true;
+    };
+    return {
+        confirm (stamp) {
+            if (!stamp) {
+                remove();
+                return false;
+            }
+            // A stamp from a foreign epoch can never be gated — treat as unstamped.
+            if (host.serverEpoch !== undefined && stamp.epoch !== host.serverEpoch) {
+                remove();
+                return false;
+            }
+            layer.commitCursor = stamp.cursor;
+            layer.commitEpoch = stamp.epoch;
+            // The confirming frame may already have passed while the HTTP response
+            // was in flight — drop now and tell the caller to re-fold.
+            if (host.serverCursor !== undefined && host.serverCursor >= stamp.cursor) {
+                return remove();
+            }
+            return false;
+        },
+        rollback () {
+            return remove();
+        }
+    };
+}
+/**
+ * Drop every confirmed layer the frame at (cursor, epoch) covers. A layer
+ * confirmed under a DIFFERENT epoch is also dropped — its gate can never fire
+ * on this timeline. Returns whether any layer was removed (host re-folds).
+ */ export function dropConfirmedLayers(host, cursor, epoch) {
+    if (cursor === undefined) return false;
+    const before = host.layers.length;
+    host.layers = host.layers.filter((layer)=>{
+        if (layer.commitCursor === undefined) return true; // still pending
+        if (epoch !== undefined && layer.commitEpoch !== epoch) return false;
+        return cursor < layer.commitCursor;
+    });
+    return host.layers.length !== before;
+}

package/dist/presence.d.ts

@@ -0,0 +1,34 @@
+import type { LiveClient } from './live-client';
+import type { LiveContract } from './types';
+/**
+ * The built-in roster query name served by `@velajs/vela/live`'s presence
+ * preset (`PRESENCE_ROSTER_QUERY` on the server side).
+ */
+export declare const PRESENCE_ROSTER_QUERY = "$presence.roster";
+/** One present connection, as the server's roster query returns it. */
+export interface PresenceMember {
+    id: string;
+    meta?: unknown;
+    lastSeen: number;
+}
+export interface PresenceOptions {
+    room: string;
+    /** Payload attached to this connection's roster entry (function form re-evaluated per beat). */
+    meta?: unknown | (() => unknown);
+    /** Keep WELL under the server's TTL (default beat 10 000 ms vs 30 000 ms TTL). */
+    heartbeatIntervalMs?: number;
+    onRoster?: (members: PresenceMember[]) => void;
+}
+export interface PresenceHandle {
+    /** The last received roster (undefined until the first push). */
+    roster(): PresenceMember[] | undefined;
+    /** Send an immediate heartbeat (e.g. on visibility regain — the React binding wires this). */
+    beat(): void;
+    stop(): void;
+}
+/**
+ * Framework-neutral presence: joins a room's roster (heartbeats over the
+ * room's live socket) and subscribes to it. Departure is immediate on socket
+ * close — the heartbeat/TTL pair only covers ungraceful drops.
+ */
+export declare function createPresence(client: LiveClient<LiveContract>, options: PresenceOptions): PresenceHandle;

package/dist/presence.js

@@ -0,0 +1,45 @@
+/**
+ * The built-in roster query name served by `@velajs/vela/live`'s presence
+ * preset (`PRESENCE_ROSTER_QUERY` on the server side).
+ */ export const PRESENCE_ROSTER_QUERY = '$presence.roster';
+/**
+ * Framework-neutral presence: joins a room's roster (heartbeats over the
+ * room's live socket) and subscribes to it. Departure is immediate on socket
+ * close — the heartbeat/TTL pair only covers ungraceful drops.
+ */ export function createPresence(client, options) {
+    const intervalMs = options.heartbeatIntervalMs ?? 10_000;
+    let members;
+    let timer;
+    let stopped = false;
+    const beat = ()=>{
+        if (stopped) return;
+        const meta = typeof options.meta === 'function' ? options.meta() : options.meta;
+        client.presenceBeat(options.room, meta);
+    };
+    const tick = ()=>{
+        timer = undefined;
+        if (stopped) return;
+        beat();
+        timer = setTimeout(tick, intervalMs);
+    };
+    const unsubscribe = client.subscribe(PRESENCE_ROSTER_QUERY, {
+        room: options.room
+    }, (value)=>{
+        members = value ?? [];
+        options.onRoster?.(members);
+    }, {
+        room: options.room
+    });
+    // First beat rides after the subscription so the socket is being opened.
+    tick();
+    return {
+        roster: ()=>members,
+        beat,
+        stop () {
+            stopped = true;
+            if (timer) clearTimeout(timer);
+            timer = undefined;
+            unsubscribe();
+        }
+    };
+}

package/dist/reconnect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Decorrelated exponential jitter (lunora `reconnect.ts` port): each retry
+ * waits a random duration between the base and 3× the previous wait, capped.
+ * Decorrelation avoids the reconnect stampede a fixed exponential schedule
+ * produces when a fleet of clients drops at once.
+ */
+export interface ReconnectState {
+    previousMs?: number;
+}
+export declare const DEFAULT_RECONNECT_BASE_MS = 250;
+export declare const DEFAULT_RECONNECT_CAP_MS = 30000;
+export declare function nextReconnectDelay(state: ReconnectState, baseMs?: number, capMs?: number, random?: () => number): number;
+export declare function resetReconnect(state: ReconnectState): void;

package/dist/reconnect.js

@@ -0,0 +1,16 @@
+/**
+ * Decorrelated exponential jitter (lunora `reconnect.ts` port): each retry
+ * waits a random duration between the base and 3× the previous wait, capped.
+ * Decorrelation avoids the reconnect stampede a fixed exponential schedule
+ * produces when a fleet of clients drops at once.
+ */ export const DEFAULT_RECONNECT_BASE_MS = 250;
+export const DEFAULT_RECONNECT_CAP_MS = 30_000;
+export function nextReconnectDelay(state, baseMs = DEFAULT_RECONNECT_BASE_MS, capMs = DEFAULT_RECONNECT_CAP_MS, random = Math.random) {
+    const high = Math.max(baseMs, (state.previousMs ?? baseMs) * 3);
+    const delay = Math.min(capMs, baseMs + random() * (high - baseMs));
+    state.previousMs = delay;
+    return delay;
+}
+export function resetReconnect(state) {
+    state.previousMs = undefined;
+}

package/dist/stable-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic JSON encoding for cache/dedup keys: object keys are sorted at
+ * every depth so `{a,b}` and `{b,a}` produce the same key (lunora
+ * `shared/stable-key.ts` pattern). NOT a wire format — wire frames use plain
+ * `JSON.stringify` via @velajs/live-protocol's canonical encoders.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/stable-key.js

@@ -0,0 +1,20 @@
+/**
+ * Deterministic JSON encoding for cache/dedup keys: object keys are sorted at
+ * every depth so `{a,b}` and `{b,a}` produce the same key (lunora
+ * `shared/stable-key.ts` pattern). NOT a wire format — wire frames use plain
+ * `JSON.stringify` via @velajs/live-protocol's canonical encoders.
+ */ export function stableStringify(value) {
+    return JSON.stringify(sortDeep(value));
+}
+function sortDeep(value) {
+    if (Array.isArray(value)) return value.map(sortDeep);
+    if (typeof value === 'object' && value !== null) {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source).sort()){
+            out[key] = sortDeep(source[key]);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/subscription.d.ts

@@ -0,0 +1,42 @@
+import type { OptimisticLayer } from './optimistic';
+/**
+ * One deduped live subscription: every `subscribe()` for the same
+ * (query, args, room) joins a single state (one wire registration, N
+ * callbacks), lunora `subscription.ts` style.
+ */
+export interface SubscriptionState {
+    /** Wire subscription id — client-chosen, unique per client (thus per socket). */
+    sub: string;
+    query: string;
+    args: unknown;
+    argsKey: string;
+    room: string;
+    key?: string;
+    /** Server acknowledged the registration. */
+    acked: boolean;
+    callbacks: Set<(value: unknown) => void>;
+    errorCallbacks: Set<(error: {
+        code: string;
+        message: string;
+        fatal: boolean;
+    }) => void>;
+    layers: OptimisticLayer[];
+    /** Authoritative value with NO optimistic overlay. */
+    serverBase: unknown;
+    /** Distinguishes "no value yet" from an authoritative `undefined`-shaped value. */
+    hasBase: boolean;
+    serverCursor?: number;
+    serverEpoch?: string;
+    /**
+     * Displayed value = serverBase folded through layers. Reassigned only when
+     * something actually changed, so snapshot consumers (React's
+     * useSyncExternalStore) get referentially stable reads between notifies.
+     */
+    lastValue: unknown;
+}
+export declare const subscriptionKey: (query: string, argsKey: string, room: string) => string;
+export declare const argsKeyOf: (args: unknown) => string;
+export declare function createSubscriptionState(query: string, args: unknown, room: string, key?: string): SubscriptionState;
+/** Re-fold the displayed value; true when it changed (notify). */
+export declare function refold(state: SubscriptionState): boolean;
+export declare function notify(state: SubscriptionState): void;

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+import type { CommitStamp } from './optimistic';
+/**
+ * The app-supplied typing contract: one entry per live query, keyed by the
+ * server's `@LiveQuery(name)`. Hand-written in v1; shaped so a future
+ * `vela codegen` emission (from OpenAPI operationIds + live metadata) is a
+ * drop-in replacement.
+ *
+ * ```ts
+ * interface AppLive {
+ *   'todos.list': { args: { listId: string }; result: Todo[] };
+ * }
+ * const client = new LiveClient<AppLive>({ url });
+ * ```
+ */
+export interface LiveContract {
+    [query: string]: {
+        args: unknown;
+        result: unknown;
+    };
+}
+export type ArgsOf<C, Q extends keyof C> = C[Q] extends {
+    args: infer A;
+} ? A : never;
+export type ResultOf<C, Q extends keyof C> = C[Q] extends {
+    result: infer R;
+} ? R : never;
+export type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'offline' | 'closed';
+/** The WebSocket surface the client uses — injectable for SSR/tests/non-browser runtimes. */
+export interface WebSocketLike {
+    onopen: ((event?: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event?: unknown) => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export interface ReconnectOptions {
+    /** First-retry floor (default 250 ms). */
+    baseMs?: number;
+    /** Backoff ceiling (default 30 000 ms). */
+    capMs?: number;
+}
+export interface LiveClientOptions {
+    /** HTTP(S) base of the Vela app, e.g. `https://api.example.com`. */
+    url: string;
+    /** WS(S) base override; derived from `url` (http→ws) when omitted. */
+    wsUrl?: string;
+    /**
+     * Gateway path template the live socket connects to. A `:room` placeholder
+     * is substituted per subscription room (matching vela's node transport,
+     * which auto-joins the `:id` route param, and Cloudflare's one-DO≈one-room
+     * model). Default `/rooms/:room/ws`.
+     */
+    wsPath?: string;
+    /** Room used when a subscribe/mutate call names none. Default `'default'`. */
+    defaultRoom?: string;
+    /** Injectables — the core never touches globals directly (SSR/edge safety). */
+    WebSocket?: WebSocketFactory;
+    fetch?: typeof fetch;
+    /**
+     * Async token provider, re-invoked per socket connect and per mutation.
+     * Sockets carry it as a `?token=` query param (browsers cannot set WS
+     * headers — use short-lived rotating tokens); mutations as a Bearer header.
+     */
+    authToken?: () => string | undefined | Promise<string | undefined>;
+    /** App-level `{event:'ping'}` keepalive cadence (default 30 000 ms; CF answers without waking the DO). */
+    heartbeatIntervalMs?: number;
+    reconnect?: ReconnectOptions;
+}
+export interface SubscribeOptions {
+    room?: string;
+    /** Delta key-field override forwarded to the server (default `'id'`). */
+    key?: string;
+    onError?: (error: {
+        code: string;
+        message: string;
+        fatal: boolean;
+    }) => void;
+}
+/** Single-subscription optimistic target for `mutate()`. */
+export interface OptimisticTarget<T = unknown> {
+    query: string;
+    args?: unknown;
+    room?: string;
+    apply: (current: T | undefined) => T;
+}
+/** Multi-subscription optimistic store (the `optimisticUpdate` callback's argument). */
+export interface LiveStore {
+    get(query: string, args?: unknown, room?: string): unknown;
+    set(query: string, args: unknown, next: unknown | ((current: unknown) => unknown), room?: string): void;
+}
+export interface MutateOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    room?: string;
+    optimistic?: OptimisticTarget;
+    optimisticUpdate?: (store: LiveStore) => void;
+}
+export type Unsubscribe = () => void;
+/** Seed states before the socket connects (SSR hydration). */
+export interface HydrationEntry {
+    query: string;
+    args?: unknown;
+    room?: string;
+    value: unknown;
+    cursor?: number;
+    epoch?: string;
+}
+/** Durable offline write outbox seam — not implemented in v1 (mutations are plain HTTP). */
+export interface OutboxSink {
+    enqueue(path: string, body: unknown, options?: MutateOptions): Promise<void>;
+    onCommit?(stamp: CommitStamp): void;
+}
+/** Durable read-cache seam (IndexedDB, …) — in-memory only in v1. */
+export interface ReadCacheAdapter {
+    load(key: string): Promise<{
+        value: unknown;
+        cursor?: number;
+        epoch?: string;
+    } | undefined>;
+    persist(key: string, value: unknown, cursor?: number, epoch?: string): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+/** Durable read-cache seam (IndexedDB, …) — in-memory only in v1. */ export { };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@velajs/client",
+  "version": "0.1.0",
+  "description": "Framework-neutral client for Vela live queries: live subscriptions over WebSocket, keyed deltas, cursor-gated optimistic updates, reconnect with resume",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./presence": {
+      "types": "./dist/presence.d.ts",
+      "import": "./dist/presence.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "vela",
+    "live-queries",
+    "realtime",
+    "websocket",
+    "optimistic-updates",
+    "client"
+  ],
+  "author": "ksh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velajs/client.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/velajs/client#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/client/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@velajs/live-protocol": "^1.0.0"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.43",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.9",
+    "@velajs/vela": "^1.17.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}