@jcbuisson/express-x-plugins 5.0.1 → 5.0.2

package/README.md

@@ -150,6 +150,95 @@ console.log(created.id)
 subscription.unsubscribe()
 ```
 
+### Managed browser sync
+
+With a server configured with `sync: true`, the client plugin can own the shared
+PGlite database and multi-tab synchronization:
+
+```sh
+npm install @electric-sql/pglite @electric-sql/client rxjs vue
+```
+
+```js
+app.configure(electricClientPlugin, {
+  sync: true,
+  databaseName: 'selommes', // persistent IndexedDB name; unique to this app/backend
+  shapePath: '/electric/v1/shape',
+  onError: (error, { modelName }) => console.error(modelName, error),
+})
+
+const ranges = app.createElectricModel('range', { primaryKey: 'uid' })
+const subscription = ranges.getObservable().subscribe(rows => console.log(rows))
+await ranges.create({ label: 'Works offline' })
+await ranges.update(uid, { label: 'Edited offline' })
+await ranges.remove(uid)
+console.log(await ranges.getStatus()) // pending, failed, online, error
+
+// During app teardown (for example, HMR disposal):
+subscription.unsubscribe()
+await app.disposeElectricSync()
+```
+
+Models prepare and start automatically; operations wait for schema readiness.
+Repeated calls for the same model reuse its instance. `findMany` and `findUnique`
+read the local cache immediately after preparation, which can be empty before
+Electric's first snapshot. Use `app.service('user').findMany({ deleted: false, ...filter })`
+when an online authentication flow requires an authoritative server read.
+
+Each plugin instance shares one persistent PGliteWorker. PGlite coordinates its
+database worker across tabs. A separate Web Lock per database/model elects one
+tab to run the Electric stream and mutation queue. Follower writes notify the
+owner through BroadcastChannel. When the owner closes or stops, a waiting tab
+takes over. Stream ownership does not depend on PGlite's leader event timing.
+BIGINT values in cached rows are stored as lossless decimal strings. Snapshot
+reconciliation and reads retry transient database leader changes. An indeterminate
+foreground local mutation is reported instead of blindly repeated.
+
+`model.stop()` stops synchronization and releases ownership without deleting local
+rows or queued edits; `await model.start()` resumes it. `await model.dispose()`
+also closes its channel. `await app.disposeElectricSync()` disposes all managed
+models and closes the plugin-owned database. A supplied `localDb` remains owned
+by the caller. Background errors appear in `getStatus()` and invoke `onError`;
+initialization failures reject reads/writes and error observable subscriptions.
+Worker startup times out after 30 seconds (`initTimeoutMs` can override this).
+
+Managed sync requires HTTPS or localhost, Web Locks, BroadcastChannel, workers,
+and IndexedDB. Configure Vite to keep the plugin and PGlite worker asset URLs
+intact during development and emit workers as ES modules:
+
+```js
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['@jcbuisson/express-x-plugins', '@electric-sql/pglite'],
+  },
+  worker: { format: 'es' },
+})
+```
+
+For other bundlers, provide `workerFactory` if their worker discovery requires
+an application-owned entry point:
+
+```js
+// electric.worker.js
+import '@jcbuisson/express-x-plugins/electric-worker'
+
+// Client configuration:
+app.configure(electricClientPlugin, {
+  sync: true,
+  databaseName: 'selommes',
+  workerFactory: () => new Worker(new URL('./electric.worker.js', import.meta.url), {
+    type: 'module',
+  }),
+})
+```
+
+PWA applications should cache the emitted PGlite `.wasm` and `.data` assets to
+initialize after an offline reload. The WASM asset is about 10 MB; increase the
+precache file-size limit accordingly. Apps that already provide a shared database
+can pass plugin-level `localDb` to retain automatic ownership management.
+
+### Explicit offline models
+
 For offline writes, install `@electric-sql/pglite`, pass a shared PGlite database
 as `localDb`, and use the sync
 server mode above. `PGliteWorker` with an IndexedDB data directory is recommended

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",
@@ -8,7 +8,8 @@
     "./electric-server": "./src/electric-server-plugin.mjs",
     "./electric-client": "./src/electric-client-plugin.mjs",
     "./reload-server": "./src/reload-server-plugin.mjs",
-    "./reload-client": "./src/reload-client-plugin.mjs"
+    "./reload-client": "./src/reload-client-plugin.mjs",
+    "./electric-worker": "./src/electric-pglite-worker.mjs"
   },
   "private": false,
   "publishConfig": {

package/src/electric-client-plugin.mjs

@@ -2,6 +2,7 @@ import { Shape, ShapeStream } from '@electric-sql/client'
 import { Observable, firstValueFrom, Subject, takeUntil } from 'rxjs'
 import { getCurrentScope, onScopeDispose } from 'vue'
 import { createOfflineElectricModel } from './electric-offline-model.mjs'
+import { createManagedSync } from './electric-managed-sync.mjs'
 
 /**
  * Add Electric-backed reactive models to an Express-X client.
@@ -19,8 +20,21 @@ export function electricClientPlugin(app, options = {}) {
    const ShapeClass = options.Shape ?? DisposableShape
    const ObservableClass = options.Observable ?? Observable
 
+   const managed = options.sync === true
+      ? createManagedSync(options, createDirectModel)
+      : null
+
    function createElectricModel(modelName, modelOptions = {}) {
       quoteIdentifier(modelName)
+      quoteIdentifier(modelOptions.primaryKey ?? 'id')
+      if (managed) {
+         if (modelOptions.idGeneration === 'server') throw new TypeError('sync models require client-generated UUIDs')
+         return managed.model(modelName, modelOptions)
+      }
+      return createDirectModel(modelName, modelOptions)
+   }
+
+   function createDirectModel(modelName, modelOptions) {
       const service = app.service(modelName)
       const url = modelOptions.url ?? modelPath(shapePath, modelName)
       if (modelOptions.localDb) return createOfflineElectricModel({
@@ -31,6 +45,8 @@ export function electricClientPlugin(app, options = {}) {
          channel: modelOptions.channel,
          network: modelOptions.network ?? globalThis.navigator,
          retryMs: modelOptions.retryMs ?? 5000,
+         streamOptions: modelOptions.streamOptions,
+         onError: modelOptions.onError ?? options.onError,
       })
       const streamOptions = modelOptions.streamOptions ?? {}
       const idGeneration = modelOptions.idGeneration ?? 'client'
@@ -53,7 +69,7 @@ export function electricClientPlugin(app, options = {}) {
             let previous
             const unsubscribe = shape.subscribe(({ rows }) => {
                const current = [...rows]
-               const serialized = JSON.stringify(current)
+               const serialized = JSON.stringify(current, (_key, value) => typeof value === 'bigint' ? String(value) : value)
                if (serialized === previous) return
                previous = serialized
                subscriber.next(current)
@@ -88,7 +104,7 @@ export function electricClientPlugin(app, options = {}) {
          if (idGeneration === 'server') return service.create(mutationData)
          const uid = globalThis.crypto?.randomUUID?.()
          if (!uid) throw new Error('crypto.randomUUID() is required')
-         return service.create(uid, data)
+         return service.create(uid, mutationData)
       }
 
       async function update(id, data) {
@@ -102,7 +118,7 @@ export function electricClientPlugin(app, options = {}) {
       return { getObservable, findMany, findUnique, create, update, remove }
    }
 
-   return Object.assign(app, { createElectricModel })
+   return Object.assign(app, { createElectricModel, ...(managed ? { disposeElectricSync: managed.dispose } : {}) })
 }
 
 

package/src/electric-managed-sync.mjs

@@ -0,0 +1,150 @@
+import { Observable } from 'rxjs'
+
+/** One database and one cached model per plugin instance. Browser locks span tabs. */
+export function createManagedSync(options, createModel) {
+   const databaseName = options.databaseName
+   if (typeof databaseName !== 'string' || !databaseName.trim()) {
+      throw new TypeError('sync: true requires a non-empty databaseName')
+   }
+   const locks = options.locks ?? globalThis.navigator?.locks
+   const Channel = options.BroadcastChannel ?? globalThis.BroadcastChannel
+   if (!locks?.request || !Channel) throw new Error('Managed sync requires Web Locks and BroadcastChannel (use HTTPS or localhost)')
+   let database
+   let preparation = Promise.resolve()
+   let closed = false
+   const models = new Map()
+
+   function getDatabase() {
+      database ??= Promise.resolve().then(async () => {
+         if (options.localDb) return options.localDb
+         if (options.createDatabase) return options.createDatabase({ dataDir: `idb://${databaseName}` })
+         const { PGliteWorker } = await import('@electric-sql/pglite/worker')
+         const worker = options.workerFactory
+            ? options.workerFactory()
+            : new Worker(new URL('./electric-pglite-worker.mjs', import.meta.url), { type: 'module' })
+         let timer
+         let rejectFailure
+         const failure = new Promise((_, reject) => { rejectFailure = reject })
+         const fail = event => rejectFailure(new Error(event.message ?? 'PGlite worker failed to initialize'))
+         worker.addEventListener('error', fail)
+         worker.addEventListener('messageerror', fail)
+         timer = setTimeout(() => rejectFailure(new Error('PGlite worker initialization timed out')), options.initTimeoutMs ?? 30_000)
+         try {
+            return await Promise.race([PGliteWorker.create(worker, { dataDir: `idb://${databaseName}` }), failure])
+         } catch (error) {
+            worker.terminate()
+            throw error
+         } finally {
+            clearTimeout(timer)
+            worker.removeEventListener('error', fail)
+            worker.removeEventListener('messageerror', fail)
+         }
+      })
+      return database
+   }
+
+   function model(name, modelOptions) {
+      if (closed) throw new Error('Electric sync has been disposed')
+      const existing = models.get(name)
+      if (existing) {
+         if (existing.primaryKey !== (modelOptions.primaryKey ?? 'id')) throw new TypeError('A cached sync model cannot change primaryKey')
+         return existing.api
+      }
+      let active = true
+      let disposed = false
+      let controller
+      let release
+      let generation = 0
+      let channel
+      let offline
+      let error = null
+      function report(cause) {
+         error = cause
+         try { (modelOptions.onError ?? options.onError)?.(cause, { modelName: name }) } catch (callbackError) { console.error(callbackError) }
+      }
+      const ready = getDatabase().then(async db => {
+         channel = new Channel(`express-x:${databaseName}:${name}`)
+         offline = createModel(name, { ...modelOptions, localDb: db, channel, ownsSync: false, onError: report })
+         const prepared = preparation.then(() => offline.prepare())
+         preparation = prepared.catch(() => {})
+         await prepared
+         if (disposed) { channel.close(); return offline }
+         if (active) startOwnership()
+         return offline
+      })
+      // Report initialization failure even when the first consumer only subscribes.
+      void ready.catch(report)
+
+      function startOwnership() {
+         if (controller || disposed || !active) return
+         offline.start()
+         controller = new AbortController()
+         const ownerGeneration = ++generation
+         void locks.request(`express-x:${databaseName}:${name}`, { signal: controller.signal }, async () => {
+            if (!active || disposed || generation !== ownerGeneration) return
+            try {
+               offline.setSyncOwner(true)
+               await new Promise(resolve => { release = resolve })
+            } finally {
+               await offline.waitForIdle()
+               if (generation === ownerGeneration) { offline.setSyncOwner(false); release = undefined }
+            }
+         }).catch(cause => { if (cause.name !== 'AbortError') report(cause) })
+      }
+      function stop() {
+         active = false
+         ++generation
+         controller?.abort()
+         controller = undefined
+         release?.()
+         release = undefined
+         offline?.setSyncOwner(false)
+         offline?.stop()
+      }
+      function start() {
+         if (disposed) throw new Error('Electric model has been disposed')
+         active = true
+         return ready.then(() => startOwnership())
+      }
+      function invoke(method, ...args) {
+         if (disposed) return Promise.reject(new Error('Electric model has been disposed'))
+         return ready.then(model => model[method](...args))
+      }
+      const api = {
+         prepare: () => ready.then(() => undefined), start, stop,
+         async dispose() {
+            if (disposed) return
+            disposed = true
+            stop()
+            try { await ready; await offline.waitForIdle() } finally { channel?.close(); models.delete(name) }
+         },
+         getObservable(where = {}) {
+            return new Observable(subscriber => {
+               if (disposed) { subscriber.error(new Error('Electric model has been disposed')); return }
+               let subscription
+               let cancelled = false
+               const fail = cause => subscriber.error(cause)
+               void ready.then(model => {
+                  if (!cancelled) subscription = model.getObservable(where).subscribe(subscriber)
+               }).catch(fail)
+               return () => { cancelled = true; subscription?.unsubscribe() }
+            })
+         },
+         findMany: (where = {}) => invoke('findMany', where),
+         findUnique: (where = {}) => invoke('findUnique', where),
+         create: data => invoke('create', data),
+         update: (id, data) => invoke('update', id, data),
+         remove: id => invoke('remove', id),
+         flushQueue: () => invoke('flushQueue'),
+         getStatus: async () => ({ ...await invoke('getStatus'), error: error?.message ?? null }),
+      }
+      models.set(name, { api, primaryKey: modelOptions.primaryKey ?? 'id' })
+      return api
+   }
+   async function dispose() {
+      closed = true
+      await Promise.allSettled([...models.values()].map(({ api }) => api.dispose()))
+      if (database && !options.localDb) await (await database).close()
+   }
+   return { model, dispose }
+}

package/src/electric-offline-model.mjs

@@ -1,7 +1,7 @@
 import { Observable } from 'rxjs'
 
 /** Offline model backed by a shared PGlite database (normally PGliteWorker). */
-export function createOfflineElectricModel({ db, service, modelName, url, primaryKey, ShapeStreamClass, ShapeClass, ownsSync, channel, network, retryMs }) {
+export function createOfflineElectricModel({ db, service, modelName, url, primaryKey, ShapeStreamClass, ShapeClass, ownsSync, channel, network, retryMs, streamOptions = {}, onError }) {
    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(primaryKey)) throw new TypeError('primaryKey must be a simple SQL identifier')
    let snapshot = null
    let operation = Promise.resolve()
@@ -10,10 +10,22 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
    let connected = false
    let timer
    let stream
+   let streamGeneration = 0
+   let lastError = null
+   const pendingBackground = new Set()
+   function report(error) {
+      lastError = error?.message ?? String(error)
+      try { onError?.(error, { modelName }) } catch (callbackError) { console.error(callbackError) }
+      notify()
+   }
+   function background(promise) {
+      pendingBackground.add(promise)
+      void promise.catch(report).finally(() => pendingBackground.delete(promise))
+   }
    const listeners = new Set()
 
    async function prepare() {
-      await db.exec(`
+      await retryLeader(() => db.exec(`
          CREATE SEQUENCE IF NOT EXISTS electric_mutation_revision_seq;
          CREATE TABLE IF NOT EXISTS electric_sync_client (
             singleton BOOLEAN PRIMARY KEY DEFAULT true CHECK (singleton),
@@ -33,11 +45,11 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
             failure_reason TEXT,
             PRIMARY KEY (model_name, row_id)
          );
-      `)
+      `))
    }
 
    function notify() {
-      channel?.postMessage({ modelName })
+      channel?.postMessage({ modelName, ...(ownsSync ? { online: connected && network?.onLine !== false } : {}) })
       for (const listener of listeners) queueMicrotask(() => { try { listener() } catch (error) { console.error(error) } })
    }
 
@@ -47,7 +59,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
    }
 
    async function findMany(where = {}) {
-      const { rows } = await db.query('SELECT data FROM electric_local_rows WHERE model_name = $1 ORDER BY row_id', [modelName])
+      const { rows } = await retryLeader(() => db.query('SELECT data FROM electric_local_rows WHERE model_name = $1 ORDER BY row_id', [modelName]))
       return rows.map(row => row.data).filter(row => matchesWhere(row, where))
    }
 
@@ -73,11 +85,11 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
       assertId(id)
       const row = { ...data, [primaryKey]: id }
       await db.transaction(async tx => {
-         await tx.query('INSERT INTO electric_local_rows (model_name, row_id, data) VALUES ($1, $2, $3::jsonb)', [modelName, String(id), JSON.stringify(row)])
+         await tx.query('INSERT INTO electric_local_rows (model_name, row_id, data) VALUES ($1, $2, $3::jsonb)', [modelName, String(id), json(row)])
          await queueMutation(tx, id, 'create', row)
       })
       notify()
-      if (started) void flushQueue()
+      if (started) background(flushQueue())
       return row
    }
 
@@ -90,14 +102,14 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
          const current = await tx.query('SELECT data FROM electric_local_rows WHERE model_name = $1 AND row_id = $2', [modelName, String(id)])
          if (!current.rows[0]) throw new Error('row not found')
          row = { ...current.rows[0].data, ...data }
-         await tx.query('UPDATE electric_local_rows SET data = $3::jsonb WHERE model_name = $1 AND row_id = $2', [modelName, String(id), JSON.stringify(row)])
+         await tx.query('UPDATE electric_local_rows SET data = $3::jsonb WHERE model_name = $1 AND row_id = $2', [modelName, String(id), json(row)])
          const queued = await tx.query('SELECT action, acknowledged_version FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2', [modelName, String(id)])
          if (queued.rows[0]?.action === 'delete') throw new Error('row has a pending delete')
          const action = queued.rows[0]?.action === 'create' && queued.rows[0].acknowledged_version == null ? 'create' : 'update'
          await queueMutation(tx, id, action, row)
       })
       notify()
-      if (started) void flushQueue()
+      if (started) background(flushQueue())
       return row
    }
 
@@ -108,7 +120,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
          await queueMutation(tx, id, 'delete', null)
       })
       notify()
-      if (started) void flushQueue()
+      if (started) background(flushQueue())
    }
 
    async function queueMutation(tx, id, action, data) {
@@ -118,7 +130,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
             action = EXCLUDED.action, data = EXCLUDED.data,
             revision = nextval('electric_mutation_revision_seq'),
             acknowledged_version = NULL, status = 'pending', failure_reason = NULL`,
-      [modelName, String(id), action, data == null ? null : JSON.stringify(data)])
+      [modelName, String(id), action, data == null ? null : json(data)])
    }
 
    function ordered(task) {
@@ -145,7 +157,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
    }
 
    async function reconcileSnapshot(rows) {
-      await db.transaction(async tx => {
+      await retryLeader(() => db.transaction(async tx => {
          for (const row of rows) {
             const id = String(row[primaryKey])
             if (row.version != null) {
@@ -158,7 +170,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
                SELECT $1, $2, $3::jsonb WHERE NOT EXISTS
                   (SELECT 1 FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2)
                ON CONFLICT (model_name, row_id) DO UPDATE SET data = EXCLUDED.data`,
-            [modelName, id, JSON.stringify(row)])
+            [modelName, id, json(row)])
          }
          const activeIds = rows.filter(row => !row.deleted).map(row => String(row[primaryKey]))
          await tx.query(`DELETE FROM electric_local_rows AS local
@@ -166,7 +178,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
               AND NOT EXISTS (SELECT 1 FROM electric_mutation_queue AS pending
                  WHERE pending.model_name = local.model_name AND pending.row_id = local.row_id)`,
          [modelName, activeIds])
-      })
+      }))
       notify()
    }
 
@@ -174,15 +186,17 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
       if (!ownsSync || flushing || network?.onLine === false) return
       flushing = true
       try {
-         while (true) {
-            const { rows } = await db.query(`SELECT * FROM electric_mutation_queue
+         while (ownsSync) {
+            const { rows } = await retryLeader(() => db.query(`SELECT * FROM electric_mutation_queue
                WHERE model_name = $1 AND status = 'pending' AND acknowledged_version IS NULL
-               ORDER BY revision LIMIT 1`, [modelName])
+               ORDER BY revision LIMIT 1`, [modelName]))
             const mutation = rows[0]
             if (!mutation) break
             try {
                await sendMutation(mutation)
+               lastError = null
             } catch (error) {
+               report(error)
                if (!isPermanent(error)) break
                await db.query(`UPDATE electric_mutation_queue SET status = 'failed', failure_reason = $3
                   WHERE model_name = $1 AND row_id = $2 AND revision = $4`,
@@ -196,7 +210,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
    }
 
    async function sendMutation(mutation) {
-      const client = await db.query('SELECT id FROM electric_sync_client WHERE singleton = true')
+      const client = await retryLeader(() => db.query('SELECT id FROM electric_sync_client WHERE singleton = true'))
       const metadata = { clientId: client.rows[0].id, revision: String(mutation.revision) }
       const { row_id: id, data, action } = mutation
       const result = action === 'create'
@@ -205,7 +219,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
             ? await service.update(id, withoutKey(data), metadata)
             : await service.delete(id, metadata)
       if (result?.version == null) throw new Error('sync mutation did not return a version')
-      await db.transaction(async tx => {
+      await retryLeader(() => db.transaction(async tx => {
          const current = await tx.query('SELECT action, revision, data FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2', [modelName, id])
          const queued = current.rows[0]
          if (!queued) return
@@ -217,7 +231,7 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
             await tx.query(`UPDATE electric_mutation_queue SET action = 'update',
                revision = nextval('electric_mutation_revision_seq') WHERE model_name = $1 AND row_id = $2`, [modelName, id])
          }
-      })
+      }))
       await reconcile()
       notify()
    }
@@ -235,45 +249,64 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
       started = true
       channel?.addEventListener('message', sharedChange)
       globalThis.addEventListener?.('online', online)
-      if (!ownsSync) return
-      stream = new ShapeStreamClass({ url })
+      if (!ownsSync) { channel?.postMessage({ modelName, requestStatus: true }); return }
+      const generation = ++streamGeneration
+      stream = new ShapeStreamClass({ ...streamOptions, url })
       stream.subscribe(messages => {
-         if (messages.some(message => message.headers?.control === 'must-refetch')) void resetSnapshot()
+         if (generation !== streamGeneration) return
+         if (messages.some(message => message.headers?.control === 'must-refetch')) background(resetSnapshot())
          connected = stream.isConnected?.() ?? true
          notify()
-      }, () => { connected = false; notify() })
+      }, error => { if (generation !== streamGeneration) return; connected = false; report(error) })
       const shape = new ShapeClass(stream)
-      shape.subscribe(({ rows }) => { connected = true; void applySnapshot([...rows]) })
-      timer = setInterval(() => { void flushQueue() }, retryMs)
-      void flushQueue()
+      shape.subscribe(({ rows }) => { if (generation !== streamGeneration) return; connected = true; background(applySnapshot([...rows])) })
+      timer = setInterval(() => { background(flushQueue()) }, retryMs)
+      background(flushQueue())
+   }
+
+   function setSyncOwner(value) {
+      if (ownsSync === value) return
+      const restart = started
+      stop()
+      ownsSync = value
+      if (restart) start()
+   }
+
+   async function waitForIdle() {
+      while (pendingBackground.size) await Promise.allSettled([...pendingBackground])
+      await operation
    }
 
    function stop() {
       if (!started) return
       started = false
+      ++streamGeneration
       clearInterval(timer)
       stream?.unsubscribeAll()
       channel?.removeEventListener('message', sharedChange)
       globalThis.removeEventListener?.('online', online)
       connected = false
+      notify()
    }
 
-   function online() { void flushQueue() }
+   function online() { background(flushQueue()) }
    function sharedChange(event) {
       if (event.data?.modelName !== modelName) return
+      if (!ownsSync && typeof event.data.online === 'boolean') connected = event.data.online
+      if (ownsSync && event.data.requestStatus) notify()
       for (const listener of listeners) queueMicrotask(() => { try { listener() } catch (error) { console.error(error) } })
-      if (ownsSync) void flushQueue()
+      if (ownsSync) background(flushQueue())
    }
 
    async function getStatus() {
-      const { rows } = await db.query(`SELECT
+      const { rows } = await retryLeader(() => db.query(`SELECT
          count(*) FILTER (WHERE status = 'pending')::int AS pending,
          count(*) FILTER (WHERE status = 'failed')::int AS failed
-         FROM electric_mutation_queue WHERE model_name = $1`, [modelName])
-      return { ...rows[0], online: network?.onLine !== false && connected }
+         FROM electric_mutation_queue WHERE model_name = $1`, [modelName]))
+      return { ...rows[0], online: network?.onLine !== false && connected, ...(lastError ? { error: lastError } : {}) }
    }
 
-   return { prepare, start, stop, subscribe, findMany, findUnique, getObservable,
+   return { prepare, start, stop, setSyncOwner, waitForIdle, subscribe, findMany, findUnique, getObservable,
       create, update, remove, flushQueue, getStatus }
 }
 
@@ -309,3 +342,19 @@ function isPermanent(error) {
    return error?.code === 'forbidden' || error instanceof TypeError ||
       status >= 400 && status < 500 && ![408, 425, 429].includes(status)
 }
+
+function json(value) {
+   return JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? String(item) : item)
+}
+
+// Snapshots and reads are safe to repeat if PGlite's worker changes mid-request.
+// Foreground local mutation transactions may have committed; callers see their error.
+async function retryLeader(action) {
+   for (let attempt = 0; ; attempt++) {
+      try { return await action() } catch (error) {
+         if (!(error?.name === 'LeaderChangedError' || error?.constructor?.name === 'LeaderChangedError' ||
+            error?.message === 'Leader changed, pending operation in indeterminate state') || attempt >= 7) throw error
+         await new Promise(resolve => setTimeout(resolve, Math.min(25 * 2 ** attempt, 250)))
+      }
+   }
+}

package/src/electric-pglite-worker.mjs

@@ -0,0 +1,4 @@
+import { PGlite } from '@electric-sql/pglite'
+import { worker } from '@electric-sql/pglite/worker'
+
+await worker({ init: options => PGlite.create(options) })

package/test/electric-client-plugin.test.mjs

@@ -142,6 +142,7 @@ test('model mutations retain the simple Express-X API', async () => {
    await todo.update(created.uid, { completed: true })
    await todo.remove(created.uid)
    assert.deepEqual(calls.map(call => call[0]), ['create', 'update', 'remove'])
+   assert.deepEqual(calls[0][2], { title: 'Test' })
 })
 
 test('model creation supports server-generated IDs', async () => {

package/test/electric-managed-sync.test.mjs

@@ -0,0 +1,254 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { PGlite } from '@electric-sql/pglite'
+import { electricClientPlugin } from '../src/electric-client-plugin.mjs'
+
+class Locks {
+   queues = new Map()
+   request(name, { signal }, callback) {
+      return new Promise((resolve, reject) => {
+         const queue = this.queues.get(name) ?? []
+         this.queues.set(name, queue)
+         const job = { callback, resolve, reject, active: false }
+         signal.addEventListener('abort', () => {
+            if (job.active) return
+            const index = queue.indexOf(job)
+            if (index !== -1) queue.splice(index, 1)
+            reject(Object.assign(new Error('aborted'), { name: 'AbortError' }))
+         }, { once: true })
+         queue.push(job)
+         if (queue.length === 1) this.run(name)
+      })
+   }
+   run(name) {
+      const queue = this.queues.get(name)
+      const job = queue[0]
+      if (!job) return
+      job.active = true
+      Promise.resolve().then(job.callback).then(job.resolve, job.reject).finally(() => {
+         queue.shift()
+         this.run(name)
+      })
+   }
+}
+class Channel extends EventTarget {
+   static instances = new Set()
+   constructor(name) { super(); this.name = name; Channel.instances.add(this) }
+   postMessage(data) {
+      for (const channel of Channel.instances) {
+         if (channel !== this && channel.name === this.name) channel.dispatchEvent(new MessageEvent('message', { data }))
+      }
+   }
+   close() { Channel.instances.delete(this) }
+}
+class Stream {
+   static instances = []
+   constructor(options) { this.options = options; Stream.instances.push(this) }
+   subscribe() { return () => {} }
+   isConnected() { return true }
+   unsubscribeAll() { this.stopped = true }
+}
+class Shape {
+   constructor(stream) { stream.shape = this }
+   subscribe(callback) { this.emit = callback; return () => {} }
+}
+async function until(predicate) {
+   for (let i = 0; i < 100; i++) {
+      if (await predicate()) return
+      await new Promise(resolve => setTimeout(resolve, 5))
+   }
+   assert.fail('condition did not become true')
+}
+function configure(db, locks, service = {}, extra = {}) {
+   const app = { service: () => service }
+   electricClientPlugin(app, {
+      sync: true, databaseName: 'test-db', localDb: db, locks,
+      BroadcastChannel: Channel, ShapeStream: Stream, Shape, ...extra,
+   })
+   return app
+}
+
+test('managed models initialize automatically, share one database, and cache models', async () => {
+   const db = new PGlite()
+   let created = 0
+   const locks = new Locks()
+   const app = configure(undefined, locks, {}, { createDatabase: async ({ dataDir }) => {
+      assert.equal(dataDir, 'idb://test-db'); created++; return db
+   } })
+   try {
+      const users = app.createElectricModel('users', { primaryKey: 'uid' })
+      const ranges = app.createElectricModel('ranges', { primaryKey: 'uid' })
+      assert.equal(app.createElectricModel('users', { primaryKey: 'uid' }), users)
+      assert.throws(() => app.createElectricModel('users'), /primaryKey/)
+      const row = await users.create({ name: 'Works before prepare' })
+      await ranges.prepare()
+      assert.equal(created, 1)
+      assert.equal((await users.findUnique({ uid: row.uid })).name, row.name)
+   } finally {
+      await app.disposeElectricSync()
+   }
+   assert.equal(db.closed, true)
+})
+
+test('only one tab streams and flushes; follower edits broadcast and ownership transfers', async () => {
+   const db = new PGlite()
+   const locks = new Locks()
+   const calls = []
+   const service = { async create(id, data) { calls.push(id); return { id, ...data, version: '42' } } }
+   const first = configure(db, locks, service)
+   const second = configure(db, locks, service)
+   const before = Stream.instances.length
+   let subscription
+   try {
+      const owner = first.createElectricModel('todos')
+      const follower = second.createElectricModel('todos')
+      await owner.prepare()
+      await follower.prepare()
+      await until(() => Stream.instances.length === before + 1)
+      let observed = []
+      subscription = owner.getObservable().subscribe(rows => { observed = rows })
+      const row = await follower.create({ title: 'Written in follower' })
+      await until(() => calls.length === 1 && observed.length === 1)
+      assert.equal(observed[0].id, row.id)
+      assert.equal(Stream.instances.length, before + 1)
+      const stream = Stream.instances.at(-1)
+      stream.shape.emit({ rows: [{ ...row, version: 42n, deleted: false }] })
+      await until(async () => (await follower.getStatus()).pending === 0)
+      assert.equal((await follower.findMany())[0].version, '42')
+      await owner.dispose()
+      await until(() => Stream.instances.length === before + 2)
+      assert.equal(stream.stopped, true)
+      const next = Stream.instances.at(-1)
+      next.shape.emit({ rows: [{ ...row, version: 42n, deleted: false }] })
+      await until(async () => (await follower.findMany()).length === 1)
+      assert.equal(calls.length, 1)
+   } finally {
+      subscription?.unsubscribe()
+      await first.disposeElectricSync()
+      await second.disposeElectricSync()
+      await db.close()
+   }
+})
+
+test('stopping a waiting follower cancels takeover; restart can acquire ownership', async () => {
+   const db = new PGlite()
+   const locks = new Locks()
+   const first = configure(db, locks)
+   const second = configure(db, locks)
+   const before = Stream.instances.length
+   try {
+      const owner = first.createElectricModel('todos')
+      const follower = second.createElectricModel('todos')
+      await owner.prepare(); await follower.prepare()
+      await until(() => Stream.instances.length === before + 1)
+      follower.stop()
+      owner.stop()
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal(Stream.instances.length, before + 1)
+      await follower.start()
+      await until(() => Stream.instances.length === before + 2)
+   } finally {
+      await first.disposeElectricSync(); await second.disposeElectricSync(); await db.close()
+   }
+})
+
+test('initialization errors reject writes and observable reads and call onError', async () => {
+   const error = new Error('Worker could not load assets')
+   const reported = []
+   const app = configure(undefined, new Locks(), {}, {
+      createDatabase: async () => { throw error },
+      onError: cause => reported.push(cause),
+   })
+   const model = app.createElectricModel('todos')
+   await assert.rejects(model.create({ title: 'No silent failure' }), /load assets/)
+   await new Promise(resolve => model.getObservable().subscribe({ error: cause => {
+      assert.equal(cause, error); resolve()
+   } }))
+   assert.deepEqual(reported, [error])
+   await assert.rejects(app.disposeElectricSync(), /load assets/)
+})
+
+test('sync mode validates browser capabilities and persistent database identity', () => {
+   const app = { service: () => ({}) }
+   assert.throws(() => electricClientPlugin(app, { sync: true }), /databaseName/)
+   assert.throws(() => electricClientPlugin(app, { sync: true, databaseName: 'todos', locks: {} }), /Web Locks/)
+})
+
+test('default worker errors and timeouts reject preparation instead of hanging', async () => {
+   for (const triggerError of [true, false]) {
+      let terminated = false
+      class Worker extends EventTarget {
+         constructor() {
+            super()
+            if (triggerError) setTimeout(() => {
+               const event = new Event('error')
+               event.message = 'worker module not found'
+               this.dispatchEvent(event)
+            }, 10)
+         }
+         terminate() { terminated = true }
+      }
+      const app = configure(undefined, new Locks(), {}, { workerFactory: () => new Worker(), initTimeoutMs: 30 })
+      const model = app.createElectricModel('todos')
+      await assert.rejects(model.prepare(), triggerError ? /module not found/ : /timed out/)
+      assert.equal(terminated, true)
+      await assert.rejects(app.disposeElectricSync())
+   }
+})
+
+test('snapshots and reads recover after a database leader changes', async () => {
+   const db = new PGlite()
+   let failSnapshot = false
+   let failRead = false
+   let snapshotRetries = 0
+   const leaderError = () => Object.assign(new Error('Leader changed, pending operation in indeterminate state'), { name: 'LeaderChangedError' })
+   const shared = {
+      exec: db.exec.bind(db),
+      async query(...args) {
+         if (failRead) { failRead = false; throw leaderError() }
+         return db.query(...args)
+      },
+      async transaction(callback) {
+         if (failSnapshot) { failSnapshot = false; snapshotRetries++; throw leaderError() }
+         return db.transaction(callback)
+      },
+   }
+   const app = configure(shared, new Locks())
+   const before = Stream.instances.length
+   try {
+      const model = app.createElectricModel('todos')
+      await model.prepare()
+      await until(() => Stream.instances.length === before + 1)
+      failSnapshot = true
+      const id = crypto.randomUUID()
+      Stream.instances.at(-1).shape.emit({ rows: [{ id, title: 'After election', version: 99n, deleted: false }] })
+      await until(async () => (await model.findMany()).length === 1)
+      assert.equal(snapshotRetries, 1)
+      failRead = true
+      assert.equal((await model.findUnique({ id })).version, '99')
+      assert.equal((await model.getStatus()).error, null)
+   } finally { await app.disposeElectricSync(); await db.close() }
+})
+
+test('an indeterminate foreground mutation is not replayed automatically', async () => {
+   const db = new PGlite()
+   let writes = 0
+   const app = { service: () => ({}) }
+   const localDb = {
+      exec: db.exec.bind(db), query: db.query.bind(db),
+      async transaction(callback) {
+         writes++
+         await db.transaction(callback)
+         throw Object.assign(new Error('Leader changed, pending operation in indeterminate state'), { name: 'LeaderChangedError' })
+      },
+   }
+   electricClientPlugin(app)
+   const model = app.createElectricModel('todos', { localDb, ownsSync: false })
+   try {
+      await model.prepare()
+      await assert.rejects(model.create({ title: 'Committed but reply lost' }), /Leader changed/)
+      assert.equal(writes, 1)
+      assert.equal((await model.findMany()).length, 1)
+      assert.equal((await model.getStatus()).pending, 1)
+   } finally { await db.close() }
+})