@nolag/iot 0.1.2 → 1.0.0

package/dist/index.mjs

@@ -1,5 +1,3 @@
-import { NoLag } from '@nolag/js-sdk';
-
 /**
  * Tiny typed event emitter — framework-agnostic base for NoLag SDKs.
  *
@@ -233,6 +231,29 @@ function createLogger(prefix, enabled) {
         console.log(`[${prefix}]`, ...args);
     };
 }
+// ============ Wrapper registry ============
+// One wrapper instance per (client, appName): two wrappers sharing an app on
+// one connection would collide on topics, presence and the online lobby.
+// Warn (not throw): HMR and tests legitimately construct before disposing.
+const wrapperRegistry = new WeakMap();
+/** Register a wrapper against a client + appName; warns on collision. */
+function registerWrapper(client, appName, wrapperName) {
+    let apps = wrapperRegistry.get(client);
+    if (!apps) {
+        apps = new Map();
+        wrapperRegistry.set(client, apps);
+    }
+    const existing = apps.get(appName);
+    if (existing) {
+        console.warn(`[${wrapperName}] Another wrapper (${existing}) is already attached to this client for app "${appName}". ` +
+            `Use one wrapper per (client, app) — detach the other instance first.`);
+    }
+    apps.set(appName, wrapperName);
+}
+/** Release a wrapper's (client, appName) registration on detach. */
+function releaseWrapper(client, appName) {
+    wrapperRegistry.get(client)?.delete(appName);
+}
 
 /**
  * Command dispatch with ack tracking and per-command timeout.
@@ -362,6 +383,8 @@ const TOPIC_COMMANDS = 'commands';
 const TOPIC_CMD_ACK = '_cmd_ack';
 /** Lobby ID for global online presence */
 const LOBBY_ID = 'online';
+/** Delay before the post-setup lobby presence refetch (catches simultaneous joiners) */
+const LOBBY_REFRESH_DELAY_MS = 2000;
 
 /**
  * DeviceGroup — a single IoT group for telemetry streaming and command dispatch.
@@ -370,14 +393,20 @@ const LOBBY_ID = 'online';
  */
 class DeviceGroup extends EventEmitter {
     /** @internal */
-    constructor(name, roomContext, localDevice, options, log) {
+    constructor(name, roomContext, localDevice, options, log, isConnected) {
         super();
         this._receivedCommands = new Map();
+        // Stored topic handler refs — cleanup removes exactly these, never all
+        // handlers for a topic (the client may be shared with other consumers).
+        this._onTelemetryRef = null;
+        this._onCommandsRef = null;
+        this._onCmdAckRef = null;
         this.name = name;
         this._roomContext = roomContext;
         this._localDevice = localDevice;
         this._options = options;
         this._log = log;
+        this._isConnected = isConnected;
         this._presenceManager = new PresenceManager(localDevice.actorTokenId);
         this._telemetryStore = new TelemetryStore(options.maxTelemetryPoints);
         this._commandManager = new CommandManager(options.commandTimeout);
@@ -486,15 +515,20 @@ class DeviceGroup extends EventEmitter {
         else {
             this._roomContext.subscribe(TOPIC_CMD_ACK);
         }
-        this._roomContext.on(TOPIC_TELEMETRY, (data) => {
+        // Listeners: refs stored for handler-specific removal (the client may be
+        // shared with other consumers on the same topic).
+        this._onTelemetryRef = (data) => {
             this._handleIncomingTelemetry(data);
-        });
-        this._roomContext.on(TOPIC_COMMANDS, (data) => {
+        };
+        this._roomContext.on(TOPIC_TELEMETRY, this._onTelemetryRef);
+        this._onCommandsRef = (data) => {
             this._handleIncomingCommand(data);
-        });
-        this._roomContext.on(TOPIC_CMD_ACK, (data) => {
+        };
+        this._roomContext.on(TOPIC_COMMANDS, this._onCommandsRef);
+        this._onCmdAckRef = (data) => {
             this._handleIncomingCmdAck(data);
-        });
+        };
+        this._roomContext.on(TOPIC_CMD_ACK, this._onCmdAckRef);
     }
     /** @internal Set presence and fetch existing group members */
     _activate() {
@@ -541,12 +575,25 @@ class DeviceGroup extends EventEmitter {
     /** @internal Unsubscribe and clean up */
     _cleanup() {
         this._log('Group cleanup:', this.name);
-        this._roomContext.unsubscribe(TOPIC_TELEMETRY);
-        this._roomContext.unsubscribe(TOPIC_COMMANDS);
-        this._roomContext.unsubscribe(TOPIC_CMD_ACK);
-        this._roomContext.off(TOPIC_TELEMETRY);
-        this._roomContext.off(TOPIC_COMMANDS);
-        this._roomContext.off(TOPIC_CMD_ACK);
+        // Server unsubscribes need a live socket; skip when disconnected
+        // (best-effort — the core would no-op with an error callback anyway).
+        if (this._isConnected()) {
+            this._roomContext.unsubscribe(TOPIC_TELEMETRY);
+            this._roomContext.unsubscribe(TOPIC_COMMANDS);
+            this._roomContext.unsubscribe(TOPIC_CMD_ACK);
+        }
+        // Handler-specific removal only: the client may be shared, and a bare
+        // off(topic) would strip other consumers' handlers too.
+        if (this._onTelemetryRef)
+            this._roomContext.off(TOPIC_TELEMETRY, this._onTelemetryRef);
+        if (this._onCommandsRef)
+            this._roomContext.off(TOPIC_COMMANDS, this._onCommandsRef);
+        if (this._onCmdAckRef)
+            this._roomContext.off(TOPIC_CMD_ACK, this._onCmdAckRef);
+        this._onTelemetryRef = null;
+        this._onCommandsRef = null;
+        this._onCmdAckRef = null;
+        // Clears all pending command-timeout timers and rejects orphaned commands.
         this._commandManager.dispose();
         this._receivedCommands.clear();
         this._presenceManager.clear();
@@ -584,6 +631,9 @@ class DeviceGroup extends EventEmitter {
             deviceName: this._localDevice.deviceName,
             role: this._localDevice.role,
             metadata: this._localDevice.metadata,
+            // Scope tag: on a shared client, other apps' wrappers filter our
+            // presence out by this (and we filter theirs).
+            __scope: this._options.appName,
         };
         this._roomContext.setPresence(presenceData);
     }
@@ -595,37 +645,72 @@ class DeviceGroup extends EventEmitter {
  * Provides device presence, real-time telemetry streaming, and command dispatch
  * with ack tracking — all framework-agnostic via events.
  *
+ * The wrapper NEVER manages the connection. The app owns one core NoLag
+ * client (shared by any number of wrappers on distinct apps) and the
+ * wrapper attaches to it at construction and releases it via `detach()`.
+ *
  * @example
  * ```typescript
+ * import { NoLag } from '@nolag/js-sdk';
  * import { NoLagIoT } from '@nolag/iot';
  *
- * const iot = new NoLagIoT(token, { deviceId: 'sensor-01', role: 'device', debug: true });
+ * const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token);
+ * const iot = new NoLagIoT({ client, deviceId: 'sensor-01', role: 'device' });
  *
  * iot.on('connected', () => console.log('Connected!'));
- * await iot.connect();
+ *
+ * await client.connect();   // the app owns the connection
+ * await iot.ready();        // wrapper setup done (identity, lobby, groups)
  *
  * const group = iot.joinGroup('factory-floor');
  * group.on('command', (cmd) => {
- *   console.log('Received command:', cmd.command);
  *   group.ackCommand(cmd.id, 'completed', { ok: true });
  * });
+ * group.sendTelemetry('temperature', 22.5, { unit: '°C' });
  *
- * // Send telemetry every second
- * setInterval(() => {
- *   group.sendTelemetry('temperature', 22.5, { unit: '°C' });
- * }, 1000);
+ * iot.detach();             // wrapper releases its handlers and topics
+ * client.disconnect();      // the app closes the socket
  * ```
  */
 class NoLagIoT extends EventEmitter {
-    constructor(token, options = {}) {
+    constructor(options) {
         super();
-        this._client = null;
         this._localDevice = null;
         this._groups = new Map();
         this._lobby = null;
         this._onlineDevices = new Map();
         this._actorToDeviceId = new Map();
-        this._token = token;
+        // Lifecycle: one setup run per connection epoch; detach is terminal.
+        this._epoch = 0;
+        this._detached = false;
+        this._isReady = false;
+        this._lobbyRefreshTimer = null;
+        // Stored client handler refs. INVARIANT: every client.on() below has a
+        // matching client.off() in detach() — never bare off(event), never inline
+        // closures on the client.
+        this._onConnectRef = () => this._onConnect();
+        this._onDisconnectRef = (reason) => {
+            this._log('Disconnected:', reason);
+            this.emit('disconnected', reason);
+        };
+        this._onReconnectRef = () => {
+            this._log('Reconnecting...');
+            this.emit('reconnecting');
+        };
+        this._onErrorRef = (error) => {
+            this._log('Error:', error);
+            this.emit('error', error);
+        };
+        this._onPresenceJoinRef = (data) => this._handleRoomPresenceJoin(data);
+        this._onPresenceLeaveRef = (data) => this._handleRoomPresenceLeave(data);
+        this._onPresenceUpdateRef = (data) => this._handleRoomPresenceUpdate(data);
+        this._onLobbyJoinRef = (data) => this._handleLobbyJoin(data);
+        this._onLobbyLeaveRef = (data) => this._handleLobbyLeave(data);
+        this._onLobbyUpdateRef = (data) => this._handleLobbyUpdate(data);
+        if (!options?.client) {
+            throw new TypeError('NoLagIoT requires an injected NoLag client: new NoLagIoT({ client, deviceId, ... })');
+        }
+        this._client = options.client;
         this._deviceId = options.deviceId ?? generateId();
         this._options = {
             deviceId: this._deviceId,
@@ -633,21 +718,49 @@ class NoLagIoT extends EventEmitter {
             role: options.role ?? 'device',
             metadata: options.metadata,
             appName: options.appName ?? DEFAULT_APP_NAME,
-            url: options.url,
             maxTelemetryPoints: options.maxTelemetryPoints ?? DEFAULT_MAX_TELEMETRY_POINTS,
             commandTimeout: options.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT,
             debug: options.debug ?? false,
-            reconnect: options.reconnect ?? true,
             groups: options.groups ?? [],
         };
         this._log = createLogger('NoLagIoT', this._options.debug);
+        this._readyPromise = new Promise((resolve, reject) => {
+            this._readyResolve = resolve;
+            this._readyReject = reject;
+        });
+        // ready() rejection is only meaningful to callers that await it
+        this._readyPromise.catch(() => { });
+        registerWrapper(this._client, this._options.appName, 'NoLagIoT');
+        // Construction = attach: wire everything now, with stored refs.
+        this._client.on('connect', this._onConnectRef);
+        this._client.on('disconnect', this._onDisconnectRef);
+        this._client.on('reconnect', this._onReconnectRef);
+        this._client.on('error', this._onErrorRef);
+        this._client.on('presence:join', this._onPresenceJoinRef);
+        this._client.on('presence:leave', this._onPresenceLeaveRef);
+        this._client.on('presence:update', this._onPresenceUpdateRef);
+        this._client.on('lobbyPresence:join', this._onLobbyJoinRef);
+        this._client.on('lobbyPresence:leave', this._onLobbyLeaveRef);
+        this._client.on('lobbyPresence:update', this._onLobbyUpdateRef);
+        // Attach-to-connected: if the client is already authenticated, run setup.
+        // The microtask lets the caller wire wrapper event handlers synchronously
+        // first; a racing real 'connect' event wins via the epoch guard.
+        queueMicrotask(() => {
+            if (this._epoch === 0 && !this._detached && this._client.connected) {
+                this._onConnect();
+            }
+        });
     }
     // ============ Public Properties ============
-    /** Whether the underlying connection is established */
+    /** Whether the underlying connection is established (connected ≠ ready) */
     get connected() {
-        return this._client?.connected ?? false;
+        return !this._detached && this._client.connected;
     }
-    /** The local device info (available after connect) */
+    /** The injected core client (owned by the app, not the wrapper) */
+    get client() {
+        return this._client;
+    }
+    /** The local device info (available after ready) */
     get localDevice() {
         return this._localDevice;
     }
@@ -657,97 +770,162 @@ class NoLagIoT extends EventEmitter {
     }
     // ============ Lifecycle ============
     /**
-     * Connect to NoLag and set up global presence.
+     * Resolves once the wrapper's first setup completed (identity, lobby and
+     * configured groups ready — equivalently, once 'connected' has fired).
+     * Rejects only if detach() is called before that. Client auth failures
+     * surface via the app's own `await client.connect()`, not here.
      */
-    async connect() {
-        this._log('Connecting...');
-        const clientOptions = {
-            debug: this._options.debug,
-            reconnect: this._options.reconnect,
-        };
-        if (this._options.url) {
-            clientOptions.url = this._options.url;
-        }
-        this._client = NoLag(this._token, clientOptions);
-        // Wire client lifecycle events
-        this._client.on('connect', () => {
-            this._log('Connected');
-            if (this._groups.size > 0) {
-                this._log('Reconnected — restoring groups...');
-                this._restoreGroups();
-                this.emit('reconnected');
-            }
-        });
-        this._client.on('disconnect', (reason) => {
-            this._log('Disconnected:', reason);
-            this.emit('disconnected', reason);
-        });
-        this._client.on('reconnect', () => {
-            this._log('Reconnecting...');
-        });
-        this._client.on('error', (error) => {
-            this._log('Error:', error);
-            this.emit('error', error);
-        });
-        // Connect
-        await this._client.connect();
-        // Wire room-level presence events
-        this._client.on('presence:join', (data) => {
-            this._handleRoomPresenceJoin(data);
-        });
-        this._client.on('presence:leave', (data) => {
-            this._handleRoomPresenceLeave(data);
-        });
-        this._client.on('presence:update', (data) => {
-            this._handleRoomPresenceUpdate(data);
-        });
-        // Create local device record
-        this._localDevice = {
-            deviceId: this._deviceId,
-            actorTokenId: this._client.actorId,
-            deviceName: this._options.deviceName,
-            role: this._options.role,
-            metadata: this._options.metadata,
-            joinedAt: Date.now(),
-            isLocal: true,
-        };
-        this._log('Local device:', this._localDevice.deviceId, '→', this._localDevice.actorTokenId);
-        // Set up lobby for global presence
-        await this._setupLobby();
-        // Emit connected now that _localDevice and lobby are ready
-        this.emit('connected');
-        // Auto-join configured groups
-        for (const groupName of this._options.groups) {
-            this.joinGroup(groupName);
-        }
-        // Deferred lobby refetch to catch devices that joined during setup window
-        setTimeout(() => {
-            if (this._lobby && this._client?.connected) {
-                this._lobby.fetchPresence().then((state) => {
-                    this._hydrateOnlineDevices(state);
-                }).catch(() => { });
-            }
-        }, 2000);
+    ready() {
+        return this._readyPromise;
     }
     /**
-     * Disconnect from NoLag and clean up all groups.
+     * Detach from the client: remove every handler this wrapper added,
+     * unsubscribe its topics and lobby (when connected), clear state. Also
+     * clears any pending command-timeout timers on every group. Terminal and
+     * idempotent; never touches the socket. To use IoT again, construct a new
+     * instance.
      */
-    disconnect() {
-        this._log('Disconnecting...');
-        // Clean up groups
+    detach() {
+        if (this._detached)
+            return;
+        this._log('Detaching...');
+        this._detached = true;
+        this._epoch++; // aborts any in-flight setup at its next checkpoint
+        if (this._lobbyRefreshTimer) {
+            clearTimeout(this._lobbyRefreshTimer);
+            this._lobbyRefreshTimer = null;
+        }
+        // Remove all client handlers by stored ref
+        this._client.off('connect', this._onConnectRef);
+        this._client.off('disconnect', this._onDisconnectRef);
+        this._client.off('reconnect', this._onReconnectRef);
+        this._client.off('error', this._onErrorRef);
+        this._client.off('presence:join', this._onPresenceJoinRef);
+        this._client.off('presence:leave', this._onPresenceLeaveRef);
+        this._client.off('presence:update', this._onPresenceUpdateRef);
+        this._client.off('lobbyPresence:join', this._onLobbyJoinRef);
+        this._client.off('lobbyPresence:leave', this._onLobbyLeaveRef);
+        this._client.off('lobbyPresence:update', this._onLobbyUpdateRef);
+        // Groups: handler-specific off + connected-gated server unsubscribe.
+        // _cleanup() also disposes each group's command-timeout timers.
         for (const name of [...this._groups.keys()]) {
-            this.leaveGroup(name);
+            this._groups.get(name)._cleanup();
+            this._groups.delete(name);
+        }
+        // Lobby: server unsubscribe is best-effort and needs a live socket
+        if (this._lobby && this._client.connected) {
+            try {
+                this._lobby.unsubscribe();
+            }
+            catch {
+                /* best-effort */
+            }
         }
-        // Unsubscribe from lobby
-        this._lobby?.unsubscribe();
         this._lobby = null;
-        // Disconnect client
-        this._client?.disconnect();
-        this._client = null;
-        // Clear state
         this._onlineDevices.clear();
         this._actorToDeviceId.clear();
         this._localDevice = null;
+        releaseWrapper(this._client, this._options.appName);
+        if (!this._isReady) {
+            this._readyReject(new Error('NoLagIoT detached before ready'));
+        }
+    }
+    // ============ Private: Epoch Setup ============
+    _onConnect() {
+        this._epoch++;
+        void this._runSetup(this._epoch);
+    }
+    /**
+     * One setup pass per connection epoch. Serves both initial setup (epoch 1)
+     * and reconnect restore (epoch > 1). Aborts silently whenever a newer
+     * epoch started or the wrapper detached — checked after every await.
+     */
+    async _runSetup(epoch) {
+        const stale = () => epoch !== this._epoch || this._detached;
+        this._log(this._isReady ? 'Restoring after reconnect...' : 'Setting up...');
+        // Identity (client.actorId is guaranteed post-auth)
+        if (!this._localDevice) {
+            this._localDevice = {
+                deviceId: this._deviceId,
+                actorTokenId: this._client.actorId,
+                deviceName: this._options.deviceName,
+                role: this._options.role,
+                metadata: this._options.metadata,
+                joinedAt: Date.now(),
+                isLocal: true,
+            };
+            this._log('Local device:', this._localDevice.deviceId, '→', this._localDevice.actorTokenId);
+        }
+        else {
+            this._localDevice.actorTokenId = this._client.actorId;
+        }
+        // Lobby: subscribe every epoch (idempotent server-side) and diff-hydrate
+        // from the returned snapshot — one path for setup and restore.
+        if (!this._lobby) {
+            this._lobby = this._client.setApp(this._options.appName).setLobby(LOBBY_ID);
+        }
+        try {
+            const state = await this._lobby.subscribe();
+            if (stale())
+                return;
+            this._diffHydrateOnlineDevices(state);
+            this._log('Lobby subscribed, online devices:', this._onlineDevices.size);
+        }
+        catch (err) {
+            if (stale())
+                return;
+            this._log('Lobby subscription failed:', err);
+        }
+        if (!this._isReady) {
+            // First successful setup: pre-join configured groups.
+            for (const groupName of this._options.groups) {
+                const group = this._subscribeGroup(groupName);
+                group._activate();
+            }
+        }
+        else {
+            // Server auto-restored topic subscriptions; only room-scoped presence
+            // needs re-applying (the core does not restore it) — persistent-presence
+            // semantics across reconnects.
+            for (const group of this._groups.values()) {
+                group._updateLocalPresence();
+            }
+        }
+        if (stale())
+            return;
+        // Ready keys on the first setup that COMPLETES, not on epoch 1: an
+        // epoch aborted by a racing reconnect must not strand ready().
+        if (!this._isReady) {
+            this._isReady = true;
+            this._readyResolve();
+            this.emit('connected');
+        }
+        else {
+            this.emit('reconnected');
+        }
+        // Deferred lobby refetch: catches devices who joined during the setup
+        // window (e.g. simultaneous multi-tab connects).
+        this._scheduleLobbyRefresh(epoch);
+    }
+    _scheduleLobbyRefresh(epoch) {
+        if (this._lobbyRefreshTimer)
+            clearTimeout(this._lobbyRefreshTimer);
+        this._lobbyRefreshTimer = setTimeout(() => {
+            this._lobbyRefreshTimer = null;
+            if (epoch !== this._epoch || this._detached || !this._client.connected || !this._lobby) {
+                return;
+            }
+            this._lobby
+                .fetchPresence()
+                .then((state) => {
+                if (epoch !== this._epoch || this._detached)
+                    return;
+                this._diffHydrateOnlineDevices(state);
+            })
+                .catch(() => {
+                /* best-effort */
+            });
+        }, LOBBY_REFRESH_DELAY_MS);
     }
     // ============ Group Management ============
     /**
@@ -755,9 +933,7 @@ class NoLagIoT extends EventEmitter {
      * Returns an existing group if already joined.
      */
     joinGroup(name) {
-        if (!this._client || !this._localDevice) {
-            throw new Error('Not connected — call connect() first');
-        }
+        this._assertUsable();
         let group = this._groups.get(name);
         if (!group) {
             group = this._subscribeGroup(name);
@@ -789,24 +965,41 @@ class NoLagIoT extends EventEmitter {
     getOnlineDevices() {
         return Array.from(this._onlineDevices.values());
     }
+    // ============ Private: Guards ============
+    _assertUsable() {
+        if (this._detached) {
+            throw new Error('NoLagIoT has been detached — construct a new instance');
+        }
+        if (!this._isReady || !this._localDevice) {
+            throw new Error('NoLagIoT not ready — await ready() or the "connected" event');
+        }
+    }
     // ============ Private: Group Setup ============
     _subscribeGroup(name) {
-        if (!this._client || !this._localDevice) {
-            throw new Error('Not connected — call connect() first');
-        }
         this._log('Subscribing group:', name);
         const roomContext = this._client.setApp(this._options.appName).setRoom(name);
-        const group = new DeviceGroup(name, roomContext, this._localDevice, this._options, createLogger(`DeviceGroup:${name}`, this._options.debug));
+        const group = new DeviceGroup(name, roomContext, this._localDevice, this._options, createLogger(`DeviceGroup:${name}`, this._options.debug), () => this._client.connected);
         this._groups.set(name, group);
         group._subscribe();
         return group;
     }
+    // ============ Private: Scope Filtering ============
+    /**
+     * On a shared client, presence events from other apps' wrappers arrive on
+     * the same connection-level events. Wrappers stamp their presence with a
+     * `__scope` (their appName); a mismatched tag means another app's data.
+     * Untagged presence is accepted (older peers in this same app).
+     */
+    _foreignScope(data) {
+        const scope = data?.__scope;
+        return typeof scope === 'string' && scope !== this._options.appName;
+    }
     // ============ Private: Room Presence ============
     _handleRoomPresenceJoin(data) {
         if (data.actorTokenId === this._localDevice?.actorTokenId)
             return;
         const presenceData = data.presence;
-        if (!presenceData?.deviceId)
+        if (!presenceData?.deviceId || this._foreignScope(presenceData))
             return;
         const device = this._presenceToDevice(data.actorTokenId, presenceData);
         this._actorToDeviceId.set(data.actorTokenId, device.deviceId);
@@ -831,7 +1024,7 @@ class NoLagIoT extends EventEmitter {
         if (data.actorTokenId === this._localDevice?.actorTokenId)
             return;
         const presenceData = data.presence;
-        if (!presenceData?.deviceId)
+        if (!presenceData?.deviceId || this._foreignScope(presenceData))
             return;
         if (this._onlineDevices.has(presenceData.deviceId)) {
             const device = this._presenceToDevice(data.actorTokenId, presenceData);
@@ -843,37 +1036,12 @@ class NoLagIoT extends EventEmitter {
         }
     }
     // ============ Private: Lobby ============
-    async _setupLobby() {
-        if (!this._client)
-            return;
-        this._lobby = this._client.setApp(this._options.appName).setLobby(LOBBY_ID);
-        const lobbyHandler = (type) => (data) => {
-            const event = data;
-            if (type === 'join')
-                this._handleLobbyJoin(event);
-            else if (type === 'leave')
-                this._handleLobbyLeave(event);
-            else
-                this._handleLobbyUpdate(event);
-        };
-        this._client.on('lobbyPresence:join', lobbyHandler('join'));
-        this._client.on('lobbyPresence:leave', lobbyHandler('leave'));
-        this._client.on('lobbyPresence:update', lobbyHandler('update'));
-        try {
-            const initialState = await this._lobby.subscribe();
-            this._hydrateOnlineDevices(initialState);
-            this._log('Lobby subscribed, online devices:', this._onlineDevices.size);
-        }
-        catch (err) {
-            this._log('Lobby subscription failed:', err);
-        }
-    }
     _handleLobbyJoin(event) {
         const { actorId, data } = event;
         if (actorId === this._localDevice?.actorTokenId)
             return;
         const presenceData = data;
-        if (!presenceData.deviceId)
+        if (!presenceData?.deviceId || this._foreignScope(presenceData))
             return;
         const device = this._presenceToDevice(actorId, presenceData);
         this._actorToDeviceId.set(actorId, device.deviceId);
@@ -887,6 +1055,8 @@ class NoLagIoT extends EventEmitter {
         if (actorId === this._localDevice?.actorTokenId)
             return;
         const presenceData = data;
+        if (this._foreignScope(presenceData))
+            return;
         const deviceId = presenceData?.deviceId
             || this._actorToDeviceId.get(actorId)
             || this._findDeviceIdByActorId(actorId);
@@ -904,29 +1074,57 @@ class NoLagIoT extends EventEmitter {
         if (actorId === this._localDevice?.actorTokenId)
             return;
         const presenceData = data;
-        if (!presenceData.deviceId)
+        if (!presenceData?.deviceId || this._foreignScope(presenceData))
             return;
         const device = this._presenceToDevice(actorId, presenceData);
         this._onlineDevices.set(device.deviceId, device);
     }
-    _hydrateOnlineDevices(state) {
+    /**
+     * Reconcile the online-device map against a fresh lobby snapshot, emitting
+     * only the deltas (deviceOffline for vanished, deviceOnline for new). One
+     * path for initial hydration, reconnect restore, and the deferred refetch.
+     */
+    _diffHydrateOnlineDevices(state) {
+        // Build the fresh device set from the snapshot
+        const fresh = new Map();
+        const freshActors = new Map();
         for (const roomId of Object.keys(state)) {
             const roomPresence = state[roomId];
             for (const actorId of Object.keys(roomPresence)) {
                 if (actorId === this._localDevice?.actorTokenId)
                     continue;
                 const raw = roomPresence[actorId];
+                // Server returns full actor records with presence nested under .presence
                 const presenceData = (raw?.presence ?? raw);
-                if (presenceData?.deviceId) {
-                    const device = this._presenceToDevice(actorId, presenceData);
-                    this._actorToDeviceId.set(actorId, device.deviceId);
-                    if (!this._onlineDevices.has(device.deviceId)) {
-                        this._onlineDevices.set(device.deviceId, device);
-                        this.emit('deviceOnline', device);
+                if (presenceData?.deviceId && !this._foreignScope(presenceData)) {
+                    if (!fresh.has(presenceData.deviceId)) {
+                        fresh.set(presenceData.deviceId, this._presenceToDevice(actorId, presenceData));
                     }
+                    freshActors.set(actorId, presenceData.deviceId);
                 }
             }
         }
+        // Vanished devices
+        for (const [deviceId, device] of [...this._onlineDevices]) {
+            if (!fresh.has(deviceId)) {
+                this._onlineDevices.delete(deviceId);
+                for (const [actorId, mappedDeviceId] of [...this._actorToDeviceId]) {
+                    if (mappedDeviceId === deviceId)
+                        this._actorToDeviceId.delete(actorId);
+                }
+                this.emit('deviceOffline', device);
+            }
+        }
+        // New devices
+        for (const [deviceId, device] of fresh) {
+            if (!this._onlineDevices.has(deviceId)) {
+                this._onlineDevices.set(deviceId, device);
+                this.emit('deviceOnline', device);
+            }
+        }
+        for (const [actorId, deviceId] of freshActors) {
+            this._actorToDeviceId.set(actorId, deviceId);
+        }
     }
     // ============ Private: Helpers ============
     _presenceToDevice(actorTokenId, data) {
@@ -947,21 +1145,6 @@ class NoLagIoT extends EventEmitter {
         }
         return undefined;
     }
-    _restoreGroups() {
-        // On reconnect, js-sdk auto-restores subscriptions.
-        // Re-set presence on all active groups.
-        for (const group of this._groups.values()) {
-            group._updateLocalPresence();
-        }
-        // Re-fetch lobby presence
-        this._lobby?.fetchPresence().then((state) => {
-            this._onlineDevices.clear();
-            this._actorToDeviceId.clear();
-            this._hydrateOnlineDevices(state);
-        }).catch((err) => {
-            this._log('Failed to re-fetch lobby presence:', err);
-        });
-    }
 }
 
 export { CommandManager, DeviceGroup, EventEmitter, NoLagIoT, PresenceManager, TelemetryStore };