@carverjs/multiplayer 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1743 @@
+import {
+  WebRTCTransport
+} from "./chunk-3KT73N2S.mjs";
+import {
+  FirebaseStrategy,
+  MqttStrategy
+} from "./chunk-UD6FDZMX.mjs";
+import {
+  EventSync,
+  PredictionSync,
+  SnapshotSync
+} from "./chunk-EO3YNPRQ.mjs";
+
+// src/components/MultiplayerProvider.ts
+import { createElement, useRef, useEffect } from "react";
+
+// src/core/TickKeeper.ts
+var _TickKeeper = class _TickKeeper {
+  constructor(tickRate = 60) {
+    this._accumulator = 0;
+    this._tick = 0;
+    this._serverTick = 0;
+    this._alpha = 0;
+    this._timeScale = 1;
+    this._tickRate = tickRate;
+    this._tickDelta = 1 / tickRate;
+  }
+  get tick() {
+    return this._tick;
+  }
+  get serverTick() {
+    return this._serverTick;
+  }
+  get tickDelta() {
+    return this._tickDelta;
+  }
+  get tickRate() {
+    return this._tickRate;
+  }
+  /** Interpolation alpha for rendering between ticks (0-1) */
+  get alpha() {
+    return this._alpha;
+  }
+  /** Current time scale (affected by drift correction) */
+  get timeScale() {
+    return this._timeScale;
+  }
+  /** Ticks ahead of server (positive = ahead, negative = behind) */
+  get drift() {
+    return this._tick - this._serverTick;
+  }
+  /** Update server tick from received snapshot */
+  setServerTick(serverTick) {
+    this._serverTick = serverTick;
+    this._updateDriftCorrection();
+  }
+  /**
+   * Accumulate time and return the number of fixed ticks to process.
+   * Call this once per render frame with the raw frame delta.
+   */
+  update(rawDelta) {
+    const maxDelta = this._tickDelta * 8;
+    const delta = Math.min(rawDelta, maxDelta) * this._timeScale;
+    this._accumulator += delta;
+    let ticksThisFrame = 0;
+    while (this._accumulator >= this._tickDelta) {
+      this._accumulator -= this._tickDelta;
+      this._tick++;
+      ticksThisFrame++;
+    }
+    this._alpha = this._accumulator / this._tickDelta;
+    return ticksThisFrame;
+  }
+  /** Reset to initial state */
+  reset() {
+    this._accumulator = 0;
+    this._tick = 0;
+    this._serverTick = 0;
+    this._alpha = 0;
+    this._timeScale = 1;
+  }
+  /** Set tick rate (updates tickDelta accordingly) */
+  setTickRate(rate) {
+    this._tickRate = rate;
+    this._tickDelta = 1 / rate;
+  }
+  _updateDriftCorrection() {
+    const drift = this.drift;
+    if (drift < _TickKeeper.DRIFT_BEHIND_THRESHOLD) {
+      this._timeScale = _TickKeeper.SPEED_UP_SCALE;
+    } else if (drift > _TickKeeper.DRIFT_AHEAD_THRESHOLD) {
+      this._timeScale = _TickKeeper.SLOW_DOWN_SCALE;
+    } else {
+      this._timeScale = _TickKeeper.NORMAL_SCALE;
+    }
+  }
+};
+// Drift correction zones
+_TickKeeper.DRIFT_BEHIND_THRESHOLD = -5;
+_TickKeeper.DRIFT_AHEAD_THRESHOLD = 5;
+_TickKeeper.SPEED_UP_SCALE = 1.5;
+_TickKeeper.SLOW_DOWN_SCALE = 0.1;
+_TickKeeper.NORMAL_SCALE = 1;
+var TickKeeper = _TickKeeper;
+
+// src/core/codec.ts
+import { pack, unpack } from "msgpackr";
+var DEFAULT_THRESHOLDS = {
+  position: 0.01,
+  rotation: 1e-3,
+  velocity: 0.05,
+  custom: "strict"
+};
+var SnapshotBuffer = class {
+  constructor(capacity = 120) {
+    this._capacity = capacity;
+    this._buffer = /* @__PURE__ */ new Map();
+  }
+  /** Store a snapshot at the given tick */
+  store(tick, entities) {
+    this._buffer.set(tick, entities);
+    if (this._buffer.size > this._capacity) {
+      const sortedTicks = Array.from(this._buffer.keys()).sort((a, b) => a - b);
+      const toRemove = sortedTicks.length - this._capacity;
+      for (let i = 0; i < toRemove; i++) {
+        this._buffer.delete(sortedTicks[i]);
+      }
+    }
+  }
+  /** Get a snapshot at the given tick */
+  get(tick) {
+    return this._buffer.get(tick);
+  }
+  /** Clear all stored snapshots */
+  clear() {
+    this._buffer.clear();
+  }
+};
+var Codec = class {
+  constructor(options) {
+    this._thresholds = { ...DEFAULT_THRESHOLDS, ...options?.thresholds };
+    this._quantize = options?.quantize;
+    this._is2D = options?.is2D ?? false;
+  }
+  /** Serialize entity states to binary (msgpackr) */
+  serialize(entities) {
+    const quantized = this._quantize ? entities.map((e) => this._quantizeEntity(e)) : entities;
+    return pack(quantized);
+  }
+  /** Deserialize binary to entity states */
+  deserialize(data) {
+    return unpack(data);
+  }
+  /**
+   * Compute delta: only include entities that changed beyond thresholds
+   * since the baseline snapshot.
+   * Returns null if nothing changed.
+   */
+  computeDelta(current, baseline) {
+    if (!baseline) {
+      return Array.from(current.values());
+    }
+    const changed = [];
+    for (const [id, entity] of current) {
+      const prev = baseline.get(id);
+      if (!prev || this._hasChanged(entity, prev)) {
+        changed.push(entity);
+      }
+    }
+    for (const id of baseline.keys()) {
+      if (!current.has(id)) {
+        if (this._is2D) {
+          changed.push({ id, x: 0, y: 0, a: 0, vx: 0, vy: 0, va: 0, c: { __removed: true } });
+        } else {
+          changed.push({ id, x: 0, y: 0, z: 0, qx: 0, qy: 0, qz: 0, qw: 1, vx: 0, vy: 0, vz: 0, wx: 0, wy: 0, wz: 0, c: { __removed: true } });
+        }
+      }
+    }
+    return changed.length > 0 ? changed : null;
+  }
+  /** Serialize a delta snapshot packet */
+  serializeDelta(tick, baseTick, current, baseline) {
+    const delta = this.computeDelta(current, baseline);
+    if (!delta) return null;
+    const packet = {
+      t: tick,
+      b: baseline ? baseTick : -1,
+      // -1 = keyframe
+      s: this.serialize(delta)
+    };
+    return pack(packet);
+  }
+  /** Deserialize a snapshot packet */
+  deserializePacket(data) {
+    const packet = unpack(data);
+    return {
+      tick: packet.t,
+      baseTick: packet.b,
+      entities: this.deserialize(packet.s)
+    };
+  }
+  _hasChanged(current, prev) {
+    const t = this._thresholds;
+    if (Math.abs(current.x - prev.x) > t.position) return true;
+    if (Math.abs(current.y - prev.y) > t.position) return true;
+    if ("z" in current && "z" in prev) {
+      const c = current;
+      const p = prev;
+      if (Math.abs(c.z - p.z) > t.position) return true;
+      if (Math.abs(c.qx - p.qx) > t.rotation) return true;
+      if (Math.abs(c.qy - p.qy) > t.rotation) return true;
+      if (Math.abs(c.qz - p.qz) > t.rotation) return true;
+      if (Math.abs(c.qw - p.qw) > t.rotation) return true;
+      if (Math.abs(c.vx - p.vx) > t.velocity) return true;
+      if (Math.abs(c.vy - p.vy) > t.velocity) return true;
+      if (Math.abs(c.vz - p.vz) > t.velocity) return true;
+      if (Math.abs(c.wx - p.wx) > t.velocity) return true;
+      if (Math.abs(c.wy - p.wy) > t.velocity) return true;
+      if (Math.abs(c.wz - p.wz) > t.velocity) return true;
+    } else {
+      const c = current;
+      const p = prev;
+      if (Math.abs(c.a - p.a) > t.rotation) return true;
+      if (Math.abs(c.vx - p.vx) > t.velocity) return true;
+      if (Math.abs(c.vy - p.vy) > t.velocity) return true;
+      if (Math.abs(c.va - p.va) > t.velocity) return true;
+    }
+    if (current.c || prev.c) {
+      const cc = current.c ?? {};
+      const pc = prev.c ?? {};
+      const allKeys = /* @__PURE__ */ new Set([...Object.keys(cc), ...Object.keys(pc)]);
+      for (const key of allKeys) {
+        if (t.custom === "strict") {
+          if (cc[key] !== pc[key]) return true;
+        } else {
+          const diff = typeof cc[key] === "number" && typeof pc[key] === "number" ? Math.abs(cc[key] - pc[key]) : cc[key] === pc[key] ? 0 : 1;
+          if (diff > t.custom) return true;
+        }
+      }
+    }
+    return false;
+  }
+  _quantizeEntity(entity) {
+    const q = this._quantize;
+    const result = { ...entity };
+    if (q.position !== void 0) {
+      const m = Math.pow(10, q.position);
+      result.x = Math.round(result.x * m) / m;
+      result.y = Math.round(result.y * m) / m;
+      if ("z" in result) {
+        result.z = Math.round(result.z * m) / m;
+      }
+    }
+    if (q.rotation !== void 0) {
+      const m = Math.pow(10, q.rotation);
+      if ("a" in result) {
+        result.a = Math.round(result.a * m) / m;
+      } else if ("qx" in result) {
+        const r = result;
+        r.qx = Math.round(r.qx * m) / m;
+        r.qy = Math.round(r.qy * m) / m;
+        r.qz = Math.round(r.qz * m) / m;
+        r.qw = Math.round(r.qw * m) / m;
+      }
+    }
+    if (q.velocity !== void 0) {
+      const m = Math.pow(10, q.velocity);
+      result.vx = Math.round(result.vx * m) / m;
+      result.vy = Math.round(result.vy * m) / m;
+      if ("vz" in result) {
+        const r = result;
+        r.vz = Math.round(r.vz * m) / m;
+        r.wx = Math.round(r.wx * m) / m;
+        r.wy = Math.round(r.wy * m) / m;
+        r.wz = Math.round(r.wz * m) / m;
+      }
+      if ("va" in result) {
+        result.va = Math.round(result.va * m) / m;
+      }
+    }
+    return result;
+  }
+};
+
+// src/core/NetworkManager.ts
+var NetworkManager = class {
+  constructor(options = {}) {
+    // Transport
+    this._transport = null;
+    this._connectionState = "disconnected";
+    // Room state
+    this._room = null;
+    this._players = /* @__PURE__ */ new Map();
+    // Sync state
+    this._syncMode = "snapshot";
+    this._networkQuality = "good";
+    // Change listeners
+    this._connectionListeners = [];
+    this._playerListeners = [];
+    this._roomListeners = [];
+    this._errorListeners = [];
+    this._options = options;
+    this._syncMode = options.mode ?? "snapshot";
+    this._tickKeeper = new TickKeeper(options.tickRate ?? 60);
+    this._codec = new Codec({
+      thresholds: options.deltaThresholds,
+      quantize: options.quantize
+    });
+    this._snapshotBuffer = new SnapshotBuffer();
+  }
+  // -- Getters --
+  get transport() {
+    return this._transport;
+  }
+  get connectionState() {
+    return this._connectionState;
+  }
+  get room() {
+    return this._room;
+  }
+  get players() {
+    return this._players;
+  }
+  get selfId() {
+    return this._transport?.peerId || null;
+  }
+  get isHost() {
+    return this._transport?.isHost ?? false;
+  }
+  get hostId() {
+    return this._transport?.hostId ?? null;
+  }
+  get syncMode() {
+    return this._syncMode;
+  }
+  get tickKeeper() {
+    return this._tickKeeper;
+  }
+  get codec() {
+    return this._codec;
+  }
+  get snapshotBuffer() {
+    return this._snapshotBuffer;
+  }
+  get networkQuality() {
+    return this._networkQuality;
+  }
+  get options() {
+    return this._options;
+  }
+  // -- Transport management --
+  setTransport(transport) {
+    this._transport = transport;
+    transport.onPeerJoin((peerId) => {
+      if (!this._players.has(peerId)) {
+        this._players.set(peerId, {
+          peerId,
+          displayName: `Player-${peerId.slice(0, 4)}`,
+          isHost: peerId === transport.hostId,
+          isSelf: false,
+          isReady: false,
+          isConnected: true,
+          metadata: {},
+          latencyMs: 0,
+          joinedAt: Date.now()
+        });
+      }
+      this._notifyPlayerListeners();
+    });
+    transport.onPeerUpdated((player) => {
+      this._players.set(player.peerId, {
+        ...player,
+        isSelf: player.peerId === this.selfId
+      });
+      this._notifyPlayerListeners();
+    });
+    transport.onPeerLeave((peerId) => {
+      this._players.delete(peerId);
+      this._notifyPlayerListeners();
+    });
+    transport.onHostChanged((_newHostId) => {
+      this._notifyRoomListeners();
+    });
+  }
+  // -- Connection state --
+  setConnectionState(state) {
+    this._connectionState = state;
+    for (const listener of this._connectionListeners) listener(state);
+  }
+  onConnectionStateChange(cb) {
+    this._connectionListeners.push(cb);
+    return () => {
+      const idx = this._connectionListeners.indexOf(cb);
+      if (idx >= 0) this._connectionListeners.splice(idx, 1);
+    };
+  }
+  // -- Room state --
+  setRoom(room) {
+    this._room = room;
+    this._notifyRoomListeners();
+  }
+  onRoomChange(cb) {
+    this._roomListeners.push(cb);
+    return () => {
+      const idx = this._roomListeners.indexOf(cb);
+      if (idx >= 0) this._roomListeners.splice(idx, 1);
+    };
+  }
+  // -- Players --
+  setPlayers(players) {
+    this._players.clear();
+    for (const p of players) {
+      this._players.set(p.peerId, p);
+    }
+    this._notifyPlayerListeners();
+  }
+  updatePlayer(player) {
+    this._players.set(player.peerId, player);
+    this._notifyPlayerListeners();
+  }
+  removePlayer(peerId) {
+    this._players.delete(peerId);
+    this._notifyPlayerListeners();
+  }
+  onPlayersChange(cb) {
+    this._playerListeners.push(cb);
+    return () => {
+      const idx = this._playerListeners.indexOf(cb);
+      if (idx >= 0) this._playerListeners.splice(idx, 1);
+    };
+  }
+  // -- Errors --
+  emitError(error) {
+    for (const listener of this._errorListeners) listener(error);
+  }
+  onError(cb) {
+    this._errorListeners.push(cb);
+    return () => {
+      const idx = this._errorListeners.indexOf(cb);
+      if (idx >= 0) this._errorListeners.splice(idx, 1);
+    };
+  }
+  // -- Network quality --
+  setNetworkQuality(quality) {
+    this._networkQuality = quality;
+  }
+  // -- Sync options --
+  updateOptions(options) {
+    this._options = options;
+    if (options.mode) this._syncMode = options.mode;
+    if (options.tickRate) this._tickKeeper.setTickRate(options.tickRate);
+    if (options.deltaThresholds || options.quantize) {
+      this._codec = new Codec({
+        thresholds: options.deltaThresholds,
+        quantize: options.quantize
+      });
+    }
+  }
+  // -- Cleanup --
+  destroy() {
+    this._transport?.disconnect();
+    this._transport = null;
+    this._connectionState = "disconnected";
+    this._room = null;
+    this._players.clear();
+    this._tickKeeper.reset();
+    this._snapshotBuffer.clear();
+    this._connectionListeners = [];
+    this._playerListeners = [];
+    this._roomListeners = [];
+    this._errorListeners = [];
+  }
+  // -- Private --
+  _notifyPlayerListeners() {
+    for (const listener of this._playerListeners) listener();
+  }
+  _notifyRoomListeners() {
+    for (const listener of this._roomListeners) listener();
+  }
+};
+
+// src/core/MultiplayerContext.ts
+import { createContext, useContext } from "react";
+var MultiplayerContext = createContext(null);
+function useMultiplayerContext() {
+  const ctx = useContext(MultiplayerContext);
+  if (!ctx) {
+    throw new Error("useMultiplayerContext must be used inside a <MultiplayerProvider>.");
+  }
+  return ctx;
+}
+
+// src/components/MultiplayerProvider.ts
+function createStrategy(appId, config) {
+  if (!config || config.type === "mqtt") {
+    return new MqttStrategy(appId, config ?? { type: "mqtt" });
+  }
+  if (config.type === "firebase") {
+    return new FirebaseStrategy(appId, config);
+  }
+  throw new Error(`Unknown strategy type: ${config.type}`);
+}
+function MultiplayerProvider({
+  appId,
+  strategy: strategyConfig,
+  iceServers,
+  children
+}) {
+  const managerRef = useRef(null);
+  const strategyRef = useRef(null);
+  if (!managerRef.current) {
+    managerRef.current = new NetworkManager();
+  }
+  if (!strategyRef.current) {
+    strategyRef.current = createStrategy(appId, strategyConfig);
+  }
+  useEffect(() => {
+    return () => {
+      strategyRef.current?.destroy();
+      strategyRef.current = null;
+      managerRef.current?.destroy();
+      managerRef.current = null;
+    };
+  }, []);
+  const value = {
+    appId,
+    strategy: strategyRef.current,
+    iceServers,
+    networkManager: managerRef.current
+  };
+  return createElement(MultiplayerContext.Provider, { value }, children);
+}
+
+// src/components/MultiplayerBridge.ts
+import { createElement as createElement2, useContext as useContext2 } from "react";
+function MultiplayerBridge({ children }) {
+  const ctx = useContext2(MultiplayerContext);
+  if (!ctx) return createElement2("group", null, children);
+  return createElement2(MultiplayerContext.Provider, { value: ctx }, children);
+}
+
+// src/hooks/useRoom.ts
+import { useState, useEffect as useEffect2, useCallback, useRef as useRef2 } from "react";
+function useRoom(roomId, options) {
+  const { strategy, iceServers, networkManager } = useMultiplayerContext();
+  const [connectionState, setConnectionState] = useState("disconnected");
+  const [isHost, setIsHost] = useState(false);
+  const [hostId, setHostId] = useState(null);
+  const [selfId, setSelfId] = useState(null);
+  const [currentRoomId, setCurrentRoomId] = useState(null);
+  const [error, setError] = useState(null);
+  const [transport, setTransport] = useState(null);
+  const [room, setRoom] = useState(null);
+  const reconnectAttemptsRef = useRef2(0);
+  const maxReconnectAttempts = options?.reconnectAttempts ?? 3;
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
+  const createTransport = useCallback(() => {
+    const opt = optionsRef.current;
+    if (opt?.transport && typeof opt.transport === "object" && "connect" in opt.transport) {
+      return opt.transport;
+    }
+    const servers = opt?.iceServers ?? iceServers;
+    const policy = opt?.privacy === "relay" ? "relay" : "all";
+    return new WebRTCTransport(strategy, servers, policy);
+  }, [strategy, iceServers]);
+  const transportRef = useRef2(null);
+  const doJoin = useCallback(async (targetRoomId, joinOptions) => {
+    if (transportRef.current) {
+      transportRef.current.disconnect();
+      transportRef.current = null;
+    }
+    const t = createTransport();
+    transportRef.current = t;
+    try {
+      setError(null);
+      setConnectionState("connecting");
+      networkManager.setConnectionState("connecting");
+      setTransport(t);
+      networkManager.setTransport(t);
+      t.onPeerJoin(() => {
+      });
+      t.onPeerLeave(() => {
+      });
+      t.onHostChanged((newHostId) => {
+        setHostId(newHostId);
+        setIsHost(t.peerId === newHostId);
+        optionsRef.current?.onHostMigration?.(newHostId);
+      });
+      if ("onRoomUpdated" in t && typeof t.onRoomUpdated === "function") {
+        t.onRoomUpdated((updatedRoom) => {
+          networkManager.setRoom(updatedRoom);
+        });
+      }
+      await t.connect(targetRoomId, {
+        displayName: optionsRef.current?.displayName,
+        playerMetadata: optionsRef.current?.playerMetadata,
+        password: joinOptions?.password ?? optionsRef.current?.password,
+        iceServers: optionsRef.current?.iceServers,
+        iceTransportPolicy: optionsRef.current?.privacy === "relay" ? "relay" : "all"
+      });
+      if (transportRef.current !== t) return;
+      setCurrentRoomId(targetRoomId);
+      setSelfId(t.peerId);
+      setHostId(t.hostId);
+      setIsHost(t.isHost);
+      setConnectionState("connected");
+      networkManager.setConnectionState("connected");
+      if (t.room) {
+        networkManager.setRoom(t.room);
+      }
+      if (t.initialPlayers) {
+        const players = t.initialPlayers.map((p) => ({
+          ...p,
+          isSelf: p.peerId === t.peerId
+        }));
+        networkManager.setPlayers(players);
+      }
+      reconnectAttemptsRef.current = 0;
+      optionsRef.current?.onConnected?.();
+    } catch (err) {
+      if (transportRef.current !== t) return;
+      const carverError = {
+        code: "CONNECTION_FAILED",
+        message: err instanceof Error ? err.message : "Connection failed",
+        recoverable: reconnectAttemptsRef.current < maxReconnectAttempts
+      };
+      setError(carverError);
+      networkManager.emitError(carverError);
+      setConnectionState("disconnected");
+      networkManager.setConnectionState("disconnected");
+      optionsRef.current?.onError?.(carverError);
+    }
+  }, [createTransport, networkManager, maxReconnectAttempts]);
+  const leave = useCallback(() => {
+    if (transportRef.current) {
+      transportRef.current.disconnect();
+      transportRef.current = null;
+    }
+    setTransport(null);
+    setConnectionState("disconnected");
+    setCurrentRoomId(null);
+    setSelfId(null);
+    setHostId(null);
+    setIsHost(false);
+    setError(null);
+    networkManager.setConnectionState("disconnected");
+    optionsRef.current?.onDisconnected?.("user_left");
+  }, [networkManager]);
+  const setReady = useCallback((ready) => {
+    transport?.setReady?.(ready);
+    const selfPlayer = networkManager.players.get(transport?.peerId ?? "");
+    if (selfPlayer) {
+      networkManager.updatePlayer({ ...selfPlayer, isReady: ready });
+    }
+  }, [transport, networkManager]);
+  const setMetadata = useCallback((meta) => {
+    transport?.setMetadata?.(meta);
+  }, [transport]);
+  const setRoomMetadata = useCallback((meta) => {
+    transport?.setRoomMetadata?.(meta);
+  }, [transport]);
+  useEffect2(() => {
+    if (roomId) {
+      doJoin(roomId);
+    }
+    return () => {
+      if (transportRef.current) {
+        transportRef.current.disconnect();
+        transportRef.current = null;
+      }
+    };
+  }, [roomId, doJoin]);
+  useEffect2(() => {
+    const unsub = networkManager.onRoomChange(() => {
+      setRoom(networkManager.room);
+    });
+    setRoom(networkManager.room);
+    return unsub;
+  }, [networkManager]);
+  return {
+    roomId: currentRoomId,
+    connectionState,
+    isHost,
+    hostId,
+    selfId,
+    room,
+    error,
+    join: doJoin,
+    leave,
+    setReady,
+    setMetadata,
+    setRoomMetadata,
+    transport
+  };
+}
+
+// src/hooks/useLobby.ts
+import { useState as useState2, useEffect as useEffect3, useCallback as useCallback2, useRef as useRef3 } from "react";
+function announcementToRoom(ann) {
+  return {
+    id: ann.roomId,
+    name: ann.name,
+    hostId: ann.hostId,
+    playerCount: ann.playerCount,
+    maxPlayers: ann.maxPlayers,
+    gameMode: ann.gameMode,
+    isPrivate: ann.isPrivate,
+    metadata: ann.metadata,
+    createdAt: ann.createdAt,
+    state: "lobby"
+  };
+}
+function useLobby(options) {
+  const { strategy } = useMultiplayerContext();
+  const [rooms, setRooms] = useState2([]);
+  const [isLoading, setIsLoading] = useState2(true);
+  const [error, setError] = useState2(null);
+  const optionsRef = useRef3(options);
+  optionsRef.current = options;
+  const filterRooms = useCallback2((roomList) => {
+    const filter = optionsRef.current?.filter;
+    if (!filter) return roomList;
+    return roomList.filter((room) => {
+      if (filter.maxPlayers !== void 0 && room.maxPlayers > filter.maxPlayers) return false;
+      if (filter.gameMode !== void 0 && room.gameMode !== filter.gameMode) return false;
+      if (filter.hasPassword !== void 0 && room.isPrivate !== filter.hasPassword) return false;
+      return true;
+    });
+  }, []);
+  useEffect3(() => {
+    setIsLoading(true);
+    setError(null);
+    const unsub = strategy.subscribeToLobby((announcements) => {
+      const converted = announcements.map(announcementToRoom);
+      setRooms(filterRooms(converted));
+      setIsLoading(false);
+    });
+    const timeout = setTimeout(() => setIsLoading(false), 3e3);
+    return () => {
+      unsub();
+      clearTimeout(timeout);
+    };
+  }, [strategy, filterRooms]);
+  const refresh = useCallback2(() => {
+    setIsLoading(true);
+    setTimeout(() => setIsLoading(false), 1e3);
+  }, []);
+  const createRoom = useCallback2(async (config) => {
+    const roomId = `${config.name.toLowerCase().replace(/\s+/g, "-")}-${Date.now().toString(36)}`;
+    const announcement = {
+      roomId,
+      name: config.name,
+      hostId: strategy.selfId,
+      playerCount: 0,
+      maxPlayers: config.maxPlayers ?? 8,
+      gameMode: config.metadata?.gameMode,
+      isPrivate: config.isPrivate ?? false,
+      metadata: config.metadata ?? {},
+      createdAt: Date.now(),
+      lastSeen: Date.now()
+    };
+    strategy.announceRoom(announcement);
+    return roomId;
+  }, [strategy]);
+  return {
+    rooms,
+    isLoading,
+    error,
+    refresh,
+    createRoom
+  };
+}
+
+// src/hooks/usePlayers.ts
+import { useState as useState3, useEffect as useEffect4, useCallback as useCallback3 } from "react";
+function usePlayers() {
+  const { networkManager } = useMultiplayerContext();
+  const [players, setPlayers] = useState3([]);
+  const [, setVersion] = useState3(0);
+  useEffect4(() => {
+    const unsubscribe = networkManager.onPlayersChange(() => {
+      setPlayers(Array.from(networkManager.players.values()));
+      setVersion((v) => v + 1);
+    });
+    setPlayers(Array.from(networkManager.players.values()));
+    return unsubscribe;
+  }, [networkManager]);
+  const self = players.find((p) => p.isSelf) ?? null;
+  const host = players.find((p) => p.isHost) ?? null;
+  const allReady = players.length > 0 && players.every((p) => p.isReady);
+  const getPlayer = useCallback3(
+    (peerId) => players.find((p) => p.peerId === peerId),
+    [players]
+  );
+  return {
+    players,
+    self,
+    host,
+    count: players.length,
+    allReady,
+    getPlayer
+  };
+}
+
+// src/hooks/useHost.ts
+import { useCallback as useCallback4 } from "react";
+function useHost() {
+  const { networkManager } = useMultiplayerContext();
+  const getTransport = useCallback4(() => {
+    const transport = networkManager.transport;
+    if (!transport || !networkManager.isHost) return null;
+    return transport;
+  }, [networkManager]);
+  const kick = useCallback4((peerId, reason) => {
+    getTransport()?.kick?.(peerId, reason);
+  }, [getTransport]);
+  const transferHost = useCallback4((peerId) => {
+    getTransport()?.transferHost?.(peerId);
+  }, [getTransport]);
+  const setRoomState = useCallback4((state) => {
+    getTransport()?.setRoomState?.(state);
+  }, [getTransport]);
+  const setMaxPlayers = useCallback4((n) => {
+    getTransport()?.setMaxPlayers?.(n);
+  }, [getTransport]);
+  const lockRoom = useCallback4(() => {
+    getTransport()?.lockRoom?.();
+  }, [getTransport]);
+  const unlockRoom = useCallback4(() => {
+    getTransport()?.unlockRoom?.();
+  }, [getTransport]);
+  return {
+    kick,
+    transferHost,
+    setRoomState,
+    setMaxPlayers,
+    lockRoom,
+    unlockRoom
+  };
+}
+
+// src/hooks/useMultiplayer.ts
+import { useEffect as useEffect5, useRef as useRef4, useState as useState4, useCallback as useCallback5 } from "react";
+import { useFrame } from "@react-three/fiber";
+import { getActorRegistry } from "@carverjs/core/systems";
+
+// src/core/NetworkSimulator.ts
+var NetworkSimulator = class {
+  constructor(options) {
+    this.sentCount = 0;
+    this.droppedCount = 0;
+    this.latencySum = 0;
+    // running sum of applied latencies
+    /** Active timeout handles so we can cancel them on destroy() */
+    this.pending = /* @__PURE__ */ new Set();
+    const opts = options ?? {};
+    this.latencyMs = opts.latencyMs ?? 0;
+    this.packetLoss = opts.packetLoss ?? 0;
+    this.jitterMs = opts.jitterMs ?? 0;
+  }
+  /* ---- public API ---- */
+  /** Update simulation parameters at runtime. */
+  setOptions(options) {
+    if (options.latencyMs !== void 0) this.latencyMs = options.latencyMs;
+    if (options.packetLoss !== void 0) this.packetLoss = options.packetLoss;
+    if (options.jitterMs !== void 0) this.jitterMs = options.jitterMs;
+  }
+  /**
+   * Wrap an existing send function so that every call goes through the
+   * simulated network conditions (latency, jitter, packet loss).
+   */
+  wrapSend(originalSend) {
+    return (data, target) => {
+      if (Math.random() < this.packetLoss) {
+        this.droppedCount++;
+        return;
+      }
+      this.sentCount++;
+      const jitter = this.jitterMs > 0 ? Math.random() * 2 * this.jitterMs - this.jitterMs : 0;
+      const delay = Math.max(0, this.latencyMs + jitter);
+      this.latencySum += delay;
+      if (delay === 0) {
+        originalSend(data, target);
+      } else {
+        const handle = setTimeout(() => {
+          this.pending.delete(handle);
+          originalSend(data, target);
+        }, delay);
+        this.pending.add(handle);
+      }
+    };
+  }
+  /** Current statistics snapshot. */
+  get stats() {
+    return {
+      sentCount: this.sentCount,
+      droppedCount: this.droppedCount,
+      avgLatencyMs: this.sentCount > 0 ? this.latencySum / this.sentCount : 0
+    };
+  }
+  /** Cancel all pending delayed sends and clean up. */
+  destroy() {
+    for (const handle of this.pending) {
+      clearTimeout(handle);
+    }
+    this.pending.clear();
+  }
+};
+
+// src/hooks/useMultiplayer.ts
+var Z_THRESHOLD = 0.01;
+function detect2D(actors) {
+  for (const [, ref] of actors) {
+    if (Math.abs(ref.object3D.position.z) > Z_THRESHOLD) return false;
+  }
+  return true;
+}
+function readEntityState2D(ref) {
+  const pos = ref.object3D.position;
+  const rot = ref.object3D.rotation;
+  const rb = ref.rigidBody;
+  let vx = 0;
+  let vy = 0;
+  let va = 0;
+  if (rb) {
+    try {
+      const lv = rb.linvel();
+      vx = lv.x;
+      vy = lv.y;
+    } catch {
+    }
+    try {
+      const av = rb.angvel();
+      va = typeof av === "number" ? av : av?.z ?? 0;
+    } catch {
+    }
+  }
+  const nc = ref.userData.networked;
+  const custom = nc?.custom;
+  return {
+    id: ref.id,
+    x: pos.x,
+    y: pos.y,
+    a: rot.z,
+    vx,
+    vy,
+    va,
+    ...custom ? { c: custom } : {}
+  };
+}
+function readEntityState3D(ref) {
+  const pos = ref.object3D.position;
+  const quat = ref.object3D.quaternion;
+  const rb = ref.rigidBody;
+  let vx = 0;
+  let vy = 0;
+  let vz = 0;
+  let wx = 0;
+  let wy = 0;
+  let wz = 0;
+  if (rb) {
+    try {
+      const lv = rb.linvel();
+      vx = lv.x;
+      vy = lv.y;
+      vz = lv.z ?? 0;
+    } catch {
+    }
+    try {
+      const av = rb.angvel();
+      wx = av.x ?? 0;
+      wy = av.y ?? 0;
+      wz = av.z ?? 0;
+    } catch {
+    }
+  }
+  const nc = ref.userData.networked;
+  const custom = nc?.custom;
+  return {
+    id: ref.id,
+    x: pos.x,
+    y: pos.y,
+    z: pos.z,
+    qx: quat.x,
+    qy: quat.y,
+    qz: quat.z,
+    qw: quat.w,
+    vx,
+    vy,
+    vz,
+    wx,
+    wy,
+    wz,
+    ...custom ? { c: custom } : {}
+  };
+}
+function buildEntityMap(actors, is2D) {
+  const entities = /* @__PURE__ */ new Map();
+  for (const [id, ref] of actors) {
+    const nc = ref.userData.networked;
+    if (nc && nc.sync === false) continue;
+    entities.set(id, is2D ? readEntityState2D(ref) : readEntityState3D(ref));
+  }
+  return entities;
+}
+function applyState2D(ref, state) {
+  ref.object3D.position.set(state.x, state.y, 0);
+  ref.object3D.rotation.z = state.a;
+  if (ref.rigidBody) {
+    try {
+      if (typeof ref.rigidBody.setTranslation === "function") {
+        ref.rigidBody.setTranslation({ x: state.x, y: state.y }, true);
+      }
+      if (typeof ref.rigidBody.setRotation === "function") {
+        ref.rigidBody.setRotation(state.a, true);
+      }
+    } catch {
+    }
+  }
+}
+function applyState3D(ref, state) {
+  ref.object3D.position.set(state.x, state.y, state.z);
+  ref.object3D.quaternion.set(state.qx, state.qy, state.qz, state.qw);
+  if (ref.rigidBody) {
+    try {
+      if (typeof ref.rigidBody.setTranslation === "function") {
+        ref.rigidBody.setTranslation({ x: state.x, y: state.y, z: state.z }, true);
+      }
+      if (typeof ref.rigidBody.setRotation === "function") {
+        ref.rigidBody.setRotation(
+          { x: state.qx, y: state.qy, z: state.qz, w: state.qw },
+          true
+        );
+      }
+    } catch {
+    }
+  }
+}
+function applyEntityState(ref, state, is2D) {
+  if (is2D) {
+    applyState2D(ref, state);
+  } else {
+    applyState3D(ref, state);
+  }
+}
+function applyStatesToActors(states, registry, is2D) {
+  for (const [id, state] of states) {
+    if (state.c && state.c.__removed) continue;
+    const ref = registry.get(id);
+    if (!ref) continue;
+    applyEntityState(ref, state, is2D);
+  }
+}
+function useMultiplayer(options = {}) {
+  const { networkManager } = useMultiplayerContext();
+  const mode = options.mode ?? networkManager.syncMode;
+  const eventSyncRef = useRef4(null);
+  const snapshotSyncRef = useRef4(null);
+  const predictionSyncRef = useRef4(null);
+  const networkSimulatorRef = useRef4(null);
+  const is2DRef = useRef4(null);
+  const [isActive, setIsActive] = useState4(false);
+  const [networkQuality, setNetworkQuality] = useState4("good");
+  const [tick, setTick] = useState4(0);
+  const [serverTick, setServerTick] = useState4(0);
+  const [drift, setDrift] = useState4(0);
+  const actorRegistry = useRef4(getActorRegistry());
+  const wasHostRef = useRef4(null);
+  const buildSnapshotOpts = useCallback5(() => {
+    return {
+      broadcastRate: options.broadcastRate,
+      keyframeInterval: options.keyframeInterval,
+      bufferSize: options.interpolation?.bufferSize,
+      interpolationMethod: options.interpolation?.method,
+      extrapolateMs: options.interpolation?.extrapolateMs,
+      is2D: is2DRef.current ?? true
+    };
+  }, [
+    options.broadcastRate,
+    options.keyframeInterval,
+    options.interpolation?.bufferSize,
+    options.interpolation?.method,
+    options.interpolation?.extrapolateMs
+  ]);
+  useEffect5(() => {
+    const transport = networkManager.transport;
+    if (!transport) return;
+    const debugOpts = options.debug;
+    let simulator = null;
+    if (debugOpts?.simulatedLatencyMs || debugOpts?.simulatedPacketLoss) {
+      simulator = new NetworkSimulator({
+        latencyMs: debugOpts.simulatedLatencyMs,
+        packetLoss: debugOpts.simulatedPacketLoss
+      });
+      networkSimulatorRef.current = simulator;
+      const origCreateChannel = transport.createChannel.bind(transport);
+      transport.createChannel = (name, channelOpts) => {
+        const ch = origCreateChannel(name, channelOpts);
+        const wrappedSend = simulator.wrapSend(ch.send.bind(ch));
+        return { ...ch, send: wrappedSend };
+      };
+    }
+    eventSyncRef.current = new EventSync(transport);
+    if (mode === "snapshot" || mode === "prediction") {
+      snapshotSyncRef.current = new SnapshotSync(
+        transport,
+        networkManager.codec,
+        networkManager.snapshotBuffer,
+        buildSnapshotOpts()
+      );
+    }
+    if (mode === "prediction") {
+      predictionSyncRef.current = new PredictionSync(
+        transport,
+        networkManager.codec,
+        networkManager.tickKeeper,
+        options.prediction
+      );
+      if (options.onPhysicsStep) {
+        predictionSyncRef.current.setPhysicsStep(options.onPhysicsStep);
+      }
+    }
+    wasHostRef.current = networkManager.isHost;
+    setIsActive(true);
+    const unsubHostChanged = (() => {
+      const onHostChanged = (newHostId) => {
+        const amNewHost = newHostId === transport.peerId;
+        const wasPreviouslyHost = wasHostRef.current;
+        wasHostRef.current = amNewHost;
+        if (amNewHost && !wasPreviouslyHost) {
+          snapshotSyncRef.current?.promoteToHost(buildSnapshotOpts());
+        } else if (!amNewHost && wasPreviouslyHost) {
+          snapshotSyncRef.current?.demoteToClient(buildSnapshotOpts());
+        }
+      };
+      transport.onHostChanged(onHostChanged);
+      return () => {
+      };
+    })();
+    return () => {
+      unsubHostChanged();
+      eventSyncRef.current?.destroy();
+      snapshotSyncRef.current?.destroy();
+      predictionSyncRef.current?.destroy();
+      networkSimulatorRef.current?.destroy();
+      eventSyncRef.current = null;
+      snapshotSyncRef.current = null;
+      predictionSyncRef.current = null;
+      networkSimulatorRef.current = null;
+      setIsActive(false);
+    };
+  }, [networkManager, mode, buildSnapshotOpts, options.prediction, options.onPhysicsStep, options.debug]);
+  useEffect5(() => {
+    const unsub = networkManager.onConnectionStateChange(() => {
+      setNetworkQuality(networkManager.networkQuality);
+    });
+    return unsub;
+  }, [networkManager]);
+  useFrame((_state, delta) => {
+    const transport = networkManager.transport;
+    if (!transport) return;
+    const tickKeeper = networkManager.tickKeeper;
+    const isHost = networkManager.isHost;
+    if (is2DRef.current === null) {
+      const networked = actorRegistry.current.getNetworked();
+      if (networked.size > 0) {
+        is2DRef.current = detect2D(networked);
+      }
+    }
+    const is2D = is2DRef.current ?? true;
+    if (mode === "events") return;
+    const ticksThisFrame = tickKeeper.update(delta);
+    for (let i = 0; i < ticksThisFrame; i++) {
+      const currentTick = tickKeeper.tick - (ticksThisFrame - 1 - i);
+      if (isHost) {
+        const networked = actorRegistry.current.getNetworked();
+        const entities = buildEntityMap(networked, is2D);
+        if (mode === "snapshot" || mode === "prediction") {
+          snapshotSyncRef.current?.hostTick(currentTick, entities, tickKeeper.tickDelta);
+        }
+        if (mode === "prediction") {
+          predictionSyncRef.current?.hostTick(currentTick, entities, tickKeeper.tickDelta);
+        }
+      } else {
+        if (mode === "prediction" && predictionSyncRef.current) {
+          predictionSyncRef.current.clientTick(currentTick);
+        }
+      }
+    }
+    if (!isHost) {
+      if (mode === "snapshot" && snapshotSyncRef.current) {
+        const renderTime = performance.now();
+        const interpolated = snapshotSyncRef.current.clientInterpolate(renderTime);
+        applyStatesToActors(interpolated, actorRegistry.current, is2D);
+      } else if (mode === "prediction" && predictionSyncRef.current) {
+        const predicted = predictionSyncRef.current.predictedState;
+        const smoothed = predictionSyncRef.current.applyErrorSmoothing(predicted);
+        applyStatesToActors(smoothed, actorRegistry.current, is2D);
+      }
+    }
+    if (ticksThisFrame > 0) {
+      const newTick = tickKeeper.tick;
+      const newServerTick = tickKeeper.serverTick;
+      const newDrift = tickKeeper.drift;
+      const newQuality = networkManager.networkQuality;
+      setTick((prev) => prev !== newTick ? newTick : prev);
+      setServerTick((prev) => prev !== newServerTick ? newServerTick : prev);
+      setDrift((prev) => prev !== newDrift ? newDrift : prev);
+      setNetworkQuality((prev) => prev !== newQuality ? newQuality : prev);
+    }
+  }, -55);
+  return {
+    isActive,
+    networkQuality,
+    tick,
+    serverTick,
+    drift,
+    syncEngine: mode
+  };
+}
+
+// src/hooks/useNetworkEvents.ts
+import { useRef as useRef5, useEffect as useEffect6, useCallback as useCallback6 } from "react";
+function useNetworkEvents(options) {
+  const { networkManager } = useMultiplayerContext();
+  const eventSyncRef = useRef5(null);
+  const pendingRef = useRef5([]);
+  const drainedUnsubsRef = useRef5([]);
+  useEffect6(() => {
+    const transport = networkManager.transport;
+    if (!transport) return;
+    const eventSync = new EventSync(transport, {
+      hostValidation: options?.hostValidation
+    });
+    eventSyncRef.current = eventSync;
+    const unsubs = [];
+    for (const entry of pendingRef.current) {
+      const unsub = eventSync.onEvent(entry.type, entry.callback);
+      entry.unsub = unsub;
+      unsubs.push(unsub);
+    }
+    pendingRef.current = [];
+    drainedUnsubsRef.current = unsubs;
+    return () => {
+      for (const unsub of drainedUnsubsRef.current) {
+        unsub();
+      }
+      drainedUnsubsRef.current = [];
+      eventSync.destroy();
+      eventSyncRef.current = null;
+    };
+  }, [networkManager.transport, options?.hostValidation]);
+  const sendEvent = useCallback6((type, payload, target) => {
+    eventSyncRef.current?.sendEvent(type, payload, target);
+  }, []);
+  const broadcast = useCallback6((type, payload) => {
+    eventSyncRef.current?.broadcast(type, payload);
+  }, []);
+  const onEvent = useCallback6((type, callback) => {
+    const castCallback = callback;
+    if (eventSyncRef.current) {
+      return eventSyncRef.current.onEvent(type, castCallback);
+    }
+    const entry = { type, callback: castCallback, unsub: null };
+    pendingRef.current.push(entry);
+    return () => {
+      if (entry.unsub) {
+        entry.unsub();
+        drainedUnsubsRef.current = drainedUnsubsRef.current.filter((u) => u !== entry.unsub);
+      } else {
+        pendingRef.current = pendingRef.current.filter((e) => e !== entry);
+      }
+    };
+  }, []);
+  return { sendEvent, broadcast, onEvent };
+}
+
+// src/hooks/useNetworkState.ts
+import { useState as useState5, useEffect as useEffect7, useCallback as useCallback7, useRef as useRef6 } from "react";
+var CHANNEL_NAME = "carver:network-state";
+function useNetworkState() {
+  const { networkManager } = useMultiplayerContext();
+  const [entities, setEntities] = useState5(
+    () => /* @__PURE__ */ new Map()
+  );
+  const entitiesRef = useRef6(entities);
+  entitiesRef.current = entities;
+  const channelRef = useRef6(null);
+  const replaceEntities = useCallback7(
+    (updater) => {
+      setEntities((prev) => {
+        const next = updater(prev);
+        entitiesRef.current = next;
+        return next;
+      });
+    },
+    []
+  );
+  const applySpawn = useCallback7(
+    (id, state) => {
+      replaceEntities((prev) => {
+        const next = new Map(prev);
+        next.set(id, state);
+        return next;
+      });
+    },
+    [replaceEntities]
+  );
+  const applyDespawn = useCallback7(
+    (id) => {
+      replaceEntities((prev) => {
+        if (!prev.has(id)) return prev;
+        const next = new Map(prev);
+        next.delete(id);
+        return next;
+      });
+    },
+    [replaceEntities]
+  );
+  useEffect7(() => {
+    const transport = networkManager.transport;
+    if (!transport) return;
+    const channel = transport.createChannel(CHANNEL_NAME, {
+      reliable: true,
+      ordered: true
+    });
+    channelRef.current = channel;
+    channel.onReceive((msg, _peerId) => {
+      switch (msg.action) {
+        // --- Spawn broadcast (sent by host to everyone) ---
+        case "spawn": {
+          if (msg.state) {
+            applySpawn(msg.id, msg.state);
+          }
+          break;
+        }
+        // --- Despawn broadcast (sent by host to everyone) ---
+        case "despawn": {
+          applyDespawn(msg.id);
+          break;
+        }
+        // --- Request-spawn (client -> host only) ---
+        case "request-spawn": {
+          if (!transport.isHost) break;
+          if (entitiesRef.current.has(msg.id)) break;
+          const config = msg.state ?? {};
+          const newState = {
+            id: msg.id,
+            x: 0,
+            y: 0,
+            a: 0,
+            vx: 0,
+            vy: 0,
+            va: 0,
+            ...config,
+            // Ensure id is authoritative.
+            ...config.id !== void 0 ? {} : {}
+          };
+          newState.id = msg.id;
+          applySpawn(msg.id, newState);
+          channel.send({ action: "spawn", id: msg.id, state: newState });
+          break;
+        }
+      }
+    });
+    return () => {
+      channel.close();
+      channelRef.current = null;
+    };
+  }, [networkManager.transport, applySpawn, applyDespawn]);
+  const spawn = useCallback7(
+    (id, initialState) => {
+      const transport = networkManager.transport;
+      if (!transport) {
+        console.warn("[useNetworkState] spawn called before transport is ready.");
+        return;
+      }
+      if (!transport.isHost) {
+        console.warn(
+          "[useNetworkState] spawn is host-only. Use requestSpawn() from a client."
+        );
+        return;
+      }
+      if (entitiesRef.current.has(id)) {
+        console.warn(
+          `[useNetworkState] entity "${id}" already exists. Ignoring spawn.`
+        );
+        return;
+      }
+      const state = { ...initialState, id };
+      applySpawn(id, state);
+      channelRef.current?.send({ action: "spawn", id, state });
+    },
+    [networkManager, applySpawn]
+  );
+  const despawn = useCallback7(
+    (id) => {
+      const transport = networkManager.transport;
+      if (!transport) {
+        console.warn("[useNetworkState] despawn called before transport is ready.");
+        return;
+      }
+      if (!transport.isHost) {
+        console.warn("[useNetworkState] despawn is host-only.");
+        return;
+      }
+      if (!entitiesRef.current.has(id)) {
+        console.warn(
+          `[useNetworkState] entity "${id}" does not exist. Ignoring despawn.`
+        );
+        return;
+      }
+      applyDespawn(id);
+      channelRef.current?.send({ action: "despawn", id });
+    },
+    [networkManager, applyDespawn]
+  );
+  const requestSpawn = useCallback7(
+    (id, config) => {
+      const transport = networkManager.transport;
+      if (!transport) {
+        console.warn(
+          "[useNetworkState] requestSpawn called before transport is ready."
+        );
+        return;
+      }
+      if (transport.isHost) {
+        if (entitiesRef.current.has(id)) {
+          console.warn(
+            `[useNetworkState] entity "${id}" already exists. Ignoring requestSpawn.`
+          );
+          return;
+        }
+        const newState = {
+          id,
+          x: 0,
+          y: 0,
+          a: 0,
+          vx: 0,
+          vy: 0,
+          va: 0,
+          ...config
+        };
+        newState.id = id;
+        applySpawn(id, newState);
+        channelRef.current?.send({ action: "spawn", id, state: newState });
+        return;
+      }
+      channelRef.current?.send(
+        { action: "request-spawn", id, state: config },
+        transport.hostId
+      );
+    },
+    [networkManager, applySpawn]
+  );
+  const getState = useCallback7(
+    (id) => {
+      return entitiesRef.current.get(id);
+    },
+    []
+  );
+  const setState = useCallback7(
+    (id, partialState) => {
+      const transport = networkManager.transport;
+      if (!transport) {
+        console.warn("[useNetworkState] setState called before transport is ready.");
+        return;
+      }
+      if (!transport.isHost) {
+        console.warn("[useNetworkState] setState is host-only.");
+        return;
+      }
+      const existing = entitiesRef.current.get(id);
+      if (!existing) {
+        console.warn(
+          `[useNetworkState] entity "${id}" does not exist. Cannot setState.`
+        );
+        return;
+      }
+      const updated = {
+        ...existing,
+        ...partialState,
+        id
+        // id is immutable
+      };
+      replaceEntities((prev) => {
+        const next = new Map(prev);
+        next.set(id, updated);
+        return next;
+      });
+      channelRef.current?.send({ action: "spawn", id, state: updated });
+    },
+    [networkManager, replaceEntities]
+  );
+  return {
+    spawn,
+    despawn,
+    requestSpawn,
+    getState,
+    setState,
+    entities
+  };
+}
+
+// src/core/DebugOverlay.ts
+var QUALITY_COLORS = {
+  good: "#00ff00",
+  degraded: "#ffff00",
+  poor: "#ff4444"
+};
+var DebugOverlay = class {
+  constructor(options) {
+    this.visible = true;
+    this.lastHTML = "";
+    const opts = options ?? {};
+    this.keyboardToggle = opts.keyboardToggle ?? "F3";
+    this.el = document.createElement("div");
+    const pos = opts.position ?? "top-right";
+    const posStyles = this.positionStyles(pos);
+    Object.assign(this.el.style, {
+      position: "fixed",
+      ...posStyles,
+      background: "rgba(0,0,0,0.75)",
+      color: "#00ff00",
+      fontFamily: "'Courier New', monospace",
+      fontSize: "11px",
+      padding: "8px",
+      borderRadius: "4px",
+      zIndex: "99999",
+      pointerEvents: "none",
+      whiteSpace: "pre",
+      lineHeight: "1.4",
+      minWidth: "200px",
+      boxSizing: "border-box"
+    });
+    document.body.appendChild(this.el);
+    this.handleKey = (e) => {
+      if (e.key === this.keyboardToggle) {
+        e.preventDefault();
+        this.toggle();
+      }
+    };
+    window.addEventListener("keydown", this.handleKey);
+  }
+  /* ---- public API ---- */
+  update(stats) {
+    if (!this.visible) return;
+    const latencyDisplay = this.formatLatency(stats.latencyMs);
+    const qualityColor = QUALITY_COLORS[stats.networkQuality] ?? "#00ff00";
+    const bwIn = (stats.bandwidthIn / 1024).toFixed(1);
+    const bwOut = (stats.bandwidthOut / 1024).toFixed(1);
+    const loss = (stats.packetLossRate * 100).toFixed(1);
+    const html = `<b style="color:#00ccff">== NET DEBUG ==</b>
+tick       ${stats.tick}
+srv tick   ${stats.serverTick}
+drift      ${stats.drift}
+latency    ${latencyDisplay} ms
+loss       ${loss}%
+bw in      ${bwIn} KB/s
+bw out     ${bwOut} KB/s
+quality    <span style="color:${qualityColor}">${stats.networkQuality}</span>
+peers      ${stats.peerCount}
+host       ${stats.isHost ? "YES" : "NO"}
+sync       ${stats.syncMode}`;
+    if (html !== this.lastHTML) {
+      this.el.innerHTML = html;
+      this.lastHTML = html;
+    }
+  }
+  show() {
+    this.visible = true;
+    this.el.style.display = "block";
+  }
+  hide() {
+    this.visible = false;
+    this.el.style.display = "none";
+  }
+  toggle() {
+    if (this.visible) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+  destroy() {
+    window.removeEventListener("keydown", this.handleKey);
+    this.el.remove();
+  }
+  /* ---- helpers ---- */
+  positionStyles(pos) {
+    switch (pos) {
+      case "top-left":
+        return { top: "8px", left: "8px" };
+      case "top-right":
+        return { top: "8px", right: "8px" };
+      case "bottom-left":
+        return { bottom: "8px", left: "8px" };
+      case "bottom-right":
+        return { bottom: "8px", right: "8px" };
+    }
+  }
+  formatLatency(latency) {
+    if (typeof latency === "number") {
+      return latency.toFixed(1);
+    }
+    if (latency.size === 0) return "\u2014";
+    let sum = 0;
+    latency.forEach((v) => sum += v);
+    return (sum / latency.size).toFixed(1);
+  }
+};
+
+// src/core/InterestManager.ts
+var InterestManager = class {
+  constructor(options) {
+    this._cellSize = options?.cellSize ?? 50;
+    this._defaultRadius = options?.defaultRadius ?? 200;
+    this._alwaysRelevant = new Set(options?.alwaysRelevant ?? []);
+    this._cells = /* @__PURE__ */ new Map();
+    this._entityPositions = /* @__PURE__ */ new Map();
+  }
+  // ── Public API ──
+  /**
+   * Rebuild the spatial hash from the authoritative entity map.
+   * Called once per host tick before any relevance queries.
+   */
+  updateEntities(entities) {
+    this._cells.clear();
+    this._entityPositions.clear();
+    for (const [id, entity] of entities) {
+      const z = "z" in entity ? entity.z : 0;
+      const pos = { x: entity.x, y: entity.y, z };
+      this._entityPositions.set(id, pos);
+      const key = this._cellKey(pos.x, pos.y, pos.z);
+      let bucket = this._cells.get(key);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Set();
+        this._cells.set(key, bucket);
+      }
+      bucket.add(id);
+    }
+  }
+  /**
+   * Return the set of entity ids relevant to a single client.
+   *
+   * Relevance is the *union* of:
+   *  1. Entities whose cell overlaps the client's bounding sphere
+   *  2. Entities in the `alwaysRelevant` set
+   *  3. Entities owned by this client
+   */
+  getRelevantEntities(clientPosition, clientId, owners, overrideRadius) {
+    const radius = overrideRadius ?? this._defaultRadius;
+    const cx = clientPosition.x;
+    const cy = clientPosition.y;
+    const cz = clientPosition.z ?? 0;
+    const result = /* @__PURE__ */ new Set();
+    const minCellX = Math.floor((cx - radius) / this._cellSize);
+    const maxCellX = Math.floor((cx + radius) / this._cellSize);
+    const minCellY = Math.floor((cy - radius) / this._cellSize);
+    const maxCellY = Math.floor((cy + radius) / this._cellSize);
+    const minCellZ = Math.floor((cz - radius) / this._cellSize);
+    const maxCellZ = Math.floor((cz + radius) / this._cellSize);
+    for (let ix = minCellX; ix <= maxCellX; ix++) {
+      for (let iy = minCellY; iy <= maxCellY; iy++) {
+        for (let iz = minCellZ; iz <= maxCellZ; iz++) {
+          const key = `${ix},${iy},${iz}`;
+          const bucket = this._cells.get(key);
+          if (bucket) {
+            for (const entityId of bucket) {
+              result.add(entityId);
+            }
+          }
+        }
+      }
+    }
+    for (const id of this._alwaysRelevant) {
+      if (this._entityPositions.has(id)) {
+        result.add(id);
+      }
+    }
+    for (const [entityId, ownerId] of owners) {
+      if (ownerId === clientId && this._entityPositions.has(entityId)) {
+        result.add(entityId);
+      }
+    }
+    return result;
+  }
+  /**
+   * Build a filter callback compatible with
+   * `HostAuthority.setInterestFilter`.
+   *
+   * The returned function closes over a single relevance pass for every
+   * known client so that per-entity filtering during broadcast is a cheap
+   * `Set.has` lookup.
+   *
+   * @param clientPositions  peerId -> position of that client's camera/player
+   * @param owners           entityId -> ownerPeerId
+   */
+  createFilter(clientPositions, owners) {
+    const relevanceSets = /* @__PURE__ */ new Map();
+    for (const [peerId, pos] of clientPositions) {
+      relevanceSets.set(
+        peerId,
+        this.getRelevantEntities(pos, peerId, owners)
+      );
+    }
+    return (entityId, peerId) => {
+      const set = relevanceSets.get(peerId);
+      if (!set) return true;
+      return set.has(entityId);
+    };
+  }
+  /** Remove all data from the grid. */
+  clear() {
+    this._cells.clear();
+    this._entityPositions.clear();
+  }
+  // ── Private helpers ──
+  _cellKey(x, y, z) {
+    const cx = Math.floor(x / this._cellSize);
+    const cy = Math.floor(y / this._cellSize);
+    const cz = Math.floor(z / this._cellSize);
+    return `${cx},${cy},${cz}`;
+  }
+};
+export {
+  DebugOverlay,
+  FirebaseStrategy,
+  InterestManager,
+  MqttStrategy,
+  MultiplayerBridge,
+  MultiplayerProvider,
+  NetworkSimulator,
+  useHost,
+  useLobby,
+  useMultiplayer,
+  useNetworkEvents,
+  useNetworkState,
+  usePlayers,
+  useRoom
+};
+//# sourceMappingURL=index.mjs.map