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

package/dist/browser/index.js

@@ -1807,16 +1807,15 @@ class DoubleRatchetManager {
     }
     async registerZK(clientId, secret, salt, ecdsaPub) {
         await this._authenticator.initializeZK();
-        console.log(`Registering ZK for ${clientId}...`);
-        console.log('ECDSA Public Key:', ecdsaPub);
         const ecdsaJwk = await crypto.subtle.exportKey('jwk', ecdsaPub);
         const ecdsaHex = toHex(fromBase64Url(ecdsaJwk.x)).slice(0, 64);
         const ecdsaPubField = new Field(BigInt('0x' + ecdsaHex));
         const ecdsaPubHash = await Poseidon.hash([ecdsaPubField]);
         const commitment = await Poseidon.hash([secret, salt, ecdsaPubHash]);
-        console.log(`Commitment for ${clientId}:`, { commitment, salt });
         this.registeredUsers.set(clientId, { commitment, salt });
-        appLogger.debug(`Registered ${clientId}: commitment=${commitment.toString()}, salt=${salt.toString()}`);
+        // NB: never log `secret`, `salt`, or `commitment` — `salt` is a private
+        // witness for the ZK circuit and `commitment` is the user's stable id.
+        appLogger.debug(`Registered ZK identity for ${clientId}`);
     }
     async performHandshake(senderId, recipientId, zkProof, publicInput, clientPublicKey, // ECDH pub for session
     clientAuthPublicKey, // ECDSA pub for auth
@@ -2083,6 +2082,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
@@ -3805,6 +3812,8 @@ class ShardClient {
     baseUrl;
     pathPrefix;
     fetchFn;
+    cache;
+    deferUpload;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -3820,6 +3829,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) {
@@ -3833,12 +3844,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}`);
@@ -3858,8 +3886,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) {
@@ -3867,7 +3912,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
@@ -4892,7 +4940,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
@@ -4928,6 +4976,8 @@ class HttpError extends Error {
 }
 class HttpClient {
     baseUrl;
+    /** Origin of {@link baseUrl} — credentials are only attached same-origin. */
+    baseOrigin;
     apiKey;
     getSessionToken;
     onUnauthorized;
@@ -4936,6 +4986,12 @@ class HttpClient {
         if (!opts?.baseUrl)
             throw new Error("HttpClient: `baseUrl` is required");
         this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        try {
+            this.baseOrigin = new URL(this.baseUrl).origin;
+        }
+        catch {
+            this.baseOrigin = "";
+        }
         this.apiKey = opts.apiKey ?? null;
         this.getSessionToken = opts.getSessionToken ?? (() => null);
         this.onUnauthorized = opts.onUnauthorized ?? null;
@@ -4952,13 +5008,34 @@ class HttpClient {
      */
     fetch = (input, init) => {
         const headers = new Headers(init?.headers);
-        if (this.apiKey)
-            headers.set("X-Muhkoo-Key", this.apiKey);
-        const token = this.getSessionToken();
-        if (token)
-            headers.set("X-Muhkoo-Session", token);
+        // Only attach credentials when the request stays on the accelerator's
+        // origin. An absolute URL pointing elsewhere (e.g. a caller-supplied or
+        // server-reflected path that escapes `baseUrl`) must NOT receive the app
+        // key or session token, or it becomes a token-exfiltration vector.
+        if (this.isSameOrigin(input)) {
+            if (this.apiKey)
+                headers.set("X-Muhkoo-Key", this.apiKey);
+            const token = this.getSessionToken();
+            if (token)
+                headers.set("X-Muhkoo-Session", token);
+        }
         return this.fetchFn(input, { ...init, headers });
     };
+    /** True when `input` resolves to {@link baseOrigin} (relative URLs always do). */
+    isSameOrigin(input) {
+        try {
+            const urlStr = typeof input === "string" ? input
+                : input instanceof URL ? input.href
+                    : input.url;
+            // Relative URLs are resolved against baseUrl downstream → same origin.
+            if (!/^https?:\/\//i.test(urlStr))
+                return true;
+            return new URL(urlStr).origin === this.baseOrigin;
+        }
+        catch {
+            return true;
+        }
+    }
     // -------------------------------------------------------------------------
     // JSON convenience helpers (path is relative to baseUrl)
     // -------------------------------------------------------------------------
@@ -6233,30 +6310,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) {
@@ -6315,6 +6466,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 });
     }
@@ -6382,41 +6537,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 {
@@ -6432,7 +6655,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 });
+        }
     }
 }
 
@@ -6560,6 +6797,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;
@@ -6797,6 +7036,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;
@@ -6847,12 +7087,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) {
@@ -6899,7 +7146,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) {
@@ -6917,7 +7187,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}
@@ -6925,7 +7210,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) {
@@ -6986,8 +7309,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 };
     }
@@ -7054,6 +7390,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 });
     }
@@ -7072,9 +7410,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) {
@@ -7083,14 +7424,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") {
@@ -7126,12 +7474,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;
@@ -7151,7 +7504,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;
@@ -7169,8 +7522,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)
@@ -7182,6 +7536,7 @@ class Space {
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
                 handle,
+                clientId: packet.headers?.cid,
                 message,
             };
         }
@@ -7224,6 +7579,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 }));
     }
@@ -7243,6 +7654,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.
@@ -7737,6 +8160,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.
  *
@@ -7772,8 +8345,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
@@ -7934,7 +8525,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,
@@ -7943,7 +8534,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) {
@@ -8190,6 +8788,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.
  *
@@ -8242,6 +10005,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. */
@@ -8261,11 +10026,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.
@@ -8276,9 +10070,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
@@ -8292,9 +10101,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() {
@@ -8519,6 +10347,116 @@ function ejectAgentTools(appClass, opts) {
     };
 }
 
+/**
+ * `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;
+}
+
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
@@ -8585,5 +10523,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_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VaultUnavailableError, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, toField, unsealSeed, unwrapWithPassphrase, verify, 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_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, 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, 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, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map