@fluxstack/live-client 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -46,6 +46,7 @@ declare class LiveConnection {
     private heartbeatInterval;
     private componentCallbacks;
     private binaryCallbacks;
+    private roomBinaryHandlers;
     private pendingRequests;
     private stateListeners;
     private _state;
@@ -74,8 +75,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 */
+    /** 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 */
@@ -177,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';
@@ -196,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;
@@ -206,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;
@@ -219,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>> {
@@ -236,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>;
@@ -247,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;
 }
 

package/dist/index.js

@@ -7,6 +7,7 @@ var LiveConnection = class {
   heartbeatInterval = null;
   componentCallbacks = /* @__PURE__ */ new Map();
   binaryCallbacks = /* @__PURE__ */ new Map();
+  roomBinaryHandlers = /* @__PURE__ */ new Set();
   pendingRequests = /* @__PURE__ */ new Map();
   stateListeners = /* @__PURE__ */ new Set();
   _state = {
@@ -298,18 +299,30 @@ var LiveConnection = class {
       }
     });
   }
-  /** Parse and route a binary BINARY_STATE_DELTA frame */
+  /** Parse and route binary frames (state delta, room events, room state) */
   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);
+    if (buffer.length < 3) return;
+    const frameType = buffer[0];
+    if (frameType === 1) {
+      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);
+    } else if (frameType === 2 || frameType === 3) {
+      for (const callback of this.roomBinaryHandlers) {
+        callback(buffer);
+      }
     }
   }
+  /** Register a handler for binary room frames (0x02 / 0x03). Returns unsubscribe. */
+  registerRoomBinaryHandler(callback) {
+    this.roomBinaryHandlers.add(callback);
+    return () => {
+      this.roomBinaryHandlers.delete(callback);
+    };
+  }
   /** Register a binary message handler for a component */
   registerBinaryHandler(componentId, callback) {
     this.binaryCallbacks.set(componentId, callback);
@@ -353,6 +366,7 @@ var LiveConnection = class {
     this.disconnect();
     this.componentCallbacks.clear();
     this.binaryCallbacks.clear();
+    this.roomBinaryHandlers.clear();
     for (const [, req] of this.pendingRequests) {
       clearTimeout(req.timeout);
       req.reject(new Error("Connection destroyed"));
@@ -363,6 +377,25 @@ var LiveConnection = class {
 };
 
 // src/component.ts
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+function deepMerge(target, source, seen) {
+  if (!seen) seen = /* @__PURE__ */ new Set();
+  if (seen.has(source)) return target;
+  seen.add(source);
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const newVal = source[key];
+    const oldVal = result[key];
+    if (isPlainObject(oldVal) && isPlainObject(newVal)) {
+      result[key] = deepMerge(oldVal, newVal, seen);
+    } else {
+      result[key] = newVal;
+    }
+  }
+  return result;
+}
 var LiveComponentHandle = class {
   connection;
   componentName;
@@ -551,7 +584,7 @@ var LiveComponentHandle = class {
     return this.connection.registerBinaryHandler(this._componentId, (payload) => {
       try {
         const delta = decoder(payload);
-        this._state = { ...this._state, ...delta };
+        this._state = deepMerge(this._state, delta);
         this.notifyStateChange(this._state, delta);
       } catch (e) {
         console.error("Binary decode error:", e);
@@ -574,7 +607,7 @@ var LiveComponentHandle = class {
       case "STATE_UPDATE": {
         const newState = msg.payload?.state;
         if (newState) {
-          this._state = { ...this._state, ...newState };
+          this._state = deepMerge(this._state, newState);
           this.notifyStateChange(this._state, null);
         }
         break;
@@ -582,7 +615,7 @@ var LiveComponentHandle = class {
       case "STATE_DELTA": {
         const delta = msg.payload?.delta;
         if (delta) {
-          this._state = { ...this._state, ...delta };
+          this._state = deepMerge(this._state, delta);
           this.notifyStateChange(this._state, delta);
         }
         break;
@@ -624,6 +657,180 @@ var LiveComponentHandle = class {
 };
 
 // src/rooms.ts
+function isPlainObject2(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+function deepMerge2(target, source, seen) {
+  if (!seen) seen = /* @__PURE__ */ new Set();
+  if (seen.has(source)) return target;
+  seen.add(source);
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const newVal = source[key];
+    const oldVal = result[key];
+    if (isPlainObject2(oldVal) && isPlainObject2(newVal)) {
+      result[key] = deepMerge2(oldVal, newVal, seen);
+    } else {
+      result[key] = newVal;
+    }
+  }
+  return result;
+}
+var BINARY_ROOM_EVENT = 2;
+var BINARY_ROOM_STATE = 3;
+var _decoder = new TextDecoder();
+function msgpackDecode(buf) {
+  return _decodeAt(buf, 0).value;
+}
+function _decodeAt(buf, offset) {
+  if (offset >= buf.length) return { value: null, offset };
+  const byte = buf[offset];
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  if (byte < 128) return { value: byte, offset: offset + 1 };
+  if (byte >= 128 && byte <= 143) return _decodeMap(buf, offset + 1, byte & 15);
+  if (byte >= 144 && byte <= 159) return _decodeArr(buf, offset + 1, byte & 15);
+  if (byte >= 160 && byte <= 191) {
+    const len = byte & 31;
+    return { value: _decoder.decode(buf.subarray(offset + 1, offset + 1 + len)), offset: offset + 1 + len };
+  }
+  if (byte >= 224) return { value: byte - 256, offset: offset + 1 };
+  switch (byte) {
+    case 192:
+      return { value: null, offset: offset + 1 };
+    case 194:
+      return { value: false, offset: offset + 1 };
+    case 195:
+      return { value: true, offset: offset + 1 };
+    case 196: {
+      const l = buf[offset + 1];
+      return { value: buf.slice(offset + 2, offset + 2 + l), offset: offset + 2 + l };
+    }
+    case 197: {
+      const l = view.getUint16(offset + 1, false);
+      return { value: buf.slice(offset + 3, offset + 3 + l), offset: offset + 3 + l };
+    }
+    case 198: {
+      const l = view.getUint32(offset + 1, false);
+      return { value: buf.slice(offset + 5, offset + 5 + l), offset: offset + 5 + l };
+    }
+    case 203:
+      return { value: view.getFloat64(offset + 1, false), offset: offset + 9 };
+    case 204:
+      return { value: buf[offset + 1], offset: offset + 2 };
+    case 205:
+      return { value: view.getUint16(offset + 1, false), offset: offset + 3 };
+    case 206:
+      return { value: view.getUint32(offset + 1, false), offset: offset + 5 };
+    case 208:
+      return { value: view.getInt8(offset + 1), offset: offset + 2 };
+    case 209:
+      return { value: view.getInt16(offset + 1, false), offset: offset + 3 };
+    case 210:
+      return { value: view.getInt32(offset + 1, false), offset: offset + 5 };
+    case 217: {
+      const l = buf[offset + 1];
+      return { value: _decoder.decode(buf.subarray(offset + 2, offset + 2 + l)), offset: offset + 2 + l };
+    }
+    case 218: {
+      const l = view.getUint16(offset + 1, false);
+      return { value: _decoder.decode(buf.subarray(offset + 3, offset + 3 + l)), offset: offset + 3 + l };
+    }
+    case 219: {
+      const l = view.getUint32(offset + 1, false);
+      return { value: _decoder.decode(buf.subarray(offset + 5, offset + 5 + l)), offset: offset + 5 + l };
+    }
+    case 220:
+      return _decodeArr(buf, offset + 3, view.getUint16(offset + 1, false));
+    case 221:
+      return _decodeArr(buf, offset + 5, view.getUint32(offset + 1, false));
+    case 222:
+      return _decodeMap(buf, offset + 3, view.getUint16(offset + 1, false));
+    case 223:
+      return _decodeMap(buf, offset + 5, view.getUint32(offset + 1, false));
+  }
+  return { value: null, offset: offset + 1 };
+}
+function _decodeArr(buf, offset, count) {
+  const arr = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const r = _decodeAt(buf, offset);
+    arr[i] = r.value;
+    offset = r.offset;
+  }
+  return { value: arr, offset };
+}
+function _decodeMap(buf, offset, count) {
+  const obj = {};
+  for (let i = 0; i < count; i++) {
+    const k = _decodeAt(buf, offset);
+    offset = k.offset;
+    const v = _decodeAt(buf, offset);
+    offset = v.offset;
+    obj[String(k.value)] = v.value;
+  }
+  return { value: obj, offset };
+}
+function parseRoomFrame(buf) {
+  if (buf.length < 6) return null;
+  let offset = 0;
+  const frameType = buf[offset++];
+  const compIdLen = buf[offset++];
+  if (offset + compIdLen > buf.length) return null;
+  const componentId = _decoder.decode(buf.subarray(offset, offset + compIdLen));
+  offset += compIdLen;
+  const roomIdLen = buf[offset++];
+  if (offset + roomIdLen > buf.length) return null;
+  const roomId = _decoder.decode(buf.subarray(offset, offset + roomIdLen));
+  offset += roomIdLen;
+  if (offset + 2 > buf.length) return null;
+  const eventLen = buf[offset] << 8 | buf[offset + 1];
+  offset += 2;
+  if (offset + eventLen > buf.length) return null;
+  const event = _decoder.decode(buf.subarray(offset, offset + eventLen));
+  offset += eventLen;
+  return { frameType, componentId, roomId, event, payload: buf.subarray(offset) };
+}
+var ROOM_RESERVED_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "joined",
+  "state",
+  "join",
+  "leave",
+  "emit",
+  "on",
+  "onSystem",
+  "setState",
+  "call",
+  "apply",
+  "bind",
+  "prototype",
+  "length",
+  "name",
+  "arguments",
+  "caller",
+  Symbol.toPrimitive,
+  Symbol.toStringTag,
+  Symbol.hasInstance
+]);
+function wrapWithStateProxy(target, getState, setStateFn) {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (ROOM_RESERVED_KEYS.has(prop) || typeof prop === "symbol") {
+        return Reflect.get(obj, prop, receiver);
+      }
+      const desc = Object.getOwnPropertyDescriptor(obj, prop);
+      if (desc) return Reflect.get(obj, prop, receiver);
+      if (prop in obj) return Reflect.get(obj, prop, receiver);
+      const st = getState();
+      return st?.[prop];
+    },
+    set(_obj, prop, value) {
+      if (typeof prop === "symbol") return false;
+      setStateFn({ [prop]: value });
+      return true;
+    }
+  });
+}
 var RoomManager = class {
   componentId;
   defaultRoom;
@@ -632,12 +839,29 @@ var RoomManager = class {
   sendMessage;
   sendMessageAndWait;
   globalUnsubscribe = null;
+  binaryUnsubscribe = null;
+  onBinaryMessage = null;
+  onMessageFactory = null;
   constructor(options) {
     this.componentId = options.componentId;
     this.defaultRoom = options.defaultRoom || null;
     this.sendMessage = options.sendMessage;
     this.sendMessageAndWait = options.sendMessageAndWait;
+    this.onBinaryMessage = options.onBinaryMessage ?? null;
+    this.onMessageFactory = options.onMessage;
     this.globalUnsubscribe = options.onMessage((msg) => this.handleServerMessage(msg));
+    if (options.onBinaryMessage) {
+      this.binaryUnsubscribe = options.onBinaryMessage((frame) => this.handleBinaryFrame(frame));
+    }
+  }
+  /** Re-subscribe message and binary handlers (needed after destroy/remount in React Strict Mode) */
+  resubscribe() {
+    if (!this.globalUnsubscribe && this.onMessageFactory) {
+      this.globalUnsubscribe = this.onMessageFactory((msg) => this.handleServerMessage(msg));
+    }
+    if (!this.binaryUnsubscribe && this.onBinaryMessage) {
+      this.binaryUnsubscribe = this.onBinaryMessage((frame) => this.handleBinaryFrame(frame));
+    }
   }
   handleServerMessage(msg) {
     if (msg.componentId !== this.componentId) return;
@@ -659,10 +883,11 @@ var RoomManager = class {
         break;
       }
       case "ROOM_STATE": {
-        room.state = { ...room.state, ...msg.data };
+        const stateChanges = msg.data?.state ?? msg.data;
+        room.state = deepMerge2(room.state, stateChanges);
         const stateHandlers = room.handlers.get("$state:change");
         if (stateHandlers) {
-          for (const handler of stateHandlers) handler(msg.data);
+          for (const handler of stateHandlers) handler(stateChanges);
         }
         break;
       }
@@ -675,6 +900,34 @@ var RoomManager = class {
         break;
     }
   }
+  /** Handle binary room frames (0x02 ROOM_EVENT, 0x03 ROOM_STATE) */
+  handleBinaryFrame(frame) {
+    const parsed = parseRoomFrame(frame);
+    if (!parsed) return;
+    if (parsed.componentId !== this.componentId) return;
+    const room = this.rooms.get(parsed.roomId);
+    if (!room) return;
+    const data = msgpackDecode(parsed.payload);
+    if (parsed.frameType === BINARY_ROOM_EVENT) {
+      const handlers = room.handlers.get(parsed.event);
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            handler(data);
+          } catch (error) {
+            console.error(`[Room:${parsed.roomId}] Handler error for '${parsed.event}':`, error);
+          }
+        }
+      }
+    } else if (parsed.frameType === BINARY_ROOM_STATE) {
+      const stateChanges = data?.state ?? data;
+      room.state = deepMerge2(room.state, stateChanges);
+      const stateHandlers = room.handlers.get("$state:change");
+      if (stateHandlers) {
+        for (const handler of stateHandlers) handler(stateChanges);
+      }
+    }
+  }
   getOrCreateRoom(roomId) {
     if (!this.rooms.has(roomId)) {
       this.rooms.set(roomId, {
@@ -755,7 +1008,7 @@ var RoomManager = class {
       },
       setState: (updates) => {
         if (!this.componentId) return;
-        room.state = { ...room.state, ...updates };
+        room.state = deepMerge2(room.state, updates);
         this.sendMessage({
           type: "ROOM_STATE_SET",
           componentId: this.componentId,
@@ -765,8 +1018,13 @@ var RoomManager = class {
         });
       }
     };
-    this.handles.set(roomId, handle);
-    return handle;
+    const proxied = wrapWithStateProxy(
+      handle,
+      () => room.state,
+      (updates) => handle.setState(updates)
+    );
+    this.handles.set(roomId, proxied);
+    return proxied;
   }
   /** Create the $room proxy */
   createProxy() {
@@ -816,6 +1074,14 @@ var RoomManager = class {
         }
       }
     });
+    if (this.defaultRoom && defaultHandle) {
+      const room = this.getOrCreateRoom(this.defaultRoom);
+      return wrapWithStateProxy(
+        proxyFn,
+        () => room.state,
+        (updates) => defaultHandle.setState(updates)
+      );
+    }
     return proxyFn;
   }
   /** List of rooms currently joined */
@@ -830,9 +1096,12 @@ var RoomManager = class {
   setComponentId(id) {
     this.componentId = id;
   }
-  /** Cleanup */
+  /** Cleanup — unsubscribes handlers but keeps factory refs for resubscribe() */
   destroy() {
     this.globalUnsubscribe?.();
+    this.globalUnsubscribe = null;
+    this.binaryUnsubscribe?.();
+    this.binaryUnsubscribe = null;
     for (const [, room] of this.rooms) {
       room.handlers.clear();
     }