@fluxstack/live-client 0.1.0 → 0.3.0

package/dist/live-client.browser.global.js

@@ -31,8 +31,11 @@ var FluxstackLive = (() => {
     StateValidator: () => StateValidator,
     clearPersistedState: () => clearPersistedState,
     createBinaryChunkMessage: () => createBinaryChunkMessage,
+    getConnection: () => getConnection,
     getPersistedState: () => getPersistedState,
-    persistState: () => persistState
+    onConnectionChange: () => onConnectionChange,
+    persistState: () => persistState,
+    useLive: () => useLive
   });
 
   // src/connection.ts
@@ -44,6 +47,8 @@ var FluxstackLive = (() => {
       __publicField(this, "reconnectTimeout", null);
       __publicField(this, "heartbeatInterval", null);
       __publicField(this, "componentCallbacks", /* @__PURE__ */ new Map());
+      __publicField(this, "binaryCallbacks", /* @__PURE__ */ new Map());
+      __publicField(this, "roomBinaryHandlers", /* @__PURE__ */ new Set());
       __publicField(this, "pendingRequests", /* @__PURE__ */ new Map());
       __publicField(this, "stateListeners", /* @__PURE__ */ new Set());
       __publicField(this, "_state", {
@@ -123,6 +128,7 @@ var FluxstackLive = (() => {
       this.log("Connecting...", { url });
       try {
         const ws = new WebSocket(url);
+        ws.binaryType = "arraybuffer";
         this.ws = ws;
         ws.onopen = () => {
           this.log("Connected");
@@ -131,19 +137,34 @@ var FluxstackLive = (() => {
           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 = () => {
@@ -318,6 +339,37 @@ var FluxstackLive = (() => {
         }
       });
     }
+    /** Parse and route binary frames (state delta, room events, room state) */
+    handleBinaryMessage(buffer) {
+      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);
+      return () => {
+        this.binaryCallbacks.delete(componentId);
+      };
+    }
     /** Register a component message callback */
     registerComponent(componentId, callback) {
       this.log("Registering component", componentId);
@@ -353,6 +405,8 @@ var FluxstackLive = (() => {
     destroy() {
       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 +417,25 @@ var FluxstackLive = (() => {
   };
 
   // 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 {
     constructor(connection, componentName, options = {}) {
       __publicField(this, "connection");
@@ -511,6 +584,21 @@ var FluxstackLive = (() => {
       }
       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.
@@ -523,6 +611,26 @@ var FluxstackLive = (() => {
         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 = deepMerge(this._state, delta);
+          this.notifyStateChange(this._state, delta);
+        } catch (e) {
+          console.error("Binary decode error:", e);
+        }
+      });
+    }
     /**
      * Subscribe to errors.
      * Returns an unsubscribe function.
@@ -539,7 +647,7 @@ var FluxstackLive = (() => {
         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;
@@ -547,7 +655,7 @@ var FluxstackLive = (() => {
         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;
@@ -589,6 +697,180 @@ var FluxstackLive = (() => {
   };
 
   // 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 {
     constructor(options) {
       __publicField(this, "componentId");
@@ -598,11 +880,28 @@ var FluxstackLive = (() => {
       __publicField(this, "sendMessage");
       __publicField(this, "sendMessageAndWait");
       __publicField(this, "globalUnsubscribe", null);
+      __publicField(this, "binaryUnsubscribe", null);
+      __publicField(this, "onBinaryMessage", null);
+      __publicField(this, "onMessageFactory", null);
       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;
@@ -624,10 +923,11 @@ var FluxstackLive = (() => {
           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;
         }
@@ -640,6 +940,34 @@ var FluxstackLive = (() => {
           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, {
@@ -720,7 +1048,7 @@ var FluxstackLive = (() => {
         },
         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,
@@ -730,8 +1058,13 @@ var FluxstackLive = (() => {
           });
         }
       };
-      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() {
@@ -781,6 +1114,14 @@ var FluxstackLive = (() => {
           }
         }
       });
+      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 */
@@ -795,9 +1136,12 @@ var FluxstackLive = (() => {
     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();
       }
@@ -1170,6 +1514,70 @@ var FluxstackLive = (() => {
       };
     }
   };
+
+  // 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);
+  }
   return __toCommonJS(src_exports);
 })();
 //# sourceMappingURL=live-client.browser.global.js.map