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

package/dist/browser/index.js

@@ -2082,6 +2082,14 @@ var EventCoreEvents;
     EventCoreEvents["MESSAGE"] = "message";
     EventCoreEvents["GET_HISTORY"] = "get_history";
     EventCoreEvents["RECEIVED_HISTORY"] = "received_history";
+    // Offline layer — connectivity + background sync lifecycle. Emitted by the
+    // ConnectivityManager / SyncEngine; apps subscribe to drive a status UI.
+    EventCoreEvents["ONLINE"] = "online";
+    EventCoreEvents["OFFLINE"] = "offline";
+    EventCoreEvents["SYNCING"] = "syncing";
+    EventCoreEvents["SYNC_PROGRESS"] = "sync_progress";
+    EventCoreEvents["SYNC_COMPLETE"] = "sync_complete";
+    EventCoreEvents["SYNC_ERROR"] = "sync_error";
 })(EventCoreEvents || (EventCoreEvents = {}));
 /**
  * @public
@@ -3804,6 +3812,9 @@ class ShardClient {
     baseUrl;
     pathPrefix;
     fetchFn;
+    cache;
+    deferUpload;
+    peers;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -3819,6 +3830,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) {
@@ -3832,12 +3846,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}`);
@@ -3857,8 +3891,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) {
@@ -3866,7 +3933,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
@@ -4891,7 +4961,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
@@ -6261,30 +6331,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) {
@@ -6343,6 +6487,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 });
     }
@@ -6410,41 +6558,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 {
@@ -6460,7 +6676,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 });
+        }
     }
 }
 
@@ -6588,6 +6818,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;
@@ -6825,6 +7057,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;
@@ -6873,14 +7108,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) {
@@ -6927,7 +7193,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) {
@@ -6945,7 +7234,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}
@@ -6953,7 +7257,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) {
@@ -6974,10 +7316,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) {
@@ -7014,8 +7358,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 };
     }
@@ -7082,6 +7439,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 });
     }
@@ -7100,9 +7460,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) {
@@ -7111,14 +7474,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") {
@@ -7154,12 +7524,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;
@@ -7179,7 +7554,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;
@@ -7197,8 +7572,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)
@@ -7210,6 +7586,7 @@ class Space {
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
                 handle,
+                clientId: packet.headers?.cid,
                 message,
             };
         }
@@ -7252,6 +7629,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 }));
     }
@@ -7271,6 +7704,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.
@@ -7766,455 +8211,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 */
         }
-        return space;
     }
-    /**
+    /** 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);
+    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();
     }
-    // -------------------------------------------------------------------------
-    // 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);
+    /** The current stamp without advancing the clock. */
+    current() {
+        return pack(this.wall, this.counter, this.nodeId);
     }
-    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
-    async setMemberRole(spaceId, username, role) {
-        await this.keyringFor(spaceId).setMemberRole(username, role);
+    /** Serializable `{ wall, counter }` for persistence. */
+    getState() {
+        return { wall: this.wall, counter: this.counter };
     }
-    /** Roster with roles (owner/members only). */
-    async members(spaceId) {
-        return this.keyringFor(spaceId).members();
+}
+
+/**
+ * `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;
     }
-    /** List a space's active invite links (creator/members only). */
-    async listInviteLinks(spaceId) {
-        return this.keyringFor(spaceId).listInviteLinks();
+    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 */
+            }
+        }
     }
-    /** Revoke an invite link by token. */
-    async revokeInviteLink(spaceId, token) {
-        await this.keyringFor(spaceId).revokeInviteLink(token);
+    scheduleOffline() {
+        if (this.state === "offline" || this.offlineTimer)
+            return;
+        this.offlineTimer = setTimeout(() => {
+            this.offlineTimer = null;
+            this.set("offline");
+        }, this.debounceMs);
+    }
+    set(state) {
+        if (state === this.state)
+            return;
+        this.state = state;
+        for (const cb of this.listeners) {
+            try {
+                cb(state);
+            }
+            catch {
+                /* a bad listener mustn't break the others */
+            }
+        }
+        const event = state === "online"
+            ? EventCoreEvents.ONLINE
+            : state === "offline"
+                ? EventCoreEvents.OFFLINE
+                : EventCoreEvents.SYNCING;
+        EventCore.emit(event, { state });
+    }
+}
+
+/**
+ * `OutboundQueue` — the durable record of writes made while offline (or that
+ * failed mid-flight) plus the machinery to replay them on reconnect. This is
+ * what makes offline writes *survive a reload*: unlike the in-memory buffer in
+ * {@link ../transport/WSTransport}, every entry lives in IndexedDB until it has
+ * been acknowledged by the server.
+ *
+ * Each domain registers a **replayer** — a function that re-applies one queued
+ * mutation by re-invoking the real namespace method (with an `isReplay` flag so
+ * it doesn't re-enqueue). `drain()` replays entries in HLC order:
+ *   - success → remove the entry;
+ *   - permanent failure (4xx) → drop it and surface a `SYNC_ERROR` (a write the
+ *     server will never accept must not wedge the queue forever);
+ *   - transient/network failure → stop draining and leave the rest for the next
+ *     reconnect.
+ *
+ * Replays are idempotent by construction (kv/db are LWW-by-key, messages dedupe
+ * by `clientId`, file PUTs are content-addressed), so re-running a partially
+ * drained queue is safe.
+ */
+class OutboundQueue {
+    store;
+    replayers = new Map();
+    draining = null;
+    constructor(store) {
+        this.store = store;
+    }
+    /** A domain registers how to replay its mutations. */
+    register(domain, replayer) {
+        this.replayers.set(domain, replayer);
+    }
+    /** Record a mutation for later replay; resolves with its assigned seq. */
+    enqueue(entry) {
+        return this.store.enqueue(entry);
+    }
+    /** Number of writes still awaiting sync. */
+    async pending() {
+        return (await this.store.queued()).length;
     }
     /**
-     * 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 });
     }
 }
 
@@ -8270,6 +10833,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. */
@@ -8289,11 +10854,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.
@@ -8304,9 +10898,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
@@ -8320,9 +10929,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() {
@@ -8547,6 +11176,116 @@ function ejectAgentTools(appClass, opts) {
     };
 }
 
+/**
+ * `LWWMap` — a map of independent last-write-wins registers, one per column.
+ * This is the conflict model for a `db` row: two devices that edit *different*
+ * columns of the same row while offline both keep their edits (no lost update),
+ * and two that edit the *same* column converge to the greater-HLC write. A row
+ * delete is a causal tombstone (see {@link ./ORSet}); a later write to any
+ * column resurrects the row with just the surviving columns.
+ *
+ * This mirrors, on the client, exactly what the accelerator's `_muhkoo_crdt`
+ * sidecar does server-side — so a row materializes identically whether it was
+ * merged locally (offline) or by the server on replay.
+ */
+function emptyMap() {
+    return { fields: {}, columnHlc: {}, tombstone: null };
+}
+/** Apply a local column write (insert/update) at the given per-column HLCs. */
+function writeColumns(map, values, hlc) {
+    const next = {
+        fields: { ...map.fields },
+        columnHlc: { ...map.columnHlc },
+        tombstone: map.tombstone,
+    };
+    for (const [col, value] of Object.entries(values)) {
+        const prev = next.columnHlc[col];
+        if (!prev || compareHlc(hlc, prev) > 0) {
+            next.fields[col] = value;
+            next.columnHlc[col] = hlc;
+        }
+    }
+    return next;
+}
+/** Apply a row delete at `hlc` (causal tombstone). */
+function tombstoneRow(map, hlc) {
+    const tombstone = !map.tombstone || compareHlc(hlc, map.tombstone) > 0 ? hlc : map.tombstone;
+    return { fields: { ...map.fields }, columnHlc: { ...map.columnHlc }, tombstone };
+}
+/** Merge two row states column-by-column. Pure; neither input is mutated. */
+function mergeMap(a, b) {
+    const cols = new Set([...Object.keys(a.columnHlc), ...Object.keys(b.columnHlc)]);
+    const out = emptyMap();
+    for (const col of cols) {
+        const ah = a.columnHlc[col];
+        const bh = b.columnHlc[col];
+        const aWins = ah && (!bh || compareHlc(ah, bh) >= 0);
+        const winner = aWins ? a : b;
+        out.fields[col] = winner.fields[col];
+        out.columnHlc[col] = winner.columnHlc[col];
+    }
+    out.tombstone =
+        a.tombstone && b.tombstone
+            ? compareHlc(a.tombstone, b.tombstone) >= 0
+                ? a.tombstone
+                : b.tombstone
+            : (a.tombstone ?? b.tombstone);
+    return out;
+}
+/**
+ * Materialize the visible row from merged state, or `null` when the row is
+ * deleted. A column is visible only when its write is causally newer than the
+ * tombstone — so a delete hides every prior column, but a post-delete write to
+ * a column brings the row back with just that column populated.
+ */
+function materializeRow(map) {
+    const visible = {};
+    let any = false;
+    for (const [col, hlc] of Object.entries(map.columnHlc)) {
+        if (!map.tombstone || compareHlc(hlc, map.tombstone) > 0) {
+            visible[col] = map.fields[col];
+            any = true;
+        }
+    }
+    return any ? visible : null;
+}
+
+/**
+ * Tombstone helpers shared by the LWW CRDTs. We don't need a full
+ * observed-remove set — every domain that deletes (kv keys, db rows) does so
+ * by stamping a delete with an HLC and keeping that stamp around. The only
+ * rule that matters is the causal one:
+ *
+ *   a delete at HLC `d` hides the value, but a *later* write at HLC `w > d`
+ *   resurrects it; a *stale* write at `w <= d` is dropped.
+ *
+ * Keeping the delete HLC (rather than physically forgetting the key) is what
+ * prevents a delayed offline write from "un-deleting" something a peer already
+ * removed. Callers GC tombstones older than any possible offline window.
+ */
+/**
+ * Does a write at `writeHlc` win against a tombstone at `tombstoneHlc`?
+ * `true` ⇒ the write applies (resurrecting a deleted item if needed); `false`
+ * ⇒ the tombstone still holds and the write is dropped. A missing tombstone
+ * (`null`) means there's nothing suppressing the write.
+ */
+function writeBeatsTombstone(writeHlc, tombstoneHlc) {
+    if (!tombstoneHlc)
+        return true;
+    return compareHlc(writeHlc, tombstoneHlc) > 0;
+}
+/**
+ * Does a delete at `deleteHlc` win against the latest write at `writeHlc`?
+ * `true` ⇒ the item is now tombstoned. Ties go to the delete (remove-wins) so
+ * that a delete and a write stamped in the same instant resolve deterministically
+ * toward removal.
+ */
+function deleteBeatsWrite(deleteHlc, writeHlc) {
+    if (!writeHlc)
+        return true;
+    return compareHlc(deleteHlc, writeHlc) >= 0;
+}
+
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
@@ -8613,5 +11352,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VaultUnavailableError, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, toField, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, 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, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map