@freecorps/ember-offline 0.1.0 → 0.3.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,10 @@
  * 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 { localOptimisticUpdates, type LocalOptimisticOptions } from "./mutations.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,8 @@
  * Contract and limits: docs/design/contracts.md, "Offline".
  */
 export { createOfflineStorage, OfflineStore } from "./store.js";
-export { NeedData, recordKey } from "./backend.js";
+export { localOptimisticUpdates } from "./mutations.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/mutations.d.ts

@@ -0,0 +1,15 @@
+import type { OptimisticUpdate } from "@freecorps/ember-client";
+import { type Identity, type LocalSchema } from "@freecorps/ember-server";
+export interface LocalOptimisticOptions {
+    schema: LocalSchema;
+    /** The app's mutation modules (`{ messages }` or `{ "messages:send": send }`): public `mutation(...)` definitions. */
+    mutations: unknown;
+    /** The queries whose loaded values are the replica and get optimistic values (public `query(...)` definitions). */
+    queries: unknown;
+    /** Who the mutation runs as locally (decoded from the client's token; not verified). */
+    identity?: () => Identity | null;
+    /** Errors from running a mutation or query locally (default: ignored; the server's answer stands). */
+    onError?: (fn: string, e: Error) => void;
+}
+/** One optimistic update per registered mutation, keyed by its name (`"messages:send"`), for `EmberClient`. */
+export declare function localOptimisticUpdates(o: LocalOptimisticOptions): Record<string, OptimisticUpdate>;

package/dist/mutations.js

@@ -0,0 +1,112 @@
+// Optimistic updates without writing one per query (PLAN §10, Brigade RFC 0016 gap G5): the client runs the same
+// `mutation(...)` the server registers over the documents its loaded queries returned, then runs the registered
+// local queries again over the result. Every subscription whose value changes shows it until the server answers.
+//
+//   import * as messages from "../ember/messages";
+//   const client = new EmberClient({
+//     url,
+//     optimisticUpdates: localOptimisticUpdates({ schema, mutations: { messages }, queries: { messages } }),
+//   });
+//
+// What it relies on, per call:
+// - The replica is the documents in the loaded values of the registered queries (`documentsIn`), so a mutation sees
+//   exactly what the screen shows. A mutation that reads a row nobody loaded behaves as if the row did not exist; one
+//   that throws (a rule, `OfflineUnsupported`) changes nothing here, and the server's answer stands.
+// - A query only gets an optimistic value when running it over that replica, before the mutation, gives back the
+//   value the server confirmed (deep equal). Projections, counts and queries over rows not on screen fail that check
+//   and keep their confirmed value, instead of showing something wrong.
+// - Inserted documents get local ids; the server's confirmed value (its own ids) replaces them.
+import { assertLocalMutation, documentsIn, localQueryRegistry, overlayReader, runLocalMutation, runLocalQuery, flattenFunctions, } from "@freecorps/ember-server";
+import { compareValues } from "@freecorps/ember-values";
+const EMPTY = { scan: () => [], get: () => null };
+/**
+ * One clock and seed per pending mutation, kept for as long as it is pending. EmberClient re-runs every pending update
+ * on each recompute (a new snapshot, another mutation) with the same pending record: keyed by it, a mutation's local
+ * ids and `ctx.random`/`ctx.now` stay the same across re-runs (no remounted rows, stacked edits find the row), and two
+ * calls never share a seed, even when the app passes the same args object twice (a form, a double submit).
+ */
+const runs = new WeakMap();
+function runOf(mutation) {
+    const fresh = () => ({ now: Date.now(), seed: Math.floor(Math.random() * 0x100000000) });
+    if (!mutation)
+        return fresh();
+    let r = runs.get(mutation);
+    if (!r)
+        runs.set(mutation, (r = fresh()));
+    return r;
+}
+function sameValue(a, b) {
+    try {
+        return compareValues(a, b) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** One optimistic update per registered mutation, keyed by its name (`"messages:send"`), for `EmberClient`. */
+export function localOptimisticUpdates(o) {
+    const queries = localQueryRegistry(o.queries);
+    const mutations = new Map();
+    for (const [name, fn] of flattenFunctions(o.mutations ?? {})) {
+        assertLocalMutation(name, fn);
+        mutations.set(name, fn);
+    }
+    const out = {};
+    for (const [name, fn] of mutations) {
+        out[name] = (store, args, mutation) => runOptimistic(o, queries, name, fn, store, args, mutation);
+    }
+    return out;
+}
+function runOptimistic(o, queries, name, fn, store, args, mutation) {
+    const m = o.schema.manifest;
+    // What the screen shows now (earlier pending mutations included: the store returns the optimistic view).
+    const loaded = [];
+    for (const [qname, qfn] of queries) {
+        for (const q of store.getAllQueries(qname)) {
+            if (q.value !== undefined)
+                loaded.push({ name: qname, fn: qfn, args: (q.args ?? {}), value: q.value });
+        }
+    }
+    if (!loaded.length)
+        return;
+    const replica = overlayReader(EMPTY, o.schema);
+    // Copies: what the mutation reads (and may change in place) is never the snapshot on screen.
+    for (const l of loaded)
+        for (const { table, doc } of documentsIn(m, l.value))
+            replica.put(table, structuredClone(doc));
+    const identity = o.identity?.() ?? null;
+    const { now, seed } = runOf(mutation);
+    // Only queries the replica reproduces get an optimistic value.
+    const reproducible = loaded.filter((l) => {
+        try {
+            return sameValue(runLocalQuery(l.fn, l.args, { schema: o.schema, reader: replica, identity, now }).value, l.value);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!reproducible.length)
+        return;
+    const after = overlayReader(replica, o.schema);
+    try {
+        runLocalMutation(fn, args, { schema: o.schema, reader: after, identity, now, seed });
+    }
+    catch (e) {
+        o.onError?.(name, e);
+        return;
+    }
+    if (!after.changes().length)
+        return;
+    for (const l of reproducible) {
+        let value;
+        try {
+            value = runLocalQuery(l.fn, l.args, { schema: o.schema, reader: after, identity, now }).value;
+        }
+        catch (e) {
+            o.onError?.(l.name, e);
+            continue;
+        }
+        if (!sameValue(value, l.value))
+            store.setQuery(l.name, l.args, value);
+    }
+}

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;