@muhkoo/connect 0.7.0-alpha.5 → 0.8.0-alpha.0

package/dist/server/index.js

@@ -2130,6 +2130,14 @@ var EventCoreEvents;
     EventCoreEvents["MESSAGE"] = "message";
     EventCoreEvents["GET_HISTORY"] = "get_history";
     EventCoreEvents["RECEIVED_HISTORY"] = "received_history";
+    // Offline layer — connectivity + background sync lifecycle. Emitted by the
+    // ConnectivityManager / SyncEngine; apps subscribe to drive a status UI.
+    EventCoreEvents["ONLINE"] = "online";
+    EventCoreEvents["OFFLINE"] = "offline";
+    EventCoreEvents["SYNCING"] = "syncing";
+    EventCoreEvents["SYNC_PROGRESS"] = "sync_progress";
+    EventCoreEvents["SYNC_COMPLETE"] = "sync_complete";
+    EventCoreEvents["SYNC_ERROR"] = "sync_error";
 })(EventCoreEvents || (EventCoreEvents = {}));
 /**
  * @public
@@ -2968,7 +2976,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.7.0-alpha.4";
+const VERSION = "0.8.0-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -4630,30 +4638,104 @@ class KvNamespace {
     cipherIdentity = null;
     constructor(deps) {
         this.deps = deps;
+        // Replay queued kv writes on reconnect by re-issuing the original request.
+        if (deps.offline?.enabled) ;
+    }
+    /** Replay one queued kv mutation (called by the sync engine). */
+    async replay(entry) {
+        const a = entry.args;
+        if (entry.method === "set") {
+            await this.deps.http.post(this.kvPath(a.collection, a.id), { value: a.stored, hlc: a.hlc });
+        }
+        else {
+            await this.deps.http.del(this.kvPath(a.collection, a.id), { hlc: a.hlc });
+        }
     }
     /** Store `value` under `collection`/`id` (encrypted at rest by default). */
     async set(collection, id, value, opts) {
         const encrypt = opts?.encrypt !== false;
         const stored = encrypt ? await this.getCipher().encrypt(value) : value;
-        await this.deps.http.post(this.kvPath(collection, id), { value: stored });
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            await this.deps.http.post(this.kvPath(collection, id), { value: stored });
+            return;
+        }
+        const fullKey = `${collection}/${id}`;
+        const hlc = await offline.nextHlc();
+        await offline.writeLocal(this.commitment(), fullKey, stored, hlc);
+        try {
+            await this.deps.http.post(this.kvPath(collection, id), { value: stored, hlc });
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err; // server reachable + refused
+            await offline.enqueue("set", { collection, id, stored, hlc }, hlc, offline.newClientId());
+        }
     }
     /** Fetch the value at `collection`/`id`, or `null` if absent. */
     async get(collection, id) {
-        const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
-        return this.decode(res.value);
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
+            return this.decode(res.value);
+        }
+        const fullKey = `${collection}/${id}`;
+        try {
+            const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
+            // Refresh the cache from the authoritative read (merge by HLC).
+            await offline.mergeRemote(this.commitment(), fullKey, res.value ?? null, res.value == null ? "delete" : "set", res.hlc);
+            return this.decode(res.value);
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err; // a real server error, not offline
+            const entry = await offline.read(this.commitment(), fullKey);
+            if (!entry || entry.deleted)
+                return null;
+            return this.decode(entry.value);
+        }
     }
     /** Delete `collection`/`id`. Returns whether the key existed. */
     async delete(collection, id) {
-        const res = await this.deps.http.del(this.kvPath(collection, id), {});
-        return Boolean(res.existed);
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            const res = await this.deps.http.del(this.kvPath(collection, id), {});
+            return Boolean(res.existed);
+        }
+        const fullKey = `${collection}/${id}`;
+        const hlc = await offline.nextHlc();
+        await offline.deleteLocal(this.commitment(), fullKey, hlc);
+        try {
+            const res = await this.deps.http.del(this.kvPath(collection, id), { hlc });
+            return Boolean(res.existed);
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await offline.enqueue("delete", { collection, id, hlc }, hlc, offline.newClientId());
+            return true; // optimistic
+        }
     }
     /** List the ids present in `collection`. */
     async list(collection) {
-        const res = await this.deps.http.post(this.spacePath("/list"), {});
         const prefix = `${collection}/`;
-        return (res.keys ?? [])
-            .filter((k) => k.startsWith(prefix))
-            .map((k) => k.slice(prefix.length));
+        const offline = this.deps.offline;
+        const fromKeys = (keys) => keys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+        if (!offline?.enabled) {
+            const res = await this.deps.http.post(this.spacePath("/list"), {});
+            return fromKeys(res.keys ?? []);
+        }
+        try {
+            const res = await this.deps.http.post(this.spacePath("/list"), {});
+            // Union with cached live keys so un-synced offline creates still show.
+            const cached = await offline.liveKeys(this.commitment());
+            return [...new Set([...(res.keys ?? []), ...cached].filter((k) => k.startsWith(prefix)))].map((k) => k.slice(prefix.length));
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            return fromKeys(await offline.liveKeys(this.commitment()));
+        }
     }
     /** Reserved — server-side query is deferred (see the overhaul plan). */
     async query(_collection, _filter) {
@@ -4712,6 +4794,10 @@ class KvNamespace {
             return;
         const collection = frame.key.slice(0, slash);
         const id = frame.key.slice(slash + 1);
+        // Keep the offline cache warm from the realtime feed (merge by HLC).
+        if (this.deps.offline?.enabled) {
+            await this.deps.offline.mergeRemote(this.commitment(), frame.key, frame.op === "set" ? frame.value ?? null : null, frame.op, frame.hlc);
+        }
         const data = frame.op === "set" ? await this.decode(frame.value) : null;
         handler({ collection, id, type: frame.op, data });
     }
@@ -4779,41 +4865,109 @@ class KvNamespace {
 class DbTable {
     http;
     name;
-    constructor(http, name) {
+    offline;
+    constructor(http, name, offline) {
         this.http = http;
         this.name = name;
+        this.offline = offline;
     }
     base() {
         return `/api/db/${encodeURIComponent(this.name)}`;
     }
+    rowUrl(id) {
+        return `${this.base()}/${encodeURIComponent(String(id))}`;
+    }
     /** Insert a row. Returns the created row and its primary-key value. */
     async insert(values) {
-        return this.http.post(this.base(), { values });
+        if (!this.offline?.enabled)
+            return this.http.post(this.base(), { values });
+        const hlc = await this.offline.nextHlc();
+        const _hlc = this.offline.columnStamps(values, hlc);
+        try {
+            const res = await this.http.post(this.base(), { values, _hlc });
+            await this.offline.writeRow(this.name, String(res.id), res.row);
+            return res;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            // Offline: queue for replay. No server pk yet — return a provisional
+            // client id so the caller has a stable handle until sync.
+            const clientId = this.offline.newClientId();
+            await this.offline.enqueue("insert", { table: this.name, values, _hlc }, hlc, clientId);
+            return { row: values, id: clientId };
+        }
     }
     /** Fetch a row by primary key, or `null` if it doesn't exist. */
     async get(id) {
         try {
-            const res = await this.http.get(`${this.base()}/${encodeURIComponent(String(id))}`);
+            const res = await this.http.get(this.rowUrl(id));
+            if (this.offline?.enabled)
+                await this.offline.writeRow(this.name, String(id), res.row);
             return res.row;
         }
         catch (e) {
             if (e?.status === 404)
                 return null;
+            if (this.offline?.enabled && !(e instanceof HttpError)) {
+                return (await this.offline.readRow(this.name, String(id)));
+            }
             throw e;
         }
     }
     /** Query rows with filters, ordering, and keyset pagination. */
     async query(query = {}) {
-        return this.http.post(`${this.base()}/query`, query);
+        if (!this.offline?.enabled)
+            return this.http.post(`${this.base()}/query`, query);
+        try {
+            const res = await this.http.post(`${this.base()}/query`, query);
+            await this.offline.writeQuery(this.name, query, res);
+            return res;
+        }
+        catch (e) {
+            if (e instanceof HttpError)
+                throw e;
+            const cached = await this.offline.readQuery(this.name, query);
+            return cached ?? { rows: [], nextCursor: null };
+        }
     }
     /** Update a row by primary key. Returns the updated row. */
     async update(id, values) {
-        return this.http.patch(`${this.base()}/${encodeURIComponent(String(id))}`, { values });
+        if (!this.offline?.enabled)
+            return this.http.patch(this.rowUrl(id), { values });
+        const hlc = await this.offline.nextHlc();
+        const _hlc = this.offline.columnStamps(values, hlc);
+        await this.offline.patchRow(this.name, String(id), values); // optimistic
+        try {
+            const res = await this.http.patch(this.rowUrl(id), { values, _hlc });
+            await this.offline.writeRow(this.name, String(id), res.row);
+            return res;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await this.offline.enqueue("update", { table: this.name, id, values, _hlc }, hlc, this.offline.newClientId());
+            return { row: (await this.offline.readRow(this.name, String(id))) };
+        }
     }
     /** Delete a row by primary key. Returns the number of rows removed (0 or 1). */
     async delete(id) {
-        const res = await this.http.del(`${this.base()}/${encodeURIComponent(String(id))}`);
-        return res.deleted ?? 0;
+        if (!this.offline?.enabled) {
+            const res = await this.http.del(this.rowUrl(id));
+            return res.deleted ?? 0;
+        }
+        const hlc = await this.offline.nextHlc();
+        await this.offline.deleteRow(this.name, String(id)); // optimistic
+        try {
+            const res = await this.http.del(this.rowUrl(id), { _hlc: hlc });
+            return res.deleted ?? 0;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await this.offline.enqueue("delete", { table: this.name, id, hlc }, hlc, this.offline.newClientId());
+            return 1; // optimistic
+        }
     }
 }
 class DbNamespace {
@@ -4829,7 +4983,21 @@ class DbNamespace {
      *   const todos = client.db.table<Todo>('todos');
      */
     table(name) {
-        return new DbTable(this.deps.http, name);
+        return new DbTable(this.deps.http, name, this.deps.offline);
+    }
+    /** Replay one queued db mutation (called by the sync engine). */
+    async replay(entry) {
+        const a = entry.args;
+        const base = `/api/db/${encodeURIComponent(a.table)}`;
+        if (entry.method === "insert") {
+            await this.deps.http.post(base, { values: a.values, _hlc: a._hlc });
+        }
+        else if (entry.method === "update") {
+            await this.deps.http.patch(`${base}/${encodeURIComponent(String(a.id))}`, { values: a.values, _hlc: a._hlc });
+        }
+        else if (entry.method === "delete") {
+            await this.deps.http.del(`${base}/${encodeURIComponent(String(a.id))}`, { _hlc: a.hlc });
+        }
     }
 }
 
@@ -5293,6 +5461,8 @@ class ShardClient {
     baseUrl;
     pathPrefix;
     fetchFn;
+    cache;
+    deferUpload;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -5308,6 +5478,8 @@ class ShardClient {
             throw new Error("ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
         }
         this.fetchFn = f.bind(globalThis);
+        this.cache = opts.cache;
+        this.deferUpload = opts.deferUpload;
     }
     /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
     urlForHash(hash) {
@@ -5321,12 +5493,29 @@ class ShardClient {
      */
     async putShard(hash, bytes) {
         const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, {
-            method: "PUT",
-            headers: { "content-type": "application/octet-stream" },
-            // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
-            body: bytes,
-        });
+        // Write the cache first so a just-uploaded file reads back even if the
+        // network PUT then fails (offline). The bytes are content-addressed, so
+        // this is safe to keep regardless of upload outcome.
+        if (this.cache)
+            await this.cache.put(hash, bytes);
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method: "PUT",
+                headers: { "content-type": "application/octet-stream" },
+                // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
+                body: bytes,
+            });
+        }
+        catch (err) {
+            // Network unreachable (offline). If a defer hook is wired, queue the
+            // upload for replay and report success — the bytes are cached.
+            if (this.deferUpload) {
+                await this.deferUpload(hash);
+                return { dedup: false };
+            }
+            throw err;
+        }
         if (!response.ok) {
             const text = await safeText(response);
             throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
@@ -5346,8 +5535,25 @@ class ShardClient {
      * `null` for 404 so callers can distinguish "missing" from "errored".
      */
     async getShard(hash) {
+        // Cache-first: a hit is content-verified by construction (key == hash).
+        if (this.cache) {
+            const cached = await this.cache.get(hash);
+            if (cached)
+                return cached;
+        }
         const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, { method: "GET" });
+        let response;
+        try {
+            response = await this.fetchFn(url, { method: "GET" });
+        }
+        catch (err) {
+            // Offline with no cache hit: report the shard as missing so
+            // FileStorage's Reed–Solomon recovery can still reconstruct from the
+            // shards that ARE cached. Rethrow when there's no cache to fall back on.
+            if (this.cache)
+                return null;
+            throw err;
+        }
         if (response.status === 404)
             return null;
         if (!response.ok) {
@@ -5355,7 +5561,10 @@ class ShardClient {
             throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);
         }
         const buf = await response.arrayBuffer();
-        return new Uint8Array(buf);
+        const bytes = new Uint8Array(buf);
+        if (this.cache)
+            void this.cache.put(hash, bytes);
+        return bytes;
     }
     /**
      * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
@@ -5860,6 +6069,8 @@ class StorageNamespace {
                 baseUrl: this.deps.baseUrl,
                 pathPrefix: "/api/shards",
                 fetch: this.deps.http.fetch,
+                cache: this.deps.shardCache,
+                deferUpload: this.deps.deferShardUpload,
             });
         }
         return this._shards;
@@ -6556,6 +6767,7 @@ class Space {
     /** Per-instance event bus for fan-out events (isolated across spaces). */
     events = new EventTarget();
     rawWired = false;
+    catchUpUnsub = null;
     constructor(deps) {
         this.deps = deps;
         this.name = deps.name;
@@ -6606,12 +6818,19 @@ class Space {
                     this.channel?.sendRaw({ name: this.deps.myId() });
                 });
                 this.wireFanout();
+                // Register offline catch-up once: on each reconnect the sync
+                // engine pages history forward to fill any gap we missed.
+                if (this.deps.offline?.enabled && !this.catchUpUnsub) {
+                    this.catchUpUnsub = this.deps.offline.registerCatchUp(() => this.catchUp());
+                }
             }
         }
         await this.channel.connect();
     }
     disconnect() {
         this.channel?.disconnect();
+        this.catchUpUnsub?.();
+        this.catchUpUnsub = null;
     }
     /** Subscribe to a raw channel event. Buffered until `connect()` if early. */
     on(event, handler) {
@@ -6658,7 +6877,30 @@ class Space {
      * persisted `spaceMessage`. Requires a keyring.
      */
     async sendMessage(payload, opts = {}) {
-        this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
+            return;
+        }
+        // Offline-aware path: stamp the message, cache it optimistically (so the
+        // UI can show it instantly via cachedMessages), then send if connected
+        // or durably queue it for replay on reconnect.
+        const clientId = offline.newClientId();
+        const hlc = await offline.nextHlc();
+        const packet = await this.sealMessage(payload, opts.channel, opts.contentType, clientId);
+        const frame = { spaceMessage: packet };
+        await offline.putMessage(this.id, {
+            handle: provisionalSpaceKey(clientId),
+            packet,
+            op: "msg",
+            clientId,
+            hlc,
+            pending: true,
+        });
+        if (this.isConnected())
+            this.sendRaw(frame);
+        else
+            await offline.enqueueFrame(this.id, frame, clientId, hlc);
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler) {
@@ -6676,7 +6918,22 @@ class Space {
      */
     async editMessage(handle, payload, opts = {}) {
         const spaceMessage = await this.sealMessage(payload, opts.channel, opts.contentType);
-        this.sendRaw({ editSpaceMessage: { ts: handle, spaceMessage } });
+        const frame = { editSpaceMessage: { ts: handle, spaceMessage } };
+        const offline = this.deps.offline;
+        if (offline?.enabled) {
+            await offline.putMessage(this.id, {
+                handle: padSpaceHandle(handle),
+                packet: spaceMessage,
+                op: "edit",
+                hlc: await offline.nextHlc(),
+            });
+            if (this.isConnected())
+                this.sendRaw(frame);
+            else
+                await offline.enqueueFrame(this.id, frame, offline.newClientId(), await offline.nextHlc());
+            return;
+        }
+        this.sendRaw(frame);
     }
     /**
      * Hard-delete a persisted message by its server {@link SpaceMessageEvent.handle}
@@ -6684,7 +6941,45 @@ class Space {
      * original author. Receivers get an {@link onMessageDeleted} event.
      */
     async deleteMessage(handle) {
-        this.sendRaw({ deleteSpaceMessage: { ts: handle } });
+        const frame = { deleteSpaceMessage: { ts: handle } };
+        const offline = this.deps.offline;
+        if (offline?.enabled) {
+            await offline.putDeleted(this.id, handle);
+            if (this.isConnected())
+                this.sendRaw(frame);
+            else
+                await offline.enqueueFrame(this.id, frame, offline.newClientId(), await offline.nextHlc());
+            return;
+        }
+        this.sendRaw(frame);
+    }
+    /**
+     * Decrypt and return the locally-cached message log for this space, in
+     * handle order (pending sends last). Works offline — the source is the
+     * IndexedDB cache populated by live frames + {@link history}. Apps call this
+     * on boot to paint instantly, then subscribe to {@link onMessage} for live
+     * updates. Returns `[]` when offline support is off.
+     */
+    async cachedMessages() {
+        const offline = this.deps.offline;
+        if (!offline?.enabled || !this.cipher)
+            return [];
+        const entries = await offline.loadMessages(this.id);
+        const out = [];
+        for (const e of entries) {
+            if (e.deleted || !e.packet)
+                continue;
+            // Already verified when first cached → skip re-verification (which
+            // would also fail offline without a warm member directory).
+            const decoded = await this.decodeFrame(e.packet, this.cipher, 
+            /*isRawFrame*/ true, e.pending ? 0 : Number(e.handle), 
+            /*skipVerify*/ true);
+            if (decoded) {
+                decoded.pending = e.pending;
+                out.push(decoded);
+            }
+        }
+        return out;
     }
     /** Subscribe to in-place edits of persisted messages (new content at the same handle). */
     onMessageEdited(handler) {
@@ -6745,8 +7040,21 @@ class Space {
         const messages = [];
         for (const raw of body.messages ?? []) {
             const decoded = await this.decodeFrame(raw, cipher);
-            if (decoded)
-                messages.push(decoded);
+            if (!decoded)
+                continue;
+            messages.push(decoded);
+            // Warm the offline cache with the inner sealed packet at its handle.
+            if (this.deps.offline?.enabled) {
+                try {
+                    const outer = JSON.parse(raw);
+                    if (typeof outer.spaceMessage === "string") {
+                        await this.cacheFrame(outer.spaceMessage, decoded, "msg");
+                    }
+                }
+                catch {
+                    /* unparseable history row — skip caching, still surfaced above */
+                }
+            }
         }
         return { messages, nextCursor: body.nextCursor ?? null };
     }
@@ -6813,6 +7121,8 @@ class Space {
             baseUrl: this.deps.httpBaseUrl,
             pathPrefix: "/api/shards",
             fetch: this.deps.fetch,
+            cache: this.deps.shardCache,
+            deferUpload: this.deps.deferShardUpload,
         });
         return new FileStorage({ shards });
     }
@@ -6831,9 +7141,12 @@ class Space {
         if (!f || typeof f !== "object")
             return;
         if (typeof f.spaceMessage === "string" && this.cipher) {
-            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, Number(f.timestamp ?? 0));
-            if (decoded)
+            const handle = Number(f.timestamp ?? 0);
+            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, handle);
+            if (decoded) {
                 this.emitEvent("message", decoded);
+                await this.cacheFrame(f.spaceMessage, decoded, "msg");
+            }
             return;
         }
         if (f.editSpaceMessage && typeof f.editSpaceMessage === "object" && this.cipher) {
@@ -6842,14 +7155,21 @@ class Space {
             const e = f.editSpaceMessage;
             if (typeof e.spaceMessage === "string") {
                 const decoded = await this.decodeFrame(e.spaceMessage, this.cipher, /*raw*/ true, Number(e.ts ?? 0));
-                if (decoded)
+                if (decoded) {
                     this.emitEvent("message-edited", decoded);
+                    await this.cacheFrame(e.spaceMessage, decoded, "edit");
+                }
             }
             return;
         }
         if (f.deleteSpaceMessage && typeof f.deleteSpaceMessage === "object") {
             const d = f.deleteSpaceMessage;
-            this.emitEvent("message-deleted", { handle: Number(d.ts ?? 0) });
+            const handle = Number(d.ts ?? 0);
+            this.emitEvent("message-deleted", { handle });
+            if (this.deps.offline?.enabled) {
+                await this.deps.offline.putDeleted(this.id, handle);
+                await this.deps.offline.observeHandle(this.id, handle);
+            }
             return;
         }
         if (f.pub && typeof f.pub === "object") {
@@ -6885,12 +7205,17 @@ class Space {
      * serialized `Packet` string. Shared by send (a new message) and edit
      * (replacement content for an existing handle). Requires a keyring.
      */
-    async sealMessage(payload, channel, contentType) {
+    async sealMessage(payload, channel, contentType, clientId) {
         const cipher = this.requireCipher(contentType);
         const message = new Message(payload);
         const headers = await cipher.seal(message.serialize());
         const source = this.deps.myId();
         const subject = channel ?? "default";
+        // Cleartext dedupe hint — lets the sender match its optimistic entry to
+        // the server echo. Not part of the signed canonical form (it carries no
+        // authority); worst case a stale hint just shows a transient duplicate.
+        if (clientId)
+            headers.cid = clientId;
         // Sign with our identity ECDSA key so receivers can verify authorship
         // end-to-end (independent of the relay's `source` stamp).
         const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
@@ -6910,7 +7235,7 @@ class Space {
      * the enclosing frame); false means `input` is the full
      * `{spaceMessage, name, timestamp}` frame and the handle is read from it.
      */
-    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0) {
+    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0, skipVerify = false) {
         try {
             let packetJson = input;
             let handle = serverTs;
@@ -6928,8 +7253,9 @@ class Space {
             // by `source`'s identity ECDSA key (looked up in the member
             // directory). Drop anything unsigned, signed by an unknown member,
             // or whose signature doesn't match — this defeats both member
-            // impersonation and a relay rewriting `source`.
-            if (!(await this.verifySender(packet)))
+            // impersonation and a relay rewriting `source`. Skipped only when
+            // re-reading from the local cache (already verified before caching).
+            if (!skipVerify && !(await this.verifySender(packet)))
                 return null;
             const serialized = await cipher.open(packet.headers);
             if (serialized === null)
@@ -6941,6 +7267,7 @@ class Space {
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
                 handle,
+                clientId: packet.headers?.cid,
                 message,
             };
         }
@@ -6983,6 +7310,62 @@ class Space {
         });
         return verifySpaceMessage(canonical, sig, key);
     }
+    /** Persist a decoded live/history/edit frame to the offline cache. */
+    async cacheFrame(packet, decoded, op) {
+        const offline = this.deps.offline;
+        if (!offline?.enabled)
+            return;
+        // An incoming real message supersedes any optimistic pending entry.
+        if (decoded.clientId)
+            await offline.dropPending(this.id, decoded.clientId);
+        await offline.putMessage(this.id, {
+            handle: padSpaceHandle(decoded.handle),
+            packet,
+            op,
+            clientId: decoded.clientId,
+        });
+        await offline.observeHandle(this.id, decoded.handle);
+    }
+    /**
+     * Inbound reconciliation run on reconnect: page the server's forward delta
+     * (`?since=<lastSeenHandle>`) to the head, pulling exactly the messages that
+     * landed while we were offline into the cache. Bounded so a long absence
+     * can't page forever. Falls back gracefully if the endpoint is unavailable.
+     */
+    async catchUp() {
+        const offline = this.deps.offline;
+        if (!offline?.enabled || !this.cipher)
+            return;
+        const cursor = await offline.getCursor(this.id);
+        let since = String(cursor?.lastSeenHandle ?? 0);
+        // Warm the member directory once so historical senders' signatures verify.
+        await this.deps.keyring?.refreshDirectory();
+        for (let page = 0; page < 50; page++) {
+            const url = `${this.deps.httpBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/history` +
+                `?since=${encodeURIComponent(since)}&limit=100`;
+            const res = await this.deps.fetch(url);
+            if (!res.ok)
+                break;
+            const body = (await res.json());
+            for (const raw of body.messages ?? []) {
+                const decoded = await this.decodeFrame(raw, this.cipher);
+                if (!decoded)
+                    continue;
+                try {
+                    const outer = JSON.parse(raw);
+                    if (typeof outer.spaceMessage === "string") {
+                        await this.cacheFrame(outer.spaceMessage, decoded, "msg");
+                    }
+                }
+                catch {
+                    /* unparseable row — skip */
+                }
+            }
+            if (!body.nextCursor)
+                break;
+            since = body.nextCursor;
+        }
+    }
     emitEvent(type, detail) {
         this.events.dispatchEvent(new CustomEvent(type, { detail }));
     }
@@ -7002,6 +7385,18 @@ class Space {
 function delay(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Zero-pad a numeric server handle for use as a cache key, so string-ordered
+ * keys sort in handle order. Must match the offline layer's `padHandle`.
+ */
+function padSpaceHandle(handle) {
+    return String(Math.max(0, Math.floor(handle))).padStart(16, "0");
+}
+/** Cache key for an un-acked optimistic send. Must match the offline layer's
+ *  `provisionalHandle` (sorts after every real, zero-padded handle). */
+function provisionalSpaceKey(clientId) {
+    return `~local:${clientId}`;
+}
 
 /**
  * `client.message` — realtime messaging over the shared-space primitive.
@@ -7496,6 +7891,156 @@ class KeyringClient {
     }
 }
 
+/**
+ * Message-log helpers — the conflict model for a Space's message history.
+ *
+ * Messages are the easy CRDT: the accelerator assigns every persisted message a
+ * monotonic, zero-padded `handle` that already totally-orders the log, and the
+ * sealed body is immutable. So the "log" is just a grow-only set keyed by
+ * `handle`, and convergence is structural — no server change needed.
+ *
+ * The only subtleties this module encodes:
+ *   - **Optimistic sends** have no server handle yet. We key them by a
+ *     provisional handle that sorts *after* every real one, and tag them with
+ *     the sender's `clientId` so the real frame (carrying the same `clientId`)
+ *     can replace the placeholder instead of duplicating it.
+ *   - **Edits** are a per-message LWW register on the body (greater HLC wins).
+ *   - **Deletes** are a tombstone at the message's handle.
+ */
+/** IndexedDB key for a message within a space. */
+function messageKey(spaceId, handle) {
+    return `${spaceId}|${handle}`;
+}
+/**
+ * A handle for an un-acked optimistic message. Prefixed with `"~"` (0x7E),
+ * which sorts after every digit, so pending sends always appear at the tail of
+ * the handle-ordered log until the real handle arrives.
+ */
+function provisionalHandle(clientId) {
+    return `~local:${clientId}`;
+}
+function isProvisional(handle) {
+    return handle.startsWith("~local:");
+}
+/**
+ * Merge two entries for the SAME handle. A delete always wins (tombstone); an
+ * edit wins over the entry it supersedes when its HLC is greater; otherwise the
+ * existing entry stands (a re-delivered `msg` is idempotent).
+ */
+function mergeMessage(local, incoming) {
+    if (!local)
+        return incoming;
+    if (incoming.op === "delete" || local.deleted) {
+        return { ...local, op: "delete", packet: null, deleted: true };
+    }
+    if (incoming.op === "edit") {
+        if (!local.hlc || (incoming.hlc && incoming.hlc > local.hlc)) {
+            return { ...local, packet: incoming.packet, hlc: incoming.hlc, op: "edit" };
+        }
+        return local;
+    }
+    // incoming.op === "msg": keep the already-stored (de-pending) entry.
+    return { ...local, pending: false };
+}
+
+/**
+ * `SpaceCache` — the offline adapter a {@link ../spaces/Space} talks to. It
+ * persists sealed message frames (ciphertext at rest), tracks per-space sync
+ * cursors, and records offline sends in the durable queue. Kept as its own
+ * object (rather than wiring the Space straight to the store + clock) so the
+ * Space stays decoupled from IndexedDB and so the no-op path is a single
+ * `enabled` check.
+ *
+ * Messages are the structural CRDT (see {@link ./crdt/MessageLog}): the server
+ * assigns a monotonic `handle` that totally-orders the log, so the cache just
+ * stores frames keyed by a zero-padded handle (real) or a provisional key
+ * (pending sends, which sort to the tail until their echo arrives).
+ */
+/** Zero-pad a numeric server handle so string keys sort in handle order. */
+function padHandle(handle) {
+    return String(Math.max(0, Math.floor(handle))).padStart(16, "0");
+}
+/**
+ * The surface a {@link ../spaces/Space} uses. Declared structurally on the
+ * Space side too (as `SpaceOfflineAdapter`) so the spaces module never imports
+ * the offline module.
+ */
+class SpaceCache {
+    manager;
+    store;
+    constructor(manager) {
+        this.manager = manager;
+        this.store = manager.store;
+    }
+    get enabled() {
+        return this.manager.enabled;
+    }
+    newClientId() {
+        return this.manager.newClientId();
+    }
+    nextHlc() {
+        return this.manager.nextHlc();
+    }
+    /** Persist a sealed message frame keyed by its (real or provisional) handle. */
+    async putMessage(spaceId, entry) {
+        await this.store.put("space-messages", messageKey(spaceId, entry.handle), entry);
+    }
+    /** Tombstone the message at `handle`. */
+    async putDeleted(spaceId, handle) {
+        const key = messageKey(spaceId, padHandle(handle));
+        const existing = await this.store.get("space-messages", key);
+        await this.store.put("space-messages", key, {
+            handle: padHandle(handle),
+            packet: null,
+            op: "delete",
+            deleted: true,
+            clientId: existing?.clientId,
+        });
+    }
+    /** Drop a pending (optimistic) entry once its real echo has been stored. */
+    async dropPending(spaceId, clientId) {
+        await this.store.delete("space-messages", messageKey(spaceId, provisionalHandle(clientId)));
+    }
+    /** All cached frames for a space, in handle order (pending ones last). */
+    async loadMessages(spaceId) {
+        const rows = await this.store.range("space-messages", `${spaceId}|`, `${spaceId}|￿`);
+        return rows.map((r) => r.value);
+    }
+    async getCursor(spaceId) {
+        return this.store.get("space-cursors", spaceId);
+    }
+    /** Advance the last-seen handle (monotonic) and track the oldest fetched. */
+    async observeHandle(spaceId, handle) {
+        if (!handle)
+            return;
+        const cur = (await this.getCursor(spaceId)) ?? {
+            lastSeenHandle: 0,
+            oldestHandle: handle,
+            fullyBackfilled: false,
+        };
+        const next = {
+            lastSeenHandle: Math.max(cur.lastSeenHandle, handle),
+            oldestHandle: cur.oldestHandle ? Math.min(cur.oldestHandle, handle) : handle,
+            fullyBackfilled: cur.fullyBackfilled,
+        };
+        await this.store.put("space-cursors", spaceId, next);
+    }
+    /** Queue a raw space frame for replay when the connection returns. */
+    async enqueueFrame(spaceId, frame, clientId, hlc) {
+        await this.manager.enqueue({
+            hlc,
+            clientId,
+            domain: "space",
+            method: "sendRaw",
+            args: { spaceId, frame },
+        });
+    }
+    /** Register an inbound catch-up task (forward/back history paging). */
+    registerCatchUp(task) {
+        return this.manager.registerCatchUp(task);
+    }
+}
+
 /**
  * `client.space` — the fan-out group-encryption surface.
  *
@@ -7531,8 +8076,26 @@ class ChannelExistsError extends Error {
 }
 class SpaceNamespace {
     deps;
+    spaceCache;
+    /** Spaces built this session, by id — used to route offline send replays. */
+    openSpaces = new Map();
     constructor(deps) {
         this.deps = deps;
+        if (deps.offline?.enabled) {
+            this.spaceCache = new SpaceCache(deps.offline);
+            // Replay queued space frames on reconnect: route each to its space
+            // (reopening + connecting it if needed), then re-send the raw frame.
+            deps.offline.registerReplayer("space", async (entry) => {
+                const { spaceId, frame } = entry.args;
+                let space = this.openSpaces.get(spaceId);
+                if (!space)
+                    space = await this.get(spaceId);
+                await space.connect();
+                if (!space.isConnected())
+                    throw new Error(`space ${spaceId} not connected for replay`);
+                space.sendRaw(frame);
+            });
+        }
     }
     /**
      * Create a new space: generate its keypair (public key = id), register
@@ -7693,7 +8256,7 @@ class SpaceNamespace {
             cache: this.deps.cache,
             historyPolicy,
         });
-        return new Space({
+        const space = new Space({
             name: spaceId,
             wsBaseUrl: this.deps.wsBaseUrl,
             httpBaseUrl: this.deps.http.baseUrl,
@@ -7702,7 +8265,14 @@ class SpaceNamespace {
             fetchTicket: () => this.fetchTicket(),
             keyring,
             historyPolicy,
+            offline: this.spaceCache,
+            shardCache: this.deps.offline?.fileCache,
+            deferShardUpload: this.deps.offline
+                ? (hash) => this.deps.offline.deferShardUpload(hash)
+                : undefined,
         });
+        this.openSpaces.set(spaceId, space);
+        return space;
     }
     /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
     async ensureIdentity(memberId) {
@@ -7949,6 +8519,1171 @@ class FunctionsNamespace {
     }
 }
 
+/**
+ * `HlcTimestamp` — a Hybrid Logical Clock reading, packed into a single
+ * lexicographically-sortable string so the whole offline layer (and the
+ * accelerator) can compare causality with one plain string comparison.
+ *
+ * An HLC fuses a physical wall-clock millisecond with a logical `counter`
+ * (breaks ties inside the same millisecond and lets the clock advance past a
+ * remote event without the wall clock moving) and a stable `nodeId` (a final,
+ * deterministic tiebreak so two devices never produce an "equal but different"
+ * stamp). See {@link ./HLC}.
+ *
+ * The packed form is `"{wall}:{counter}:{nodeId}"` with `wall` and `counter`
+ * zero-padded to a FIXED width. Fixed width is what makes lexicographic order
+ * equal to numeric order — `"0000000000123:..."` < `"0000000000124:..."`. The
+ * server only ever compares these strings; it never has to parse them.
+ */
+/** Zero-padded width of the wall-clock field. 15 digits holds ms timestamps
+ *  past the year 5000, so `Date.now()` (currently 13 digits) never overflows. */
+const WALL_DIGITS = 15;
+/** Zero-padded width of the logical counter. 5 digits allows 100k events in a
+ *  single wall-clock millisecond before the clock is forced forward — far more
+ *  than any real burst. */
+const COUNTER_DIGITS = 5;
+/** The smallest possible stamp — used as the "nothing stored yet" sentinel so a
+ *  first real write always wins (`compareHlc(real, ZERO_HLC) > 0`). */
+const ZERO_HLC = pack(0, 0, "");
+function padNum(n, width) {
+    const s = Math.max(0, Math.floor(n)).toString();
+    return s.length >= width ? s : "0".repeat(width - s.length) + s;
+}
+/** Pack the three components into the sortable string form. */
+function pack(wall, counter, nodeId) {
+    return `${padNum(wall, WALL_DIGITS)}:${padNum(counter, COUNTER_DIGITS)}:${nodeId}`;
+}
+/** Parse a packed stamp back into its components. Tolerates the empty/zero
+ *  sentinel. Throws on a malformed string so corruption surfaces loudly. */
+function unpack(stamp) {
+    const idx1 = stamp.indexOf(":");
+    const idx2 = stamp.indexOf(":", idx1 + 1);
+    if (idx1 < 0 || idx2 < 0) {
+        throw new Error(`malformed HLC timestamp: ${JSON.stringify(stamp)}`);
+    }
+    return {
+        wall: Number(stamp.slice(0, idx1)),
+        counter: Number(stamp.slice(idx1 + 1, idx2)),
+        nodeId: stamp.slice(idx2 + 1),
+    };
+}
+/**
+ * Total order over packed HLC strings: negative if `a < b`, positive if
+ * `a > b`, `0` only when they are byte-identical. Because the fields are
+ * fixed-width and ordered (wall, counter, nodeId), a single string comparison
+ * already yields causal order — this helper just normalizes the result to the
+ * `-1 | 0 | 1` shape callers expect.
+ */
+function compareHlc(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/** Convenience: is `a` strictly newer than `b`? */
+function isNewer(a, b) {
+    return compareHlc(a, b) > 0;
+}
+
+/**
+ * `HLC` — a Hybrid Logical Clock. Hands out monotonically increasing
+ * {@link HlcTimestamp} stamps that (a) track real time closely enough to be
+ * human-meaningful, yet (b) never go backwards, even across a reload or when a
+ * peer's clock is ahead of ours.
+ *
+ * Two operations, both the textbook HLC algorithm (Kulkarni et al.):
+ *   - `now()` — stamp a local event.
+ *   - `update(remote)` — observe a remote stamp (e.g. arriving on the realtime
+ *     change feed) and advance our clock past it, so any event we generate
+ *     afterwards is causally `> remote`.
+ *
+ * State is just `{ wall, counter }`; `nodeId` is fixed for the install. The
+ * owner ({@link ../OfflineManager}) seeds the clock from persisted state on
+ * boot and persists `getState()` after each tick so monotonicity survives page
+ * reloads — without that, a reload could mint a stamp that loses to one written
+ * seconds earlier.
+ */
+class HLC {
+    wall;
+    counter;
+    nodeId;
+    physical;
+    constructor(nodeId, opts = {}) {
+        this.nodeId = nodeId;
+        this.physical = opts.physical ?? (() => Date.now());
+        this.wall = opts.state?.wall ?? 0;
+        this.counter = opts.state?.counter ?? 0;
+    }
+    /** Stamp a locally-generated event. Advances the clock. */
+    now() {
+        const pt = this.physical();
+        const prevWall = this.wall;
+        this.wall = Math.max(prevWall, pt);
+        this.counter = this.wall === prevWall ? this.counter + 1 : 0;
+        return this.current();
+    }
+    /**
+     * Merge in an observed remote stamp and advance our clock strictly past it.
+     * Call this for every inbound HLC (change-feed frames, history rows) so the
+     * next `now()` is causally after anything we've seen.
+     */
+    update(remote) {
+        const pt = this.physical();
+        const prevWall = this.wall;
+        const newWall = Math.max(prevWall, remote.wall, pt);
+        if (newWall === prevWall && newWall === remote.wall) {
+            this.counter = Math.max(this.counter, remote.counter) + 1;
+        }
+        else if (newWall === prevWall) {
+            this.counter = this.counter + 1;
+        }
+        else if (newWall === remote.wall) {
+            this.counter = remote.counter + 1;
+        }
+        else {
+            this.counter = 0;
+        }
+        this.wall = newWall;
+        return this.current();
+    }
+    /** The current stamp without advancing the clock. */
+    current() {
+        return pack(this.wall, this.counter, this.nodeId);
+    }
+    /** Serializable `{ wall, counter }` for persistence. */
+    getState() {
+        return { wall: this.wall, counter: this.counter };
+    }
+}
+
+/**
+ * `ConnectivityManager` — the single source of truth for "are we online", which
+ * the offline layer needs to decide between a network call and a cache read, and
+ * to know when to flush the durable outbound queue.
+ *
+ * `navigator.onLine` alone lies often (captive portals, VPN flaps, a laptop
+ * that's "connected" to a network with no route), so we fuse three signals:
+ *   1. the browser `online`/`offline` events (coarse but free),
+ *   2. real fetch outcomes reported by {@link ../core/HttpClient} and the shard
+ *      client — a thrown `TypeError`/abort is the most reliable "offline" tell,
+ *      and a 2xx is the most reliable "online" tell,
+ *   3. the sync engine, which flips us to `syncing` while it drains the queue.
+ *
+ * The offline→online edge fires `onReconnect` (wired to the sync engine) so
+ * queued writes replay automatically. Transitions are debounced to avoid
+ * flapping the UI on a brief blip. State changes also emit on {@link EventCore}
+ * (`ONLINE`/`OFFLINE`/`SYNCING`) so apps can render a status indicator.
+ */
+class ConnectivityManager {
+    state;
+    listeners = new Set();
+    onReconnect;
+    debounceMs;
+    offlineTimer = null;
+    started = false;
+    handleOnline = () => this.markOnline();
+    handleOffline = () => this.scheduleOffline();
+    constructor(opts = {}) {
+        this.onReconnect = opts.onReconnect;
+        this.debounceMs = opts.debounceMs ?? 1500;
+        this.state =
+            typeof navigator !== "undefined" && navigator.onLine === false ? "offline" : "online";
+    }
+    /** Attach to the browser online/offline events. Safe to call in Node (no-op). */
+    start() {
+        if (this.started || typeof window === "undefined")
+            return;
+        window.addEventListener("online", this.handleOnline);
+        window.addEventListener("offline", this.handleOffline);
+        this.started = true;
+    }
+    stop() {
+        if (!this.started || typeof window === "undefined")
+            return;
+        window.removeEventListener("online", this.handleOnline);
+        window.removeEventListener("offline", this.handleOffline);
+        if (this.offlineTimer)
+            clearTimeout(this.offlineTimer);
+        this.started = false;
+    }
+    get current() {
+        return this.state;
+    }
+    get isOnline() {
+        return this.state !== "offline";
+    }
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onChange(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    /** Report a failed network attempt (thrown fetch / abort). */
+    reportFetchFailure() {
+        this.scheduleOffline();
+    }
+    /** Report a successful network round-trip — strongest "we're online" signal. */
+    reportFetchSuccess() {
+        this.markOnline();
+    }
+    /** The sync engine entering its drain phase. */
+    markSyncing() {
+        if (this.offlineTimer) {
+            clearTimeout(this.offlineTimer);
+            this.offlineTimer = null;
+        }
+        this.set("syncing");
+    }
+    /** The sync engine finished — settle back to online. */
+    markSynced() {
+        this.set("online");
+    }
+    markOnline() {
+        if (this.offlineTimer) {
+            clearTimeout(this.offlineTimer);
+            this.offlineTimer = null;
+        }
+        // The sync engine owns the syncing→online transition (via markSynced).
+        // A request succeeding mid-drain must not cut the syncing state short.
+        if (this.state === "syncing")
+            return;
+        const wasOffline = this.state === "offline";
+        this.set("online");
+        if (wasOffline) {
+            try {
+                this.onReconnect?.();
+            }
+            catch {
+                /* a reconnect handler must not break connectivity tracking */
+            }
+        }
+    }
+    scheduleOffline() {
+        if (this.state === "offline" || this.offlineTimer)
+            return;
+        this.offlineTimer = setTimeout(() => {
+            this.offlineTimer = null;
+            this.set("offline");
+        }, this.debounceMs);
+    }
+    set(state) {
+        if (state === this.state)
+            return;
+        this.state = state;
+        for (const cb of this.listeners) {
+            try {
+                cb(state);
+            }
+            catch {
+                /* a bad listener mustn't break the others */
+            }
+        }
+        const event = state === "online"
+            ? EventCoreEvents.ONLINE
+            : state === "offline"
+                ? EventCoreEvents.OFFLINE
+                : EventCoreEvents.SYNCING;
+        EventCore.emit(event, { state });
+    }
+}
+
+/**
+ * `OutboundQueue` — the durable record of writes made while offline (or that
+ * failed mid-flight) plus the machinery to replay them on reconnect. This is
+ * what makes offline writes *survive a reload*: unlike the in-memory buffer in
+ * {@link ../transport/WSTransport}, every entry lives in IndexedDB until it has
+ * been acknowledged by the server.
+ *
+ * Each domain registers a **replayer** — a function that re-applies one queued
+ * mutation by re-invoking the real namespace method (with an `isReplay` flag so
+ * it doesn't re-enqueue). `drain()` replays entries in HLC order:
+ *   - success → remove the entry;
+ *   - permanent failure (4xx) → drop it and surface a `SYNC_ERROR` (a write the
+ *     server will never accept must not wedge the queue forever);
+ *   - transient/network failure → stop draining and leave the rest for the next
+ *     reconnect.
+ *
+ * Replays are idempotent by construction (kv/db are LWW-by-key, messages dedupe
+ * by `clientId`, file PUTs are content-addressed), so re-running a partially
+ * drained queue is safe.
+ */
+class OutboundQueue {
+    store;
+    replayers = new Map();
+    draining = null;
+    constructor(store) {
+        this.store = store;
+    }
+    /** A domain registers how to replay its mutations. */
+    register(domain, replayer) {
+        this.replayers.set(domain, replayer);
+    }
+    /** Record a mutation for later replay; resolves with its assigned seq. */
+    enqueue(entry) {
+        return this.store.enqueue(entry);
+    }
+    /** Number of writes still awaiting sync. */
+    async pending() {
+        return (await this.store.queued()).length;
+    }
+    /**
+     * Replay queued mutations in HLC order. Coalesces concurrent calls into a
+     * single in-flight drain. Stops on the first transient failure, leaving the
+     * remaining entries for the next attempt.
+     */
+    drain() {
+        if (this.draining)
+            return this.draining;
+        this.draining = this.runDrain().finally(() => {
+            this.draining = null;
+        });
+        return this.draining;
+    }
+    async runDrain() {
+        const entries = await this.store.queued();
+        for (const entry of entries) {
+            const replayer = this.replayers.get(entry.domain);
+            if (!replayer) {
+                // No handler registered (namespace not wired) — drop it rather
+                // than block the queue; nothing can ever replay it.
+                await this.store.dequeue(entry.seq);
+                continue;
+            }
+            try {
+                await replayer(entry);
+                await this.store.dequeue(entry.seq);
+                EventCore.emit(EventCoreEvents.SYNC_PROGRESS, {
+                    domain: entry.domain,
+                    method: entry.method,
+                });
+            }
+            catch (err) {
+                if (isPermanent(err)) {
+                    await this.store.dequeue(entry.seq);
+                    EventCore.emit(EventCoreEvents.SYNC_ERROR, {
+                        domain: entry.domain,
+                        method: entry.method,
+                        error: String(err?.message ?? err),
+                        dropped: true,
+                    });
+                    continue;
+                }
+                // Transient (offline again, 5xx) — keep the entry, stop here.
+                throw err;
+            }
+        }
+    }
+}
+/** A 4xx is the server permanently refusing the write; anything else is worth
+ *  retrying on the next reconnect. */
+function isPermanent(err) {
+    return err instanceof HttpError && err.status >= 400 && err.status < 500;
+}
+
+/**
+ * `SyncEngine` — orchestrates catch-up when the client comes back online. It's
+ * the thing wired to the {@link ConnectivityManager}'s offline→online edge.
+ *
+ * One `run()` does, in order:
+ *   1. **Guard** — only proceed when the session is authenticated and unlocked
+ *      (replays may need to re-seal/re-encrypt, and there's no point pushing
+ *      writes for a logged-out user).
+ *   2. **Drain** the durable {@link OutboundQueue} — push every offline write.
+ *   3. **Catch-up tasks** — domain-registered pulls that reconcile *inbound*
+ *      state we missed while offline (e.g. a Space paging history forward to its
+ *      last-seen handle). Registered by the namespaces.
+ *
+ * Concurrent triggers coalesce into a single in-flight run (a reconnect often
+ * fires several signals at once), mirroring `Client.recoverInFlight`.
+ */
+class SyncEngine {
+    deps;
+    catchUpTasks = new Set();
+    running = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Register an inbound reconciliation task run after the queue drains. */
+    registerCatchUp(task) {
+        this.catchUpTasks.add(task);
+        return () => this.catchUpTasks.delete(task);
+    }
+    /** Drain + catch up. Concurrent calls share one in-flight run. */
+    run() {
+        if (this.running)
+            return this.running;
+        this.running = this.execute().finally(() => {
+            this.running = null;
+        });
+        return this.running;
+    }
+    async execute() {
+        if (!this.deps.canSync())
+            return;
+        this.deps.connectivity.markSyncing();
+        try {
+            await this.deps.queue.drain();
+            for (const task of this.catchUpTasks) {
+                try {
+                    await task();
+                }
+                catch {
+                    // One domain's catch-up failing shouldn't abort the others
+                    // or wedge the sync; it'll retry on the next reconnect.
+                }
+            }
+            EventCore.emit(EventCoreEvents.SYNC_COMPLETE, {});
+        }
+        finally {
+            this.deps.connectivity.markSynced();
+        }
+    }
+}
+
+/**
+ * Errors specific to the offline layer.
+ */
+/**
+ * Thrown when an offline read/write needs the user's identity (to decrypt or
+ * re-encrypt cached data) but the client is locked — typically right after a
+ * reload, where only the session token was restored and `unlock()` hasn't run
+ * yet. Distinct from the generic "not signed in" identity error so apps can
+ * specifically prompt the user to unlock to see their offline data.
+ */
+class OfflineLockedError extends Error {
+    constructor(message = "Unlock required to access encrypted offline data. Call client.auth.zk.unlock(password).") {
+        super(message);
+        this.name = "OfflineLockedError";
+    }
+}
+
+/**
+ * `client.offline.snapshot` — a small, encrypted, app-state cache. Apps stash
+ * whatever they need to repaint instantly on a cold offline boot: the last open
+ * Space, a draft message, scroll position, the current route. It's deliberately
+ * separate from `client.kv`: snapshots are **local-only by default** (instant,
+ * never metered, never leave the device) and hold view state rather than domain
+ * data.
+ *
+ *   await client.offline.snapshot.save('ui', { route, openSpaceId, draft })
+ *   const ui = await client.offline.snapshot.load<UiState>('ui')
+ *
+ * Values are encrypted at rest with the same identity-derived {@link StorageCipher}
+ * as `client.kv`, so a snapshot is unreadable until the user unlocks — `load`
+ * returns `null` when locked or absent, and `save` throws {@link OfflineLockedError}.
+ * Conflict model is a single-writer LWW register (the latest save wins).
+ */
+class SnapshotNamespace {
+    deps;
+    cipher = null;
+    cipherIdentity = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Persist `state` under `name` (encrypted). No-op when offline support is off. */
+    async save(name, state) {
+        if (!this.deps.store.enabled)
+            return;
+        const envelope = await this.requireCipher().encrypt(state);
+        const record = {
+            envelope,
+            hlc: await this.deps.nextHlc(),
+            updatedAt: Date.now(),
+        };
+        await this.deps.store.put("snapshots", this.key(name), record);
+    }
+    /** Load and decrypt the snapshot `name`, or `null` if absent/locked. */
+    async load(name) {
+        if (!this.deps.store.enabled)
+            return null;
+        const record = await this.deps.store.get("snapshots", this.key(name));
+        if (!record)
+            return null;
+        if (!this.deps.session.isUnlocked)
+            return null;
+        return this.requireCipher().decrypt(record.envelope);
+    }
+    /** Remove the snapshot `name`. */
+    async delete(name) {
+        if (!this.deps.store.enabled)
+            return;
+        await this.deps.store.delete("snapshots", this.key(name));
+    }
+    /** Names of all snapshots for the current user. */
+    async list() {
+        if (!this.deps.store.enabled)
+            return [];
+        const prefix = `${this.commitment()}|`;
+        const rows = await this.deps.store.prefix("snapshots", prefix);
+        return rows.map((r) => r.key.slice(prefix.length));
+    }
+    key(name) {
+        return `${this.commitment()}|${name}`;
+    }
+    commitment() {
+        // Snapshots are scoped per user; before sign-in they share an "anon"
+        // bucket so pre-auth UI state (e.g. a chosen theme) still persists.
+        return this.deps.session.commitment ?? "anon";
+    }
+    requireCipher() {
+        if (!this.deps.session.isUnlocked)
+            throw new OfflineLockedError();
+        const identity = this.deps.session.requireIdentity();
+        if (this.cipher && this.cipherIdentity === identity)
+            return this.cipher;
+        this.cipher = new StorageCipher(identity.secretHex, identity.saltHex);
+        this.cipherIdentity = identity;
+        return this.cipher;
+    }
+}
+
+/**
+ * `ShardCache` — a Cache-API-backed store for file-shard bytes. Shards are
+ * content-addressed (the key IS the SHA-256 of the ciphertext), so caching them
+ * is uniquely safe: a cache hit is self-validating, immutable, and shareable
+ * across files. The Cache API (rather than IndexedDB) is the right home for
+ * large binary blobs — it streams, it's purpose-built for response bodies, and
+ * it has its own eviction.
+ *
+ * Keys are SYNTHETIC absolute URLs (`https://shard.muhkoo.local/<hash>`) rather
+ * than the real shard endpoint, so the cache is addressable by hash alone — the
+ * sync engine can re-PUT a deferred shard knowing only its hash, without
+ * reconstructing the accelerator URL. We never fetch these synthetic URLs; they
+ * exist only as cache keys.
+ *
+ * Every method degrades to a no-op / null where the Cache API is unavailable
+ * (Node, Workers, insecure contexts), so callers don't need to branch.
+ */
+const CACHE_NAME = "muhkoo-shards-v1";
+class ShardCache {
+    static available() {
+        try {
+            return typeof caches !== "undefined";
+        }
+        catch {
+            return false;
+        }
+    }
+    key(hash) {
+        return `https://shard.muhkoo.local/${encodeURIComponent(hash)}`;
+    }
+    open() {
+        return caches.open(CACHE_NAME);
+    }
+    /** Cached shard bytes, or `null` on miss / when unavailable. */
+    async get(hash) {
+        if (!ShardCache.available())
+            return null;
+        try {
+            const cache = await this.open();
+            const res = await cache.match(this.key(hash));
+            if (!res)
+                return null;
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Store shard bytes under their hash. Best-effort. */
+    async put(hash, bytes) {
+        if (!ShardCache.available())
+            return;
+        try {
+            const cache = await this.open();
+            await cache.put(this.key(hash), new Response(bytes, {
+                headers: { "content-type": "application/octet-stream" },
+            }));
+        }
+        catch {
+            /* quota / unavailable — degrade to online-only for this shard */
+        }
+    }
+    /** Whether a shard is present in the cache. */
+    async has(hash) {
+        if (!ShardCache.available())
+            return false;
+        try {
+            const cache = await this.open();
+            return Boolean(await cache.match(this.key(hash)));
+        }
+        catch {
+            return false;
+        }
+    }
+}
+
+/**
+ * IndexedDB schema for the offline layer — the single source of truth for the
+ * database name, version, and object stores. Bump {@link DB_VERSION} whenever
+ * the store set changes; {@link ./idb}'s `onupgradeneeded` creates any store
+ * that doesn't exist yet (additive migrations only — never drop
+ * `outbound-queue`, it holds un-synced writes).
+ *
+ * One database per origin. Records are partitioned *by key* (most keys are
+ * prefixed with the user's `commitment`) rather than by separate databases, so
+ * a single connection serves every signed-in user on the origin and prefix
+ * scans isolate a user's data.
+ */
+const DB_NAME = "muhkoo.offline";
+const DB_VERSION = 1;
+const STORES = [
+    { name: "kv-cache" },
+    { name: "db-row-cache" },
+    { name: "db-query-cache" },
+    { name: "space-messages" },
+    { name: "space-cursors" },
+    { name: "outbound-queue", autoIncrement: true, keyPath: "seq" },
+    { name: "snapshots" },
+    { name: "hlc-state" },
+    { name: "meta" },
+];
+/** Fixed keys in the `meta` store. */
+const META_NODE_ID = "nodeId";
+
+/**
+ * `OfflineManager` — the object `client.offline` points at, and the single
+ * owner of everything the offline layer needs at runtime: the {@link
+ * OfflineStore}, the {@link HLC} (Hybrid Logical Clock), the {@link
+ * ConnectivityManager}, the durable {@link OutboundQueue}, the {@link
+ * SyncEngine}, and the {@link SnapshotNamespace}.
+ *
+ * The {@link ../core/Client} constructs one of these (always — it's a cheap
+ * no-op when offline support is off) and hands the namespaces the small set of
+ * primitives they need to participate: `nextHlc()` to stamp a write,
+ * `observeHlc()` to fold in a remote stamp, `enqueue()` to record an offline
+ * mutation, and `registerReplayer()`/`registerCatchUp()` to define how their
+ * domain re-syncs on reconnect. Keeping that wiring here means the namespaces
+ * stay decoupled from IndexedDB and the clock.
+ */
+const HLC_STATE_KEY = "global";
+class OfflineManager {
+    /** True in browsers with IndexedDB; false when running over a NoopStore. */
+    enabled;
+    store;
+    connectivity;
+    queue;
+    sync;
+    /** `client.offline.snapshot` — encrypted app-state cache. */
+    snapshot;
+    /** Cache-API store for file-shard bytes (browser only). */
+    fileCache;
+    hlc = null;
+    nodeId = "";
+    bootPromise;
+    persistTimer = null;
+    constructor(deps) {
+        this.enabled = deps.enabled;
+        this.store = deps.store;
+        this.queue = new OutboundQueue(deps.store);
+        this.connectivity = new ConnectivityManager({
+            onReconnect: () => void this.sync.run(),
+        });
+        this.sync = new SyncEngine({
+            queue: this.queue,
+            connectivity: this.connectivity,
+            // Replays may need to re-seal/re-encrypt, and there's no point
+            // pushing a logged-out user's writes — gate on a usable session.
+            canSync: () => deps.session.isAuthenticated && deps.session.isUnlocked,
+        });
+        this.snapshot = new SnapshotNamespace({
+            store: deps.store,
+            session: deps.session,
+            nextHlc: () => this.nextHlc(),
+        });
+        if (this.enabled && ShardCache.available())
+            this.fileCache = new ShardCache();
+        this.bootPromise = this.boot();
+        if (this.enabled)
+            this.connectivity.start();
+    }
+    /**
+     * Queue a shard upload that couldn't reach the network. The bytes are
+     * already cached (keyed by `hash`), so only the hash is recorded; the file
+     * replayer re-PUTs from the cache on reconnect.
+     */
+    async deferShardUpload(hash) {
+        await this.enqueue({
+            hlc: await this.nextHlc(),
+            clientId: this.newClientId(),
+            domain: "file",
+            method: "putShard",
+            args: { hash },
+        });
+    }
+    /** Resolve once the clock + node id are loaded. */
+    ready() {
+        return this.bootPromise;
+    }
+    /** Current connectivity state (`online` | `offline` | `syncing`). */
+    get status() {
+        return this.connectivity.current;
+    }
+    /** Subscribe to connectivity changes. Returns an unsubscribe function. */
+    onStatusChange(cb) {
+        return this.connectivity.onChange(cb);
+    }
+    /** Stamp a locally-generated write with a fresh, monotonic HLC. */
+    async nextHlc() {
+        await this.bootPromise;
+        const stamp = this.hlc.now();
+        this.schedulePersist();
+        return stamp;
+    }
+    /** Fold an observed remote HLC into the clock (call for inbound stamps). */
+    async observeHlc(remote) {
+        await this.bootPromise;
+        this.hlc.update(unpack(remote));
+        this.schedulePersist();
+    }
+    /** A fresh client-generated id (idempotent replay / message dedupe). */
+    newClientId() {
+        return generateId();
+    }
+    /** Record an offline mutation for replay on reconnect. */
+    enqueue(entry) {
+        return this.queue.enqueue(entry);
+    }
+    /** A domain registers how to replay its queued mutations. */
+    registerReplayer(domain, replayer) {
+        this.queue.register(domain, replayer);
+    }
+    /** A domain registers an inbound catch-up task (run after the queue drains). */
+    registerCatchUp(task) {
+        return this.sync.registerCatchUp(task);
+    }
+    /** Surface a network failure to connectivity tracking. */
+    reportFetchFailure() {
+        this.connectivity.reportFetchFailure();
+    }
+    /** Surface a successful round-trip to connectivity tracking. */
+    reportFetchSuccess() {
+        this.connectivity.reportFetchSuccess();
+    }
+    /** Tear down listeners (tests / hot-reload). */
+    dispose() {
+        this.connectivity.stop();
+        if (this.persistTimer)
+            clearTimeout(this.persistTimer);
+    }
+    async boot() {
+        if (!this.enabled) {
+            // In-memory clock only; nothing is persisted over a NoopStore.
+            this.nodeId = generateId();
+            this.hlc = new HLC(this.nodeId);
+            return;
+        }
+        let nodeId = await this.store.get("meta", META_NODE_ID);
+        if (!nodeId) {
+            nodeId = generateId();
+            await this.store.put("meta", META_NODE_ID, nodeId);
+        }
+        this.nodeId = nodeId;
+        const state = await this.store.get("hlc-state", HLC_STATE_KEY);
+        this.hlc = new HLC(nodeId, { state });
+    }
+    /** Coalesce HLC-state writes — a burst of stamps persists once. */
+    schedulePersist() {
+        if (!this.enabled || this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            if (this.hlc)
+                void this.store.put("hlc-state", HLC_STATE_KEY, this.hlc.getState());
+        }, 200);
+    }
+}
+
+/**
+ * Environment probe deciding whether the offline layer turns itself on. Offline
+ * support is **on by default in browsers** and a no-op everywhere else, so this
+ * is the gate the {@link ../core/Client} consults to pick {@link
+ * ./store/IndexedDbStore} vs {@link ./store/NoopStore}.
+ *
+ * We require all three web APIs the layer leans on — `indexedDB` (structured
+ * cache + durable queue), the Cache API (file-shard bytes), and a `window`
+ * (so we're in a real document with online/offline events) — and we *touch*
+ * them inside a try/catch, because some sandboxed or private-mode contexts
+ * expose the globals but throw on use (mirrors `defaultSessionStore`).
+ */
+function isOfflineCapable() {
+    try {
+        return (typeof window !== "undefined" &&
+            typeof indexedDB !== "undefined" &&
+            typeof caches !== "undefined");
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * A ~thin promise wrapper over the raw IndexedDB API — just enough surface for
+ * {@link ./IndexedDbStore}: open-with-migration, get/put/delete, prefix and
+ * range cursor scans, autoincrement append, and clear. We hand-roll this rather
+ * than depend on `idb`/`dexie` because the access patterns are simple and
+ * `@muhkoo/connect` keeps its runtime dependency surface minimal.
+ *
+ * Everything here assumes a browser (or a `fake-indexeddb` test shim) — callers
+ * gate construction behind {@link ../detect}.
+ */
+function req(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/** Open (and migrate) the offline database. Creates any missing object store. */
+function openDatabase() {
+    return new Promise((resolve, reject) => {
+        const open = indexedDB.open(DB_NAME, DB_VERSION);
+        open.onupgradeneeded = () => {
+            const db = open.result;
+            for (const def of STORES) {
+                if (db.objectStoreNames.contains(def.name))
+                    continue;
+                db.createObjectStore(def.name, def.autoIncrement ? { keyPath: def.keyPath, autoIncrement: true } : undefined);
+            }
+        };
+        open.onsuccess = () => resolve(open.result);
+        open.onerror = () => reject(open.error);
+        // A blocked upgrade means another tab holds an older version open; let
+        // it surface as an error rather than hang forever.
+        open.onblocked = () => reject(new Error("offline DB upgrade blocked by another tab"));
+    });
+}
+/** Wraps an open connection with the typed operations the store needs. */
+class IdbConnection {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    tx(store, mode) {
+        return this.db.transaction(store, mode).objectStore(store);
+    }
+    get(store, key) {
+        return req(this.tx(store, "readonly").get(key)).then((v) => v ?? null);
+    }
+    async put(store, key, value) {
+        await req(this.tx(store, "readwrite").put(value, key));
+    }
+    async delete(store, key) {
+        await req(this.tx(store, "readwrite").delete(key));
+    }
+    async clear(store) {
+        await req(this.tx(store, "readwrite").clear());
+    }
+    /** Append to an autoincrement store; resolves with the generated key. */
+    async append(store, value) {
+        const key = await req(this.tx(store, "readwrite").add(value));
+        return key;
+    }
+    /** All entries whose string key falls in `[lower, upper)`, in key order. */
+    range(store, lower, upper) {
+        return this.scan(store, IDBKeyRange.bound(lower, upper, false, true));
+    }
+    /** All entries whose key starts with `prefix`, in key order. */
+    prefix(store, prefix) {
+        // "￿" is the largest BMP code unit, so `[prefix, prefix+￿)`
+        // bounds every key that begins with `prefix`.
+        return this.scan(store, IDBKeyRange.bound(prefix, prefix + "￿", false, true));
+    }
+    /** Every entry in the store, in key order. */
+    all(store) {
+        return this.scan(store, null);
+    }
+    scan(store, range) {
+        return new Promise((resolve, reject) => {
+            const out = [];
+            const cursorReq = this.tx(store, "readonly").openCursor(range ?? undefined);
+            cursorReq.onsuccess = () => {
+                const cursor = cursorReq.result;
+                if (!cursor)
+                    return resolve(out);
+                out.push({ key: String(cursor.key), value: cursor.value });
+                cursor.continue();
+            };
+            cursorReq.onerror = () => reject(cursorReq.error);
+        });
+    }
+}
+
+/**
+ * `IndexedDbStore` — the browser {@link OfflineStore}, backed by one IndexedDB
+ * database per origin (see {@link ./schema}). It opens lazily on first use and
+ * memoizes the connection. The queue methods sit on the autoincrement
+ * `outbound-queue` store and return mutations in HLC order for the sync engine.
+ *
+ * Construct only where `indexedDB` exists — {@link ../detect.isOfflineCapable}
+ * gates this, and the {@link ../../core/Client} falls back to {@link ./NoopStore}
+ * everywhere else.
+ */
+class IndexedDbStore {
+    enabled = true;
+    conn = null;
+    opening = null;
+    connect() {
+        if (this.conn)
+            return Promise.resolve(this.conn);
+        if (!this.opening) {
+            this.opening = openDatabase()
+                .then((db) => {
+                this.conn = new IdbConnection(db);
+                return this.conn;
+            })
+                .finally(() => {
+                this.opening = null;
+            });
+        }
+        return this.opening;
+    }
+    async ready() {
+        await this.connect();
+    }
+    async get(store, key) {
+        return (await this.connect()).get(store, key);
+    }
+    async put(store, key, value) {
+        await (await this.connect()).put(store, key, value);
+    }
+    async delete(store, key) {
+        await (await this.connect()).delete(store, key);
+    }
+    async prefix(store, prefix) {
+        return (await this.connect()).prefix(store, prefix);
+    }
+    async range(store, lower, upper) {
+        return (await this.connect()).range(store, lower, upper);
+    }
+    async all(store) {
+        return (await this.connect()).all(store);
+    }
+    async clear(store) {
+        await (await this.connect()).clear(store);
+    }
+    async enqueue(entry) {
+        // keyPath autoincrement writes the generated `seq` back into the record.
+        return (await this.connect()).append("outbound-queue", entry);
+    }
+    async dequeue(seq) {
+        await (await this.connect()).delete("outbound-queue", seq);
+    }
+    async queued() {
+        const rows = await (await this.connect()).all("outbound-queue");
+        return rows.map((r) => r.value).sort((a, b) => compareHlc(a.hlc, b.hlc));
+    }
+}
+
+/**
+ * `NoopStore` — the {@link OfflineStore} used wherever offline support is off
+ * (Node, Workers, SSR, or when a consumer disables it). Every read returns
+ * empty and every write is dropped, so the namespace hooks that call into it
+ * behave exactly as they did before the offline layer existed. `enabled` is
+ * `false` so hot paths can skip the call entirely.
+ */
+class NoopStore {
+    enabled = false;
+    async ready() { }
+    async get(_store, _key) {
+        return null;
+    }
+    async put(_store, _key, _value) { }
+    async delete(_store, _key) { }
+    async prefix(_store, _prefix) {
+        return [];
+    }
+    async range(_store, _lower, _upper) {
+        return [];
+    }
+    async all(_store) {
+        return [];
+    }
+    async clear(_store) { }
+    async enqueue(_entry) {
+        return -1;
+    }
+    async dequeue(_seq) { }
+    async queued() {
+        return [];
+    }
+}
+
+/**
+ * `LWWRegister` — a last-write-wins register CRDT, the conflict model for a
+ * `kv` value and for an app-state snapshot. A register holds a single value
+ * stamped with the {@link HlcTimestamp} of the write that produced it. Two
+ * concurrent writes converge to the one with the greater HLC; the loser is
+ * discarded. A delete is just a write that sets `deleted` (a tombstone), so a
+ * stale write that arrives after a newer delete can't resurrect the value.
+ *
+ * Because the HLC total-orders every write deterministically (down to a nodeId
+ * tiebreak), every replica that has seen the same set of writes lands on the
+ * same value — that's the convergence guarantee.
+ */
+/** An empty register that loses to any real write. */
+function emptyRegister() {
+    return { value: null, hlc: ZERO_HLC, deleted: true };
+}
+/**
+ * Merge two register states, returning the winner (greater HLC). Pure: neither
+ * input is mutated. Used identically on the inbound change feed and on
+ * sync-replay reconciliation so there's exactly one definition of "who wins".
+ */
+function mergeRegister(a, b) {
+    return compareHlc(a.hlc, b.hlc) >= 0 ? a : b;
+}
+/** Build the register produced by a `set`. */
+function writeRegister(value, hlc) {
+    return { value, hlc, deleted: false };
+}
+/** Build the register produced by a `delete` (a tombstone at `hlc`). */
+function deleteRegister(hlc) {
+    return { value: null, hlc, deleted: true };
+}
+
+/**
+ * `KvCache` — the offline adapter for `client.kv`. Stores each value's
+ * ciphertext envelope (never plaintext) under `${commitment}|${collection}/${id}`
+ * as an LWW-Register stamped with an HLC, so reads work offline and concurrent
+ * writes converge (see {@link ./crdt/LWWRegister}). Deletes are causal
+ * tombstones — a stale write can't resurrect a key a newer delete removed.
+ *
+ * True cross-device convergence also needs the accelerator to honor the HLC
+ * (see the server's `kvmeta` sidecar); this adapter embeds the stamp now and
+ * degrades gracefully (last-writer-by-arrival) until that ships.
+ */
+class KvCache {
+    manager;
+    store;
+    constructor(manager) {
+        this.manager = manager;
+        this.store = manager.store;
+    }
+    get enabled() {
+        return this.manager.enabled;
+    }
+    nextHlc() {
+        return this.manager.nextHlc();
+    }
+    newClientId() {
+        return this.manager.newClientId();
+    }
+    key(commitment, fullKey) {
+        return `${commitment}|${fullKey}`;
+    }
+    /** Read the cached register for `collection/id`, or null when absent. */
+    read(commitment, fullKey) {
+        return this.store.get("kv-cache", this.key(commitment, fullKey));
+    }
+    /** Optimistically record a local `set` (ciphertext envelope + HLC). */
+    async writeLocal(commitment, fullKey, envelope, hlc) {
+        await this.store.put("kv-cache", this.key(commitment, fullKey), writeRegister(envelope, hlc));
+    }
+    /** Optimistically record a local `delete` (tombstone at HLC). */
+    async deleteLocal(commitment, fullKey, hlc) {
+        await this.store.put("kv-cache", this.key(commitment, fullKey), deleteRegister(hlc));
+    }
+    /**
+     * Merge an authoritative value (from a GET refresh or a realtime frame) into
+     * the cache by HLC. When the server doesn't supply an HLC yet, treat it as
+     * "now-ish" by stamping our clock so a server value still beats stale local
+     * state but a fresh local write wins.
+     */
+    async mergeRemote(commitment, fullKey, envelope, op, hlc) {
+        const k = this.key(commitment, fullKey);
+        const incoming = op === "delete"
+            ? deleteRegister(hlc ?? (await this.nextHlc()))
+            : writeRegister(envelope, hlc ?? (await this.nextHlc()));
+        const local = (await this.store.get("kv-cache", k)) ?? emptyRegister();
+        await this.store.put("kv-cache", k, mergeRegister(local, incoming));
+    }
+    /** Non-tombstoned full keys for a commitment (used for offline `list`). */
+    async liveKeys(commitment) {
+        const prefix = `${commitment}|`;
+        const rows = await this.store.prefix("kv-cache", prefix);
+        return rows.filter((r) => !r.value.deleted).map((r) => r.key.slice(prefix.length));
+    }
+    /** Queue a kv mutation for replay on reconnect. */
+    async enqueue(method, args, hlc, clientId) {
+        await this.manager.enqueue({ hlc, clientId, domain: "kv", method, args });
+    }
+}
+
+/**
+ * `DbCache` — the offline adapter for `client.db`. Unlike kv, db rows are
+ * server-plaintext, so they're cached as-is. The SDK doesn't know a table's
+ * primary-key column, so it caches schema-agnostically:
+ *   - `get(id)` results keyed by the requested id (`${table}|row|${id}`),
+ *   - `query(q)` result pages keyed by a stable hash of the query.
+ *
+ * Writes carry per-column HLC stamps (`_hlc`) so the accelerator's per-column
+ * LWW merge can converge concurrent edits; offline writes are queued and
+ * replayed. Optimistic row patches keep `get` fresh between sync cycles.
+ */
+/** Stable JSON for query-cache keys (sorted object keys → deterministic). */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`)
+        .join(",")}}`;
+}
+class DbCache {
+    manager;
+    store;
+    constructor(manager) {
+        this.manager = manager;
+        this.store = manager.store;
+    }
+    get enabled() {
+        return this.manager.enabled;
+    }
+    nextHlc() {
+        return this.manager.nextHlc();
+    }
+    newClientId() {
+        return this.manager.newClientId();
+    }
+    /** Build the `{ [col]: hlc }` map for a write (one stamp across its columns). */
+    columnStamps(values, hlc) {
+        const out = {};
+        for (const col of Object.keys(values))
+            out[col] = hlc;
+        return out;
+    }
+    rowKey(table, id) {
+        return `${table}|row|${id}`;
+    }
+    queryKey(table, q) {
+        return `${table}|query|${stableStringify(q)}`;
+    }
+    async readRow(table, id) {
+        return this.store.get("db-row-cache", this.rowKey(table, id));
+    }
+    async writeRow(table, id, row) {
+        await this.store.put("db-row-cache", this.rowKey(table, id), row);
+    }
+    /** Shallow-merge a partial update into a cached row (optimistic). */
+    async patchRow(table, id, values) {
+        const existing = (await this.readRow(table, id)) ?? {};
+        await this.writeRow(table, id, { ...existing, ...values });
+    }
+    async deleteRow(table, id) {
+        await this.store.delete("db-row-cache", this.rowKey(table, id));
+    }
+    async readQuery(table, q) {
+        return this.store.get("db-query-cache", this.queryKey(table, q));
+    }
+    async writeQuery(table, q, page) {
+        await this.store.put("db-query-cache", this.queryKey(table, q), page);
+    }
+    async enqueue(method, args, hlc, clientId) {
+        await this.manager.enqueue({ hlc, clientId, domain: "db", method, args });
+    }
+}
+
 /**
  * `Client` — the single entry point to the Muhkoo SDK.
  *
@@ -8001,6 +9736,8 @@ class Client {
     agents;
     /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
     functions;
+    /** Offline cache + sync — `client.offline.status`, `client.offline.snapshot`, etc. */
+    offline;
     session;
     http;
     /** Subscribers notified when a session expires and can't be recovered. */
@@ -8020,11 +9757,40 @@ class Client {
         }
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.session = new SessionState(options.sessionStore ?? defaultSessionStore());
+        // Offline layer. On by default in browsers, a no-op (NoopStore) in Node,
+        // Workers, and SSR — so existing consumers are unaffected unless they're
+        // in a browser that can actually cache.
+        const offlineEnabled = options.offline?.enabled ?? isOfflineCapable();
+        const offlineStore = offlineEnabled
+            ? (options.offline?.store ?? new IndexedDbStore())
+            : new NoopStore();
+        this.offline = new OfflineManager({
+            store: offlineStore,
+            session: this.session,
+            enabled: offlineEnabled,
+        });
+        // Wrap fetch so every accelerator round-trip feeds the connectivity
+        // detector: a thrown fetch is the strongest "offline" signal, a 2xx the
+        // strongest "online" one. Only when offline support is active.
+        const baseFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+        const reportingFetch = offlineEnabled && baseFetch
+            ? async (input, init) => {
+                try {
+                    const res = await baseFetch(input, init);
+                    this.offline.reportFetchSuccess();
+                    return res;
+                }
+                catch (err) {
+                    this.offline.reportFetchFailure();
+                    throw err;
+                }
+            }
+            : options.fetch;
         this.http = new HttpClient({
             baseUrl: this.baseUrl,
             apiKey: options.apiKey,
             getSessionToken: () => this.session.token,
-            fetch: options.fetch,
+            fetch: reportingFetch,
             // Self-heal stale sessions: on a 401, try a silent re-auth (only
             // works while unlocked). If it can't, `recoverSession` fires the
             // session-expired event so the app can redirect to login.
@@ -8035,9 +9801,24 @@ class Client {
         const wsBaseUrl = toWsBase(this.baseUrl);
         const authBaseUrl = (options.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/+$/, "");
         this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session, authBaseUrl });
-        this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl });
-        this.db = new DbNamespace({ http: this.http });
-        this.storage = new StorageNamespace({ http: this.http, baseUrl: this.baseUrl, kv: this.kv });
+        const deferShardUpload = offlineEnabled
+            ? (hash) => this.offline.deferShardUpload(hash)
+            : undefined;
+        const kvCache = offlineEnabled ? new KvCache(this.offline) : undefined;
+        this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl, offline: kvCache });
+        if (offlineEnabled)
+            this.offline.registerReplayer("kv", (e) => this.kv.replay(e));
+        const dbCache = offlineEnabled ? new DbCache(this.offline) : undefined;
+        this.db = new DbNamespace({ http: this.http, offline: dbCache });
+        if (offlineEnabled)
+            this.offline.registerReplayer("db", (e) => this.db.replay(e));
+        this.storage = new StorageNamespace({
+            http: this.http,
+            baseUrl: this.baseUrl,
+            kv: this.kv,
+            shardCache: this.offline.fileCache,
+            deferShardUpload,
+        });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
         // by client.kv), so a returning member hydrates without a fresh keyring
@@ -8051,9 +9832,28 @@ class Client {
             session: this.session,
             wsBaseUrl,
             cache: spaceKeyCache,
+            offline: this.offline,
         });
         this.agents = new AgentsNamespace({ http: this.http });
         this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });
+        // Replay deferred shard uploads on reconnect. The bytes live in the
+        // Cache API keyed by hash; re-PUT them through a (defer-free) shard
+        // client so a failure surfaces as transient and the entry stays queued.
+        if (offlineEnabled && this.offline.fileCache) {
+            const replayShards = new ShardClient({
+                baseUrl: this.baseUrl,
+                pathPrefix: "/api/shards",
+                fetch: this.http.fetch,
+                cache: this.offline.fileCache,
+            });
+            this.offline.registerReplayer("file", async (entry) => {
+                const { hash } = entry.args;
+                const bytes = await this.offline.fileCache.get(hash);
+                if (!bytes)
+                    return; // evicted from cache — nothing to replay
+                await replayShards.putShard(hash, bytes);
+            });
+        }
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -8107,6 +9907,116 @@ class Client {
     }
 }
 
+/**
+ * `LWWMap` — a map of independent last-write-wins registers, one per column.
+ * This is the conflict model for a `db` row: two devices that edit *different*
+ * columns of the same row while offline both keep their edits (no lost update),
+ * and two that edit the *same* column converge to the greater-HLC write. A row
+ * delete is a causal tombstone (see {@link ./ORSet}); a later write to any
+ * column resurrects the row with just the surviving columns.
+ *
+ * This mirrors, on the client, exactly what the accelerator's `_muhkoo_crdt`
+ * sidecar does server-side — so a row materializes identically whether it was
+ * merged locally (offline) or by the server on replay.
+ */
+function emptyMap() {
+    return { fields: {}, columnHlc: {}, tombstone: null };
+}
+/** Apply a local column write (insert/update) at the given per-column HLCs. */
+function writeColumns(map, values, hlc) {
+    const next = {
+        fields: { ...map.fields },
+        columnHlc: { ...map.columnHlc },
+        tombstone: map.tombstone,
+    };
+    for (const [col, value] of Object.entries(values)) {
+        const prev = next.columnHlc[col];
+        if (!prev || compareHlc(hlc, prev) > 0) {
+            next.fields[col] = value;
+            next.columnHlc[col] = hlc;
+        }
+    }
+    return next;
+}
+/** Apply a row delete at `hlc` (causal tombstone). */
+function tombstoneRow(map, hlc) {
+    const tombstone = !map.tombstone || compareHlc(hlc, map.tombstone) > 0 ? hlc : map.tombstone;
+    return { fields: { ...map.fields }, columnHlc: { ...map.columnHlc }, tombstone };
+}
+/** Merge two row states column-by-column. Pure; neither input is mutated. */
+function mergeMap(a, b) {
+    const cols = new Set([...Object.keys(a.columnHlc), ...Object.keys(b.columnHlc)]);
+    const out = emptyMap();
+    for (const col of cols) {
+        const ah = a.columnHlc[col];
+        const bh = b.columnHlc[col];
+        const aWins = ah && (!bh || compareHlc(ah, bh) >= 0);
+        const winner = aWins ? a : b;
+        out.fields[col] = winner.fields[col];
+        out.columnHlc[col] = winner.columnHlc[col];
+    }
+    out.tombstone =
+        a.tombstone && b.tombstone
+            ? compareHlc(a.tombstone, b.tombstone) >= 0
+                ? a.tombstone
+                : b.tombstone
+            : (a.tombstone ?? b.tombstone);
+    return out;
+}
+/**
+ * Materialize the visible row from merged state, or `null` when the row is
+ * deleted. A column is visible only when its write is causally newer than the
+ * tombstone — so a delete hides every prior column, but a post-delete write to
+ * a column brings the row back with just that column populated.
+ */
+function materializeRow(map) {
+    const visible = {};
+    let any = false;
+    for (const [col, hlc] of Object.entries(map.columnHlc)) {
+        if (!map.tombstone || compareHlc(hlc, map.tombstone) > 0) {
+            visible[col] = map.fields[col];
+            any = true;
+        }
+    }
+    return any ? visible : null;
+}
+
+/**
+ * Tombstone helpers shared by the LWW CRDTs. We don't need a full
+ * observed-remove set — every domain that deletes (kv keys, db rows) does so
+ * by stamping a delete with an HLC and keeping that stamp around. The only
+ * rule that matters is the causal one:
+ *
+ *   a delete at HLC `d` hides the value, but a *later* write at HLC `w > d`
+ *   resurrects it; a *stale* write at `w <= d` is dropped.
+ *
+ * Keeping the delete HLC (rather than physically forgetting the key) is what
+ * prevents a delayed offline write from "un-deleting" something a peer already
+ * removed. Callers GC tombstones older than any possible offline window.
+ */
+/**
+ * Does a write at `writeHlc` win against a tombstone at `tombstoneHlc`?
+ * `true` ⇒ the write applies (resurrecting a deleted item if needed); `false`
+ * ⇒ the tombstone still holds and the write is dropped. A missing tombstone
+ * (`null`) means there's nothing suppressing the write.
+ */
+function writeBeatsTombstone(writeHlc, tombstoneHlc) {
+    if (!tombstoneHlc)
+        return true;
+    return compareHlc(writeHlc, tombstoneHlc) > 0;
+}
+/**
+ * Does a delete at `deleteHlc` win against the latest write at `writeHlc`?
+ * `true` ⇒ the item is now tombstoned. Ties go to the delete (remove-wins) so
+ * that a delete and a write stamped in the same instant resolve deterministically
+ * toward removal.
+ */
+function deleteBeatsWrite(deleteHlc, writeHlc) {
+    if (!writeHlc)
+        return true;
+    return compareHlc(deleteHlc, writeHlc) >= 0;
+}
+
 /**
  * Muhkoo app decorators — declare your app's agent-facing surface in code, then
  * "eject" a system prompt you hand to a Programmable Agent.
@@ -8814,5 +10724,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VERSION, VaultUnavailableError, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, serialize, shardHash, signMessage, toBase64$1 as toBase64, toBase64Url, toField, toHex, unsealSeed, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compareHlc, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isProvisional, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, serialize, shardHash, signMessage, stableStringify, toBase64$1 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map