@prabhask5/stellar-engine 1.1.7 → 1.1.8

package/dist/realtime.js

@@ -1,18 +1,79 @@
 /**
- * Real-Time Subscription Manager
+ * @fileoverview Real-Time Subscription Manager -- Supabase Realtime WebSocket Layer
  *
  * Phase 5 of multi-device sync: Implements Supabase Realtime subscriptions
  * for instant multi-device synchronization.
  *
- * Design decisions:
- * - Uses Supabase Realtime PostgreSQL Changes for all entity tables
- * - Skips echo (own changes) by comparing device_id in the payload
- * - Tracks recently processed entities to prevent duplicate processing with polling
- * - Applies changes through existing conflict resolution engine
- * - Falls back to polling if WebSocket connection fails (max 5 reconnect attempts)
- * - Single channel per user with filter by user_id for efficiency
- * - Pauses reconnection attempts while offline (waits for online event)
- * - Uses reconnectScheduled flag to prevent duplicate reconnect attempts
+ * ## Architecture
+ *
+ * This module manages a single Supabase Realtime channel per authenticated user,
+ * listening for PostgreSQL changes (INSERT, UPDATE, DELETE) across all configured
+ * entity tables. When a change arrives from another device, it is applied to the
+ * local Dexie (IndexedDB) store and subscribers are notified so the UI can react.
+ *
+ * ```
+ *   Supabase Postgres  --(CDC)--> Supabase Realtime Server
+ *                                        |
+ *                                   WebSocket
+ *                                        |
+ *                                   This module
+ *                                        |
+ *                          +-------------+-------------+
+ *                          |                           |
+ *                   Local Dexie DB             UI Notification
+ *                  (conflict-resolved)       (animation / refresh)
+ * ```
+ *
+ * ## Echo Suppression
+ *
+ * Every write to Supabase includes a `device_id` field. When a realtime event
+ * arrives, we compare its `device_id` against our own. If they match, the event
+ * originated from this device and is silently discarded. This prevents the
+ * "echo" problem where a device processes its own outgoing changes a second time.
+ *
+ * ## Deduplication with Polling
+ *
+ * The sync engine also runs periodic polling as a fallback. To prevent the same
+ * remote change from being applied twice (once via realtime, once via poll), this
+ * module maintains a short-lived `recentlyProcessedByRealtime` map. The polling
+ * path in `engine.ts` checks this map before processing a change.
+ *
+ * ## Reconnection Strategy
+ *
+ * On WebSocket disconnection the module uses exponential backoff (1s, 2s, 4s, ...)
+ * up to {@link MAX_RECONNECT_ATTEMPTS} (5) attempts. If the browser is offline,
+ * reconnection is paused entirely -- no timers fire until a `navigator.onLine`
+ * event restores connectivity. A `reconnectScheduled` flag prevents duplicate
+ * reconnection timers from stacking up when multiple channel events fire in
+ * quick succession.
+ *
+ * ## Soft Deletes and Animations
+ *
+ * When a soft delete is detected (UPDATE with `deleted=true`), the module
+ * records the deletion in {@link remoteChangesStore} *before* writing to Dexie.
+ * This ordering is intentional: it allows the UI layer to play a removal
+ * animation before the reactive store filters out the deleted record.
+ *
+ * ## Security Considerations
+ *
+ * - **Row-Level Security (RLS):** No client-side user ID filter is applied to
+ *   the channel subscription. All access control is enforced by Supabase RLS
+ *   policies at the database level. This is a deliberate security decision:
+ *   client-side filters can be bypassed, whereas RLS operates inside Postgres
+ *   and cannot be circumvented by a malicious client.
+ * - **Device ID trust boundary:** The `device_id` field is used only for echo
+ *   suppression and conflict tiebreaking, **not** for authorization. A spoofed
+ *   `device_id` could cause an event to be incorrectly suppressed on another
+ *   device, but it cannot escalate privileges or access unauthorized data.
+ * - **Channel naming:** The channel name includes the user ID to ensure
+ *   Supabase routes CDC events correctly. This is a routing hint, not a
+ *   security boundary -- RLS is the actual enforcement mechanism.
+ *
+ * @see {@link ./engine.ts} for the orchestrating sync engine and polling loop
+ * @see {@link ./conflicts.ts} for the conflict resolution algorithm
+ * @see {@link ./queue.ts} for the pending operations queue
+ * @see {@link ./stores/remoteChanges.ts} for UI change-tracking and animations
+ * @see {@link ./deviceId.ts} for per-device identity generation
  */
 import { debugLog, debugWarn, debugError } from './debug';
 import { getEngineConfig, getDexieTableFor } from './config';
@@ -20,11 +81,60 @@ import { getDeviceId } from './deviceId';
 import { resolveConflicts, storeConflictHistory, getPendingOpsForEntity } from './conflicts';
 import { getPendingEntityIds } from './queue';
 import { remoteChangesStore } from './stores/remoteChanges';
-// Protection window for recently modified entities (matches engine.ts)
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * How long (in ms) a processed entity is considered "recent."
+ * Must match the TTL used in engine.ts for `recentlyModifiedEntities`
+ * so that the deduplication windows overlap correctly.
+ *
+ * **Why 2 seconds?** This window must be long enough to span the typical
+ * latency gap between a realtime WebSocket push and the next polling cycle.
+ * If the poll fires within 2s of the realtime event, the entity will still
+ * be in the dedup map and the poll result will be skipped.
+ *
+ * @see {@link ./engine.ts} -- `RECENTLY_MODIFIED_TTL_MS`
+ */
 const RECENTLY_MODIFIED_TTL_MS = 2000;
-// Track entities that realtime has just processed (to prevent duplicate processing with polling)
-// This is separate from engine.ts's recentlyModifiedEntities (which tracks local writes)
+/**
+ * Maximum number of reconnection attempts before the module gives up
+ * and falls back to polling-only mode.
+ *
+ * **Why 5?** With exponential backoff (1s, 2s, 4s, 8s, 16s) the total
+ * wait before giving up is ~31 seconds, which covers most transient
+ * network hiccups without annoying the user with prolonged retry noise.
+ */
+const MAX_RECONNECT_ATTEMPTS = 5;
+/**
+ * Base delay for exponential backoff between reconnection attempts.
+ * Actual delay = RECONNECT_BASE_DELAY * 2^(attemptIndex).
+ */
+const RECONNECT_BASE_DELAY = 1000;
+// =============================================================================
+// MODULE-LEVEL STATE
+// =============================================================================
+/**
+ * Tracks entities that realtime has recently processed, keyed by entity ID
+ * with the timestamp of processing as the value.
+ *
+ * This is intentionally separate from `engine.ts`'s `recentlyModifiedEntities`
+ * (which tracks *local* writes). This map tracks *remote* changes received via
+ * WebSocket so that the polling path can skip them.
+ *
+ * **Memory note:** Entries are lazily evicted on read (see {@link wasRecentlyProcessed})
+ * and actively cleaned by {@link cleanupRealtimeTracking}. In the worst case the map
+ * holds one entry per entity modified within the last {@link RECENTLY_MODIFIED_TTL_MS}.
+ */
 const recentlyProcessedByRealtime = new Map();
+/**
+ * Singleton state instance. Initialized to a clean "disconnected" baseline.
+ *
+ * **Why a singleton?** A browser tab should never have more than one WebSocket
+ * connection to Supabase Realtime for the same user. Multiple connections would
+ * cause duplicate event processing and wasted bandwidth. The singleton pattern
+ * enforces this at the module level.
+ */
 const state = {
     channel: null,
     connectionState: 'disconnected',
@@ -34,43 +144,140 @@ const state = {
     reconnectAttempts: 0,
     reconnectTimeout: null
 };
-// Callbacks for state changes and data updates
+// =============================================================================
+// CALLBACK REGISTRIES
+// =============================================================================
+/**
+ * Registered listeners that fire whenever the connection state transitions.
+ * Each callback receives the new {@link RealtimeConnectionState}.
+ *
+ * **Why a Set?** Using a `Set` ensures the same callback reference cannot be
+ * registered twice, which prevents duplicate notifications if consumer code
+ * accidentally calls `onConnectionStateChange` more than once with the same fn.
+ */
 const connectionCallbacks = new Set();
+/**
+ * Registered listeners that fire after a remote change has been applied to the
+ * local Dexie database. Consumers (e.g. Svelte stores) use this to trigger
+ * reactive re-queries.
+ *
+ * **Ordering guarantee:** Callbacks are invoked *after* the Dexie write has
+ * completed, so any re-query inside the callback will return the updated data.
+ */
 const dataUpdateCallbacks = new Set();
-// Maximum reconnect attempts before giving up (will fall back to polling)
-const MAX_RECONNECT_ATTEMPTS = 5;
-// Base delay for exponential backoff (ms)
-const RECONNECT_BASE_DELAY = 1000;
-// Lock to prevent concurrent start/stop operations
+// =============================================================================
+// CONCURRENCY GUARDS
+// =============================================================================
+/**
+ * Mutex-like flag preventing concurrent `start` / `stop` operations.
+ * Because channel setup and teardown are async, overlapping calls could leave
+ * the module in an inconsistent state without this guard.
+ *
+ * **Not a true mutex:** This is a cooperative lock -- it relies on callers
+ * checking the flag and bailing out. Since JavaScript is single-threaded,
+ * there is no race between the check and the set, making this safe.
+ */
 let operationInProgress = false;
-// Flag to track if reconnect is already scheduled (prevents duplicate scheduling)
+/**
+ * Prevents duplicate reconnection timers from being scheduled.
+ * Supabase may emit both `CHANNEL_ERROR` and `CLOSED` events for the same
+ * disconnection; without this flag each event would schedule its own timer.
+ *
+ * **Reset points:** This flag is cleared in three places:
+ * 1. Inside the setTimeout callback (normal reconnect flow)
+ * 2. In {@link stopRealtimeSubscriptionsInternal} (teardown)
+ * 3. In {@link pauseRealtime} (offline transition)
+ */
 let reconnectScheduled = false;
+// =============================================================================
+// PUBLIC API -- SUBSCRIPTION HOOKS
+// =============================================================================
 /**
- * Subscribe to connection state changes
+ * Subscribe to connection state changes.
+ *
+ * The callback is invoked immediately with the current state upon registration,
+ * then again on every subsequent transition.
+ *
+ * @param callback - Function invoked with the new {@link RealtimeConnectionState}.
+ * @returns An unsubscribe function. Call it to remove the listener.
+ *
+ * @example
+ * ```ts
+ * const unsub = onConnectionStateChange((state) => {
+ *   if (state === 'error') showReconnectBanner();
+ * });
+ * // Later, to stop listening:
+ * unsub();
+ * ```
  */
 export function onConnectionStateChange(callback) {
     connectionCallbacks.add(callback);
-    // Immediately call with current state
+    /* Deliver the current state immediately so the subscriber doesn't have to
+       wait for the next transition to learn the baseline. This pattern is common
+       in observable/store implementations (e.g., Svelte stores call subscribers
+       on subscription). */
     callback(state.connectionState);
     return () => connectionCallbacks.delete(callback);
 }
 /**
- * Subscribe to data update notifications (called after local DB is updated)
+ * Subscribe to data update notifications.
+ *
+ * Callbacks fire *after* the remote change has been written to the local Dexie
+ * database, so re-querying inside the callback will return fresh data.
+ *
+ * @param callback - Function invoked with the Supabase table name and entity ID.
+ * @returns An unsubscribe function. Call it to remove the listener.
+ *
+ * @example
+ * ```ts
+ * const unsub = onRealtimeDataUpdate((table, entityId) => {
+ *   if (table === 'habits') refreshHabitStore();
+ * });
+ * ```
+ *
+ * @see {@link notifyDataUpdate} for the internal dispatch function
  */
 export function onRealtimeDataUpdate(callback) {
     dataUpdateCallbacks.add(callback);
     return () => dataUpdateCallbacks.delete(callback);
 }
+// =============================================================================
+// PUBLIC API -- STATE QUERIES
+// =============================================================================
 /**
- * Get current realtime connection state.
- * Used by debug utilities exposed on the window object.
+ * Get the current realtime connection state.
+ *
+ * Primarily used by debug utilities exposed on `window.__stellarDebug`.
+ *
+ * @returns The current {@link RealtimeConnectionState}.
+ *
+ * @see {@link ./debug.ts} for the debug surface that consumes this
  */
 export function getConnectionState() {
     return state.connectionState;
 }
 /**
- * Check if an entity was recently processed via realtime
- * Used by engine.ts to prevent duplicate processing during polling
+ * Check whether an entity was recently processed via a realtime event.
+ *
+ * Called by `engine.ts` during polling to avoid applying the same remote
+ * change twice (once from realtime, once from the poll response).
+ *
+ * **Side effect:** Expired entries are lazily evicted on access. This keeps
+ * the map from growing during bursts of activity, complementing the
+ * periodic cleanup in {@link cleanupRealtimeTracking}.
+ *
+ * @param entityId - The UUID of the entity to check.
+ * @returns `true` if the entity was processed within the last {@link RECENTLY_MODIFIED_TTL_MS} ms.
+ *
+ * @example
+ * ```ts
+ * if (wasRecentlyProcessedByRealtime(entity.id)) {
+ *   // Skip -- realtime already handled this change
+ *   continue;
+ * }
+ * ```
+ *
+ * @see {@link ./engine.ts} -- polling path
  */
 export function wasRecentlyProcessedByRealtime(entityId) {
     const processedAt = recentlyProcessedByRealtime.get(entityId);
@@ -84,7 +291,45 @@ export function wasRecentlyProcessedByRealtime(entityId) {
     return true;
 }
 /**
- * Update connection state and notify subscribers
+ * Check if the realtime connection is healthy (connected and not in an error state).
+ *
+ * @returns `true` when the WebSocket channel is in the `'connected'` state.
+ */
+export function isRealtimeHealthy() {
+    return state.connectionState === 'connected';
+}
+/**
+ * Remove expired entries from the recently-processed tracking map.
+ *
+ * Called periodically by the sync engine's maintenance loop to prevent
+ * unbounded memory growth in long-running sessions.
+ *
+ * **Why explicit cleanup?** Lazy eviction in {@link wasRecentlyProcessedByRealtime}
+ * only fires when an entity is looked up. If an entity is processed by realtime
+ * but never polled (e.g., a table not included in the current poll cycle),
+ * its entry would persist indefinitely without this active sweep.
+ *
+ * @see {@link RECENTLY_MODIFIED_TTL_MS}
+ */
+export function cleanupRealtimeTracking() {
+    const now = Date.now();
+    for (const [entityId, processedAt] of recentlyProcessedByRealtime) {
+        if (now - processedAt > RECENTLY_MODIFIED_TTL_MS) {
+            recentlyProcessedByRealtime.delete(entityId);
+        }
+    }
+}
+// =============================================================================
+// INTERNAL HELPERS -- STATE NOTIFICATIONS
+// =============================================================================
+/**
+ * Transition the connection state and notify all registered listeners.
+ *
+ * Errors thrown by individual callbacks are caught and logged so that one
+ * misbehaving listener cannot break the notification chain.
+ *
+ * @param newState - The {@link RealtimeConnectionState} to transition to.
+ * @param error    - Optional human-readable error message stored in {@link state.lastError}.
  */
 function setConnectionState(newState, error) {
     state.connectionState = newState;
@@ -94,12 +339,23 @@ function setConnectionState(newState, error) {
             callback(newState);
         }
         catch (e) {
+            /* Catch-and-continue: a broken subscriber must not prevent other
+               subscribers from being notified, nor should it crash the realtime
+               lifecycle management. */
             debugError('[Realtime] Connection callback error:', e);
         }
     }
 }
 /**
- * Notify data update subscribers
+ * Dispatch a data-update event to all registered subscribers.
+ *
+ * Called after a remote change has been written to Dexie. Errors thrown by
+ * individual callbacks are caught and logged.
+ *
+ * @param table    - The Supabase table name where the change originated (e.g. `'habits'`).
+ * @param entityId - The UUID of the changed entity.
+ *
+ * @see {@link onRealtimeDataUpdate} for the public subscription API
  */
 function notifyDataUpdate(table, entityId) {
     debugLog(`[Realtime] Notifying ${dataUpdateCallbacks.size} subscribers of update: ${table}/${entityId}`);
@@ -112,8 +368,26 @@ function notifyDataUpdate(table, entityId) {
         }
     }
 }
+// =============================================================================
+// INTERNAL HELPERS -- ECHO & DEDUP FILTERS
+// =============================================================================
 /**
- * Check if this change came from our own device (skip to prevent echo)
+ * Determine whether a change event originated from this device.
+ *
+ * Supabase Realtime delivers *all* changes matching the channel filter,
+ * including changes made by the current device. We compare the `device_id`
+ * field in the payload against our own to suppress these "echoes."
+ *
+ * **Security note:** The `device_id` comparison is used purely for performance
+ * optimization (avoiding redundant local writes). It is **not** a security
+ * mechanism. A spoofed `device_id` could only cause an event to be skipped
+ * on the spoofing device -- it cannot grant access to other users' data
+ * because RLS enforces row-level access at the database level.
+ *
+ * @param record - The `new` record from the realtime payload, or `null`.
+ * @returns `true` if the record's `device_id` matches this device.
+ *
+ * @see {@link ./deviceId.ts} -- where the device identity is generated
  */
 function isOwnDeviceChange(record) {
     if (!record)
@@ -122,7 +396,20 @@ function isOwnDeviceChange(record) {
     return recordDeviceId === state.deviceId;
 }
 /**
- * Check if entity was recently processed by realtime (prevent duplicate processing)
+ * Check if an entity was recently processed by this realtime handler.
+ *
+ * This is the *internal* counterpart of the exported
+ * {@link wasRecentlyProcessedByRealtime}. It is called inside
+ * {@link handleRealtimeChange} to short-circuit duplicate events that may
+ * arrive in rapid succession (e.g. due to Supabase retries).
+ *
+ * **Why a separate function?** The internal version is used in the hot path
+ * of change processing, while the exported version is used by the polling
+ * engine. Keeping them separate makes it clear which is the internal guard
+ * and which is the cross-module dedup check.
+ *
+ * @param entityId - The UUID of the entity to check.
+ * @returns `true` if the entity is within the deduplication window.
  */
 function wasRecentlyProcessed(entityId) {
     const processedAt = recentlyProcessedByRealtime.get(entityId);
@@ -135,8 +422,40 @@ function wasRecentlyProcessed(entityId) {
     }
     return true;
 }
+// =============================================================================
+// CORE CHANGE HANDLER
+// =============================================================================
 /**
- * Handle incoming realtime change
+ * Process an incoming realtime change event from Supabase.
+ *
+ * This is the central routing function for all realtime events. It:
+ * 1. Extracts the entity ID and event type from the payload.
+ * 2. Applies echo suppression and deduplication filters.
+ * 3. Looks up the matching Dexie table via the engine config.
+ * 4. Delegates to the appropriate branch: INSERT/UPDATE or DELETE.
+ * 5. Records the change in {@link remoteChangesStore} for UI animations.
+ * 6. Marks the entity as recently processed to prevent polling duplication.
+ * 7. Notifies data-update subscribers.
+ *
+ * For INSERT/UPDATE events with pending local operations, the function
+ * delegates to {@link resolveConflicts} to produce a merged entity.
+ *
+ * **Error handling:** All errors are caught at the top level and logged.
+ * A failure to process one event must not crash the WebSocket listener or
+ * prevent subsequent events from being handled.
+ *
+ * **Ordering contract with remoteChangesStore:**
+ * For delete operations (both soft and hard), the change is recorded in
+ * remoteChangesStore **before** writing to Dexie. This ordering is critical
+ * for exit animations -- see the soft delete and hard delete sections below.
+ *
+ * @param table   - The Supabase table name (e.g. `'habits'`, `'entries'`).
+ * @param payload - The raw Supabase realtime change payload.
+ *
+ * @throws Never throws -- all errors are caught internally and logged.
+ *
+ * @see {@link resolveConflicts} for the conflict resolution algorithm
+ * @see {@link remoteChangesStore} for how the UI animates remote changes
  */
 async function handleRealtimeChange(table, payload) {
     const eventType = payload.eventType;
@@ -144,19 +463,26 @@ async function handleRealtimeChange(table, payload) {
     const newRecord = payload.new;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const oldRecord = payload.old;
-    // Determine entity ID
+    /* For DELETEs, Supabase only populates `old`; for INSERTs only `new`.
+       UPDATEs populate both. We need the ID from whichever is available. */
     const entityId = (newRecord?.id || oldRecord?.id);
     debugLog(`[Realtime] Received ${eventType} on ${table}:`, entityId);
     if (!entityId) {
         debugWarn('[Realtime] Change without entity ID:', table, eventType);
         return;
     }
-    // Skip if this change came from our own device (prevents echo)
+    /* ---- Echo suppression ----
+       Skip events that originated from this device. Without this check, every
+       local write would be processed a second time when the CDC event arrives
+       back through the WebSocket, causing redundant Dexie writes and UI flicker. */
     if (isOwnDeviceChange(newRecord)) {
         debugLog(`[Realtime] Skipping own device change: ${table}/${entityId}`);
         return;
     }
-    // Skip if we just processed this entity (prevents rapid duplicate processing)
+    /* ---- Deduplication ----
+       Skip events for entities we already processed very recently. This guards
+       against Supabase delivering the same CDC event multiple times (which can
+       happen during server-side reconnection or rebalancing). */
     if (wasRecentlyProcessed(entityId)) {
         debugLog(`[Realtime] Skipping recently processed: ${table}/${entityId}`);
         return;
@@ -170,106 +496,165 @@ async function handleRealtimeChange(table, payload) {
     }
     try {
         switch (eventType) {
+            // -----------------------------------------------------------------------
+            // INSERT / UPDATE -- the bulk of the logic lives here
+            // -----------------------------------------------------------------------
             case 'INSERT':
             case 'UPDATE': {
                 if (!newRecord)
                     return;
-                // Check if entity is being edited in a manual-save form
+                /* Check if entity is being edited in a manual-save form. When true,
+                   remoteChangesStore will defer the incoming change until the form is
+                   closed, preventing jarring mid-edit overwrites. This is a UX decision:
+                   we prioritize the active editing experience over instant sync. */
                 const _isBeingEdited = remoteChangesStore.isEditing(entityId, table);
-                // Get local entity if it exists
+                /* Fetch the local version so we can diff fields and detect conflicts. */
                 const localEntity = await getEngineConfig().db.table(dexieTable).get(entityId);
-                // Determine which fields changed
+                /* Build a list of fields whose values actually differ between local
+                   and remote. We skip metadata fields (updated_at, _version) because
+                   they always change and would produce noisy animations. These fields
+                   are managed by the sync engine, not the user, so highlighting them
+                   would be misleading. */
                 const changedFields = [];
                 if (localEntity && newRecord) {
                     for (const key of Object.keys(newRecord)) {
                         if (key === 'updated_at' || key === '_version')
                             continue;
+                        /* JSON.stringify comparison handles nested objects/arrays correctly.
+                           For primitives it is equivalent to ===, with the caveat that
+                           undefined fields are omitted (which is the desired behavior). */
                         if (JSON.stringify(localEntity[key]) !== JSON.stringify(newRecord[key])) {
                             changedFields.push(key);
                         }
                     }
                 }
-                // Soft delete: UPDATE with deleted=true is treated as a deletion
-                // Play the delete animation BEFORE writing to DB so stores don't filter it out instantly
+                /* ---- Soft delete detection ----
+                   A soft delete manifests as an UPDATE where `deleted` transitions from
+                   false to true. We handle this specially: the UI animation (fade-out)
+                   must play BEFORE the record is written to Dexie, because reactive
+                   stores will immediately filter out deleted records, removing the DOM
+                   element and preventing any exit animation.
+        
+                   **Why not use CSS `animation-fill-mode: forwards`?** Because the DOM
+                   element is removed entirely by the reactive framework (Svelte's
+                   {#each} block), not just hidden. Once the Dexie write triggers a
+                   store update, the element is gone from the DOM. */
                 const isSoftDelete = newRecord.deleted === true && localEntity && !localEntity.deleted;
                 if (isSoftDelete) {
                     debugLog(`[Realtime] Soft delete detected for ${table}/${entityId}`);
-                    // Record delete animation and wait for it to play
+                    /* Record + await the delete animation before touching the DB.
+                       The wildcard ['*'] signals the UI that the entire row is affected. */
                     remoteChangesStore.recordRemoteChange(entityId, table, ['*'], true, 'DELETE');
                     await remoteChangesStore.markPendingDelete(entityId, table);
-                    // Now write the soft-deleted record to DB (triggers reactive store refresh)
+                    /* Now persist the soft-deleted record; reactive stores refresh. */
                     await getEngineConfig().db.table(dexieTable).put(newRecord);
                     recentlyProcessedByRealtime.set(entityId, Date.now());
                     notifyDataUpdate(table, entityId);
                     break;
                 }
-                // Check for pending operations
+                /* ---- Conflict resolution path ----
+                   Three branches depending on local state:
+                   1. No local entity  -> simple insert (no conflict possible)
+                   2. No pending ops   -> accept remote if newer (last-write-wins)
+                   3. Pending ops exist -> full conflict resolution via resolveConflicts
+        
+                   **Why check pending ops?** If the user has unsynced local changes,
+                   blindly accepting the remote version would silently discard the
+                   user's work. The conflict resolver preserves local pending changes
+                   while incorporating non-conflicting remote updates. */
                 const pendingEntityIds = await getPendingEntityIds();
                 const hasPendingOps = pendingEntityIds.has(entityId);
                 let applied = false;
                 if (!localEntity) {
-                    // New entity - just insert it
+                    /* Branch 1: Entity doesn't exist locally -- just insert.
+                       This happens when another device creates a new entity. */
                     await getEngineConfig().db.table(dexieTable).put(newRecord);
                     applied = true;
                 }
                 else if (!hasPendingOps) {
-                    // No pending ops - check if remote is newer
+                    /* Branch 2: No unsynced local changes -- simple timestamp comparison.
+                       Only overwrite if the remote timestamp is strictly newer. If the
+                       local version is newer (possible if a local write just happened
+                       but hasn't been pushed yet), we keep the local version to avoid
+                       regressing the UI. */
                     const localUpdatedAt = new Date(localEntity.updated_at).getTime();
                     const remoteUpdatedAt = new Date(newRecord.updated_at).getTime();
                     if (remoteUpdatedAt > localUpdatedAt) {
-                        // Remote is newer, accept it
                         await getEngineConfig().db.table(dexieTable).put(newRecord);
                         applied = true;
                     }
                 }
                 else {
-                    // Has pending operations - use conflict resolution
+                    /* Branch 3: Pending local operations exist -- we must merge.
+                       The conflict resolver produces a merged entity that preserves
+                       non-conflicting local edits while incorporating the remote state.
+                       See conflicts.ts for the three-tier resolution algorithm. */
                     const pendingOps = await getPendingOpsForEntity(entityId);
                     const resolution = await resolveConflicts(table, entityId, localEntity, newRecord, pendingOps);
-                    // Store merged entity
                     await getEngineConfig().db.table(dexieTable).put(resolution.mergedEntity);
                     applied = true;
-                    // Store conflict history if there were conflicts
+                    /* Persist conflict history for auditability and potential undo.
+                       Only stored when actual field-level conflicts were detected
+                       (not for clean auto-merges). */
                     if (resolution.hasConflicts) {
                         await storeConflictHistory(resolution);
                     }
                 }
-                // Calculate value delta for increment/decrement detection
+                /* ---- Value delta for counter animations ----
+                   If the `current_value` field changed, compute the delta so the UI
+                   can show an increment/decrement animation (e.g. "+1" / "-3").
+                   This is specific to counter-style entities (e.g., habit streaks,
+                   goal progress). */
                 let valueDelta;
                 if (changedFields.includes('current_value') && localEntity && newRecord) {
                     const oldValue = localEntity.current_value || 0;
                     const newValue = newRecord.current_value || 0;
                     valueDelta = newValue - oldValue;
                 }
-                // Record the remote change for UI animation
-                // If entity is being edited in a form, the change will be deferred
-                // We pass the eventType so the store can detect the action type
+                /* ---- UI change notification ----
+                   Record the change in remoteChangesStore so the UI can highlight
+                   the affected row / field. If the entity is currently being edited
+                   in a form, the store defers the notification until editing ends.
+        
+                   We only notify when there are actual visible changes (changedFields > 0)
+                   or when the entity is entirely new (!localEntity). This prevents
+                   spurious highlight animations for metadata-only updates. */
                 if (changedFields.length > 0 || !localEntity) {
                     remoteChangesStore.recordRemoteChange(entityId, table, changedFields.length > 0 ? changedFields : ['*'], applied, eventType, valueDelta);
-                    // Call table-specific onRemoteChange hook if configured
+                    /* Fire the optional per-table hook so consumers can run custom
+                       side-effects (e.g. toast notifications, badge updates). */
                     const tblConfig = getEngineConfig().tables.find((t) => t.supabaseName === table);
                     if (tblConfig?.onRemoteChange) {
                         tblConfig.onRemoteChange(table, newRecord);
                     }
                 }
-                // Mark as recently processed to prevent duplicate processing by polling
+                /* Mark as recently processed so the polling path skips this entity.
+                   This is the bridge between realtime and polling deduplication. */
                 recentlyProcessedByRealtime.set(entityId, Date.now());
-                // Notify subscribers
                 notifyDataUpdate(table, entityId);
                 break;
             }
+            // -----------------------------------------------------------------------
+            // DELETE -- hard-delete path (rare in soft-delete systems)
+            // -----------------------------------------------------------------------
             case 'DELETE': {
-                // For soft-delete systems, this would be an UPDATE with deleted=true
-                // But if hard delete happens, we should remove locally too
+                /* In a soft-delete system most deletions arrive as UPDATEs with
+                   `deleted=true` (handled above). A hard DELETE is uncommon but must
+                   still be handled for correctness -- it can occur when:
+                   - An admin purges records directly in the database
+                   - A scheduled cleanup job removes old soft-deleted rows
+                   - The application uses hard deletes for certain entity types */
                 if (oldRecord) {
-                    // Record the delete for UI animation before removing
+                    /* Record delete animation BEFORE removing from DB, same ordering
+                       rationale as the soft-delete path above: the reactive framework
+                       will remove the DOM element immediately on Dexie deletion, so
+                       the animation must be set up first. */
                     remoteChangesStore.recordRemoteChange(entityId, table, ['*'], true, 'DELETE');
-                    // Mark as pending delete and wait for animation to complete
-                    // This allows the UI to play the delete animation before DOM removal
+                    /* Wait for the pending-delete animation to complete so the UI has
+                       time to play an exit transition before the DOM element disappears. */
                     await remoteChangesStore.markPendingDelete(entityId, table);
-                    // Now actually delete from database (triggers reactive DOM removal)
+                    /* Now remove the record from Dexie (triggers reactive DOM removal). */
                     await getEngineConfig().db.table(dexieTable).delete(entityId);
-                    // Mark as recently processed
                     recentlyProcessedByRealtime.set(entityId, Date.now());
                     notifyDataUpdate(table, entityId);
                 }
@@ -278,15 +663,38 @@ async function handleRealtimeChange(table, payload) {
         }
     }
     catch (error) {
+        /* Top-level catch ensures one bad event never crashes the WebSocket
+           listener. The channel continues processing subsequent events. */
         debugError(`[Realtime] Error handling ${eventType} on ${table}:`, error);
     }
 }
+// =============================================================================
+// RECONNECTION LOGIC
+// =============================================================================
 /**
- * Schedule reconnection with exponential backoff
- * Only schedules if online - no point reconnecting while offline
+ * Schedule a reconnection attempt using exponential backoff.
+ *
+ * Behavior:
+ * - If the browser is offline (`navigator.onLine === false`), reconnection is
+ *   skipped entirely. The sync engine's `online` event handler will re-trigger
+ *   subscription start when connectivity returns.
+ * - If the maximum number of attempts has been reached, the module gives up and
+ *   transitions to `'error'` state; the polling fallback remains active.
+ * - A `reconnectScheduled` flag prevents duplicate timers from being created
+ *   when multiple channel events (e.g. CHANNEL_ERROR + CLOSED) fire in quick
+ *   succession for the same disconnection.
+ *
+ * **Backoff schedule:** 1s, 2s, 4s, 8s, 16s (geometric progression).
+ * Total wait across all 5 attempts: ~31 seconds.
+ *
+ * @see {@link MAX_RECONNECT_ATTEMPTS}
+ * @see {@link RECONNECT_BASE_DELAY}
+ * @see {@link startRealtimeSubscriptions} -- called by the timer callback
  */
 function scheduleReconnect() {
-    // Prevent duplicate scheduling from multiple event callbacks
+    /* Guard: prevent duplicate scheduling from multiple event callbacks.
+       Supabase can emit CHANNEL_ERROR followed closely by CLOSED for the same
+       disconnection event; both would call this function without this guard. */
     if (reconnectScheduled) {
         return;
     }
@@ -294,7 +702,9 @@ function scheduleReconnect() {
         clearTimeout(state.reconnectTimeout);
         state.reconnectTimeout = null;
     }
-    // Don't attempt reconnection while offline - wait for online event
+    /* No point burning reconnect attempts while the network is down.
+       The sync engine listens for the browser's `online` event and will call
+       startRealtimeSubscriptions() when connectivity returns. */
     if (typeof navigator !== 'undefined' && !navigator.onLine) {
         debugLog('[Realtime] Offline - waiting for online event to reconnect');
         setConnectionState('disconnected');
@@ -306,11 +716,13 @@ function scheduleReconnect() {
         return;
     }
     reconnectScheduled = true;
+    /* Exponential backoff: 1s, 2s, 4s, 8s, 16s */
     const delay = RECONNECT_BASE_DELAY * Math.pow(2, state.reconnectAttempts);
     debugLog(`[Realtime] Scheduling reconnect attempt ${state.reconnectAttempts + 1} in ${delay}ms`);
     state.reconnectTimeout = setTimeout(async () => {
         reconnectScheduled = false;
-        // Double-check we're still online before attempting
+        /* Re-check online status in case we went offline during the backoff wait.
+           This avoids wasting a reconnect attempt on a network that's now down. */
         if (typeof navigator !== 'undefined' && !navigator.onLine) {
             debugLog('[Realtime] Went offline during backoff, cancelling reconnect');
             return;
@@ -321,22 +733,43 @@ function scheduleReconnect() {
         }
     }, delay);
 }
+// =============================================================================
+// LIFECYCLE -- START / STOP / PAUSE
+// =============================================================================
 /**
- * Internal stop function (doesn't check operation lock)
+ * Internal teardown: remove the channel and reset connection state.
+ *
+ * Does **not** acquire the `operationInProgress` lock -- callers are
+ * responsible for holding it. This allows {@link startRealtimeSubscriptions}
+ * to call it mid-operation without deadlocking.
+ *
+ * **Why separate from the public `stopRealtimeSubscriptions`?** The public
+ * version acquires the concurrency lock and clears session-level state (userId,
+ * tracking map). This internal version only handles the channel teardown,
+ * making it safe to call from within `startRealtimeSubscriptions` which
+ * already holds the lock.
+ *
+ * @see {@link stopRealtimeSubscriptions} -- the public API that wraps this
  */
 async function stopRealtimeSubscriptionsInternal() {
-    // Clear reconnect timeout and flag
+    /* Clear any pending reconnect timer and reset the scheduling flag.
+       If we don't clear these, a pending timer could fire after the channel
+       is torn down and attempt to reconnect with stale state. */
     if (state.reconnectTimeout) {
         clearTimeout(state.reconnectTimeout);
         state.reconnectTimeout = null;
     }
     reconnectScheduled = false;
-    // Unsubscribe from channel
+    /* Unsubscribe from the Supabase channel. This sends an unsubscribe
+       message over the WebSocket and cleans up the local channel state. */
     if (state.channel) {
         try {
             await getEngineConfig().supabase.removeChannel(state.channel);
         }
         catch (error) {
+            /* Log but don't rethrow -- we're tearing down and must continue
+               cleanup even if the server-side unsubscribe fails (e.g., the
+               WebSocket is already dead). */
             debugError('[Realtime] Error removing channel:', error);
         }
         state.channel = null;
@@ -345,40 +778,91 @@ async function stopRealtimeSubscriptionsInternal() {
     setConnectionState('disconnected');
 }
 /**
- * Start realtime subscriptions for a user
+ * Start realtime subscriptions for an authenticated user.
+ *
+ * Creates a single Supabase Realtime channel and registers PostgreSQL change
+ * listeners for every table defined in the engine config.
+ *
+ * **Security:** Access control is enforced by Supabase RLS policies at the
+ * database level -- no client-side `user_id` filter is applied to the channel
+ * subscription. The Realtime server evaluates RLS policies for each CDC event
+ * and only delivers events the user is authorized to see.
+ *
+ * This function is idempotent: if the channel is already connected for the
+ * same user, it returns immediately. If a different user is provided, the
+ * existing channel is torn down first.
+ *
+ * **Channel multiplexing:** One channel is created for all tables rather than
+ * one per table. This is more efficient because Supabase multiplexes all
+ * subscriptions over a single WebSocket connection regardless, so separate
+ * channels would only add overhead without improving parallelism.
+ *
+ * @param userId - The authenticated user's UUID. Used to construct a unique
+ *                 channel name (`{prefix}_sync_{userId}`).
+ *
+ * @throws Never throws -- all errors are caught internally. On failure, the
+ *         connection state transitions to `'error'` and reconnection is
+ *         scheduled automatically.
+ *
+ * @example
+ * ```ts
+ * // After login:
+ * await startRealtimeSubscriptions(session.user.id);
+ * ```
+ *
+ * @see {@link stopRealtimeSubscriptions} to cleanly tear down the channel
+ * @see {@link getEngineConfig} for the table configuration consumed here
  */
 export async function startRealtimeSubscriptions(userId) {
+    /* SSR guard: realtime requires a browser environment for WebSocket.
+       In SSR contexts (e.g., SvelteKit server-side rendering), `window` is
+       undefined and we must bail early to avoid runtime errors. */
     if (typeof window === 'undefined')
         return;
-    // Don't start if offline - wait for online event
+    /* Don't attempt connection while offline; the sync engine's `online` event
+       will call us again when connectivity is restored. Attempting to connect
+       while offline would waste a reconnect attempt on an inevitable failure. */
     if (!navigator.onLine) {
         debugLog('[Realtime] Offline - skipping subscription start');
         return;
     }
-    // Don't start if already connected with same user
+    /* Idempotency: skip if already connected for this user. This prevents
+       unnecessary channel teardown/recreation when the caller doesn't track
+       whether we're already connected. */
     if (state.channel && state.userId === userId && state.connectionState === 'connected') {
         return;
     }
-    // Prevent concurrent start/stop operations
+    /* Concurrency guard: prevent overlapping start/stop sequences. Without
+       this, rapid login/logout cycles could interleave async channel operations
+       and leave the module in an inconsistent state. */
     if (operationInProgress) {
         debugLog('[Realtime] Operation already in progress, skipping');
         return;
     }
     operationInProgress = true;
     try {
-        // Stop existing subscriptions first
+        /* Tear down any existing channel before creating a new one. This handles
+           the case where we're switching users (logout + login) or recovering
+           from an error state. */
         await stopRealtimeSubscriptionsInternal();
         state.userId = userId;
         state.deviceId = getDeviceId();
         setConnectionState('connecting');
         const config = getEngineConfig();
         const realtimeTables = config.tables.map((t) => t.supabaseName);
-        // Create a single channel for all tables
-        // Using a unique channel name per user
+        /* ---- Channel creation ----
+           One channel per user, listening to all configured tables. This is more
+           efficient than one channel per table because Supabase multiplexes all
+           subscriptions over a single WebSocket connection regardless. The channel
+           name includes the user ID to ensure uniqueness across browser tabs that
+           might have different users logged in. */
         const channelName = `${config.prefix}_sync_${userId}`;
         state.channel = config.supabase.channel(channelName);
-        // Subscribe to all tables without user_id filter
-        // RLS (Row Level Security) policies handle security at the database level
+        /* ---- Register table listeners ----
+           We subscribe to `event: '*'` (INSERT, UPDATE, DELETE) on each table.
+           No `filter` parameter is used because RLS policies enforce row-level
+           security at the database level. Adding a client-side filter would be
+           redundant and could fall out of sync with the RLS policy definitions. */
         debugLog(`[Realtime] Setting up subscriptions for ${realtimeTables.length} tables`);
         for (const table of realtimeTables) {
             state.channel = state.channel.on('postgres_changes', {
@@ -387,16 +871,24 @@ export async function startRealtimeSubscriptions(userId) {
                 table: table
             }, (payload) => {
                 debugLog(`[Realtime] Raw payload received for ${table}:`, payload.eventType);
+                /* Fire-and-forget: the handler runs asynchronously. Errors are caught
+                   inside handleRealtimeChange so they don't propagate to the Supabase
+                   client's event loop. */
                 handleRealtimeChange(table, payload).catch((error) => {
                     debugError(`[Realtime] Error processing ${table} change:`, error);
                 });
             });
         }
-        // Subscribe to the channel
+        /* ---- Activate the channel ----
+           The status callback handles lifecycle transitions. Note that Supabase
+           may emit multiple statuses for the same underlying event (e.g.,
+           CHANNEL_ERROR followed by CLOSED for a single disconnection). */
         state.channel.subscribe((status, err) => {
             switch (status) {
                 case 'SUBSCRIBED':
                     debugLog('[Realtime] Connected and subscribed');
+                    /* Reset backoff counter on successful connection so the next
+                       disconnection starts fresh with a 1s delay. */
                     state.reconnectAttempts = 0;
                     reconnectScheduled = false;
                     setConnectionState('connected');
@@ -415,10 +907,13 @@ export async function startRealtimeSubscriptions(userId) {
                     break;
                 case 'CLOSED':
                     debugLog('[Realtime] Channel closed');
-                    // Only try to reconnect if:
-                    // 1. We weren't intentionally disconnected
-                    // 2. We have a user
-                    // 3. We're not already scheduled for reconnect (prevents duplicate from CHANNEL_ERROR + CLOSED)
+                    /* Only reconnect if:
+                       1. This wasn't an intentional disconnect (state would be 'disconnected').
+                       2. We still have a user to reconnect for.
+                       3. A reconnect isn't already scheduled (prevents duplicate timers
+                          when CHANNEL_ERROR fires shortly before CLOSED).
+                       Without condition 3, we would schedule two overlapping reconnect
+                       timers for a single disconnection event. */
                     if (state.connectionState !== 'disconnected' && state.userId && !reconnectScheduled) {
                         setConnectionState('disconnected');
                         scheduleReconnect();
@@ -433,14 +928,35 @@ export async function startRealtimeSubscriptions(userId) {
         scheduleReconnect();
     }
     finally {
+        /* Always release the concurrency lock, even on error. Without this,
+           a failed start would permanently block all future start/stop attempts. */
         operationInProgress = false;
     }
 }
 /**
- * Stop realtime subscriptions (public API)
+ * Stop realtime subscriptions and clean up all state.
+ *
+ * This is the public-facing teardown API. It acquires the concurrency lock,
+ * delegates to {@link stopRealtimeSubscriptionsInternal}, clears the user ID,
+ * and wipes the recently-processed tracking map.
+ *
+ * **When to call:** On user logout or app shutdown. For temporary connectivity
+ * loss, use {@link pauseRealtime} instead (it preserves the userId so
+ * reconnection can resume automatically).
+ *
+ * @throws Never throws -- errors during channel removal are caught and logged.
+ *
+ * @example
+ * ```ts
+ * // On logout:
+ * await stopRealtimeSubscriptions();
+ * ```
+ *
+ * @see {@link startRealtimeSubscriptions} to re-establish the connection
+ * @see {@link pauseRealtime} for temporary disconnection (offline)
  */
 export async function stopRealtimeSubscriptions() {
-    // Prevent concurrent operations
+    /* Concurrency guard: prevent overlapping start/stop sequences. */
     if (operationInProgress) {
         debugLog('[Realtime] Operation already in progress, skipping stop');
         return;
@@ -449,7 +965,9 @@ export async function stopRealtimeSubscriptions() {
     try {
         await stopRealtimeSubscriptionsInternal();
         state.userId = null;
-        // Clear recently processed tracking
+        /* Clear tracking so stale entries don't leak across sessions. Without
+           this, a dedup entry from user A's session could cause user B's session
+           (if they log in on the same device) to skip a legitimate change. */
         recentlyProcessedByRealtime.clear();
     }
     finally {
@@ -457,36 +975,42 @@ export async function stopRealtimeSubscriptions() {
     }
 }
 /**
- * Pause realtime (when going offline) - stops reconnection attempts
- * Called by sync engine when offline event fires
+ * Pause realtime subscriptions when the browser goes offline.
+ *
+ * Unlike {@link stopRealtimeSubscriptions}, this does **not** clear
+ * `state.userId` -- the user is still authenticated, we just can't reach
+ * the server. When the browser comes back online, the sync engine calls
+ * {@link startRealtimeSubscriptions} with the same user ID.
+ *
+ * Key behaviors:
+ * - Cancels any pending reconnect timers.
+ * - Resets the reconnect attempt counter so we get a fresh set of attempts
+ *   when connectivity returns.
+ * - Transitions to `'disconnected'` state.
+ *
+ * **Why not call stopRealtimeSubscriptionsInternal?** Because the offline
+ * transition is often transient (e.g., brief WiFi dropout). We want to
+ * preserve the userId and avoid the overhead of `removeChannel()` (which
+ * tries to send an unsubscribe message over the dead WebSocket). Simply
+ * clearing the reconnect state and transitioning to `'disconnected'` is
+ * faster and avoids potential errors from network calls during offline.
+ *
+ * @see {@link ./engine.ts} -- calls this from the `offline` event handler
  */
 export function pauseRealtime() {
-    // Clear any pending reconnect attempts and reset flags
+    /* Cancel any in-flight reconnection timer and reset the flag.
+       Without this, a timer set before the offline event could fire during
+       the offline period and waste a reconnect attempt. */
     if (state.reconnectTimeout) {
         clearTimeout(state.reconnectTimeout);
         state.reconnectTimeout = null;
     }
     reconnectScheduled = false;
-    // Reset reconnect attempts so we get fresh attempts when coming online
+    /* Reset attempts so the next online event gets the full backoff budget.
+       This is more forgiving than carrying over the count: if the user's
+       network flaps repeatedly, they get a full set of 5 attempts each time. */
     state.reconnectAttempts = 0;
     setConnectionState('disconnected');
     debugLog('[Realtime] Paused - waiting for online event');
 }
-/**
- * Check if realtime is healthy (connected and not in error state)
- */
-export function isRealtimeHealthy() {
-    return state.connectionState === 'connected';
-}
-/**
- * Clean up expired entries from recently processed tracking
- */
-export function cleanupRealtimeTracking() {
-    const now = Date.now();
-    for (const [entityId, processedAt] of recentlyProcessedByRealtime) {
-        if (now - processedAt > RECENTLY_MODIFIED_TTL_MS) {
-            recentlyProcessedByRealtime.delete(entityId);
-        }
-    }
-}
 //# sourceMappingURL=realtime.js.map