cry-synced-db-client 0.1.140 → 0.1.143

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 ## Unreleased
 
+### `getDirtyMeta()` for lightweight dirty-state inspection
+
+- New `SyncedDb.getDirtyMeta()` returns dirty-entry meta (everything except the
+  `changes` payload) grouped per collection, only for collections with ≥1 dirty
+  record. Mirrors `getDirty()` shape but avoids loading change payloads —
+  useful for counts, timestamps, and indicator UIs.
+- New `I_DexieDb.getDirtyMeta(collection)` returning `DirtyMeta[]`.
+- New exported `DirtyMeta` type (`Omit<DirtyChange, "changes">`) and
+  `DirtyChange` type surfaced from the package entry.
+
+### Fix: multi-tab divergence when offline edits cross leader/follower
+
+Fixes a bug where, after both tabs edited different records offline and came
+online with leader-first, the leader ended up with stale record content
+carrying the new server `_rev`. Because `resolveConflict` ignores server
+echoes with equal-or-lower `_rev`, the divergence was permanent until page
+reload. Follower-first came out clean; leader-first did not.
+
+Two contributing causes, both fixed:
+
+- `SyncEngine` post-upload in-mem patch no longer spreads stale `getInMemById`
+  result over server-returned `_rev`/`_ts`. In-mem is now fed the freshly
+  patched Dexie item (authoritative content + server meta), so the tab that
+  uploaded on behalf of another tab's dirty write ends up with matching
+  content and `_rev` in-mem.
+- `CrossTabSyncManager.broadcastMetaUpdate` no longer gated by `isLeader()`.
+  Non-leader tabs now broadcast their local writes so the leader's in-mem
+  cache learns of them via the existing shared-Dexie reload path. Reload
+  broadcasts (post-full-sync) remain leader-only.
+
+### BREAKING: Self-healing sync/reconnect lifecycle
+
+Fixes a class of bugs where the 60s auto-sync scheduler silently died after a
+sync failure or leader flap and was never re-armed until a page reload (see
+`/tmp/cry-synced-db-client-sync-interval-bug.md`). Reproducers spanned 5
+tenants, 62–296 min of dead scheduler with dirty items accumulating.
+
+- Removed `onForcedOffline` callback and `ConnectionManager.goOffline()` method.
+- Added `onSyncFailed(reason)` callback — fires on each sync failure but does
+  **not** mutate online state. The next auto-sync / reconnect tick retries.
+- Added `onlineRetryIntervalMs` config (default 60000, 0 = disable) — periodic
+  `tryGoOnline()` probe while offline but not forcedOffline. Always-live from
+  `init()` to `close()` so recovery does not depend on external signals.
+- `autoSyncTimer` and the new reconnect timer are both always-live from `init()`
+  to `close()`. `setOnline(false)`, `forceOffline(true)`, and sync failure no
+  longer clear timers — only flip flags; each tick is defensive.
+- `SyncedDb.sync()` now opportunistically calls `tryGoOnline()` when internally
+  offline (but not forcedOffline). Syncs while `forceOffline(true)` still throw
+  `Cannot sync while in forced offline mode`.
+- `onBecameLeader` now triggers `tryGoOnline()` when offline and post-init,
+  covering visibility re-claim and leader flap after mobile browser discards
+  state.
+- `syncLock` is now acquired before the early `tryGoOnline()` in
+  `SyncedDb.sync()` so the internal `INITIAL SYNC` that `tryGoOnline()` kicks
+  off is a no-op inside the outer call (avoids double sync).
+
+**Migration for consumers:**
+`onForcedOffline: (reason) => log(reason)` → `onSyncFailed: (reason) => log(reason)`.
+Signature is identical. No other callback changes.
+
 - Add `refreshInBackground` `QueryOpts` option for `findById` / `findByIds`
   - Stale-while-revalidate: cache-hit returns local result immediately and
     triggers a background fetch that updates Dexie + in-mem through conflict

package/dist/index.js

@@ -634,13 +634,14 @@ var CrossTabSyncManager = class {
   }
   /**
    * Broadcast updated IDs to other tabs (debounced).
-   * Only the leader should broadcast.
+   * Any tab with local writes broadcasts so other tabs refresh their in-mem
+   * from shared Dexie. Otherwise non-leader writes stay invisible to the leader's
+   * in-mem cache, and a later upload patches new _rev onto stale content.
    * While a server sync is in progress, suppresses delta broadcasts and only
    * records which collections were affected (for the post-sync reload broadcast).
    */
   broadcastMetaUpdate(updates) {
     if (!this.metaUpdateChannel) return;
-    if (!this.deps.isLeader()) return;
     if (this.serverSyncInProgress) {
       for (const collection of Object.keys(updates)) {
         this.syncAffectedCollections.add(collection);
@@ -842,46 +843,41 @@ var CrossTabSyncManager = class {
 };
 
 // src/db/managers/ConnectionManager.ts
+var DEFAULT_ONLINE_RETRY_INTERVAL_MS = 6e4;
 var ConnectionManager = class {
   constructor(config) {
     this.online = false;
     this.forcedOffline = false;
+    this.tryGoOnlineInFlight = false;
+    this.closed = false;
+    var _a;
     this.restInterface = config.restInterface;
     this.restTimeoutMs = config.restTimeoutMs;
     this.syncTimeoutMs = config.syncTimeoutMs;
     this.autoSyncIntervalMs = config.autoSyncIntervalMs;
+    this.onlineRetryIntervalMs = (_a = config.onlineRetryIntervalMs) != null ? _a : DEFAULT_ONLINE_RETRY_INTERVAL_MS;
     this.callbacks = config.callbacks;
     this.deps = config.deps;
   }
-  /**
-   * Current online status (considering forcedOffline).
-   */
+  /** Current online status (considering forcedOffline). */
   isOnline() {
     return this.online && !this.forcedOffline;
   }
-  /**
-   * Is forced offline mode active?
-   */
   isForcedOffline() {
     return this.forcedOffline;
   }
-  /**
-   * Can we sync with server?
-   */
   canSync() {
     return this.online && !this.forcedOffline;
   }
-  /**
-   * Can we receive server updates?
-   */
   canReceiveServerUpdates() {
     return !this.forcedOffline;
   }
   /**
-   * Set online status.
-   * Note: Going offline does NOT release leadership. With window-scoped locks,
-   * a tab should remain leader within its window to process WebSocket notifications
-   * even while offline.
+   * Set online status. Does NOT stop any timers.
+   *
+   * - `setOnline(true)` attempts `tryGoOnline` (ping → flip state).
+   * - `setOnline(false)` flips state to offline and fires `onOnlineStatusChange`.
+   *   The reconnect timer will continue attempting to come back online.
    */
   async setOnline(online) {
     var _a, _b;
@@ -889,19 +885,19 @@ var ConnectionManager = class {
     if (online) {
       await this.tryGoOnline();
     } else {
-      this.online = online;
-      this.stopAutoSync();
+      this.online = false;
       (_b = (_a = this.callbacks).onOnlineStatusChange) == null ? void 0 : _b.call(_a, false);
     }
   }
   /**
-   * Force offline mode.
+   * Force offline mode. Does NOT stop timers — reconnect timer will still
+   * check `forcedOffline` and skip while true. When released, `tryGoOnline`
+   * fires immediately to avoid waiting for the next tick.
    */
   forceOffline(forced) {
     if (this.forcedOffline === forced) return;
     this.forcedOffline = forced;
     if (forced) {
-      this.stopAutoSync();
       this.deps.releaseLeaderLock();
     } else {
       this.deps.tryBecomeLeader();
@@ -911,50 +907,86 @@ var ConnectionManager = class {
     }
   }
   /**
-   * Go offline with reason.
-   * Note: This does NOT release leadership. With window-scoped locks,
-   * a tab should remain leader within its window to process WebSocket notifications
-   * even while offline due to network issues.
+   * Attempt to transition from offline to online.
+   * Idempotent, guards against concurrent calls and forcedOffline.
    */
-  goOffline(reason) {
-    var _a, _b;
-    const wasOnline = this.online;
-    this.online = false;
-    this.stopAutoSync();
-    if (wasOnline) {
-      (_b = (_a = this.callbacks).onOnlineStatusChange) == null ? void 0 : _b.call(_a, false);
-    }
-    if (this.callbacks.onForcedOffline) {
+  async tryGoOnline() {
+    var _a, _b, _c;
+    if (this.closed) return;
+    if (this.forcedOffline) return;
+    if (this.tryGoOnlineInFlight) return;
+    this.tryGoOnlineInFlight = true;
+    try {
+      const wasOffline = !this.online;
+      if (wasOffline) {
+        let pingResult;
+        try {
+          pingResult = await this.withSyncTimeout(
+            this.restInterface.ping(),
+            "ping"
+          );
+        } catch (err) {
+          console.warn("tryGoOnline: ping failed:", err);
+          this.online = false;
+          return;
+        }
+        if (!pingResult) {
+          const url = (_a = this.restInterface.endpoint) != null ? _a : "unknown";
+          console.warn(`Ping to ${url} failed - staying offline`);
+          return;
+        }
+        this.online = true;
+        (_c = (_b = this.callbacks).onOnlineStatusChange) == null ? void 0 : _c.call(_b, true);
+        if (!this.deps.isLeader()) {
+          this.deps.tryBecomeLeader();
+        }
+      }
       try {
-        this.callbacks.onForcedOffline(reason);
+        await this.deps.sync("INITIAL SYNC");
       } catch (err) {
-        console.error("onForcedOffline callback failed:", err);
+        console.warn("INITIAL SYNC after tryGoOnline failed (stays online):", err);
       }
+    } finally {
+      this.tryGoOnlineInFlight = false;
     }
   }
   /**
-   * Start auto-sync timer.
+   * Start both timers. Idempotent. Called by SyncedDb.init().
    */
-  startAutoSync() {
-    this.stopAutoSync();
-    if (this.forcedOffline || !this.autoSyncIntervalMs || this.autoSyncIntervalMs <= 0) {
-      return;
+  startTimers() {
+    this.closed = false;
+    if (!this.autoSyncTimer && this.autoSyncIntervalMs && this.autoSyncIntervalMs > 0) {
+      const intervalMs = this.autoSyncIntervalMs;
+      this.autoSyncTimer = setInterval(() => {
+        if (this.forcedOffline || !this.online) return;
+        this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
+          console.error("Auto-sync failed:", err);
+        });
+      }, intervalMs);
+    }
+    if (!this.reconnectTimer && this.onlineRetryIntervalMs && this.onlineRetryIntervalMs > 0) {
+      const retryMs = this.onlineRetryIntervalMs;
+      this.reconnectTimer = setInterval(() => {
+        if (this.forcedOffline || this.online || this.tryGoOnlineInFlight) return;
+        this.tryGoOnline().catch((err) => {
+          console.error("Reconnect tryGoOnline failed:", err);
+        });
+      }, retryMs);
     }
-    const intervalMs = this.autoSyncIntervalMs;
-    this.autoSyncTimer = setInterval(() => {
-      this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
-        console.error("Auto-sync failed:", err);
-      });
-    }, intervalMs);
   }
   /**
-   * Stop auto-sync timer.
+   * Stop both timers. Called by SyncedDb.close().
    */
-  stopAutoSync() {
+  stopTimers() {
+    this.closed = true;
     if (this.autoSyncTimer) {
       clearInterval(this.autoSyncTimer);
       this.autoSyncTimer = void 0;
     }
+    if (this.reconnectTimer) {
+      clearInterval(this.reconnectTimer);
+      this.reconnectTimer = void 0;
+    }
   }
   /**
    * Ping server.
@@ -1025,6 +1057,19 @@ var ConnectionManager = class {
       }
     }
   }
+  /**
+   * Notify consumers of a sync failure. Does not mutate state.
+   * Called from SyncEngine via deps.onSyncFailed wiring.
+   */
+  callOnSyncFailed(reason) {
+    if (this.callbacks.onSyncFailed) {
+      try {
+        this.callbacks.onSyncFailed(reason);
+      } catch (err) {
+        console.error("onSyncFailed callback failed:", err);
+      }
+    }
+  }
   /**
    * Call onWsConnect callback.
    */
@@ -1083,43 +1128,6 @@ var ConnectionManager = class {
   getOnWsReconnect() {
     return this.callbacks.onWsReconnect;
   }
-  // ============================================================
-  // Private Methods
-  // ============================================================
-  async tryGoOnline() {
-    var _a, _b, _c, _d, _e;
-    if (this.forcedOffline) {
-      return;
-    }
-    try {
-      const pingResult = await this.withSyncTimeout(
-        this.restInterface.ping(),
-        "ping"
-      );
-      if (!pingResult) {
-        const url = (_a = this.restInterface.endpoint) != null ? _a : "unknown";
-        console.warn(`Ping to ${url} failed - staying offline`);
-        return;
-      }
-      const wasOffline = !this.online;
-      this.online = true;
-      if (wasOffline) {
-        (_c = (_b = this.callbacks).onOnlineStatusChange) == null ? void 0 : _c.call(_b, true);
-        if (!this.deps.isLeader()) {
-          this.deps.tryBecomeLeader();
-        }
-      }
-      this.startAutoSync();
-      await this.deps.sync("INITIAL SYNC");
-    } catch (err) {
-      console.warn("Failed to go online (ping failed or timed out):", err);
-      const wasOnline = this.online;
-      this.online = false;
-      if (wasOnline) {
-        (_e = (_d = this.callbacks).onOnlineStatusChange) == null ? void 0 : _e.call(_d, false);
-      }
-    }
-  }
 };
 
 // node_modules/superjson/dist/double-indexed-kv.js
@@ -2541,8 +2549,8 @@ var _SyncEngine = class _SyncEngine {
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      console.error("Sync failed, going offline:", err);
-      this.deps.goOffline(`Sync failed: ${reason}`);
+      console.error("Sync failed:", err);
+      this.deps.onSyncFailed(`Sync failed: ${reason}`);
       this.callOnSyncEnd({
         durationMs: Date.now() - startTime,
         receivedCount,
@@ -2661,13 +2669,7 @@ var _SyncEngine = class _SyncEngine {
                 dexieDeleteIds.push(entity._id);
               } else {
                 dexieSaveBatch.push(dexieItem);
-                const inMemItem = this.deps.getInMemById(collection, entity._id);
-                if (inMemItem) {
-                  inMemUpdateBatch.push(__spreadProps(__spreadValues({}, inMemItem), {
-                    _rev: entity._rev,
-                    _ts: entity._ts
-                  }));
-                }
+                inMemUpdateBatch.push(dexieItem);
               }
             }
           }
@@ -3511,7 +3513,20 @@ var _SyncedDb = class _SyncedDb {
       tenant: this.tenant,
       windowId,
       callbacks: {
-        onBecameLeader: config.onBecameLeader,
+        onBecameLeader: () => {
+          if (this.initialized && !this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
+            this.connectionManager.tryGoOnline().catch((err) => {
+              console.error("tryGoOnline on becameLeader failed:", err);
+            });
+          }
+          if (config.onBecameLeader) {
+            try {
+              config.onBecameLeader();
+            } catch (err) {
+              console.error("onBecameLeader callback failed:", err);
+            }
+          }
+        },
         onLostLeadership: config.onLostLeadership,
         onInfrastructureError: config.onInfrastructureError ? (type, message, error) => {
           config.onInfrastructureError({
@@ -3556,9 +3571,10 @@ var _SyncedDb = class _SyncedDb {
       restTimeoutMs: (_h = config.restTimeoutMs) != null ? _h : 9e4,
       syncTimeoutMs: (_i = config.syncTimeoutMs) != null ? _i : 12e4,
       autoSyncIntervalMs: config.autoSyncIntervalMs,
+      onlineRetryIntervalMs: config.onlineRetryIntervalMs,
       callbacks: {
         onOnlineStatusChange: config.onOnlineStatusChange,
-        onForcedOffline: config.onForcedOffline,
+        onSyncFailed: config.onSyncFailed,
         onWsConnect: config.onWsConnect,
         onWsDisconnect: config.onWsDisconnect,
         onWsReconnect: config.onWsReconnect,
@@ -3628,7 +3644,7 @@ var _SyncedDb = class _SyncedDb {
         },
         getInMemById: (collection, id) => this.inMemDb.getById(collection, id),
         withSyncTimeout: (promise, operation) => this.connectionManager.withSyncTimeout(promise, operation),
-        goOffline: (reason) => this.connectionManager.goOffline(reason),
+        onSyncFailed: (reason) => this.connectionManager.callOnSyncFailed(reason),
         flushAllPendingChanges: () => this.pendingChanges.flushAll(),
         cancelRestUploadTimer: () => this.pendingChanges.cancelRestUploadTimer(),
         awaitRestUpload: () => this.pendingChanges.awaitRestUpload(),
@@ -3769,6 +3785,7 @@ var _SyncedDb = class _SyncedDb {
     this.crossTabSync.init();
     (_a = this.wakeSync) == null ? void 0 : _a.init();
     (_b = this.networkStatus) == null ? void 0 : _b.init();
+    this.connectionManager.startTimers();
     if (this.serverUpdateNotifier) {
       if (this.serverUpdateNotifier.setCallbacks) {
         const cleanup = this.serverUpdateNotifier.setCallbacks({
@@ -3875,7 +3892,7 @@ var _SyncedDb = class _SyncedDb {
     var _a, _b;
     this.leaderElection.setClosing(true);
     this.pendingChanges.cancelRestUploadTimer();
-    this.connectionManager.stopAutoSync();
+    this.connectionManager.stopTimers();
     await this.pendingChanges.flushAll();
     (_a = this.networkStatus) == null ? void 0 : _a.dispose();
     (_b = this.wakeSync) == null ? void 0 : _b.dispose();
@@ -4423,39 +4440,45 @@ var _SyncedDb = class _SyncedDb {
   }
   // ==================== Sync Operations ====================
   async sync(calledFrom) {
-    if (!this.connectionManager.canSync()) {
-      if (this.connectionManager.isForcedOffline()) {
-        throw new Error("Cannot sync while in forced offline mode");
-      }
-      return;
-    }
     if (this.syncLock) return;
     this.syncLock = true;
-    this.syncing = true;
-    this.crossTabSync.startServerSync();
     try {
-      await this.syncEngine.sync(calledFrom);
-      if (!this.syncOnlyCollections) {
-        const now = /* @__PURE__ */ new Date();
-        if (!this._lastFullSyncDate) {
-          this._setLastInitialSync(now).catch((err) => {
-            console.error("Failed to persist lastInitialSync:", err);
+      if (!this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
+        await this.connectionManager.tryGoOnline();
+      }
+      if (!this.connectionManager.canSync()) {
+        if (this.connectionManager.isForcedOffline()) {
+          throw new Error("Cannot sync while in forced offline mode");
+        }
+        return;
+      }
+      this.syncing = true;
+      this.crossTabSync.startServerSync();
+      try {
+        await this.syncEngine.sync(calledFrom);
+        if (!this.syncOnlyCollections) {
+          const now = /* @__PURE__ */ new Date();
+          if (!this._lastFullSyncDate) {
+            this._setLastInitialSync(now).catch((err) => {
+              console.error("Failed to persist lastInitialSync:", err);
+            });
+          }
+          this._setLastFullSync(now).catch((err) => {
+            console.error("Failed to persist lastFullSync:", err);
           });
         }
-        this._setLastFullSync(now).catch((err) => {
-          console.error("Failed to persist lastFullSync:", err);
-        });
+      } finally {
+        this.syncing = false;
+        this.crossTabSync.endServerSync();
+        await this.processQueuedWsUpdates();
+        try {
+          await this.maybeAutoEvict();
+        } catch (err) {
+          console.error("Auto-eviction failed:", err);
+        }
       }
     } finally {
-      this.syncing = false;
       this.syncLock = false;
-      this.crossTabSync.endServerSync();
-      await this.processQueuedWsUpdates();
-      try {
-        await this.maybeAutoEvict();
-      } catch (err) {
-        console.error("Auto-eviction failed:", err);
-      }
     }
   }
   async processQueuedWsUpdates() {
@@ -4522,6 +4545,16 @@ var _SyncedDb = class _SyncedDb {
     }
     return result;
   }
+  async getDirtyMeta() {
+    const result = {};
+    for (const [collectionName] of this.collections) {
+      const metas = await this.dexieDb.getDirtyMeta(collectionName);
+      if (metas.length > 0) {
+        result[collectionName] = metas;
+      }
+    }
+    return result;
+  }
   // ==================== Data Deletion ====================
   async dropCollection(collection, force = false) {
     this.assertCollection(collection);
@@ -5142,6 +5175,21 @@ var DexieDb = class extends Dexie {
     }
     return result;
   }
+  async getDirtyMeta(collection) {
+    const dirtyEntries = await this.dirtyChanges.where("[collection+id]").between([collection, Dexie.minKey], [collection, Dexie.maxKey]).toArray();
+    const result = [];
+    for (const entry of dirtyEntries) {
+      result.push({
+        collection: entry.collection,
+        id: entry.id,
+        baseTs: entry.baseTs,
+        baseRev: entry.baseRev,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt
+      });
+    }
+    return result;
+  }
   async addDirtyChange(collection, id, changes, baseMeta) {
     const stringId = this.idToString(id);
     const existing = await this.dirtyChanges.get([collection, stringId]);

package/dist/src/db/DexieDb.d.ts

@@ -1,5 +1,5 @@
 import Dexie from "dexie";
-import type { DirtyChange, I_DexieDb, SyncMeta } from "../types/I_DexieDb";
+import type { DirtyChange, DirtyMeta, I_DexieDb, SyncMeta } from "../types/I_DexieDb";
 import type { CollectionConfig } from "../types/CollectionConfig";
 import type { Id, LocalDbEntity } from "../types/DbEntity";
 /**
@@ -31,6 +31,7 @@ export declare class DexieDb extends Dexie implements I_DexieDb {
     forEachBatch<T extends LocalDbEntity>(collection: string, batchSize: number, callback: (items: T[]) => Promise<void>): Promise<void>;
     count(collection: string): Promise<number>;
     getDirty<T extends LocalDbEntity>(collection: string): Promise<Partial<T>[]>;
+    getDirtyMeta(collection: string): Promise<DirtyMeta[]>;
     addDirtyChange(collection: string, id: Id, changes: Record<string, any>, baseMeta?: {
         _ts?: any;
         _rev?: number;

package/dist/src/db/SyncedDb.d.ts

@@ -1,6 +1,6 @@
 import type { AggregateOptions } from "mongodb";
 import type { I_SyncedDb, SyncedDbConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo } from "../types/I_SyncedDb";
-import type { MetaUpdateBroadcast } from "../types/I_DexieDb";
+import type { DirtyMeta, MetaUpdateBroadcast } from "../types/I_DexieDb";
 import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
 import type { Id, DbEntity } from "../types/DbEntity";
 /**
@@ -161,6 +161,7 @@ export declare class SyncedDb implements I_SyncedDb {
     getOnWsNotification(): ((info: WsNotificationInfo) => void) | undefined;
     getOnWakeSync(): ((info: import("./types/managers").WakeSyncInfo) => void) | undefined;
     getDirty<T extends DbEntity>(): Promise<Readonly<Record<string, readonly T[]>>>;
+    getDirtyMeta(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
     dropCollection(collection: string, force?: boolean): Promise<void>;
     dropDatabase(force?: boolean): Promise<void>;
     /**

package/dist/src/db/managers/ConnectionManager.d.ts

@@ -1,11 +1,19 @@
 /**
- * ConnectionManager - Manages online/offline state and auto-sync.
+ * ConnectionManager - Manages online/offline state, auto-sync and reconnect.
  *
- * Handles:
- * - Online/offline state transitions
- * - Forced offline mode
- * - Auto-sync timer management
- * - REST/sync timeouts
+ * Invariants:
+ * - `autoSyncTimer` and `reconnectTimer` are always-live from `startTimers()`
+ *   (called by SyncedDb during init) until `stopTimers()` (called by close()).
+ * - Neither timer is cleared by `setOnline(false)`, `forceOffline(true)`, or
+ *   sync failure — state changes only flip flags. Each tick is defensive and
+ *   no-ops when inapplicable.
+ * - `autoSyncTimer` tick: run `sync()` iff `online && !forcedOffline`.
+ * - `reconnectTimer` tick: call `tryGoOnline()` iff `!online && !forcedOffline`
+ *   and no `tryGoOnline` is in flight.
+ * - `tryGoOnline()` pings the server; on success flips `online=true` (next
+ *   auto-sync tick then runs). Historical `goOffline(reason)` method and
+ *   `onForcedOffline` callback are removed — use `onSyncFailed` (logging-only
+ *   callback fired from SyncEngine) or explicit `forceOffline(true)`.
  */
 import type { I_ConnectionManager, ConnectionManagerConfig } from "../types/managers";
 export declare class ConnectionManager implements I_ConnectionManager {
@@ -13,54 +21,48 @@ export declare class ConnectionManager implements I_ConnectionManager {
     private readonly restTimeoutMs;
     private readonly syncTimeoutMs;
     private readonly autoSyncIntervalMs?;
+    private readonly onlineRetryIntervalMs;
     private readonly callbacks;
     private readonly deps;
     private online;
     private forcedOffline;
     private autoSyncTimer?;
+    private reconnectTimer?;
+    private tryGoOnlineInFlight;
+    private closed;
     constructor(config: ConnectionManagerConfig);
-    /**
-     * Current online status (considering forcedOffline).
-     */
+    /** Current online status (considering forcedOffline). */
     isOnline(): boolean;
-    /**
-     * Is forced offline mode active?
-     */
     isForcedOffline(): boolean;
-    /**
-     * Can we sync with server?
-     */
     canSync(): boolean;
-    /**
-     * Can we receive server updates?
-     */
     canReceiveServerUpdates(): boolean;
     /**
-     * Set online status.
-     * Note: Going offline does NOT release leadership. With window-scoped locks,
-     * a tab should remain leader within its window to process WebSocket notifications
-     * even while offline.
+     * Set online status. Does NOT stop any timers.
+     *
+     * - `setOnline(true)` attempts `tryGoOnline` (ping → flip state).
+     * - `setOnline(false)` flips state to offline and fires `onOnlineStatusChange`.
+     *   The reconnect timer will continue attempting to come back online.
      */
     setOnline(online: boolean): Promise<void>;
     /**
-     * Force offline mode.
+     * Force offline mode. Does NOT stop timers — reconnect timer will still
+     * check `forcedOffline` and skip while true. When released, `tryGoOnline`
+     * fires immediately to avoid waiting for the next tick.
      */
     forceOffline(forced: boolean): void;
     /**
-     * Go offline with reason.
-     * Note: This does NOT release leadership. With window-scoped locks,
-     * a tab should remain leader within its window to process WebSocket notifications
-     * even while offline due to network issues.
+     * Attempt to transition from offline to online.
+     * Idempotent, guards against concurrent calls and forcedOffline.
      */
-    goOffline(reason: string): void;
+    tryGoOnline(): Promise<void>;
     /**
-     * Start auto-sync timer.
+     * Start both timers. Idempotent. Called by SyncedDb.init().
      */
-    startAutoSync(): void;
+    startTimers(): void;
     /**
-     * Stop auto-sync timer.
+     * Stop both timers. Called by SyncedDb.close().
      */
-    stopAutoSync(): void;
+    stopTimers(): void;
     /**
      * Ping server.
      */
@@ -77,6 +79,11 @@ export declare class ConnectionManager implements I_ConnectionManager {
      * Report infrastructure error.
      */
     reportInfrastructureError(type: string, message: string, error?: Error): void;
+    /**
+     * Notify consumers of a sync failure. Does not mutate state.
+     * Called from SyncEngine via deps.onSyncFailed wiring.
+     */
+    callOnSyncFailed(reason: string): void;
     /**
      * Call onWsConnect callback.
      */
@@ -101,5 +108,4 @@ export declare class ConnectionManager implements I_ConnectionManager {
      * Get onWsReconnect callback.
      */
     getOnWsReconnect(): ((attempt: number) => void) | undefined;
-    private tryGoOnline;
 }

package/dist/src/db/managers/CrossTabSyncManager.d.ts

@@ -1,8 +1,9 @@
 /**
  * CrossTabSyncManager - Manages cross-tab synchronization via BroadcastChannel.
  *
- * When the leader tab syncs data or receives WebSocket updates, it broadcasts
- * the IDs of updated records so other tabs can refresh their in-memory state.
+ * Any tab with local writes (leader or follower) broadcasts the IDs of updated
+ * records so other tabs refresh their in-memory state from shared Dexie.
+ * Reload broadcasts (post-full-sync) remain leader-only.
  */
 import type { MetaUpdateBroadcast } from "../../types/I_DexieDb";
 import type { I_CrossTabSyncManager, CrossTabSyncConfig } from "../types/managers";
@@ -31,7 +32,9 @@ export declare class CrossTabSyncManager implements I_CrossTabSyncManager {
     init(): void;
     /**
      * Broadcast updated IDs to other tabs (debounced).
-     * Only the leader should broadcast.
+     * Any tab with local writes broadcasts so other tabs refresh their in-mem
+     * from shared Dexie. Otherwise non-leader writes stay invisible to the leader's
+     * in-mem cache, and a later upload patches new _rev onto stale content.
      * While a server sync is in progress, suppresses delta broadcasts and only
      * records which collections were affected (for the post-sync reload broadcast).
      */

package/dist/src/db/types/managers.d.ts

@@ -91,7 +91,10 @@ export interface I_CrossTabSyncManager {
 }
 export interface ConnectionCallbacks {
     onOnlineStatusChange?: (online: boolean) => void;
-    onForcedOffline?: (reason: string) => void;
+    /**
+     * Fired on sync failure. Does NOT mutate online state. For logging only.
+     */
+    onSyncFailed?: (reason: string) => void;
     onWsConnect?: () => void;
     onWsDisconnect?: (reason: string) => void;
     onWsReconnect?: (attempt: number) => void;
@@ -112,6 +115,7 @@ export interface ConnectionManagerConfig {
     restTimeoutMs: number;
     syncTimeoutMs: number;
     autoSyncIntervalMs?: number;
+    onlineRetryIntervalMs?: number;
     callbacks: ConnectionCallbacks;
     deps: ConnectionManagerDeps;
 }
@@ -128,12 +132,15 @@ export interface I_ConnectionManager {
     setOnline(online: boolean): Promise<void>;
     /** Force offline mode. */
     forceOffline(forced: boolean): void;
-    /** Go offline with reason. */
-    goOffline(reason: string): void;
-    /** Start auto-sync timer. */
-    startAutoSync(): void;
-    /** Stop auto-sync timer. */
-    stopAutoSync(): void;
+    /**
+     * Attempt to transition from internal-offline to online (ping + start timers
+     * if successful). No-op if already online, forcedOffline, or a try is in flight.
+     */
+    tryGoOnline(): Promise<void>;
+    /** Start both auto-sync and reconnect timers (idempotent). */
+    startTimers(): void;
+    /** Stop both auto-sync and reconnect timers. Called from close(). */
+    stopTimers(): void;
     /** Ping server. */
     ping(timeoutMs?: number): Promise<boolean>;
     /** Wrap promise with sync timeout. */
@@ -256,7 +263,8 @@ export interface SyncEngineDeps {
     writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete") => void;
     getInMemById: <T extends DbEntity>(collection: string, id: Id) => T | undefined;
     withSyncTimeout: <T>(promise: Promise<T>, operation: string) => Promise<T>;
-    goOffline: (reason: string) => void;
+    /** Notify consumers that a sync cycle failed. Does not mutate online state. */
+    onSyncFailed: (reason: string) => void;
     flushAllPendingChanges: () => Promise<void>;
     cancelRestUploadTimer: () => void;
     awaitRestUpload: () => Promise<void>;

package/dist/src/types/I_DexieDb.d.ts

@@ -27,6 +27,12 @@ export interface DirtyChange {
     /** When last change was accumulated */
     updatedAt: number;
 }
+/**
+ * Meta fields of a DirtyChange entry, without the `changes` payload.
+ * Used by `getDirtyMeta` for lightweight dirty-state inspection
+ * (counts, timestamps) without loading change payloads into memory.
+ */
+export type DirtyMeta = Omit<DirtyChange, "changes">;
 /** Shared fields for all cross-tab broadcast messages */
 interface BroadcastBase {
     /** Unique ID of the SyncedDb instance that sent this broadcast */
@@ -84,6 +90,8 @@ export interface I_DexieDb {
     forEachBatch<T extends LocalDbEntity>(collection: string, batchSize: number, callback: (items: T[]) => Promise<void>): Promise<void>;
     /** Vrne vse dirty objekte (z lokalnimi spremembami) - returns only changed fields + _id + metadata */
     getDirty<T extends LocalDbEntity>(collection: string): Promise<Partial<T>[]>;
+    /** Vrne meta podatke vseh dirty vnosov za kolekcijo (brez `changes` payloada) */
+    getDirtyMeta(collection: string): Promise<DirtyMeta[]>;
     /** Add or accumulate changes for a record */
     addDirtyChange(collection: string, id: Id, changes: Record<string, any>, baseMeta?: {
         _ts?: any;

package/dist/src/types/I_SyncedDb.d.ts

@@ -1,7 +1,7 @@
 import type { AggregateOptions } from "mongodb";
 import type { Id, DbEntity, LocalDbEntity } from "./DbEntity";
 import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec, I_RestInterface, CollectionUpdateRequest, CollectionUpdateResult, GetNewerSpec } from "./I_RestInterface";
-import type { I_DexieDb } from "./I_DexieDb";
+import type { DirtyMeta, I_DexieDb } from "./I_DexieDb";
 import type { I_InMemDb } from "./I_InMemDb";
 import type { I_ServerUpdateNotifier } from "./I_ServerUpdateNotifier";
 import type { WakeSyncInfo, NetworkStatusChangeInfo } from "../db/types/managers";
@@ -317,8 +317,13 @@ export interface SyncedDbConfig {
     debounceDexieWritesMs?: number;
     /** Debounce čas za pošiljanje na REST v ms (default: 100) - po uspešnem zapisu v Dexie */
     debounceRestWritesMs?: number;
-    /** Callback ki se pokliče, ko SyncedDb sam preide v offline stanje (npr. ob sync napaki) */
-    onForcedOffline?: (reason: string) => void;
+    /**
+     * Callback fired on each sync failure. Unlike the removed `onForcedOffline`,
+     * this does NOT mutate online state — the library keeps trying on the next
+     * auto-sync tick. Use this callback for logging/telemetry only. To actually
+     * force the database offline, call {@link forceOffline}.
+     */
+    onSyncFailed?: (reason: string) => void;
     /** Callback fired once during init() when the IndexedDB database was created fresh (first ever open). */
     onDatabaseCreated?: () => void;
     /** Callback at the start of each sync cycle. initialSync=true if no full sync has completed yet. */
@@ -381,8 +386,19 @@ export interface SyncedDbConfig {
      * Če je podano, se sync() kliče avtomatsko na ta interval, ko je online.
      * Auto-sync se izvaja samo ko je online in ne bo interferiral z eksplicitnimi sync() klici
      * (uporablja isti syncLock mehanizem).
+     *
+     * Timer je zagnan v init() in ustavljen v close(). Če je offline ali
+     * forcedOffline, tick-i so no-op (ne ubije se timer, naslednji tick bo spet
+     * poskusil). Self-healing: sync napaka ne ustavi timer-ja.
      */
     autoSyncIntervalMs?: number;
+    /**
+     * Interval za periodično poskušanje preklopa iz offline v online, v ms.
+     * Vedno-živi timer: od init() do close(). Če smo offline in ne forcedOffline,
+     * vsak tick pokliče `tryGoOnline()` (ping → če uspešen, gremo online in naslednji
+     * auto-sync tick bo sinhroniziral). Default: 60000 (60 s). 0/undefined disable.
+     */
+    onlineRetryIntervalMs?: number;
     /** Callback when WebSocket connects */
     onWsConnect?: () => void;
     /** Callback when WebSocket disconnects */
@@ -391,7 +407,7 @@ export interface SyncedDbConfig {
     onWsReconnect?: (attempt: number) => void;
     /** Callback when a WebSocket notification is received */
     onWsNotification?: (info: WsNotificationInfo) => void;
-    /** Callback when online status changes (after ping success/failure in tryGoOnline or goOffline) */
+    /** Callback when online status changes (after ping success/failure in tryGoOnline) */
     onOnlineStatusChange?: (online: boolean) => void;
     /** Debounce interval for cross-tab sync broadcasts in ms (default: 100) */
     crossTabSyncDebounceMs?: number;
@@ -684,6 +700,11 @@ export interface I_SyncedDb {
     getDebounceRestWritesMs(): number;
     /** Vrne vse dirty objekte iz vseh kolekcij */
     getDirty<T extends DbEntity>(): Promise<Readonly<Record<string, readonly T[]>>>;
+    /**
+     * Vrne meta podatke dirty vnosov (brez `changes` payloada) po kolekcijah,
+     * ki imajo vsaj en dirty zapis. Kolekcije brez dirty vnosov niso vključene.
+     */
+    getDirtyMeta(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
     /**
      * Drops a collection, ensuring no data loss.
      * - Throws if offline or forcedOffline (unless force=true)

package/dist/src/types/index.d.ts

@@ -2,7 +2,7 @@ export type { Id, Entity, IdOrEntity, DbEntity, LocalDbEntity } from "./DbEntity
 export type { PublishableOperation, PublishRevsPayloadInsert, PublishRevsPayloadUpdate, PublishRevsPayloadDelete, PublishRevsPayloadUpdateMany, PublishRevsPayloadDeleteMany, PublishRevsPayloadBatchItem, PublishRevsPayloadBatch, PublishRevsPayload, PublishRevsSpec, PublishDataPayloadBase, PublishDataPayloadInsert, PublishDataPayloadUpdate, PublishDataPayloadDelete, PublishDataPayloadBatch, PublishDataPayload, PublishDataSpec, PublishSpec, } from "./PublishRevsPayload";
 export type { Obj, QuerySpec, Projection, QueryOpts, KeyOf, InsertKeyOf, InsertSpec, UpdateSpec, BatchSpec, UpsertOptions, GetNewerSpec, I_RestInterface as RestInterface, } from "./I_RestInterface";
 export type { I_InMemDb as InMemDb } from "./I_InMemDb";
-export type { I_DexieDb as DexieDb, SyncMeta } from "./I_DexieDb";
+export type { I_DexieDb as DexieDb, SyncMeta, DirtyChange, DirtyMeta } from "./I_DexieDb";
 export type { I_ServerUpdateNotifier as ServerUpdateNotifier, ServerUpdateCallback, ServerUpdateNotifierCallbacks } from "./I_ServerUpdateNotifier";
 export type { I_SyncedDb as SyncedDb, SyncedDbConfig, CollectionConfig, CollectionSyncConfig, SyncInfo, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, InfrastructureErrorType, InfrastructureErrorInfo, ConflictSource, ConflictResolutionReport, CrossTabSyncInfo, EvictionInfo, EvictionCollectionInfo, } from "./I_SyncedDb";
 export type { NetworkStatusChangeInfo } from "../db/types/managers";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.140",
+  "version": "0.1.143",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",