@livestore/adapter-web 0.4.0-dev.8 → 0.4.0

package/src/web-worker/client-session/persisted-adapter.ts

@@ -1,53 +1,62 @@
-import type { Adapter, ClientSession, LockStatus } from '@livestore/common'
+import type { Adapter, BootWarningReason, ClientSession, LockStatus } from '@livestore/common'
 import {
   IntentionalShutdownCause,
+  isWorkerTransportError,
   liveStoreVersion,
   makeClientSession,
   StoreInterrupted,
   sessionChangesetMetaTable,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
 // TODO bring back - this currently doesn't work due to https://github.com/vitejs/vite/issues/8427
 // NOTE We're using a non-relative import here for Vite to properly resolve the import during app builds
 // import LiveStoreSharedWorker from '@livestore/adapter-web/internal-shared-worker?sharedworker'
 import { EventSequenceNumber } from '@livestore/common/schema'
 import { sqliteDbFactory } from '@livestore/sqlite-wasm/browser'
-import { loadSqlite3Wasm } from '@livestore/sqlite-wasm/load-wasm'
-import { isDevEnv, shouldNeverHappen, tryAsFunctionAndNew } from '@livestore/utils'
+import { isDevEnv, omitUndefineds, shouldNeverHappen, tryAsFunctionAndNew } from '@livestore/utils'
 import {
-  BrowserWorker,
   Cause,
   Deferred,
   Effect,
   Exit,
   Fiber,
   Layer,
-  ParseResult,
+  Option,
   Queue,
   Schema,
   Stream,
+  Subscribable,
   SubscriptionRef,
-  WebLock,
   Worker,
-  WorkerError,
 } from '@livestore/utils/effect'
+import { BrowserWorker, Opfs, WebError, WebLock } from '@livestore/utils/effect/browser'
 import { nanoid } from '@livestore/utils/nanoid'
 
-import * as OpfsUtils from '../../opfs-utils.ts'
-import { readPersistedAppDbFromClientSession, resetPersistedDataFromClientSession } from '../common/persisted-sqlite.ts'
+import { makeSingleTabAdapter } from '../../single-tab/single-tab-adapter.ts'
+import {
+  readPersistedStateDbFromClientSession,
+  resetPersistedDataFromClientSession,
+} from '../common/persisted-sqlite.ts'
 import { makeShutdownChannel } from '../common/shutdown-channel.ts'
 import { DedicatedWorkerDisconnectBroadcast, makeWorkerDisconnectChannel } from '../common/worker-disconnect-channel.ts'
 import * as WorkerSchema from '../common/worker-schema.ts'
 import { connectWebmeshNodeClientSession } from './client-session-devtools.ts'
+import { loadSqlite3 } from './sqlite-loader.ts'
 
-// NOTE we're starting to initialize the sqlite wasm binary here to speed things up
-const sqlite3Promise = loadSqlite3Wasm()
+/**
+ * Checks if SharedWorker API is available in the current browser context.
+ *
+ * Returns false on Android Chrome and other browsers without SharedWorker support.
+ *
+ * @see https://github.com/livestorejs/livestore/issues/321
+ * @see https://issues.chromium.org/issues/40290702
+ */
+export const canUseSharedWorker = (): boolean => typeof SharedWorker !== 'undefined'
 
-if (isDevEnv()) {
+if (isDevEnv() === true) {
   globalThis.__debugLiveStoreUtils = {
-    opfs: OpfsUtils,
-    runSync: (effect: Effect.Effect<any, any, never>) => Effect.runSync(effect),
-    runFork: (effect: Effect.Effect<any, any, never>) => Effect.runFork(effect),
+    ...globalThis.__debugLiveStoreUtils,
+    opfs: Opfs.debugUtils,
   }
 }
 
@@ -123,6 +132,15 @@ export type WebAdapterOptions = {
  * Creates a web adapter with persistent storage (currently only supports OPFS).
  * Requires both a web worker and a shared worker.
  *
+ * On browsers without SharedWorker support (e.g. Android Chrome), this adapter
+ * automatically falls back to single-tab mode. In single-tab mode:
+ * - Each tab runs independently with its own leader worker
+ * - Multi-tab synchronization is not available
+ * - Devtools are not supported
+ *
+ * @see https://github.com/livestorejs/livestore/issues/321 - SharedWorker tracking issue
+ * @see https://issues.chromium.org/issues/40290702 - Chromium SharedWorker bug
+ *
  * @example
  * ```ts
  * import { makePersistedAdapter } from '@livestore/adapter-web'
@@ -140,13 +158,49 @@ export const makePersistedAdapter =
   (options: WebAdapterOptions): Adapter =>
   (adapterArgs) =>
     Effect.gen(function* () {
-      const { schema, storeId, devtoolsEnabled, debugInstanceId, bootStatusQueue, shutdown, syncPayload } = adapterArgs
+      // Check SharedWorker availability first and fall back to single-tab mode if unavailable
+      if (canUseSharedWorker() === false) {
+        yield* Effect.logWarning(
+          '[@livestore/adapter-web] SharedWorker unavailable (e.g. Android Chrome). ' +
+            'Falling back to single-tab mode. Multi-tab synchronization and devtools are disabled. ' +
+            'See: https://github.com/livestorejs/livestore/issues/321',
+        )
+
+        return yield* makeSingleTabAdapter({
+          worker: options.worker,
+          storage: options.storage,
+          ...omitUndefineds({
+            resetPersistence: options.resetPersistence,
+            clientId: options.clientId,
+            sessionId: options.sessionId,
+            experimental: options.experimental,
+          }),
+        })(adapterArgs)
+      }
+
+      const {
+        schema,
+        storeId,
+        devtoolsEnabled,
+        debugInstanceId,
+        bootStatusQueue,
+        shutdown,
+        syncPayloadSchema: _syncPayloadSchema,
+        syncPayloadEncoded,
+      } = adapterArgs
+
+      // NOTE: The schema travels with the worker bundle (developers call
+      // `makeWorker({ schema, syncPayloadSchema })`). We only keep the
+      // destructured value here to document availability on the client session
+      // side—structured cloning the Effect schema into the worker is not
+      // possible, so we intentionally do not forward it.
+      void _syncPayloadSchema
 
       yield* ensureBrowserRequirements
 
       yield* Queue.offer(bootStatusQueue, { stage: 'loading' })
 
-      const sqlite3 = yield* Effect.promise(() => sqlite3Promise)
+      const sqlite3 = yield* Effect.promise(() => loadSqlite3())
 
       const LIVESTORE_TAB_LOCK = `livestore-tab-lock-${storeId}`
       const LIVESTORE_SHARED_WORKER_TERMINATION_LOCK = `livestore-shared-worker-termination-lock-${storeId}`
@@ -155,10 +209,21 @@ export const makePersistedAdapter =
 
       const shutdownChannel = yield* makeShutdownChannel(storeId)
 
-      if (options.resetPersistence === true) {
+      // Check OPFS availability early and notify user if storage is unavailable (e.g. private browsing)
+      const opfsWarning = yield* checkOpfsAvailability
+      if (opfsWarning !== undefined) {
+        yield* Effect.logWarning('[@livestore/adapter-web:client-session] OPFS unavailable', opfsWarning)
+      }
+
+      if (options.resetPersistence === true && opfsWarning === undefined) {
         yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'adapter-reset' }))
 
         yield* resetPersistedDataFromClientSession({ storageOptions, storeId })
+      } else if (options.resetPersistence === true) {
+        yield* Effect.logWarning(
+          '[@livestore/adapter-web:client-session] Skipping persistence reset because storage is unavailable',
+          opfsWarning,
+        )
       }
 
       // Note on fast-path booting:
@@ -168,9 +233,17 @@ export const makePersistedAdapter =
       // We need to be extra careful though to not run into any race conditions or inconsistencies.
       // TODO also verify persisted data
       const dataFromFile =
-        options.experimental?.disableFastPath === true
+        options.experimental?.disableFastPath === true || opfsWarning !== undefined
           ? undefined
-          : yield* readPersistedAppDbFromClientSession({ storageOptions, storeId, schema })
+          : yield* readPersistedStateDbFromClientSession({ storageOptions, storeId, schema }).pipe(
+              Effect.tapError((error) =>
+                Effect.logDebug('[@livestore/adapter-web:client-session] Could not read persisted state db', error, {
+                  storeId,
+                }),
+              ),
+              // If we get any error here, we return `undefined` to fall back to the slow path
+              Effect.orElseSucceed(() => undefined),
+            )
 
       // The same across all client sessions (i.e. tabs, windows)
       const clientId = options.clientId ?? getPersistedId(`clientId:${storeId}`, 'local')
@@ -182,7 +255,7 @@ export const makePersistedAdapter =
       yield* shutdownChannel.listen.pipe(
         Stream.flatten(),
         Stream.tap((cause) =>
-          shutdown(cause._tag === 'LiveStore.IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
+          shutdown(cause._tag === 'IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
         ),
         Stream.runDrain,
         Effect.interruptible,
@@ -192,7 +265,7 @@ export const makePersistedAdapter =
 
       const sharedWebWorker = tryAsFunctionAndNew(options.sharedWorker, { name: `livestore-shared-worker-${storeId}` })
 
-      if (options.experimental?.awaitSharedWorkerTermination) {
+      if (options.experimental?.awaitSharedWorkerTermination === true) {
         // Relying on the lock being available is currently the only mechanism we're aware of
         // to know whether the shared worker has terminated.
         yield* Effect.addFinalizer(() => WebLock.waitForLock(LIVESTORE_SHARED_WORKER_TERMINATION_LOCK))
@@ -202,25 +275,10 @@ export const makePersistedAdapter =
       const sharedWorkerFiber = yield* Worker.makePoolSerialized<typeof WorkerSchema.SharedWorkerRequest.Type>({
         size: 1,
         concurrency: 100,
-        initialMessage: () =>
-          new WorkerSchema.SharedWorkerInitialMessage({
-            liveStoreVersion,
-            payload: {
-              _tag: 'FromClientSession',
-              initialMessage: new WorkerSchema.LeaderWorkerInnerInitialMessage({
-                storageOptions,
-                storeId,
-                clientId,
-                devtoolsEnabled,
-                debugInstanceId,
-                syncPayload,
-              }),
-            },
-          }),
       }).pipe(
         Effect.provide(sharedWorkerContext),
         Effect.tapCauseLogPretty,
-        UnexpectedError.mapToUnexpectedError,
+        Effect.orDie,
         Effect.tapErrorCause((cause) => shutdown(Exit.failCause(cause))),
         Effect.withSpan('@livestore/adapter-web:client-session:setupSharedWorker'),
         Effect.forkScoped,
@@ -232,7 +290,7 @@ export const makePersistedAdapter =
       //
       // Sorry for this pun ...
       let gotLocky = yield* WebLock.tryGetDeferredLock(lockDeferred, LIVESTORE_TAB_LOCK)
-      const lockStatus = yield* SubscriptionRef.make<LockStatus>(gotLocky ? 'has-lock' : 'no-lock')
+      const lockStatus = yield* SubscriptionRef.make<LockStatus>(gotLocky === true ? 'has-lock' : 'no-lock')
 
       // Ideally we can come up with a simpler implementation that doesn't require this
       const waitForSharedWorkerInitialized = yield* Deferred.make<void>()
@@ -262,7 +320,7 @@ export const makePersistedAdapter =
           initialMessage: () => new WorkerSchema.LeaderWorkerOuterInitialMessage({ port: mc.port1, storeId, clientId }),
         }).pipe(
           Effect.provide(BrowserWorker.layer(() => worker)),
-          UnexpectedError.mapToUnexpectedError,
+          UnknownError.mapToUnknownError,
           Effect.tapErrorCause((cause) => shutdown(Exit.failCause(cause))),
           Effect.withSpan('@livestore/adapter-web:client-session:setupDedicatedWorker'),
           Effect.tapCauseLogPretty,
@@ -272,10 +330,25 @@ export const makePersistedAdapter =
         yield* workerDisconnectChannel.send(DedicatedWorkerDisconnectBroadcast.make({}))
 
         const sharedWorker = yield* Fiber.join(sharedWorkerFiber)
-        yield* sharedWorker.executeEffect(new WorkerSchema.SharedWorkerUpdateMessagePort({ port: mc.port2 })).pipe(
-          UnexpectedError.mapToUnexpectedError,
-          Effect.tapErrorCause((cause) => shutdown(Exit.failCause(cause))),
-        )
+        yield* sharedWorker
+          .executeEffect(
+            new WorkerSchema.SharedWorkerUpdateMessagePort({
+              port: mc.port2,
+              liveStoreVersion,
+              initial: new WorkerSchema.LeaderWorkerInnerInitialMessage({
+                storageOptions,
+                storeId,
+                clientId,
+                devtoolsEnabled,
+                debugInstanceId,
+                syncPayloadEncoded,
+              }),
+            }),
+          )
+          .pipe(
+            UnknownError.mapToUnknownError,
+            Effect.tapErrorCause((cause) => shutdown(Exit.failCause(cause))),
+          )
 
         yield* Deferred.succeed(waitForSharedWorkerInitialized, undefined)
 
@@ -302,15 +375,14 @@ export const makePersistedAdapter =
         yield* runLocked.pipe(Effect.interruptible, Effect.tapCauseLogPretty, Effect.forkScoped)
       }
 
-      const runInWorker = <TReq extends typeof WorkerSchema.SharedWorkerRequest.Type>(
-        req: TReq,
-      ): TReq extends Schema.WithResult<infer A, infer _I, infer E, infer _EI, infer R>
-        ? Effect.Effect<A, UnexpectedError | E, R>
-        : never =>
+      const runInWorker = <A, I, E, EI, R>(
+        req: WorkerSchema.SharedWorkerRequest & Schema.WithResult<A, I, E, EI, R>,
+      ): Effect.Effect<A, E, R> =>
         Fiber.join(sharedWorkerFiber).pipe(
           // NOTE we need to wait for the shared worker to be initialized before we can send requests to it
           Effect.tap(() => waitForSharedWorkerInitialized),
-          Effect.flatMap((worker) => worker.executeEffect(req) as any),
+          Effect.flatMap((worker) => worker.executeEffect(req)),
+          Effect.catchIf(isWorkerTransportError, (e) => Effect.die(e)),
           // NOTE we want to treat worker requests as atomic and therefore not allow them to be interrupted
           // Interruption usually only happens during leader re-election or store shutdown
           // Effect.uninterruptible,
@@ -319,40 +391,24 @@ export const makePersistedAdapter =
             duration: 2000,
           }),
           Effect.withSpan(`@livestore/adapter-web:client-session:runInWorker:${req._tag}`),
-          Effect.mapError((cause) =>
-            Schema.is(UnexpectedError)(cause)
-              ? cause
-              : ParseResult.isParseError(cause) || Schema.is(WorkerError.WorkerError)(cause)
-                ? new UnexpectedError({ cause })
-                : cause,
-          ),
-          Effect.catchAllDefect((cause) => new UnexpectedError({ cause })),
-        ) as any
-
-      const runInWorkerStream = <TReq extends typeof WorkerSchema.SharedWorkerRequest.Type>(
-        req: TReq,
-      ): TReq extends Schema.WithResult<infer A, infer _I, infer _E, infer _EI, infer R>
-        ? Stream.Stream<A, UnexpectedError, R>
-        : never =>
+        )
+
+      const runInWorkerStream = <A, I, E, EI, R>(
+        req: WorkerSchema.SharedWorkerRequest & Schema.WithResult<A, I, E, EI, R>,
+      ): Stream.Stream<A, E, R> =>
         Effect.gen(function* () {
           const sharedWorker = yield* Fiber.join(sharedWorkerFiber)
-          return sharedWorker.execute(req as any).pipe(
-            Stream.mapError((cause) =>
-              Schema.is(UnexpectedError)(cause)
-                ? cause
-                : ParseResult.isParseError(cause) || Schema.is(WorkerError.WorkerError)(cause)
-                  ? new UnexpectedError({ cause })
-                  : cause,
-            ),
+          return sharedWorker.execute(req).pipe(
+            Stream.refineOrDie((e) => isWorkerTransportError(e) === true ? Option.none() : Option.some(e)),
             Stream.withSpan(`@livestore/adapter-web:client-session:runInWorkerStream:${req._tag}`),
           )
-        }).pipe(Stream.unwrap) as any
+        }).pipe(Stream.unwrap)
 
       const bootStatusFiber = yield* runInWorkerStream(new WorkerSchema.LeaderWorkerInnerBootStatusStream()).pipe(
         Stream.tap((_) => Queue.offer(bootStatusQueue, _)),
         Stream.runDrain,
         Effect.tapErrorCause((cause) =>
-          Cause.isInterruptedOnly(cause) ? Effect.void : shutdown(Exit.failCause(cause)),
+          Cause.isInterruptedOnly(cause) === true ? Effect.void : shutdown(Exit.failCause(cause)),
         ),
         Effect.interruptible,
         Effect.tapCauseLogPretty,
@@ -389,7 +445,7 @@ export const makePersistedAdapter =
       const numberOfTables =
         sqliteDb.select<{ count: number }>(`select count(*) as count from sqlite_master`)[0]?.count ?? 0
       if (numberOfTables === 0) {
-        return yield* UnexpectedError.make({
+        return yield* UnknownError.make({
           cause: `Encountered empty or corrupted database`,
           payload: { snapshotByteLength: initialResult.snapshot.byteLength, storageOptions: options.storage },
         })
@@ -407,20 +463,21 @@ export const makePersistedAdapter =
           .first(),
       )
 
-      const initialLeaderHead = initialLeaderHeadRes
-        ? EventSequenceNumber.make({
-            global: initialLeaderHeadRes.seqNumGlobal,
-            client: initialLeaderHeadRes.seqNumClient,
-            rebaseGeneration: initialLeaderHeadRes.seqNumRebaseGeneration,
-          })
-        : EventSequenceNumber.ROOT
+      const initialLeaderHead =
+        initialLeaderHeadRes !== undefined
+          ? EventSequenceNumber.Client.Composite.make({
+              global: initialLeaderHeadRes.seqNumGlobal,
+              client: initialLeaderHeadRes.seqNumClient,
+              rebaseGeneration: initialLeaderHeadRes.seqNumRebaseGeneration,
+            })
+          : EventSequenceNumber.Client.ROOT
 
       // console.debug('[@livestore/adapter-web:client-session] initialLeaderHead', initialLeaderHead)
 
       yield* Effect.addFinalizer((ex) =>
         Effect.gen(function* () {
           if (
-            Exit.isFailure(ex) &&
+            Exit.isFailure(ex) === true &&
             Exit.isInterrupted(ex) === false &&
             Schema.is(IntentionalShutdownCause)(Cause.squash(ex.cause)) === false &&
             Schema.is(StoreInterrupted)(Cause.squash(ex.cause)) === false
@@ -430,7 +487,7 @@ export const makePersistedAdapter =
             yield* Effect.logDebug('[@livestore/adapter-web:client-session] client-session shutdown', gotLocky, ex)
           }
 
-          if (gotLocky) {
+          if (gotLocky === true) {
             yield* Deferred.succeed(lockDeferred, undefined)
           }
         }).pipe(Effect.tapCauseLogPretty, Effect.orDie),
@@ -438,8 +495,7 @@ export const makePersistedAdapter =
 
       const leaderThread: ClientSession['leaderThread'] = {
         export: runInWorker(new WorkerSchema.LeaderWorkerInnerExport()).pipe(
-          Effect.timeout(10_000),
-          UnexpectedError.mapToUnexpectedError,
+          Effect.timeoutOrDie(10_000),
           Effect.withSpan('@livestore/adapter-web:client-session:export'),
         ),
 
@@ -452,26 +508,39 @@ export const makePersistedAdapter =
                 attributes: { batchSize: batch.length },
               }),
             ),
+          stream: (options) =>
+            runInWorkerStream(new WorkerSchema.LeaderWorkerInnerStreamEvents(options)).pipe(
+              Stream.withSpan('@livestore/adapter-web:client-session:streamEvents'),
+              Stream.orDie,
+            ),
         },
 
-        initialState: { leaderHead: initialLeaderHead, migrationsReport },
+        initialState: {
+          leaderHead: initialLeaderHead,
+          migrationsReport,
+          storageMode: opfsWarning === undefined ? 'persisted' : 'in-memory',
+        },
 
         getEventlogData: runInWorker(new WorkerSchema.LeaderWorkerInnerExportEventlog()).pipe(
-          Effect.timeout(10_000),
-          UnexpectedError.mapToUnexpectedError,
+          Effect.timeoutOrDie(10_000),
           Effect.withSpan('@livestore/adapter-web:client-session:getEventlogData'),
         ),
 
-        getSyncState: runInWorker(new WorkerSchema.LeaderWorkerInnerGetLeaderSyncState()).pipe(
-          UnexpectedError.mapToUnexpectedError,
-          Effect.withSpan('@livestore/adapter-web:client-session:getLeaderSyncState'),
-        ),
+        syncState: Subscribable.make({
+          get: runInWorker(new WorkerSchema.LeaderWorkerInnerGetLeaderSyncState()).pipe(
+            Effect.withSpan('@livestore/adapter-web:client-session:getLeaderSyncState'),
+          ),
+          changes: runInWorkerStream(new WorkerSchema.LeaderWorkerInnerSyncStateStream()).pipe(Stream.orDie),
+        }),
 
         sendDevtoolsMessage: (message) =>
           runInWorker(new WorkerSchema.LeaderWorkerInnerExtraDevtoolsMessage({ message })).pipe(
-            UnexpectedError.mapToUnexpectedError,
             Effect.withSpan('@livestore/adapter-web:client-session:devtoolsMessageForLeader'),
           ),
+        networkStatus: Subscribable.make({
+          get: runInWorker(new WorkerSchema.LeaderWorkerInnerGetNetworkStatus()),
+          changes: runInWorkerStream(new WorkerSchema.LeaderWorkerInnerNetworkStatusStream()),
+        }),
       }
 
       const sharedWorker = yield* Fiber.join(sharedWorkerFiber)
@@ -482,10 +551,11 @@ export const makePersistedAdapter =
         lockStatus,
         clientId,
         sessionId,
-        // isLeader: gotLocky, // TODO update when leader is changing
-        isLeader: true,
+        isLeader: gotLocky,
         leaderThread,
         webmeshMode: 'direct',
+        // Can be undefined in Node.js
+        origin: globalThis.location?.origin,
         connectWebmeshNode: ({ sessionInfo, webmeshNode }) =>
           connectWebmeshNodeClientSession({ webmeshNode, sessionInfo, sharedWorker, devtoolsEnabled, schema }),
         registerBeforeUnload: (onBeforeUnload) => {
@@ -499,7 +569,7 @@ export const makePersistedAdapter =
       })
 
       return clientSession
-    }).pipe(UnexpectedError.mapToUnexpectedError)
+    }).pipe(Effect.provide(Opfs.Opfs.Default), UnknownError.mapToUnknownError)
 
 // NOTE for `local` storage we could also use the eventlog db to store the data
 const getPersistedId = (key: string, storageType: 'session' | 'local') => {
@@ -512,7 +582,7 @@ const getPersistedId = (key: string, storageType: 'session' | 'local') => {
         ? sessionStorage
         : storageType === 'local'
           ? localStorage
-          : shouldNeverHappen(`[@livestore/adapter-web] Invalid storage type: ${storageType}`)
+          : shouldNeverHappen(`[@livestore/adapter-web] Invalid storage type: ${String(storageType)}`)
 
   // in case of a worker, we need the id of the parent window, to keep the id consistent
   // we also need to handle the case where there are multiple workers being spawned by the same window
@@ -523,7 +593,7 @@ const getPersistedId = (key: string, storageType: 'session' | 'local') => {
   const fullKey = `livestore:${key}`
   const storedKey = storage.getItem(fullKey)
 
-  if (storedKey) return storedKey
+  if (storedKey !== null) return storedKey
 
   const newKey = makeId()
   storage.setItem(fullKey, newKey)
@@ -534,8 +604,8 @@ const getPersistedId = (key: string, storageType: 'session' | 'local') => {
 const ensureBrowserRequirements = Effect.gen(function* () {
   const validate = (condition: boolean, label: string) =>
     Effect.gen(function* () {
-      if (condition) {
-        return yield* UnexpectedError.make({
+      if (condition === true) {
+        return yield* UnknownError.make({
           cause: `[@livestore/adapter-web] Browser not supported. The LiveStore web adapter needs '${label}' to work properly`,
         })
       }
@@ -550,3 +620,29 @@ const ensureBrowserRequirements = Effect.gen(function* () {
     validate(typeof sessionStorage === 'undefined', 'sessionStorage'),
   ])
 })
+
+/**
+ * Attempts to access OPFS and returns a warning if unavailable.
+ *
+ * Common failure scenarios:
+ * - Safari/Firefox private browsing: SecurityError or NotAllowedError
+ * - Permission denied: NotAllowedError
+ * - Quota exceeded: QuotaExceededError
+ */
+const checkOpfsAvailability = Effect.gen(function* () {
+  const opfs = yield* Opfs.Opfs
+  return yield* opfs.getRootDirectoryHandle.pipe(
+    Effect.as(undefined),
+    Effect.catchAll((error) => {
+      const reason: BootWarningReason =
+        Schema.is(WebError.SecurityError)(error) === true || Schema.is(WebError.NotAllowedError)(error) === true
+          ? 'private-browsing'
+          : 'storage-unavailable'
+      const message =
+        reason === 'private-browsing'
+          ? 'Storage unavailable in private browsing mode. LiveStore will continue without persistence.'
+          : 'Storage access denied. LiveStore will continue without persistence.'
+      return Effect.succeed({ reason, message } as const)
+    }),
+  )
+})

package/src/web-worker/client-session/sqlite-loader.ts

@@ -0,0 +1,19 @@
+import { loadSqlite3Wasm } from '@livestore/sqlite-wasm/load-wasm'
+
+/**
+ * Browser sessions benefit from downloading and compiling the wasm binary as soon as
+ * possible to hide network and IO latency behind the rest of the boot process. We kick
+ * that work off eagerly on the client while still returning the shared promise.
+ *
+ * The Cloudflare / Workerd runtime has stricter rules: async fetches during module
+ * evaluation are blocked, so we defer loading until the worker asks for it.
+ */
+const isServerRuntime = String(import.meta.env?.SSR) === 'true' || typeof window === 'undefined'
+
+let sqlite3Promise: ReturnType<typeof loadSqlite3Wasm> | undefined
+
+if (isServerRuntime === false) {
+  sqlite3Promise = loadSqlite3Wasm()
+}
+
+export const loadSqlite3 = () => (isServerRuntime === true ? loadSqlite3Wasm() : (sqlite3Promise ?? loadSqlite3Wasm()))