@nolag/dash 0.1.1 → 1.0.0

package/dist/index.cjs

@@ -1,7 +1,5 @@
 'use strict';
 
-var jsSdk = require('@nolag/js-sdk');
-
 class EventEmitter {
     constructor() {
         this._handlers = new Map();
@@ -162,6 +160,29 @@ function createLogger(prefix, enabled) {
     }
     return (...args) => { 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);
+}
 
 const DEFAULT_APP_NAME = 'dash';
 const DEFAULT_MAX_METRIC_POINTS = 1000;
@@ -169,15 +190,23 @@ const DEFAULT_AGGREGATION_WINDOW = 60000; // 1 minute
 const TOPIC_METRICS = 'metrics';
 const TOPIC_WIDGETS = 'widgets';
 const LOBBY_ID = 'online';
+/** Delay before the post-setup lobby presence refetch (catches simultaneous joiners) */
+const LOBBY_REFRESH_DELAY_MS = 2000;
 
 class DashboardPanel extends EventEmitter {
-    constructor(name, roomContext, localViewerId, localActorId, options, log) {
+    /** @internal */
+    constructor(name, roomContext, localViewerId, localActorId, options, log, isConnected) {
         super();
+        // Stored topic handler refs — cleanup removes exactly these, never all
+        // handlers for a topic (the client may be shared with other consumers).
+        this._onMetricsRef = null;
+        this._onWidgetsRef = null;
         this.name = name;
         this._roomContext = roomContext;
         this._localViewerId = localViewerId;
         this._options = options;
         this._log = log;
+        this._isConnected = isConnected;
         this._presenceManager = new PresenceManager(localActorId);
         this._metricStore = new MetricStore(options.maxMetricPoints);
         this._widgetManager = new WidgetManager();
@@ -225,18 +254,22 @@ class DashboardPanel extends EventEmitter {
             this._roomContext.subscribe(TOPIC_METRICS);
         }
         this._roomContext.subscribe(TOPIC_WIDGETS);
-        this._roomContext.on(TOPIC_METRICS, (data, meta) => {
+        // Listen for metrics (refs stored for handler-specific removal)
+        this._onMetricsRef = (data, meta) => {
             const raw = data;
             const point = { id: raw.id, streamId: raw.streamId, value: raw.value, unit: raw.unit, tags: raw.tags, timestamp: raw.timestamp, isReplay: meta.isReplay ?? false };
             if (this._metricStore.add(point))
                 this.emit('metric', point);
-        });
-        this._roomContext.on(TOPIC_WIDGETS, (data, meta) => {
+        };
+        this._roomContext.on(TOPIC_METRICS, this._onMetricsRef);
+        // Listen for widget updates
+        this._onWidgetsRef = (data, meta) => {
             const raw = data;
             const update = { id: raw.id, widgetId: raw.widgetId, type: raw.type, data: raw.data, label: raw.label, timestamp: raw.timestamp, isReplay: meta.isReplay ?? false };
             this._widgetManager.update(update);
             this.emit('widgetUpdate', update);
-        });
+        };
+        this._roomContext.on(TOPIC_WIDGETS, this._onWidgetsRef);
     }
     _activate() {
         this._setPresence();
@@ -260,106 +293,407 @@ class DashboardPanel extends EventEmitter {
     _handleReplayEnd(replayed) { this.emit('replayEnd', { replayed }); }
     _updateLocalPresence() { this._setPresence(); }
     _cleanup() {
-        this._roomContext.unsubscribe(TOPIC_METRICS);
-        this._roomContext.unsubscribe(TOPIC_WIDGETS);
-        this._roomContext.off(TOPIC_METRICS);
-        this._roomContext.off(TOPIC_WIDGETS);
+        this._log('Panel cleanup:', this.name);
+        // 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_METRICS);
+            this._roomContext.unsubscribe(TOPIC_WIDGETS);
+        }
+        // Handler-specific removal only: the client may be shared, and a bare
+        // off(topic) would strip other consumers' handlers too.
+        if (this._onMetricsRef)
+            this._roomContext.off(TOPIC_METRICS, this._onMetricsRef);
+        if (this._onWidgetsRef)
+            this._roomContext.off(TOPIC_WIDGETS, this._onWidgetsRef);
+        this._onMetricsRef = null;
+        this._onWidgetsRef = null;
         this._metricStore.clear();
         this._widgetManager.clear();
         this._presenceManager.clear();
         this.removeAllListeners();
     }
     _setPresence() {
-        this._roomContext.setPresence({ viewerId: this._localViewerId, username: this._options.username, metadata: this._options.metadata });
+        this._roomContext.setPresence({
+            viewerId: this._localViewerId,
+            username: this._options.username,
+            metadata: this._options.metadata,
+            // Scope tag: on a shared client, other apps' wrappers filter our
+            // presence out by this (and we filter theirs).
+            __scope: this._options.appName,
+        });
     }
 }
 
+/**
+ * NoLagDash — high-level live dashboard SDK built on @nolag/js-sdk.
+ *
+ * Provides multi-panel dashboards, real-time metric streams with
+ * aggregation, widget updates, viewer presence, and replay — 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 { NoLagDash } from '@nolag/dash';
+ *
+ * const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token);
+ * const dash = new NoLagDash({ client, appName: 'my-dash', username: 'Alice' });
+ *
+ * dash.on('viewerOnline', (v) => console.log(v.username, 'is watching'));
+ *
+ * await client.connect();   // the app owns the connection
+ * await dash.ready();       // wrapper setup done (identity, lobby, panels)
+ *
+ * const panel = dash.joinPanel('overview');
+ * panel.on('metric', (m) => console.log(m.streamId, m.value));
+ * panel.publishMetric('cpu', 75);
+ *
+ * dash.detach();            // wrapper releases its handlers and topics
+ * client.disconnect();      // the app closes the socket
+ * ```
+ */
 class NoLagDash extends EventEmitter {
-    constructor(token, options = {}) {
+    constructor(options) {
         super();
-        this._client = null;
+        this._localViewer = null;
         this._panels = new Map();
         this._lobby = null;
         this._onlineViewers = new Map();
         this._actorToViewerId = 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._onReplayStartRef = (data) => {
+            const event = data;
+            for (const panel of this._panels.values()) {
+                panel._handleReplayStart(event.count);
+            }
+        };
+        this._onReplayEndRef = (data) => {
+            const event = data;
+            for (const panel of this._panels.values()) {
+                panel._handleReplayEnd(event.replayed);
+            }
+        };
+        this._onPresenceJoinRef = (data) => this._handlePresenceJoin(data);
+        this._onPresenceLeaveRef = (data) => this._handlePresenceLeave(data);
+        this._onPresenceUpdateRef = (data) => this._handlePresenceUpdate(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('NoLagDash requires an injected NoLag client: new NoLagDash({ client, appName, ... })');
+        }
+        this._client = options.client;
         this._viewerId = generateId();
         this._options = {
-            username: options.username, metadata: options.metadata, appName: options.appName ?? DEFAULT_APP_NAME,
-            url: options.url, maxMetricPoints: options.maxMetricPoints ?? DEFAULT_MAX_METRIC_POINTS,
+            username: options.username,
+            metadata: options.metadata,
+            appName: options.appName ?? DEFAULT_APP_NAME,
+            maxMetricPoints: options.maxMetricPoints ?? DEFAULT_MAX_METRIC_POINTS,
             aggregationWindow: options.aggregationWindow ?? DEFAULT_AGGREGATION_WINDOW,
-            debug: options.debug ?? false, reconnect: options.reconnect ?? true, panels: options.panels ?? [],
+            debug: options.debug ?? false,
+            panels: options.panels ?? [],
         };
         this._log = createLogger('NoLagDash', 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, 'NoLagDash');
+        // 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('replay:start', this._onReplayStartRef);
+        this._client.on('replay:end', this._onReplayEndRef);
+        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();
+            }
+        });
     }
-    get connected() { return this._client?.connected ?? false; }
-    get panels() { return this._panels; }
-    async connect() {
-        const clientOptions = { debug: this._options.debug, reconnect: this._options.reconnect };
-        if (this._options.url)
-            clientOptions.url = this._options.url;
-        this._client = jsSdk.NoLag(this._token, clientOptions);
-        this._client.on('connect', () => { if (this._panels.size > 0) {
-            this._restorePanels();
-            this.emit('reconnected');
-        } });
-        this._client.on('disconnect', (reason) => this.emit('disconnected', reason));
-        this._client.on('error', (error) => this.emit('error', error));
-        this._client.on('replay:start', (data) => { for (const p of this._panels.values())
-            p._handleReplayStart(data.count); });
-        this._client.on('replay:end', (data) => { for (const p of this._panels.values())
-            p._handleReplayEnd(data.replayed); });
-        await this._client.connect();
-        this._client.on('presence:join', (data) => this._handlePresenceJoin(data));
-        this._client.on('presence:leave', (data) => this._handlePresenceLeave(data));
-        this._client.on('presence:update', (data) => this._handlePresenceUpdate(data));
-        await this._setupLobby();
-        for (const name of this._options.panels)
-            this._subscribePanel(name);
-        this.emit('connected');
-        setTimeout(() => { if (this._lobby && this._client?.connected)
-            this._lobby.fetchPresence().then(s => this._hydrateViewers(s)).catch(() => { }); }, 2000);
-    }
-    disconnect() {
-        for (const name of [...this._panels.keys()])
-            this.leavePanel(name);
-        this._lobby?.unsubscribe();
+    // ============ Public Properties ============
+    /** Whether the underlying connection is established (connected ≠ ready) */
+    get connected() {
+        return !this._detached && this._client.connected;
+    }
+    /** The injected core client (owned by the app, not the wrapper) */
+    get client() {
+        return this._client;
+    }
+    /** The local viewer's info (available after ready) */
+    get localViewer() {
+        return this._localViewer;
+    }
+    /** All currently joined panels */
+    get panels() {
+        return this._panels;
+    }
+    // ============ Lifecycle ============
+    /**
+     * Resolves once the wrapper's first setup completed (identity, lobby and
+     * configured panels 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.
+     */
+    ready() {
+        return this._readyPromise;
+    }
+    /**
+     * Detach from the client: remove every handler this wrapper added,
+     * unsubscribe its topics and lobby (when connected), clear state.
+     * Terminal and idempotent; never touches the socket. To use dash again,
+     * construct a new instance.
+     */
+    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('replay:start', this._onReplayStartRef);
+        this._client.off('replay:end', this._onReplayEndRef);
+        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);
+        // Panels: handler-specific off + connected-gated server unsubscribe
+        for (const name of [...this._panels.keys()]) {
+            this._panels.get(name)._cleanup();
+            this._panels.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 */
+            }
+        }
         this._lobby = null;
-        this._client?.disconnect();
-        this._client = null;
         this._onlineViewers.clear();
         this._actorToViewerId.clear();
+        this._localViewer = null;
+        releaseWrapper(this._client, this._options.appName);
+        if (!this._isReady) {
+            this._readyReject(new Error('NoLagDash 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._localViewer) {
+            this._localViewer = {
+                viewerId: this._viewerId,
+                actorTokenId: this._client.actorId,
+                username: this._options.username,
+                metadata: this._options.metadata,
+                joinedAt: Date.now(),
+                isLocal: true,
+            };
+            this._log('Local viewer:', this._localViewer.viewerId, '→', this._localViewer.actorTokenId);
+        }
+        else {
+            this._localViewer.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._diffHydrateOnlineViewers(state);
+            this._log('Lobby subscribed, online viewers:', this._onlineViewers.size);
+        }
+        catch (err) {
+            if (stale())
+                return;
+            this._log('Lobby subscription failed:', err);
+        }
+        if (!this._isReady) {
+            // First successful setup: pre-subscribe configured panels
+            for (const panelName of this._options.panels) {
+                this._subscribePanelInternal(panelName);
+            }
+        }
+        else {
+            // Server auto-restored topic subscriptions; only panel-scoped presence
+            // needs re-applying (the core does not restore it).
+            for (const panel of this._panels.values()) {
+                panel._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 viewers 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._diffHydrateOnlineViewers(state);
+            })
+                .catch(() => {
+                /* best-effort */
+            });
+        }, LOBBY_REFRESH_DELAY_MS);
+    }
+    // ============ Panel Management ============
+    /**
+     * Join a dashboard panel. If the panel was pre-subscribed via the `panels`
+     * option, activates it. Otherwise creates, subscribes, and activates it.
+     */
     joinPanel(name, opts) {
-        if (!this._client)
-            throw new Error('Not connected — call connect() first');
+        this._assertUsable();
         let panel = this._panels.get(name);
-        if (!panel)
-            panel = this._subscribePanel(name, opts?.metricFilters);
+        if (!panel) {
+            panel = this._subscribePanelInternal(name, opts?.metricFilters);
+        }
         panel._activate();
         return panel;
     }
+    /**
+     * Leave a dashboard panel. Fully unsubscribes and removes it.
+     */
     leavePanel(name) {
         const panel = this._panels.get(name);
         if (!panel)
             return;
+        this._log('Leaving panel:', name);
         panel._cleanup();
         this._panels.delete(name);
     }
-    _subscribePanel(name, metricFilters) {
-        if (!this._client)
-            throw new Error('Not connected');
+    /**
+     * Get all joined panels.
+     */
+    getPanels() {
+        return Array.from(this._panels.values());
+    }
+    // ============ Global Presence ============
+    /**
+     * Get all viewers currently online across all panels.
+     */
+    getOnlineViewers() {
+        return Array.from(this._onlineViewers.values());
+    }
+    // ============ Private: Guards ============
+    _assertUsable() {
+        if (this._detached) {
+            throw new Error('NoLagDash has been detached — construct a new instance');
+        }
+        if (!this._isReady || !this._localViewer) {
+            throw new Error('NoLagDash not ready — await ready() or the "connected" event');
+        }
+    }
+    // ============ Private: Panel Setup ============
+    _subscribePanelInternal(name, metricFilters) {
+        this._log('Subscribing panel:', name);
         const roomContext = this._client.setApp(this._options.appName).setRoom(name);
-        const panel = new DashboardPanel(name, roomContext, this._viewerId, this._client.actorId, this._options, createLogger(`DashPanel:${name}`, this._options.debug));
+        const panel = new DashboardPanel(name, roomContext, this._viewerId, this._client.actorId, this._options, createLogger(`DashPanel:${name}`, this._options.debug), () => this._client.connected);
         this._panels.set(name, panel);
         panel._subscribe(metricFilters);
         return panel;
     }
+    // ============ 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 → Panels ============
     _handlePresenceJoin(data) {
-        if (data.actorTokenId === this._client?.actorId)
+        if (data.actorTokenId === this._localViewer?.actorTokenId)
             return;
         const pd = data.presence;
-        if (!pd?.viewerId)
+        if (!pd?.viewerId || this._foreignScope(pd))
             return;
         const viewer = this._toViewer(data.actorTokenId, pd);
         this._actorToViewerId.set(data.actorTokenId, viewer.viewerId);
@@ -367,89 +701,137 @@ class NoLagDash extends EventEmitter {
             this._onlineViewers.set(viewer.viewerId, viewer);
             this.emit('viewerOnline', viewer);
         }
-        for (const p of this._panels.values())
-            p._handlePresenceJoin(data.actorTokenId, pd);
+        for (const panel of this._panels.values()) {
+            panel._handlePresenceJoin(data.actorTokenId, pd);
+        }
     }
     _handlePresenceLeave(data) {
-        if (data.actorTokenId === this._client?.actorId)
+        if (data.actorTokenId === this._localViewer?.actorTokenId)
             return;
-        for (const p of this._panels.values())
-            p._handlePresenceLeave(data.actorTokenId);
+        // Panel leave ≠ offline — viewer may still be on another panel.
+        // Lobby leave handles actual offline status.
+        for (const panel of this._panels.values()) {
+            panel._handlePresenceLeave(data.actorTokenId);
+        }
     }
     _handlePresenceUpdate(data) {
-        if (data.actorTokenId === this._client?.actorId)
+        if (data.actorTokenId === this._localViewer?.actorTokenId)
             return;
         const pd = data.presence;
-        if (!pd?.viewerId)
+        if (!pd?.viewerId || this._foreignScope(pd))
             return;
-        for (const p of this._panels.values())
-            p._handlePresenceUpdate(data.actorTokenId, pd);
+        for (const panel of this._panels.values()) {
+            panel._handlePresenceUpdate(data.actorTokenId, pd);
+        }
     }
-    async _setupLobby() {
-        if (!this._client)
+    // ============ Private: Lobby ============
+    _handleLobbyJoin(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localViewer?.actorTokenId)
             return;
-        this._lobby = this._client.setApp(this._options.appName).setLobby(LOBBY_ID);
-        const lh = (type) => (data) => {
-            const e = data;
-            if (type === 'join') {
-                const pd = e.data;
-                if (e.actorId !== this._client?.actorId && pd?.viewerId) {
-                    const v = this._toViewer(e.actorId, pd);
-                    this._actorToViewerId.set(e.actorId, v.viewerId);
-                    if (!this._onlineViewers.has(v.viewerId)) {
-                        this._onlineViewers.set(v.viewerId, v);
-                        this.emit('viewerOnline', v);
-                    }
-                }
-            }
-            else {
-                if (e.actorId !== this._client?.actorId) {
-                    const vid = this._actorToViewerId.get(e.actorId);
-                    if (vid) {
-                        const v = this._onlineViewers.get(vid);
-                        if (v) {
-                            this._onlineViewers.delete(vid);
-                            this._actorToViewerId.delete(e.actorId);
-                            this.emit('viewerOffline', v);
-                        }
-                    }
-                }
+        const pd = data;
+        if (!pd?.viewerId || this._foreignScope(pd))
+            return;
+        const viewer = this._toViewer(actorId, pd);
+        this._actorToViewerId.set(actorId, viewer.viewerId);
+        if (!this._onlineViewers.has(viewer.viewerId)) {
+            this._onlineViewers.set(viewer.viewerId, viewer);
+            this.emit('viewerOnline', viewer);
+        }
+    }
+    _handleLobbyLeave(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localViewer?.actorTokenId)
+            return;
+        const pd = data;
+        if (this._foreignScope(pd))
+            return;
+        const viewerId = pd?.viewerId
+            || this._actorToViewerId.get(actorId)
+            || this._findViewerIdByActorId(actorId);
+        if (viewerId) {
+            const viewer = this._onlineViewers.get(viewerId);
+            if (viewer) {
+                this._onlineViewers.delete(viewerId);
+                this._actorToViewerId.delete(actorId);
+                this.emit('viewerOffline', viewer);
             }
-        };
-        this._client.on('lobbyPresence:join', lh('join'));
-        this._client.on('lobbyPresence:leave', lh('leave'));
-        this._client.on('lobbyPresence:update', lh('join'));
-        try {
-            const s = await this._lobby.subscribe();
-            this._hydrateViewers(s);
         }
-        catch { }
     }
-    _hydrateViewers(state) {
-        for (const rid of Object.keys(state)) {
-            for (const aid of Object.keys(state[rid])) {
-                if (aid === this._client?.actorId)
+    _handleLobbyUpdate(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localViewer?.actorTokenId)
+            return;
+        const pd = data;
+        if (!pd?.viewerId || this._foreignScope(pd))
+            return;
+        const viewer = this._toViewer(actorId, pd);
+        this._onlineViewers.set(viewer.viewerId, viewer);
+    }
+    /**
+     * Reconcile the online-viewer map against a fresh lobby snapshot, emitting
+     * only the deltas (viewerOffline for vanished, viewerOnline for new). One
+     * path for initial hydration, reconnect restore, and the deferred refetch.
+     */
+    _diffHydrateOnlineViewers(state) {
+        // Build the fresh viewer 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._localViewer?.actorTokenId)
                     continue;
-                const raw = state[rid][aid];
+                const raw = roomPresence[actorId];
+                // Server returns full actor records with presence nested under .presence
                 const pd = (raw?.presence ?? raw);
-                if (pd?.viewerId) {
-                    const v = this._toViewer(aid, pd);
-                    this._actorToViewerId.set(aid, v.viewerId);
-                    if (!this._onlineViewers.has(v.viewerId)) {
-                        this._onlineViewers.set(v.viewerId, v);
-                        this.emit('viewerOnline', v);
+                if (pd?.viewerId && !this._foreignScope(pd)) {
+                    if (!fresh.has(pd.viewerId)) {
+                        fresh.set(pd.viewerId, this._toViewer(actorId, pd));
                     }
+                    freshActors.set(actorId, pd.viewerId);
+                }
+            }
+        }
+        // Vanished viewers
+        for (const [viewerId, viewer] of [...this._onlineViewers]) {
+            if (!fresh.has(viewerId)) {
+                this._onlineViewers.delete(viewerId);
+                for (const [actorId, mappedViewerId] of [...this._actorToViewerId]) {
+                    if (mappedViewerId === viewerId)
+                        this._actorToViewerId.delete(actorId);
                 }
+                this.emit('viewerOffline', viewer);
             }
         }
+        // New viewers
+        for (const [viewerId, viewer] of fresh) {
+            if (!this._onlineViewers.has(viewerId)) {
+                this._onlineViewers.set(viewerId, viewer);
+                this.emit('viewerOnline', viewer);
+            }
+        }
+        for (const [actorId, viewerId] of freshActors) {
+            this._actorToViewerId.set(actorId, viewerId);
+        }
     }
+    // ============ Private: Helpers ============
     _toViewer(actorTokenId, data) {
-        return { viewerId: data.viewerId, actorTokenId, username: data.username, metadata: data.metadata, joinedAt: Date.now(), isLocal: false };
+        return {
+            viewerId: data.viewerId,
+            actorTokenId,
+            username: data.username,
+            metadata: data.metadata,
+            joinedAt: Date.now(),
+            isLocal: false,
+        };
     }
-    _restorePanels() {
-        for (const p of this._panels.values())
-            p._updateLocalPresence();
-        this._lobby?.fetchPresence().then(s => { this._onlineViewers.clear(); this._actorToViewerId.clear(); this._hydrateViewers(s); }).catch(() => { });
+    _findViewerIdByActorId(actorTokenId) {
+        for (const viewer of this._onlineViewers.values()) {
+            if (viewer.actorTokenId === actorTokenId)
+                return viewer.viewerId;
+        }
+        return undefined;
     }
 }