@prabhask5/stellar-engine 1.1.18 → 1.2.0

package/dist/crdt/awareness.js

@@ -0,0 +1,284 @@
+/**
+ * @fileoverview CRDT Presence / Awareness Management
+ *
+ * Bridges Supabase Presence ↔ local presence state for collaborative cursor
+ * and user tracking. Each open document has its own set of collaborators.
+ *
+ * Responsibilities:
+ *   - Tracking local cursor/selection state per document
+ *   - Debouncing cursor updates to avoid flooding the Presence channel
+ *   - Maintaining a list of active collaborators per document
+ *   - Providing subscription-based notifications for collaborator changes
+ *   - Deterministic color assignment from userId hash
+ *
+ * The Supabase Presence integration is handled through the same Realtime
+ * channel used for Broadcast. Presence state is tracked separately from
+ * Yjs document updates — they use different Supabase Realtime features
+ * (Presence vs Broadcast) on the same channel.
+ *
+ * @see {@link ./types.ts} for {@link UserPresenceState}
+ * @see {@link ./channel.ts} for the underlying Broadcast channel
+ * @see {@link ./provider.ts} for the lifecycle orchestrator
+ */
+import { getDeviceId } from '../deviceId';
+import { debugLog } from '../debug';
+import { getCRDTConfig } from './config';
+// =============================================================================
+//  Color Palette
+// =============================================================================
+/**
+ * 12-color palette for deterministic collaborator color assignment.
+ *
+ * Colors are chosen for good contrast on both light and dark backgrounds,
+ * and to be distinguishable from each other even at small sizes (cursor lines,
+ * selection highlights).
+ */
+const COLLABORATOR_COLORS = [
+    '#E57373', // Red
+    '#81C784', // Green
+    '#64B5F6', // Blue
+    '#FFD54F', // Amber
+    '#BA68C8', // Purple
+    '#4DB6AC', // Teal
+    '#FF8A65', // Deep Orange
+    '#A1887F', // Brown
+    '#90A4AE', // Blue Grey
+    '#F06292', // Pink
+    '#AED581', // Light Green
+    '#4FC3F7' // Light Blue
+];
+// =============================================================================
+//  Module State
+// =============================================================================
+/** Active collaborators per document. */
+const collaboratorsByDocument = new Map();
+/** Change listeners per document. */
+const changeListeners = new Map();
+/** Last cursor update timestamp per document (for debouncing). */
+const lastCursorUpdate = new Map();
+// =============================================================================
+//  Color Assignment
+// =============================================================================
+/**
+ * Assign a deterministic color to a user based on their userId.
+ *
+ * Uses a simple hash of the userId to index into the 12-color palette.
+ * The same userId always gets the same color, so collaborators appear
+ * consistent across sessions and devices.
+ *
+ * @param userId - The user's UUID.
+ * @returns A hex color string from the palette.
+ */
+export function assignColor(userId) {
+    let hash = 0;
+    for (let i = 0; i < userId.length; i++) {
+        hash = ((hash << 5) - hash + userId.charCodeAt(i)) | 0;
+    }
+    return COLLABORATOR_COLORS[Math.abs(hash) % COLLABORATOR_COLORS.length];
+}
+// =============================================================================
+//  Internal Lifecycle (called by provider.ts)
+// =============================================================================
+/**
+ * Initialize presence tracking for a document.
+ *
+ * Called by the provider when a document is opened. Sets up the collaborator
+ * map and announces the local user's presence.
+ *
+ * @param documentId - The document to join.
+ * @param isConnected - Whether the Broadcast channel is connected.
+ * @param initialPresence - The local user's initial presence info.
+ * @internal
+ */
+export function joinPresence(documentId, isConnected, initialPresence) {
+    if (!collaboratorsByDocument.has(documentId)) {
+        collaboratorsByDocument.set(documentId, new Map());
+    }
+    if (isConnected) {
+        debugLog(`[CRDT] Document ${documentId}: announcing presence (name=${initialPresence.name})`);
+    }
+}
+/**
+ * Leave presence tracking for a document.
+ *
+ * Called by the provider when a document is closed. Cleans up the collaborator
+ * map and notifies listeners.
+ *
+ * @param documentId - The document to leave.
+ * @internal
+ */
+export function leavePresence(documentId) {
+    collaboratorsByDocument.delete(documentId);
+    lastCursorUpdate.delete(documentId);
+    /* Don't delete listeners — they unsubscribe themselves. */
+}
+/**
+ * Handle a remote user joining the document.
+ *
+ * Called when a Supabase Presence `join` event is received.
+ *
+ * @param documentId - The document.
+ * @param presence - The remote user's presence state.
+ * @internal
+ */
+export function handlePresenceJoin(documentId, presence) {
+    const collaborators = collaboratorsByDocument.get(documentId);
+    if (!collaborators)
+        return;
+    /* Multi-tab dedup: use `userId:deviceId` as the key so the same user on
+     * different devices shows as separate presence entries, but same user on
+     * the same device (multiple tabs) collapses to one. */
+    const key = `${presence.userId}:${presence.deviceId}`;
+    collaborators.set(key, presence);
+    debugLog(`[CRDT] Document ${documentId}: ${presence.name} joined (userId=${presence.userId}, deviceId=${presence.deviceId})`);
+    notifyListeners(documentId);
+}
+/**
+ * Handle a remote user leaving the document.
+ *
+ * @param documentId - The document.
+ * @param userId - The user's UUID.
+ * @param deviceId - The user's device ID.
+ * @internal
+ */
+export function handlePresenceLeave(documentId, userId, deviceId) {
+    const collaborators = collaboratorsByDocument.get(documentId);
+    if (!collaborators)
+        return;
+    const key = `${userId}:${deviceId}`;
+    const presence = collaborators.get(key);
+    collaborators.delete(key);
+    if (presence) {
+        debugLog(`[CRDT] Document ${documentId}: ${presence.name} left`);
+    }
+    notifyListeners(documentId);
+}
+// =============================================================================
+//  Public API
+// =============================================================================
+/**
+ * Update the local user's cursor and selection in a document.
+ *
+ * Debounced to `cursorDebounceMs` (default 50ms) to avoid flooding the
+ * Presence channel with rapid cursor movements.
+ *
+ * @param documentId - The document to update cursor for.
+ * @param cursor - Editor-specific cursor position (opaque to the engine).
+ * @param selection - Editor-specific selection range (opaque to the engine).
+ *
+ * @example
+ * // In your editor's cursor change handler:
+ * editor.on('selectionUpdate', ({ editor }) => {
+ *   updateCursor('doc-1', editor.state.selection.anchor, editor.state.selection);
+ * });
+ */
+export function updateCursor(documentId, cursor, selection) {
+    const config = getCRDTConfig();
+    const now = Date.now();
+    const lastUpdate = lastCursorUpdate.get(documentId) ?? 0;
+    if (now - lastUpdate < config.cursorDebounceMs) {
+        debugLog(`[CRDT] Document ${documentId}: cursor update throttled (${now - lastUpdate}ms < ${config.cursorDebounceMs}ms)`);
+        return;
+    }
+    lastCursorUpdate.set(documentId, now);
+    /* Update local collaborator entry (if tracking). */
+    const collaborators = collaboratorsByDocument.get(documentId);
+    if (!collaborators)
+        return;
+    const deviceId = getDeviceId();
+    /* The local user's entry — find it or it might not exist yet. */
+    for (const [key, state] of collaborators) {
+        if (state.deviceId === deviceId) {
+            collaborators.set(key, {
+                ...state,
+                cursor,
+                selection,
+                lastActiveAt: new Date().toISOString()
+            });
+            notifyListeners(documentId);
+            break;
+        }
+    }
+}
+/**
+ * Get the current list of collaborators for a document.
+ *
+ * Excludes the local user (they don't need to see their own cursor).
+ *
+ * @param documentId - The document to get collaborators for.
+ * @returns Array of presence states for remote collaborators.
+ *
+ * @example
+ * const collaborators = getCollaborators('doc-1');
+ * // [{ userId: '...', name: 'Alice', color: '#E57373', cursor: {...} }]
+ */
+export function getCollaborators(documentId) {
+    const collaborators = collaboratorsByDocument.get(documentId);
+    if (!collaborators)
+        return [];
+    const localDeviceId = getDeviceId();
+    const result = [];
+    for (const state of collaborators.values()) {
+        if (state.deviceId !== localDeviceId) {
+            result.push(state);
+        }
+    }
+    const count = result.length;
+    if (count > 0) {
+        debugLog(`[CRDT] Document ${documentId}: ${count} active collaborators`);
+    }
+    return result;
+}
+/**
+ * Subscribe to collaborator changes for a document.
+ *
+ * The callback is invoked whenever a collaborator joins, leaves, or updates
+ * their cursor position. The callback receives the current list of remote
+ * collaborators (excluding the local user).
+ *
+ * @param documentId - The document to subscribe to.
+ * @param callback - Called with the updated collaborator list.
+ * @returns An unsubscribe function.
+ *
+ * @example
+ * const unsub = onCollaboratorsChange('doc-1', (collaborators) => {
+ *   avatarList = collaborators.map(c => ({ name: c.name, color: c.color }));
+ * });
+ * // Later:
+ * unsub();
+ */
+export function onCollaboratorsChange(documentId, callback) {
+    let listeners = changeListeners.get(documentId);
+    if (!listeners) {
+        listeners = new Set();
+        changeListeners.set(documentId, listeners);
+    }
+    listeners.add(callback);
+    return () => {
+        listeners.delete(callback);
+        if (listeners.size === 0) {
+            changeListeners.delete(documentId);
+        }
+    };
+}
+// =============================================================================
+//  Internal Helpers
+// =============================================================================
+/**
+ * Notify all listeners for a document of a collaborator change.
+ */
+function notifyListeners(documentId) {
+    const listeners = changeListeners.get(documentId);
+    if (!listeners || listeners.size === 0)
+        return;
+    const collaborators = getCollaborators(documentId);
+    for (const callback of listeners) {
+        try {
+            callback(collaborators);
+        }
+        catch {
+            /* Swallow listener errors to prevent cascading failures. */
+        }
+    }
+}
+//# sourceMappingURL=awareness.js.map

package/dist/crdt/awareness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.js","sourceRoot":"","sources":["../../src/crdt/awareness.ts"],"names":[],"mappings":"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"}

package/dist/crdt/channel.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview CRDT Broadcast Channel — Supabase Realtime Transport
+ *
+ * Manages one Supabase Broadcast + Presence channel per open CRDT document.
+ * Responsible for:
+ *   - Distributing Yjs updates to remote peers via Broadcast
+ *   - Receiving and applying remote updates (with echo suppression)
+ *   - Debouncing outbound updates and merging via `Y.mergeUpdates()`
+ *   - Chunking payloads that exceed the Broadcast size limit
+ *   - Running the sync protocol on join (exchange state vectors, send deltas)
+ *   - Cross-tab sync via browser `BroadcastChannel` API (avoids Supabase for same-device)
+ *   - Reconnection with exponential backoff
+ *
+ * Channel naming convention: `crdt:${prefix}:${documentId}`
+ *
+ * @see {@link ./provider.ts} for the orchestrator that creates channels
+ * @see {@link ./types.ts} for message type definitions
+ * @see {@link ./awareness.ts} for Presence management (separate concern)
+ */
+import * as Y from 'yjs';
+import type { CRDTConnectionState } from './types';
+/**
+ * Manages the Supabase Broadcast channel for a single CRDT document.
+ *
+ * Handles update distribution, echo suppression, debouncing, chunking,
+ * the sync protocol, cross-tab sync, and reconnection.
+ *
+ * @internal — consumers interact via {@link ./provider.ts}, not this class directly.
+ */
+export declare class CRDTChannel {
+    readonly documentId: string;
+    private readonly doc;
+    private readonly deviceId;
+    private readonly channelName;
+    /** Supabase Realtime channel instance. */
+    private channel;
+    /** Browser BroadcastChannel for cross-tab sync (same device). */
+    private localChannel;
+    /** Current connection state. */
+    private _connectionState;
+    /** Callback invoked when connection state changes. */
+    private onConnectionStateChange;
+    /** Initial presence info for Supabase Presence tracking. */
+    private presenceInfo;
+    private pendingUpdates;
+    private debounceTimer;
+    private chunkBuffers;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private destroyed;
+    private syncResolvers;
+    constructor(documentId: string, doc: Y.Doc, onConnectionStateChange?: (state: CRDTConnectionState) => void);
+    /** Current connection state of the channel. */
+    get connectionState(): CRDTConnectionState;
+    /**
+     * Set the local user's presence info for Supabase Presence tracking.
+     *
+     * Call this before `join()` to announce presence immediately on channel subscribe,
+     * or after join to update the tracked presence.
+     */
+    setPresenceInfo(info: {
+        name: string;
+        avatarUrl?: string;
+    }): void;
+    /**
+     * Join the Broadcast channel and start receiving messages.
+     *
+     * After subscribing, initiates the sync protocol by sending a sync-step-1
+     * message with the local state vector so peers can respond with deltas.
+     */
+    join(): Promise<void>;
+    /**
+     * Leave the channel and clean up all resources.
+     */
+    leave(): Promise<void>;
+    /**
+     * Queue a Yjs update for broadcasting to remote peers.
+     *
+     * Updates are debounced for `broadcastDebounceMs` (default 100ms) and merged
+     * via `Y.mergeUpdates()` before sending. This reduces network traffic for
+     * rapid keystrokes while keeping latency under 100ms.
+     *
+     * @param update - The Yjs update delta from `doc.on('update')`.
+     */
+    broadcastUpdate(update: Uint8Array): void;
+    /**
+     * Wait for the sync protocol to complete after joining.
+     *
+     * Resolves when at least one peer responds with sync-step-2, or times out
+     * after `syncPeerTimeoutMs` (default 3s) if no peers are available.
+     *
+     * @returns `true` if a peer responded, `false` if timed out (no peers).
+     */
+    waitForSync(): Promise<boolean>;
+    /**
+     * Handle an incoming Broadcast message from a remote peer.
+     *
+     * Dispatches to type-specific handlers and performs echo suppression
+     * (skip messages from our own device).
+     */
+    private handleBroadcastMessage;
+    /**
+     * Apply a remote Yjs update to the local document.
+     */
+    private handleRemoteUpdate;
+    /**
+     * Handle sync-step-1: a peer is requesting missing updates.
+     *
+     * We compute the delta between our state and their state vector,
+     * then send it back as sync-step-2.
+     */
+    private handleSyncStep1;
+    /**
+     * Handle sync-step-2: a peer responded to our sync-step-1 with a delta.
+     */
+    private handleSyncStep2;
+    /**
+     * Handle a chunk message — part of a large payload that was split.
+     *
+     * Buffers chunks until all parts arrive, then reassembles and processes
+     * the full payload as a regular message.
+     */
+    private handleChunk;
+    /**
+     * Flush all pending updates: merge, encode, and send via Broadcast.
+     *
+     * If the merged payload exceeds the max size, it is chunked.
+     */
+    private flushUpdates;
+    /**
+     * Send sync-step-1 to request missing updates from connected peers.
+     */
+    private sendSyncStep1;
+    /**
+     * Send a message via the Supabase Broadcast channel.
+     */
+    private sendMessage;
+    /**
+     * Split a large base64 payload into chunks and send each one.
+     */
+    private sendChunked;
+    /**
+     * Set up the browser BroadcastChannel for same-device tab sync.
+     *
+     * This avoids Supabase Broadcast for updates between tabs on the same device,
+     * which is faster and doesn't consume any network bandwidth.
+     */
+    private setupLocalChannel;
+    /**
+     * Handle a channel disconnect — attempt reconnection with exponential backoff.
+     */
+    private handleDisconnect;
+    /**
+     * Track the local user's presence on the Supabase Presence channel.
+     *
+     * Sends the user's name, avatar, color, and device ID so other collaborators
+     * can display cursor badges and avatar lists.
+     */
+    private trackPresence;
+    /**
+     * Update the connection state and notify the listener.
+     */
+    private setConnectionState;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/crdt/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/crdt/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAQzB,OAAO,KAAK,EAMV,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAqCjB;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,0CAA0C;IAC1C,OAAO,CAAC,OAAO,CAAgC;IAE/C,iEAAiE;IACjE,OAAO,CAAC,YAAY,CAAiC;IAErD,gCAAgC;IAChC,OAAO,CAAC,gBAAgB,CAAuC;IAE/D,sDAAsD;IACtD,OAAO,CAAC,uBAAuB,CAAuD;IAEtF,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAAqD;IAGzE,OAAO,CAAC,cAAc,CAAoB;IAC1C,OAAO,CAAC,aAAa,CAA8C;IAGnE,OAAO,CAAC,YAAY,CAA0E;IAG9F,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,aAAa,CAAsC;gBAGzD,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,uBAAuB,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI;IAahE,+CAA+C;IAC/C,IAAI,eAAe,IAAI,mBAAmB,CAEzC;IAED;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAQjE;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyD3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAsBzC;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA8B/B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAyB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAcvB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAiCnB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IA4BpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,WAAW;IA6BnB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsCxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAK3B"}