@nolag/collab 0.1.0

package/dist/index.cjs

@@ -0,0 +1,984 @@
+'use strict';
+
+var jsSdk = require('@nolag/js-sdk');
+
+/**
+ * Tiny typed event emitter — framework-agnostic base for NoLag SDKs.
+ *
+ * EventMap is a record of event name → tuple of handler arguments.
+ */
+class EventEmitter {
+    constructor() {
+        this._handlers = new Map();
+    }
+    on(event, handler) {
+        if (!this._handlers.has(event)) {
+            this._handlers.set(event, new Set());
+        }
+        this._handlers.get(event).add(handler);
+        return this;
+    }
+    off(event, handler) {
+        if (handler) {
+            this._handlers.get(event)?.delete(handler);
+        }
+        else {
+            this._handlers.delete(event);
+        }
+        return this;
+    }
+    removeAllListeners() {
+        this._handlers.clear();
+        return this;
+    }
+    emit(event, ...args) {
+        const handlers = this._handlers.get(event);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(...args);
+            }
+            catch (e) {
+                console.error(`Error in ${String(event)} handler:`, e);
+            }
+        }
+    }
+    listenerCount(event) {
+        return this._handlers.get(event)?.size ?? 0;
+    }
+}
+
+/**
+ * PresenceManager — maps actorTokenId ↔ CollabUser, filtering self.
+ */
+class PresenceManager {
+    constructor(localActorId) {
+        this._users = new Map();
+        this._actorToUserId = new Map();
+        this._localActorId = localActorId;
+    }
+    /**
+     * Add or update a user from presence data.
+     * Returns the CollabUser if it is a remote user, null if it is self.
+     */
+    addFromPresence(actorTokenId, presence, joinedAt) {
+        const isLocal = actorTokenId === this._localActorId;
+        // Skip self
+        if (isLocal)
+            return null;
+        const existing = this._actorToUserId.get(actorTokenId);
+        const userId = presence.userId || existing || actorTokenId;
+        const user = {
+            userId,
+            actorTokenId,
+            username: presence.username,
+            avatar: presence.avatar,
+            color: presence.color,
+            status: presence.status ?? 'active',
+            metadata: presence.metadata,
+            joinedAt: joinedAt ?? Date.now(),
+            isLocal: false,
+        };
+        this._users.set(userId, user);
+        this._actorToUserId.set(actorTokenId, userId);
+        return user;
+    }
+    /**
+     * Remove a user by actorTokenId.
+     * Returns the removed CollabUser, or null if not found / is self.
+     */
+    removeByActorId(actorTokenId) {
+        if (actorTokenId === this._localActorId)
+            return null;
+        const userId = this._actorToUserId.get(actorTokenId);
+        if (!userId)
+            return null;
+        const user = this._users.get(userId) ?? null;
+        this._users.delete(userId);
+        this._actorToUserId.delete(actorTokenId);
+        return user;
+    }
+    /**
+     * Update only the status field for an existing user.
+     */
+    updateStatus(actorTokenId, status) {
+        const userId = this._actorToUserId.get(actorTokenId);
+        if (!userId)
+            return null;
+        const user = this._users.get(userId);
+        if (!user)
+            return null;
+        const updated = { ...user, status };
+        this._users.set(userId, updated);
+        return updated;
+    }
+    /**
+     * Get a user by userId.
+     */
+    getUser(userId) {
+        return this._users.get(userId);
+    }
+    /**
+     * Get a user by actorTokenId.
+     */
+    getUserByActorId(actorTokenId) {
+        const userId = this._actorToUserId.get(actorTokenId);
+        return userId ? this._users.get(userId) : undefined;
+    }
+    /**
+     * Get all remote users.
+     */
+    getAll() {
+        return Array.from(this._users.values());
+    }
+    /**
+     * Get the users Map (readonly view).
+     */
+    get users() {
+        return this._users;
+    }
+    /**
+     * Clear all tracked users.
+     */
+    clear() {
+        this._users.clear();
+        this._actorToUserId.clear();
+    }
+}
+
+/**
+ * Ordered, deduplicated operation log bounded by maxOperationCache.
+ *
+ * Operations are stored sorted by timestamp ascending. Duplicate IDs are
+ * silently ignored. When the cache exceeds its limit the oldest entries
+ * are evicted.
+ */
+class OperationStore {
+    constructor(maxSize) {
+        this._ops = [];
+        this._ids = new Set();
+        this._maxSize = maxSize;
+    }
+    /**
+     * Add an operation to the store.
+     * Returns true if the operation was added, false if it was a duplicate.
+     */
+    add(op) {
+        if (this._ids.has(op.id))
+            return false;
+        this._ids.add(op.id);
+        this._ops.push(op);
+        // Keep sorted by timestamp ascending
+        this._ops.sort((a, b) => a.timestamp - b.timestamp);
+        // Evict oldest entries when over capacity
+        while (this._ops.length > this._maxSize) {
+            const evicted = this._ops.shift();
+            if (evicted)
+                this._ids.delete(evicted.id);
+        }
+        return true;
+    }
+    /**
+     * Get all stored operations in timestamp order.
+     */
+    getAll() {
+        return [...this._ops];
+    }
+    /**
+     * Get all operations sent by a specific user.
+     */
+    getByUser(userId) {
+        return this._ops.filter((op) => op.userId === userId);
+    }
+    /**
+     * Check whether an operation ID is already stored.
+     */
+    has(id) {
+        return this._ids.has(id);
+    }
+    /**
+     * Number of operations currently stored.
+     */
+    get size() {
+        return this._ops.length;
+    }
+    /**
+     * Clear all stored operations.
+     */
+    clear() {
+        this._ops = [];
+        this._ids.clear();
+    }
+}
+
+/**
+ * AwarenessManager — cursor tracking and idle detection per user.
+ *
+ * Tracks cursor positions for all connected users and manages per-user
+ * idle timers that fire a callback when a user has been inactive.
+ */
+class AwarenessManager {
+    constructor(localUserId) {
+        this._cursors = new Map();
+        this._statuses = new Map();
+        this._idleTimers = new Map();
+        this._localUserId = localUserId;
+    }
+    /**
+     * Update the cursor position for a user and reset their idle timer.
+     */
+    updateCursor(userId, position) {
+        this._cursors.set(userId, position);
+        // Reset idle timer if one is running for this user
+        if (this._idleTimers.has(userId)) {
+            const timer = this._idleTimers.get(userId);
+            clearTimeout(timer);
+            this._idleTimers.delete(userId);
+        }
+    }
+    /**
+     * Get the last known cursor position for a user.
+     */
+    getCursor(userId) {
+        return this._cursors.get(userId);
+    }
+    /**
+     * Get all cursor positions except the local user's.
+     */
+    getCursors() {
+        return Array.from(this._cursors.values()).filter((c) => c.userId !== this._localUserId);
+    }
+    /**
+     * Set the activity status for a user.
+     */
+    setStatus(userId, status) {
+        this._statuses.set(userId, status);
+    }
+    /**
+     * Get the current activity status for a user (defaults to 'active').
+     */
+    getStatus(userId) {
+        return this._statuses.get(userId) ?? 'active';
+    }
+    /**
+     * Start an idle timer for a user. If the timer fires, onIdle is called
+     * and the user's status is set to 'idle'. Calling updateCursor resets it.
+     */
+    startIdleTracking(userId, timeout, onIdle) {
+        // Cancel any existing timer
+        this.stopIdleTracking(userId);
+        const timer = setTimeout(() => {
+            this._idleTimers.delete(userId);
+            this._statuses.set(userId, 'idle');
+            onIdle();
+        }, timeout);
+        this._idleTimers.set(userId, timer);
+    }
+    /**
+     * Cancel the idle timer for a user without firing the callback.
+     */
+    stopIdleTracking(userId) {
+        const timer = this._idleTimers.get(userId);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this._idleTimers.delete(userId);
+        }
+    }
+    /**
+     * Remove all cursor data for a user.
+     */
+    removeCursor(userId) {
+        this._cursors.delete(userId);
+        this._statuses.delete(userId);
+        this.stopIdleTracking(userId);
+    }
+    /**
+     * Dispose — clear all timers and state.
+     */
+    dispose() {
+        for (const timer of this._idleTimers.values()) {
+            clearTimeout(timer);
+        }
+        this._idleTimers.clear();
+        this._cursors.clear();
+        this._statuses.clear();
+    }
+}
+
+function generateId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxx-xxxx-xxxx-xxxx'.replace(/x/g, () => Math.floor(Math.random() * 16).toString(16));
+}
+function createLogger(prefix, enabled) {
+    if (!enabled) {
+        return (..._args) => { };
+    }
+    return (...args) => {
+        console.log(`[${prefix}]`, ...args);
+    };
+}
+
+/** Default app name for NoLag collab SDK */
+const DEFAULT_APP_NAME = 'collab';
+/** Maximum number of operations to keep in the cache */
+const DEFAULT_MAX_OPERATION_CACHE = 1000;
+/** Idle timeout in milliseconds before a user is marked idle */
+const DEFAULT_IDLE_TIMEOUT = 60000;
+/** Cursor throttle in milliseconds — minimum interval between cursor updates */
+const DEFAULT_CURSOR_THROTTLE = 50;
+/** Topic name for operation messages within a document */
+const TOPIC_OPERATIONS = 'operations';
+/** Topic name for cursor presence messages within a document */
+const TOPIC_CURSORS = '_cursors';
+/** Lobby ID for global online presence */
+const LOBBY_ID = 'online';
+
+/**
+ * CollabDocument — a single collaborative document room.
+ *
+ * Created via `NoLagCollab.joinDocument(name)`. Do not instantiate directly.
+ *
+ * Subscribes to 'operations' and '_cursors' topics and exposes a clean API
+ * for sending operations, broadcasting cursor positions, and managing
+ * user awareness (idle detection, status).
+ */
+class CollabDocument extends EventEmitter {
+    /** @internal */
+    constructor(name, roomContext, localUser, options, log) {
+        super();
+        /** Throttle state for cursor updates */
+        this._cursorThrottleTimer = null;
+        this._pendingCursorUpdate = null;
+        this.name = name;
+        this._roomContext = roomContext;
+        this._localUser = localUser;
+        this._options = options;
+        this._log = log;
+        this._presenceManager = new PresenceManager(localUser.actorTokenId);
+        this._operationStore = new OperationStore(options.maxOperationCache);
+        this._awarenessManager = new AwarenessManager(localUser.userId);
+    }
+    // ============ Public Properties ============
+    /** All remote users currently in this document */
+    get users() {
+        return this._presenceManager.users;
+    }
+    // ============ Operations ============
+    /**
+     * Send an operation to all collaborators in this document.
+     * Returns the operation that was created and broadcast.
+     */
+    sendOperation(type, opts = {}) {
+        const op = {
+            id: generateId(),
+            type,
+            path: opts.path,
+            position: opts.position,
+            length: opts.length,
+            content: opts.content,
+            data: opts.data,
+            userId: this._localUser.userId,
+            username: this._localUser.username,
+            timestamp: Date.now(),
+            isReplay: false,
+        };
+        this._log('Sending operation:', type, op.id);
+        this._operationStore.add(op);
+        this._roomContext.emit(TOPIC_OPERATIONS, op, { echo: false });
+        return op;
+    }
+    /**
+     * Get all cached operations for this document, in timestamp order.
+     */
+    getOperations() {
+        return this._operationStore.getAll();
+    }
+    // ============ Cursors ============
+    /**
+     * Broadcast a cursor position update. Calls are throttled by the
+     * cursorThrottle option (default 50 ms) to avoid flooding.
+     */
+    updateCursor(opts) {
+        this._pendingCursorUpdate = opts;
+        if (this._cursorThrottleTimer !== null) {
+            // Already scheduled — the pending update will be sent when it fires
+            return;
+        }
+        // Send immediately for the first call in the window, then throttle
+        this._flushCursorUpdate();
+        this._cursorThrottleTimer = setTimeout(() => {
+            this._cursorThrottleTimer = null;
+            if (this._pendingCursorUpdate) {
+                this._flushCursorUpdate();
+            }
+        }, this._options.cursorThrottle);
+    }
+    /**
+     * Get all remote cursor positions.
+     */
+    getCursors() {
+        return this._awarenessManager.getCursors();
+    }
+    // ============ Awareness ============
+    /**
+     * Update the local user's activity status and broadcast it.
+     */
+    setStatus(status) {
+        this._localUser = { ...this._localUser, status };
+        this._setPresence();
+        this._log('Status updated:', status);
+    }
+    // ============ Users ============
+    /**
+     * Get all remote users currently in the document.
+     */
+    getUsers() {
+        return this._presenceManager.getAll();
+    }
+    /**
+     * Get a specific user by userId.
+     */
+    getUser(userId) {
+        return this._presenceManager.getUser(userId);
+    }
+    // ============ Internal (called by NoLagCollab) ============
+    /** @internal Subscribe to operations and cursors topics and attach listeners */
+    _subscribe() {
+        this._log('Document subscribe:', this.name);
+        this._roomContext.subscribe(TOPIC_OPERATIONS);
+        this._roomContext.subscribe(TOPIC_CURSORS);
+        this._roomContext.on(TOPIC_OPERATIONS, (data) => {
+            this._handleIncomingOperation(data);
+        });
+        this._roomContext.on(TOPIC_CURSORS, (data) => {
+            this._handleIncomingCursor(data);
+        });
+    }
+    /** @internal Set presence and fetch current room members */
+    _activate() {
+        this._log('Document activate:', this.name);
+        this._setPresence();
+        this._roomContext.fetchPresence().then((actors) => {
+            this._log('Document presence fetched:', this.name, actors.length, 'actors');
+            for (const actor of actors) {
+                if (actor.presence) {
+                    const user = this._presenceManager.addFromPresence(actor.actorTokenId, actor.presence, actor.joinedAt);
+                    if (user) {
+                        this._awarenessManager.setStatus(user.userId, user.status);
+                        this.emit('userJoined', user);
+                    }
+                }
+            }
+        }).catch((err) => {
+            this._log('Failed to fetch document presence:', err);
+        });
+    }
+    /** @internal Re-set presence after reconnect */
+    _updateLocalPresence() {
+        this._setPresence();
+    }
+    /** @internal Handle a presence:join event */
+    _handlePresenceJoin(actorTokenId, presenceData) {
+        const user = this._presenceManager.addFromPresence(actorTokenId, presenceData);
+        if (user) {
+            this._log('User joined document:', this.name, user.userId);
+            this._awarenessManager.setStatus(user.userId, user.status);
+            this._startUserIdleTracking(user);
+            this.emit('userJoined', user);
+        }
+    }
+    /** @internal Handle a presence:leave event */
+    _handlePresenceLeave(actorTokenId) {
+        const user = this._presenceManager.removeByActorId(actorTokenId);
+        if (user) {
+            this._log('User left document:', this.name, user.userId);
+            this._awarenessManager.removeCursor(user.userId);
+            this.emit('userLeft', user);
+        }
+    }
+    /** @internal Handle a presence:update event */
+    _handlePresenceUpdate(actorTokenId, presenceData) {
+        const user = this._presenceManager.addFromPresence(actorTokenId, presenceData);
+        if (user) {
+            this._awarenessManager.setStatus(user.userId, user.status);
+        }
+    }
+    /** @internal Replay operations from another source (e.g. history fetch) */
+    _replayOperations(ops) {
+        const pending = ops.filter((op) => !this._operationStore.has(op.id));
+        if (pending.length === 0)
+            return;
+        this._log('Replaying', pending.length, 'operations');
+        this.emit('replayStart', { count: pending.length });
+        let replayed = 0;
+        for (const op of pending) {
+            const replayOp = { ...op, isReplay: true };
+            if (this._operationStore.add(replayOp)) {
+                this.emit('operation', replayOp);
+                replayed++;
+            }
+        }
+        this.emit('replayEnd', { replayed });
+    }
+    /** @internal Unsubscribe and clean up */
+    _cleanup() {
+        this._log('Document cleanup:', this.name);
+        // Cancel throttle timer
+        if (this._cursorThrottleTimer !== null) {
+            clearTimeout(this._cursorThrottleTimer);
+            this._cursorThrottleTimer = null;
+        }
+        this._roomContext.unsubscribe(TOPIC_OPERATIONS);
+        this._roomContext.unsubscribe(TOPIC_CURSORS);
+        this._roomContext.off(TOPIC_OPERATIONS);
+        this._roomContext.off(TOPIC_CURSORS);
+        this._awarenessManager.dispose();
+        this._presenceManager.clear();
+        this._operationStore.clear();
+        this.removeAllListeners();
+    }
+    // ============ Private ============
+    _handleIncomingOperation(data) {
+        const op = data;
+        // Deduplicate
+        if (this._operationStore.has(op.id))
+            return;
+        const stored = { ...op, isReplay: false };
+        this._operationStore.add(stored);
+        this._log('Received operation:', op.type, op.id, 'from', op.userId);
+        this.emit('operation', stored);
+    }
+    _handleIncomingCursor(data) {
+        const cursor = data;
+        // Ignore own cursor echoes (should not happen with echo: false, but guard anyway)
+        if (cursor.userId === this._localUser.userId)
+            return;
+        this._awarenessManager.updateCursor(cursor.userId, cursor);
+        // Reset idle tracking for this user
+        const user = this._presenceManager.getUser(cursor.userId);
+        if (user) {
+            this._startUserIdleTracking(user);
+        }
+        this._log('Cursor moved:', cursor.userId);
+        this.emit('cursorMoved', cursor);
+    }
+    _flushCursorUpdate() {
+        if (!this._pendingCursorUpdate)
+            return;
+        const opts = this._pendingCursorUpdate;
+        this._pendingCursorUpdate = null;
+        const cursor = {
+            userId: this._localUser.userId,
+            username: this._localUser.username,
+            color: this._localUser.color,
+            timestamp: Date.now(),
+            ...opts,
+        };
+        this._awarenessManager.updateCursor(this._localUser.userId, cursor);
+        this._roomContext.emit(TOPIC_CURSORS, cursor, { echo: false });
+    }
+    _setPresence() {
+        const presenceData = {
+            userId: this._localUser.userId,
+            username: this._localUser.username,
+            avatar: this._localUser.avatar,
+            color: this._localUser.color,
+            status: this._localUser.status,
+            metadata: this._localUser.metadata,
+        };
+        this._roomContext.setPresence(presenceData);
+    }
+    _startUserIdleTracking(user) {
+        // Mark user as active first
+        if (this._awarenessManager.getStatus(user.userId) !== 'active') {
+            this._awarenessManager.setStatus(user.userId, 'active');
+        }
+        this._awarenessManager.startIdleTracking(user.userId, this._options.idleTimeout, () => {
+            this._log('User went idle:', user.userId);
+            this.emit('awarenessChanged', { userId: user.userId, status: 'idle' });
+        });
+    }
+}
+
+/**
+ * NoLagCollab — high-level real-time collaboration SDK built on @nolag/js-sdk.
+ *
+ * Provides document-scoped operations, cursor broadcasting, and user awareness
+ * (idle detection, status tracking) — all framework-agnostic via events.
+ *
+ * @example
+ * ```typescript
+ * import { NoLagCollab } from '@nolag/collab';
+ *
+ * const collab = new NoLagCollab(token, { username: 'Alice', debug: true });
+ *
+ * collab.on('connected', () => console.log('Connected!'));
+ * collab.on('userOnline', (user) => console.log(user.username, 'is online'));
+ *
+ * await collab.connect();
+ *
+ * const doc = collab.joinDocument('my-doc');
+ * doc.on('operation', (op) => applyOp(op));
+ * doc.sendOperation('insert', { position: 0, content: 'Hello' });
+ * ```
+ */
+class NoLagCollab extends EventEmitter {
+    constructor(token, options) {
+        super();
+        this._client = null;
+        this._localUser = null;
+        this._documents = new Map();
+        this._lobby = null;
+        this._onlineUsers = new Map();
+        this._actorToUserId = new Map();
+        this._token = token;
+        this._userId = generateId();
+        this._options = {
+            username: options.username,
+            avatar: options.avatar,
+            color: options.color,
+            metadata: options.metadata,
+            appName: options.appName ?? DEFAULT_APP_NAME,
+            url: options.url,
+            maxOperationCache: options.maxOperationCache ?? DEFAULT_MAX_OPERATION_CACHE,
+            idleTimeout: options.idleTimeout ?? DEFAULT_IDLE_TIMEOUT,
+            cursorThrottle: options.cursorThrottle ?? DEFAULT_CURSOR_THROTTLE,
+            debug: options.debug ?? false,
+            reconnect: options.reconnect ?? true,
+            documents: options.documents ?? [],
+        };
+        this._log = createLogger('NoLagCollab', this._options.debug);
+    }
+    // ============ Public Properties ============
+    /** Whether the underlying connection is established */
+    get connected() {
+        return this._client?.connected ?? false;
+    }
+    /** The local user's info (available after connect) */
+    get localUser() {
+        return this._localUser;
+    }
+    /** All currently joined documents */
+    get documents() {
+        return this._documents;
+    }
+    // ============ Lifecycle ============
+    /**
+     * Connect to NoLag and set up global presence.
+     */
+    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 = jsSdk.NoLag(this._token, clientOptions);
+        // Wire client lifecycle events
+        this._client.on('connect', () => {
+            this._log('Connected');
+            if (this._documents.size > 0) {
+                this._log('Reconnected — restoring documents...');
+                this._restoreDocuments();
+                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 user
+        this._localUser = {
+            userId: this._userId,
+            actorTokenId: this._client.actorId,
+            username: this._options.username,
+            avatar: this._options.avatar,
+            color: this._options.color,
+            status: 'active',
+            metadata: this._options.metadata,
+            joinedAt: Date.now(),
+            isLocal: true,
+        };
+        this._log('Local user:', this._localUser.userId, '→', this._localUser.actorTokenId);
+        // Set up lobby for global presence
+        await this._setupLobby();
+        // Emit connected now that _localUser and lobby are ready
+        this.emit('connected');
+        // Auto-join documents specified in options
+        for (const docName of this._options.documents) {
+            this.joinDocument(docName);
+        }
+        // Deferred lobby refetch to catch users who joined during the setup window
+        setTimeout(() => {
+            if (this._lobby && this._client?.connected) {
+                this._lobby.fetchPresence().then((state) => {
+                    this._hydrateOnlineUsers(state);
+                }).catch(() => { });
+            }
+        }, 2000);
+    }
+    /**
+     * Disconnect from NoLag and clean up all documents.
+     */
+    disconnect() {
+        this._log('Disconnecting...');
+        // Clean up documents
+        for (const name of [...this._documents.keys()]) {
+            this.leaveDocument(name);
+        }
+        // Unsubscribe from lobby
+        this._lobby?.unsubscribe();
+        this._lobby = null;
+        // Disconnect client
+        this._client?.disconnect();
+        this._client = null;
+        // Clear state
+        this._onlineUsers.clear();
+        this._actorToUserId.clear();
+        this._localUser = null;
+    }
+    // ============ Document Management ============
+    /**
+     * Join a collaborative document. Creates, subscribes, and activates it.
+     * Returns an existing document if already joined.
+     */
+    joinDocument(name) {
+        if (!this._client || !this._localUser) {
+            throw new Error('Not connected — call connect() first');
+        }
+        let doc = this._documents.get(name);
+        if (!doc) {
+            doc = this._subscribeDocument(name);
+            doc._activate();
+        }
+        return doc;
+    }
+    /**
+     * Leave a collaborative document. Fully unsubscribes and removes it.
+     */
+    leaveDocument(name) {
+        const doc = this._documents.get(name);
+        if (!doc)
+            return;
+        this._log('Leaving document:', name);
+        doc._cleanup();
+        this._documents.delete(name);
+    }
+    /**
+     * Get all joined documents.
+     */
+    getDocuments() {
+        return Array.from(this._documents.values());
+    }
+    // ============ Global Presence ============
+    /**
+     * Get all users currently online across all documents.
+     */
+    getOnlineUsers() {
+        return Array.from(this._onlineUsers.values());
+    }
+    // ============ Private: Document Setup ============
+    _subscribeDocument(name) {
+        if (!this._client || !this._localUser) {
+            throw new Error('Not connected — call connect() first');
+        }
+        this._log('Subscribing document:', name);
+        const roomContext = this._client.setApp(this._options.appName).setRoom(name);
+        const doc = new CollabDocument(name, roomContext, this._localUser, this._options, createLogger(`CollabDocument:${name}`, this._options.debug));
+        this._documents.set(name, doc);
+        doc._subscribe();
+        return doc;
+    }
+    // ============ Private: Room Presence ============
+    _handleRoomPresenceJoin(data) {
+        if (data.actorTokenId === this._localUser?.actorTokenId)
+            return;
+        const presenceData = data.presence;
+        if (!presenceData?.userId)
+            return;
+        const user = this._presenceToUser(data.actorTokenId, presenceData);
+        this._actorToUserId.set(data.actorTokenId, user.userId);
+        if (!this._onlineUsers.has(user.userId)) {
+            this._onlineUsers.set(user.userId, user);
+            this.emit('userOnline', user);
+        }
+        // Route to all documents
+        for (const doc of this._documents.values()) {
+            doc._handlePresenceJoin(data.actorTokenId, presenceData);
+        }
+    }
+    _handleRoomPresenceLeave(data) {
+        if (data.actorTokenId === this._localUser?.actorTokenId)
+            return;
+        // Route to all documents
+        for (const doc of this._documents.values()) {
+            doc._handlePresenceLeave(data.actorTokenId);
+        }
+    }
+    _handleRoomPresenceUpdate(data) {
+        if (data.actorTokenId === this._localUser?.actorTokenId)
+            return;
+        const presenceData = data.presence;
+        if (!presenceData?.userId)
+            return;
+        if (this._onlineUsers.has(presenceData.userId)) {
+            const user = this._presenceToUser(data.actorTokenId, presenceData);
+            this._onlineUsers.set(user.userId, user);
+        }
+        // Route to all documents
+        for (const doc of this._documents.values()) {
+            doc._handlePresenceUpdate(data.actorTokenId, presenceData);
+        }
+    }
+    // ============ 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._hydrateOnlineUsers(initialState);
+            this._log('Lobby subscribed, online users:', this._onlineUsers.size);
+        }
+        catch (err) {
+            this._log('Lobby subscription failed:', err);
+        }
+    }
+    _handleLobbyJoin(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localUser?.actorTokenId)
+            return;
+        const presenceData = data;
+        if (!presenceData.userId)
+            return;
+        const user = this._presenceToUser(actorId, presenceData);
+        this._actorToUserId.set(actorId, user.userId);
+        if (!this._onlineUsers.has(user.userId)) {
+            this._onlineUsers.set(user.userId, user);
+            this.emit('userOnline', user);
+        }
+    }
+    _handleLobbyLeave(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localUser?.actorTokenId)
+            return;
+        const presenceData = data;
+        const userId = presenceData?.userId
+            || this._actorToUserId.get(actorId)
+            || this._findUserIdByActorId(actorId);
+        if (userId) {
+            const user = this._onlineUsers.get(userId);
+            if (user) {
+                this._onlineUsers.delete(userId);
+                this._actorToUserId.delete(actorId);
+                this.emit('userOffline', user);
+            }
+        }
+    }
+    _handleLobbyUpdate(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localUser?.actorTokenId)
+            return;
+        const presenceData = data;
+        if (!presenceData.userId)
+            return;
+        const user = this._presenceToUser(actorId, presenceData);
+        this._onlineUsers.set(user.userId, user);
+    }
+    _hydrateOnlineUsers(state) {
+        for (const roomId of Object.keys(state)) {
+            const roomPresence = state[roomId];
+            for (const actorId of Object.keys(roomPresence)) {
+                if (actorId === this._localUser?.actorTokenId)
+                    continue;
+                const raw = roomPresence[actorId];
+                const presenceData = (raw?.presence ?? raw);
+                if (presenceData?.userId) {
+                    const user = this._presenceToUser(actorId, presenceData);
+                    this._actorToUserId.set(actorId, user.userId);
+                    if (!this._onlineUsers.has(user.userId)) {
+                        this._onlineUsers.set(user.userId, user);
+                        this.emit('userOnline', user);
+                    }
+                }
+            }
+        }
+    }
+    // ============ Private: Helpers ============
+    _presenceToUser(actorTokenId, data) {
+        return {
+            userId: data.userId,
+            actorTokenId,
+            username: data.username,
+            avatar: data.avatar,
+            color: data.color,
+            status: data.status ?? 'active',
+            metadata: data.metadata,
+            joinedAt: Date.now(),
+            isLocal: false,
+        };
+    }
+    _findUserIdByActorId(actorTokenId) {
+        for (const user of this._onlineUsers.values()) {
+            if (user.actorTokenId === actorTokenId)
+                return user.userId;
+        }
+        return undefined;
+    }
+    _restoreDocuments() {
+        // On reconnect, js-sdk auto-restores subscriptions.
+        // Re-set presence on all active documents.
+        for (const doc of this._documents.values()) {
+            doc._updateLocalPresence();
+        }
+        // Re-fetch lobby presence
+        this._lobby?.fetchPresence().then((state) => {
+            this._onlineUsers.clear();
+            this._actorToUserId.clear();
+            this._hydrateOnlineUsers(state);
+        }).catch((err) => {
+            this._log('Failed to re-fetch lobby presence:', err);
+        });
+    }
+}
+
+exports.CollabDocument = CollabDocument;
+exports.EventEmitter = EventEmitter;
+exports.NoLagCollab = NoLagCollab;
+//# sourceMappingURL=index.cjs.map