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

package/dist/server/index.js

@@ -2130,6 +2130,14 @@ var EventCoreEvents;
     EventCoreEvents["MESSAGE"] = "message";
     EventCoreEvents["GET_HISTORY"] = "get_history";
     EventCoreEvents["RECEIVED_HISTORY"] = "received_history";
+    // Offline layer — connectivity + background sync lifecycle. Emitted by the
+    // ConnectivityManager / SyncEngine; apps subscribe to drive a status UI.
+    EventCoreEvents["ONLINE"] = "online";
+    EventCoreEvents["OFFLINE"] = "offline";
+    EventCoreEvents["SYNCING"] = "syncing";
+    EventCoreEvents["SYNC_PROGRESS"] = "sync_progress";
+    EventCoreEvents["SYNC_COMPLETE"] = "sync_complete";
+    EventCoreEvents["SYNC_ERROR"] = "sync_error";
 })(EventCoreEvents || (EventCoreEvents = {}));
 /**
  * @public
@@ -2968,7 +2976,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.7.0-alpha.4";
+const VERSION = "0.9.0-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -4630,30 +4638,104 @@ class KvNamespace {
     cipherIdentity = null;
     constructor(deps) {
         this.deps = deps;
+        // Replay queued kv writes on reconnect by re-issuing the original request.
+        if (deps.offline?.enabled) ;
+    }
+    /** Replay one queued kv mutation (called by the sync engine). */
+    async replay(entry) {
+        const a = entry.args;
+        if (entry.method === "set") {
+            await this.deps.http.post(this.kvPath(a.collection, a.id), { value: a.stored, hlc: a.hlc });
+        }
+        else {
+            await this.deps.http.del(this.kvPath(a.collection, a.id), { hlc: a.hlc });
+        }
     }
     /** Store `value` under `collection`/`id` (encrypted at rest by default). */
     async set(collection, id, value, opts) {
         const encrypt = opts?.encrypt !== false;
         const stored = encrypt ? await this.getCipher().encrypt(value) : value;
-        await this.deps.http.post(this.kvPath(collection, id), { value: stored });
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            await this.deps.http.post(this.kvPath(collection, id), { value: stored });
+            return;
+        }
+        const fullKey = `${collection}/${id}`;
+        const hlc = await offline.nextHlc();
+        await offline.writeLocal(this.commitment(), fullKey, stored, hlc);
+        try {
+            await this.deps.http.post(this.kvPath(collection, id), { value: stored, hlc });
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err; // server reachable + refused
+            await offline.enqueue("set", { collection, id, stored, hlc }, hlc, offline.newClientId());
+        }
     }
     /** Fetch the value at `collection`/`id`, or `null` if absent. */
     async get(collection, id) {
-        const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
-        return this.decode(res.value);
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
+            return this.decode(res.value);
+        }
+        const fullKey = `${collection}/${id}`;
+        try {
+            const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
+            // Refresh the cache from the authoritative read (merge by HLC).
+            await offline.mergeRemote(this.commitment(), fullKey, res.value ?? null, res.value == null ? "delete" : "set", res.hlc);
+            return this.decode(res.value);
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err; // a real server error, not offline
+            const entry = await offline.read(this.commitment(), fullKey);
+            if (!entry || entry.deleted)
+                return null;
+            return this.decode(entry.value);
+        }
     }
     /** Delete `collection`/`id`. Returns whether the key existed. */
     async delete(collection, id) {
-        const res = await this.deps.http.del(this.kvPath(collection, id), {});
-        return Boolean(res.existed);
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            const res = await this.deps.http.del(this.kvPath(collection, id), {});
+            return Boolean(res.existed);
+        }
+        const fullKey = `${collection}/${id}`;
+        const hlc = await offline.nextHlc();
+        await offline.deleteLocal(this.commitment(), fullKey, hlc);
+        try {
+            const res = await this.deps.http.del(this.kvPath(collection, id), { hlc });
+            return Boolean(res.existed);
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await offline.enqueue("delete", { collection, id, hlc }, hlc, offline.newClientId());
+            return true; // optimistic
+        }
     }
     /** List the ids present in `collection`. */
     async list(collection) {
-        const res = await this.deps.http.post(this.spacePath("/list"), {});
         const prefix = `${collection}/`;
-        return (res.keys ?? [])
-            .filter((k) => k.startsWith(prefix))
-            .map((k) => k.slice(prefix.length));
+        const offline = this.deps.offline;
+        const fromKeys = (keys) => keys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+        if (!offline?.enabled) {
+            const res = await this.deps.http.post(this.spacePath("/list"), {});
+            return fromKeys(res.keys ?? []);
+        }
+        try {
+            const res = await this.deps.http.post(this.spacePath("/list"), {});
+            // Union with cached live keys so un-synced offline creates still show.
+            const cached = await offline.liveKeys(this.commitment());
+            return [...new Set([...(res.keys ?? []), ...cached].filter((k) => k.startsWith(prefix)))].map((k) => k.slice(prefix.length));
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            return fromKeys(await offline.liveKeys(this.commitment()));
+        }
     }
     /** Reserved — server-side query is deferred (see the overhaul plan). */
     async query(_collection, _filter) {
@@ -4712,6 +4794,10 @@ class KvNamespace {
             return;
         const collection = frame.key.slice(0, slash);
         const id = frame.key.slice(slash + 1);
+        // Keep the offline cache warm from the realtime feed (merge by HLC).
+        if (this.deps.offline?.enabled) {
+            await this.deps.offline.mergeRemote(this.commitment(), frame.key, frame.op === "set" ? frame.value ?? null : null, frame.op, frame.hlc);
+        }
         const data = frame.op === "set" ? await this.decode(frame.value) : null;
         handler({ collection, id, type: frame.op, data });
     }
@@ -4779,41 +4865,109 @@ class KvNamespace {
 class DbTable {
     http;
     name;
-    constructor(http, name) {
+    offline;
+    constructor(http, name, offline) {
         this.http = http;
         this.name = name;
+        this.offline = offline;
     }
     base() {
         return `/api/db/${encodeURIComponent(this.name)}`;
     }
+    rowUrl(id) {
+        return `${this.base()}/${encodeURIComponent(String(id))}`;
+    }
     /** Insert a row. Returns the created row and its primary-key value. */
     async insert(values) {
-        return this.http.post(this.base(), { values });
+        if (!this.offline?.enabled)
+            return this.http.post(this.base(), { values });
+        const hlc = await this.offline.nextHlc();
+        const _hlc = this.offline.columnStamps(values, hlc);
+        try {
+            const res = await this.http.post(this.base(), { values, _hlc });
+            await this.offline.writeRow(this.name, String(res.id), res.row);
+            return res;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            // Offline: queue for replay. No server pk yet — return a provisional
+            // client id so the caller has a stable handle until sync.
+            const clientId = this.offline.newClientId();
+            await this.offline.enqueue("insert", { table: this.name, values, _hlc }, hlc, clientId);
+            return { row: values, id: clientId };
+        }
     }
     /** Fetch a row by primary key, or `null` if it doesn't exist. */
     async get(id) {
         try {
-            const res = await this.http.get(`${this.base()}/${encodeURIComponent(String(id))}`);
+            const res = await this.http.get(this.rowUrl(id));
+            if (this.offline?.enabled)
+                await this.offline.writeRow(this.name, String(id), res.row);
             return res.row;
         }
         catch (e) {
             if (e?.status === 404)
                 return null;
+            if (this.offline?.enabled && !(e instanceof HttpError)) {
+                return (await this.offline.readRow(this.name, String(id)));
+            }
             throw e;
         }
     }
     /** Query rows with filters, ordering, and keyset pagination. */
     async query(query = {}) {
-        return this.http.post(`${this.base()}/query`, query);
+        if (!this.offline?.enabled)
+            return this.http.post(`${this.base()}/query`, query);
+        try {
+            const res = await this.http.post(`${this.base()}/query`, query);
+            await this.offline.writeQuery(this.name, query, res);
+            return res;
+        }
+        catch (e) {
+            if (e instanceof HttpError)
+                throw e;
+            const cached = await this.offline.readQuery(this.name, query);
+            return cached ?? { rows: [], nextCursor: null };
+        }
     }
     /** Update a row by primary key. Returns the updated row. */
     async update(id, values) {
-        return this.http.patch(`${this.base()}/${encodeURIComponent(String(id))}`, { values });
+        if (!this.offline?.enabled)
+            return this.http.patch(this.rowUrl(id), { values });
+        const hlc = await this.offline.nextHlc();
+        const _hlc = this.offline.columnStamps(values, hlc);
+        await this.offline.patchRow(this.name, String(id), values); // optimistic
+        try {
+            const res = await this.http.patch(this.rowUrl(id), { values, _hlc });
+            await this.offline.writeRow(this.name, String(id), res.row);
+            return res;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await this.offline.enqueue("update", { table: this.name, id, values, _hlc }, hlc, this.offline.newClientId());
+            return { row: (await this.offline.readRow(this.name, String(id))) };
+        }
     }
     /** Delete a row by primary key. Returns the number of rows removed (0 or 1). */
     async delete(id) {
-        const res = await this.http.del(`${this.base()}/${encodeURIComponent(String(id))}`);
-        return res.deleted ?? 0;
+        if (!this.offline?.enabled) {
+            const res = await this.http.del(this.rowUrl(id));
+            return res.deleted ?? 0;
+        }
+        const hlc = await this.offline.nextHlc();
+        await this.offline.deleteRow(this.name, String(id)); // optimistic
+        try {
+            const res = await this.http.del(this.rowUrl(id), { _hlc: hlc });
+            return res.deleted ?? 0;
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            await this.offline.enqueue("delete", { table: this.name, id, hlc }, hlc, this.offline.newClientId());
+            return 1; // optimistic
+        }
     }
 }
 class DbNamespace {
@@ -4829,7 +4983,21 @@ class DbNamespace {
      *   const todos = client.db.table<Todo>('todos');
      */
     table(name) {
-        return new DbTable(this.deps.http, name);
+        return new DbTable(this.deps.http, name, this.deps.offline);
+    }
+    /** Replay one queued db mutation (called by the sync engine). */
+    async replay(entry) {
+        const a = entry.args;
+        const base = `/api/db/${encodeURIComponent(a.table)}`;
+        if (entry.method === "insert") {
+            await this.deps.http.post(base, { values: a.values, _hlc: a._hlc });
+        }
+        else if (entry.method === "update") {
+            await this.deps.http.patch(`${base}/${encodeURIComponent(String(a.id))}`, { values: a.values, _hlc: a._hlc });
+        }
+        else if (entry.method === "delete") {
+            await this.deps.http.del(`${base}/${encodeURIComponent(String(a.id))}`, { _hlc: a.hlc });
+        }
     }
 }
 
@@ -5293,6 +5461,9 @@ class ShardClient {
     baseUrl;
     pathPrefix;
     fetchFn;
+    cache;
+    deferUpload;
+    peers;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -5308,6 +5479,9 @@ 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;
+        this.peers = opts.peers;
     }
     /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
     urlForHash(hash) {
@@ -5321,12 +5495,32 @@ 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);
+        // Tell the swarm we now hold this block, so peers can pull it from us.
+        if (this.peers)
+            this.peers.announce(hash);
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method: "PUT",
+                headers: { "content-type": "application/octet-stream" },
+                // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
+                body: bytes,
+            });
+        }
+        catch (err) {
+            // Network unreachable (offline). If a defer hook is wired, queue the
+            // upload for replay and report success — the bytes are cached.
+            if (this.deferUpload) {
+                await this.deferUpload(hash);
+                return { dedup: false };
+            }
+            throw err;
+        }
         if (!response.ok) {
             const text = await safeText(response);
             throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
@@ -5346,8 +5540,41 @@ 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;
+        }
+        // Peers next: ask the Space swarm before spending origin egress. Peer
+        // blocks are hash-verified by the block engine; on miss/timeout we fall
+        // through to origin. Best-effort — never let a peer error block a read.
+        if (this.peers) {
+            try {
+                const fromPeer = await this.peers.getBlock(hash);
+                if (fromPeer) {
+                    if (this.cache)
+                        void this.cache.put(hash, fromPeer);
+                    return fromPeer;
+                }
+            }
+            catch {
+                /* peer layer hiccup — fall through to origin */
+            }
+        }
         const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, { method: "GET" });
+        let response;
+        try {
+            response = await this.fetchFn(url, { method: "GET" });
+        }
+        catch (err) {
+            // Offline with no cache hit: report the shard as missing so
+            // FileStorage's Reed–Solomon recovery can still reconstruct from the
+            // shards that ARE cached. Rethrow when there's no cache to fall back on.
+            if (this.cache)
+                return null;
+            throw err;
+        }
         if (response.status === 404)
             return null;
         if (!response.ok) {
@@ -5355,7 +5582,10 @@ class ShardClient {
             throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);
         }
         const buf = await response.arrayBuffer();
-        return new Uint8Array(buf);
+        const bytes = new Uint8Array(buf);
+        if (this.cache)
+            void this.cache.put(hash, bytes);
+        return bytes;
     }
     /**
      * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
@@ -5860,6 +6090,8 @@ class StorageNamespace {
                 baseUrl: this.deps.baseUrl,
                 pathPrefix: "/api/shards",
                 fetch: this.deps.http.fetch,
+                cache: this.deps.shardCache,
+                deferUpload: this.deps.deferShardUpload,
             });
         }
         return this._shards;
@@ -6556,6 +6788,9 @@ class Space {
     /** Per-instance event bus for fan-out events (isolated across spaces). */
     events = new EventTarget();
     rawWired = false;
+    catchUpUnsub = null;
+    /** Optional P2P swarm for this Space (block exchange among members). */
+    peerNet = null;
     constructor(deps) {
         this.deps = deps;
         this.name = deps.name;
@@ -6604,14 +6839,45 @@ class Space {
             if (this.deps.keyring) {
                 this.channel.on(BroadcastChannelEvents.CONNECTED, () => {
                     this.channel?.sendRaw({ name: this.deps.myId() });
+                    // Kick P2P peer discovery now the signaling channel is live
+                    // (re-runs on each reconnect to re-form the mesh).
+                    this.peerNet?.start();
                 });
                 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;
+        this.peerNet?.close();
+        this.peerNet = null;
+    }
+    /** Attach a P2P swarm so this Space's file reads/writes can use peers. */
+    attachPeerNetwork(net) {
+        this.peerNet = net;
+    }
+    /**
+     * Broadcast an app payload directly to connected Space peers over P2P,
+     * **bypassing the server** — for CRDT ops / high-frequency state (live
+     * cursors, presence, collaborative edits) you don't want to push through the
+     * relay. No-op when no P2P mesh is active (requires `client` `p2p`).
+     * Unlike {@link sendEphemeral} (server-relayed, metered, size-limited), this
+     * is peer-direct and fragments large payloads.
+     */
+    gossipToPeers(data) {
+        this.peerNet?.gossip(data);
+    }
+    /** Subscribe to peer gossip ({@link gossipToPeers}). Returns an unsubscribe fn. */
+    onPeerGossip(handler) {
+        return this.peerNet?.onGossip(handler) ?? (() => { });
     }
     /** Subscribe to a raw channel event. Buffered until `connect()` if early. */
     on(event, handler) {
@@ -6658,7 +6924,30 @@ class Space {
      * persisted `spaceMessage`. Requires a keyring.
      */
     async sendMessage(payload, opts = {}) {
-        this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
+        const offline = this.deps.offline;
+        if (!offline?.enabled) {
+            this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
+            return;
+        }
+        // Offline-aware path: stamp the message, cache it optimistically (so the
+        // UI can show it instantly via cachedMessages), then send if connected
+        // or durably queue it for replay on reconnect.
+        const clientId = offline.newClientId();
+        const hlc = await offline.nextHlc();
+        const packet = await this.sealMessage(payload, opts.channel, opts.contentType, clientId);
+        const frame = { spaceMessage: packet };
+        await offline.putMessage(this.id, {
+            handle: provisionalSpaceKey(clientId),
+            packet,
+            op: "msg",
+            clientId,
+            hlc,
+            pending: true,
+        });
+        if (this.isConnected())
+            this.sendRaw(frame);
+        else
+            await offline.enqueueFrame(this.id, frame, clientId, hlc);
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler) {
@@ -6676,7 +6965,22 @@ class Space {
      */
     async editMessage(handle, payload, opts = {}) {
         const spaceMessage = await this.sealMessage(payload, opts.channel, opts.contentType);
-        this.sendRaw({ editSpaceMessage: { ts: handle, spaceMessage } });
+        const frame = { editSpaceMessage: { ts: handle, spaceMessage } };
+        const offline = this.deps.offline;
+        if (offline?.enabled) {
+            await offline.putMessage(this.id, {
+                handle: padSpaceHandle(handle),
+                packet: spaceMessage,
+                op: "edit",
+                hlc: await offline.nextHlc(),
+            });
+            if (this.isConnected())
+                this.sendRaw(frame);
+            else
+                await offline.enqueueFrame(this.id, frame, offline.newClientId(), await offline.nextHlc());
+            return;
+        }
+        this.sendRaw(frame);
     }
     /**
      * Hard-delete a persisted message by its server {@link SpaceMessageEvent.handle}
@@ -6684,7 +6988,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) {
@@ -6705,10 +7047,12 @@ class Space {
      * indicators, presence, or live cursors are built on top of this. No-op if
      * the space isn't connected (ephemeral signals aren't worth queuing).
      */
-    sendEphemeral(subject, data) {
+    sendEphemeral(subject, data, to) {
         if (!this.isConnected())
             return;
-        this.sendRaw({ pub: { subject, data } });
+        // `to` (a member id) lets the server unicast a *directed* ephemeral
+        // instead of broadcasting; omitted ⇒ broadcast to the room (unchanged).
+        this.sendRaw({ pub: to ? { subject, data, to } : { subject, data } });
     }
     /** Subscribe to inbound ephemeral signals. `from` is the authenticated sender. */
     onEphemeral(handler) {
@@ -6745,8 +7089,21 @@ class Space {
         const messages = [];
         for (const raw of body.messages ?? []) {
             const decoded = await this.decodeFrame(raw, cipher);
-            if (decoded)
-                messages.push(decoded);
+            if (!decoded)
+                continue;
+            messages.push(decoded);
+            // Warm the offline cache with the inner sealed packet at its handle.
+            if (this.deps.offline?.enabled) {
+                try {
+                    const outer = JSON.parse(raw);
+                    if (typeof outer.spaceMessage === "string") {
+                        await this.cacheFrame(outer.spaceMessage, decoded, "msg");
+                    }
+                }
+                catch {
+                    /* unparseable history row — skip caching, still surfaced above */
+                }
+            }
         }
         return { messages, nextCursor: body.nextCursor ?? null };
     }
@@ -6813,6 +7170,9 @@ class Space {
             baseUrl: this.deps.httpBaseUrl,
             pathPrefix: "/api/shards",
             fetch: this.deps.fetch,
+            cache: this.deps.shardCache,
+            deferUpload: this.deps.deferShardUpload,
+            peers: this.peerNet?.exchange,
         });
         return new FileStorage({ shards });
     }
@@ -6831,9 +7191,12 @@ class Space {
         if (!f || typeof f !== "object")
             return;
         if (typeof f.spaceMessage === "string" && this.cipher) {
-            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, Number(f.timestamp ?? 0));
-            if (decoded)
+            const handle = Number(f.timestamp ?? 0);
+            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, handle);
+            if (decoded) {
                 this.emitEvent("message", decoded);
+                await this.cacheFrame(f.spaceMessage, decoded, "msg");
+            }
             return;
         }
         if (f.editSpaceMessage && typeof f.editSpaceMessage === "object" && this.cipher) {
@@ -6842,14 +7205,21 @@ class Space {
             const e = f.editSpaceMessage;
             if (typeof e.spaceMessage === "string") {
                 const decoded = await this.decodeFrame(e.spaceMessage, this.cipher, /*raw*/ true, Number(e.ts ?? 0));
-                if (decoded)
+                if (decoded) {
                     this.emitEvent("message-edited", decoded);
+                    await this.cacheFrame(e.spaceMessage, decoded, "edit");
+                }
             }
             return;
         }
         if (f.deleteSpaceMessage && typeof f.deleteSpaceMessage === "object") {
             const d = f.deleteSpaceMessage;
-            this.emitEvent("message-deleted", { handle: Number(d.ts ?? 0) });
+            const handle = Number(d.ts ?? 0);
+            this.emitEvent("message-deleted", { handle });
+            if (this.deps.offline?.enabled) {
+                await this.deps.offline.putDeleted(this.id, handle);
+                await this.deps.offline.observeHandle(this.id, handle);
+            }
             return;
         }
         if (f.pub && typeof f.pub === "object") {
@@ -6885,12 +7255,17 @@ class Space {
      * serialized `Packet` string. Shared by send (a new message) and edit
      * (replacement content for an existing handle). Requires a keyring.
      */
-    async sealMessage(payload, channel, contentType) {
+    async sealMessage(payload, channel, contentType, clientId) {
         const cipher = this.requireCipher(contentType);
         const message = new Message(payload);
         const headers = await cipher.seal(message.serialize());
         const source = this.deps.myId();
         const subject = channel ?? "default";
+        // Cleartext dedupe hint — lets the sender match its optimistic entry to
+        // the server echo. Not part of the signed canonical form (it carries no
+        // authority); worst case a stale hint just shows a transient duplicate.
+        if (clientId)
+            headers.cid = clientId;
         // Sign with our identity ECDSA key so receivers can verify authorship
         // end-to-end (independent of the relay's `source` stamp).
         const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
@@ -6910,7 +7285,7 @@ class Space {
      * the enclosing frame); false means `input` is the full
      * `{spaceMessage, name, timestamp}` frame and the handle is read from it.
      */
-    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0) {
+    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0, skipVerify = false) {
         try {
             let packetJson = input;
             let handle = serverTs;
@@ -6928,8 +7303,9 @@ class Space {
             // by `source`'s identity ECDSA key (looked up in the member
             // directory). Drop anything unsigned, signed by an unknown member,
             // or whose signature doesn't match — this defeats both member
-            // impersonation and a relay rewriting `source`.
-            if (!(await this.verifySender(packet)))
+            // impersonation and a relay rewriting `source`. Skipped only when
+            // re-reading from the local cache (already verified before caching).
+            if (!skipVerify && !(await this.verifySender(packet)))
                 return null;
             const serialized = await cipher.open(packet.headers);
             if (serialized === null)
@@ -6941,6 +7317,7 @@ class Space {
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
                 handle,
+                clientId: packet.headers?.cid,
                 message,
             };
         }
@@ -6983,6 +7360,62 @@ class Space {
         });
         return verifySpaceMessage(canonical, sig, key);
     }
+    /** Persist a decoded live/history/edit frame to the offline cache. */
+    async cacheFrame(packet, decoded, op) {
+        const offline = this.deps.offline;
+        if (!offline?.enabled)
+            return;
+        // An incoming real message supersedes any optimistic pending entry.
+        if (decoded.clientId)
+            await offline.dropPending(this.id, decoded.clientId);
+        await offline.putMessage(this.id, {
+            handle: padSpaceHandle(decoded.handle),
+            packet,
+            op,
+            clientId: decoded.clientId,
+        });
+        await offline.observeHandle(this.id, decoded.handle);
+    }
+    /**
+     * Inbound reconciliation run on reconnect: page the server's forward delta
+     * (`?since=<lastSeenHandle>`) to the head, pulling exactly the messages that
+     * landed while we were offline into the cache. Bounded so a long absence
+     * can't page forever. Falls back gracefully if the endpoint is unavailable.
+     */
+    async catchUp() {
+        const offline = this.deps.offline;
+        if (!offline?.enabled || !this.cipher)
+            return;
+        const cursor = await offline.getCursor(this.id);
+        let since = String(cursor?.lastSeenHandle ?? 0);
+        // Warm the member directory once so historical senders' signatures verify.
+        await this.deps.keyring?.refreshDirectory();
+        for (let page = 0; page < 50; page++) {
+            const url = `${this.deps.httpBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/history` +
+                `?since=${encodeURIComponent(since)}&limit=100`;
+            const res = await this.deps.fetch(url);
+            if (!res.ok)
+                break;
+            const body = (await res.json());
+            for (const raw of body.messages ?? []) {
+                const decoded = await this.decodeFrame(raw, this.cipher);
+                if (!decoded)
+                    continue;
+                try {
+                    const outer = JSON.parse(raw);
+                    if (typeof outer.spaceMessage === "string") {
+                        await this.cacheFrame(outer.spaceMessage, decoded, "msg");
+                    }
+                }
+                catch {
+                    /* unparseable row — skip */
+                }
+            }
+            if (!body.nextCursor)
+                break;
+            since = body.nextCursor;
+        }
+    }
     emitEvent(type, detail) {
         this.events.dispatchEvent(new CustomEvent(type, { detail }));
     }
@@ -7002,6 +7435,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.
@@ -7497,455 +7942,2573 @@ class KeyringClient {
 }
 
 /**
- * `client.space` — the fan-out group-encryption surface.
- *
- *   const space = await client.space.createSpace({ historyPolicy: "static" });
- *   await space.sendMessage({ text: "hello" });
- *   space.onMessage(e => …);
- *
- *   const joined = await client.space.joinSpace(space.id); // newcomer
- *
- * A space owns a client-generated keypair whose public key is its id, a
- * symmetric group key distributed server-blind via the keyring, and a
- * persisted message log. This namespace wires the {@link Space} handle to the
- * HTTP {@link KeyringClient}, the member's identity keys (from {@link KeyStore},
- * shared with the Double Ratchet path), and a PersonalSpace-backed key cache.
+ * 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.
  */
-/** Thrown by `joinChannel` when no channel with that name is registered. */
-class ChannelNotFoundError extends Error {
-    channelName;
-    constructor(channelName) {
-        super(`Channel "${channelName}" does not exist. Create it first.`);
-        this.channelName = channelName;
-        this.name = "ChannelNotFoundError";
-    }
+/** IndexedDB key for a message within a space. */
+function messageKey(spaceId, handle) {
+    return `${spaceId}|${handle}`;
 }
-/** Thrown by `createChannel` when the name is already registered. */
-class ChannelExistsError extends Error {
-    channelName;
-    constructor(channelName) {
-        super(`Channel "${channelName}" already exists.`);
-        this.channelName = channelName;
-        this.name = "ChannelExistsError";
+/**
+ * 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 };
 }
-class SpaceNamespace {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+
+/**
+ * `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,
+        });
     }
-    /**
-     * Create a new space: generate its keypair (public key = id), register
-     * metadata, mint the initial group key, and connect. Returns the open Space.
-     */
-    async createSpace(opts = {}) {
-        const historyPolicy = opts.historyPolicy ?? "static";
-        const identity = await generateSpaceIdentity();
-        // Register the space (server records pubkey + policy; the DO is lazy).
-        // For a private space the server also records the creator (this user) as
-        // its first member — so the metadata POST must carry the user session.
-        await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy, visibility: opts.private ? "private" : "public" });
-        const space = await this.build(identity.id, historyPolicy);
-        await space.create();
-        return space;
+    /** 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)));
     }
-    /** Join an existing space by id (its public key). Resolves once a key arrives. */
-    async joinSpace(spaceId, opts = {}) {
-        const policy = await this.fetchPolicy(spaceId);
-        const space = await this.build(spaceId, policy);
-        await space.join({ timeoutMs: opts.timeoutMs });
-        return space;
+    /** 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);
     }
-    /** A handle to a space without auto-connecting (uses cached keys on demand). */
-    async get(spaceId, historyPolicy = "static") {
-        return this.build(spaceId, historyPolicy);
+    async getCursor(spaceId) {
+        return this.store.get("space-cursors", spaceId);
     }
-    // -------------------------------------------------------------------------
-    // Channels — named, app-scoped pointers to spaces. The name → space-id
-    // directory is app-public config (server-readable, scoped to this app via
-    // its key); the channel CONTENTS stay fan-out E2E-encrypted. Lets chat use
-    // human room names (`general`) instead of raw pubkey ids.
-    // -------------------------------------------------------------------------
-    /** List this app's channels (name → space-id) for the key's environment. */
-    async listChannels() {
-        const body = await this.deps.http.get("/api/app/channels");
-        return body.channels ?? [];
+    /** 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 },
+        });
     }
-    /** Resolve a channel name to its space id, or null if it doesn't exist. */
-    async resolveChannel(name) {
+    /** Register an inbound catch-up task (forward/back history paging). */
+    registerCatchUp(task) {
+        return this.manager.registerCatchUp(task);
+    }
+}
+
+/**
+ * `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 {
-            const body = await this.deps.http.get(`/api/app/channels/${encodeURIComponent(name)}`);
-            return body.spaceId ?? null;
+            return typeof caches !== "undefined";
         }
-        catch (err) {
-            if (err instanceof HttpError && err.status === 404)
-                return null;
-            throw err;
+        catch {
+            return false;
         }
     }
-    /**
-     * Create a new channel: mint a fan-out space (the caller becomes its first
-     * key-holder) and register `name → spaceId` in the app directory. Throws
-     * {@link ChannelExistsError} if the name is already taken.
-     */
-    async createChannel(name, opts = {}) {
-        const space = await this.createSpace(opts);
-        // Register name → id first so a name clash doesn't leave an admitted keeper.
+    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 {
-            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id, visibility: opts.private ? "private" : "public" });
+            const cache = await this.open();
+            const res = await cache.match(this.key(hash));
+            if (!res)
+                return null;
+            return new Uint8Array(await res.arrayBuffer());
         }
-        catch (err) {
-            if (err instanceof HttpError && err.status === 409) {
-                throw new ChannelExistsError(name);
-            }
-            throw err;
+        catch {
+            return null;
         }
-        // Admit the app keeper so the channel is joinable with no member online.
-        // Best-effort: a channel still works (members admit each other) without it.
+    }
+    /** Store shard bytes under their hash. Best-effort. */
+    async put(hash, bytes) {
+        if (!ShardCache.available())
+            return;
         try {
-            const { pubkey } = await this.deps.http.get("/api/app/keeper");
-            if (pubkey && space.keyring)
-                await space.keyring.admit(KEEPER_MEMBER_ID, pubkey);
+            const cache = await this.open();
+            await cache.put(this.key(hash), new Response(bytes, {
+                headers: { "content-type": "application/octet-stream" },
+            }));
         }
-        catch (err) {
-            console.warn("[client.space] keeper admit failed (channel still usable):", err);
+        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;
+        }
+    }
+}
+
+/**
+ * `PeerExchange` — the thin façade the storage layer consults to try fetching a
+ * block from peers before falling back to origin. It satisfies the structural
+ * `PeerBlockSource` interface that {@link ../storage/transport/ShardClient}
+ * declares (so storage never imports the p2p module — the dependency arrow stays
+ * one-way, p2p → storage).
+ *
+ * It delegates to an {@link EngineHandle} — either an in-process {@link
+ * ./worker/blockEngine.BlockEngine} or the Web Worker proxy — so the same façade
+ * works whether the block engine runs on the main thread or off it.
+ */
+class PeerExchange {
+    engine;
+    timeoutMs;
+    constructor(engine, opts = {}) {
+        this.engine = engine;
+        this.timeoutMs = opts.timeoutMs ?? 2500;
+    }
+    getBlock(hash, opts) {
+        return this.engine.want(hash, opts?.timeoutMs ?? this.timeoutMs);
+    }
+    announce(hash) {
+        this.engine.announce(hash);
+    }
+}
+
+/**
+ * `SpaceSignaler` — WebRTC signaling carried over the Space's existing ephemeral
+ * relay. No new server channel: `Space.sendEphemeral`/`onEphemeral` already
+ * blind-relay `pub` frames stamped with the authenticated sender, so SDP
+ * offers/answers and ICE candidates ride a reserved subject (`__p2p__`) scoped
+ * to Space membership. The sender (`from`) is server-stamped and can't be
+ * spoofed; the payload is opaque to the server.
+ *
+ * Envelopes carry a `to` (a member id, or `"*"` for discovery) so the
+ * accelerator can optionally unicast peer-pair signaling instead of broadcasting
+ * (a small, backward-compatible `pub` enhancement); the client filters by `to`
+ * regardless.
+ */
+const P2P_SUBJECT = "__p2p__";
+class SpaceSignaler {
+    space;
+    myId;
+    constructor(space, myId) {
+        this.space = space;
+        this.myId = myId;
+    }
+    /** Send a signal to one peer (or `"*"`). */
+    send(to, kind, data) {
+        const env = { to, kind, data };
+        // Ask the server to unicast for a directed target; broadcast for "*".
+        // `to` also stays in the envelope so a broadcast-only server still works
+        // (the client filters by it).
+        this.space.sendEphemeral(P2P_SUBJECT, env, to !== "*" ? to : undefined);
+    }
+    /** Announce/withdraw P2P availability to all Space members. */
+    broadcast(kind, data) {
+        this.send("*", kind, data);
+    }
+    /**
+     * Subscribe to inbound signals addressed to us (or broadcast). Skips our own
+     * echoes. Returns an unsubscribe function.
+     */
+    onSignal(cb) {
+        return this.space.onEphemeral((e) => {
+            if (e.subject !== P2P_SUBJECT || e.from === this.myId)
+                return;
+            const env = e.data;
+            if (!env || typeof env.kind !== "string")
+                return;
+            if (env.to !== this.myId && env.to !== "*")
+                return;
+            cb(e.from, env.kind, env.data);
+        });
+    }
+}
+
+/**
+ * `WebRtcTransport` — a {@link ./PeerTransport.PeerTransport} over RTCDataChannels,
+ * signaled by {@link ../signaling/SpaceSignaler}. Runs on the **main thread**
+ * (`RTCPeerConnection` is Window-only — not available in Workers), so the block
+ * engine lives in a Worker and this only shuttles bytes.
+ *
+ * Connection setup uses a deterministic initiator (the peer with the smaller id
+ * dials) to avoid offer/answer glare. STUN handles NAT traversal; there is no
+ * TURN — an unreachable peer simply never connects and the caller falls back to
+ * origin (P2P is best-effort).
+ *
+ * Frames (up to a 4 MiB shard) exceed an RTCDataChannel's max message size, so
+ * each frame is fragmented into `CHUNK`-sized pieces with a 12-byte header
+ * `[msgId u32][index u32][total u32]` and reassembled per peer.
+ */
+const CHUNK = 16 * 1024;
+// [msgId u32][index u32][total u32][channel u32]
+const HEADER$1 = 16;
+/** Pause sends when a channel has this many bytes buffered (backpressure). */
+const MAX_BUFFERED = 4 * 1024 * 1024;
+const DEFAULT_ICE = [{ urls: "stun:stun.cloudflare.com:3478" }];
+class WebRtcTransport {
+    signaler;
+    myId;
+    conns = new Map();
+    msgCbs = new Set();
+    peerCbs = new Set();
+    offSignal;
+    iceServers;
+    maxPeers;
+    nextMsgId = 1;
+    constructor(signaler, myId, opts = {}) {
+        this.signaler = signaler;
+        this.myId = myId;
+        this.iceServers = opts.iceServers ?? DEFAULT_ICE;
+        this.maxPeers = opts.maxPeers ?? 8;
+        this.offSignal = this.signaler.onSignal((from, kind, data) => this.onSignal(from, kind, data));
+    }
+    peers() {
+        return [...this.conns].filter(([, c]) => c.dc?.readyState === "open").map(([id]) => id);
+    }
+    /** Dial a peer (no-op unless we're the deterministic initiator for the pair). */
+    connectTo(peerId) {
+        if (peerId === this.myId || this.conns.has(peerId))
+            return;
+        if (this.conns.size >= this.maxPeers)
+            return; // mesh cap
+        if (this.myId < peerId)
+            void this.initiate(peerId); // smaller id dials
+    }
+    send(peer, data, channel = 0) {
+        const dc = this.conns.get(peer)?.dc;
+        if (dc?.readyState === "open")
+            void this.sendFragmented(dc, data, channel);
+    }
+    broadcast(data, channel = 0) {
+        for (const [, c] of this.conns) {
+            if (c.dc?.readyState === "open")
+                void this.sendFragmented(c.dc, data, channel);
+        }
+    }
+    onMessage(cb) {
+        this.msgCbs.add(cb);
+        return () => this.msgCbs.delete(cb);
+    }
+    onPeerChange(cb) {
+        this.peerCbs.add(cb);
+        return () => this.peerCbs.delete(cb);
+    }
+    close() {
+        this.offSignal();
+        for (const [, c] of this.conns) {
+            try {
+                c.dc?.close();
+            }
+            catch { /* already closing */ }
+            try {
+                c.pc.close();
+            }
+            catch { /* already closing */ }
+        }
+        this.conns.clear();
+        this.msgCbs.clear();
+        this.peerCbs.clear();
+    }
+    // -- internals -----------------------------------------------------------
+    newPc(peerId) {
+        const pc = new RTCPeerConnection({ iceServers: this.iceServers });
+        const conn = { pc, reasm: new Map() };
+        this.conns.set(peerId, conn);
+        pc.onicecandidate = (e) => {
+            if (e.candidate)
+                this.signaler.send(peerId, "ice", e.candidate.toJSON());
+        };
+        pc.onconnectionstatechange = () => {
+            if (["failed", "closed", "disconnected"].includes(pc.connectionState))
+                this.drop(peerId);
+        };
+        pc.ondatachannel = (e) => this.bindChannel(peerId, conn, e.channel);
+        return conn;
+    }
+    async initiate(peerId) {
+        const conn = this.newPc(peerId);
+        const dc = conn.pc.createDataChannel("blocks");
+        this.bindChannel(peerId, conn, dc);
+        const offer = await conn.pc.createOffer();
+        await conn.pc.setLocalDescription(offer);
+        this.signaler.send(peerId, "offer", offer);
+    }
+    bindChannel(peerId, conn, dc) {
+        dc.binaryType = "arraybuffer";
+        conn.dc = dc;
+        dc.onopen = () => this.firePeerChange();
+        dc.onclose = () => this.drop(peerId);
+        dc.onmessage = (e) => this.onChunk(peerId, conn, new Uint8Array(e.data));
+    }
+    async onSignal(from, kind, data) {
+        if (kind === "offer") {
+            if (!this.conns.has(from) && this.conns.size >= this.maxPeers)
+                return; // mesh cap
+            const conn = this.conns.get(from) ?? this.newPc(from);
+            await conn.pc.setRemoteDescription(data);
+            const answer = await conn.pc.createAnswer();
+            await conn.pc.setLocalDescription(answer);
+            this.signaler.send(from, "answer", answer);
+        }
+        else if (kind === "answer") {
+            const conn = this.conns.get(from);
+            if (conn)
+                await conn.pc.setRemoteDescription(data);
+        }
+        else if (kind === "ice") {
+            const conn = this.conns.get(from);
+            if (conn && data) {
+                try {
+                    await conn.pc.addIceCandidate(data);
+                }
+                catch { /* pre-SRD race */ }
+            }
+        }
+        else if (kind === "bye") {
+            this.drop(from);
+        }
+    }
+    drop(peerId) {
+        const conn = this.conns.get(peerId);
+        if (!conn)
+            return;
+        this.conns.delete(peerId);
+        try {
+            conn.dc?.close();
+        }
+        catch { /* already closing */ }
+        try {
+            conn.pc.close();
+        }
+        catch { /* already closing */ }
+        this.firePeerChange();
+    }
+    firePeerChange() {
+        const peers = this.peers();
+        for (const cb of this.peerCbs)
+            cb(peers);
+    }
+    // -- fragmentation -------------------------------------------------------
+    async sendFragmented(dc, data, channel) {
+        const msgId = this.nextMsgId++ >>> 0;
+        const total = Math.max(1, Math.ceil(data.length / CHUNK));
+        for (let i = 0; i < total; i++) {
+            const slice = data.subarray(i * CHUNK, (i + 1) * CHUNK);
+            const frame = new Uint8Array(HEADER$1 + slice.length);
+            const dv = new DataView(frame.buffer);
+            dv.setUint32(0, msgId);
+            dv.setUint32(4, i);
+            dv.setUint32(8, total);
+            dv.setUint32(12, channel);
+            frame.set(slice, HEADER$1);
+            if (dc.bufferedAmount > MAX_BUFFERED)
+                await this.drain(dc);
+            dc.send(frame);
+        }
+    }
+    drain(dc) {
+        return new Promise((resolve) => {
+            dc.bufferedAmountLowThreshold = MAX_BUFFERED / 2;
+            const onLow = () => { dc.removeEventListener("bufferedamountlow", onLow); resolve(); };
+            dc.addEventListener("bufferedamountlow", onLow);
+        });
+    }
+    onChunk(peerId, conn, frame) {
+        if (frame.length < HEADER$1)
+            return;
+        const dv = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+        const msgId = dv.getUint32(0);
+        const index = dv.getUint32(4);
+        const total = dv.getUint32(8);
+        const channel = dv.getUint32(12);
+        const chunk = frame.slice(HEADER$1);
+        let r = conn.reasm.get(msgId);
+        if (!r) {
+            r = { chunks: new Array(total), received: 0, total, size: 0, channel };
+            conn.reasm.set(msgId, r);
+        }
+        if (r.chunks[index])
+            return; // dup
+        r.chunks[index] = chunk;
+        r.received++;
+        r.size += chunk.length;
+        if (r.received < r.total)
+            return;
+        conn.reasm.delete(msgId);
+        const out = new Uint8Array(r.size);
+        let off = 0;
+        for (const c of r.chunks) {
+            if (!c)
+                return; // gap — shouldn't happen on reliable ordered
+            out.set(c, off);
+            off += c.length;
+        }
+        for (const cb of this.msgCbs)
+            cb(peerId, out, r.channel);
+    }
+}
+
+/**
+ * `PeerTransport` — the pluggable wire under the block engine. It moves opaque
+ * frames between Space peers; it knows nothing about blocks, hashes, or the
+ * protocol. {@link ./WebRtcTransport} implements it over RTCDataChannels today;
+ * a future libp2p/Helia transport can implement the same interface without the
+ * block engine or `ShardClient` changing.
+ *
+ * Implementations are responsible for fragmenting/ reassembling frames larger
+ * than the underlying channel's max message size (a 4 MiB shard won't fit in one
+ * `RTCDataChannel.send`); the engine always deals in whole frames.
+ */
+/**
+ * Logical channels multiplexed over the one data link. `0` is block exchange
+ * (the engine), `1` is gossip (app/CRDT data). The tag rides the framing header
+ * so payloads aren't copied to prepend it.
+ */
+const CHANNEL_BLOCK = 0;
+const CHANNEL_GOSSIP = 1;
+
+/**
+ * Bitswap-lite wire protocol for peer block exchange. Four frame types over a
+ * {@link ../transport/PeerTransport} data channel:
+ *
+ *   WANT(hash)         — "does anyone have this block?" / "send it to me"
+ *   HAVE(hash)         — "I hold this block" (announce / reply to a WANT)
+ *   BLOCK(hash, bytes) — the block itself (verified by hash on receipt)
+ *   CANCEL(hash)       — "stop, I got it elsewhere"
+ *
+ * Frames are compact binary so a 4 MiB shard isn't base64-bloated through JSON:
+ *
+ *   byte 0      : type (0 WANT | 1 HAVE | 2 BLOCK | 3 CANCEL)
+ *   bytes 1..33 : 32-byte raw SHA-256 of the block (our shard hash, hex-decoded)
+ *   bytes 33..  : payload (BLOCK only)
+ *
+ * Blocks are AES-GCM ciphertext, so a frame carries nothing readable; the hash
+ * is the capability check (the receiver re-hashes the payload and drops a
+ * mismatch). See {@link ./blockEngine}.
+ */
+var FrameType;
+(function (FrameType) {
+    FrameType[FrameType["WANT"] = 0] = "WANT";
+    FrameType[FrameType["HAVE"] = 1] = "HAVE";
+    FrameType[FrameType["BLOCK"] = 2] = "BLOCK";
+    FrameType[FrameType["CANCEL"] = 3] = "CANCEL";
+})(FrameType || (FrameType = {}));
+const HASH_BYTES = 32;
+const HEADER = 1 + HASH_BYTES; // type + hash
+function hexToBytes(hex) {
+    if (hex.length !== HASH_BYTES * 2) {
+        throw new Error(`protocol: expected a ${HASH_BYTES}-byte hex hash, got ${hex.length / 2} bytes`);
+    }
+    const out = new Uint8Array(HASH_BYTES);
+    for (let i = 0; i < HASH_BYTES; i++)
+        out[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return out;
+}
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+function bytesToHex(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++)
+        s += HEX[bytes[i]];
+    return s;
+}
+function header(type, hash, extra = 0) {
+    const buf = new Uint8Array(HEADER + extra);
+    buf[0] = type;
+    buf.set(hexToBytes(hash), 1);
+    return { buf, offset: HEADER };
+}
+function encodeWant(hash) {
+    return header(FrameType.WANT, hash).buf;
+}
+function encodeHave(hash) {
+    return header(FrameType.HAVE, hash).buf;
+}
+function encodeCancel(hash) {
+    return header(FrameType.CANCEL, hash).buf;
+}
+function encodeBlock(hash, payload) {
+    const { buf, offset } = header(FrameType.BLOCK, hash, payload.length);
+    buf.set(payload, offset);
+    return buf;
+}
+function decode(frame) {
+    if (frame.length < HEADER)
+        throw new Error("protocol: frame too short");
+    const type = frame[0];
+    const hash = bytesToHex(frame.subarray(1, HEADER));
+    if (type === FrameType.BLOCK) {
+        // Copy the payload out so it doesn't alias a transferred/pooled buffer.
+        return { type, hash, payload: frame.slice(HEADER) };
+    }
+    return { type, hash };
+}
+
+var protocol = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    get FrameType () { return FrameType; },
+    decode: decode,
+    encodeBlock: encodeBlock,
+    encodeCancel: encodeCancel,
+    encodeHave: encodeHave,
+    encodeWant: encodeWant
+});
+
+/**
+ * `BlockEngine` — the bitswap-lite want/have ledger. Host-agnostic: it speaks
+ * only to a {@link BlockStore} (get/put/has) and an `out` sink that ships
+ * encoded frames to a peer (or `"*"` to broadcast). The host wires `out` and
+ * `handleFrame` to a real transport — on the main thread or inside the Web
+ * Worker (see {@link ./engineClient}) — so this class is pure and unit-testable.
+ *
+ * It never sees keys: blocks are AES-GCM ciphertext, addressed by SHA-256. The
+ * one trust check is integrity — an inbound BLOCK is re-hashed and dropped on
+ * mismatch, so a malicious peer can't poison the store (the requester just
+ * falls back to origin).
+ */
+class BlockEngine {
+    store;
+    out;
+    hash;
+    wants = new Map();
+    constructor(store, out, hash) {
+        this.store = store;
+        this.out = out;
+        this.hash = hash;
+    }
+    /**
+     * Ask the swarm for a block. Resolves with the verified bytes, or `null` on
+     * timeout (caller then falls back to origin). Returns immediately if we
+     * already hold it; concurrent wants for the same hash share one request.
+     */
+    want(hash, timeoutMs) {
+        return new Promise((resolve) => {
+            void this.store.get(hash).then((local) => {
+                if (local)
+                    return resolve(local);
+                const existing = this.wants.get(hash);
+                if (existing) {
+                    existing.resolvers.push(resolve);
+                    return;
+                }
+                const timer = setTimeout(() => {
+                    const w = this.wants.get(hash);
+                    this.wants.delete(hash);
+                    this.out("*", encodeCancel(hash));
+                    w?.resolvers.forEach((r) => r(null));
+                }, timeoutMs);
+                this.wants.set(hash, { resolvers: [resolve], timer });
+                this.out("*", encodeWant(hash));
+            });
+        });
+    }
+    /** Tell the swarm we now hold `hash` (so peers wanting it can pull from us). */
+    announce(hash) {
+        this.out("*", encodeHave(hash));
+    }
+    /** Handle one inbound frame from `peer`. */
+    async handleFrame(peer, frame) {
+        let f;
+        try {
+            f = decode(frame);
+        }
+        catch {
+            return; // malformed — ignore
+        }
+        switch (f.type) {
+            case FrameType.WANT: {
+                const bytes = await this.store.get(f.hash);
+                if (bytes)
+                    this.out(peer, encodeBlock(f.hash, bytes));
+                return;
+            }
+            case FrameType.HAVE: {
+                // A peer announced a block we're still waiting for → pull from them.
+                if (this.wants.has(f.hash))
+                    this.out(peer, encodeWant(f.hash));
+                return;
+            }
+            case FrameType.BLOCK: {
+                const pending = this.wants.get(f.hash);
+                if (!pending || !f.payload)
+                    return; // unsolicited / empty — ignore
+                // Integrity: a peer can't poison the store. Drop a mismatch and
+                // keep waiting (the timeout will fall back to origin).
+                const got = await this.hash(f.payload);
+                if (got !== f.hash)
+                    return;
+                await this.store.put(f.hash, f.payload);
+                this.wants.delete(f.hash);
+                clearTimeout(pending.timer);
+                this.out("*", encodeCancel(f.hash)); // others can stop sending
+                pending.resolvers.forEach((r) => r(f.payload));
+                return;
+            }
+            case FrameType.CANCEL:
+                // We serve WANTs synchronously, so there's nothing in flight to
+                // cancel yet. Reserved for chunked-send cancellation later.
+                return;
+        }
+    }
+    /** Drop all pending waits (resolve null) — on teardown. */
+    close() {
+        for (const [, w] of this.wants) {
+            clearTimeout(w.timer);
+            w.resolvers.forEach((r) => r(null));
+        }
+        this.wants.clear();
+    }
+}
+
+/**
+ * `EngineHost` — the boundary {@link ../PeerNetwork} wires a transport to. It
+ * abstracts *where* the {@link ./blockEngine.BlockEngine} runs:
+ *   - {@link LocalEngineHost} runs it on the calling thread (tests, or a
+ *     fallback when the Web Worker can't be built by a consumer's bundler);
+ *   - the Worker proxy ({@link ./engineClient}) runs it off-thread.
+ *
+ * Either way the host exposes the same surface: drive `want`/`announce`, feed it
+ * inbound frames via `handleFrame`, and receive its outbound frames via
+ * `onOutbound` (which the network forwards to the transport).
+ */
+/** Runs the engine in-process (main thread or test). */
+class LocalEngineHost {
+    engine;
+    cbs = new Set();
+    constructor(store, hasher) {
+        this.engine = new BlockEngine(store, (target, frame) => {
+            for (const cb of this.cbs)
+                cb(target, frame);
+        }, hasher);
+    }
+    want(hash, timeoutMs) {
+        return this.engine.want(hash, timeoutMs);
+    }
+    announce(hash) {
+        this.engine.announce(hash);
+    }
+    handleFrame(peer, frame) {
+        void this.engine.handleFrame(peer, frame);
+    }
+    onOutbound(cb) {
+        this.cbs.add(cb);
+        return () => this.cbs.delete(cb);
+    }
+    close() {
+        this.engine.close();
+        this.cbs.clear();
+    }
+}
+
+/**
+ * `WorkerEngineHost` — the main-thread proxy to a {@link ./blockEngine.BlockEngine}
+ * running inside a dedicated Web Worker (so hashing, blockstore I/O, and the
+ * protocol codec stay off the main thread). It speaks the small message protocol
+ * in {@link ./blockEngine.worker} and satisfies {@link ./engineHost.EngineHost},
+ * so {@link ../PeerNetwork} treats it identically to the in-process host.
+ *
+ * Block bytes cross the worker boundary as **transferable** ArrayBuffers
+ * (zero-copy). Only encrypted blocks ever cross — keys never enter the worker.
+ */
+class WorkerEngineHost {
+    worker;
+    wants = new Map();
+    cbs = new Set();
+    nextId = 1;
+    constructor(worker) {
+        this.worker = worker;
+        this.worker.onmessage = (e) => {
+            const m = e.data;
+            if (m.t === "out") {
+                const frame = new Uint8Array(m.data);
+                for (const cb of this.cbs)
+                    cb(m.target, frame);
+            }
+            else if (m.t === "want-result") {
+                const resolve = this.wants.get(m.id);
+                if (resolve) {
+                    this.wants.delete(m.id);
+                    resolve(m.data ? new Uint8Array(m.data) : null);
+                }
+            }
+        };
+    }
+    want(hash, timeoutMs) {
+        return new Promise((resolve) => {
+            const id = this.nextId++;
+            this.wants.set(id, resolve);
+            this.worker.postMessage({ t: "want", id, hash, timeout: timeoutMs });
+        });
+    }
+    announce(hash) {
+        this.worker.postMessage({ t: "announce", hash });
+    }
+    handleFrame(peer, frame) {
+        // Transfer an exact-size buffer; copy if the view doesn't own the whole buffer.
+        const buf = frame.byteOffset === 0 && frame.byteLength === frame.buffer.byteLength
+            ? frame.buffer
+            : frame.slice().buffer;
+        this.worker.postMessage({ t: "frame", peer, data: buf }, [buf]);
+    }
+    onOutbound(cb) {
+        this.cbs.add(cb);
+        return () => this.cbs.delete(cb);
+    }
+    close() {
+        try {
+            this.worker.postMessage({ t: "close" });
+        }
+        catch { /* already gone */ }
+        this.worker.terminate();
+        this.wants.forEach((r) => r(null));
+        this.wants.clear();
+        this.cbs.clear();
+    }
+}
+
+/**
+ * `PeerNetwork` — the per-Space orchestrator that ties the pieces together on
+ * the main thread:
+ *
+ *   transport (WebRTC)  ⇄  engine host (Worker or in-process)  →  PeerExchange
+ *        ▲                                                            │
+ *        └────────────── signaling over the Space relay ─────────────┘
+ *
+ * It owns one {@link ./transport/WebRtcTransport} + one {@link
+ * ./worker/engineHost.EngineHost}, wires inbound frames to the engine and the
+ * engine's outbound frames back to the transport, runs peer discovery over the
+ * Space's ephemeral channel, and exposes a {@link ./PeerExchange.PeerExchange}
+ * for `ShardClient` to consult. Scope is one Space (private swarm).
+ *
+ * `engineHost` defaults to in-process; pass `workerFactory` to run the block
+ * engine off the main thread (the consumer's bundler resolves the worker URL).
+ */
+/**
+ * Build the engine host, preferring an off-thread Web Worker:
+ *   1. an explicit `workerFactory` (most reliable in app bundlers), else
+ *   2. the bundled worker resolved relative to this module (works where the
+ *      bundler supports `new Worker(new URL(...))`, e.g. Vite builds), else
+ *   3. the in-process engine (always works; tests + non-worker runtimes).
+ * Any worker construction failure degrades to in-process.
+ */
+function buildEngineHost(opts) {
+    try {
+        const worker = opts.workerFactory ? opts.workerFactory() : defaultWorker();
+        if (worker)
+            return new WorkerEngineHost(worker);
+    }
+    catch {
+        /* no Worker global / bundler can't resolve it → in-process */
+    }
+    return new LocalEngineHost(opts.store ?? new ShardCache(), shardHash);
+}
+/** Construct the bundled worker if the runtime + bundler support it, else null. */
+function defaultWorker() {
+    try {
+        if (typeof Worker === "undefined")
+            return null;
+        // The string is resolved by the consumer's bundler relative to the
+        // built connect module (sibling of dist/browser/index.js).
+        return new Worker(new URL("./blockEngine.worker.js", import.meta.url), { type: "module" });
+    }
+    catch {
+        return null;
+    }
+}
+class PeerNetwork {
+    /** Pass this to a `ShardClient` as `peers`. */
+    exchange;
+    transport;
+    host;
+    signaler;
+    offs = [];
+    gossipCbs = new Set();
+    closed = false;
+    constructor(opts) {
+        this.signaler = new SpaceSignaler(opts.space, opts.myId);
+        this.transport =
+            opts.transport ??
+                new WebRtcTransport(this.signaler, opts.myId, {
+                    iceServers: opts.iceServers,
+                    maxPeers: opts.maxPeers,
+                });
+        this.host = buildEngineHost(opts);
+        // Wire transport ⇄ engine, demuxing block (engine) from gossip (app).
+        this.offs.push(this.transport.onMessage((peer, data, channel) => {
+            if (channel === CHANNEL_GOSSIP) {
+                for (const cb of this.gossipCbs)
+                    cb(peer, data);
+            }
+            else {
+                this.host.handleFrame(peer, data);
+            }
+        }));
+        this.offs.push(this.host.onOutbound((target, frame) => target === "*"
+            ? this.transport.broadcast(frame, CHANNEL_BLOCK)
+            : this.transport.send(target, frame, CHANNEL_BLOCK)));
+        // Discovery: a broadcast hello triggers a unicast hello back (so a
+        // newcomer learns existing members); both sides connectTo (the smaller
+        // id actually dials). Deterministic + idempotent.
+        this.offs.push(this.signaler.onSignal((from, kind, data) => {
+            if (kind !== "hello")
+                return;
+            this.transport.connectTo?.(from);
+            if (data?.broadcast) {
+                this.signaler.send(from, "hello", { broadcast: false });
+            }
+        }));
+        this.exchange = new PeerExchange(this.host, { timeoutMs: opts.timeoutMs });
+    }
+    /**
+     * Begin peer discovery — broadcast a hello so existing members dial us and
+     * we learn them. Call once the signaling channel is live (the Space fires
+     * this on CONNECTED); safe to call again on reconnect.
+     */
+    start() {
+        if (this.closed)
+            return;
+        this.signaler.broadcast("hello", { broadcast: true });
+    }
+    /**
+     * Broadcast an app payload to all connected peers over the gossip channel —
+     * a direct, server-bypassing data path for CRDT ops / high-frequency state
+     * (cursors, presence, collaborative edits). Single-hop (no re-forwarding).
+     */
+    gossip(data) {
+        this.transport.broadcast(data, CHANNEL_GOSSIP);
+    }
+    /** Subscribe to gossip from peers. Returns an unsubscribe function. */
+    onGossip(cb) {
+        this.gossipCbs.add(cb);
+        return () => this.gossipCbs.delete(cb);
+    }
+    /** Connected peer count (open data channels). */
+    peerCount() {
+        return this.transport.peers().length;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.signaler.broadcast("bye");
+        }
+        catch { /* socket may be gone */ }
+        for (const off of this.offs)
+            off();
+        this.transport.close();
+        this.host.close();
+    }
+}
+
+/**
+ * Whether this environment can do WebRTC peering. `RTCPeerConnection` is
+ * Window-only (absent in Node/Workers/SSR), so this gates whether a
+ * {@link ./PeerNetwork} can be built at all.
+ */
+function isP2pCapable() {
+    try {
+        return typeof RTCPeerConnection !== "undefined";
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * `client.space` — the fan-out group-encryption surface.
+ *
+ *   const space = await client.space.createSpace({ historyPolicy: "static" });
+ *   await space.sendMessage({ text: "hello" });
+ *   space.onMessage(e => …);
+ *
+ *   const joined = await client.space.joinSpace(space.id); // newcomer
+ *
+ * A space owns a client-generated keypair whose public key is its id, a
+ * symmetric group key distributed server-blind via the keyring, and a
+ * persisted message log. This namespace wires the {@link Space} handle to the
+ * HTTP {@link KeyringClient}, the member's identity keys (from {@link KeyStore},
+ * shared with the Double Ratchet path), and a PersonalSpace-backed key cache.
+ */
+/** Thrown by `joinChannel` when no channel with that name is registered. */
+class ChannelNotFoundError extends Error {
+    channelName;
+    constructor(channelName) {
+        super(`Channel "${channelName}" does not exist. Create it first.`);
+        this.channelName = channelName;
+        this.name = "ChannelNotFoundError";
+    }
+}
+/** Thrown by `createChannel` when the name is already registered. */
+class ChannelExistsError extends Error {
+    channelName;
+    constructor(channelName) {
+        super(`Channel "${channelName}" already exists.`);
+        this.channelName = channelName;
+        this.name = "ChannelExistsError";
+    }
+}
+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
+     * metadata, mint the initial group key, and connect. Returns the open Space.
+     */
+    async createSpace(opts = {}) {
+        const historyPolicy = opts.historyPolicy ?? "static";
+        const identity = await generateSpaceIdentity();
+        // Register the space (server records pubkey + policy; the DO is lazy).
+        // For a private space the server also records the creator (this user) as
+        // its first member — so the metadata POST must carry the user session.
+        await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy, visibility: opts.private ? "private" : "public" });
+        const space = await this.build(identity.id, historyPolicy);
+        await space.create();
+        return space;
+    }
+    /** Join an existing space by id (its public key). Resolves once a key arrives. */
+    async joinSpace(spaceId, opts = {}) {
+        const policy = await this.fetchPolicy(spaceId);
+        const space = await this.build(spaceId, policy);
+        await space.join({ timeoutMs: opts.timeoutMs });
+        return space;
+    }
+    /** A handle to a space without auto-connecting (uses cached keys on demand). */
+    async get(spaceId, historyPolicy = "static") {
+        return this.build(spaceId, historyPolicy);
+    }
+    // -------------------------------------------------------------------------
+    // Channels — named, app-scoped pointers to spaces. The name → space-id
+    // directory is app-public config (server-readable, scoped to this app via
+    // its key); the channel CONTENTS stay fan-out E2E-encrypted. Lets chat use
+    // human room names (`general`) instead of raw pubkey ids.
+    // -------------------------------------------------------------------------
+    /** List this app's channels (name → space-id) for the key's environment. */
+    async listChannels() {
+        const body = await this.deps.http.get("/api/app/channels");
+        return body.channels ?? [];
+    }
+    /** Resolve a channel name to its space id, or null if it doesn't exist. */
+    async resolveChannel(name) {
+        try {
+            const body = await this.deps.http.get(`/api/app/channels/${encodeURIComponent(name)}`);
+            return body.spaceId ?? null;
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Create a new channel: mint a fan-out space (the caller becomes its first
+     * key-holder) and register `name → spaceId` in the app directory. Throws
+     * {@link ChannelExistsError} if the name is already taken.
+     */
+    async createChannel(name, opts = {}) {
+        const space = await this.createSpace(opts);
+        // Register name → id first so a name clash doesn't leave an admitted keeper.
+        try {
+            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id, visibility: opts.private ? "private" : "public" });
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 409) {
+                throw new ChannelExistsError(name);
+            }
+            throw err;
+        }
+        // Admit the app keeper so the channel is joinable with no member online.
+        // Best-effort: a channel still works (members admit each other) without it.
+        try {
+            const { pubkey } = await this.deps.http.get("/api/app/keeper");
+            if (pubkey && space.keyring)
+                await space.keyring.admit(KEEPER_MEMBER_ID, pubkey);
+        }
+        catch (err) {
+            console.warn("[client.space] keeper admit failed (channel still usable):", err);
         }
         return space;
     }
-    /**
-     * Join an existing channel by name. Throws {@link ChannelNotFoundError} if
-     * no channel with that name is registered (use {@link createChannel} first).
-     */
-    async joinChannel(name, opts = {}) {
-        const spaceId = await this.resolveChannel(name);
-        if (!spaceId)
-            throw new ChannelNotFoundError(name);
-        return this.joinSpace(spaceId, opts);
+    /**
+     * Join an existing channel by name. Throws {@link ChannelNotFoundError} if
+     * no channel with that name is registered (use {@link createChannel} first).
+     */
+    async joinChannel(name, opts = {}) {
+        const spaceId = await this.resolveChannel(name);
+        if (!spaceId)
+            throw new ChannelNotFoundError(name);
+        return this.joinSpace(spaceId, opts);
+    }
+    // -------------------------------------------------------------------------
+    // Invite links — shareable, keeper-gated invitations to a space. The token
+    // is a capability: anyone signed in who redeems it is admitted by the
+    // keeper. Mint/list/revoke require the caller to be the space's creator or
+    // an existing member.
+    // -------------------------------------------------------------------------
+    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
+     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
+     *  access granted to redeemers (default viewer). Returns the link. */
+    async createInviteLink(spaceId, opts = {}) {
+        return this.keyringFor(spaceId).createInviteLink(opts);
+    }
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    async setMemberRole(spaceId, username, role) {
+        await this.keyringFor(spaceId).setMemberRole(username, role);
+    }
+    /** Roster with roles (owner/members only). */
+    async members(spaceId) {
+        return this.keyringFor(spaceId).members();
+    }
+    /** List a space's active invite links (creator/members only). */
+    async listInviteLinks(spaceId) {
+        return this.keyringFor(spaceId).listInviteLinks();
+    }
+    /** Revoke an invite link by token. */
+    async revokeInviteLink(spaceId, token) {
+        await this.keyringFor(spaceId).revokeInviteLink(token);
+    }
+    /**
+     * Join a space using an invite link: redeem the token (the keeper admits
+     * this member), then connect and resolve once the group key arrives.
+     * Returns the open {@link Space}.
+     */
+    async joinByInvite(spaceId, token, opts = {}) {
+        const memberId = this.myId();
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
+        await this.keyringFor(spaceId).redeemInvite({ token, identityEcdhPub: ecdhPub, identityEcdsaPub: ecdsaPub });
+        return this.joinSpace(spaceId, opts);
+    }
+    /** The current member roster of a space (member id → identity public keys). */
+    async roster(spaceId) {
+        return this.keyringFor(spaceId).fetchRoster();
+    }
+    keyringFor(spaceId) {
+        return new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    async build(spaceId, historyPolicy) {
+        const memberId = this.myId();
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
+        const transport = new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        });
+        const keyring = new SpaceKeyring({
+            spaceId,
+            memberId,
+            identityEcdhPub: ecdhPub,
+            identityEcdsaPub: ecdsaPub,
+            ownPrivateKey: () => KeyStore.getInstance().getKeyPair(memberId)?.privateKey ?? null,
+            transport,
+            cache: this.deps.cache,
+            historyPolicy,
+        });
+        const space = new Space({
+            name: spaceId,
+            wsBaseUrl: this.deps.wsBaseUrl,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+            myId: () => memberId,
+            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);
+        // Attach a private P2P swarm scoped to this Space (block exchange among
+        // members; signaled over the Space relay). Discovery starts on connect.
+        if (this.deps.p2p?.enabled && isP2pCapable()) {
+            space.attachPeerNetwork(new PeerNetwork({
+                space,
+                myId: memberId,
+                workerFactory: this.deps.p2p.workerFactory,
+                iceServers: this.deps.p2p.iceServers,
+                maxPeers: this.deps.p2p.maxPeers,
+            }));
+        }
+        return space;
+    }
+    /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
+    async ensureIdentity(memberId) {
+        const store = KeyStore.getInstance();
+        if (!store.getKeyPair(memberId)) {
+            await store.generateOwnKeyPair(memberId);
+        }
+        const ecdhPub = await exportEcdhPublicKey(store.getKeyPair(memberId).publicKey);
+        const ecdsaPub = await exportEcdsaPublicKey(store.getAuthKeyPair(memberId).publicKey);
+        return { ecdhPub, ecdsaPub };
+    }
+    async fetchPolicy(spaceId) {
+        const meta = await new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        }).fetchMetadata();
+        return meta?.historyPolicy ?? "static";
+    }
+    async fetchTicket() {
+        try {
+            const res = await this.deps.http.post("/api/ws-ticket", {});
+            return res?.ticket ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    myId() {
+        const id = this.deps.session.username;
+        if (!id)
+            throw new Error("client.space: not signed in — call client.auth.zk.login() first.");
+        return id;
+    }
+}
+
+/**
+ * `client.agents` — manage an app's **Programmable Agents** (server-side
+ * "virtual users" backed by Workers AI).
+ *
+ *   const { config } = await client.agents.create(appId, {
+ *     handle: '@assistant', displayName: 'Assistant',
+ *     systemPrompt: 'You are a helpful teammate in this Space.',
+ *     triggers: [{ type: 'mention' }],
+ *   });
+ *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
+ *
+ * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
+ * app's owner or an editor of its shared Space may create/update/enable an agent
+ * (viewers can read). Authorization rides the user session token; non-owner
+ * editors pass their management Space via `opts.space`.
+ *
+ * An agent is "prompts + persona": a system prompt, a model, named prompt
+ * `skills`, and `triggers` that decide when it speaks — plus optional `tools`
+ * that let it act on the app (query/write its database, call its functions,
+ * resolve its channels) via a server-side function-calling loop. See
+ * {@link AgentToolsConfig}. Pair with the `@MuhkooAgent`/`@MuhkooSpace`/
+ * `@MuhkooDB`/`@MuhkooFunction` decorators + `ejectAgentPrompt`/`ejectAgentTools`
+ * to generate `systemPrompt` and `tools` straight from your app's surface.
+ */
+class AgentsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's agents. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.agents ?? [];
+    }
+    /** Read one agent (config + identity keys). */
+    async get(appId, agentId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(agentId)}`, opts));
+    }
+    /** Create an agent (owner/editor only). */
+    async create(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    async update(appId, agentId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete an agent (owner/editor only). */
+    async delete(appId, agentId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { space: opts.space });
+    }
+    /** Enable the agent on a Space (per-Space opt-in). */
+    async enable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the agent on a Space. */
+    async disable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/agents${suffix}${q}`;
+    }
+}
+
+/**
+ * `client.functions` — manage an app's **serverless functions** (developer-
+ * authored code that runs on the accelerator).
+ *
+ *   const { config } = await client.functions.deploy(appId, {
+ *     name: 'hello', displayName: 'Hello',
+ *     code: `export default { fetch: () => new Response('hi') }`,
+ *     triggers: { http: { enabled: true } },
+ *   });
+ *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
+ *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *   const out = await client.functions.invoke({ name: 'hello', slug }, { body: { q: 1 } });
+ *
+ * These are MANAGEMENT calls — the function itself runs on the accelerator
+ * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
+ * an editor of its shared Space may deploy/update/enable (viewers read).
+ * Authorization rides the user session token; non-owner editors pass their
+ * management Space via `opts.space`.
+ *
+ * v1 is "compute-only": a function is an untrusted single-module ES worker
+ * (`export default { fetch }`) with NO platform bindings — it reaches the
+ * platform as an external client (the end-user session is passed through). Two
+ * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
+ * like a Programmable Agent).
+ */
+/** The hosted platform's HTTP-function zone. */
+const DEFAULT_FN_HOST_SUFFIX = "fns.muhkoo.dev";
+/** Bodies `fetch` accepts natively — everything else is JSON-encoded. */
+function isRawBody(body) {
+    return (typeof body === "string" ||
+        body instanceof FormData ||
+        body instanceof Blob ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof URLSearchParams ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
+class FunctionsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's functions. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.functions ?? [];
+    }
+    /** Read one function's config. */
+    async get(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}`, opts));
+    }
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    async code(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}/code`, opts));
+    }
+    /** Deploy (create) a function (owner/editor only). */
+    async deploy(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    async update(appId, functionId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete a function (owner/editor only). */
+    async delete(appId, functionId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { space: opts.space });
+    }
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    async enable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the function on a Space. */
+    async disable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /**
+     * Invoke an HTTP-triggered function and parse its JSON response.
+     *
+     *   const out = await client.functions.invoke({ name: 'hello', slug: 'myapp' });
+     *   const out = await client.functions.invoke('hello--myapp', { body: { q: 1 } });
+     *   const out = await client.functions.invoke('https://hello--myapp.fns.muhkoo.dev/x');
+     *
+     * The request carries the SDK's credentials (`X-Muhkoo-Key` and, when a
+     * user is signed in, `X-Muhkoo-Session`) — the platform passes the session
+     * token through to the function, which can verify it server-side via
+     * `POST /api/auth/verify` to establish the caller's identity.
+     *
+     * Non-2xx responses throw {@link HttpError}. For functions that return
+     * something other than JSON, use {@link invokeRaw}.
+     */
+    async invoke(target, opts = {}) {
+        const res = await this.invokeRaw(target, opts);
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            // Non-JSON body — fall through to the status-only error below.
+        }
+        if (!res.ok) {
+            const msg = parsed && typeof parsed === "object" && "error" in parsed
+                ? String(parsed.error)
+                : `${res.status} ${res.statusText}`;
+            throw new HttpError(msg, res.status, parsed);
+        }
+        return parsed;
+    }
+    /** Invoke an HTTP-triggered function and return the raw `Response`. */
+    async invokeRaw(target, opts = {}) {
+        const init = {
+            method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
+        };
+        const headers = new Headers(opts.headers);
+        if (opts.body !== undefined) {
+            if (isRawBody(opts.body)) {
+                init.body = opts.body;
+            }
+            else {
+                init.body = JSON.stringify(opts.body);
+                if (!headers.has("Content-Type"))
+                    headers.set("Content-Type", "application/json");
+            }
+        }
+        init.headers = headers;
+        return this.deps.http.fetch(this.invokeUrl(target, opts.path), init);
+    }
+    /** Resolve an invoke target to the function's absolute URL. */
+    invokeUrl(target, path = "") {
+        const suffix = this.deps.fnHostSuffix ?? DEFAULT_FN_HOST_SUFFIX;
+        let base;
+        if (typeof target === "string") {
+            base = /^https?:\/\//.test(target) ? target : `https://${target}.${suffix}`;
+        }
+        else {
+            base = `https://${target.name}--${target.slug}.${suffix}`;
+        }
+        if (!path)
+            return base;
+        return `${base.replace(/\/+$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${q}`;
+    }
+}
+
+/**
+ * `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;
     }
-    // -------------------------------------------------------------------------
-    // Invite links — shareable, keeper-gated invitations to a space. The token
-    // is a capability: anyone signed in who redeems it is admitted by the
-    // keeper. Mint/list/revoke require the caller to be the space's creator or
-    // an existing member.
-    // -------------------------------------------------------------------------
-    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
-     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
-     *  access granted to redeemers (default viewer). Returns the link. */
-    async createInviteLink(spaceId, opts = {}) {
-        return this.keyringFor(spaceId).createInviteLink(opts);
+    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 */
+            }
+        }
     }
-    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
-    async setMemberRole(spaceId, username, role) {
-        await this.keyringFor(spaceId).setMemberRole(username, role);
+    scheduleOffline() {
+        if (this.state === "offline" || this.offlineTimer)
+            return;
+        this.offlineTimer = setTimeout(() => {
+            this.offlineTimer = null;
+            this.set("offline");
+        }, this.debounceMs);
     }
-    /** Roster with roles (owner/members only). */
-    async members(spaceId) {
-        return this.keyringFor(spaceId).members();
+    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 });
     }
-    /** List a space's active invite links (creator/members only). */
-    async listInviteLinks(spaceId) {
-        return this.keyringFor(spaceId).listInviteLinks();
+}
+
+/**
+ * `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;
     }
-    /** Revoke an invite link by token. */
-    async revokeInviteLink(spaceId, token) {
-        await this.keyringFor(spaceId).revokeInviteLink(token);
+    /** 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;
     }
     /**
-     * Join a space using an invite link: redeem the token (the keeper admits
-     * this member), then connect and resolve once the group key arrives.
-     * Returns the open {@link Space}.
+     * 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.
      */
-    async joinByInvite(spaceId, token, opts = {}) {
-        const memberId = this.myId();
-        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
-        await this.keyringFor(spaceId).redeemInvite({ token, identityEcdhPub: ecdhPub, identityEcdsaPub: ecdsaPub });
-        return this.joinSpace(spaceId, opts);
+    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;
+            }
+        }
     }
-    /** The current member roster of a space (member id → identity public keys). */
-    async roster(spaceId) {
-        return this.keyringFor(spaceId).fetchRoster();
+}
+/** 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;
     }
-    keyringFor(spaceId) {
-        return new KeyringClient({
-            spaceId,
-            httpBaseUrl: this.deps.http.baseUrl,
-            fetch: this.deps.http.fetch,
+    /** 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;
     }
-    // -------------------------------------------------------------------------
-    // Internals
-    // -------------------------------------------------------------------------
-    async build(spaceId, historyPolicy) {
-        const memberId = this.myId();
-        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
-        const transport = new KeyringClient({
-            spaceId,
-            httpBaseUrl: this.deps.http.baseUrl,
-            fetch: this.deps.http.fetch,
+    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;
+    }
+}
+
+/**
+ * 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(),
         });
-        const keyring = new SpaceKeyring({
-            spaceId,
-            memberId,
-            identityEcdhPub: ecdhPub,
-            identityEcdsaPub: ecdsaPub,
-            ownPrivateKey: () => KeyStore.getInstance().getKeyPair(memberId)?.privateKey ?? null,
-            transport,
-            cache: this.deps.cache,
-            historyPolicy,
+        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,
         });
-        return new Space({
-            name: spaceId,
-            wsBaseUrl: this.deps.wsBaseUrl,
-            httpBaseUrl: this.deps.http.baseUrl,
-            fetch: this.deps.http.fetch,
-            myId: () => memberId,
-            fetchTicket: () => this.fetchTicket(),
-            keyring,
-            historyPolicy,
+        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();
     }
-    /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
-    async ensureIdentity(memberId) {
-        const store = KeyStore.getInstance();
-        if (!store.getKeyPair(memberId)) {
-            await store.generateOwnKeyPair(memberId);
+    /**
+     * 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;
         }
-        const ecdhPub = await exportEcdhPublicKey(store.getKeyPair(memberId).publicKey);
-        const ecdsaPub = await exportEcdsaPublicKey(store.getAuthKeyPair(memberId).publicKey);
-        return { ecdhPub, ecdsaPub };
+        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 fetchPolicy(spaceId) {
-        const meta = await new KeyringClient({
-            spaceId,
-            httpBaseUrl: this.deps.http.baseUrl,
-            fetch: this.deps.http.fetch,
-        }).fetchMetadata();
-        return meta?.historyPolicy ?? "static";
+    async put(_store, _key, _value) { }
+    async delete(_store, _key) { }
+    async prefix(_store, _prefix) {
+        return [];
     }
-    async fetchTicket() {
-        try {
-            const res = await this.deps.http.post("/api/ws-ticket", {});
-            return res?.ticket ?? null;
-        }
-        catch {
-            return null;
-        }
+    async range(_store, _lower, _upper) {
+        return [];
     }
-    myId() {
-        const id = this.deps.session.username;
-        if (!id)
-            throw new Error("client.space: not signed in — call client.auth.zk.login() first.");
-        return id;
+    async all(_store) {
+        return [];
+    }
+    async clear(_store) { }
+    async enqueue(_entry) {
+        return -1;
+    }
+    async dequeue(_seq) { }
+    async queued() {
+        return [];
     }
 }
 
 /**
- * `client.agents` — manage an app's **Programmable Agents** (server-side
- * "virtual users" backed by Workers AI).
- *
- *   const { config } = await client.agents.create(appId, {
- *     handle: '@assistant', displayName: 'Assistant',
- *     systemPrompt: 'You are a helpful teammate in this Space.',
- *     triggers: [{ type: 'mention' }],
- *   });
- *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
- *
- * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
- * app's owner or an editor of its shared Space may create/update/enable an agent
- * (viewers can read). Authorization rides the user session token; non-owner
- * editors pass their management Space via `opts.space`.
- *
- * An agent is "prompts + persona": a system prompt, a model, named prompt
- * `skills`, and `triggers` that decide when it speaks — plus optional `tools`
- * that let it act on the app (query/write its database, call its functions,
- * resolve its channels) via a server-side function-calling loop. See
- * {@link AgentToolsConfig}. Pair with the `@MuhkooAgent`/`@MuhkooSpace`/
- * `@MuhkooDB`/`@MuhkooFunction` decorators + `ejectAgentPrompt`/`ejectAgentTools`
- * to generate `systemPrompt` and `tools` straight from your app's surface.
+ * `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.
  */
-class AgentsNamespace {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+/** 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;
     }
-    /** List the app's agents. */
-    async list(appId, opts = {}) {
-        const res = await this.deps.http.get(this.path(appId, "", opts));
-        return res.agents ?? [];
+    get enabled() {
+        return this.manager.enabled;
     }
-    /** Read one agent (config + identity keys). */
-    async get(appId, agentId, opts = {}) {
-        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(agentId)}`, opts));
+    nextHlc() {
+        return this.manager.nextHlc();
     }
-    /** Create an agent (owner/editor only). */
-    async create(appId, input, opts = {}) {
-        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    newClientId() {
+        return this.manager.newClientId();
     }
-    /** Update an agent's editor-settable fields (owner/editor only). */
-    async update(appId, agentId, patch, opts = {}) {
-        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { ...patch, space: opts.space });
+    key(commitment, fullKey) {
+        return `${commitment}|${fullKey}`;
     }
-    /** Delete an agent (owner/editor only). */
-    async delete(appId, agentId, opts = {}) {
-        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { space: opts.space });
+    /** Read the cached register for `collection/id`, or null when absent. */
+    read(commitment, fullKey) {
+        return this.store.get("kv-cache", this.key(commitment, fullKey));
     }
-    /** Enable the agent on a Space (per-Space opt-in). */
-    async enable(appId, agentId, spaceId, opts = {}) {
-        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    /** 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));
     }
-    /** Disable the agent on a Space. */
-    async disable(appId, agentId, spaceId, opts = {}) {
-        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    /** 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));
     }
-    path(appId, suffix, opts) {
-        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
-        return `/api/apps/${encodeURIComponent(appId)}/agents${suffix}${q}`;
+    /**
+     * 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 });
     }
 }
 
 /**
- * `client.functions` — manage an app's **serverless functions** (developer-
- * authored code that runs on the accelerator).
- *
- *   const { config } = await client.functions.deploy(appId, {
- *     name: 'hello', displayName: 'Hello',
- *     code: `export default { fetch: () => new Response('hi') }`,
- *     triggers: { http: { enabled: true } },
- *   });
- *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
- *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
- *   const out = await client.functions.invoke({ name: 'hello', slug }, { body: { q: 1 } });
- *
- * These are MANAGEMENT calls — the function itself runs on the accelerator
- * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
- * an editor of its shared Space may deploy/update/enable (viewers read).
- * Authorization rides the user session token; non-owner editors pass their
- * management Space via `opts.space`.
- *
- * v1 is "compute-only": a function is an untrusted single-module ES worker
- * (`export default { fetch }`) with NO platform bindings — it reaches the
- * platform as an external client (the end-user session is passed through). Two
- * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
- * like a Programmable Agent).
+ * `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.
  */
-/** The hosted platform's HTTP-function zone. */
-const DEFAULT_FN_HOST_SUFFIX = "fns.muhkoo.dev";
-/** Bodies `fetch` accepts natively — everything else is JSON-encoded. */
-function isRawBody(body) {
-    return (typeof body === "string" ||
-        body instanceof FormData ||
-        body instanceof Blob ||
-        body instanceof ArrayBuffer ||
-        ArrayBuffer.isView(body) ||
-        body instanceof URLSearchParams ||
-        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
-}
-class FunctionsNamespace {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+/** 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;
     }
-    /** List the app's functions. */
-    async list(appId, opts = {}) {
-        const res = await this.deps.http.get(this.path(appId, "", opts));
-        return res.functions ?? [];
+    get enabled() {
+        return this.manager.enabled;
     }
-    /** Read one function's config. */
-    async get(appId, functionId, opts = {}) {
-        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}`, opts));
+    nextHlc() {
+        return this.manager.nextHlc();
     }
-    /** Read a function's decrypted source (owner/editor; for the editor UI). */
-    async code(appId, functionId, opts = {}) {
-        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}/code`, opts));
+    newClientId() {
+        return this.manager.newClientId();
     }
-    /** Deploy (create) a function (owner/editor only). */
-    async deploy(appId, input, opts = {}) {
-        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    /** 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;
     }
-    /** Update a function's editor-settable fields and/or redeploy its `code`. */
-    async update(appId, functionId, patch, opts = {}) {
-        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { ...patch, space: opts.space });
+    rowKey(table, id) {
+        return `${table}|row|${id}`;
     }
-    /** Delete a function (owner/editor only). */
-    async delete(appId, functionId, opts = {}) {
-        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { space: opts.space });
+    queryKey(table, q) {
+        return `${table}|query|${stableStringify(q)}`;
     }
-    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
-    async enable(appId, functionId, spaceId, opts = {}) {
-        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    async readRow(table, id) {
+        return this.store.get("db-row-cache", this.rowKey(table, id));
     }
-    /** Disable the function on a Space. */
-    async disable(appId, functionId, spaceId, opts = {}) {
-        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    async writeRow(table, id, row) {
+        await this.store.put("db-row-cache", this.rowKey(table, id), row);
     }
-    /**
-     * Invoke an HTTP-triggered function and parse its JSON response.
-     *
-     *   const out = await client.functions.invoke({ name: 'hello', slug: 'myapp' });
-     *   const out = await client.functions.invoke('hello--myapp', { body: { q: 1 } });
-     *   const out = await client.functions.invoke('https://hello--myapp.fns.muhkoo.dev/x');
-     *
-     * The request carries the SDK's credentials (`X-Muhkoo-Key` and, when a
-     * user is signed in, `X-Muhkoo-Session`) — the platform passes the session
-     * token through to the function, which can verify it server-side via
-     * `POST /api/auth/verify` to establish the caller's identity.
-     *
-     * Non-2xx responses throw {@link HttpError}. For functions that return
-     * something other than JSON, use {@link invokeRaw}.
-     */
-    async invoke(target, opts = {}) {
-        const res = await this.invokeRaw(target, opts);
-        let parsed = null;
-        try {
-            parsed = await res.json();
-        }
-        catch {
-            // Non-JSON body — fall through to the status-only error below.
-        }
-        if (!res.ok) {
-            const msg = parsed && typeof parsed === "object" && "error" in parsed
-                ? String(parsed.error)
-                : `${res.status} ${res.statusText}`;
-            throw new HttpError(msg, res.status, parsed);
-        }
-        return parsed;
+    /** 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 });
     }
-    /** Invoke an HTTP-triggered function and return the raw `Response`. */
-    async invokeRaw(target, opts = {}) {
-        const init = {
-            method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
-        };
-        const headers = new Headers(opts.headers);
-        if (opts.body !== undefined) {
-            if (isRawBody(opts.body)) {
-                init.body = opts.body;
-            }
-            else {
-                init.body = JSON.stringify(opts.body);
-                if (!headers.has("Content-Type"))
-                    headers.set("Content-Type", "application/json");
-            }
-        }
-        init.headers = headers;
-        return this.deps.http.fetch(this.invokeUrl(target, opts.path), init);
+    async deleteRow(table, id) {
+        await this.store.delete("db-row-cache", this.rowKey(table, id));
     }
-    /** Resolve an invoke target to the function's absolute URL. */
-    invokeUrl(target, path = "") {
-        const suffix = this.deps.fnHostSuffix ?? DEFAULT_FN_HOST_SUFFIX;
-        let base;
-        if (typeof target === "string") {
-            base = /^https?:\/\//.test(target) ? target : `https://${target}.${suffix}`;
-        }
-        else {
-            base = `https://${target.name}--${target.slug}.${suffix}`;
-        }
-        if (!path)
-            return base;
-        return `${base.replace(/\/+$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
+    async readQuery(table, q) {
+        return this.store.get("db-query-cache", this.queryKey(table, q));
     }
-    path(appId, suffix, opts) {
-        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
-        return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${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 });
     }
 }
 
@@ -8001,6 +10564,8 @@ class Client {
     agents;
     /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
     functions;
+    /** Offline cache + sync — `client.offline.status`, `client.offline.snapshot`, etc. */
+    offline;
     session;
     http;
     /** Subscribers notified when a session expires and can't be recovered. */
@@ -8020,11 +10585,40 @@ class Client {
         }
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.session = new SessionState(options.sessionStore ?? defaultSessionStore());
+        // Offline layer. On by default in browsers, a no-op (NoopStore) in Node,
+        // Workers, and SSR — so existing consumers are unaffected unless they're
+        // in a browser that can actually cache.
+        const offlineEnabled = options.offline?.enabled ?? isOfflineCapable();
+        const offlineStore = offlineEnabled
+            ? (options.offline?.store ?? new IndexedDbStore())
+            : new NoopStore();
+        this.offline = new OfflineManager({
+            store: offlineStore,
+            session: this.session,
+            enabled: offlineEnabled,
+        });
+        // Wrap fetch so every accelerator round-trip feeds the connectivity
+        // detector: a thrown fetch is the strongest "offline" signal, a 2xx the
+        // strongest "online" one. Only when offline support is active.
+        const baseFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+        const reportingFetch = offlineEnabled && baseFetch
+            ? async (input, init) => {
+                try {
+                    const res = await baseFetch(input, init);
+                    this.offline.reportFetchSuccess();
+                    return res;
+                }
+                catch (err) {
+                    this.offline.reportFetchFailure();
+                    throw err;
+                }
+            }
+            : options.fetch;
         this.http = new HttpClient({
             baseUrl: this.baseUrl,
             apiKey: options.apiKey,
             getSessionToken: () => this.session.token,
-            fetch: options.fetch,
+            fetch: reportingFetch,
             // Self-heal stale sessions: on a 401, try a silent re-auth (only
             // works while unlocked). If it can't, `recoverSession` fires the
             // session-expired event so the app can redirect to login.
@@ -8035,9 +10629,24 @@ class Client {
         const wsBaseUrl = toWsBase(this.baseUrl);
         const authBaseUrl = (options.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/+$/, "");
         this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session, authBaseUrl });
-        this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl });
-        this.db = new DbNamespace({ http: this.http });
-        this.storage = new StorageNamespace({ http: this.http, baseUrl: this.baseUrl, kv: this.kv });
+        const deferShardUpload = offlineEnabled
+            ? (hash) => this.offline.deferShardUpload(hash)
+            : undefined;
+        const kvCache = offlineEnabled ? new KvCache(this.offline) : undefined;
+        this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl, offline: kvCache });
+        if (offlineEnabled)
+            this.offline.registerReplayer("kv", (e) => this.kv.replay(e));
+        const dbCache = offlineEnabled ? new DbCache(this.offline) : undefined;
+        this.db = new DbNamespace({ http: this.http, offline: dbCache });
+        if (offlineEnabled)
+            this.offline.registerReplayer("db", (e) => this.db.replay(e));
+        this.storage = new StorageNamespace({
+            http: this.http,
+            baseUrl: this.baseUrl,
+            kv: this.kv,
+            shardCache: this.offline.fileCache,
+            deferShardUpload,
+        });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
         // by client.kv), so a returning member hydrates without a fresh keyring
@@ -8051,9 +10660,29 @@ class Client {
             session: this.session,
             wsBaseUrl,
             cache: spaceKeyCache,
+            offline: this.offline,
+            p2p: options.p2p,
         });
         this.agents = new AgentsNamespace({ http: this.http });
         this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });
+        // Replay deferred shard uploads on reconnect. The bytes live in the
+        // Cache API keyed by hash; re-PUT them through a (defer-free) shard
+        // client so a failure surfaces as transient and the entry stays queued.
+        if (offlineEnabled && this.offline.fileCache) {
+            const replayShards = new ShardClient({
+                baseUrl: this.baseUrl,
+                pathPrefix: "/api/shards",
+                fetch: this.http.fetch,
+                cache: this.offline.fileCache,
+            });
+            this.offline.registerReplayer("file", async (entry) => {
+                const { hash } = entry.args;
+                const bytes = await this.offline.fileCache.get(hash);
+                if (!bytes)
+                    return; // evicted from cache — nothing to replay
+                await replayShards.putShard(hash, bytes);
+            });
+        }
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -8107,6 +10736,116 @@ class Client {
     }
 }
 
+/**
+ * `LWWMap` — a map of independent last-write-wins registers, one per column.
+ * This is the conflict model for a `db` row: two devices that edit *different*
+ * columns of the same row while offline both keep their edits (no lost update),
+ * and two that edit the *same* column converge to the greater-HLC write. A row
+ * delete is a causal tombstone (see {@link ./ORSet}); a later write to any
+ * column resurrects the row with just the surviving columns.
+ *
+ * This mirrors, on the client, exactly what the accelerator's `_muhkoo_crdt`
+ * sidecar does server-side — so a row materializes identically whether it was
+ * merged locally (offline) or by the server on replay.
+ */
+function emptyMap() {
+    return { fields: {}, columnHlc: {}, tombstone: null };
+}
+/** Apply a local column write (insert/update) at the given per-column HLCs. */
+function writeColumns(map, values, hlc) {
+    const next = {
+        fields: { ...map.fields },
+        columnHlc: { ...map.columnHlc },
+        tombstone: map.tombstone,
+    };
+    for (const [col, value] of Object.entries(values)) {
+        const prev = next.columnHlc[col];
+        if (!prev || compareHlc(hlc, prev) > 0) {
+            next.fields[col] = value;
+            next.columnHlc[col] = hlc;
+        }
+    }
+    return next;
+}
+/** Apply a row delete at `hlc` (causal tombstone). */
+function tombstoneRow(map, hlc) {
+    const tombstone = !map.tombstone || compareHlc(hlc, map.tombstone) > 0 ? hlc : map.tombstone;
+    return { fields: { ...map.fields }, columnHlc: { ...map.columnHlc }, tombstone };
+}
+/** Merge two row states column-by-column. Pure; neither input is mutated. */
+function mergeMap(a, b) {
+    const cols = new Set([...Object.keys(a.columnHlc), ...Object.keys(b.columnHlc)]);
+    const out = emptyMap();
+    for (const col of cols) {
+        const ah = a.columnHlc[col];
+        const bh = b.columnHlc[col];
+        const aWins = ah && (!bh || compareHlc(ah, bh) >= 0);
+        const winner = aWins ? a : b;
+        out.fields[col] = winner.fields[col];
+        out.columnHlc[col] = winner.columnHlc[col];
+    }
+    out.tombstone =
+        a.tombstone && b.tombstone
+            ? compareHlc(a.tombstone, b.tombstone) >= 0
+                ? a.tombstone
+                : b.tombstone
+            : (a.tombstone ?? b.tombstone);
+    return out;
+}
+/**
+ * Materialize the visible row from merged state, or `null` when the row is
+ * deleted. A column is visible only when its write is causally newer than the
+ * tombstone — so a delete hides every prior column, but a post-delete write to
+ * a column brings the row back with just that column populated.
+ */
+function materializeRow(map) {
+    const visible = {};
+    let any = false;
+    for (const [col, hlc] of Object.entries(map.columnHlc)) {
+        if (!map.tombstone || compareHlc(hlc, map.tombstone) > 0) {
+            visible[col] = map.fields[col];
+            any = true;
+        }
+    }
+    return any ? visible : null;
+}
+
+/**
+ * Tombstone helpers shared by the LWW CRDTs. We don't need a full
+ * observed-remove set — every domain that deletes (kv keys, db rows) does so
+ * by stamping a delete with an HLC and keeping that stamp around. The only
+ * rule that matters is the causal one:
+ *
+ *   a delete at HLC `d` hides the value, but a *later* write at HLC `w > d`
+ *   resurrects it; a *stale* write at `w <= d` is dropped.
+ *
+ * Keeping the delete HLC (rather than physically forgetting the key) is what
+ * prevents a delayed offline write from "un-deleting" something a peer already
+ * removed. Callers GC tombstones older than any possible offline window.
+ */
+/**
+ * Does a write at `writeHlc` win against a tombstone at `tombstoneHlc`?
+ * `true` ⇒ the write applies (resurrecting a deleted item if needed); `false`
+ * ⇒ the tombstone still holds and the write is dropped. A missing tombstone
+ * (`null`) means there's nothing suppressing the write.
+ */
+function writeBeatsTombstone(writeHlc, tombstoneHlc) {
+    if (!tombstoneHlc)
+        return true;
+    return compareHlc(writeHlc, tombstoneHlc) > 0;
+}
+/**
+ * Does a delete at `deleteHlc` win against the latest write at `writeHlc`?
+ * `true` ⇒ the item is now tombstoned. Ties go to the delete (remove-wins) so
+ * that a delete and a write stamped in the same instant resolve deterministically
+ * toward removal.
+ */
+function deleteBeatsWrite(deleteHlc, writeHlc) {
+    if (!writeHlc)
+        return true;
+    return compareHlc(deleteHlc, writeHlc) >= 0;
+}
+
 /**
  * Muhkoo app decorators — declare your app's agent-facing surface in code, then
  * "eject" a system prompt you hand to a Programmable Agent.
@@ -8814,5 +11553,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VERSION, VaultUnavailableError, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, serialize, shardHash, signMessage, toBase64$1 as toBase64, toBase64Url, toField, toHex, unsealSeed, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compareHlc, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, serialize, shardHash, signMessage, stableStringify, toBase64$1 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map