@evolu/web 3.3.0 → 3.4.1

package/dist/src/Sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sqlite.d.ts","sourceRoot":"","sources":["../../src/Sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,eAAe,CAAC;AAqCnE,eAAO,MAAM,sBAAsB,EAAE,kBAyLlC,CAAC"}
+{"version":3,"file":"Sqlite.d.ts","sourceRoot":"","sources":["../../src/Sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,eAAe,CAAC;AAqCnE,eAAO,MAAM,sBAAsB,EAAE,kBA4LlC,CAAC"}

package/dist/src/Sqlite.js

@@ -81,9 +81,11 @@ export const createWasmSqliteDriver = (name, options) => async (run) => {
             // DbWorker that ended without closing it, because its tab closed,
             // crashed or navigated away, can hold pool files after the lock has
             // passed on: WebKit releases a terminated worker's locks and its files
-            // separately, in no set order. sqlite-wasm cannot set up a pool with a
-            // held file, and it then deletes the pool directory, which the held file
-            // usually but not always prevents. Only a worker that has ended can hold
+            // separately, in no set order
+            // (https://bugs.webkit.org/show_bug.cgi?id=301520). sqlite-wasm cannot
+            // set up a pool with a held file, and it then deletes the pool
+            // directory, which the held file usually but not always prevents. Only
+            // a worker that has ended can hold
             // the files, and it can only release them, so the pool is set up once
             // every file opens.
             const canOpenPoolFiles = async () => {
@@ -101,7 +103,8 @@ export const createWasmSqliteDriver = (name, options) => async (run) => {
                     const accessHandle = await tryAsync(() => handle.createSyncAccessHandle());
                     if (!accessHandle.ok) {
                         // WebKit rejects a held file with InvalidStateError, other
-                        // engines with NoModificationAllowedError, as the spec says.
+                        // engines with NoModificationAllowedError, as the spec says
+                        // (https://bugs.webkit.org/show_bug.cgi?id=326135).
                         // WebKit also uses InvalidStateError for a closed or invalid
                         // handle and a stopped context. A retry opens fresh handles from
                         // a new listing, and a stopped context ends the loop with its

package/dist/src/local-first/Evolu.d.ts

@@ -1,27 +1,11 @@
 import { type ConsoleDep, type ReloadAppDep } from "@evolu/common";
-import type { EvoluDeps } from "@evolu/common/local-first";
+import type { EvoluDeps, RequestPersistentStorageDep } from "@evolu/common/local-first";
 export interface SharedWorkerUnsupported {
     readonly type: "SharedWorkerUnsupported";
 }
 export interface SharedWorkerUnsupportedDep {
     readonly onSharedWorkerUnsupported: () => void;
 }
-export interface StorageUnavailableDep {
-    /**
-     * Called when the browser offers no persistent storage, as in Safari's
-     * Private Browsing, so every database is kept in memory. See Storage in the
-     * Shared module of `@evolu/common`.
-     *
-     * The app keeps working. Data synced with a relay comes back, as on a new
-     * device, and nothing stays on the device once the tabs close. That suits
-     * someone checking their app on a borrowed phone, so a message such as
-     * "Nothing from this session is kept on this device." tells the user what to
-     * expect. Data that exists only locally, or has not synced yet, is lost when
-     * the tab hosting the database closes or navigates away, even while other
-     * tabs stay open.
-     */
-    readonly onStorageUnavailable: () => void;
-}
 /**
  * Creates Evolu dependencies for the web platform.
  *
@@ -38,18 +22,30 @@ export interface StorageUnavailableDep {
  *
  * When the page enters the browser's back-forward cache, as Safari does on
  * every navigation away, this tab ends its part as if it closed: it stops the
- * database workers it hosts, so another tab takes them over, and it reloads if
- * the user comes back to it.
+ * database workers it hosts, so another tab takes them over, the shared worker
+ * ends this tab's Evolu instances, and the tab reloads if the user comes back
+ * to it.
  *
  * Where the browser offers no persistent storage, as in Safari's Private
- * Browsing, the database is kept in memory, and
- * {@link StorageUnavailableDep.onStorageUnavailable} lets the app tell the
- * user.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * A custom {@link ReloadApp} replaces the default page reload, for example to
  * save state first. It should end by reloading the page, because the other
  * build waits until this tab reloads or closes, and a page restored from the
  * back-forward cache cannot work until it reloads.
  */
-export declare const createEvoluDeps: (deps?: Partial<ConsoleDep> & Partial<ReloadAppDep> & Partial<SharedWorkerUnsupportedDep> & Partial<StorageUnavailableDep>) => EvoluDeps;
+export declare const createEvoluDeps: (deps?: Partial<ConsoleDep> & Partial<ReloadAppDep> & Partial<SharedWorkerUnsupportedDep> & Partial<RequestPersistentStorageDep>) => EvoluDeps;
 //# sourceMappingURL=Evolu.d.ts.map

package/dist/src/local-first/Evolu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Evolu.d.ts","sourceRoot":"","sources":["../../../src/local-first/Evolu.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEf,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAIV,SAAS,EAIV,MAAM,2BAA2B,CAAC;AAgBnC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,UACpB,OAAO,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,YAAY,CAAC,GACrB,OAAO,CAAC,0BAA0B,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC,KAC/B,SAiPF,CAAC"}
+{"version":3,"file":"Evolu.d.ts","sourceRoot":"","sources":["../../../src/local-first/Evolu.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAKV,SAAS,EACT,2BAA2B,EAI5B,MAAM,2BAA2B,CAAC;AAgBnC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,eAAe,UACpB,OAAO,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,YAAY,CAAC,GACrB,OAAO,CAAC,0BAA0B,CAAC,GACnC,OAAO,CAAC,2BAA2B,CAAC,KACrC,SAgSF,CAAC"}

package/dist/src/local-first/Evolu.js

@@ -50,7 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { exhaustiveCheck, trySync, } from "@evolu/common";
+import { exhaustiveCheck, tryAsync, trySync, } from "@evolu/common";
 import { BuildWaiting, BuildWaitingRequest, buildsBroadcastChannelName, createEvoluDeps as createCommonEvoluDeps, } from "@evolu/common/local-first";
 import { reloadApp } from "../Platform.js";
 import { createBroadcastChannel, createMessageChannel, createSharedWorker, createWorker, installOneTabSharedWorkerPolyfill, } from "../Worker.js";
@@ -70,13 +70,25 @@ import { createBroadcastChannel, createMessageChannel, createSharedWorker, creat
  *
  * When the page enters the browser's back-forward cache, as Safari does on
  * every navigation away, this tab ends its part as if it closed: it stops the
- * database workers it hosts, so another tab takes them over, and it reloads if
- * the user comes back to it.
+ * database workers it hosts, so another tab takes them over, the shared worker
+ * ends this tab's Evolu instances, and the tab reloads if the user comes back
+ * to it.
  *
  * Where the browser offers no persistent storage, as in Safari's Private
- * Browsing, the database is kept in memory, and
- * {@link StorageUnavailableDep.onStorageUnavailable} lets the app tell the
- * user.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * A custom {@link ReloadApp} replaces the default page reload, for example to
  * save state first. It should end by reloading the page, because the other
@@ -105,6 +117,7 @@ export const createEvoluDeps = (deps = {}) => {
         const earlyAnnouncedWorkerIds = new Set();
         // Checks whether the user left this tab while another build waits.
         let focusCheckId = null;
+        let isPersistentStorageRequested = false;
         const disposer = __addDisposableResource(env_1, new DisposableStack(), false);
         const buildsBroadcastChannel = disposer.use(createBroadcastChannel(buildsBroadcastChannelName));
         const stopFocusCheck = () => {
@@ -206,11 +219,6 @@ export const createEvoluDeps = (deps = {}) => {
                     });
                     break;
                 }
-                case "StorageUnavailable": {
-                    deps.onStorageUnavailable?.();
-                    forward(message);
-                    break;
-                }
                 case "SharedWorkerUnsupported": {
                     if (deps.onSharedWorkerUnsupported) {
                         deps.onSharedWorkerUnsupported();
@@ -259,20 +267,55 @@ export const createEvoluDeps = (deps = {}) => {
                 },
             },
         };
+        const requestPersistentStorage = () => {
+            if (isPersistentStorageRequested)
+                return;
+            isPersistentStorageRequested = true;
+            void tryAsync(async () => {
+                if (await navigator.storage.persisted())
+                    return;
+                await navigator.storage.persist();
+            });
+        };
+        // Disposing the deps releases the locks this page holds through them, as
+        // closing the page would, and a lock granted afterwards is released at once.
+        // The SharedWorker learns that an Evolu instance ended when it gets the lock
+        // the instance holds. Chrome keeps the locks of a page in its back-forward
+        // cache, and a request made before the page entered the cache waits until
+        // Chrome drops the page (https://issues.chromium.org/issues/567630881), so
+        // the SharedWorker would keep syncing the owners of a cached tab's instances
+        // and rerunning their queries.
+        let areLocksReleased = false;
+        const locksReleased = Promise.withResolvers();
+        disposer.defer(() => {
+            areLocksReleased = true;
+            locksReleased.resolve();
+        });
+        function requestLock(name, ...args) {
+            const [options, callback] = args.length === 1 ? [{}, args[0]] : args;
+            return navigator.locks.request(name, options, (lock) => areLocksReleased
+                ? undefined
+                : Promise.race([callback(lock), locksReleased.promise]));
+        }
         const evoluDeps = disposer.use(createCommonEvoluDeps({
+            requestPersistentStorage,
             ...deps,
             createDbWorker,
             createBroadcastChannel,
             createMessageChannel,
-            lockManager: navigator.locks,
+            lockManager: {
+                query: () => navigator.locks.query(),
+                request: requestLock,
+            },
             reloadApp: reloadThisApp,
             sharedWorker,
         }));
-        // A page entering the back-forward cache is frozen with its DbWorkers, which
-        // keep their database locks, so the other tabs would stall. WebKit also
-        // releases the page's own locks, so a restored page would work with state
-        // the other tabs gave up on. The page therefore ends its part as if it
-        // closed, and reloads when it is shown again.
+        // A page entering the back-forward cache is frozen with its DbWorkers, and
+        // WebKit keeps their database locks while the page is cached
+        // (https://bugs.webkit.org/show_bug.cgi?id=316904), so the other tabs would
+        // stall. WebKit also releases the page's own locks, so a restored page would
+        // work with state the other tabs gave up on. The page therefore ends its part
+        // as if it closed, and reloads when it is shown again.
         const reloadRestoredPage = (event) => {
             if (event.persisted)
                 reloadThisApp();

package/dist/src/local-first/Shared.worker.js

@@ -66,8 +66,12 @@ addUncaughtErrorListener(self, (error) => {
 const run = createRun({
     ...createWorkerDeps(),
     createWebSocket,
-    // Safari's Private Browsing offers no OPFS; see Storage in the Shared module.
-    isPersistentStorageAvailable: async () => (await tryAsync(() => navigator.storage.getDirectory())).ok,
+    // Safari's Private Browsing and Firefox's private windows offer no OPFS, and
+    // a browser may delete it, as Chrome's incognito does when the session ends;
+    // see Storage in the Shared module.
+    getDevicePersistence: async () => (await tryAsync(() => navigator.storage.getDirectory())).ok
+        ? "Unknown"
+        : "NotPersisted",
     lockManager: navigator.locks,
 });
 void run(async (run) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/web",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "Evolu for web",
   "keywords": [
     "evolu",
@@ -35,7 +35,7 @@
     "@evolu/sqlite-wasm": "2.2.4"
   },
   "devDependencies": {
-    "@evolu/common": "8.13.0",
+    "@evolu/common": "8.18.0",
     "@evolu/typescript-config": "0.1.1",
     "@types/node": "^24.10.9",
     "@types/sharedworker": "^0.0.229",
@@ -44,7 +44,7 @@
     "user-agent-data-types": "^0.4.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.13.0"
+    "@evolu/common": "^8.18.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Sqlite.ts

@@ -53,9 +53,11 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
       // DbWorker that ended without closing it, because its tab closed,
       // crashed or navigated away, can hold pool files after the lock has
       // passed on: WebKit releases a terminated worker's locks and its files
-      // separately, in no set order. sqlite-wasm cannot set up a pool with a
-      // held file, and it then deletes the pool directory, which the held file
-      // usually but not always prevents. Only a worker that has ended can hold
+      // separately, in no set order
+      // (https://bugs.webkit.org/show_bug.cgi?id=301520). sqlite-wasm cannot
+      // set up a pool with a held file, and it then deletes the pool
+      // directory, which the held file usually but not always prevents. Only
+      // a worker that has ended can hold
       // the files, and it can only release them, so the pool is set up once
       // every file opens.
       const canOpenPoolFiles = async (): Promise<boolean> => {
@@ -76,7 +78,8 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
           );
           if (!accessHandle.ok) {
             // WebKit rejects a held file with InvalidStateError, other
-            // engines with NoModificationAllowedError, as the spec says.
+            // engines with NoModificationAllowedError, as the spec says
+            // (https://bugs.webkit.org/show_bug.cgi?id=326135).
             // WebKit also uses InvalidStateError for a closed or invalid
             // handle and a stopped context. A retry opens fresh handles from
             // a new listing, and a stopped context ends the loop with its

package/src/local-first/Evolu.test.ts

@@ -1,4 +1,5 @@
 import {
+  acquireLeaderLock,
   assertEqual,
   assertFalse,
   assertNonNullable,
@@ -7,6 +8,7 @@ import {
   createConsole,
   createIdFromString,
   PositiveInt,
+  testCreateRun,
   testName,
   testStubGlobal,
   type NativeMessagePort,
@@ -148,26 +150,59 @@ describe("createEvoluDeps", () => {
     });
   });
 
-  describe("storage unavailable", () => {
-    const workerId = createIdFromString<"SharedWorker">("worker");
+  describe("persistent storage request", () => {
+    const setupStorage = (isPersisted: boolean) => ({
+      persisted: mock.fn(() => Promise.resolve(isPersisted)),
+      persist: mock.fn(() => Promise.resolve(true)),
+    });
 
-    it("tells the app when its worker keeps databases in memory", () => {
-      const onStorageUnavailable = mock.fn<() => void>();
-      using setup = setupWebEvoluDeps({ onStorageUnavailable });
-      setup.connect(workerId);
+    it("asks the browser once to keep the site's data", async () => {
+      const storage = setupStorage(false);
+      using setup = setupWebEvoluDeps({ storage });
 
-      setup.post({ type: "StorageUnavailable" });
+      setup.deps.requestPersistentStorage?.();
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
 
-      assertSame(onStorageUnavailable.mock.callCount(), 1);
+      assertSame(storage.persisted.mock.callCount(), 1);
+      assertSame(storage.persist.mock.callCount(), 1);
     });
 
-    it("works without a callback", () => {
-      using setup = setupWebEvoluDeps();
-      setup.connect(workerId);
+    it("does not ask when the site's data is already persistent", async () => {
+      const storage = setupStorage(true);
+      using setup = setupWebEvoluDeps({ storage });
 
-      setup.post({ type: "StorageUnavailable" });
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
 
-      assertSame(setup.reloadApp.mock.callCount(), 0);
+      assertSame(storage.persist.mock.callCount(), 0);
+    });
+
+    it("ignores a browser that refuses to answer", async () => {
+      const storage = {
+        persisted: mock.fn(() =>
+          Promise.reject(new TypeError("Storage is disabled.")),
+        ),
+        persist: mock.fn(() => Promise.resolve(true)),
+      };
+      using setup = setupWebEvoluDeps({ storage });
+
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
+
+      assertSame(storage.persist.mock.callCount(), 0);
+    });
+
+    it("uses the app's request instead", async () => {
+      const storage = setupStorage(false);
+      const requestPersistentStorage = mock.fn<() => void>();
+      using setup = setupWebEvoluDeps({ storage, requestPersistentStorage });
+
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
+
+      assertSame(requestPersistentStorage.mock.callCount(), 1);
+      assertSame(storage.persisted.mock.callCount(), 0);
     });
   });
 
@@ -189,6 +224,39 @@ describe("createEvoluDeps", () => {
       assertSame(setup.reloadApp.mock.callCount(), 0);
     });
 
+    it("releases the locks of its Evolu instances when the page enters the cache", async () => {
+      using setup = setupWebEvoluDeps();
+      await using run = testCreateRun({
+        lockManager: setup.deps.lockManager,
+      });
+      await using _instanceLock = await run.ok(
+        acquireLeaderLock("cached-instance"),
+      );
+      assertFalse(await isLockAvailable("evolu-leaderlock-cached-instance"));
+
+      setup.dispatchPageTransition("pagehide", true);
+      await waitForMacrotask();
+
+      assertTrue(await isLockAvailable("evolu-leaderlock-cached-instance"));
+    });
+
+    it("releases at once a lock granted after the page entered the cache", async () => {
+      using setup = setupWebEvoluDeps();
+      const name = "evolu-granted-after-cache";
+      const held = Promise.withResolvers<void>();
+      const holding = navigator.locks.request(name, () => held.promise);
+      const callback = mock.fn<LockGrantedCallback<void>>();
+      const request = setup.deps.lockManager.request(name, callback);
+
+      setup.dispatchPageTransition("pagehide", true);
+      held.resolve();
+      await holding;
+      await request;
+
+      assertSame(callback.mock.callCount(), 0);
+      assertTrue(await isLockAvailable(name));
+    });
+
     it("reloads once when the page is restored from the cache", () => {
       using setup = setupWebEvoluDeps();
       setup.dispatchPageTransition("pageshow", false);
@@ -443,7 +511,8 @@ const setupWebEvoluDeps = ({
   isSessionStorageAvailable = true,
   refusalReloads,
   reloadedFor,
-  onStorageUnavailable,
+  storage,
+  requestPersistentStorage,
 }: {
   hasFocus?: boolean;
   isAutomaticReload?: boolean;
@@ -452,7 +521,9 @@ const setupWebEvoluDeps = ({
   refusalReloads?: string;
   /** The stored waiting workers, as a previous page load left them. */
   reloadedFor?: string;
-  onStorageUnavailable?: () => void;
+  /** Stands in for `navigator.storage`. */
+  storage?: Pick<StorageManager, "persist" | "persisted">;
+  requestPersistentStorage?: () => void;
 } = {}) => {
   using disposer = new DisposableStack();
   const sharedWorkerPort = createClosableNativePort<unknown>();
@@ -539,12 +610,17 @@ const setupWebEvoluDeps = ({
   );
   let hasFocus = initialHasFocus;
   disposer.use(testStubGlobal("document", { hasFocus: () => hasFocus }));
+  if (storage) {
+    disposer.use(
+      testStubGlobal("navigator", { locks: navigator.locks, storage }),
+    );
+  }
   const reloadApp = mock.fn<ReloadApp>();
 
   const deps = createEvoluDeps({
     console: createConsole({ level: "silent" }),
     reloadApp,
-    ...(onStorageUnavailable && { onStorageUnavailable }),
+    ...(requestPersistentStorage && { requestPersistentStorage }),
   });
   const builds = channels.find(
     (channel) => channel.name === buildsBroadcastChannelName,

package/src/local-first/Evolu.ts

@@ -1,5 +1,6 @@
 import {
   exhaustiveCheck,
+  tryAsync,
   trySync,
   type ConsoleDep,
   type ReloadApp,
@@ -10,7 +11,9 @@ import type {
   SharedWorker as CommonSharedWorker,
   CreateDbWorker,
   DbWorkerInit,
+  Evolu,
   EvoluDeps,
+  RequestPersistentStorageDep,
   SharedWorkerId,
   SharedWorkerInput,
   SharedWorkerOutput,
@@ -38,23 +41,6 @@ export interface SharedWorkerUnsupportedDep {
   readonly onSharedWorkerUnsupported: () => void;
 }
 
-export interface StorageUnavailableDep {
-  /**
-   * Called when the browser offers no persistent storage, as in Safari's
-   * Private Browsing, so every database is kept in memory. See Storage in the
-   * Shared module of `@evolu/common`.
-   *
-   * The app keeps working. Data synced with a relay comes back, as on a new
-   * device, and nothing stays on the device once the tabs close. That suits
-   * someone checking their app on a borrowed phone, so a message such as
-   * "Nothing from this session is kept on this device." tells the user what to
-   * expect. Data that exists only locally, or has not synced yet, is lost when
-   * the tab hosting the database closes or navigates away, even while other
-   * tabs stay open.
-   */
-  readonly onStorageUnavailable: () => void;
-}
-
 /**
  * Creates Evolu dependencies for the web platform.
  *
@@ -71,13 +57,25 @@ export interface StorageUnavailableDep {
  *
  * When the page enters the browser's back-forward cache, as Safari does on
  * every navigation away, this tab ends its part as if it closed: it stops the
- * database workers it hosts, so another tab takes them over, and it reloads if
- * the user comes back to it.
+ * database workers it hosts, so another tab takes them over, the shared worker
+ * ends this tab's Evolu instances, and the tab reloads if the user comes back
+ * to it.
  *
  * Where the browser offers no persistent storage, as in Safari's Private
- * Browsing, the database is kept in memory, and
- * {@link StorageUnavailableDep.onStorageUnavailable} lets the app tell the
- * user.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * A custom {@link ReloadApp} replaces the default page reload, for example to
  * save state first. It should end by reloading the page, because the other
@@ -88,7 +86,7 @@ export const createEvoluDeps = (
   deps: Partial<ConsoleDep> &
     Partial<ReloadAppDep> &
     Partial<SharedWorkerUnsupportedDep> &
-    Partial<StorageUnavailableDep> = {},
+    Partial<RequestPersistentStorageDep> = {},
 ): EvoluDeps => {
   installOneTabSharedWorkerPolyfill();
   const reloadThisApp = deps.reloadApp ?? reloadApp;
@@ -110,6 +108,7 @@ export const createEvoluDeps = (
   const earlyAnnouncedWorkerIds = new Set<SharedWorkerId>();
   // Checks whether the user left this tab while another build waits.
   let focusCheckId: ReturnType<typeof setInterval> | null = null;
+  let isPersistentStorageRequested = false;
 
   using disposer = new DisposableStack();
   const buildsBroadcastChannel = disposer.use(
@@ -225,12 +224,6 @@ export const createEvoluDeps = (
         break;
       }
 
-      case "StorageUnavailable": {
-        deps.onStorageUnavailable?.();
-        forward(message);
-        break;
-      }
-
       case "SharedWorkerUnsupported": {
         if (deps.onSharedWorkerUnsupported) {
           deps.onSharedWorkerUnsupported();
@@ -292,23 +285,75 @@ export const createEvoluDeps = (
     },
   };
 
+  const requestPersistentStorage = (): void => {
+    if (isPersistentStorageRequested) return;
+    isPersistentStorageRequested = true;
+    void tryAsync(async () => {
+      if (await navigator.storage.persisted()) return;
+      await navigator.storage.persist();
+    });
+  };
+
+  // Disposing the deps releases the locks this page holds through them, as
+  // closing the page would, and a lock granted afterwards is released at once.
+  // The SharedWorker learns that an Evolu instance ended when it gets the lock
+  // the instance holds. Chrome keeps the locks of a page in its back-forward
+  // cache, and a request made before the page entered the cache waits until
+  // Chrome drops the page (https://issues.chromium.org/issues/567630881), so
+  // the SharedWorker would keep syncing the owners of a cached tab's instances
+  // and rerunning their queries.
+  let areLocksReleased = false;
+  const locksReleased = Promise.withResolvers<void>();
+  disposer.defer(() => {
+    areLocksReleased = true;
+    locksReleased.resolve();
+  });
+
+  function requestLock<T>(
+    name: string,
+    callback: LockGrantedCallback<T>,
+  ): Promise<Awaited<T>>;
+  function requestLock<T>(
+    name: string,
+    options: LockOptions,
+    callback: LockGrantedCallback<T>,
+  ): Promise<Awaited<T>>;
+  function requestLock(
+    name: string,
+    ...args:
+      | [LockGrantedCallback<unknown>]
+      | [LockOptions, LockGrantedCallback<unknown>]
+  ): Promise<unknown> {
+    const [options, callback] = args.length === 1 ? [{}, args[0]] : args;
+    return navigator.locks.request(name, options, (lock) =>
+      areLocksReleased
+        ? undefined
+        : Promise.race([callback(lock), locksReleased.promise]),
+    );
+  }
+
   const evoluDeps = disposer.use(
     createCommonEvoluDeps({
+      requestPersistentStorage,
       ...deps,
       createDbWorker,
       createBroadcastChannel,
       createMessageChannel,
-      lockManager: navigator.locks,
+      lockManager: {
+        query: () => navigator.locks.query(),
+        request: requestLock,
+      },
       reloadApp: reloadThisApp,
       sharedWorker,
     }),
   );
 
-  // A page entering the back-forward cache is frozen with its DbWorkers, which
-  // keep their database locks, so the other tabs would stall. WebKit also
-  // releases the page's own locks, so a restored page would work with state
-  // the other tabs gave up on. The page therefore ends its part as if it
-  // closed, and reloads when it is shown again.
+  // A page entering the back-forward cache is frozen with its DbWorkers, and
+  // WebKit keeps their database locks while the page is cached
+  // (https://bugs.webkit.org/show_bug.cgi?id=316904), so the other tabs would
+  // stall. WebKit also releases the page's own locks, so a restored page would
+  // work with state the other tabs gave up on. The page therefore ends its part
+  // as if it closed, and reloads when it is shown again.
   const reloadRestoredPage = (event: PageTransitionEvent): void => {
     if (event.persisted) reloadThisApp();
   };

package/src/local-first/Shared.worker.ts

@@ -42,9 +42,13 @@ addUncaughtErrorListener(self, (error) => {
 const run = createRun({
   ...createWorkerDeps(),
   createWebSocket,
-  // Safari's Private Browsing offers no OPFS; see Storage in the Shared module.
-  isPersistentStorageAvailable: async () =>
-    (await tryAsync(() => navigator.storage.getDirectory())).ok,
+  // Safari's Private Browsing and Firefox's private windows offer no OPFS, and
+  // a browser may delete it, as Chrome's incognito does when the session ends;
+  // see Storage in the Shared module.
+  getDevicePersistence: async () =>
+    (await tryAsync(() => navigator.storage.getDirectory())).ok
+      ? "Unknown"
+      : "NotPersisted",
   lockManager: navigator.locks,
 });