dexie-cloud-addon 4.4.11 → 4.4.13

package/dist/umd/service-worker.js

@@ -8,7 +8,7 @@
  *
  * ==========================================================================
  *
- * Version 4.4.11, Sun Apr 19 2026
+ * Version 4.4.13, Wed May 27 2026
  *
  * https://dexie.org
  *
@@ -4217,14 +4217,16 @@
                             }
                             break;
                         case 'update':
-                            if (!primaryKey.outbound && primaryKey.keyPath) {
+                            if (!primaryKey.outbound &&
+                                primaryKey.keyPath &&
+                                typeof primaryKey.keyPath === 'string') {
                                 // The primary key should never be part of an updateSpec — it cannot change
                                 // and is already communicated via the operation's keys array.
                                 // For private singleton IDs (e.g. "#key:userId" on server, "#key" on client),
                                 // the encoded server-side key may leak into the changeSpec via getObjectDiff().
                                 // Strip it here unconditionally as a defensive measure.
                                 for (const changeSpec of mut.changeSpecs) {
-                                    Dexie.delByKeyPath(changeSpec, primaryKey.keyPath);
+                                    delete changeSpec[primaryKey.keyPath];
                                 }
                             }
                             yield bulkUpdate(table, keys, mut.changeSpecs);
@@ -13623,7 +13625,7 @@
      *
      * ==========================================================================
      *
-     * Version 4.4.0, Sun Apr 19 2026
+     * Version 4.4.0, Wed May 27 2026
      *
      * https://dexie.org
      *
@@ -15231,22 +15233,208 @@
     }
 
     /**
-     * Deduplicates in-flight blob downloads.
+     * BlobSavingQueue - Queues resolved blobs for saving back to IndexedDB.
      *
-     * Both the blob-resolve middleware and the eager blob downloader may
-     * try to fetch the same blob concurrently. This tracker ensures each
-     * unique blob ref is only downloaded once — subsequent requests for
-     * the same ref piggyback on the existing promise.
+     * This is an internal collaborator of BlobDownloadTracker and is not
+     * intended to be used directly by middleware or other code. See
+     * BlobDownloadTracker.enqueueSave().
      *
-     * Instantiate once per DexieCloudDB.
+     * Uses setTimeout(fn, 0) instead of queueMicrotask to completely isolate
+     * from Dexie's Promise.PSD context. This prevents the save operation
+     * from inheriting any ongoing transaction.
+     *
+     * Each blob is saved atomically using downCore transaction with the specific
+     * keyPath to avoid race conditions with other property changes.
+     */
+    class BlobSavingQueue {
+        constructor(db, onPersisted) {
+            this.queue = [];
+            this.isProcessing = false;
+            this.drainResolvers = [];
+            this.db = db;
+            this.onPersisted = onPersisted;
+        }
+        /**
+         * Queue a resolved blob for saving.
+         * Only the specific blob property will be updated atomically.
+         */
+        saveBlobs(tableName, primaryKey, resolvedBlobs) {
+            this.queue.push({
+                tableName,
+                primaryKey,
+                resolvedBlobs,
+            });
+            this.startConsumer();
+        }
+        /**
+         * Returns a promise that resolves when the queue is empty AND no item
+         * is currently being processed. Used by callers that need to know when
+         * all previously enqueued saves have been persisted to IndexedDB before
+         * making decisions based on the on-disk state (e.g., the eager blob
+         * downloader looping over `_hasBlobRefs=1` rows in chunks).
+         *
+         * Note: New work enqueued AFTER drain() is called does NOT extend the
+         * wait. Callers that race against concurrent producers should treat the
+         * returned promise as "queue was empty at some point after this call".
+         */
+        drain() {
+            if (!this.isProcessing && this.queue.length === 0) {
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                this.drainResolvers.push(resolve);
+            });
+        }
+        /**
+         * Start the consumer if not already processing.
+         * Uses setTimeout(fn, 0) to completely break out of any
+         * Dexie transaction context (Promise.PSD).
+         */
+        startConsumer() {
+            if (this.isProcessing)
+                return;
+            this.isProcessing = true;
+            // Use setTimeout to completely isolate from Dexie's PSD context
+            // queueMicrotask would risk inheriting the current transaction
+            setTimeout(() => {
+                this.processQueue();
+            }, 0);
+        }
+        /**
+         * Process all queued blobs.
+         * Runs in a completely isolated context (no inherited transaction).
+         * Uses atomic updates to avoid race conditions.
+         */
+        processQueue() {
+            const item = this.queue.shift();
+            if (!item) {
+                this.isProcessing = false;
+                // Fire any pending drain() waiters. New saveBlobs() calls that
+                // arrive after this point will start a fresh processing cycle
+                // and have their own drain() semantics.
+                const resolvers = this.drainResolvers;
+                if (resolvers.length > 0) {
+                    this.drainResolvers = [];
+                    for (const resolve of resolvers)
+                        resolve();
+                }
+                return;
+            }
+            // Atomic update of just the blob property
+            this.db
+                .transaction('rw', item.tableName, (tx) => {
+                const trans = tx.idbtrans;
+                trans.disableChangeTracking = true; // Don't regard this as a change for sync purposes
+                trans.disableAccessControl = true; // Bypass any access control checks since this is an internal operation
+                trans.disableBlobResolve = true; // Custom flag to skip blob resolve middleware during this transaction
+                const updateSpec = {};
+                for (const blob of item.resolvedBlobs) {
+                    updateSpec[blob.keyPath] = blob.data;
+                }
+                tx.table(item.tableName).update(item.primaryKey, (obj) => {
+                    // Check that object still has the same unresolved blob refs before applying update (i.e. it hasn't been modified since we read it)
+                    for (const blob of item.resolvedBlobs) {
+                        // Verify atomicity - none of the blob properties has been modified since we read it. If any of them was modified, skip updating this item to avoid overwriting user changes.
+                        const currentValue = Dexie.getByKeyPath(obj, blob.keyPath);
+                        if (currentValue === undefined) {
+                            // Blob property was removed - skip updating this blob
+                            continue;
+                        }
+                        if (!isBlobRef(currentValue)) {
+                            // Blob property was modified to a non-blob-ref value - skip updating this blob
+                            continue;
+                        }
+                        if (currentValue.ref !== blob.ref) {
+                            // Blob property was modified - skip updating this blob
+                            return; // Stop. Another items has been queued to fully fix the object.
+                        }
+                        Dexie.setByKeyPath(obj, blob.keyPath, blob.data);
+                    }
+                    delete obj._hasBlobRefs; // Clear the _hasBlobRefs marker if all refs was resolved.
+                });
+                // Note: we intentionally do NOT clear trans.mutatedParts here.
+                // Letting the normal mutation signal through means the
+                // blobProgress liveQuery (and any user-defined liveQuery that
+                // depends on the resolved fields) wakes up and reflects progress
+                // as blobs land in IndexedDB.
+            })
+                .catch((error) => {
+                console.error(`Error saving resolved blobs on ${item.tableName}:${item.primaryKey}:`, error);
+            })
+                .finally(() => {
+                // At this point, the transaction has completed (either successfully or with error),
+                // and the blobs have been saved (or failed to save).
+                // Notify the owner (BlobDownloadTracker) so it can release the
+                // in-flight download cache entries for these refs. The cache was
+                // kept alive until now to maximize reuse while the blob was still
+                // in-flight (downloading or queued for save).
+                this.onPersisted(item.resolvedBlobs.map((b) => b.ref));
+                // Process next item in the queue
+                return this.processQueue();
+            });
+        }
+    }
+
+    /**
+     * Owns the full lifecycle of downloaded blobs:
+     *   1. Deduplicates concurrent downloads for the same ref.
+     *   2. Bounds the number of concurrent network fetches (MAX_CONCURRENT)
+     *      so that ad-hoc reads can't starve the HTTP connection pool. Calls
+     *      beyond the cap queue in FIFO order as slots free. The slot is held
+     *      only for the duration of the fetch — NOT until persistence — to
+     *      avoid deadlocks when a single object contains more blob refs than
+     *      MAX_CONCURRENT (a sequential resolver would otherwise hold every
+     *      slot itself while waiting for the next).
+     *   3. Keeps the in-flight promise alive after the network fetch completes,
+     *      until the blob has been persisted back to IndexedDB. This way,
+     *      readers that ask for the same ref while it is queued for saving
+     *      can piggyback on the existing promise instead of refetching.
+     *      In-flight membership and slot ownership are independent: a piggyback
+     *      reader consumes neither a slot nor extra memory beyond the existing
+     *      cached Uint8Array.
+     *   4. Persists resolved blobs via an internal BlobSavingQueue, and
+     *      releases the in-flight entry when persistence completes.
+     *
+     * Both the blob-resolve middleware and the eager blob downloader use this
+     * tracker. Instantiate once per DexieCloudDB.
      */
+    /**
+     * Maximum number of concurrent blob fetches.
+     *
+     * Historically 6 to match the HTTP/1.1 same-origin connection cap that
+     * browsers enforce. With HTTP/2 (the typical transport for Dexie Cloud
+     * today) many streams multiplex over a single TCP connection, so the
+     * old cap is overly conservative. 10 is a modest bump that still keeps
+     * memory pressure (in-flight Uint8Arrays) and server load bounded.
+     * Can be made configurable via DexieCloudOptions if a real need arises.
+     */
+    const MAX_CONCURRENT = 10;
     class BlobDownloadTracker {
         constructor(db) {
             this.inFlight = new Map();
+            this.activeFetches = 0;
+            this.waiting = [];
             this.db = db;
+            this.savingQueue = new BlobSavingQueue(db, (refs) => {
+                // Called by the queue when a save transaction has completed
+                // (regardless of success). Drop the in-flight cache entries now —
+                // any future reader will go through IndexedDB instead.
+                for (const ref of refs) {
+                    this.inFlight.delete(ref);
+                }
+            });
         }
         /**
-         * Download a blob, deduplicating concurrent requests for the same ref.
+         * Download a blob, deduplicating concurrent requests for the same ref
+         * and respecting the global fetch concurrency cap.
+         *
+         * Lifecycle:
+         *   - Slot is acquired before the fetch and released as soon as the
+         *     fetch settles (success or failure).
+         *   - The in-flight entry survives a successful fetch and lives on
+         *     until persistence completes (via enqueueSave) or releaseRefs
+         *     is called. On fetch failure, the entry is removed immediately
+         *     so a future call can retry.
          *
          * @param blobRef - The BlobRef to download
          * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
@@ -15254,45 +15442,103 @@
         download(blobRef, dbUrl) {
             let promise = this.inFlight.get(blobRef.ref);
             if (!promise) {
-                promise = loadCachedAccessToken(this.db)
-                    .then((accessToken) => {
-                    // accessToken may be null for anonymous/unauthenticated users.
-                    // Public realm blobs (rlm-public) are accessible without auth.
-                    // downloadBlob will omit the Authorization header when token is null.
-                    return downloadBlob(blobRef, dbUrl, accessToken);
-                })
-                    .finally(() => this.inFlight.delete(blobRef.ref));
-                // When the promise settles (either fulfilled or rejected), remove it from the in-flight map
+                promise = this.acquireSlot()
+                    .then(() => this.downloadBlob(blobRef, dbUrl).finally(() => this.releaseSlot()))
+                    .catch((err) => {
+                    // On error, remove immediately so a future call can retry.
+                    // (Slot already released by the .finally above.)
+                    this.inFlight.delete(blobRef.ref);
+                    throw err;
+                });
                 this.inFlight.set(blobRef.ref, promise);
             }
             return promise;
         }
-    }
-    /**
-     * Download blob data from server via proxy endpoint.
-     * Uses auth header for authentication (same as sync).
-     * When accessToken is null, the request is made without Authorization header —
-     * this allows downloading blobs from public realms (rlm-public) for
-     * unauthenticated users.
-     *
-     * @param blobRef - The BlobRef to download
-     * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
-     * @param accessToken - Access token for authentication, or null for anonymous access
-     */
-    function downloadBlob(blobRef, dbUrl, accessToken) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const downloadUrl = `${dbUrl}/blob/${blobRef.ref}`;
-            const headers = {};
-            if (accessToken) {
-                headers['Authorization'] = `Bearer ${accessToken}`;
+        /**
+         * Queue resolved blobs for persisting back to IndexedDB.
+         * When the save transaction completes, the corresponding in-flight
+         * entries are released.
+         */
+        enqueueSave(tableName, primaryKey, resolvedBlobs) {
+            this.savingQueue.saveBlobs(tableName, primaryKey, resolvedBlobs);
+        }
+        /**
+         * Wait until all previously enqueued saves have been persisted to
+         * IndexedDB. Used by callers that need to make decisions based on
+         * on-disk state — e.g., the eager downloader looping over rows with
+         * `_hasBlobRefs=1` in chunks, where each iteration must see the
+         * previous chunk's writes before re-querying.
+         *
+         * New saves enqueued AFTER drainPendingSaves() is called do NOT extend
+         * the wait.
+         */
+        drainPendingSaves() {
+            return this.savingQueue.drain();
+        }
+        /**
+         * Release in-flight entries without going through the internal saving
+         * queue. Used when the caller persists the blobs itself, or when no
+         * primary key was available and the data won't be persisted at all.
+         */
+        releaseRefs(refs) {
+            for (const ref of refs) {
+                this.inFlight.delete(ref);
             }
-            const response = yield fetch(downloadUrl, { headers });
-            if (!response.ok) {
-                throw new Error(`Failed to download blob ${blobRef.ref}: ${response.status} ${response.statusText}`);
+        }
+        acquireSlot() {
+            if (this.activeFetches < MAX_CONCURRENT) {
+                this.activeFetches++;
+                return Promise.resolve();
             }
-            const arrayBuffer = yield response.arrayBuffer();
-            return new Uint8Array(arrayBuffer);
-        });
+            return new Promise((resolve) => {
+                this.waiting.push(() => {
+                    this.activeFetches++;
+                    resolve();
+                });
+            });
+        }
+        releaseSlot() {
+            this.activeFetches--;
+            const next = this.waiting.shift();
+            if (next)
+                next();
+        }
+        /**
+         * Download blob data from server via proxy endpoint.
+         * Uses auth header for authentication (same as sync).
+         * When accessToken is null, the request is made without Authorization header —
+         * this allows downloading blobs from public realms (rlm-public) for
+         * unauthenticated users.
+         *
+         * @param blobRef - The BlobRef to download
+         * @param dbUrl - Base URL for the database (e.g., 'https://mydb.dexie.cloud')
+         */
+        downloadBlob(blobRef, dbUrl) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const accessToken = yield loadCachedAccessToken(this.db);
+                const downloadUrl = `${dbUrl}/blob/${blobRef.ref}`;
+                const headers = {};
+                if (accessToken) {
+                    // accessToken may be null for anonymous/unauthenticated users.
+                    // Public realm blobs (rlm-public) are accessible without auth.
+                    // downloadBlob will omit the Authorization header when token is null.
+                    headers['Authorization'] = `Bearer ${accessToken}`;
+                }
+                // cache: 'no-store' prevents the browser from storing this response in its
+                // HTTP cache. The server sets a long Expires/Cache-Control header on blob
+                // responses (blobs are immutable and content-addressed), which would
+                // otherwise cause the browser to keep a copy in its disk cache in addition
+                // to the copy we persist to IndexedDB — doubling storage for every blob.
+                // Since we always persist to IndexedDB and subsequent reads go through
+                // IndexedDB (never re-fetch), the browser cache copy is pure overhead.
+                const response = yield fetch(downloadUrl, { headers, cache: 'no-store' });
+                if (!response.ok) {
+                    throw new Error(`Failed to download blob ${blobRef.ref}: ${response.status} ${response.statusText}`);
+                }
+                const arrayBuffer = yield response.arrayBuffer();
+                return new Uint8Array(arrayBuffer);
+            });
+        }
     }
 
     const wm$2 = new WeakMap();
@@ -15513,118 +15759,116 @@
      * Downloads unresolved blobs in the background when blobMode='eager'.
      * Called after sync completes to prefetch blobs for offline access.
      *
+     * Strategy:
+     *   1. Snapshot the primary keys of all rows currently flagged
+     *      `_hasBlobRefs=1` for each syncable table.
+     *   2. Walk that key list in chunks via `bulkGet`. Each `bulkGet`
+     *      triggers the blob-resolve middleware, which does all the actual
+     *      work — downloading blobs (throttled and deduplicated by the
+     *      shared BlobDownloadTracker) and enqueueing them for persistence
+     *      via the internal save queue.
+     *
+     * This keeps a single, symmetric code path with normal application
+     * reads, which is important when other middlewares are present
+     * (e.g., a hypothetical encryption middleware): writes from the save
+     * queue and reads from this loop both pass through the full middleware
+     * stack, so on-disk representation stays consistent.
+     *
+     * Why a snapshot of primary keys (rather than re-querying the index)?
+     *   - Rows that get resolved by parallel application reads simply
+     *     disappear from the table contents we're about to re-fetch; the
+     *     middleware skips them since `_hasBlobRefs` is already cleared.
+     *   - Stuck rows (e.g., blob 404s) are naturally bypassed: we just
+     *     advance to the next chunk in the snapshot. No `seenKeys`
+     *     bookkeeping required.
+     *   - The snapshot is `string[]`-shaped for typical Dexie Cloud rows
+     *     (~36 bytes/UUID), so ~28K keys per MB. Acceptable for any
+     *     realistic dataset.
+     *
      * Progress is tracked automatically via liveQuery in blobProgress.ts —
      * no manual progress reporting needed here.
-     */
+     *
+     * --- Throughput note ---
+     * The chunk loop is sequential: bulkGet → wait for all downloads to
+     * settle → next bulkGet. The save queue drains in the background and
+     * does not block iteration (saves no longer need to be persisted before
+     * the next iteration, since we don't re-query the index). For typical
+     * blob sizes (10 KB – 10 MB) the network dominates total time. If
+     * real-world profiling later shows the per-chunk fixed cost matters,
+     * the next bulkGet could be kicked off in parallel with the current
+     * one's middleware work — but we keep it simple until measurements
+     * justify otherwise.
+     */
+    // One chunk = one full saturation of the tracker's concurrency semaphore.
+    // Larger chunks would only buffer more downloaded Uint8Arrays in memory
+    // while waiting for the save queue to persist them, without any throughput
+    // benefit (the semaphore is the gate, not the bulkGet).
+    const CHUNK_SIZE = MAX_CONCURRENT - 1; // Leave one slot for parallel app reads that might also trigger downloads
     /**
      * Download all unresolved blobs in the background.
      *
      * This is called when blobMode='eager' (default) after sync completes.
-     * BlobRef URLs are signed (SAS tokens) so no auth header needed.
-     *
-     * Each blob is saved atomically using Table.update() to avoid race conditions.
      */
     function downloadUnresolvedBlobs(db, downloading$, signal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             const debugLog = (msg) => console.debug(`[dexie-cloud] ${msg}`);
             debugLog('Eager download: Starting...');
-            // Scan for unresolved blobs
-            const syncedTables = getSyncableTables(db);
-            let hasWork = false;
-            for (const table of syncedTables) {
-                try {
-                    const hasIndex = !!table.schema.idxByName['_hasBlobRefs'];
-                    if (!hasIndex)
-                        continue;
-                    const count = yield table.where('_hasBlobRefs').equals(1).count();
-                    if (count > 0) {
-                        hasWork = true;
-                        break;
-                    }
-                }
-                catch (_b) {
-                    // skip
-                }
-            }
-            if (!hasWork) {
-                debugLog('Eager download: No blobs remaining, exiting');
-                return;
-            }
-            setDownloadingState(downloading$, true);
+            const syncedTables = getSyncableTables(db).filter((t) => t.schema.indexes.some((idx) => idx.name === '_hasBlobRefs'));
+            let started = false;
+            let totalProcessed = 0;
             try {
-                debugLog(`Eager download: Found ${syncedTables.length} syncable tables: ${syncedTables.map((t) => t.name).join(', ')}`);
                 for (const table of syncedTables) {
                     if (signal === null || signal === void 0 ? void 0 : signal.aborted)
                         ;
+                    let keys;
                     try {
-                        // Check if table has _hasBlobRefs index
-                        const hasIndex = table.schema.indexes.some((idx) => idx.name === '_hasBlobRefs');
-                        if (!hasIndex)
-                            continue;
-                        // Query objects with _hasBlobRefs marker
-                        const unresolvedObjects = yield table
-                            .where('_hasBlobRefs')
-                            .equals(1)
-                            .toArray();
-                        debugLog(`Eager download: Table ${table.name} has ${unresolvedObjects.length} unresolved objects`);
-                        const databaseUrl = (_a = db.cloud.options) === null || _a === void 0 ? void 0 : _a.databaseUrl;
-                        if (!databaseUrl)
-                            throw new Error('Database URL is required to download blobs');
-                        // Download up to MAX_CONCURRENT blobs in parallel
-                        const MAX_CONCURRENT = 6;
-                        const primaryKey = table.schema.primKey;
-                        // Filter to actionable objects first
-                        const pending = unresolvedObjects.filter((obj) => {
-                            if (!hasUnresolvedBlobRefs(obj))
-                                return false;
-                            const key = primaryKey.keyPath
-                                ? Dexie.getByKeyPath(obj, primaryKey.keyPath)
-                                : undefined;
-                            return key !== undefined;
-                        });
-                        // Process in parallel with concurrency limit
-                        let i = 0;
-                        const runNext = () => __awaiter(this, void 0, void 0, function* () {
-                            while (i < pending.length) {
-                                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
-                                    ;
-                                const obj = pending[i++];
-                                const key = Dexie.getByKeyPath(obj, primaryKey.keyPath);
-                                try {
-                                    // Refresh token per object — cheap (returns cached) but ensures
-                                    // we pick up renewed tokens during long download sessions.
-                                    const resolvedBlobs = [];
-                                    yield resolveAllBlobRefs(obj, databaseUrl, resolvedBlobs, '', new WeakMap(), db.blobDownloadTracker);
-                                    const updateSpec = {
-                                        _hasBlobRefs: undefined,
-                                    };
-                                    for (const blob of resolvedBlobs) {
-                                        updateSpec[blob.keyPath] = blob.data;
-                                    }
-                                    debugLog(`Eager download: Updating ${table.name}:${key} with ${resolvedBlobs.length} blobs`);
-                                    yield table.update(key, updateSpec);
-                                    // liveQuery in blobProgress.ts auto-detects this change
-                                }
-                                catch (err) {
-                                    console.error(`Failed to download blobs for ${table.name}:${key}:`, err);
-                                }
-                            }
-                        });
-                        // Launch up to MAX_CONCURRENT workers
-                        const workers = [];
-                        for (let w = 0; w < Math.min(MAX_CONCURRENT, pending.length); w++) {
-                            workers.push(runNext());
-                        }
-                        yield Promise.all(workers);
+                        keys = yield table.where('_hasBlobRefs').equals(1).primaryKeys();
                     }
                     catch (err) {
-                        // Table might not have _hasBlobRefs index or other issues - skip silently
+                        console.error(`Eager download: failed to list unresolved rows for ${table.name}:`, err);
+                        continue;
+                    }
+                    if (keys.length === 0)
+                        continue;
+                    if (!started) {
+                        setDownloadingState(downloading$, true);
+                        started = true;
                     }
+                    debugLog(`Eager download: ${table.name} has ${keys.length} row(s)`);
+                    for (let i = 0; i < keys.length; i += CHUNK_SIZE) {
+                        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                            ;
+                        const slice = keys.slice(i, i + CHUNK_SIZE);
+                        try {
+                            // bulkGet triggers the blob-resolve middleware for each row that
+                            // still has `_hasBlobRefs=1`. Rows already resolved by parallel
+                            // reads come back without the marker and the middleware no-ops.
+                            // Rows that have been deleted return `undefined` and are
+                            // likewise skipped.
+                            yield table.bulkGet(slice);
+                        }
+                        catch (err) {
+                            console.error(`Eager download: ${table.name} chunk failed:`, err);
+                            continue;
+                        }
+                        totalProcessed += slice.length;
+                        debugLog(`Eager download: ${table.name} ${Math.min(i + CHUNK_SIZE, keys.length)}/${keys.length}`);
+                    }
+                }
+                if (started) {
+                    // Make sure all middleware-enqueued saves have landed before we flip
+                    // `downloading$` to false — otherwise observers might see a "done"
+                    // signal while writes are still in flight.
+                    yield db.blobDownloadTracker.drainPendingSaves();
+                    debugLog(`Eager download: done (${totalProcessed} row(s) processed)`);
+                }
+                else {
+                    debugLog('Eager download: No blobs remaining, exiting');
                 }
             }
             finally {
-                setDownloadingState(downloading$, false);
+                if (started)
+                    setDownloadingState(downloading$, false);
             }
         });
     }
@@ -16960,99 +17204,6 @@
         };
     }
 
-    /**
-     * BlobSavingQueue - Queues resolved blobs for saving back to IndexedDB
-     *
-     * Uses setTimeout(fn, 0) instead of queueMicrotask to completely isolate
-     * from Dexie's Promise.PSD context. This prevents the save operation
-     * from inheriting any ongoing transaction.
-     *
-     * Each blob is saved atomically using downCore transaction with the specific
-     * keyPath to avoid race conditions with other property changes.
-     */
-    class BlobSavingQueue {
-        constructor(db) {
-            this.queue = [];
-            this.isProcessing = false;
-            this.db = db;
-        }
-        /**
-         * Queue a resolved blob for saving.
-         * Only the specific blob property will be updated atomically.
-         */
-        saveBlobs(tableName, primaryKey, resolvedBlobs) {
-            this.queue.push({ tableName, primaryKey, resolvedBlobs });
-            this.startConsumer();
-        }
-        /**
-         * Start the consumer if not already processing.
-         * Uses setTimeout(fn, 0) to completely break out of any
-         * Dexie transaction context (Promise.PSD).
-         */
-        startConsumer() {
-            if (this.isProcessing)
-                return;
-            this.isProcessing = true;
-            // Use setTimeout to completely isolate from Dexie's PSD context
-            // queueMicrotask would risk inheriting the current transaction
-            setTimeout(() => {
-                this.processQueue();
-            }, 0);
-        }
-        /**
-         * Process all queued blobs.
-         * Runs in a completely isolated context (no inherited transaction).
-         * Uses atomic updates to avoid race conditions.
-         */
-        processQueue() {
-            const item = this.queue.shift();
-            if (!item) {
-                this.isProcessing = false;
-                return;
-            }
-            // Atomic update of just the blob property
-            this.db
-                .transaction('rw', item.tableName, (tx) => {
-                const trans = tx.idbtrans;
-                trans.disableChangeTracking = true; // Don't regard this as a change for sync purposes
-                trans.disableAccessControl = true; // Bypass any access control checks since this is an internal operation
-                trans.disableBlobResolve = true; // Custom flag to skip blob resolve middleware during this transaction
-                const updateSpec = {};
-                for (const blob of item.resolvedBlobs) {
-                    updateSpec[blob.keyPath] = blob.data;
-                }
-                tx.table(item.tableName).update(item.primaryKey, (obj) => {
-                    // Check that object still has the same unresolved blob refs before applying update (i.e. it hasn't been modified since we read it)
-                    for (const blob of item.resolvedBlobs) {
-                        // Verify atomicity - none of the blob properties has been modified since we read it. If any of them was modified, skip updating this item to avoid overwriting user changes.
-                        const currentValue = Dexie.getByKeyPath(obj, blob.keyPath);
-                        if (currentValue === undefined) {
-                            // Blob property was removed - skip updating this blob
-                            continue;
-                        }
-                        if (!isBlobRef(currentValue)) {
-                            // Blob property was modified to a non-blob-ref value - skip updating this blob
-                            continue;
-                        }
-                        if (currentValue.ref !== blob.ref) {
-                            // Blob property was modified - skip updating this blob
-                            return; // Stop. Another items has been queued to fully fix the object.
-                        }
-                        Dexie.setByKeyPath(obj, blob.keyPath, blob.data);
-                    }
-                    delete obj._hasBlobRefs; // Clear the _hasBlobRefs marker if all refs was resolved.
-                });
-            })
-                .catch((error) => {
-                console.error(`Error saving resolved blobs on ${item.tableName}:${item.primaryKey}:`, error);
-            })
-                .finally(() => {
-                // Process next item in the queue
-                return this.processQueue();
-            });
-        }
-    }
-
     /**
      * DBCore Middleware for resolving BlobRefs on read
      *
@@ -17063,10 +17214,11 @@
      * Uses Dexie.waitFor() only for explicit rw transactions to keep them alive.
      * For readonly or implicit transactions, resolves directly (no waitFor needed).
      *
-     * Resolved blobs are queued for saving via BlobSavingQueue, which uses
-     * setTimeout(fn, 0) to completely isolate from Dexie's transaction context.
-     * Each blob is saved atomically using Table.update() with its keyPath to
-     * avoid race conditions with other property changes.
+     * Resolved blobs are persisted via db.blobDownloadTracker.enqueueSave(),
+     * which internally uses a queue that runs in a fresh JS task to completely
+     * isolate from Dexie's transaction context. Each blob is saved atomically
+     * using Table.update() with its keyPath to avoid race conditions with other
+     * property changes.
      *
      * Blob downloads use Authorization header (same as sync) via the server
      * proxy endpoint: GET /blob/{ref}
@@ -17077,8 +17229,6 @@
             name: 'blobResolve',
             level: 2, // Run above cache (0) and other middlewares (1) to resolve BlobRefs from cached data
             create(downlevelDatabase) {
-                // Create a single queue instance for this database
-                const blobSavingQueue = new BlobSavingQueue(db);
                 return Object.assign(Object.assign({}, downlevelDatabase), { table(tableName) {
                         var _a;
                         if (!db.cloud) {
@@ -17099,7 +17249,7 @@
                                 }
                                 return downlevelTable.get(req).then((result) => {
                                     if (result && hasUnresolvedBlobRefs(result)) {
-                                        return resolveAndSave(downlevelTable, req.trans, req.key, result, blobSavingQueue, db);
+                                        return resolveAndSave(downlevelTable, req.trans, req.key, result, db);
                                     }
                                     return result;
                                 });
@@ -17116,7 +17266,7 @@
                                         return results;
                                     return Dexie.Promise.all(results.map((result, index) => {
                                         if (result && hasUnresolvedBlobRefs(result)) {
-                                            return resolveAndSave(downlevelTable, req.trans, req.keys[index], result, blobSavingQueue, db);
+                                            return resolveAndSave(downlevelTable, req.trans, req.keys[index], result, db);
                                         }
                                         return result;
                                     }));
@@ -17136,7 +17286,7 @@
                                         return result;
                                     return Dexie.Promise.all(result.result.map((item) => {
                                         if (item && hasUnresolvedBlobRefs(item)) {
-                                            return resolveAndSave(downlevelTable, req.trans, undefined, item, blobSavingQueue, db);
+                                            return resolveAndSave(downlevelTable, req.trans, undefined, item, db);
                                         }
                                         return item;
                                     })).then((resolved) => (Object.assign(Object.assign({}, result), { result: resolved })));
@@ -17154,7 +17304,7 @@
                                         return cursor; // No values requested, so no resolution needed
                                     if (!dbUrl)
                                         return cursor; // No database URL configured, can't resolve blobs
-                                    return createBlobResolvingCursor(cursor, downlevelTable, blobSavingQueue, db);
+                                    return createBlobResolvingCursor(cursor, downlevelTable, db);
                                 });
                             } });
                     } });
@@ -17171,7 +17321,7 @@
      * Returns the cursor synchronously. Resolution happens in start() before
      * each onNext callback, ensuring cursor.value is always available.
      */
-    function createBlobResolvingCursor(cursor, table, blobSavingQueue, db) {
+    function createBlobResolvingCursor(cursor, table, db) {
         // Create wrapped cursor using Object.create() - inherits everything.
         // Important: .key and .primaryKey must be explicitly overridden with
         // closure-based getters to prevent native IDBCursorWithValue getters from
@@ -17179,11 +17329,15 @@
         // throws "Illegal invocation" in Chrome 146+.
         const wrappedCursor = Object.create(cursor, {
             key: {
-                get() { return cursor.key; },
+                get() {
+                    return cursor.key;
+                },
                 configurable: true,
             },
             primaryKey: {
-                get() { return cursor.primaryKey; },
+                get() {
+                    return cursor.primaryKey;
+                },
                 configurable: true,
             },
             value: {
@@ -17201,7 +17355,7 @@
                             onNext();
                             return;
                         }
-                        resolveAndSave(table, cursor.trans, cursor.primaryKey, rawValue, blobSavingQueue, db, true).then((resolved) => {
+                        resolveAndSave(table, cursor.trans, cursor.primaryKey, rawValue, db, true).then((resolved) => {
                             wrappedCursor.value = resolved;
                             onNext();
                         }, (err) => {
@@ -17229,7 +17383,7 @@
      * Returns Dexie.Promise to preserve PSD context.
      */
     function resolveAndSave(table, trans, pKey, // optional. If missing, tries to extract from object using primary key path
-    obj, blobSavingQueue, db, isCursorValue = false // Flag to indicate if we're resolving a cursor value (which may not have a primary key)
+    obj, db, isCursorValue = false // Flag to indicate if we're resolving a cursor value (which may not have a primary key)
     ) {
         var _a;
         try {
@@ -17266,21 +17420,19 @@
                         ? Dexie.getByKeyPath(obj, primaryKey.keyPath)
                         : undefined;
                 if (key !== undefined) {
-                    // Queue each resolved blob individually for atomic update
-                    // This uses setTimeout(fn, 0) to completely isolate from
-                    // Dexie's transaction context (avoids inheriting PSD)
-                    if (isReadonly) {
-                        blobSavingQueue.saveBlobs(table.name, key, resolvedBlobs);
-                    }
-                    else {
-                        // For rw transactions, we can save directly without queueing
-                        // since we're still in the same transaction context
-                        table
-                            .mutate({ type: 'put', keys: [key], values: [resolved], trans })
-                            .catch((err) => {
-                            console.error(`Failed to save resolved blob on ${table.name}:${key}:`, err);
-                        });
-                    }
+                    // Hand off persistence to the tracker. The tracker owns an
+                    // internal save-queue that runs in a fresh JS task (setTimeout 0)
+                    // — completely outside any PSD context, so opening a Dexie rw
+                    // transaction there is always safe regardless of the calling
+                    // context. The tracker also keeps the in-flight download cache
+                    // alive until the save completes, so concurrent readers piggyback
+                    // on the already-downloaded data instead of refetching.
+                    db.blobDownloadTracker.enqueueSave(table.name, key, resolvedBlobs);
+                }
+                else if (resolvedBlobs.length > 0) {
+                    // No primary key — we can't persist. Release the in-flight cache
+                    // entries explicitly so they don't leak.
+                    db.blobDownloadTracker.releaseRefs(resolvedBlobs.map((b) => b.ref));
                 }
                 return resolved;
             })
@@ -19570,7 +19722,7 @@
         const downloading$ = createDownloadingState();
         dexie.cloud = {
             // @ts-ignore
-            version: "4.4.11",
+            version: "4.4.13",
             options: Object.assign({}, DEFAULT_OPTIONS),
             schema: null,
             get currentUserId() {
@@ -20015,7 +20167,7 @@
         }
     }
     // @ts-ignore
-    dexieCloud.version = "4.4.11";
+    dexieCloud.version = "4.4.13";
     Dexie.Cloud = dexieCloud;
 
     // In case the SW lives for a while, let it reuse already opened connections: