@freecorps/ember-offline 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @freecorps/ember-offline
 
-Offline-first storage for Ember clients: persisted query results, replicated rows and local query execution over IndexedDB, SQLite or expo-sqlite.
+Offline-first storage for Ember clients: persisted query results, replicated rows and reactive local query execution over IndexedDB, SQLite (expo-sqlite, SQLite-Wasm on OPFS) or TinyBase, coordinated across tabs.
 
 Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
 Objects. Source: [`packages/offline`](https://github.com/freecorps/ember/tree/main/packages/offline).

package/dist/backend.d.ts

@@ -1,5 +1,6 @@
 import type { PendingMutationRecord } from "@freecorps/ember-client";
 import type { Doc, LocalReader } from "@freecorps/ember-server";
+import type { RowDiff } from "@freecorps/ember-values";
 /** The last server value of one subscribed query, and the replicated rows it owns. */
 export interface QueryRecord {
     /** `${shard}\u0000${fn}\u0000${argsJson}` */
@@ -8,18 +9,45 @@ export interface QueryRecord {
     fn: string;
     args: Record<string, unknown>;
     argsJson: string;
+    /**
+     * The value (the base of the log when entries follow). With `refs`, the replicated documents in it are stored
+     * as row references `{ _id, $row: 1 }` and read back from the replicated rows.
+     */
     value: unknown;
     version: number;
+    /** The shard epoch of `version` (absent in records written before it, or when the client did not know it). */
+    epoch?: string;
     /** ms; refreshed on every server value (retention / eviction). */
     updatedAt: number;
     /** `_id`s of the complete documents in `value` (rows owned by this record). */
     ids: string[];
+    /** `value` holds row references (format 2). Absent in records written before it. */
+    refs?: true;
+    /** Encoded size of `value` (bounds the log: entries never outgrow the base). */
+    size?: number;
 }
-/** One atomic write to a shard: query records and the rows they own. */
+/**
+ * One appended change of a record: the row diff from the previous stored value (references stay references), the
+ * new version, and the owned ids that came and went. Replayed over `QueryRecord.value` on open, in `seq` order;
+ * a `put` of the record (compaction) removes its entries.
+ */
+export interface QueryLogEntry {
+    key: string;
+    seq: number;
+    diff: RowDiff;
+    version: number;
+    epoch?: string;
+    updatedAt: number;
+    add: string[];
+    remove: string[];
+}
+/** One atomic write to a shard: query records, their log, and the rows they own. */
 export interface Commit {
+    /** Records written whole (their log entries are removed). */
     put?: QueryRecord[];
-    /** Record keys to remove. */
+    /** Record keys to remove (with their log). */
     drop?: string[];
+    append?: QueryLogEntry[];
     upsert?: Array<{
         table: string;
         doc: Doc;
@@ -37,11 +65,17 @@ export interface BackendReader extends LocalReader {
     readonly misses?: number;
     fetch?(): Promise<void>;
 }
+/** Rows a backend saw change outside `commit` (another writer of a shared store): tables per shard. */
+export type ExternalChange = {
+    shard: string;
+    tables: string[];
+};
 export interface OfflineBackend {
     /** Open / migrate (a schema change the planner refuses resets the replica; pending survives). */
     open(): Promise<{
         meta: Record<string, string>;
         queries: QueryRecord[];
+        log?: QueryLogEntry[];
     }>;
     setMeta(key: string, value: string | null): Promise<void> | void;
     loadPending(): Promise<PendingMutationRecord[]> | PendingMutationRecord[];
@@ -49,6 +83,8 @@ export interface OfflineBackend {
     removePending(mid: string): Promise<void> | void;
     commit(shard: string, c: Commit): Promise<void> | void;
     reader(shard: string): BackendReader;
+    /** Optional: report row changes made by someone else (e.g. the app writing to a shared TinyBase store). */
+    onExternalChange?(listener: (c: ExternalChange) => void): () => void;
     close(): Promise<void> | void;
 }
 /** Thrown by async readers on a miss (see `BackendReader`). */

package/dist/backend.js

@@ -1,7 +1,7 @@
-// The storage seam under the generic offline store (store.ts). A backend persists four things — metadata, the
-// pending mutation queue, query records, and replicated rows per shard — and serves synchronous reads of one
-// shard's rows to `runLocalQuery`. Backends: memory (memory.ts), SQLite (sqlite.ts, expo-sqlite.ts), IndexedDB
-// (indexeddb.ts).
+// The storage seam under the generic offline store (store.ts). A backend persists five things — metadata, the
+// pending mutation queue, query records, their diff logs, and replicated rows per shard — and serves synchronous
+// reads of one shard's rows to `runLocalQuery`. Backends: memory (memory.ts), SQLite (sqlite.ts, expo-sqlite.ts,
+// sqlite-wasm.ts / opfs), IndexedDB (indexeddb.ts), TinyBase (tinybase.ts).
 /** Thrown by async readers on a miss (see `BackendReader`). */
 export class NeedData extends Error {
     constructor() {

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 /**
  * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
  *
+ *   import { opfsStorage } from "@freecorps/ember-offline/opfs";                // browsers: SQLite-Wasm on OPFS (Worker:
+ *                                                                               //   serveOpfsStorage from "/opfs-worker")
  *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
  *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { tinybaseStorage } from "@freecorps/ember-offline/tinybase";        // the replica in a TinyBase Store
  *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *   import { sqliteWasmStorage } from "@freecorps/ember-offline/sqlite-wasm";   // any SQLite-Wasm oo1 database
+ *   import { coordinateTabs } from "@freecorps/ember-offline";                  // several tabs, one storage
  *
  *   new EmberClient({
  *     url,
@@ -14,7 +19,9 @@
  * Contract and limits: docs/design/contracts.md, "Offline".
  */
 export { createOfflineStorage, OfflineStore, type OfflineOptions } from "./store.ts";
-export { NeedData, recordKey, type BackendReader, type Commit, type OfflineBackend, type QueryRecord } from "./backend.ts";
+export { NeedData, recordKey, type BackendReader, type Commit, type ExternalChange, type OfflineBackend, type QueryLogEntry, type QueryRecord, } from "./backend.ts";
 export { MemoryBackend, memoryStorage } from "./memory.ts";
+export { coordinateTabs, TabCoordinator, type LockManagerLike, type TabRole, type TabsOptions } from "./tabs.ts";
+export { RemoteStorage, serveStorage, type Endpoint, type ServableStorage, type Served, type ServeOptions } from "./remote.ts";
 export type { LocalSchema } from "@freecorps/ember-server";
 export type { StorageAdapter, SyncSpec, LocalQueryResult, QueryUpdate } from "@freecorps/ember-client";

package/dist/index.js

@@ -1,9 +1,14 @@
 /**
  * `@freecorps/ember-offline`: optional offline-first storage for `@freecorps/ember-client` (PLAN §10).
  *
+ *   import { opfsStorage } from "@freecorps/ember-offline/opfs";                // browsers: SQLite-Wasm on OPFS (Worker:
+ *                                                                               //   serveOpfsStorage from "/opfs-worker")
  *   import { indexedDbStorage } from "@freecorps/ember-offline/indexeddb";      // browsers
  *   import { expoSqliteStorage } from "@freecorps/ember-offline/expo-sqlite";   // React Native / Expo
+ *   import { tinybaseStorage } from "@freecorps/ember-offline/tinybase";        // the replica in a TinyBase Store
  *   import { sqliteStorage } from "@freecorps/ember-offline/sqlite";            // any synchronous SqlDriver
+ *   import { sqliteWasmStorage } from "@freecorps/ember-offline/sqlite-wasm";   // any SQLite-Wasm oo1 database
+ *   import { coordinateTabs } from "@freecorps/ember-offline";                  // several tabs, one storage
  *
  *   new EmberClient({
  *     url,
@@ -14,5 +19,7 @@
  * Contract and limits: docs/design/contracts.md, "Offline".
  */
 export { createOfflineStorage, OfflineStore } from "./store.js";
-export { NeedData, recordKey } from "./backend.js";
+export { NeedData, recordKey, } from "./backend.js";
 export { MemoryBackend, memoryStorage } from "./memory.js";
+export { coordinateTabs, TabCoordinator } from "./tabs.js";
+export { RemoteStorage, serveStorage } from "./remote.js";

package/dist/indexeddb.d.ts

@@ -1,6 +1,6 @@
 import type { PendingMutationRecord } from "@freecorps/ember-client";
 import { type LocalSchema } from "@freecorps/ember-server";
-import { type BackendReader, type Commit, type OfflineBackend, type QueryRecord } from "./backend.ts";
+import { type BackendReader, type Commit, type OfflineBackend, type QueryLogEntry, type QueryRecord } from "./backend.ts";
 import { type OfflineOptions, type OfflineStore } from "./store.ts";
 export interface IndexedDbStorageOptions extends OfflineOptions {
     /** Database name. Default `"ember"`. */
@@ -23,6 +23,7 @@ export declare class IndexedDbBackend implements OfflineBackend {
     open(): Promise<{
         meta: Record<string, string>;
         queries: QueryRecord[];
+        log: QueryLogEntry[];
     }>;
     setMeta(key: string, value: string | null): Promise<void>;
     loadPending(): Promise<PendingMutationRecord[]>;

package/dist/indexeddb.js

@@ -18,6 +18,7 @@ import { createOfflineStorage } from "./store.js";
 const META = "meta";
 const PENDING = "pending";
 const QUERIES = "queries";
+const LOG = "log";
 const tableStore = (table) => `t:${table}`;
 const keyProp = (index) => `_k_${index}`;
 const buf = (u) => u.slice().buffer;
@@ -65,11 +66,14 @@ export class IndexedDbBackend {
                     db.createObjectStore(PENDING, { autoIncrement: true }).createIndex("mid", "mid", { unique: true });
                 if (!db.objectStoreNames.contains(QUERIES))
                     db.createObjectStore(QUERIES, { keyPath: "key" });
+                if (!db.objectStoreNames.contains(LOG))
+                    db.createObjectStore(LOG, { keyPath: ["key", "seq"] });
                 if (ev.oldVersion === 0 || reset) {
                     for (const n of Array.from(db.objectStoreNames))
                         if (n.startsWith("t:"))
                             db.deleteObjectStore(n);
                     tx.objectStore(QUERIES).clear();
+                    tx.objectStore(LOG).clear();
                     for (const [table, t] of Object.entries(this.schema.manifest.tables)) {
                         const s = db.createObjectStore(tableStore(table), { keyPath: ["s", "id"] });
                         for (const i of dbIndexesOf(t))
@@ -90,25 +94,27 @@ export class IndexedDbBackend {
     async open() {
         let db = await this.openDb();
         const stored = await req(db.transaction(META).objectStore(META).get("schema"));
-        if (stored !== this.schema.manifest.version) {
+        if (stored !== this.schema.manifest.version || !db.objectStoreNames.contains(LOG)) {
+            // A new schema resets the replica; a database from before the log only gains the store.
             const v = db.version + 1;
             db.close();
-            db = await this.openDb(v, true);
+            db = await this.openDb(v, stored !== this.schema.manifest.version);
         }
         this.db = db;
-        const tx = db.transaction([META, QUERIES]);
+        const tx = db.transaction([META, QUERIES, LOG]);
         const metaStore = tx.objectStore(META);
-        const [keys, values, queries] = await Promise.all([
+        const [keys, values, queries, log] = await Promise.all([
             req(metaStore.getAllKeys()),
             req(metaStore.getAll()),
             req(tx.objectStore(QUERIES).getAll()),
+            req(tx.objectStore(LOG).getAll()),
         ]);
         const meta = {};
         keys.forEach((k, i) => {
             if (typeof k === "string" && k !== "schema" && typeof values[i] === "string")
                 meta[k] = values[i];
         });
-        return { meta, queries };
+        return { meta, queries, log };
     }
     async setMeta(key, value) {
         const tx = this.conn.transaction(META, "readwrite");
@@ -145,12 +151,20 @@ export class IndexedDbBackend {
     }
     async commit(shard, c) {
         const tables = new Set([...(c.upsert ?? []), ...(c.delete ?? [])].map((x) => tableStore(x.table)));
-        const tx = this.conn.transaction([QUERIES, ...tables], "readwrite");
+        const tx = this.conn.transaction([QUERIES, LOG, ...tables], "readwrite");
         const q = tx.objectStore(QUERIES);
-        for (const r of c.put ?? [])
+        const log = tx.objectStore(LOG);
+        const entriesOf = (key) => this.Range.bound([key], [key, []]);
+        for (const r of c.put ?? []) {
             q.put(r);
-        for (const k of c.drop ?? [])
+            log.delete(entriesOf(r.key));
+        }
+        for (const k of c.drop ?? []) {
             q.delete(k);
+            log.delete(entriesOf(k));
+        }
+        for (const e of c.append ?? [])
+            log.put(e);
         for (const { table, id } of c.delete ?? [])
             tx.objectStore(tableStore(table)).delete([shard, id]);
         for (const { table, doc } of c.upsert ?? [])

package/dist/memory.d.ts

@@ -1,11 +1,12 @@
 import type { PendingMutationRecord } from "@freecorps/ember-client";
 import { type Doc, type LocalSchema } from "@freecorps/ember-server";
-import type { BackendReader, Commit, OfflineBackend, QueryRecord } from "./backend.ts";
+import type { BackendReader, Commit, OfflineBackend, QueryLogEntry, QueryRecord } from "./backend.ts";
 import { type OfflineOptions, type OfflineStore } from "./store.ts";
 export declare class MemoryBackend implements OfflineBackend {
     readonly meta: Map<string, string>;
     readonly pending: Map<string, PendingMutationRecord>;
     readonly queries: Map<string, QueryRecord>;
+    readonly log: Map<string, QueryLogEntry[]>;
     /** shard → table → id → doc */
     readonly rows: Map<string, Map<string, Map<string, Doc>>>;
     /** Sorted rows per `shard\0table\0index`, rebuilt after writes. */
@@ -19,6 +20,7 @@ export declare class MemoryBackend implements OfflineBackend {
             [k: string]: string;
         };
         queries: QueryRecord[];
+        log: QueryLogEntry[];
     }>;
     setMeta(key: string, value: string | null): void;
     loadPending(): PendingMutationRecord[];

package/dist/memory.js

@@ -7,6 +7,7 @@ export class MemoryBackend {
     meta = new Map();
     pending = new Map();
     queries = new Map();
+    log = new Map();
     /** shard → table → id → doc */
     rows = new Map();
     /** Sorted rows per `shard\0table\0index`, rebuilt after writes. */
@@ -22,10 +23,11 @@ export class MemoryBackend {
         if (this.version !== null && this.version !== v) {
             this.rows.clear();
             this.queries.clear();
+            this.log.clear();
             this.sorted.clear();
         }
         this.version = v;
-        return { meta: Object.fromEntries(this.meta), queries: [...this.queries.values()] };
+        return { meta: Object.fromEntries(this.meta), queries: [...this.queries.values()], log: [...this.log.values()].flat() };
     }
     setMeta(key, value) {
         if (value === null)
@@ -52,10 +54,21 @@ export class MemoryBackend {
         return t;
     }
     commit(shard, c) {
-        for (const r of c.put ?? [])
+        for (const r of c.put ?? []) {
             this.queries.set(r.key, r);
-        for (const k of c.drop ?? [])
+            this.log.delete(r.key);
+        }
+        for (const k of c.drop ?? []) {
             this.queries.delete(k);
+            this.log.delete(k);
+        }
+        // Keyed by (key, seq), like the SQLite (INSERT OR REPLACE) and IndexedDB (put) logs.
+        for (const e of c.append ?? []) {
+            const list = (this.log.get(e.key) ?? []).filter((x) => x.seq !== e.seq);
+            list.push(e);
+            list.sort((a, b) => a.seq - b.seq);
+            this.log.set(e.key, list);
+        }
         for (const { table, doc } of c.upsert ?? [])
             this.table(shard, table).set(doc._id, doc);
         for (const { table, id } of c.delete ?? [])

package/dist/opfs-worker.d.ts

@@ -0,0 +1,52 @@
+import { type Endpoint, type Served } from "./remote.ts";
+import { type WasmSqliteDatabase } from "./sqlite-wasm.ts";
+import type { OfflineOptions, OfflineStore } from "./store.ts";
+import { type LockManagerLike, type TabCoordinator, type TabRole } from "./tabs.ts";
+/** The part of the SQLite-Wasm module (`await sqlite3InitModule()`) used here. */
+export interface Sqlite3Module {
+    installOpfsSAHPoolVfs(opts: {
+        name?: string;
+        directory?: string;
+        initialCapacity?: number;
+        clearOnInit?: boolean;
+    }): Promise<SahPool>;
+}
+/** The part of the `opfs-sahpool` pool utility used here. */
+export interface SahPool {
+    OpfsSAHPoolDb: new (filename: string) => WasmSqliteDatabase;
+    reserveMinimumCapacity(n: number): Promise<number>;
+    pauseVfs(): unknown;
+    unpauseVfs(): Promise<unknown>;
+    isPaused(): boolean;
+}
+export interface OpfsWorkerOptions extends OfflineOptions {
+    /** Storage name (OPFS directory `.ember-<name>`, database prefix, tab lock / channel). Default `"ember"`. */
+    name?: string;
+    /** Loads SQLite-Wasm. Default: `import("@sqlite.org/sqlite-wasm")` and its default init. */
+    sqlite3?: () => Promise<Sqlite3Module>;
+    /**
+     * Files the pool keeps open: two per database (data + journal) — the main database plus one per shard. Default 16
+     * (7 shards). Raise it for apps that use many shards.
+     */
+    capacity?: number;
+    /** Coordinate the tabs that open this storage (default true; needs Web Locks). */
+    multiTab?: boolean;
+    /** Tests: the lock manager / channel (default `navigator.locks`, `BroadcastChannel`). */
+    locks?: LockManagerLike | null;
+    channel?: Endpoint & {
+        close(): void;
+    };
+    /** Where the page is (default: the worker global scope). */
+    scope?: Endpoint;
+    /** This Worker became the leader (owns the files) / a follower / closed. */
+    onRoleChange?(role: TabRole): void;
+}
+/** Opens OPFS storage in this Worker (the leader's job). Call `close()` to release the files (pauses the VFS). */
+export declare function openOpfsStore(options: OpfsWorkerOptions, loaded?: {
+    pool?: SahPool;
+}): Promise<OfflineStore>;
+/** Serves OPFS storage to the page (`opfsStorage`), coordinating with the other tabs' Workers. */
+export declare function serveOpfsStorage(options: OpfsWorkerOptions): {
+    storage: TabCoordinator;
+    served: Served;
+};

package/dist/opfs-worker.js

@@ -0,0 +1,72 @@
+// The Worker half of OPFS storage: SQLite-Wasm (`@sqlite.org/sqlite-wasm`, optional peer) on the Origin Private
+// File System through the `opfs-sahpool` VFS. Sync access handles exist only in dedicated Workers, and the SQL path
+// is synchronous (`SqlDriver`), so the whole offline store runs here — the server's DDL, row codec, SQL compiler and
+// FTS5 search, exactly as `sqliteStorage` — and the page talks to it with `opfsStorage` (opfs.ts) over postMessage.
+// `opfs-sahpool` needs no COOP/COEP headers (no SharedArrayBuffer).
+//
+// Tabs: the pool's files can be held by one Worker at a time, so the Workers of every tab elect a leader with Web
+// Locks (tabs.ts); only the leader installs the VFS and opens the databases, the others forward over a
+// BroadcastChannel. When the leader goes away, the next Worker installs the VFS (retrying while the old handles
+// are released) and takes over.
+//
+//   // ember-offline.worker.ts — bundled as a module worker; imports the same schema and query() definitions
+//   import { serveOpfsStorage } from "@freecorps/ember-offline/opfs-worker";
+//   import schema from "../ember/schema";
+//   import { list, search } from "../ember/messages";
+//   serveOpfsStorage({ name: "chat", schema, queries: { "messages:list": list, "messages:search": search },
+//                      sync: [{ query: "messages:recent", args: { days: 90 } }] });
+import { serveStorage } from "./remote.js";
+import { sqliteWasmStorage } from "./sqlite-wasm.js";
+import { coordinateTabs } from "./tabs.js";
+// Only apps that import this module (OPFS users) make their bundler resolve the optional peer.
+const defaultSqlite3 = async () => {
+    const m = (await import("@sqlite.org/sqlite-wasm"));
+    return await m.default();
+};
+/** Opens OPFS storage in this Worker (the leader's job). Call `close()` to release the files (pauses the VFS). */
+export async function openOpfsStore(options, loaded) {
+    const name = options.name ?? "ember";
+    let pool = loaded?.pool;
+    if (!pool) {
+        const sqlite3 = await (options.sqlite3 ?? defaultSqlite3)();
+        pool = await sqlite3.installOpfsSAHPoolVfs({ name: `ember-${name}`, directory: `.ember-${name}`, initialCapacity: options.capacity ?? 16 });
+        if (loaded)
+            loaded.pool = pool;
+    }
+    else if (pool.isPaused())
+        await pool.unpauseVfs();
+    const p = pool;
+    try {
+        await p.reserveMinimumCapacity(options.capacity ?? 16);
+    }
+    catch (e) {
+        // Do not keep the files while failing: another tab's Worker (or our next attempt) must be able to take them.
+        if (!p.isPaused())
+            p.pauseVfs();
+        throw e;
+    }
+    const store = sqliteWasmStorage({ ...options, name, open: (n) => new p.OpfsSAHPoolDb(`/${n}.db`) });
+    const close = store.close.bind(store);
+    store.close = async () => {
+        await close();
+        // Release the access handles so another tab's Worker can take over.
+        if (!p.isPaused())
+            p.pauseVfs();
+    };
+    return store;
+}
+/** Serves OPFS storage to the page (`opfsStorage`), coordinating with the other tabs' Workers. */
+export function serveOpfsStorage(options) {
+    const name = options.name ?? "ember";
+    const loaded = {};
+    const storage = coordinateTabs({
+        name: `opfs:${name}`,
+        open: () => openOpfsStore(options, loaded),
+        ...(options.multiTab === false ? { locks: null } : options.locks !== undefined ? { locks: options.locks } : {}),
+        ...(options.channel ? { channel: options.channel } : {}),
+        ...(options.onRoleChange ? { onRoleChange: options.onRoleChange } : {}),
+    });
+    const scope = options.scope ?? globalThis;
+    const served = serveStorage(storage, scope);
+    return { storage, served };
+}

package/dist/opfs.d.ts

@@ -0,0 +1,30 @@
+import { RemoteStorage, type Endpoint } from "./remote.ts";
+export interface OpfsStorageOptions {
+    /** The Worker that calls `serveOpfsStorage` (or a factory for it). */
+    worker: (Endpoint & {
+        terminate?(): void;
+    }) | (() => Endpoint & {
+        terminate?(): void;
+    });
+    /** Terminate the Worker on `close()` (default true). */
+    terminate?: boolean;
+    /**
+     * How long `close()` waits for the Worker to close its database (default 5000 ms). A Worker that reported an
+     * error is not waited for at all; one that went silent is given up on after this, then terminated.
+     */
+    closeTimeoutMs?: number;
+}
+export declare class OpfsStorage extends RemoteStorage {
+    private readonly options;
+    private readonly worker;
+    private readonly failed;
+    constructor(options: OpfsStorageOptions);
+    private terminated;
+    private terminate;
+    load(): Promise<{
+        identity?: import("@freecorps/ember-client").LocalIdentity | null;
+    }>;
+    close(): Promise<void>;
+}
+/** Offline storage on SQLite-Wasm over OPFS, run in a dedicated Worker (see opfs-worker.ts). */
+export declare function opfsStorage(options: OpfsStorageOptions): OpfsStorage;

package/dist/opfs.js

@@ -0,0 +1,66 @@
+// The page half of OPFS storage: a `StorageAdapter` whose calls run in the app's offline Worker (opfs-worker.ts),
+// where SQLite-Wasm owns the OPFS files. Local results are watched there and streamed back. The Worker reports its
+// `sync` specs on load, so they are declared once, in the Worker.
+//
+//   import { opfsStorage } from "@freecorps/ember-offline/opfs";
+//   new EmberClient({
+//     url,
+//     storage: opfsStorage({ worker: new Worker(new URL("./ember-offline.worker.ts", import.meta.url), { type: "module" }) }),
+//     optimisticUpdates: { "messages:send": addMessage },
+//   });
+//
+// If OPFS or the Worker fails to start, `load()` rejects and the client carries on without offline storage
+// (`storage_error`), as with any adapter.
+import { RemoteStorage } from "./remote.js";
+export class OpfsStorage extends RemoteStorage {
+    options;
+    worker;
+    failed;
+    constructor(options) {
+        const worker = typeof options.worker === "function" ? options.worker() : options.worker;
+        super(worker);
+        this.options = options;
+        this.worker = worker;
+        // A Worker that cannot load (bad URL, syntax error, no module workers) fails the load instead of hanging it.
+        let fail = () => { };
+        this.failed = new Promise((_, reject) => (fail = reject));
+        this.failed.catch(() => undefined);
+        // After a successful load too: a Worker that reports an error (crash, wasm abort, OOM) is not trusted again —
+        // calls in flight and later ones fail with the error, watches get it once, and the Worker is terminated so it
+        // releases its OPFS handles (and, with several tabs, the leader lock for the next tab).
+        const w = worker;
+        w.addEventListener?.("error", (e) => {
+            const error = new Error(`offline worker failed: ${e?.message ?? "error"}`);
+            fail(error);
+            this.setUnavailable(error, { permanent: true });
+            this.terminate();
+        });
+    }
+    terminated = false;
+    terminate() {
+        if (this.terminated || this.options.terminate === false)
+            return;
+        this.terminated = true;
+        this.worker.terminate?.();
+    }
+    async load() {
+        return await Promise.race([super.load(), this.failed]);
+    }
+    async close() {
+        // A dead Worker never answers "close": stop waiting when it has failed or after the timeout.
+        let timer;
+        const timeout = new Promise((r) => (timer = setTimeout(r, this.options.closeTimeoutMs ?? 5000)));
+        try {
+            await Promise.race([this.shutdown(), this.failed.catch(() => undefined), timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+            this.detach();
+            this.terminate();
+        }
+    }
+}
+/** Offline storage on SQLite-Wasm over OPFS, run in a dedicated Worker (see opfs-worker.ts). */
+export function opfsStorage(options) {
+    return new OpfsStorage(options);
+}

package/dist/remote.d.ts

@@ -0,0 +1,109 @@
+import { type LocalIdentity, type LocalQueryRequest, type LocalQueryResult, type PendingStorage, type QueryUpdate, type StorageAdapter, type SyncSpec } from "@freecorps/ember-client";
+/** Anything that carries messages both ways (Worker, `self` in a worker, MessagePort, BroadcastChannel). */
+export interface Endpoint {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", listener: (e: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (e: {
+        data: unknown;
+    }) => void): void;
+}
+/** What can be served: a StorageAdapter, optionally with `watchQueryLocally` and `clear` (OfflineStore has both). */
+export type ServableStorage = StorageAdapter & {
+    clear?(): Promise<void>;
+};
+type Op = "load" | "getClientId" | "setClientId" | "loadPending" | "putPending" | "removePending" | "applyPatch" | "runQueryLocally" | "setIdentity" | "flush" | "clear" | "close" | "watch" | "unwatch";
+export declare const randomId: () => string;
+/** Calls `op` on an adapter (the serving side of the protocol, also used to re-run calls locally). */
+export declare function invoke(s: ServableStorage, op: Op, a: unknown[]): Promise<unknown>;
+export interface ServeOptions {
+    /** The address requests must be sent to (default `"*"`: any). */
+    address?: string;
+    /** First message from a caller (tabs.ts watches its liveness). */
+    onPeer?(peer: string): void;
+}
+export interface Served {
+    /** Announce this server (callers resend what is in flight). */
+    announce(from: string): void;
+    /** Forget a caller's watches (it is gone). */
+    dropPeer(peer: string): void;
+    stop(): void;
+}
+/** Serves an adapter on an endpoint: answers calls addressed to it, streams watched results. */
+export declare function serveStorage(storage: ServableStorage, endpoint: Endpoint, options?: ServeOptions): Served;
+export interface RemoteStorageOptions {
+    /** This caller's address (default: random). */
+    id?: string;
+    /** The server's address (default `"*"`). */
+    to?: string;
+    /** Instead of posting, run calls here (a tab that became the leader runs its own calls locally). */
+    local?: ServableStorage | null;
+    /** A server announced itself (after the calls in flight were resent to it). */
+    onLeader?(from: string): void;
+}
+/**
+ * The client side: a StorageAdapter whose calls run on a remote `serveStorage`. Calls in flight are resent when a
+ * new server announces itself (`k: "leader"`), and watches are re-established there.
+ */
+export declare class RemoteStorage implements StorageAdapter {
+    private readonly endpoint;
+    readonly id: string;
+    readonly persistPending: PendingStorage;
+    private syncSpecs;
+    private seq;
+    private readonly inflight;
+    private readonly watches;
+    /** Local unwatch functions while calls run locally. */
+    private readonly localWatches;
+    private local;
+    /** No server to send to (see setUnavailable): calls fail with this until one announces itself. */
+    private unavailable;
+    /** The server is gone for good (setUnavailable permanent): calls fail with this, announcements are ignored. */
+    private dead;
+    private readonly to;
+    private readonly onLeader;
+    private closed;
+    private readonly listener;
+    constructor(endpoint: Endpoint, options?: RemoteStorageOptions);
+    /** Known after `load()` (the server's `sync` specs, as names). */
+    get sync(): readonly SyncSpec[];
+    load(): Promise<{
+        identity?: LocalIdentity | null;
+    }>;
+    applyPatch(u: QueryUpdate): Promise<void>;
+    runQueryLocally(req: LocalQueryRequest): Promise<LocalQueryResult | undefined>;
+    setIdentity(identity: LocalIdentity | null): Promise<void>;
+    flush(): Promise<void>;
+    clear(): Promise<void>;
+    watchQueryLocally(req: LocalQueryRequest, onResult: (r: LocalQueryResult | undefined) => void, onError?: (e: Error) => void): () => void;
+    private establish;
+    /**
+     * Run calls here from now on (null: post them again). Calls in flight are re-run on the new target and watches
+     * re-established there.
+     */
+    setLocal(local: ServableStorage | null): void;
+    /**
+     * Nobody serves now (a tab that could not open the storage gave up the lead): calls in flight and new calls
+     * fail with `error` instead of waiting, watches get `error` once. The next server that announces itself ends
+     * this — calls go to it and watches are re-established there.
+     */
+    setUnavailable(error: Error, options?: {
+        permanent?: boolean;
+    }): void;
+    private call;
+    private dispatch;
+    /**
+     * A new server (or a local target): every call still in flight runs again there, in order; watches too. Each
+     * call goes out under a new request id, so only the server it was last sent to can answer it: a late answer of
+     * the previous server (to the old id) finds nothing.
+     */
+    private resend;
+    private onMessage;
+    /** Closes the served storage itself (then this caller): e.g. the Worker's database before terminating it. */
+    shutdown(): Promise<void>;
+    /** Stop: pending calls are rejected, the server drops this caller's watches. */
+    close(): void | Promise<void>;
+    protected detach(): void;
+}
+export {};