@fluxstack/live-client 0.1.0 → 0.3.0

package/dist/index.js

@@ -6,6 +6,8 @@ var LiveConnection = class {
   reconnectTimeout = null;
   heartbeatInterval = null;
   componentCallbacks = /* @__PURE__ */ new Map();
+  binaryCallbacks = /* @__PURE__ */ new Map();
+  roomBinaryHandlers = /* @__PURE__ */ new Set();
   pendingRequests = /* @__PURE__ */ new Map();
   stateListeners = /* @__PURE__ */ new Set();
   _state = {
@@ -86,6 +88,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 +97,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 +299,37 @@ var LiveConnection = class {
       }
     });
   }
+  /** 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);
@@ -316,6 +365,8 @@ var LiveConnection = class {
   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"));
@@ -326,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;
@@ -474,6 +544,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 +571,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 = deepMerge(this._state, delta);
+        this.notifyStateChange(this._state, delta);
+      } catch (e) {
+        console.error("Binary decode error:", e);
+      }
+    });
+  }
   /**
    * Subscribe to errors.
    * Returns an unsubscribe function.
@@ -502,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;
@@ -510,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;
@@ -552,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;
@@ -560,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;
@@ -587,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;
       }
@@ -603,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, {
@@ -683,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,
@@ -693,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() {
@@ -744,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 */
@@ -758,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();
     }
@@ -1133,6 +1474,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 +1547,10 @@ export {
   StateValidator,
   clearPersistedState,
   createBinaryChunkMessage,
+  getConnection,
   getPersistedState,
-  persistState
+  onConnectionChange,
+  persistState,
+  useLive
 };
 //# sourceMappingURL=index.js.map