@syncular/client 0.0.1 → 0.0.2-126

package/dist/create-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-client.js","sourceRoot":"","sources":["../src/create-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,SAAS,+BAA+B,CAAK,IAG5C,EAAe;IACd,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,CAAC,OAAO,CAAC,KAAK,4DAA4D;YACxF,qDAAqD;YACrD,8CACE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAC9C,GAAG,CACN,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;IAC5B,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AAAA,CACpC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAGxB,KAAa,EAAE,MAAgB,EAAqC;IACpE,OAAO,mBAAmB,CAAgB;QACxC,KAAK,EAAE,KAAkB;QACzB,MAAM,EAAE,MAA2B;KACpC,CAAC,CAAC;AAAA,CACJ;AAmFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAgC,EACC;IACjC,MAAM,EACJ,EAAE,EACF,GAAG,GAAG,WAAW,EACjB,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EACN,MAAM,EACN,OAAO,EACP,QAAQ,GAAG,UAAU,EAAE,EACvB,SAAS,EAAE,eAAe,EAC1B,UAAU,EACV,IAAI,GAAG,EAAE,EACT,WAAW,EACX,OAAO,EACP,OAAO,EACP,SAAS,GAAG,IAAI,GACjB,GAAG,OAAO,CAAC;IAEZ,mBAAmB;IACnB,IAAI,CAAC,gBAAgB,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,+CAA+C;IAC/C,MAAM,QAAQ,GACZ,gBAAgB;QAChB,MAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACpB,iBAAiB,CAAwB,KAAK,EAAE,MAAO,CAAC,CACzD,CAAC;IAEJ,qCAAqC;IACrC,MAAM,aAAa,GAAG,IAAI,mBAAmB,EAAM,CAAC;IACpD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,4CAA4C;IAC5C,IAAI,SAAS,GAAG,eAAe,CAAC;IAChC,IAAI,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;QACtB,SAAS,GAAG,mBAAmB,CAAC;YAC9B,OAAO,EAAE,GAAG;YACZ,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,oCAAoC;IACpC,MAAM,aAAa,GAAG,QAAQ;SAC3B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAChB,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC;QAC9B,6CAA6C;QAC7C,IAAI,GAAG,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC;QAE/B,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtC,sEAAsE;YACtE,4EAA4E;YAC5E,MAAM,MAAM,GAAG,+BAA+B,CAAC;gBAC7C,OAAO;gBACP,OAAO;aACR,CAAC,CAAC;YACH,OAAO;gBACL,EAAE,EAAE,OAAO,CAAC,KAAK;gBACjB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,MAAM;gBACN,MAAM,EAAE,EAAE;aACX,CAAC;QACJ,CAAC;QACD,6BAA6B;QAC7B,MAAM,MAAM,GAAgB,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;QAC7C,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,YAAY,OAAO,CAAC,KAAK,yCAAyC;gBAChE,mDAAmD,CACtD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,KAAK;YACjB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;SACzB,CAAC;IAAA,CACH,CAAC;SACD,MAAM,CAAC,CAAC,GAAG,EAAkC,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IAEjE,gBAAgB;IAChB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,EAAE;QACF,SAAS;QACT,aAAa;QACb,QAAQ;QACR,OAAO;QACP,aAAa;QACb,WAAW;QACX,OAAO;QACP,OAAO;QACP,eAAe,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;QACtC,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC,CAAC;IAEH,aAAa;IACb,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,OAAO;QACL,MAAM;QACN,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE;QACzB,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE;KAChC,CAAC;AAAA,CACH"}
+{"version":3,"file":"create-client.js","sourceRoot":"","sources":["../src/create-client.ts"],"names":[],"mappings":"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"}

package/dist/engine/SyncEngine.d.ts

@@ -4,7 +4,7 @@
  * Event-driven sync engine that manages push/pull cycles, connection state,
  * and provides a clean API for framework bindings to consume.
  */
-import type { SyncSubscriptionRequest } from '@syncular/core';
+import { type SyncSubscriptionRequest } from '@syncular/core';
 import { type Kysely } from 'kysely';
 import type { SyncClientDb } from '../schema';
 import type { ConflictInfo, OutboxStats, PresenceEntry, SyncEngineConfig, SyncEngineState, SyncEventListener, SyncEventType, SyncResult } from './types';
@@ -21,12 +21,20 @@ export declare class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     private syncPromise;
     private syncRequestedWhileRunning;
     private retryTimeoutId;
+    private realtimeCatchupTimeoutId;
+    private hasRealtimeConnectedOnce;
     /**
      * In-memory map tracking local mutation timestamps by rowId.
      * Used for efficient fingerprint-based rerender optimization.
      * Key format: `${table}:${rowId}`, Value: timestamp (Date.now())
      */
     private mutationTimestamps;
+    /**
+     * In-memory map tracking table-level mutation timestamps.
+     * Used for coarse invalidation during large bootstrap snapshots to avoid
+     * storing timestamps for every row.
+     */
+    private tableMutationTimestamps;
     /**
      * In-memory presence state by scope key.
      * Updated via realtime presence events.
@@ -118,12 +126,18 @@ export declare class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     /**
      * Trigger a manual sync
      */
-    sync(): Promise<SyncResult>;
+    sync(opts?: {
+        trigger?: 'ws' | 'local' | 'poll';
+    }): Promise<SyncResult>;
     private performSyncLoop;
     private performSyncOnce;
     private extractChangedTables;
+    private applyWsDeliveredChanges;
+    private handleWsDelivery;
     private timestampCounter;
+    private nextPreciseTimestamp;
     private bumpMutationTimestamp;
+    private bumpTableMutationTimestamp;
     /**
      * Record local mutations that were already applied to the DB.
      *
@@ -142,12 +156,20 @@ export declare class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     private recordMutationTimestampsFromPullResponse;
     private scheduleRetry;
     private handleError;
+    private triggerSyncInBackground;
     private setupPolling;
     private stopPolling;
     private setupRealtime;
     private stopRealtime;
+    private scheduleRealtimeReconnectCatchupSync;
     private startFallbackPolling;
     private stopFallbackPolling;
+    /**
+     * Clear all in-memory mutation state and emit data:change so UI re-renders.
+     * Call this after deleting local data (e.g. reset flow) so that React hooks
+     * recompute fingerprints from scratch instead of seeing stale timestamps.
+     */
+    resetLocalState(): void;
     /**
      * Reconnect
      */

package/dist/engine/SyncEngine.d.ts.map

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

package/dist/engine/SyncEngine.js

@@ -4,14 +4,16 @@
  * Event-driven sync engine that manages push/pull cycles, connection state,
  * and provides a clean API for framework bindings to consume.
  */
+import { captureSyncException, countSyncMetric, distributionSyncMetric, isRecord, startSyncSpan, } from '@syncular/core';
 import { sql } from 'kysely';
-import { syncPushOnce } from '../push-engine';
-import { syncOnce } from '../sync-loop';
+import { syncPushOnce } from '../push-engine.js';
+import { syncOnce } from '../sync-loop.js';
 const DEFAULT_POLL_INTERVAL_MS = 10_000;
 const DEFAULT_MAX_RETRIES = 5;
 const INITIAL_RETRY_DELAY_MS = 1000;
 const MAX_RETRY_DELAY_MS = 60000;
 const EXPONENTIAL_FACTOR = 2;
+const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
 function calculateRetryDelay(attemptIndex) {
     return Math.min(INITIAL_RETRY_DELAY_MS * EXPONENTIAL_FACTOR ** attemptIndex, MAX_RETRY_DELAY_MS);
 }
@@ -28,8 +30,8 @@ function createSyncError(code, message, cause) {
         timestamp: Date.now(),
     };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function resolveSyncTriggerLabel(trigger) {
+    return trigger ?? 'auto';
 }
 export class SyncEngine {
     config;
@@ -44,12 +46,20 @@ export class SyncEngine {
     syncPromise = null;
     syncRequestedWhileRunning = false;
     retryTimeoutId = null;
+    realtimeCatchupTimeoutId = null;
+    hasRealtimeConnectedOnce = false;
     /**
      * In-memory map tracking local mutation timestamps by rowId.
      * Used for efficient fingerprint-based rerender optimization.
      * Key format: `${table}:${rowId}`, Value: timestamp (Date.now())
      */
     mutationTimestamps = new Map();
+    /**
+     * In-memory map tracking table-level mutation timestamps.
+     * Used for coarse invalidation during large bootstrap snapshots to avoid
+     * storing timestamps for every row.
+     */
+    tableMutationTimestamps = new Map();
     /**
      * In-memory presence state by scope key.
      * Updated via realtime presence events.
@@ -65,7 +75,9 @@ export class SyncEngine {
      * Returns 0 if row has no recorded mutation timestamp.
      */
     getMutationTimestamp(table, rowId) {
-        return this.mutationTimestamps.get(`${table}:${rowId}`) ?? 0;
+        const rowTs = this.mutationTimestamps.get(`${table}:${rowId}`) ?? 0;
+        const tableTs = this.tableMutationTimestamps.get(table) ?? 0;
+        return Math.max(rowTs, tableTs);
     }
     /**
      * Get presence entries for a scope key.
@@ -187,7 +199,7 @@ export class SyncEngine {
             clientId.length > 0);
     }
     detectTransportMode() {
-        if (this.config.realtimeEnabled &&
+        if (this.config.realtimeEnabled !== false &&
             isRealtimeTransport(this.config.transport)) {
             return 'realtime';
         }
@@ -345,11 +357,15 @@ export class SyncEngine {
             clearTimeout(this.retryTimeoutId);
             this.retryTimeoutId = null;
         }
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+            this.realtimeCatchupTimeoutId = null;
+        }
     }
     /**
      * Trigger a manual sync
      */
-    async sync() {
+    async sync(opts) {
         // Dedupe concurrent sync calls
         if (this.syncPromise) {
             // A sync is already in-flight; queue one more run so we don't miss
@@ -368,7 +384,7 @@ export class SyncEngine {
                 error: createSyncError('SYNC_ERROR', 'Sync not enabled'),
             };
         }
-        this.syncPromise = this.performSyncLoop();
+        this.syncPromise = this.performSyncLoop(opts?.trigger);
         try {
             return await this.syncPromise;
         }
@@ -376,7 +392,7 @@ export class SyncEngine {
             this.syncPromise = null;
         }
     }
-    async performSyncLoop() {
+    async performSyncLoop(trigger) {
         let lastResult = {
             success: false,
             pushedCommits: 0,
@@ -386,7 +402,9 @@ export class SyncEngine {
         };
         do {
             this.syncRequestedWhileRunning = false;
-            lastResult = await this.performSyncOnce();
+            lastResult = await this.performSyncOnce(trigger);
+            // After the first iteration, clear trigger context
+            trigger = undefined;
             // If the sync failed, let retry logic handle backoff instead of tight looping.
             if (!lastResult.success)
                 break;
@@ -395,22 +413,34 @@ export class SyncEngine {
             this.isEnabled());
         return lastResult;
     }
-    async performSyncOnce() {
+    async performSyncOnce(trigger) {
         const timestamp = Date.now();
+        const startedAtMs = timestamp;
+        const triggerLabel = resolveSyncTriggerLabel(trigger);
         this.updateState({ isSyncing: true });
         this.emit('sync:start', { timestamp });
+        countSyncMetric('sync.client.sync.attempts', 1, {
+            attributes: { trigger: triggerLabel },
+        });
         try {
             const pullApplyTimestamp = Date.now();
-            const result = await syncOnce(this.config.db, this.config.transport, this.config.shapes, {
+            const result = await startSyncSpan({
+                name: 'sync.client.sync',
+                op: 'sync.client.sync',
+                attributes: { trigger: triggerLabel },
+            }, () => syncOnce(this.config.db, this.config.transport, this.config.handlers, {
                 clientId: this.config.clientId,
                 actorId: this.config.actorId ?? undefined,
                 plugins: this.config.plugins,
-                subscriptions: this.config.subscriptions,
+                subscriptions: this.config
+                    .subscriptions,
                 limitCommits: this.config.limitCommits,
                 limitSnapshotRows: this.config.limitSnapshotRows,
                 maxSnapshotPages: this.config.maxSnapshotPages,
                 stateId: this.config.stateId,
-            });
+                sha256: this.config.sha256,
+                trigger,
+            }));
             const syncResult = {
                 success: true,
                 pushedCommits: result.pushedCommits,
@@ -442,8 +472,30 @@ export class SyncEngine {
                 });
                 this.config.onDataChange?.(changedTables);
             }
-            // Refresh outbox stats
-            await this.refreshOutboxStats();
+            // Refresh outbox stats (fire-and-forget — don't block sync:complete)
+            this.refreshOutboxStats().catch((error) => {
+                console.warn('[SyncEngine] Failed to refresh outbox stats after sync:', error);
+            });
+            const durationMs = Math.max(0, Date.now() - startedAtMs);
+            countSyncMetric('sync.client.sync.results', 1, {
+                attributes: {
+                    trigger: triggerLabel,
+                    status: 'success',
+                },
+            });
+            distributionSyncMetric('sync.client.sync.duration_ms', durationMs, {
+                unit: 'millisecond',
+                attributes: {
+                    trigger: triggerLabel,
+                    status: 'success',
+                },
+            });
+            distributionSyncMetric('sync.client.sync.pushed_commits', result.pushedCommits, {
+                attributes: { trigger: triggerLabel },
+            });
+            distributionSyncMetric('sync.client.sync.pull_rounds', result.pullRounds, {
+                attributes: { trigger: triggerLabel },
+            });
             return syncResult;
         }
         catch (err) {
@@ -455,6 +507,24 @@ export class SyncEngine {
                 isRetrying: false,
             });
             this.handleError(error);
+            const durationMs = Math.max(0, Date.now() - startedAtMs);
+            countSyncMetric('sync.client.sync.results', 1, {
+                attributes: {
+                    trigger: triggerLabel,
+                    status: 'error',
+                },
+            });
+            distributionSyncMetric('sync.client.sync.duration_ms', durationMs, {
+                unit: 'millisecond',
+                attributes: {
+                    trigger: triggerLabel,
+                    status: 'error',
+                },
+            });
+            captureSyncException(err, {
+                event: 'sync.client.sync',
+                trigger: triggerLabel,
+            });
             // Schedule retry if under max retries
             const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
             if (this.state.retryCount < maxRetries) {
@@ -489,16 +559,141 @@ export class SyncEngine {
         }
         return Array.from(tables);
     }
+    /**
+     * Apply changes delivered inline over WebSocket for instant UI updates.
+     * Returns true if changes were applied and cursor updated successfully,
+     * false if anything failed (caller should fall back to HTTP sync).
+     */
+    async applyWsDeliveredChanges(changes, cursor) {
+        try {
+            await this.config.db.transaction().execute(async (trx) => {
+                for (const change of changes) {
+                    const handler = this.config.handlers.get(change.table);
+                    if (!handler) {
+                        throw new Error(`Missing client table handler for WS change table "${change.table}"`);
+                    }
+                    await handler.applyChange({ trx }, change);
+                }
+                // Update subscription cursors
+                const stateId = this.config.stateId ?? 'default';
+                await sql `
+          update ${sql.table('sync_subscription_state')}
+          set ${sql.ref('cursor')} = ${sql.val(cursor)}
+          where ${sql.ref('state_id')} = ${sql.val(stateId)}
+            and ${sql.ref('cursor')} < ${sql.val(cursor)}
+        `.execute(trx);
+            });
+            // Update mutation timestamps BEFORE emitting data:change so that
+            // React hooks re-querying the DB see fresh fingerprints immediately.
+            const now = Date.now();
+            for (const change of changes) {
+                if (!change.table || !change.row_id)
+                    continue;
+                if (change.op === 'delete') {
+                    this.mutationTimestamps.delete(`${change.table}:${change.row_id}`);
+                }
+                else {
+                    this.bumpMutationTimestamp(change.table, change.row_id, now);
+                }
+            }
+            // Emit data change for immediate UI update
+            const changedTables = [...new Set(changes.map((c) => c.table))];
+            if (changedTables.length > 0) {
+                this.emit('data:change', {
+                    scopes: changedTables,
+                    timestamp: Date.now(),
+                });
+                this.config.onDataChange?.(changedTables);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Handle WS-delivered changes: apply them and decide whether to skip HTTP pull.
+     * Falls back to full HTTP sync when conditions require it.
+     */
+    async handleWsDelivery(changes, cursor) {
+        // If a sync is already in-flight, let it handle everything
+        if (this.syncPromise) {
+            countSyncMetric('sync.client.ws.delivery.events', 1, {
+                attributes: { path: 'inflight_sync' },
+            });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws delivery with in-flight sync');
+            return;
+        }
+        // If there are pending outbox commits, need to push via HTTP
+        if (this.state.pendingCount > 0) {
+            countSyncMetric('sync.client.ws.delivery.events', 1, {
+                attributes: { path: 'pending_outbox' },
+            });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws delivery with pending outbox');
+            return;
+        }
+        // If afterPull plugins exist, inline WS changes may require transforms
+        // (e.g. decryption). Fall back to HTTP sync and do not apply inline payload.
+        const hasAfterPullPlugins = this.config.plugins?.some((p) => typeof p.afterPull === 'function');
+        if (hasAfterPullPlugins) {
+            countSyncMetric('sync.client.ws.delivery.events', 1, {
+                attributes: { path: 'after_pull_plugins' },
+            });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws delivery with afterPull plugins');
+            return;
+        }
+        // Apply changes + update cursor
+        const inlineApplyStartedAtMs = Date.now();
+        const applied = await this.applyWsDeliveredChanges(changes, cursor);
+        const inlineApplyDurationMs = Math.max(0, Date.now() - inlineApplyStartedAtMs);
+        distributionSyncMetric('sync.client.ws.inline_apply.duration_ms', inlineApplyDurationMs, {
+            unit: 'millisecond',
+        });
+        if (!applied) {
+            countSyncMetric('sync.client.ws.delivery.events', 1, {
+                attributes: { path: 'inline_fallback' },
+            });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws inline apply fallback');
+            return;
+        }
+        // All clear — skip HTTP pull entirely
+        countSyncMetric('sync.client.ws.delivery.events', 1, {
+            attributes: { path: 'inline_applied' },
+        });
+        this.updateState({
+            lastSyncAt: Date.now(),
+            error: null,
+            retryCount: 0,
+            isRetrying: false,
+        });
+        this.emit('sync:complete', {
+            timestamp: Date.now(),
+            pushedCommits: 0,
+            pullRounds: 0,
+            pullResponse: { ok: true, subscriptions: [] },
+        });
+        this.refreshOutboxStats().catch((error) => {
+            console.warn('[SyncEngine] Failed to refresh outbox stats after WS apply:', error);
+        });
+    }
     timestampCounter = 0;
-    bumpMutationTimestamp(table, rowId, now) {
-        const key = `${table}:${rowId}`;
+    nextPreciseTimestamp(now) {
         // Use sub-millisecond precision by combining timestamp with atomic counter
         // This prevents race conditions in concurrent mutations while maintaining
-        // millisecond-level compatibility with existing code
-        const preciseNow = now + (this.timestampCounter++ % 1000) / 1000;
+        // millisecond-level compatibility with existing code.
+        return now + (this.timestampCounter++ % 1000) / 1000;
+    }
+    bumpMutationTimestamp(table, rowId, now) {
+        const key = `${table}:${rowId}`;
+        const preciseNow = this.nextPreciseTimestamp(now);
         const prev = this.mutationTimestamps.get(key) ?? 0;
         this.mutationTimestamps.set(key, Math.max(preciseNow, prev + 0.001));
     }
+    bumpTableMutationTimestamp(table, now) {
+        const preciseNow = this.nextPreciseTimestamp(now);
+        const prev = this.tableMutationTimestamps.get(table) ?? 0;
+        this.tableMutationTimestamps.set(table, Math.max(preciseNow, prev + 0.001));
+    }
     /**
      * Record local mutations that were already applied to the DB.
      *
@@ -531,17 +726,12 @@ export class SyncEngine {
     }
     recordMutationTimestampsFromPullResponse(response, now) {
         for (const sub of response.subscriptions ?? []) {
-            // Mark snapshot rows as changed so bootstrap/resnapshot updates propagate
-            // in wa-sqlite mode.
+            // Mark snapshot tables as changed so bootstrap/resnapshot updates
+            // propagate without storing per-row timestamps for massive snapshots.
             for (const snapshot of sub.snapshots ?? []) {
-                const table = snapshot.table;
-                for (const row of snapshot.rows ?? []) {
-                    // Snapshot rows are untyped - access id dynamically
-                    const id = row?.id;
-                    if (id == null)
-                        continue;
-                    this.bumpMutationTimestamp(table, String(id), now);
-                }
+                if (!snapshot.table)
+                    continue;
+                this.bumpTableMutationTimestamp(snapshot.table, now);
             }
             for (const commit of sub.commits ?? []) {
                 for (const change of commit.changes ?? []) {
@@ -568,7 +758,7 @@ export class SyncEngine {
         this.retryTimeoutId = setTimeout(() => {
             this.retryTimeoutId = null;
             if (!this.isDestroyed) {
-                this.sync();
+                this.triggerSyncInBackground(undefined, 'retry timer');
             }
         }, delay);
     }
@@ -576,12 +766,17 @@ export class SyncEngine {
         this.emit('sync:error', error);
         this.config.onError?.(error);
     }
+    triggerSyncInBackground(opts, reason = 'background') {
+        void this.sync(opts).catch((error) => {
+            console.error(`[SyncEngine] Unexpected sync failure during ${reason}:`, error);
+        });
+    }
     setupPolling() {
         this.stopPolling();
         const interval = this.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.pollerId = setInterval(() => {
             if (!this.state.isSyncing && !this.isDestroyed) {
-                this.sync();
+                this.triggerSyncInBackground(undefined, 'polling interval');
             }
         }, interval);
         this.setConnectionState('connected');
@@ -622,15 +817,36 @@ export class SyncEngine {
         }
         this.realtimeDisconnect = transport.connect({ clientId: this.config.clientId }, (event) => {
             if (event.event === 'sync') {
-                this.sync();
+                countSyncMetric('sync.client.ws.events', 1, {
+                    attributes: { type: 'sync' },
+                });
+                const hasInlineChanges = Array.isArray(event.data.changes) && event.data.changes.length > 0;
+                const cursor = event.data.cursor;
+                if (hasInlineChanges && typeof cursor === 'number') {
+                    // WS delivered changes + cursor — may skip HTTP pull
+                    this.handleWsDelivery(event.data.changes, cursor);
+                }
+                else {
+                    // Cursor-only wake-up or no cursor — must HTTP sync
+                    countSyncMetric('sync.client.ws.delivery.events', 1, {
+                        attributes: { path: 'cursor_wakeup' },
+                    });
+                    this.triggerSyncInBackground({ trigger: 'ws' }, 'ws cursor wakeup');
+                }
             }
         }, (state) => {
             switch (state) {
-                case 'connected':
+                case 'connected': {
+                    const wasConnectedBefore = this.hasRealtimeConnectedOnce;
+                    this.hasRealtimeConnectedOnce = true;
                     this.setConnectionState('connected');
                     this.stopFallbackPolling();
-                    this.sync();
+                    this.triggerSyncInBackground(undefined, 'realtime connected state');
+                    if (wasConnectedBefore) {
+                        this.scheduleRealtimeReconnectCatchupSync();
+                    }
                     break;
+                }
                 case 'connecting':
                     this.setConnectionState('connecting');
                     break;
@@ -642,6 +858,10 @@ export class SyncEngine {
         });
     }
     stopRealtime() {
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+            this.realtimeCatchupTimeoutId = null;
+        }
         if (this.realtimePresenceUnsub) {
             this.realtimePresenceUnsub();
             this.realtimePresenceUnsub = null;
@@ -652,13 +872,26 @@ export class SyncEngine {
         }
         this.stopFallbackPolling();
     }
+    scheduleRealtimeReconnectCatchupSync() {
+        if (this.realtimeCatchupTimeoutId) {
+            clearTimeout(this.realtimeCatchupTimeoutId);
+        }
+        this.realtimeCatchupTimeoutId = setTimeout(() => {
+            this.realtimeCatchupTimeoutId = null;
+            if (this.isDestroyed || !this.isEnabled())
+                return;
+            if (this.state.connectionState !== 'connected')
+                return;
+            this.triggerSyncInBackground(undefined, 'realtime reconnect catchup');
+        }, REALTIME_RECONNECT_CATCHUP_DELAY_MS);
+    }
     startFallbackPolling() {
         if (this.fallbackPollerId)
             return;
         const interval = this.config.realtimeFallbackPollMs ?? 30_000;
         this.fallbackPollerId = setInterval(() => {
             if (!this.state.isSyncing && !this.isDestroyed) {
-                this.sync();
+                this.triggerSyncInBackground(undefined, 'realtime fallback poll');
             }
         }, interval);
     }
@@ -668,6 +901,23 @@ export class SyncEngine {
             this.fallbackPollerId = null;
         }
     }
+    /**
+     * Clear all in-memory mutation state and emit data:change so UI re-renders.
+     * Call this after deleting local data (e.g. reset flow) so that React hooks
+     * recompute fingerprints from scratch instead of seeing stale timestamps.
+     */
+    resetLocalState() {
+        const tables = [...this.tableMutationTimestamps.keys()];
+        this.mutationTimestamps.clear();
+        this.tableMutationTimestamps.clear();
+        if (tables.length > 0) {
+            this.emit('data:change', {
+                scopes: tables,
+                timestamp: Date.now(),
+            });
+            this.config.onDataChange?.(tables);
+        }
+    }
     /**
      * Reconnect
      */
@@ -688,10 +938,7 @@ export class SyncEngine {
         // Polling mode: restart the poller and trigger a sync immediately.
         if (this.state.transportMode === 'polling') {
             this.setupPolling();
-            // Trigger sync in background - errors are handled internally by sync()
-            this.sync().catch((err) => {
-                console.error('Unexpected error during reconnect sync:', err);
-            });
+            this.triggerSyncInBackground(undefined, 'reconnect');
         }
     }
     /**
@@ -825,7 +1072,7 @@ export class SyncEngine {
     updateSubscriptions(subscriptions) {
         this.config.subscriptions = subscriptions;
         // Trigger a sync to apply new subscriptions
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'subscription update');
     }
     /**
      * Apply local mutations immediately to the database and emit change events.
@@ -833,12 +1080,12 @@ export class SyncEngine {
      */
     async applyLocalMutation(inputs) {
         const db = this.config.db;
-        const shapes = this.config.shapes;
+        const handlers = this.config.handlers;
         const affectedTables = new Set();
         const now = Date.now();
         await db.transaction().execute(async (trx) => {
             for (const input of inputs) {
-                const handler = shapes.get(input.table);
+                const handler = handlers.get(input.table);
                 if (!handler)
                     continue;
                 affectedTables.add(input.table);