@fluxstack/live 0.2.0 → 0.3.0

package/dist/index.js

@@ -331,6 +331,11 @@ function deduplicateDeltas(messages) {
   }
   return result;
 }
+function sendBinaryImmediate(ws, data) {
+  if (ws && ws.readyState === 1) {
+    ws.send(data);
+  }
+}
 function sendImmediate(ws, data) {
   if (ws && ws.readyState === 1) {
     ws.send(data);
@@ -374,22 +379,7 @@ function shouldLog(componentId, category) {
   if (cfg === true) return true;
   return cfg.includes(category);
 }
-var _debugger = null;
-function _setLoggerDebugger(dbg) {
-  _debugger = dbg;
-}
-function emitToDebugger(category, level, componentId, message, args) {
-  if (!_debugger?.enabled) return;
-  const data = { category, level, message };
-  if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
-    data.details = args[0];
-  } else if (args.length > 0) {
-    data.details = args;
-  }
-  _debugger.emit("LOG", componentId, null, data);
-}
 function liveLog(category, componentId, message, ...args) {
-  emitToDebugger(category, "info", componentId, message, args);
   if (shouldLog(componentId, category)) {
     if (args.length > 0) {
       console.log(message, ...args);
@@ -399,7 +389,6 @@ function liveLog(category, componentId, message, ...args) {
   }
 }
 function liveWarn(category, componentId, message, ...args) {
-  emitToDebugger(category, "warn", componentId, message, args);
   if (shouldLog(componentId, category)) {
     if (args.length > 0) {
       console.warn(message, ...args);
@@ -409,9 +398,383 @@ function liveWarn(category, componentId, message, ...args) {
   }
 }
 
+// src/utils/deepDiff.ts
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+function computeDeepDiff(prev, next, depth = 0, maxDepth = 3, seen) {
+  if (depth > maxDepth) return prev === next ? null : next;
+  if (!seen) seen = /* @__PURE__ */ new Set();
+  if (seen.has(next)) return prev === next ? null : next;
+  seen.add(next);
+  let result = null;
+  for (const key of Object.keys(next)) {
+    const oldVal = prev[key];
+    const newVal = next[key];
+    if (oldVal === newVal) continue;
+    if (isPlainObject(oldVal) && isPlainObject(newVal)) {
+      const nested = computeDeepDiff(oldVal, newVal, depth + 1, maxDepth, seen);
+      if (nested !== null) {
+        result ??= {};
+        result[key] = nested;
+      }
+    } else {
+      result ??= {};
+      result[key] = newVal;
+    }
+  }
+  return result;
+}
+function deepAssign(target, source, seen) {
+  if (!seen) seen = /* @__PURE__ */ new Set();
+  if (seen.has(source)) return;
+  seen.add(source);
+  for (const key of Object.keys(source)) {
+    if (isPlainObject(target[key]) && isPlainObject(source[key])) {
+      deepAssign(target[key], source[key], seen);
+    } else {
+      target[key] = source[key];
+    }
+  }
+}
+
+// src/rooms/RoomCodec.ts
+var BINARY_ROOM_EVENT = 2;
+var BINARY_ROOM_STATE = 3;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function msgpackEncode(value) {
+  const parts = [];
+  encode(value, parts);
+  let totalLen = 0;
+  for (const p of parts) totalLen += p.length;
+  const result = new Uint8Array(totalLen);
+  let offset = 0;
+  for (const p of parts) {
+    result.set(p, offset);
+    offset += p.length;
+  }
+  return result;
+}
+function encode(value, parts) {
+  if (value === null || value === void 0) {
+    parts.push(new Uint8Array([192]));
+    return;
+  }
+  if (typeof value === "boolean") {
+    parts.push(new Uint8Array([value ? 195 : 194]));
+    return;
+  }
+  if (typeof value === "number") {
+    if (Number.isInteger(value)) {
+      encodeInt(value, parts);
+    } else {
+      const buf = new Uint8Array(9);
+      buf[0] = 203;
+      new DataView(buf.buffer).setFloat64(1, value, false);
+      parts.push(buf);
+    }
+    return;
+  }
+  if (typeof value === "string") {
+    const encoded = encoder.encode(value);
+    const len = encoded.length;
+    if (len < 32) {
+      parts.push(new Uint8Array([160 | len]));
+    } else if (len < 256) {
+      parts.push(new Uint8Array([217, len]));
+    } else if (len < 65536) {
+      parts.push(new Uint8Array([218, len >> 8, len & 255]));
+    } else {
+      parts.push(new Uint8Array([219, len >> 24 & 255, len >> 16 & 255, len >> 8 & 255, len & 255]));
+    }
+    parts.push(encoded);
+    return;
+  }
+  if (value instanceof Uint8Array) {
+    const len = value.length;
+    if (len < 256) {
+      parts.push(new Uint8Array([196, len]));
+    } else if (len < 65536) {
+      parts.push(new Uint8Array([197, len >> 8, len & 255]));
+    } else {
+      parts.push(new Uint8Array([198, len >> 24 & 255, len >> 16 & 255, len >> 8 & 255, len & 255]));
+    }
+    parts.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    const len = value.length;
+    if (len < 16) {
+      parts.push(new Uint8Array([144 | len]));
+    } else if (len < 65536) {
+      parts.push(new Uint8Array([220, len >> 8, len & 255]));
+    } else {
+      parts.push(new Uint8Array([221, len >> 24 & 255, len >> 16 & 255, len >> 8 & 255, len & 255]));
+    }
+    for (const item of value) {
+      encode(item, parts);
+    }
+    return;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    const len = keys.length;
+    if (len < 16) {
+      parts.push(new Uint8Array([128 | len]));
+    } else if (len < 65536) {
+      parts.push(new Uint8Array([222, len >> 8, len & 255]));
+    } else {
+      parts.push(new Uint8Array([223, len >> 24 & 255, len >> 16 & 255, len >> 8 & 255, len & 255]));
+    }
+    for (const key of keys) {
+      encode(key, parts);
+      encode(value[key], parts);
+    }
+    return;
+  }
+  parts.push(new Uint8Array([192]));
+}
+function encodeInt(value, parts) {
+  if (value >= 0) {
+    if (value < 128) {
+      parts.push(new Uint8Array([value]));
+    } else if (value < 256) {
+      parts.push(new Uint8Array([204, value]));
+    } else if (value < 65536) {
+      parts.push(new Uint8Array([205, value >> 8, value & 255]));
+    } else if (value < 4294967296) {
+      parts.push(new Uint8Array([206, value >> 24 & 255, value >> 16 & 255, value >> 8 & 255, value & 255]));
+    } else {
+      const buf = new Uint8Array(9);
+      buf[0] = 203;
+      new DataView(buf.buffer).setFloat64(1, value, false);
+      parts.push(buf);
+    }
+  } else {
+    if (value >= -32) {
+      parts.push(new Uint8Array([value & 255]));
+    } else if (value >= -128) {
+      parts.push(new Uint8Array([208, value & 255]));
+    } else if (value >= -32768) {
+      const buf = new Uint8Array(3);
+      buf[0] = 209;
+      new DataView(buf.buffer).setInt16(1, value, false);
+      parts.push(buf);
+    } else if (value >= -2147483648) {
+      const buf = new Uint8Array(5);
+      buf[0] = 210;
+      new DataView(buf.buffer).setInt32(1, value, false);
+      parts.push(buf);
+    } else {
+      const buf = new Uint8Array(9);
+      buf[0] = 203;
+      new DataView(buf.buffer).setFloat64(1, value, false);
+      parts.push(buf);
+    }
+  }
+}
+function msgpackDecode(buf) {
+  const result = decodeAt(buf, 0);
+  return result.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 decodeArray(buf, offset + 1, byte & 15);
+  if (byte >= 160 && byte <= 191) {
+    const len = byte & 31;
+    const str = decoder.decode(buf.subarray(offset + 1, offset + 1 + len));
+    return { value: str, offset: offset + 1 + len };
+  }
+  if (byte >= 224) return { value: byte - 256, offset: offset + 1 };
+  switch (byte) {
+    // nil
+    case 192:
+      return { value: null, offset: offset + 1 };
+    // false
+    case 194:
+      return { value: false, offset: offset + 1 };
+    // true
+    case 195:
+      return { value: true, offset: offset + 1 };
+    // bin 8
+    case 196: {
+      const len = buf[offset + 1];
+      return { value: buf.slice(offset + 2, offset + 2 + len), offset: offset + 2 + len };
+    }
+    // bin 16
+    case 197: {
+      const len = view.getUint16(offset + 1, false);
+      return { value: buf.slice(offset + 3, offset + 3 + len), offset: offset + 3 + len };
+    }
+    // bin 32
+    case 198: {
+      const len = view.getUint32(offset + 1, false);
+      return { value: buf.slice(offset + 5, offset + 5 + len), offset: offset + 5 + len };
+    }
+    // float 64
+    case 203:
+      return { value: view.getFloat64(offset + 1, false), offset: offset + 9 };
+    // uint 8
+    case 204:
+      return { value: buf[offset + 1], offset: offset + 2 };
+    // uint 16
+    case 205:
+      return { value: view.getUint16(offset + 1, false), offset: offset + 3 };
+    // uint 32
+    case 206:
+      return { value: view.getUint32(offset + 1, false), offset: offset + 5 };
+    // int 8
+    case 208:
+      return { value: view.getInt8(offset + 1), offset: offset + 2 };
+    // int 16
+    case 209:
+      return { value: view.getInt16(offset + 1, false), offset: offset + 3 };
+    // int 32
+    case 210:
+      return { value: view.getInt32(offset + 1, false), offset: offset + 5 };
+    // str 8
+    case 217: {
+      const len = buf[offset + 1];
+      return { value: decoder.decode(buf.subarray(offset + 2, offset + 2 + len)), offset: offset + 2 + len };
+    }
+    // str 16
+    case 218: {
+      const len = view.getUint16(offset + 1, false);
+      return { value: decoder.decode(buf.subarray(offset + 3, offset + 3 + len)), offset: offset + 3 + len };
+    }
+    // str 32
+    case 219: {
+      const len = view.getUint32(offset + 1, false);
+      return { value: decoder.decode(buf.subarray(offset + 5, offset + 5 + len)), offset: offset + 5 + len };
+    }
+    // array 16
+    case 220:
+      return decodeArray(buf, offset + 3, view.getUint16(offset + 1, false));
+    // array 32
+    case 221:
+      return decodeArray(buf, offset + 5, view.getUint32(offset + 1, false));
+    // map 16
+    case 222:
+      return decodeMap(buf, offset + 3, view.getUint16(offset + 1, false));
+    // map 32
+    case 223:
+      return decodeMap(buf, offset + 5, view.getUint32(offset + 1, false));
+  }
+  return { value: null, offset: offset + 1 };
+}
+function decodeArray(buf, offset, count) {
+  const arr = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const result = decodeAt(buf, offset);
+    arr[i] = result.value;
+    offset = result.offset;
+  }
+  return { value: arr, offset };
+}
+function decodeMap(buf, offset, count) {
+  const obj = {};
+  for (let i = 0; i < count; i++) {
+    const keyResult = decodeAt(buf, offset);
+    offset = keyResult.offset;
+    const valResult = decodeAt(buf, offset);
+    offset = valResult.offset;
+    obj[String(keyResult.value)] = valResult.value;
+  }
+  return { value: obj, offset };
+}
+var msgpackCodec = {
+  encode: msgpackEncode,
+  decode: msgpackDecode
+};
+var jsonCodec = {
+  encode(data) {
+    return encoder.encode(JSON.stringify(data));
+  },
+  decode(buf) {
+    return JSON.parse(decoder.decode(buf));
+  }
+};
+function resolveCodec(option) {
+  if (!option || option === "msgpack") return msgpackCodec;
+  if (option === "json") return jsonCodec;
+  return option;
+}
+var textEncoder = encoder;
+function buildRoomFrame(frameType, componentId, roomId, event, payload) {
+  const compIdBytes = textEncoder.encode(componentId);
+  const roomIdBytes = textEncoder.encode(roomId);
+  const eventBytes = textEncoder.encode(event);
+  const totalLen = 1 + 1 + compIdBytes.length + 1 + roomIdBytes.length + 2 + eventBytes.length + payload.length;
+  const frame = new Uint8Array(totalLen);
+  let offset = 0;
+  frame[offset++] = frameType;
+  frame[offset++] = compIdBytes.length;
+  frame.set(compIdBytes, offset);
+  offset += compIdBytes.length;
+  frame[offset++] = roomIdBytes.length;
+  frame.set(roomIdBytes, offset);
+  offset += roomIdBytes.length;
+  frame[offset++] = eventBytes.length >> 8 & 255;
+  frame[offset++] = eventBytes.length & 255;
+  frame.set(eventBytes, offset);
+  offset += eventBytes.length;
+  frame.set(payload, offset);
+  return frame;
+}
+function buildRoomFrameTail(roomId, event, payload) {
+  const roomIdBytes = textEncoder.encode(roomId);
+  const eventBytes = textEncoder.encode(event);
+  const tailLen = 1 + roomIdBytes.length + 2 + eventBytes.length + payload.length;
+  const tail = new Uint8Array(tailLen);
+  let offset = 0;
+  tail[offset++] = roomIdBytes.length;
+  tail.set(roomIdBytes, offset);
+  offset += roomIdBytes.length;
+  tail[offset++] = eventBytes.length >> 8 & 255;
+  tail[offset++] = eventBytes.length & 255;
+  tail.set(eventBytes, offset);
+  offset += eventBytes.length;
+  tail.set(payload, offset);
+  return tail;
+}
+function prependMemberHeader(frameType, componentId, tail) {
+  const compIdBytes = textEncoder.encode(componentId);
+  const frame = new Uint8Array(1 + 1 + compIdBytes.length + tail.length);
+  frame[0] = frameType;
+  frame[1] = compIdBytes.length;
+  frame.set(compIdBytes, 2);
+  frame.set(tail, 2 + compIdBytes.length);
+  return frame;
+}
+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;
+  const payload = buf.subarray(offset);
+  return { frameType, componentId, roomId, event, payload };
+}
+
 // src/rooms/LiveRoomManager.ts
 var LiveRoomManager = class {
-  // componentId -> roomIds
   /**
    * @param roomEvents - Local server-side event bus
    * @param pubsub - Optional cross-instance pub/sub adapter (e.g. Redis).
@@ -424,26 +787,79 @@ var LiveRoomManager = class {
   }
   rooms = /* @__PURE__ */ new Map();
   componentRooms = /* @__PURE__ */ new Map();
+  // componentId -> roomIds
+  /** Room registry for LiveRoom class lookup. Set by LiveServer. */
+  roomRegistry;
   /**
-   * Component joins a room
+   * Component joins a room.
+   * @param options.deepDiff - Enable/disable deep diff for this room's state. Default: true
+   * @param joinContext - Optional context for LiveRoom lifecycle hooks (userId, payload)
    */
-  joinRoom(componentId, roomId, ws, initialState) {
+  joinRoom(componentId, roomId, ws, initialState, options, joinContext) {
     if (!roomId || !ROOM_NAME_REGEX.test(roomId)) {
       throw new Error("Invalid room name. Must be 1-64 alphanumeric characters, hyphens, underscores, dots, or colons.");
     }
     const now = Date.now();
     let room = this.rooms.get(roomId);
+    let isNewRoom = false;
     if (!room) {
-      room = {
-        id: roomId,
-        state: initialState || {},
-        members: /* @__PURE__ */ new Map(),
-        createdAt: now,
-        lastActivity: now
-      };
+      isNewRoom = true;
+      const roomClass = this.roomRegistry?.resolveFromId(roomId);
+      if (roomClass) {
+        const instance = new roomClass(roomId, this);
+        const opts = roomClass.$options ?? {};
+        room = {
+          id: roomId,
+          state: instance.state,
+          members: /* @__PURE__ */ new Map(),
+          createdAt: now,
+          lastActivity: now,
+          deepDiff: opts.deepDiff ?? true,
+          deepDiffDepth: opts.deepDiffDepth ?? 3,
+          serverOnlyState: true,
+          // LiveRoom-backed rooms are always server-only
+          instance,
+          codec: resolveCodec(opts.codec)
+        };
+      } else {
+        room = {
+          id: roomId,
+          state: initialState || {},
+          members: /* @__PURE__ */ new Map(),
+          createdAt: now,
+          lastActivity: now,
+          deepDiff: options?.deepDiff ?? true,
+          deepDiffDepth: options?.deepDiffDepth ?? 3,
+          serverOnlyState: options?.serverOnlyState ?? false,
+          codec: null
+        };
+      }
       this.rooms.set(roomId, room);
       liveLog("rooms", componentId, `Room '${roomId}' created`);
     }
+    if (room.instance) {
+      const ctor = room.instance.constructor;
+      const maxMembers = ctor.$options?.maxMembers;
+      if (maxMembers && room.members.size >= maxMembers) {
+        return { rejected: true, reason: "Room is full" };
+      }
+    }
+    if (room.instance) {
+      const result = room.instance.onJoin({
+        componentId,
+        userId: joinContext?.userId,
+        payload: joinContext?.payload
+      });
+      if (result === false) {
+        if (isNewRoom) {
+          this.rooms.delete(roomId);
+        }
+        return { rejected: true, reason: "Join rejected by room" };
+      }
+    }
+    if (isNewRoom && room.instance) {
+      room.instance.onCreate();
+    }
     room.members.set(componentId, {
       componentId,
       ws,
@@ -475,10 +891,17 @@ var LiveRoomManager = class {
   }
   /**
    * Component leaves a room
+   * @param leaveReason - Why the component is leaving. Default: 'leave'
    */
-  leaveRoom(componentId, roomId) {
+  leaveRoom(componentId, roomId, leaveReason = "leave") {
     const room = this.rooms.get(roomId);
     if (!room) return;
+    if (room.instance) {
+      room.instance.onLeave({
+        componentId,
+        reason: leaveReason
+      });
+    }
     room.members.delete(componentId);
     const now = Date.now();
     room.lastActivity = now;
@@ -502,6 +925,10 @@ var LiveRoomManager = class {
       setTimeout(() => {
         const currentRoom = this.rooms.get(roomId);
         if (currentRoom && currentRoom.members.size === 0) {
+          if (currentRoom.instance) {
+            const result = currentRoom.instance.onDestroy();
+            if (result === false) return;
+          }
           this.rooms.delete(roomId);
           liveLog("rooms", null, `Room '${roomId}' destroyed (empty)`);
         }
@@ -510,7 +937,7 @@ var LiveRoomManager = class {
   }
   /**
    * Component disconnects - leave all rooms.
-   * Batches removals: removes member from all rooms first,
+   * Batches removals: calls onLeave hooks, removes member from all rooms,
    * then sends leave notifications in bulk.
    */
   cleanupComponent(componentId) {
@@ -521,6 +948,12 @@ var LiveRoomManager = class {
     for (const roomId of roomIds) {
       const room = this.rooms.get(roomId);
       if (!room) continue;
+      if (room.instance) {
+        room.instance.onLeave({
+          componentId,
+          reason: "disconnect"
+        });
+      }
       room.members.delete(componentId);
       room.lastActivity = now;
       const memberCount = room.members.size;
@@ -530,7 +963,12 @@ var LiveRoomManager = class {
         setTimeout(() => {
           const currentRoom = this.rooms.get(roomId);
           if (currentRoom && currentRoom.members.size === 0) {
+            if (currentRoom.instance) {
+              const result = currentRoom.instance.onDestroy();
+              if (result === false) return;
+            }
             this.rooms.delete(roomId);
+            liveLog("rooms", null, `Room '${roomId}' destroyed (empty)`);
           }
         }, 5 * 60 * 1e3);
       }
@@ -551,13 +989,19 @@ var LiveRoomManager = class {
     this.componentRooms.delete(componentId);
   }
   /**
-   * Emit event to all members in a room
+   * Emit event to all members in a room.
+   * For LiveRoom-backed rooms, calls onEvent() hook before broadcasting.
    */
   emitToRoom(roomId, event, data, excludeComponentId) {
     const room = this.rooms.get(roomId);
     if (!room) return 0;
     const now = Date.now();
     room.lastActivity = now;
+    if (room.instance) {
+      room.instance.onEvent(event, data, {
+        componentId: excludeComponentId ?? ""
+      });
+    }
     this.roomEvents.emit("room", roomId, event, data, excludeComponentId);
     this.pubsub?.publish(roomId, event, data)?.catch(() => {
     });
@@ -572,12 +1016,35 @@ var LiveRoomManager = class {
   }
   /**
    * Update room state.
-   * Mutates state in-place with Object.assign to avoid full-object spread.
+   * When deepDiff is enabled (default), deep-diffs plain objects to send only changed fields.
+   * When disabled, uses shallow diff (reference equality) like classic behavior.
    */
   setRoomState(roomId, updates, excludeComponentId) {
     const room = this.rooms.get(roomId);
     if (!room) return;
-    Object.assign(room.state, updates);
+    let actualChanges;
+    if (room.deepDiff) {
+      const diff = computeDeepDiff(
+        room.state,
+        updates,
+        0,
+        room.deepDiffDepth
+      );
+      if (diff === null) return;
+      actualChanges = diff;
+      deepAssign(room.state, actualChanges);
+    } else {
+      actualChanges = {};
+      let hasChanges = false;
+      for (const key of Object.keys(updates)) {
+        if (room.state[key] !== updates[key]) {
+          actualChanges[key] = updates[key];
+          hasChanges = true;
+        }
+      }
+      if (!hasChanges) return;
+      Object.assign(room.state, actualChanges);
+    }
     if (room.stateSize === void 0) {
       const fullJson = JSON.stringify(room.state);
       room.stateSize = fullJson.length;
@@ -585,7 +1052,7 @@ var LiveRoomManager = class {
         throw new Error("Room state exceeds maximum size limit");
       }
     } else {
-      const deltaSize = JSON.stringify(updates).length;
+      const deltaSize = JSON.stringify(actualChanges).length;
       room.stateSize += deltaSize;
       if (room.stateSize > MAX_ROOM_STATE_SIZE) {
         const precise = JSON.stringify(room.state).length;
@@ -597,14 +1064,14 @@ var LiveRoomManager = class {
     }
     const now = Date.now();
     room.lastActivity = now;
-    this.pubsub?.publishStateChange(roomId, updates)?.catch(() => {
+    this.pubsub?.publishStateChange(roomId, actualChanges)?.catch(() => {
     });
     this.broadcastToRoom(roomId, {
       type: "ROOM_STATE",
       componentId: "",
       roomId,
       event: "$state:update",
-      data: { state: updates },
+      data: { state: actualChanges },
       timestamp: now
     }, excludeComponentId);
   }
@@ -616,27 +1083,39 @@ var LiveRoomManager = class {
   }
   /**
    * Broadcast to all members in a room.
-   * Serializes the message ONCE and sends the same string to all members.
+   *
+   * When the room has a binary codec (LiveRoom-backed), builds a binary frame
+   * once (encode payload + frame tail), then prepends per-member componentId header.
+   *
+   * When no codec (legacy rooms), uses JSON with serialize-once optimization:
+   * builds the JSON string template once, then inserts each member's componentId.
    */
   broadcastToRoom(roomId, message, excludeComponentId) {
     const room = this.rooms.get(roomId);
     if (!room || room.members.size === 0) return 0;
-    const serialized = JSON.stringify(message);
     let sent = 0;
-    if (excludeComponentId) {
-      for (const [componentId, member] of room.members) {
-        if (componentId === excludeComponentId) continue;
-        if (member.ws.readyState === 1) {
-          queuePreSerialized(member.ws, serialized);
-          sent++;
-        }
+    if (room.codec) {
+      const frameType = message.type === "ROOM_EVENT" || message.type === "ROOM_SYSTEM" ? BINARY_ROOM_EVENT : BINARY_ROOM_STATE;
+      const event = message.event ?? "";
+      const payload = room.codec.encode(message.data);
+      const tail = buildRoomFrameTail(roomId, event, payload);
+      for (const [memberComponentId, member] of room.members) {
+        if (memberComponentId === excludeComponentId) continue;
+        if (member.ws.readyState !== 1) continue;
+        const frame = prependMemberHeader(frameType, memberComponentId, tail);
+        sendBinaryImmediate(member.ws, frame);
+        sent++;
       }
     } else {
-      for (const member of room.members.values()) {
-        if (member.ws.readyState === 1) {
-          queuePreSerialized(member.ws, serialized);
-          sent++;
-        }
+      const { componentId: _, ...rest } = message;
+      const jsonBody = JSON.stringify(rest);
+      const prefix = '{"componentId":"';
+      const suffix = '",' + jsonBody.slice(1);
+      for (const [memberComponentId, member] of room.members) {
+        if (memberComponentId === excludeComponentId) continue;
+        if (member.ws.readyState !== 1) continue;
+        queuePreSerialized(member.ws, prefix + memberComponentId + suffix);
+        sent++;
       }
     }
     return sent;
@@ -647,12 +1126,31 @@ var LiveRoomManager = class {
   isInRoom(componentId, roomId) {
     return this.rooms.get(roomId)?.members.has(componentId) ?? false;
   }
+  /**
+   * Check if room state is server-only (no client writes)
+   */
+  isServerOnlyState(roomId) {
+    return this.rooms.get(roomId)?.serverOnlyState ?? false;
+  }
   /**
    * Get rooms for a component
    */
   getComponentRooms(componentId) {
     return Array.from(this.componentRooms.get(componentId) || []);
   }
+  /**
+   * Get member count for a room
+   */
+  getMemberCount(roomId) {
+    return this.rooms.get(roomId)?.members.size ?? 0;
+  }
+  /**
+   * Get the LiveRoom instance for a room (if backed by a typed room class).
+   * Used by ComponentRoomProxy to expose custom methods.
+   */
+  getRoomInstance(roomId) {
+    return this.rooms.get(roomId)?.instance;
+  }
   /**
    * Get statistics
    */
@@ -672,276 +1170,6 @@ var LiveRoomManager = class {
   }
 };
 
-// src/debug/LiveDebugger.ts
-var MAX_EVENTS = 500;
-var MAX_STATE_SIZE = 5e4;
-var LiveDebugger = class {
-  events = [];
-  componentSnapshots = /* @__PURE__ */ new Map();
-  debugClients = /* @__PURE__ */ new Set();
-  _enabled = false;
-  startTime = Date.now();
-  eventCounter = 0;
-  constructor(enabled = false) {
-    this._enabled = enabled;
-  }
-  get enabled() {
-    return this._enabled;
-  }
-  set enabled(value) {
-    this._enabled = value;
-  }
-  // ===== Event Emission =====
-  emit(type, componentId, componentName, data = {}) {
-    if (!this._enabled) return;
-    const event = {
-      id: `dbg-${++this.eventCounter}`,
-      timestamp: Date.now(),
-      type,
-      componentId,
-      componentName,
-      data: this.sanitizeData(data)
-    };
-    this.events.push(event);
-    if (this.events.length > MAX_EVENTS) {
-      this.events.shift();
-    }
-    if (componentId) {
-      this.updateSnapshot(event);
-    }
-    this.broadcastEvent(event);
-  }
-  // ===== Component Tracking =====
-  trackComponentMount(componentId, componentName, initialState, room, debugLabel) {
-    if (!this._enabled) return;
-    const snapshot = {
-      componentId,
-      componentName,
-      debugLabel,
-      state: this.sanitizeState(initialState),
-      rooms: room ? [room] : [],
-      mountedAt: Date.now(),
-      lastActivity: Date.now(),
-      actionCount: 0,
-      stateChangeCount: 0,
-      errorCount: 0
-    };
-    this.componentSnapshots.set(componentId, snapshot);
-    this.emit("COMPONENT_MOUNT", componentId, componentName, {
-      initialState: snapshot.state,
-      room: room ?? null,
-      debugLabel: debugLabel ?? null
-    });
-  }
-  trackComponentUnmount(componentId) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    const componentName = snapshot?.componentName ?? null;
-    this.emit("COMPONENT_UNMOUNT", componentId, componentName, {
-      lifetime: snapshot ? Date.now() - snapshot.mountedAt : 0,
-      totalActions: snapshot?.actionCount ?? 0,
-      totalStateChanges: snapshot?.stateChangeCount ?? 0,
-      totalErrors: snapshot?.errorCount ?? 0
-    });
-    this.componentSnapshots.delete(componentId);
-  }
-  trackStateChange(componentId, delta, fullState, source = "setState") {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    if (snapshot) {
-      snapshot.state = this.sanitizeState(fullState);
-      snapshot.stateChangeCount++;
-      snapshot.lastActivity = Date.now();
-    }
-    this.emit("STATE_CHANGE", componentId, snapshot?.componentName ?? null, {
-      delta,
-      fullState: this.sanitizeState(fullState),
-      source
-    });
-  }
-  trackActionCall(componentId, action, payload) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    if (snapshot) {
-      snapshot.actionCount++;
-      snapshot.lastActivity = Date.now();
-    }
-    this.emit("ACTION_CALL", componentId, snapshot?.componentName ?? null, {
-      action,
-      payload: this.sanitizeData({ payload }).payload
-    });
-  }
-  trackActionResult(componentId, action, result, duration) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    this.emit("ACTION_RESULT", componentId, snapshot?.componentName ?? null, {
-      action,
-      result: this.sanitizeData({ result }).result,
-      duration
-    });
-  }
-  trackActionError(componentId, action, error, duration) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    if (snapshot) {
-      snapshot.errorCount++;
-    }
-    this.emit("ACTION_ERROR", componentId, snapshot?.componentName ?? null, {
-      action,
-      error,
-      duration
-    });
-  }
-  trackRoomJoin(componentId, roomId) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    if (snapshot && !snapshot.rooms.includes(roomId)) {
-      snapshot.rooms.push(roomId);
-    }
-    this.emit("ROOM_JOIN", componentId, snapshot?.componentName ?? null, { roomId });
-  }
-  trackRoomLeave(componentId, roomId) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    if (snapshot) {
-      snapshot.rooms = snapshot.rooms.filter((r) => r !== roomId);
-    }
-    this.emit("ROOM_LEAVE", componentId, snapshot?.componentName ?? null, { roomId });
-  }
-  trackRoomEmit(componentId, roomId, event, data) {
-    if (!this._enabled) return;
-    const snapshot = this.componentSnapshots.get(componentId);
-    this.emit("ROOM_EMIT", componentId, snapshot?.componentName ?? null, {
-      roomId,
-      event,
-      data: this.sanitizeData({ data }).data
-    });
-  }
-  trackConnection(connectionId) {
-    if (!this._enabled) return;
-    this.emit("WS_CONNECT", null, null, { connectionId });
-  }
-  trackDisconnection(connectionId, componentCount) {
-    if (!this._enabled) return;
-    this.emit("WS_DISCONNECT", null, null, { connectionId, componentCount });
-  }
-  trackError(componentId, error, context) {
-    if (!this._enabled) return;
-    const snapshot = componentId ? this.componentSnapshots.get(componentId) : null;
-    if (snapshot) {
-      snapshot.errorCount++;
-    }
-    this.emit("ERROR", componentId, snapshot?.componentName ?? null, {
-      error,
-      ...context
-    });
-  }
-  // ===== Debug Client Management =====
-  registerDebugClient(ws) {
-    if (!this._enabled) {
-      const disabled = {
-        type: "DEBUG_DISABLED",
-        enabled: false,
-        timestamp: Date.now()
-      };
-      ws.send(JSON.stringify(disabled));
-      ws.close();
-      return;
-    }
-    this.debugClients.add(ws);
-    const welcome = {
-      type: "DEBUG_WELCOME",
-      enabled: true,
-      snapshot: this.getSnapshot(),
-      timestamp: Date.now()
-    };
-    ws.send(JSON.stringify(welcome));
-    for (const event of this.events.slice(-100)) {
-      const msg = {
-        type: "DEBUG_EVENT",
-        event,
-        timestamp: Date.now()
-      };
-      ws.send(JSON.stringify(msg));
-    }
-  }
-  unregisterDebugClient(ws) {
-    this.debugClients.delete(ws);
-  }
-  // ===== Snapshot =====
-  getSnapshot() {
-    return {
-      components: Array.from(this.componentSnapshots.values()),
-      connections: this.debugClients.size,
-      uptime: Date.now() - this.startTime,
-      totalEvents: this.eventCounter
-    };
-  }
-  getComponentState(componentId) {
-    return this.componentSnapshots.get(componentId) ?? null;
-  }
-  getEvents(filter) {
-    let filtered = this.events;
-    if (filter?.componentId) {
-      filtered = filtered.filter((e) => e.componentId === filter.componentId);
-    }
-    if (filter?.type) {
-      filtered = filtered.filter((e) => e.type === filter.type);
-    }
-    const limit = filter?.limit ?? 100;
-    return filtered.slice(-limit);
-  }
-  clearEvents() {
-    this.events = [];
-  }
-  // ===== Internal =====
-  broadcastEvent(event) {
-    if (this.debugClients.size === 0) return;
-    const msg = {
-      type: "DEBUG_EVENT",
-      event,
-      timestamp: Date.now()
-    };
-    const json = JSON.stringify(msg);
-    for (const client of this.debugClients) {
-      try {
-        client.send(json);
-      } catch {
-        this.debugClients.delete(client);
-      }
-    }
-  }
-  sanitizeData(data) {
-    try {
-      const json = JSON.stringify(data);
-      if (json.length > MAX_STATE_SIZE) {
-        return { _truncated: true, _size: json.length, _preview: json.slice(0, 500) + "..." };
-      }
-      return JSON.parse(json);
-    } catch {
-      return { _serialization_error: true };
-    }
-  }
-  sanitizeState(state) {
-    try {
-      const json = JSON.stringify(state);
-      if (json.length > MAX_STATE_SIZE) {
-        return { _truncated: true, _size: json.length };
-      }
-      return JSON.parse(json);
-    } catch {
-      return { _serialization_error: true };
-    }
-  }
-  updateSnapshot(event) {
-    if (!event.componentId) return;
-    const snapshot = this.componentSnapshots.get(event.componentId);
-    if (snapshot) {
-      snapshot.lastActivity = event.timestamp;
-    }
-  }
-};
-
 // src/auth/LiveAuthContext.ts
 var AuthenticatedContext = class {
   authenticated = true;
@@ -2021,18 +2249,20 @@ var ComponentStateManager = class {
   _proxyState;
   _inStateChange = false;
   _idBytes = null;
+  _deepDiff;
+  _deepDiffDepth;
   componentId;
   ws;
   emitFn;
   onStateChangeFn;
-  _debugger;
   constructor(opts) {
     this.componentId = opts.componentId;
     this.ws = opts.ws;
     this.emitFn = opts.emitFn;
     this.onStateChangeFn = opts.onStateChangeFn;
-    this._debugger = opts.debugger ?? null;
-    this._state = opts.initialState;
+    this._deepDiff = opts.deepDiff ?? false;
+    this._deepDiffDepth = opts.deepDiffDepth ?? 3;
+    this._state = this._deepDiff ? structuredClone(opts.initialState) : opts.initialState;
     this._proxyState = this.createStateProxy(this._state);
   }
   get rawState() {
@@ -2064,12 +2294,6 @@ var ComponentStateManager = class {
               self._inStateChange = false;
             }
           }
-          self._debugger?.trackStateChange(
-            self.componentId,
-            changes,
-            target,
-            "proxy"
-          );
         }
         return true;
       },
@@ -2080,16 +2304,34 @@ var ComponentStateManager = class {
   }
   setState(updates) {
     const newUpdates = typeof updates === "function" ? updates(this._state) : updates;
-    const actualChanges = {};
-    let hasChanges = false;
-    for (const key of Object.keys(newUpdates)) {
-      if (this._state[key] !== newUpdates[key]) {
-        actualChanges[key] = newUpdates[key];
-        hasChanges = true;
+    let actualChanges;
+    let hasChanges;
+    if (this._deepDiff) {
+      const diff = computeDeepDiff(
+        this._state,
+        newUpdates,
+        0,
+        this._deepDiffDepth
+      );
+      if (diff === null) return;
+      actualChanges = diff;
+      hasChanges = true;
+    } else {
+      actualChanges = {};
+      hasChanges = false;
+      for (const key of Object.keys(newUpdates)) {
+        if (this._state[key] !== newUpdates[key]) {
+          actualChanges[key] = newUpdates[key];
+          hasChanges = true;
+        }
       }
     }
     if (!hasChanges) return;
-    Object.assign(this._state, actualChanges);
+    if (this._deepDiff) {
+      deepAssign(this._state, actualChanges);
+    } else {
+      Object.assign(this._state, actualChanges);
+    }
     this.emitFn("STATE_DELTA", { delta: actualChanges });
     if (!this._inStateChange) {
       this._inStateChange = true;
@@ -2101,14 +2343,8 @@ var ComponentStateManager = class {
         this._inStateChange = false;
       }
     }
-    this._debugger?.trackStateChange(
-      this.componentId,
-      actualChanges,
-      this._state,
-      "setState"
-    );
   }
-  sendBinaryDelta(delta, encoder) {
+  sendBinaryDelta(delta, encoder2) {
     const actualChanges = {};
     let hasChanges = false;
     for (const key of Object.keys(delta)) {
@@ -2119,7 +2355,7 @@ var ComponentStateManager = class {
     }
     if (!hasChanges) return;
     Object.assign(this._state, actualChanges);
-    const payload = encoder(actualChanges);
+    const payload = encoder2(actualChanges);
     if (!this._idBytes) {
       this._idBytes = new TextEncoder().encode(this.componentId);
     }
@@ -2278,7 +2514,6 @@ var BLOCKED_ACTIONS = /* @__PURE__ */ new Set([
 var ActionSecurityManager = class {
   _actionCalls = /* @__PURE__ */ new Map();
   async validateAndExecute(action, payload, ctx) {
-    const actionStart = Date.now();
     const { component, componentClass, componentId } = ctx;
     try {
       if (BLOCKED_ACTIONS.has(action)) {
@@ -2332,12 +2567,10 @@ var ActionSecurityManager = class {
         }
         payload = result2.data ?? payload;
       }
-      ctx.debugger?.trackActionCall(componentId, action, payload);
       let hookResult;
       try {
         hookResult = await component.onAction(action, payload);
       } catch (hookError) {
-        ctx.debugger?.trackActionError(componentId, action, hookError.message, Date.now() - actionStart);
         ctx.emitFn("ERROR", {
           action,
           error: `Action '${action}' failed pre-validation`
@@ -2345,15 +2578,12 @@ var ActionSecurityManager = class {
         throw hookError;
       }
       if (hookResult === false) {
-        ctx.debugger?.trackActionError(componentId, action, "Action cancelled", Date.now() - actionStart);
         throw new Error(`Action '${action}' was cancelled`);
       }
       const result = await method.call(component, payload);
-      ctx.debugger?.trackActionResult(componentId, action, result, Date.now() - actionStart);
       return result;
     } catch (error) {
       if (!error.message?.includes("was cancelled") && !error.message?.includes("pre-validation")) {
-        ctx.debugger?.trackActionError(componentId, action, error.message, Date.now() - actionStart);
         ctx.emitFn("ERROR", {
           action,
           error: error.message
@@ -2365,6 +2595,66 @@ var ActionSecurityManager = class {
 };
 
 // src/component/managers/ComponentRoomProxy.ts
+var RESERVED_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "state",
+  "join",
+  "leave",
+  "emit",
+  "on",
+  "setState",
+  // Function internals (proxy wraps a function)
+  "call",
+  "apply",
+  "bind",
+  "prototype",
+  "length",
+  "name",
+  "arguments",
+  "caller",
+  // Symbol keys
+  Symbol.toPrimitive,
+  Symbol.toStringTag,
+  Symbol.hasInstance
+]);
+var TYPED_RESERVED_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "state",
+  "meta",
+  "join",
+  "leave",
+  "emit",
+  "on",
+  "setState",
+  "memberCount",
+  // Proxy internals
+  "then",
+  "toJSON",
+  "valueOf",
+  "toString",
+  Symbol.toPrimitive,
+  Symbol.toStringTag,
+  Symbol.hasInstance
+]);
+function wrapWithStateProxy(target, getState, setState) {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (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;
+      setState({ [prop]: value });
+      return true;
+    }
+  });
+}
 var ComponentRoomProxy = class {
   roomEventUnsubscribers = [];
   joinedRooms = /* @__PURE__ */ new Set();
@@ -2377,18 +2667,22 @@ var ComponentRoomProxy = class {
   componentId;
   ws;
   getCtx;
-  _debugger;
   setStateFn;
+  _deepDiff;
+  _deepDiffDepth;
+  _serverOnlyState;
   constructor(rctx) {
     this.componentId = rctx.componentId;
     this.ws = rctx.ws;
     this.room = rctx.defaultRoom;
     this.getCtx = rctx.getCtx;
-    this._debugger = rctx.debugger ?? null;
     this.setStateFn = rctx.setStateFn;
+    this._deepDiff = rctx.deepDiff ?? true;
+    this._deepDiffDepth = rctx.deepDiffDepth;
+    this._serverOnlyState = rctx.serverOnlyState ?? false;
     if (this.room) {
       this.joinedRooms.add(this.room);
-      this.ctx.roomManager.joinRoom(this.componentId, this.room, this.ws);
+      this.ctx.roomManager.joinRoom(this.componentId, this.room, this.ws, void 0, { deepDiff: this._deepDiff, deepDiffDepth: this._deepDiffDepth, serverOnlyState: this._serverOnlyState });
     }
   }
   /** Lazy context resolution — cached after first access */
@@ -2416,7 +2710,7 @@ var ComponentRoomProxy = class {
           if (self.joinedRooms.has(roomId)) return;
           self.joinedRooms.add(roomId);
           self._roomsCache = null;
-          self.ctx.roomManager.joinRoom(self.componentId, roomId, self.ws, initialState);
+          self.ctx.roomManager.joinRoom(self.componentId, roomId, self.ws, initialState, { deepDiff: self._deepDiff, deepDiffDepth: self._deepDiffDepth, serverOnlyState: self._serverOnlyState });
         },
         leave: () => {
           if (!self.joinedRooms.has(roomId)) return;
@@ -2442,10 +2736,20 @@ var ComponentRoomProxy = class {
           self.ctx.roomManager.setRoomState(roomId, updates, self.componentId);
         }
       };
-      this.roomHandles.set(roomId, handle);
-      return handle;
+      const proxied = wrapWithStateProxy(
+        handle,
+        () => self.ctx.roomManager.getRoomState(roomId),
+        (updates) => self.ctx.roomManager.setRoomState(roomId, updates, self.componentId)
+      );
+      this.roomHandles.set(roomId, proxied);
+      return proxied;
     };
-    const proxyFn = ((roomId) => createHandle(roomId));
+    const proxyFn = ((roomIdOrClass, instanceId) => {
+      if (typeof roomIdOrClass === "function" && instanceId !== void 0) {
+        return self.$typedRoom(roomIdOrClass, instanceId);
+      }
+      return createHandle(roomIdOrClass);
+    });
     const defaultHandle = this.room ? createHandle(this.room) : null;
     Object.defineProperties(proxyFn, {
       id: { get: () => self.room },
@@ -2481,8 +2785,113 @@ var ComponentRoomProxy = class {
         }
       }
     });
-    this._roomProxy = proxyFn;
-    return proxyFn;
+    const defaultRoom = this.room;
+    const wrapped = defaultRoom ? wrapWithStateProxy(
+      proxyFn,
+      () => self.ctx.roomManager.getRoomState(defaultRoom),
+      (updates) => self.ctx.roomManager.setRoomState(defaultRoom, updates, self.componentId)
+    ) : proxyFn;
+    this._roomProxy = wrapped;
+    return wrapped;
+  }
+  /**
+   * Get a typed room handle backed by a LiveRoom class.
+   *
+   * Usage: `this.$room(ChatRoom, 'lobby')` → typed handle with custom methods
+   *
+   * The returned handle exposes:
+   * - `.id`, `.state`, `.meta`, `.memberCount` — framework properties
+   * - `.join(payload?)`, `.leave()`, `.emit()`, `.on()`, `.setState()` — framework API
+   * - Any custom method defined on the LiveRoom subclass (e.g. `.addMessage()`, `.ban()`)
+   *
+   * The compound room ID is `${roomClass.roomName}:${instanceId}`.
+   */
+  $typedRoom(roomClass, instanceId) {
+    const roomId = `${roomClass.roomName}:${instanceId}`;
+    const self = this;
+    const cached = this.roomHandles.get(roomId);
+    if (cached) return cached;
+    const handle = {
+      get id() {
+        return roomId;
+      },
+      get state() {
+        const instance = self.ctx.roomManager.getRoomInstance?.(roomId);
+        return instance ? instance.state : self.ctx.roomManager.getRoomState(roomId);
+      },
+      get meta() {
+        const instance = self.ctx.roomManager.getRoomInstance?.(roomId);
+        if (!instance) throw new Error(`Room '${roomId}' not found or not backed by a LiveRoom class`);
+        return instance.meta;
+      },
+      get memberCount() {
+        return self.ctx.roomManager.getMemberCount?.(roomId) ?? 0;
+      },
+      join: (payload) => {
+        if (self.joinedRooms.has(roomId)) return {};
+        const result = self.ctx.roomManager.joinRoom(
+          self.componentId,
+          roomId,
+          self.ws,
+          void 0,
+          void 0,
+          { userId: void 0, payload }
+        );
+        if ("rejected" in result && result.rejected) {
+          return result;
+        }
+        self.joinedRooms.add(roomId);
+        self._roomsCache = null;
+        sendImmediate(self.ws, JSON.stringify({
+          type: "ROOM_JOINED",
+          componentId: self.componentId,
+          roomId,
+          event: "$room:joined",
+          data: { state: result.state },
+          timestamp: Date.now()
+        }));
+        return {};
+      },
+      leave: () => {
+        if (!self.joinedRooms.has(roomId)) return;
+        self.joinedRooms.delete(roomId);
+        self._roomsCache = null;
+        self.ctx.roomManager.leaveRoom(self.componentId, roomId, "leave");
+      },
+      emit: ((event, data) => {
+        return self.ctx.roomManager.emitToRoom(roomId, event, data, self.componentId);
+      }),
+      on: (event, handler) => {
+        const unsubscribe = self.ctx.roomEvents.on(
+          "room",
+          roomId,
+          event,
+          self.componentId,
+          handler
+        );
+        self.roomEventUnsubscribers.push(unsubscribe);
+        return unsubscribe;
+      },
+      setState: (updates) => {
+        self.ctx.roomManager.setRoomState(roomId, updates, self.componentId);
+      }
+    };
+    const proxied = new Proxy(handle, {
+      get(obj, prop, receiver) {
+        if (TYPED_RESERVED_KEYS.has(prop) || typeof prop === "symbol") {
+          return Reflect.get(obj, prop, receiver);
+        }
+        if (prop in obj) return Reflect.get(obj, prop, receiver);
+        const instance = self.ctx.roomManager.getRoomInstance?.(roomId);
+        if (instance && prop in instance) {
+          const val = instance[prop];
+          return typeof val === "function" ? val.bind(instance) : val;
+        }
+        return void 0;
+      }
+    });
+    this.roomHandles.set(roomId, proxied);
+    return proxied;
   }
   get $rooms() {
     if (this._roomsCache) return this._roomsCache;
@@ -2500,7 +2909,6 @@ var ComponentRoomProxy = class {
     const excludeId = notifySelf ? void 0 : this.componentId;
     const notified = this.ctx.roomEvents.emit(this.roomType, this.room, event, data, excludeId);
     liveLog("rooms", this.componentId, `[${this.componentId}] Room event '${event}' -> ${notified} components`);
-    this._debugger?.trackRoomEmit(this.componentId, this.room, event, data);
     return notified;
   }
   onRoomEvent(event, handler) {
@@ -2546,10 +2954,6 @@ var ComponentRoomProxy = class {
 };
 
 // src/component/LiveComponent.ts
-var _liveDebugger = null;
-function _setLiveDebugger(dbg) {
-  _liveDebugger = dbg;
-}
 var LiveComponent = class {
   /** Component name for registry lookup - must be defined in subclasses */
   static componentName;
@@ -2599,6 +3003,13 @@ var LiveComponent = class {
    * All clients share the same state.
    */
   static singleton;
+  /**
+   * Component behavior options.
+   *
+   * @example
+   * static $options = { deepDiff: true }
+   */
+  static $options;
   id;
   state;
   // Proxy wrapper (getter delegates to _stateManager)
@@ -2642,7 +3053,8 @@ var LiveComponent = class {
       ws: this.ws,
       emitFn: (type, payload) => this._messaging.emit(type, payload),
       onStateChangeFn: (changes) => this.onStateChange(changes),
-      debugger: _liveDebugger
+      deepDiff: ctor.$options?.deepDiff ?? false,
+      deepDiffDepth: ctor.$options?.deepDiffDepth
     });
     this.state = this._stateManager.proxyState;
     this._actionSecurity = new ActionSecurityManager();
@@ -2651,8 +3063,10 @@ var LiveComponent = class {
       ws: this.ws,
       defaultRoom: this.room,
       getCtx: () => getLiveComponentContext(),
-      debugger: _liveDebugger,
-      setStateFn: (updates) => this.setState(updates)
+      setStateFn: (updates) => this.setState(updates),
+      deepDiff: ctor.$options?.roomDeepDiff,
+      deepDiffDepth: ctor.$options?.deepDiffDepth,
+      serverOnlyState: ctor.$options?.serverOnlyRoomState
     });
     this._stateManager.applyDirectAccessors(this, this.constructor);
   }
@@ -2665,6 +3079,14 @@ var LiveComponent = class {
   // ========================================
   // $room - Unified Room System
   // ========================================
+  /**
+   * Unified room accessor.
+   *
+   * Usage:
+   * - `this.$room` — default room handle (legacy)
+   * - `this.$room('roomId')` — untyped room handle (legacy)
+   * - `this.$room(ChatRoom, 'lobby')` — typed handle with custom methods
+   */
   get $room() {
     return this._roomProxyManager.$room;
   }
@@ -2746,8 +3168,8 @@ var LiveComponent = class {
    * as a binary frame: [0x01][idLen:u8][id_bytes:utf8][payload_bytes].
    * Bypasses the JSON batcher — ideal for high-frequency updates.
    */
-  sendBinaryDelta(delta, encoder) {
-    this._stateManager.sendBinaryDelta(delta, encoder);
+  sendBinaryDelta(delta, encoder2) {
+    this._stateManager.sendBinaryDelta(delta, encoder2);
   }
   setValue(payload) {
     return this._stateManager.setValue(payload);
@@ -2760,8 +3182,7 @@ var LiveComponent = class {
       component: this,
       componentClass: this.constructor,
       componentId: this.id,
-      emitFn: (type, p) => this.emit(type, p),
-      debugger: _liveDebugger
+      emitFn: (type, p) => this.emit(type, p)
     });
   }
   // ========================================
@@ -2828,16 +3249,13 @@ var ComponentRegistry = class {
   remoteSingletons = /* @__PURE__ */ new Map();
   cluster;
   authManager;
-  debugger;
   stateSignature;
   performanceMonitor;
   constructor(deps) {
     this.authManager = deps.authManager;
-    this.debugger = deps.debugger;
     this.stateSignature = deps.stateSignature;
     this.performanceMonitor = deps.performanceMonitor;
     this.cluster = deps.cluster;
-    _setLiveDebugger(deps.debugger);
     this.setupHealthMonitoring();
     this.setupClusterHandlers();
   }
@@ -3142,13 +3560,6 @@ var ComponentRegistry = class {
         ;
         component.emit("ERROR", { action: "onMount", error: `Mount initialization failed: ${err?.message || err}` });
       }
-      this.debugger.trackComponentMount(
-        component.id,
-        componentName,
-        component.getSerializableState(),
-        options?.room,
-        options?.debugLabel
-      );
       return { componentId: component.id, initialState: component.getSerializableState(), signedState };
     } catch (error) {
       console.error(`Failed to mount component ${componentName}:`, error);
@@ -3291,7 +3702,6 @@ var ComponentRegistry = class {
     } else {
       if (this.removeSingletonConnection(componentId, void 0, "unmount")) return;
     }
-    this.debugger.trackComponentUnmount(componentId);
     component.destroy?.();
     this.unsubscribeFromAllRooms(componentId);
     this.components.delete(componentId);
@@ -3638,12 +4048,146 @@ function sanitizePayload(value, depth = 0) {
   return value;
 }
 
+// src/rooms/LiveRoom.ts
+var LiveRoom = class {
+  /** Unique room type name. Used as prefix in compound room IDs (e.g. "chat:lobby"). */
+  static roomName;
+  /** Initial public state template. Cloned per room instance. */
+  static defaultState = {};
+  /** Initial private metadata template. Cloned per room instance. */
+  static defaultMeta = {};
+  /** Room-level options */
+  static $options;
+  /** The unique room instance identifier (e.g. "chat:lobby") */
+  id;
+  /** Public state — synced to all connected clients via setState(). */
+  state;
+  /** Private metadata — NEVER leaves the server. Mutate directly. */
+  meta;
+  /** @internal Reference to the room manager for broadcasting */
+  _manager;
+  constructor(id, manager) {
+    const ctor = this.constructor;
+    this.id = id;
+    this._manager = manager;
+    this.state = structuredClone(ctor.defaultState ?? {});
+    this.meta = structuredClone(ctor.defaultMeta ?? {});
+  }
+  // ===== Framework Methods =====
+  /**
+   * Update public state and broadcast changes to all room members.
+   * Uses deep diff by default — only changed fields are sent over the wire.
+   */
+  setState(updates) {
+    this._manager.setRoomState(this.id, updates);
+  }
+  /**
+   * Emit a typed event to all members in this room.
+   * @returns Number of members notified
+   */
+  emit(event, data) {
+    return this._manager.emitToRoom(this.id, event, data);
+  }
+  /** Get current member count */
+  get memberCount() {
+    return this._manager.getMemberCount?.(this.id) ?? 0;
+  }
+  // ===== Lifecycle Hooks (override in subclass) =====
+  /**
+   * Called when a component attempts to join this room.
+   * Return false to reject the join.
+   */
+  onJoin(_ctx2) {
+  }
+  /**
+   * Called after a component leaves this room.
+   */
+  onLeave(_ctx2) {
+  }
+  /**
+   * Called when an event is emitted to this room.
+   * Can intercept/validate events before broadcasting.
+   */
+  onEvent(_event, _data, _ctx2) {
+  }
+  /**
+   * Called once when the room is first created (first member joins).
+   */
+  onCreate() {
+  }
+  /**
+   * Called when the last member leaves and the room is about to be destroyed.
+   * Return false to keep the room alive (e.g., persist state).
+   */
+  onDestroy() {
+  }
+};
+
+// src/rooms/RoomRegistry.ts
+var RoomRegistry = class {
+  rooms = /* @__PURE__ */ new Map();
+  /**
+   * Register a LiveRoom subclass.
+   * @throws If the class doesn't define a static roomName
+   */
+  register(roomClass) {
+    const name = roomClass.roomName;
+    if (!name) {
+      throw new Error("LiveRoom subclass must define static roomName");
+    }
+    if (this.rooms.has(name)) {
+      throw new Error(`LiveRoom '${name}' is already registered`);
+    }
+    this.rooms.set(name, roomClass);
+  }
+  /**
+   * Get a registered room class by name.
+   */
+  get(name) {
+    return this.rooms.get(name);
+  }
+  /**
+   * Check if a room class is registered.
+   */
+  has(name) {
+    return this.rooms.has(name);
+  }
+  /**
+   * Resolve a compound room ID (e.g. "chat:lobby") to its registered class.
+   * Returns undefined if the prefix doesn't match any registered room.
+   */
+  resolveFromId(roomId) {
+    const colonIdx = roomId.indexOf(":");
+    if (colonIdx === -1) return void 0;
+    const prefix = roomId.substring(0, colonIdx);
+    return this.rooms.get(prefix);
+  }
+  /**
+   * Get all registered room names.
+   */
+  getRegisteredNames() {
+    return Array.from(this.rooms.keys());
+  }
+  /**
+   * Check if a value is a LiveRoom subclass.
+   */
+  static isLiveRoomClass(cls) {
+    if (typeof cls !== "function" || !cls.prototype) return false;
+    if (typeof cls.roomName !== "string") return false;
+    let proto = Object.getPrototypeOf(cls.prototype);
+    while (proto) {
+      if (proto.constructor === LiveRoom) return true;
+      proto = Object.getPrototypeOf(proto);
+    }
+    return false;
+  }
+};
+
 // src/server/LiveServer.ts
 var LiveServer = class {
   // Public singletons (accessible for transport adapters & advanced usage)
   roomEvents;
   roomManager;
-  debugger;
   authManager;
   stateSignature;
   performanceMonitor;
@@ -3651,6 +4195,7 @@ var LiveServer = class {
   connectionManager;
   registry;
   rateLimiter;
+  roomRegistry;
   transport;
   options;
   constructor(options) {
@@ -3658,25 +4203,28 @@ var LiveServer = class {
     this.transport = options.transport;
     this.roomEvents = new RoomEventBus();
     this.roomManager = new LiveRoomManager(this.roomEvents, options.roomPubSub);
-    this.debugger = new LiveDebugger(options.debug ?? false);
     this.authManager = new LiveAuthManager();
     this.stateSignature = new StateSignatureManager(options.stateSignature);
     this.performanceMonitor = new PerformanceMonitor(options.performance);
     this.fileUploadManager = new FileUploadManager(options.fileUpload);
     this.connectionManager = new WebSocketConnectionManager(options.connection);
     this.rateLimiter = new RateLimiterRegistry(options.rateLimitMaxTokens, options.rateLimitRefillRate);
+    this.roomRegistry = new RoomRegistry();
+    this.roomManager.roomRegistry = this.roomRegistry;
+    if (options.rooms) {
+      for (const roomClass of options.rooms) {
+        this.roomRegistry.register(roomClass);
+      }
+    }
     this.registry = new ComponentRegistry({
       authManager: this.authManager,
-      debugger: this.debugger,
       stateSignature: this.stateSignature,
       performanceMonitor: this.performanceMonitor,
       cluster: options.cluster
     });
-    _setLoggerDebugger(this.debugger);
     setLiveComponentContext({
       roomEvents: this.roomEvents,
-      roomManager: this.roomManager,
-      debugger: this.debugger
+      roomManager: this.roomManager
     });
   }
   /**
@@ -3686,6 +4234,14 @@ var LiveServer = class {
     this.authManager.register(provider);
     return this;
   }
+  /**
+   * Register a LiveRoom class.
+   * Can be called before start() to register room types dynamically.
+   */
+  useRoom(roomClass) {
+    this.roomRegistry.register(roomClass);
+    return this;
+  }
   /**
    * Start the LiveServer: register WS + HTTP handlers on the transport.
    */
@@ -3745,7 +4301,6 @@ var LiveServer = class {
       origin
     };
     this.connectionManager.registerConnection(ws, connectionId);
-    this.debugger.trackConnection(connectionId);
     sendImmediate(ws, JSON.stringify({
       type: "CONNECTION_ESTABLISHED",
       connectionId,
@@ -3803,7 +4358,7 @@ var LiveServer = class {
         return;
       }
       if (message.type === "ROOM_JOIN" || message.type === "ROOM_LEAVE" || message.type === "ROOM_EMIT" || message.type === "ROOM_STATE_SET" || message.type === "ROOM_STATE_GET") {
-        this.handleRoomMessage(ws, message);
+        await this.handleRoomMessage(ws, message);
         return;
       }
       if (message.type === "FILE_UPLOAD_START") {
@@ -3882,18 +4437,27 @@ var LiveServer = class {
       this.connectionManager.cleanupConnection(connectionId);
       this.rateLimiter.remove(connectionId);
     }
-    this.debugger.trackDisconnection(connectionId || "", componentCount);
     liveLog("websocket", null, `Connection closed: ${connectionId} (${componentCount} components)`);
   }
   handleError(ws, error) {
     console.error(`[LiveServer] WebSocket error:`, error.message);
   }
   // ===== Room Message Router =====
-  handleRoomMessage(ws, message) {
+  async handleRoomMessage(ws, message) {
     const { componentId } = message;
     const roomId = message.roomId || message.payload?.roomId;
     switch (message.type) {
       case "ROOM_JOIN": {
+        if (this.roomRegistry.resolveFromId(roomId)) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: "Room requires server-side join via component action",
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
         const connRooms = ws.data?.rooms;
         if (connRooms && connRooms.size >= MAX_ROOMS_PER_CONNECTION) {
           sendImmediate(ws, JSON.stringify({
@@ -3905,7 +4469,34 @@ var LiveServer = class {
           }));
           break;
         }
+        if (this.authManager.hasProviders()) {
+          const authContext = ws.data?.authContext;
+          const authResult = await this.authManager.authorizeRoom(
+            authContext || ANONYMOUS_CONTEXT,
+            roomId
+          );
+          if (!authResult.allowed) {
+            sendImmediate(ws, JSON.stringify({
+              type: "ERROR",
+              componentId,
+              error: authResult.reason || "Room access denied",
+              requestId: message.requestId,
+              timestamp: Date.now()
+            }));
+            break;
+          }
+        }
         const result = this.roomManager.joinRoom(componentId, roomId, ws, message.payload?.initialState);
+        if ("rejected" in result && result.rejected) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: result.reason,
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
         if (!ws.data.rooms) ws.data.rooms = /* @__PURE__ */ new Set();
         ws.data.rooms.add(roomId);
         sendImmediate(ws, JSON.stringify({
@@ -3928,13 +4519,55 @@ var LiveServer = class {
           timestamp: Date.now()
         }));
         break;
-      case "ROOM_EMIT":
+      case "ROOM_EMIT": {
+        if (!this.roomManager.isInRoom(componentId, roomId)) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: "Not a member of this room",
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
         this.roomManager.emitToRoom(roomId, message.payload?.event, message.payload?.data, componentId);
         break;
-      case "ROOM_STATE_SET":
+      }
+      case "ROOM_STATE_SET": {
+        if (!this.roomManager.isInRoom(componentId, roomId)) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: "Not a member of this room",
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
+        if (this.roomManager.isServerOnlyState(roomId)) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: "Room state is server-only",
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
         this.roomManager.setRoomState(roomId, message.payload?.state, componentId);
         break;
+      }
       case "ROOM_STATE_GET": {
+        if (!this.roomManager.isInRoom(componentId, roomId)) {
+          sendImmediate(ws, JSON.stringify({
+            type: "ERROR",
+            componentId,
+            error: "Not a member of this room",
+            requestId: message.requestId,
+            timestamp: Date.now()
+          }));
+          break;
+        }
         const state = this.roomManager.getRoomState(roomId);
         sendImmediate(ws, JSON.stringify({
           type: "ROOM_STATE",
@@ -4189,6 +4822,6 @@ var InMemoryRoomAdapter = class {
   }
 };
 
-export { ANONYMOUS_CONTEXT, AnonymousContext, AuthenticatedContext, ComponentRegistry, ConnectionRateLimiter, DEFAULT_CHUNK_SIZE, DEFAULT_WS_PATH, EMIT_OVERRIDE_KEY, FileUploadManager, InMemoryRoomAdapter, LiveAuthManager, LiveComponent, LiveDebugger, LiveRoomManager, LiveServer, PROTOCOL_VERSION, PerformanceMonitor, RateLimiterRegistry, RoomEventBus, RoomStateManager, StateSignatureManager, WebSocketConnectionManager, createTypedRoomEventBus, createTypedRoomState, decodeBinaryChunk, encodeBinaryChunk, getLiveComponentContext, liveLog, liveWarn, queueWsMessage, registerComponentLogging, sendImmediate, setLiveComponentContext, unregisterComponentLogging };
+export { ANONYMOUS_CONTEXT, AnonymousContext, AuthenticatedContext, BINARY_ROOM_EVENT, BINARY_ROOM_STATE, ComponentRegistry, ConnectionRateLimiter, DEFAULT_CHUNK_SIZE, DEFAULT_WS_PATH, EMIT_OVERRIDE_KEY, FileUploadManager, InMemoryRoomAdapter, LiveAuthManager, LiveComponent, LiveRoom, LiveRoomManager, LiveServer, PROTOCOL_VERSION, PerformanceMonitor, RateLimiterRegistry, RoomEventBus, RoomRegistry, RoomStateManager, StateSignatureManager, WebSocketConnectionManager, buildRoomFrame, buildRoomFrameTail, createTypedRoomEventBus, createTypedRoomState, decodeBinaryChunk, encodeBinaryChunk, getLiveComponentContext, jsonCodec, liveLog, liveWarn, msgpackCodec, parseRoomFrame, prependMemberHeader, queueWsMessage, registerComponentLogging, resolveCodec, sendBinaryImmediate, sendImmediate, setLiveComponentContext, unregisterComponentLogging };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map