@fluxstack/live-client 0.1.0 → 0.3.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,8 @@ declare class LiveConnection {
     private reconnectTimeout;
     private heartbeatInterval;
     private componentCallbacks;
+    private binaryCallbacks;
+    private roomBinaryHandlers;
     private pendingRequests;
     private stateListeners;
     private _state;
@@ -73,6 +75,12 @@ 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 binary frames (state delta, room events, room state) */
+    private handleBinaryMessage;
+    /** Register a handler for binary room frames (0x02 / 0x03). Returns unsubscribe. */
+    registerRoomBinaryHandler(callback: (frame: Uint8Array) => void): () => void;
+    /** 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 +147,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.
@@ -159,6 +180,12 @@ declare class LiveComponentHandle<TState extends Record<string, any> = Record<st
 
 type EventHandler<T = any> = (data: T) => void;
 type Unsubscribe = () => void;
+/** Reserved keys on RoomHandle/RoomProxy — cannot be state fields */
+type RoomReservedKeys = 'id' | 'joined' | 'state' | 'join' | 'leave' | 'emit' | 'on' | 'onSystem' | 'setState';
+/** State fields accessible directly on handle/proxy (excludes reserved method names) */
+type RoomStateFields<TState> = TState extends Record<string, any> ? {
+    readonly [K in Exclude<keyof TState, RoomReservedKeys>]: TState[K];
+} : unknown;
 /** Message from client to server */
 interface RoomClientMessage {
     type: 'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_STATE_GET' | 'ROOM_STATE_SET';
@@ -178,7 +205,7 @@ interface RoomServerMessage {
     timestamp: number;
 }
 /** Interface of an individual room handle */
-interface RoomHandle<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+type RoomHandle<TState = any, TEvents extends Record<string, any> = Record<string, any>> = {
     readonly id: string;
     readonly joined: boolean;
     readonly state: TState;
@@ -188,10 +215,16 @@ interface RoomHandle<TState = any, TEvents extends Record<string, any> = Record<
     on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
     onSystem: (event: string, handler: EventHandler) => Unsubscribe;
     setState: (updates: Partial<TState>) => void;
-}
+} & RoomStateFields<TState>;
+/** Infer TEvents from a LiveRoom class (via $events brand) or use T directly as events map */
+type InferRoomEvents<T> = T extends {
+    $events: infer E extends Record<string, any>;
+} ? E : T extends Record<string, any> ? T : Record<string, any>;
 /** Proxy interface for $room - callable as function or object */
-interface RoomProxy<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
-    (roomId: string): RoomHandle<TState, TEvents>;
+type RoomProxy<TState = any, TEvents extends Record<string, any> = Record<string, any>> = {
+    /** Get a typed room handle. Pass the Room class or events interface as generic:
+     * `$room<CounterRoom>('counter:global').on('counter:updated', data => ...)` */
+    <T = TEvents>(roomId: string): RoomHandle<any, InferRoomEvents<T>>;
     readonly id: string | null;
     readonly joined: boolean;
     readonly state: TState;
@@ -201,13 +234,15 @@ interface RoomProxy<TState = any, TEvents extends Record<string, any> = Record<s
     on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
     onSystem: (event: string, handler: EventHandler) => Unsubscribe;
     setState: (updates: Partial<TState>) => void;
-}
+} & RoomStateFields<TState>;
 interface RoomManagerOptions {
     componentId: string | null;
     defaultRoom?: string;
     sendMessage: (msg: any) => void;
     sendMessageAndWait: (msg: any, timeout?: number) => Promise<any>;
     onMessage: (handler: (msg: RoomServerMessage) => void) => Unsubscribe;
+    /** Optional: register for binary room frames (0x02 ROOM_EVENT, 0x03 ROOM_STATE) */
+    onBinaryMessage?: (handler: (frame: Uint8Array) => void) => Unsubscribe;
 }
 /** Client-side room manager. Framework-agnostic. */
 declare class RoomManager<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
@@ -218,8 +253,15 @@ declare class RoomManager<TState = any, TEvents extends Record<string, any> = Re
     private sendMessage;
     private sendMessageAndWait;
     private globalUnsubscribe;
+    private binaryUnsubscribe;
+    private onBinaryMessage;
+    private onMessageFactory;
     constructor(options: RoomManagerOptions);
+    /** Re-subscribe message and binary handlers (needed after destroy/remount in React Strict Mode) */
+    resubscribe(): void;
     private handleServerMessage;
+    /** Handle binary room frames (0x02 ROOM_EVENT, 0x03 ROOM_STATE) */
+    private handleBinaryFrame;
     private getOrCreateRoom;
     /** Create handle for a specific room (cached) */
     createHandle(roomId: string): RoomHandle<TState, TEvents>;
@@ -229,7 +271,7 @@ declare class RoomManager<TState = any, TEvents extends Record<string, any> = Re
     getJoinedRooms(): string[];
     /** Update componentId (when component mounts) */
     setComponentId(id: string | null): void;
-    /** Cleanup */
+    /** Cleanup — unsubscribes handlers but keeps factory refs for resubscribe() */
     destroy(): void;
 }
 
@@ -356,4 +398,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 };