@muhkoo/connect 0.8.0-alpha.0 → 0.9.0-alpha.0

package/dist/browser/index.js

@@ -3814,6 +3814,7 @@ class ShardClient {
     fetchFn;
     cache;
     deferUpload;
+    peers;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -3831,6 +3832,7 @@ class ShardClient {
         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) {
@@ -3849,6 +3851,9 @@ class ShardClient {
         // 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, {
@@ -3892,6 +3897,22 @@ class ShardClient {
             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);
         let response;
         try {
@@ -4940,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.8.0-alpha.0";
+const VERSION = "0.9.0-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -7037,6 +7058,8 @@ class Space {
     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;
@@ -7085,6 +7108,9 @@ 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
@@ -7100,6 +7126,27 @@ class Space {
         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) {
@@ -7269,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) {
@@ -7392,6 +7441,7 @@ class Space {
             fetch: this.deps.fetch,
             cache: this.deps.shardCache,
             deferUpload: this.deps.deferShardUpload,
+            peers: this.peerNet?.exchange,
         });
         return new FileStorage({ shards });
     }
@@ -8310,6 +8360,849 @@ class SpaceCache {
     }
 }
 
+/**
+ * `ShardCache` — a Cache-API-backed store for file-shard bytes. Shards are
+ * content-addressed (the key IS the SHA-256 of the ciphertext), so caching them
+ * is uniquely safe: a cache hit is self-validating, immutable, and shareable
+ * across files. The Cache API (rather than IndexedDB) is the right home for
+ * large binary blobs — it streams, it's purpose-built for response bodies, and
+ * it has its own eviction.
+ *
+ * Keys are SYNTHETIC absolute URLs (`https://shard.muhkoo.local/<hash>`) rather
+ * than the real shard endpoint, so the cache is addressable by hash alone — the
+ * sync engine can re-PUT a deferred shard knowing only its hash, without
+ * reconstructing the accelerator URL. We never fetch these synthetic URLs; they
+ * exist only as cache keys.
+ *
+ * Every method degrades to a no-op / null where the Cache API is unavailable
+ * (Node, Workers, insecure contexts), so callers don't need to branch.
+ */
+const CACHE_NAME = "muhkoo-shards-v1";
+class ShardCache {
+    static available() {
+        try {
+            return typeof caches !== "undefined";
+        }
+        catch {
+            return false;
+        }
+    }
+    key(hash) {
+        return `https://shard.muhkoo.local/${encodeURIComponent(hash)}`;
+    }
+    open() {
+        return caches.open(CACHE_NAME);
+    }
+    /** Cached shard bytes, or `null` on miss / when unavailable. */
+    async get(hash) {
+        if (!ShardCache.available())
+            return null;
+        try {
+            const cache = await this.open();
+            const res = await cache.match(this.key(hash));
+            if (!res)
+                return null;
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Store shard bytes under their hash. Best-effort. */
+    async put(hash, bytes) {
+        if (!ShardCache.available())
+            return;
+        try {
+            const cache = await this.open();
+            await cache.put(this.key(hash), new Response(bytes, {
+                headers: { "content-type": "application/octet-stream" },
+            }));
+        }
+        catch {
+            /* quota / unavailable — degrade to online-only for this shard */
+        }
+    }
+    /** Whether a shard is present in the cache. */
+    async has(hash) {
+        if (!ShardCache.available())
+            return false;
+        try {
+            const cache = await this.open();
+            return Boolean(await cache.match(this.key(hash)));
+        }
+        catch {
+            return false;
+        }
+    }
+}
+
+/**
+ * `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.
  *
@@ -8541,6 +9434,17 @@ class SpaceNamespace {
                 : 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. */
@@ -9304,82 +10208,6 @@ class SnapshotNamespace {
     }
 }
 
-/**
- * `ShardCache` — a Cache-API-backed store for file-shard bytes. Shards are
- * content-addressed (the key IS the SHA-256 of the ciphertext), so caching them
- * is uniquely safe: a cache hit is self-validating, immutable, and shareable
- * across files. The Cache API (rather than IndexedDB) is the right home for
- * large binary blobs — it streams, it's purpose-built for response bodies, and
- * it has its own eviction.
- *
- * Keys are SYNTHETIC absolute URLs (`https://shard.muhkoo.local/<hash>`) rather
- * than the real shard endpoint, so the cache is addressable by hash alone — the
- * sync engine can re-PUT a deferred shard knowing only its hash, without
- * reconstructing the accelerator URL. We never fetch these synthetic URLs; they
- * exist only as cache keys.
- *
- * Every method degrades to a no-op / null where the Cache API is unavailable
- * (Node, Workers, insecure contexts), so callers don't need to branch.
- */
-const CACHE_NAME = "muhkoo-shards-v1";
-class ShardCache {
-    static available() {
-        try {
-            return typeof caches !== "undefined";
-        }
-        catch {
-            return false;
-        }
-    }
-    key(hash) {
-        return `https://shard.muhkoo.local/${encodeURIComponent(hash)}`;
-    }
-    open() {
-        return caches.open(CACHE_NAME);
-    }
-    /** Cached shard bytes, or `null` on miss / when unavailable. */
-    async get(hash) {
-        if (!ShardCache.available())
-            return null;
-        try {
-            const cache = await this.open();
-            const res = await cache.match(this.key(hash));
-            if (!res)
-                return null;
-            return new Uint8Array(await res.arrayBuffer());
-        }
-        catch {
-            return null;
-        }
-    }
-    /** Store shard bytes under their hash. Best-effort. */
-    async put(hash, bytes) {
-        if (!ShardCache.available())
-            return;
-        try {
-            const cache = await this.open();
-            await cache.put(this.key(hash), new Response(bytes, {
-                headers: { "content-type": "application/octet-stream" },
-            }));
-        }
-        catch {
-            /* quota / unavailable — degrade to online-only for this shard */
-        }
-    }
-    /** Whether a shard is present in the cache. */
-    async has(hash) {
-        if (!ShardCache.available())
-            return false;
-        try {
-            const cache = await this.open();
-            return Boolean(await cache.match(this.key(hash)));
-        }
-        catch {
-            return false;
-        }
-    }
-}
-
 /**
  * IndexedDB schema for the offline layer — the single source of truth for the
  * database name, version, and object stores. Bump {@link DB_VERSION} whenever
@@ -10102,6 +10930,7 @@ class Client {
             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 });
@@ -10523,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, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, provisionalHandle, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+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