@fluxstack/live-client 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,179 @@
+# @fluxstack/live-client
+
+Framework-agnostic browser client for `@fluxstack/live`.
+
+Works with any UI framework (React, Vue, Svelte, vanilla JS) or no framework at all. For React-specific bindings, see `@fluxstack/live-react`.
+
+## Installation
+
+### NPM/Bun
+
+```bash
+bun add @fluxstack/live-client
+```
+
+### Browser (IIFE)
+
+```html
+<script src="/live-client.js"></script>
+<script>
+  const counter = FluxstackLive.useLive('Counter', { count: 0 })
+</script>
+```
+
+The IIFE bundle is served automatically by any transport adapter at `/live-client.js`.
+
+## Quick Start
+
+### Vanilla JS (useLive)
+
+```typescript
+import { useLive, onConnectionChange } from '@fluxstack/live-client'
+
+// Mount a component (uses singleton connection)
+const counter = useLive('Counter', { count: 0 })
+
+// Listen for state changes
+counter.on(state => {
+  document.getElementById('count').textContent = state.count
+})
+
+// Call server actions
+document.getElementById('btn').onclick = () => counter.call('increment')
+
+// Connection status
+onConnectionChange(connected => {
+  console.log(connected ? 'Online' : 'Offline')
+})
+```
+
+### Manual Connection
+
+```typescript
+import { LiveConnection, LiveComponentHandle } from '@fluxstack/live-client'
+
+const conn = new LiveConnection({
+  url: 'ws://localhost:3000/api/live/ws',
+  autoReconnect: true,
+  reconnectInterval: 1000,
+})
+await conn.connect()
+
+const counter = new LiveComponentHandle(conn, {
+  componentName: 'Counter',
+  defaultState: { count: 0 },
+})
+
+counter.on(state => console.log('Count:', state.count))
+await counter.call('increment')
+```
+
+## API
+
+### `useLive(componentName, defaultState, options?)`
+
+High-level API using a shared connection singleton:
+
+```typescript
+const handle = useLive('Counter', { count: 0 }, {
+  url: 'ws://localhost:3000/api/live/ws',  // Auto-detected if omitted
+  room: 'my-room',                          // Optional room
+  singleton: true,                           // Singleton mount
+})
+
+handle.on(state => { ... })    // State change listener
+handle.call('action', payload) // Call server action
+handle.destroy()               // Unmount component
+```
+
+### `onConnectionChange(callback)`
+
+Subscribe to connection status changes:
+
+```typescript
+const unsubscribe = onConnectionChange(connected => { ... })
+```
+
+### `getConnection()`
+
+Access the shared connection singleton:
+
+```typescript
+const conn = getConnection()
+```
+
+### `LiveConnection`
+
+WebSocket connection manager with auto-reconnect, state rehydration, and message routing:
+
+```typescript
+const conn = new LiveConnection({
+  url: 'ws://localhost:3000/api/live/ws',
+  autoReconnect: true,
+  reconnectInterval: 1000,
+  auth: {
+    token: 'my-jwt-token',
+    provider: 'jwt',
+  },
+})
+```
+
+### `LiveComponentHandle`
+
+Handle to a remote component. Manages mounting, state updates, and action calls:
+
+```typescript
+const handle = new LiveComponentHandle(conn, {
+  componentName: 'Counter',
+  defaultState: { count: 0 },
+  room: 'optional-room',
+})
+
+handle.on(state => { ... })     // State listener
+handle.call('action', payload)  // Call action
+handle.$state                   // Current state
+handle.$connected               // Connection status
+handle.destroy()                // Unmount
+```
+
+### `RoomManager`
+
+Client-side room event management:
+
+```typescript
+const rooms = new RoomManager(conn)
+const room = rooms.join('chat-room')
+room.on('message:new', data => { ... })
+room.emit('typing', { user: 'Alice' })
+room.leave()
+```
+
+### `ChunkedUploader`
+
+Stream file uploads over WebSocket:
+
+```typescript
+const uploader = new ChunkedUploader(conn, {
+  chunkSize: 64 * 1024,
+  onProgress: (progress) => { ... },
+})
+await uploader.upload(file)
+```
+
+### State Persistence
+
+```typescript
+import { persistState, getPersistedState, clearPersistedState } from '@fluxstack/live-client'
+
+persistState('Counter', componentId, state, signature)
+const saved = getPersistedState('Counter', componentId)
+clearPersistedState('Counter', componentId)
+```
+
+## Browser IIFE Build
+
+The package includes a pre-built browser bundle at `dist/live-client.browser.global.js` that exposes a `FluxstackLive` global with all exports. Transport adapters serve this automatically at `/live-client.js`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -45,6 +45,7 @@ declare class LiveConnection {
     private reconnectTimeout;
     private heartbeatInterval;
     private componentCallbacks;
+    private binaryCallbacks;
     private pendingRequests;
     private stateListeners;
     private _state;
@@ -73,6 +74,10 @@ declare class LiveConnection {
     sendMessageAndWait(message: WebSocketMessage, timeout?: number): Promise<WebSocketResponse>;
     /** Send binary data and wait for response (for file uploads) */
     sendBinaryAndWait(data: ArrayBuffer, requestId: string, timeout?: number): Promise<WebSocketResponse>;
+    /** Parse and route a binary BINARY_STATE_DELTA frame */
+    private handleBinaryMessage;
+    /** Register a binary message handler for a component */
+    registerBinaryHandler(componentId: string, callback: (payload: Uint8Array) => void): () => void;
     /** Register a component message callback */
     registerComponent(componentId: string, callback: ComponentCallback): () => void;
     /** Unregister a component */
@@ -139,12 +144,25 @@ declare class LiveComponentHandle<TState extends Record<string, any> = Record<st
      * Returns the action's return value.
      */
     call<R = any>(action: string, payload?: Record<string, any>): Promise<R>;
+    /**
+     * Fire an action without waiting for a response (fire-and-forget).
+     * Useful for high-frequency operations like game input where the
+     * server doesn't need to send back a result.
+     */
+    fire(action: string, payload?: Record<string, any>): void;
     /**
      * Subscribe to state changes.
      * Callback receives the full new state and the delta (or null for full updates).
      * Returns an unsubscribe function.
      */
     onStateChange(callback: StateChangeCallback<TState>): () => void;
+    /**
+     * Register a binary decoder for this component.
+     * When the server sends a BINARY_STATE_DELTA frame targeting this component,
+     * the decoder converts the raw payload into a delta object which is merged into state.
+     * Returns an unsubscribe function.
+     */
+    setBinaryDecoder(decoder: (buffer: Uint8Array) => Record<string, any>): () => void;
     /**
      * Subscribe to errors.
      * Returns an unsubscribe function.
@@ -356,4 +374,81 @@ declare class StateValidator {
     static updateValidation<T>(hybridState: HybridState<T>, source?: 'client' | 'server' | 'mount'): HybridState<T>;
 }
 
-export { type AdaptiveChunkConfig, AdaptiveChunkSizer, type ChunkMetrics, type ChunkedUploadOptions, type ChunkedUploadState, ChunkedUploader, type EventHandler, type HybridState, type LiveAuthOptions, LiveComponentHandle, type LiveComponentOptions, LiveConnection, type LiveConnectionOptions, type LiveConnectionState, type PersistedState, type RoomClientMessage, type RoomHandle, RoomManager, type RoomManagerOptions, type RoomProxy, type RoomServerMessage, type StateConflict, type StateValidation, StateValidator, type Unsubscribe, clearPersistedState, createBinaryChunkMessage, getPersistedState, persistState };
+/** Status listeners for the shared connection */
+type ConnectionStatusCallback = (connected: boolean) => void;
+interface UseLiveOptions {
+    /** WebSocket URL. Auto-detected from window.location if omitted. */
+    url?: string;
+    /** Room to join on mount */
+    room?: string;
+    /** User ID for component isolation */
+    userId?: string;
+    /** Auto-mount when connected. Default: true */
+    autoMount?: boolean;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+interface UseLiveHandle<TState extends Record<string, any> = Record<string, any>> {
+    /** Call a server action */
+    call: <R = any>(action: string, payload?: Record<string, any>) => Promise<R>;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    on: (callback: (state: TState, delta: Partial<TState> | null) => void) => () => void;
+    /** Subscribe to errors. Returns unsubscribe function. */
+    onError: (callback: (error: string) => void) => () => void;
+    /** Current state (read-only snapshot) */
+    readonly state: Readonly<TState>;
+    /** Whether the component is mounted on the server */
+    readonly mounted: boolean;
+    /** Server-assigned component ID */
+    readonly componentId: string | null;
+    /** Last error message */
+    readonly error: string | null;
+    /** Destroy the component and clean up */
+    destroy: () => void;
+    /** Access the underlying LiveComponentHandle */
+    readonly handle: LiveComponentHandle<TState>;
+}
+/**
+ * Create a live component with minimal boilerplate.
+ * Manages the WebSocket connection automatically (singleton).
+ *
+ * @example Browser IIFE
+ * ```html
+ * <script src="/live-client.js"></script>
+ * <script>
+ *   const counter = FluxstackLive.useLive('Counter', { count: 0 })
+ *   counter.on(state => {
+ *     document.getElementById('count').textContent = state.count
+ *   })
+ *   document.querySelector('.inc').onclick = () => counter.call('increment')
+ * </script>
+ * ```
+ *
+ * @example ES modules
+ * ```ts
+ * import { useLive } from '@fluxstack/live-client'
+ * const counter = useLive('Counter', { count: 0 }, { url: 'ws://localhost:3000/api/live/ws' })
+ * counter.on(state => console.log(state.count))
+ * counter.call('increment')
+ * ```
+ */
+declare function useLive<TState extends Record<string, any> = Record<string, any>>(componentName: string, initialState: TState, options?: UseLiveOptions): UseLiveHandle<TState>;
+/**
+ * Subscribe to the shared connection status (connected/disconnected).
+ * Useful for showing a global status indicator.
+ *
+ * @example
+ * ```js
+ * FluxstackLive.onConnectionChange(connected => {
+ *   statusEl.textContent = connected ? 'Connected' : 'Disconnected'
+ * })
+ * ```
+ */
+declare function onConnectionChange(callback: ConnectionStatusCallback): () => void;
+/**
+ * Get or create the shared connection instance.
+ * Useful when you need direct access to the connection.
+ */
+declare function getConnection(url?: string): LiveConnection;
+
+export { type AdaptiveChunkConfig, AdaptiveChunkSizer, type ChunkMetrics, type ChunkedUploadOptions, type ChunkedUploadState, ChunkedUploader, type EventHandler, type HybridState, type LiveAuthOptions, LiveComponentHandle, type LiveComponentOptions, LiveConnection, type LiveConnectionOptions, type LiveConnectionState, type PersistedState, type RoomClientMessage, type RoomHandle, RoomManager, type RoomManagerOptions, type RoomProxy, type RoomServerMessage, type StateConflict, type StateValidation, StateValidator, type Unsubscribe, type UseLiveHandle, type UseLiveOptions, clearPersistedState, createBinaryChunkMessage, getConnection, getPersistedState, onConnectionChange, persistState, useLive };

package/dist/index.js

@@ -6,6 +6,7 @@ var LiveConnection = class {
   reconnectTimeout = null;
   heartbeatInterval = null;
   componentCallbacks = /* @__PURE__ */ new Map();
+  binaryCallbacks = /* @__PURE__ */ new Map();
   pendingRequests = /* @__PURE__ */ new Map();
   stateListeners = /* @__PURE__ */ new Set();
   _state = {
@@ -86,6 +87,7 @@ var LiveConnection = class {
     this.log("Connecting...", { url });
     try {
       const ws = new WebSocket(url);
+      ws.binaryType = "arraybuffer";
       this.ws = ws;
       ws.onopen = () => {
         this.log("Connected");
@@ -94,19 +96,34 @@ var LiveConnection = class {
         this.startHeartbeat();
       };
       ws.onmessage = (event) => {
+        if (event.data instanceof ArrayBuffer) {
+          this.handleBinaryMessage(new Uint8Array(event.data));
+          return;
+        }
         try {
-          const response = JSON.parse(event.data);
-          this.log("Received", { type: response.type, componentId: response.componentId });
-          this.handleMessage(response);
+          const parsed = JSON.parse(event.data);
+          if (Array.isArray(parsed)) {
+            for (const msg of parsed) {
+              this.log("Received", { type: msg.type, componentId: msg.componentId });
+              this.handleMessage(msg);
+            }
+          } else {
+            this.log("Received", { type: parsed.type, componentId: parsed.componentId });
+            this.handleMessage(parsed);
+          }
         } catch {
           this.log("Failed to parse message");
           this.setState({ error: "Failed to parse message" });
         }
       };
-      ws.onclose = () => {
-        this.log("Disconnected");
+      ws.onclose = (event) => {
+        this.log("Disconnected", { code: event.code, reason: event.reason });
         this.setState({ connected: false, connecting: false, connectionId: null });
         this.stopHeartbeat();
+        if (event.code === 4003) {
+          this.setState({ error: "Connection rejected: origin not allowed" });
+          return;
+        }
         this.attemptReconnect();
       };
       ws.onerror = () => {
@@ -281,6 +298,25 @@ var LiveConnection = class {
       }
     });
   }
+  /** Parse and route a binary BINARY_STATE_DELTA frame */
+  handleBinaryMessage(buffer) {
+    if (buffer.length < 3 || buffer[0] !== 1) return;
+    const idLen = buffer[1];
+    if (buffer.length < 2 + idLen) return;
+    const componentId = new TextDecoder().decode(buffer.subarray(2, 2 + idLen));
+    const payload = buffer.subarray(2 + idLen);
+    const callback = this.binaryCallbacks.get(componentId);
+    if (callback) {
+      callback(payload);
+    }
+  }
+  /** Register a binary message handler for a component */
+  registerBinaryHandler(componentId, callback) {
+    this.binaryCallbacks.set(componentId, callback);
+    return () => {
+      this.binaryCallbacks.delete(componentId);
+    };
+  }
   /** Register a component message callback */
   registerComponent(componentId, callback) {
     this.log("Registering component", componentId);
@@ -316,6 +352,7 @@ var LiveConnection = class {
   destroy() {
     this.disconnect();
     this.componentCallbacks.clear();
+    this.binaryCallbacks.clear();
     for (const [, req] of this.pendingRequests) {
       clearTimeout(req.timeout);
       req.reject(new Error("Connection destroyed"));
@@ -474,6 +511,21 @@ var LiveComponentHandle = class {
     }
     return response.result;
   }
+  /**
+   * Fire an action without waiting for a response (fire-and-forget).
+   * Useful for high-frequency operations like game input where the
+   * server doesn't need to send back a result.
+   */
+  fire(action, payload = {}) {
+    if (!this._mounted || !this._componentId) return;
+    this.connection.sendMessage({
+      type: "CALL_ACTION",
+      componentId: this._componentId,
+      action,
+      payload,
+      expectResponse: false
+    });
+  }
   // ── State ──
   /**
    * Subscribe to state changes.
@@ -486,6 +538,26 @@ var LiveComponentHandle = class {
       this.stateListeners.delete(callback);
     };
   }
+  /**
+   * Register a binary decoder for this component.
+   * When the server sends a BINARY_STATE_DELTA frame targeting this component,
+   * the decoder converts the raw payload into a delta object which is merged into state.
+   * Returns an unsubscribe function.
+   */
+  setBinaryDecoder(decoder) {
+    if (!this._componentId) {
+      throw new Error("Component must be mounted before setting binary decoder");
+    }
+    return this.connection.registerBinaryHandler(this._componentId, (payload) => {
+      try {
+        const delta = decoder(payload);
+        this._state = { ...this._state, ...delta };
+        this.notifyStateChange(this._state, delta);
+      } catch (e) {
+        console.error("Binary decode error:", e);
+      }
+    });
+  }
   /**
    * Subscribe to errors.
    * Returns an unsubscribe function.
@@ -1133,6 +1205,70 @@ var StateValidator = class {
     };
   }
 };
+
+// src/index.ts
+var _sharedConnection = null;
+var _sharedConnectionUrl = null;
+var _statusListeners = /* @__PURE__ */ new Set();
+function getOrCreateConnection(url) {
+  const resolvedUrl = url ?? `ws://${typeof location !== "undefined" ? location.host : "localhost:3000"}/api/live/ws`;
+  if (_sharedConnection && _sharedConnectionUrl === resolvedUrl) {
+    return _sharedConnection;
+  }
+  if (_sharedConnection) {
+    _sharedConnection.destroy();
+  }
+  _sharedConnection = new LiveConnection({ url: resolvedUrl });
+  _sharedConnectionUrl = resolvedUrl;
+  _sharedConnection.onStateChange((state) => {
+    for (const cb of _statusListeners) {
+      cb(state.connected);
+    }
+  });
+  return _sharedConnection;
+}
+function useLive(componentName, initialState, options = {}) {
+  const { url, room, userId, autoMount = true, debug = false } = options;
+  const connection = getOrCreateConnection(url);
+  const handle = new LiveComponentHandle(connection, componentName, {
+    initialState,
+    room,
+    userId,
+    autoMount,
+    debug
+  });
+  return {
+    call: (action, payload) => handle.call(action, payload ?? {}),
+    on: (callback) => handle.onStateChange(callback),
+    onError: (callback) => handle.onError(callback),
+    get state() {
+      return handle.state;
+    },
+    get mounted() {
+      return handle.mounted;
+    },
+    get componentId() {
+      return handle.componentId;
+    },
+    get error() {
+      return handle.error;
+    },
+    destroy: () => handle.destroy(),
+    handle
+  };
+}
+function onConnectionChange(callback) {
+  _statusListeners.add(callback);
+  if (_sharedConnection) {
+    callback(_sharedConnection.state.connected);
+  }
+  return () => {
+    _statusListeners.delete(callback);
+  };
+}
+function getConnection(url) {
+  return getOrCreateConnection(url);
+}
 export {
   AdaptiveChunkSizer,
   ChunkedUploader,
@@ -1142,7 +1278,10 @@ export {
   StateValidator,
   clearPersistedState,
   createBinaryChunkMessage,
+  getConnection,
   getPersistedState,
-  persistState
+  onConnectionChange,
+  persistState,
+  useLive
 };
 //# sourceMappingURL=index.js.map