dexie-cloud-addon 4.4.11 → 4.4.12

package/dist/modern/service-worker.js

@@ -8,7 +8,7 @@
  *
  * ==========================================================================
  *
- * Version 4.4.11, Sun Apr 19 2026
+ * Version 4.4.12, Mon May 25 2026
  *
  * https://dexie.org
  *
@@ -4263,22 +4263,208 @@ function MessagesFromServerConsumer(db) {
 }
 
 /**
- * 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')
@@ -4286,45 +4472,103 @@ class BlobDownloadTracker {
     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();
@@ -4545,118 +4789,116 @@ function findBlobRefs(obj) {
  * 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);
         }
     });
 }
@@ -5992,99 +6234,6 @@ function createMutationTrackingMiddleware({ currentUserObservable, db, }) {
     };
 }
 
-/**
- * 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
  *
@@ -6095,10 +6244,11 @@ class BlobSavingQueue {
  * 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}
@@ -6109,8 +6259,6 @@ function createBlobResolveMiddleware(db) {
         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) {
@@ -6131,7 +6279,7 @@ function createBlobResolveMiddleware(db) {
                             }
                             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;
                             });
@@ -6148,7 +6296,7 @@ function createBlobResolveMiddleware(db) {
                                     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;
                                 }));
@@ -6168,7 +6316,7 @@ function createBlobResolveMiddleware(db) {
                                     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 })));
@@ -6186,7 +6334,7 @@ function createBlobResolveMiddleware(db) {
                                     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);
                             });
                         } });
                 } });
@@ -6203,7 +6351,7 @@ function createBlobResolveMiddleware(db) {
  * 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
@@ -6211,11 +6359,15 @@ function createBlobResolvingCursor(cursor, table, blobSavingQueue, db) {
     // 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: {
@@ -6233,7 +6385,7 @@ function createBlobResolvingCursor(cursor, table, blobSavingQueue, db) {
                         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) => {
@@ -6261,7 +6413,7 @@ function createBlobResolvingCursor(cursor, table, blobSavingQueue, db) {
  * 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 {
@@ -6298,21 +6450,19 @@ obj, blobSavingQueue, db, isCursorValue = false // Flag to indicate if we're res
                     ? 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;
         })
@@ -8340,7 +8490,7 @@ function dexieCloud(dexie) {
     const downloading$ = createDownloadingState();
     dexie.cloud = {
         // @ts-ignore
-        version: "4.4.11",
+        version: "4.4.12",
         options: Object.assign({}, DEFAULT_OPTIONS),
         schema: null,
         get currentUserId() {
@@ -8785,7 +8935,7 @@ function dexieCloud(dexie) {
     }
 }
 // @ts-ignore
-dexieCloud.version = "4.4.11";
+dexieCloud.version = "4.4.12";
 Dexie.Cloud = dexieCloud;
 
 // In case the SW lives for a while, let it reuse already opened connections: