@muhkoo/connect 0.15.0-alpha.1 → 0.15.0-alpha.2

package/dist/browser/blockEngine.worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"blockEngine.worker.js","sources":["../../src/p2p/worker/protocol.ts","../../src/p2p/worker/blockEngine.ts","../../src/offline/cache/ShardCache.ts","../../src/utilities/bytes.ts","../../src/storage/transport/ShardClient.ts","../../src/p2p/worker/blockEngine.worker.ts"],"sourcesContent":["/**\n * Bitswap-lite wire protocol for peer block exchange. Four frame types over a\n * {@link ../transport/PeerTransport} data channel:\n *\n *   WANT(hash)         — \"does anyone have this block?\" / \"send it to me\"\n *   HAVE(hash)         — \"I hold this block\" (announce / reply to a WANT)\n *   BLOCK(hash, bytes) — the block itself (verified by hash on receipt)\n *   CANCEL(hash)       — \"stop, I got it elsewhere\"\n *\n * Frames are compact binary so a 4 MiB shard isn't base64-bloated through JSON:\n *\n *   byte 0      : type (0 WANT | 1 HAVE | 2 BLOCK | 3 CANCEL)\n *   bytes 1..33 : 32-byte raw SHA-256 of the block (our shard hash, hex-decoded)\n *   bytes 33..  : payload (BLOCK only)\n *\n * Blocks are AES-GCM ciphertext, so a frame carries nothing readable; the hash\n * is the capability check (the receiver re-hashes the payload and drops a\n * mismatch). See {@link ./blockEngine}.\n */\n\nexport enum FrameType {\n    WANT = 0,\n    HAVE = 1,\n    BLOCK = 2,\n    CANCEL = 3,\n}\n\nexport interface DecodedFrame {\n    type: FrameType;\n    /** Lowercase hex SHA-256 (matches `shardHash`). */\n    hash: string;\n    /** Present only for {@link FrameType.BLOCK}. */\n    payload?: Uint8Array;\n}\n\nconst HASH_BYTES = 32;\nconst HEADER = 1 + HASH_BYTES; // type + hash\n\nfunction hexToBytes(hex: string): Uint8Array {\n    if (hex.length !== HASH_BYTES * 2) {\n        throw new Error(`protocol: expected a ${HASH_BYTES}-byte hex hash, got ${hex.length / 2} bytes`);\n    }\n    const out = new Uint8Array(HASH_BYTES);\n    for (let i = 0; i < HASH_BYTES; i++) out[i] = parseInt(hex.substr(i * 2, 2), 16);\n    return out;\n}\n\nconst HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, \"0\"));\nfunction bytesToHex(bytes: Uint8Array): string {\n    let s = \"\";\n    for (let i = 0; i < bytes.length; i++) s += HEX[bytes[i]];\n    return s;\n}\n\nfunction header(type: FrameType, hash: string, extra = 0): { buf: Uint8Array; offset: number } {\n    const buf = new Uint8Array(HEADER + extra);\n    buf[0] = type;\n    buf.set(hexToBytes(hash), 1);\n    return { buf, offset: HEADER };\n}\n\nexport function encodeWant(hash: string): Uint8Array {\n    return header(FrameType.WANT, hash).buf;\n}\n\nexport function encodeHave(hash: string): Uint8Array {\n    return header(FrameType.HAVE, hash).buf;\n}\n\nexport function encodeCancel(hash: string): Uint8Array {\n    return header(FrameType.CANCEL, hash).buf;\n}\n\nexport function encodeBlock(hash: string, payload: Uint8Array): Uint8Array {\n    const { buf, offset } = header(FrameType.BLOCK, hash, payload.length);\n    buf.set(payload, offset);\n    return buf;\n}\n\nexport function decode(frame: Uint8Array): DecodedFrame {\n    if (frame.length < HEADER) throw new Error(\"protocol: frame too short\");\n    const type = frame[0] as FrameType;\n    const hash = bytesToHex(frame.subarray(1, HEADER));\n    if (type === FrameType.BLOCK) {\n        // Copy the payload out so it doesn't alias a transferred/pooled buffer.\n        return { type, hash, payload: frame.slice(HEADER) };\n    }\n    return { type, hash };\n}\n","/**\n * `BlockEngine` — the bitswap-lite want/have ledger. Host-agnostic: it speaks\n * only to a {@link BlockStore} (get/put/has) and an `out` sink that ships\n * encoded frames to a peer (or `\"*\"` to broadcast). The host wires `out` and\n * `handleFrame` to a real transport — on the main thread or inside the Web\n * Worker (see {@link ./engineClient}) — so this class is pure and unit-testable.\n *\n * It never sees keys: blocks are AES-GCM ciphertext, addressed by SHA-256. The\n * one trust check is integrity — an inbound BLOCK is re-hashed and dropped on\n * mismatch, so a malicious peer can't poison the store (the requester just\n * falls back to origin).\n */\n\nimport {\n    FrameType,\n    decode,\n    encodeWant,\n    encodeHave,\n    encodeBlock,\n    encodeCancel,\n} from \"./protocol\";\n\nexport interface BlockStore {\n    get(hash: string): Promise<Uint8Array | null>;\n    put(hash: string, bytes: Uint8Array): Promise<void>;\n    has(hash: string): Promise<boolean>;\n}\n\n/** Ship an encoded frame to one peer, or `\"*\"` for every connected peer. */\nexport type OutSink = (target: string | \"*\", frame: Uint8Array) => void;\n\n/** Lowercase hex SHA-256 of `bytes` — injected so tests can stub it. */\nexport type Hasher = (bytes: Uint8Array) => Promise<string>;\n\ninterface PendingWant {\n    resolvers: Array<(b: Uint8Array | null) => void>;\n    timer: ReturnType<typeof setTimeout>;\n}\n\nexport class BlockEngine {\n    private readonly wants = new Map<string, PendingWant>();\n\n    constructor(\n        private readonly store: BlockStore,\n        private readonly out: OutSink,\n        private readonly hash: Hasher,\n    ) {}\n\n    /**\n     * Ask the swarm for a block. Resolves with the verified bytes, or `null` on\n     * timeout (caller then falls back to origin). Returns immediately if we\n     * already hold it; concurrent wants for the same hash share one request.\n     */\n    want(hash: string, timeoutMs: number): Promise<Uint8Array | null> {\n        return new Promise((resolve) => {\n            void this.store.get(hash).then((local) => {\n                if (local) return resolve(local);\n                const existing = this.wants.get(hash);\n                if (existing) {\n                    existing.resolvers.push(resolve);\n                    return;\n                }\n                const timer = setTimeout(() => {\n                    const w = this.wants.get(hash);\n                    this.wants.delete(hash);\n                    this.out(\"*\", encodeCancel(hash));\n                    w?.resolvers.forEach((r) => r(null));\n                }, timeoutMs);\n                this.wants.set(hash, { resolvers: [resolve], timer });\n                this.out(\"*\", encodeWant(hash));\n            });\n        });\n    }\n\n    /** Tell the swarm we now hold `hash` (so peers wanting it can pull from us). */\n    announce(hash: string): void {\n        this.out(\"*\", encodeHave(hash));\n    }\n\n    /** Handle one inbound frame from `peer`. */\n    async handleFrame(peer: string, frame: Uint8Array): Promise<void> {\n        let f;\n        try {\n            f = decode(frame);\n        } catch {\n            return; // malformed — ignore\n        }\n        switch (f.type) {\n            case FrameType.WANT: {\n                const bytes = await this.store.get(f.hash);\n                if (bytes) this.out(peer, encodeBlock(f.hash, bytes));\n                return;\n            }\n            case FrameType.HAVE: {\n                // A peer announced a block we're still waiting for → pull from them.\n                if (this.wants.has(f.hash)) this.out(peer, encodeWant(f.hash));\n                return;\n            }\n            case FrameType.BLOCK: {\n                const pending = this.wants.get(f.hash);\n                if (!pending || !f.payload) return; // unsolicited / empty — ignore\n                // Integrity: a peer can't poison the store. Drop a mismatch and\n                // keep waiting (the timeout will fall back to origin).\n                const got = await this.hash(f.payload);\n                if (got !== f.hash) return;\n                await this.store.put(f.hash, f.payload);\n                this.wants.delete(f.hash);\n                clearTimeout(pending.timer);\n                this.out(\"*\", encodeCancel(f.hash)); // others can stop sending\n                pending.resolvers.forEach((r) => r(f.payload!));\n                return;\n            }\n            case FrameType.CANCEL:\n                // We serve WANTs synchronously, so there's nothing in flight to\n                // cancel yet. Reserved for chunked-send cancellation later.\n                return;\n        }\n    }\n\n    /** Drop all pending waits (resolve null) — on teardown. */\n    close(): void {\n        for (const [, w] of this.wants) {\n            clearTimeout(w.timer);\n            w.resolvers.forEach((r) => r(null));\n        }\n        this.wants.clear();\n    }\n}\n\nexport default BlockEngine;\n","/**\n * `ShardCache` — a Cache-API-backed store for file-shard bytes. Shards are\n * content-addressed (the key IS the SHA-256 of the ciphertext), so caching them\n * is uniquely safe: a cache hit is self-validating, immutable, and shareable\n * across files. The Cache API (rather than IndexedDB) is the right home for\n * large binary blobs — it streams, it's purpose-built for response bodies, and\n * it has its own eviction.\n *\n * Keys are SYNTHETIC absolute URLs (`https://shard.muhkoo.local/<hash>`) rather\n * than the real shard endpoint, so the cache is addressable by hash alone — the\n * sync engine can re-PUT a deferred shard knowing only its hash, without\n * reconstructing the accelerator URL. We never fetch these synthetic URLs; they\n * exist only as cache keys.\n *\n * Every method degrades to a no-op / null where the Cache API is unavailable\n * (Node, Workers, insecure contexts), so callers don't need to branch.\n */\n\nconst CACHE_NAME = \"muhkoo-shards-v1\";\n\nexport class ShardCache {\n    static available(): boolean {\n        try {\n            return typeof caches !== \"undefined\";\n        } catch {\n            return false;\n        }\n    }\n\n    private key(hash: string): string {\n        return `https://shard.muhkoo.local/${encodeURIComponent(hash)}`;\n    }\n\n    private open(): Promise<Cache> {\n        return caches.open(CACHE_NAME);\n    }\n\n    /** Cached shard bytes, or `null` on miss / when unavailable. */\n    async get(hash: string): Promise<Uint8Array | null> {\n        if (!ShardCache.available()) return null;\n        try {\n            const cache = await this.open();\n            const res = await cache.match(this.key(hash));\n            if (!res) return null;\n            return new Uint8Array(await res.arrayBuffer());\n        } catch {\n            return null;\n        }\n    }\n\n    /** Store shard bytes under their hash. Best-effort. */\n    async put(hash: string, bytes: Uint8Array): Promise<void> {\n        if (!ShardCache.available()) return;\n        try {\n            const cache = await this.open();\n            await cache.put(\n                this.key(hash),\n                new Response(bytes as BodyInit, {\n                    headers: { \"content-type\": \"application/octet-stream\" },\n                }),\n            );\n        } catch {\n            /* quota / unavailable — degrade to online-only for this shard */\n        }\n    }\n\n    /** Whether a shard is present in the cache. */\n    async has(hash: string): Promise<boolean> {\n        if (!ShardCache.available()) return false;\n        try {\n            const cache = await this.open();\n            return Boolean(await cache.match(this.key(hash)));\n        } catch {\n            return false;\n        }\n    }\n}\n\nexport default ShardCache;\n","/**\n * Byte conversion helpers usable in both Node and the browser.\n *\n * Replaces Node's `Buffer` API for the small set of operations we actually\n * need in the crypto layer: hex/base64/base64url encode + decode, and array\n * concatenation. Lets `DoubleRatchet`, `KeyStore`, etc. compile against\n * platforms without `Buffer` (browsers, CF Workers).\n */\n\nconst HEX_CHARS = \"0123456789abcdef\";\n\n/** Encode a byte array as a lowercase hex string. */\nexport function toHex(bytes: Uint8Array): string {\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    const b = bytes[i];\n    out += HEX_CHARS[b >> 4] + HEX_CHARS[b & 0x0f];\n  }\n  return out;\n}\n\n/** Decode a hex string into a byte array. Accepts upper/lowercase; rejects odd-length input. */\nexport function fromHex(hex: string): Uint8Array<ArrayBuffer> {\n  if (hex.length % 2 !== 0) {\n    throw new Error(`fromHex: input length must be even (got ${hex.length})`);\n  }\n  const ab = new ArrayBuffer(hex.length / 2);\n  const out = new Uint8Array(ab);\n  for (let i = 0; i < out.length; i++) {\n    const byte = parseInt(hex.substring(i * 2, i * 2 + 2), 16);\n    if (Number.isNaN(byte)) {\n      throw new Error(`fromHex: invalid hex character at offset ${i * 2}`);\n    }\n    out[i] = byte;\n  }\n  return out;\n}\n\n/** Encode a byte array as a standard base64 string. */\nexport function toBase64(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\n/** Decode a standard base64 string to bytes. */\nexport function fromBase64(b64: string): Uint8Array<ArrayBuffer> {\n  const binary = atob(b64);\n  const ab = new ArrayBuffer(binary.length);\n  const out = new Uint8Array(ab);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\n/** Encode a byte array as a base64url string (no padding). */\nexport function toBase64Url(bytes: Uint8Array): string {\n  return toBase64(bytes).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Decode a base64url string (with or without padding) to bytes. */\nexport function fromBase64Url(b64url: string): Uint8Array<ArrayBuffer> {\n  const padded = b64url.replace(/-/g, \"+\").replace(/_/g, \"/\") +\n    \"=\".repeat((4 - (b64url.length % 4)) % 4);\n  return fromBase64(padded);\n}\n\n/** Concatenate any number of byte arrays into a single Uint8Array. */\nexport function concatBytes(...arrays: (Uint8Array | ArrayBuffer)[]): Uint8Array<ArrayBuffer> {\n  let total = 0;\n  for (const a of arrays) total += a.byteLength;\n  const ab = new ArrayBuffer(total);\n  const out = new Uint8Array(ab);\n  let offset = 0;\n  for (const a of arrays) {\n    const view = a instanceof Uint8Array ? a : new Uint8Array(a);\n    out.set(view, offset);\n    offset += view.length;\n  }\n  return out;\n}\n\n/** Encode a UTF-8 string as bytes. Thin wrapper around TextEncoder for symmetry. */\nexport function utf8Encode(s: string): Uint8Array<ArrayBuffer> {\n  // TextEncoder.encode returns Uint8Array<ArrayBufferLike>; widen to the\n  // ArrayBuffer variant explicitly so WebCrypto's BufferSource type accepts it.\n  const u8 = new TextEncoder().encode(s);\n  const ab = new ArrayBuffer(u8.byteLength);\n  const out = new Uint8Array(ab);\n  out.set(u8);\n  return out;\n}\n\n/** Decode UTF-8 bytes to a string. */\nexport function utf8Decode(bytes: Uint8Array): string {\n  return new TextDecoder().decode(bytes);\n}\n","/**\n * HTTP client for the open content-addressed shard store.\n *\n * Each shard is named by the lowercase hex SHA-256 of its ciphertext bytes.\n * The server verifies the hash on PUT, so the address authenticates the\n * contents — there's no benefit to ACLing PUT/GET, and making them open\n * enables cross-user dedup down the line.\n *\n * Wire protocol:\n *   PUT  /api/shards/:hash    body: shard bytes (application/octet-stream)\n *                             200 { ok: true, hash, size, dedup: boolean }\n *                             400 if hash doesn't match body\n *\n *   GET  /api/shards/:hash    200 with shard bytes (application/octet-stream)\n *                             404 if absent\n *\n *   HEAD /api/shards/:hash    200 if present (no body) — used by callers to\n *                             skip a PUT they'd otherwise dedup-rewrite. The\n *                             server can ignore the optimization if it wants.\n */\n\nimport { toHex } from \"../../utilities/bytes\";\n\n/**\n * How long concurrent shard reads are gathered before one batch is sent.\n *\n * Long enough to collect what a concurrent directory walk issues at the same\n * moment, short enough that a single read does not feel it.\n */\nconst SHARD_BATCH_WINDOW_MS = 6;\n\n/** Hashes per batch. Must not exceed what the server will accept. */\nconst SHARD_BATCH_MAX = 256;\n\n/** Decode base64 without `atob`'s per-character loop cost on large shards. */\nfunction bytesFromBase64(b64: string): Uint8Array {\n    const binary = atob(b64);\n    const out = new Uint8Array(binary.length);\n    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n    return out;\n}\n\n/** Peer head-start (ms) before origin joins the race in {@link ShardClient.getShard}. */\nconst HEDGE_MS = 500;\n\n/**\n * A content-addressed byte cache for shards (the offline layer's `ShardCache`\n * satisfies this structurally). Declared here as a minimal interface so the\n * storage layer doesn't import the offline module — keeping the dependency\n * arrow one-way (offline → storage).\n */\nexport interface ShardByteCache {\n    get(hash: string): Promise<Uint8Array | null>;\n    put(hash: string, bytes: Uint8Array): Promise<void>;\n}\n\n/**\n * A peer block source (the p2p layer's `PeerExchange` satisfies this\n * structurally). Consulted between the local cache and origin: a block fetched\n * from a peer is verified by hash before use. Declared here so the storage layer\n * doesn't import the p2p module (dependency arrow stays p2p → storage).\n */\nexport interface PeerBlockSource {\n    getBlock(hash: string, opts?: { timeoutMs?: number }): Promise<Uint8Array | null>;\n    announce(hash: string): void;\n}\n\nexport interface ShardClientOptions {\n    /** Base URL of the accelerator (e.g. `https://muhkoo-accelerator.workers.dev`). */\n    baseUrl: string;\n    /**\n     * Path prefix for the shard endpoints, joined to `baseUrl` before the\n     * hash. Defaults to `/api/shards`, which targets a global shard store\n     * (e.g. a dedicated `ShardStoreDO`). Pass a room-scoped value like\n     * `/api/spaces/{roomId}/shards` to keep shards bound to a specific\n     * `SharedSpaceDO` — that's the path the chat application uses today.\n     *\n     * Leading slash optional; trailing slash stripped. The final URL is\n     * always `${baseUrl}${normalizedPrefix}/${encodeURIComponent(hash)}`.\n     */\n    pathPrefix?: string;\n    /**\n     * Optional custom fetch implementation. Defaults to `globalThis.fetch`.\n     * Provided so callers can inject retries / auth / instrumentation.\n     */\n    fetch?: typeof fetch;\n    /**\n     * Optional offline byte cache. When present, GETs are served cache-first and\n     * populated on success, and PUTs write the cache before the network so a\n     * just-uploaded file reads back offline. See {@link ShardByteCache}.\n     */\n    cache?: ShardByteCache;\n    /**\n     * Coalesce concurrent origin reads into `POST {pathPrefix}/batch`. On by\n     * default: it is what keeps opening a project from costing one request per\n     * shard. Set false to force one-at-a-time — useful against a server without\n     * the route, though that is detected and handled automatically.\n     */\n    batchShards?: boolean;\n    /**\n     * Called when a PUT can't reach the network (offline). Lets the caller queue\n     * the upload for replay on reconnect; the bytes are already in {@link cache}\n     * keyed by `hash`, so only the hash needs recording.\n     */\n    deferUpload?: (hash: string) => Promise<void>;\n    /**\n     * Optional peer block source. When present, GETs try peers between the local\n     * cache and origin (peer blocks are verified by hash); PUTs announce the new\n     * block to peers. Best-effort — any failure falls through to origin.\n     */\n    peers?: PeerBlockSource;\n    /**\n     * When true, {@link ShardClient.putShard} returns as soon as the shard is\n     * written to {@link cache} and announced to {@link peers} — the origin PUT is\n     * fired in the BACKGROUND rather than awaited. This makes a large write's\n     * manifest available immediately (so a peer/worker can start pulling the\n     * shards over P2P right away) while origin catches up as a durable fallback.\n     * On a background-PUT failure the shard is handed to {@link deferUpload} (if\n     * present) for replay. Requires a {@link cache} so the bytes survive locally\n     * until the background upload lands. No-op without a cache.\n     */\n    backgroundUpload?: boolean;\n}\n\n/**\n * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in\n * every runtime this SDK targets.\n */\nexport async function shardHash(bytes: Uint8Array): Promise<string> {\n    const subtle = (globalThis.crypto as Crypto | undefined)?.subtle;\n    if (!subtle) {\n        throw new Error(\"shardHash: `globalThis.crypto.subtle` is unavailable in this runtime.\");\n    }\n    const digest = await subtle.digest(\"SHA-256\", bytes as BufferSource);\n    return toHex(new Uint8Array(digest));\n}\n\nexport class ShardClient {\n    private readonly baseUrl: string;\n    private readonly pathPrefix: string;\n    private readonly fetchFn: typeof fetch;\n    private readonly cache?: ShardByteCache;\n    /** Hashes waiting for the next batch, each with everyone awaiting it. */\n    private pendingShards!: Map<string, Array<{ resolve: (v: Uint8Array | null) => void; reject: (e: unknown) => void }>>;\n    private batchTimer!: ReturnType<typeof setTimeout> | null;\n    /** False once the server is known not to have the batch route. */\n    private batchSupported!: boolean;\n    private readonly deferUpload?: (hash: string) => Promise<void>;\n    private readonly peers?: PeerBlockSource;\n    private readonly backgroundUpload: boolean;\n\n    constructor(opts: ShardClientOptions) {\n        if (!opts?.baseUrl) throw new Error(\"ShardClient: `baseUrl` is required\");\n        // Strip trailing slash so url concatenation stays clean.\n        this.baseUrl = opts.baseUrl.replace(/\\/+$/, \"\");\n        // Normalize prefix to leading-slash + no-trailing-slash form so the\n        // URL builder can blindly append `/{hash}`.\n        const rawPrefix = opts.pathPrefix ?? \"/api/shards\";\n        const withSlash = rawPrefix.startsWith(\"/\") ? rawPrefix : `/${rawPrefix}`;\n        this.pathPrefix = withSlash.replace(/\\/+$/, \"\");\n        const f = opts.fetch ?? globalThis.fetch;\n        if (typeof f !== \"function\") {\n            throw new Error(\"ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.\");\n        }\n        this.fetchFn = f.bind(globalThis);\n        this.cache = opts.cache;\n        // Coalescing state. `batchSupported` latches false against a deployment\n        // without the batch route, so we degrade once rather than per request.\n        this.pendingShards = new Map();\n        this.batchTimer = null;\n        this.batchSupported = opts.batchShards !== false;\n        this.deferUpload = opts.deferUpload;\n        this.peers = opts.peers;\n        // Background upload needs a local cache to hold the bytes until the PUT\n        // lands; without one it would race the reader against a not-yet-uploaded\n        // origin, so we quietly ignore the flag when there's no cache.\n        this.backgroundUpload = Boolean(opts.backgroundUpload && opts.cache);\n    }\n\n    /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */\n    urlForHash(hash: string): string {\n        return `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(hash)}`;\n    }\n\n    /**\n     * Upload a shard. The server verifies SHA-256(body) matches `:hash` and\n     * rejects with 400 if not, so the caller is the source of truth on\n     * naming. Re-uploading an existing shard is idempotent — the server\n     * returns `dedup: true` in that case.\n     */\n    async putShard(hash: string, bytes: Uint8Array): Promise<{ dedup: boolean }> {\n        const url = this.urlForHash(hash);\n        // Write the cache first so a just-uploaded file reads back even if the\n        // network PUT then fails (offline). The bytes are content-addressed, so\n        // this is safe to keep regardless of upload outcome.\n        if (this.cache) await this.cache.put(hash, bytes);\n        // Tell the swarm we now hold this block, so peers can pull it from us.\n        if (this.peers) this.peers.announce(hash);\n        // Background mode: the bytes are cached + announced, so return now and let\n        // origin catch up asynchronously (a peer can already pull this block). The\n        // PUT is enqueued through a bounded worker pool so a big file doesn't fire\n        // hundreds of concurrent uploads at once.\n        if (this.backgroundUpload) {\n            this.enqueueBackgroundUpload(url, hash);\n            return { dedup: false };\n        }\n        let response: Response;\n        try {\n            response = await this.fetchFn(url, {\n                method: \"PUT\",\n                headers: { \"content-type\": \"application/octet-stream\" },\n                // BufferSource is what fetch's body expects; a Uint8Array satisfies it.\n                body: bytes as BodyInit,\n            });\n        } catch (err) {\n            // Network unreachable (offline). If a defer hook is wired, queue the\n            // upload for replay and report success — the bytes are cached.\n            if (this.deferUpload) {\n                await this.deferUpload(hash);\n                return { dedup: false };\n            }\n            throw err;\n        }\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);\n        }\n        let dedup = false;\n        try {\n            const json = (await response.json()) as { dedup?: boolean };\n            dedup = Boolean(json?.dedup);\n        } catch {\n            // Server returned 200 with no body — treat as fresh upload.\n        }\n        return { dedup };\n    }\n\n    // ── bounded background-upload pool (backgroundUpload mode) ──\n    private bgActive = 0;\n    private readonly bgQueue: Array<() => void> = [];\n    private static readonly BG_CONCURRENCY = 6;\n\n    /** Queue a shard's origin PUT to run in the background under a concurrency\n     *  cap. Bytes are re-read from {@link cache} at upload time (not held in the\n     *  queue) so a large file's backlog doesn't pin a second copy in memory. */\n    private enqueueBackgroundUpload(url: string, hash: string): void {\n        const run = async () => {\n            this.bgActive++;\n            try {\n                const bytes = this.cache ? await this.cache.get(hash) : null;\n                if (bytes) await this.uploadToOrigin(url, hash, bytes);\n            } catch {\n                // Origin unreachable/failed — queue for replay if we can; otherwise\n                // the block is still cached + peer-served, so a later re-PUT covers it.\n                if (this.deferUpload) { try { await this.deferUpload(hash); } catch { /* best-effort */ } }\n            } finally {\n                this.bgActive--;\n                const next = this.bgQueue.shift();\n                if (next) next();\n            }\n        };\n        if (this.bgActive < ShardClient.BG_CONCURRENCY) void run();\n        else this.bgQueue.push(() => void run());\n    }\n\n    /** PUT the shard bytes to origin, verifying the server accepted them.\n     *  Used by the background-upload path; throws on network/HTTP failure. */\n    private async uploadToOrigin(url: string, hash: string, bytes: Uint8Array): Promise<void> {\n        const response = await this.fetchFn(url, {\n            method: \"PUT\",\n            headers: { \"content-type\": \"application/octet-stream\" },\n            body: bytes as BodyInit,\n        });\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);\n        }\n    }\n\n    /**\n     * Fetch a shard by hash. Throws if the server returns a non-200; returns\n     * `null` for 404 so callers can distinguish \"missing\" from \"errored\".\n     */\n    async getShard(hash: string): Promise<Uint8Array | null> {\n        // Cache-first: a hit is content-verified by construction (key == hash).\n        if (this.cache) {\n            const cached = await this.cache.get(hash);\n            if (cached) return cached;\n        }\n        // No peers → straight to origin.\n        if (!this.peers) return this.fetchFromOrigin(hash);\n\n        // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow\n        // or missing peer stall delivery — give the peer a short head start, then\n        // start origin in parallel and take whichever returns the block first.\n        const peers = this.peers;\n        return new Promise<Uint8Array | null>((resolve, reject) => {\n            let done = false;\n            let originStarted = false;\n            let timer: ReturnType<typeof setTimeout> | null = null;\n            const win = (b: Uint8Array | null) => {\n                if (done) return;\n                done = true;\n                if (timer) clearTimeout(timer);\n                resolve(b);\n            };\n            const fail = (e: unknown) => {\n                if (!done) { done = true; reject(e); }\n            };\n            const startOrigin = () => {\n                if (originStarted || done) return;\n                originStarted = true;\n                if (timer) { clearTimeout(timer); timer = null; }\n                this.fetchFromOrigin(hash).then(win, fail);\n            };\n            timer = setTimeout(startOrigin, HEDGE_MS);\n            peers.getBlock(hash).then(\n                (b) => {\n                    if (b) {\n                        if (this.cache) void this.cache.put(hash, b);\n                        win(b); // peer delivered first\n                    } else {\n                        startOrigin(); // peer miss → don't wait out the hedge\n                    }\n                },\n                () => startOrigin(), // peer error → origin now\n            );\n        });\n    }\n\n    /**\n     * Fetch from origin, COALESCING concurrent requests into one batch.\n     *\n     * A shard is not a file. A project is thousands of small source modules,\n     * each split into shards, so reading one at a time made opening a project\n     * cost thousands of requests — 2,086 for a 519-file project. Latency, not\n     * bytes, is what that spends: Chromium took 18.4s over those requests and\n     * Brave, which filters every one, took 37.5s for identical work. Batching\n     * collapses whatever is in flight at the same moment into a single POST,\n     * which is why it helps most exactly where it hurt most.\n     *\n     * Callers are unchanged: `getShard` still asks for one shard and gets one\n     * shard. The window is a few milliseconds — long enough to gather the reads\n     * a concurrent walk issues together, short enough not to be felt by a lone\n     * read.\n     *\n     * Falls back permanently to one-at-a-time if the server has no batch route,\n     * so a new SDK keeps working against an older deployment.\n     */\n    private fetchFromOrigin(hash: string): Promise<Uint8Array | null> {\n        if (!this.batchSupported) return this.fetchOneFromOrigin(hash);\n        return new Promise<Uint8Array | null>((resolve, reject) => {\n            const waiting = this.pendingShards.get(hash);\n            if (waiting) { waiting.push({ resolve, reject }); return; }\n            this.pendingShards.set(hash, [{ resolve, reject }]);\n            if (this.batchTimer === null) {\n                this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);\n            }\n        });\n    }\n\n    /** Send one batch of whatever has accumulated, and settle those callers. */\n    private async flushShardBatch(): Promise<void> {\n        this.batchTimer = null;\n        if (this.pendingShards.size === 0) return;\n\n        const hashes = [...this.pendingShards.keys()].slice(0, SHARD_BATCH_MAX);\n        const waiters = hashes.map((h) => {\n            const w = this.pendingShards.get(h)!;\n            this.pendingShards.delete(h);\n            return [h, w] as const;\n        });\n        // Anything over the cap waits for the next window rather than being\n        // dropped or silently truncated.\n        if (this.pendingShards.size > 0 && this.batchTimer === null) {\n            this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);\n        }\n\n        let shards: Record<string, string>;\n        try {\n            const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {\n                method: \"POST\",\n                headers: { \"Content-Type\": \"application/json\" },\n                body: JSON.stringify({ hashes }),\n            });\n            if (res.status === 404 || res.status === 405) {\n                // No batch route on this deployment. Stop trying, and serve\n                // everyone individually — including the batch we just gathered.\n                this.batchSupported = false;\n                for (const [h, ws] of waiters) {\n                    this.fetchOneFromOrigin(h).then(\n                        (b) => ws.forEach((w) => w.resolve(b)),\n                        (e) => ws.forEach((w) => w.reject(e)),\n                    );\n                }\n                return;\n            }\n            if (!res.ok) throw new Error(`ShardClient batch failed (${res.status}): ${await safeText(res)}`);\n            const parsed: unknown = await res.json().catch(() => null);\n            // A 200 is not proof the batch route exists. A catch-all handler, a\n            // proxy, or an older deployment can answer this POST with something\n            // else entirely, and trusting the shape would resolve every hash to\n            // `null` — reads silently returning \"missing\" for shards that are\n            // right there. Anything not shaped like a batch reply is treated as\n            // \"no batch route\", exactly like a 404.\n            const candidate = (parsed as { shards?: unknown } | null)?.shards;\n            if (!candidate || typeof candidate !== \"object\") {\n                this.batchSupported = false;\n                for (const [h, ws] of waiters) {\n                    this.fetchOneFromOrigin(h).then(\n                        (b) => ws.forEach((w) => w.resolve(b)),\n                        (e) => ws.forEach((w) => w.reject(e)),\n                    );\n                }\n                return;\n            }\n            shards = candidate as Record<string, string>;\n        } catch (err) {\n            // Offline with a cache behaves as it does for a single fetch: report\n            // absence so Reed-Solomon recovery can still be attempted.\n            for (const [, ws] of waiters) {\n                if (this.cache) ws.forEach((w) => w.resolve(null));\n                else ws.forEach((w) => w.reject(err));\n            }\n            return;\n        }\n\n        for (const [hash, ws] of waiters) {\n            const b64 = shards[hash];\n            if (typeof b64 !== \"string\") { ws.forEach((w) => w.resolve(null)); continue; }\n            let bytes: Uint8Array;\n            try { bytes = bytesFromBase64(b64); }\n            catch (e) { ws.forEach((w) => w.reject(e)); continue; }\n            if (this.cache) void this.cache.put(hash, bytes);\n            ws.forEach((w) => w.resolve(bytes));\n        }\n    }\n\n    /** Fetch a shard from origin. Returns `null` for 404 (or offline when a\n     *  cache is present, so RS recovery can proceed); throws otherwise. */\n    private async fetchOneFromOrigin(hash: string): Promise<Uint8Array | null> {\n        const url = this.urlForHash(hash);\n        let response: Response;\n        try {\n            response = await this.fetchFn(url, { method: \"GET\" });\n        } catch (err) {\n            if (this.cache) return null;\n            throw err;\n        }\n        if (response.status === 404) return null;\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);\n        }\n        const bytes = new Uint8Array(await response.arrayBuffer());\n        if (this.cache) void this.cache.put(hash, bytes);\n        return bytes;\n    }\n\n    /**\n     * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise\n     * dedup-rewrite. The server can implement this as a HEAD or return a small\n     * JSON body — we don't depend on either.\n     */\n    async hasShard(hash: string): Promise<boolean> {\n        const url = this.urlForHash(hash);\n        const response = await this.fetchFn(url, { method: \"HEAD\" });\n        return response.status === 200;\n    }\n}\n\nasync function safeText(response: Response): Promise<string> {\n    try { return await response.text(); } catch { return \"\"; }\n}\n","/**\n * Dedicated Web Worker entry that hosts a {@link ./blockEngine.BlockEngine}. The\n * blockstore is the Cache-API-backed {@link ../../offline/cache/ShardCache}\n * (the Cache API is available in workers and origin-scoped, so it's the *same*\n * store the main thread reads), and hashing uses {@link\n * ../../storage/transport/ShardClient.shardHash}.\n *\n * Message protocol (see {@link ./engineClient.WorkerEngineHost}):\n *   in : {t:\"frame\",peer,data} | {t:\"want\",id,hash,timeout} | {t:\"announce\",hash} | {t:\"close\"}\n *   out: {t:\"out\",target,data}  | {t:\"want-result\",id,data}\n *\n * Consumers instantiate this with a bundler-resolved URL, e.g.\n *   new Worker(new URL(\"@muhkoo/connect/dist/.../blockEngine.worker.js\", import.meta.url), { type: \"module\" })\n * and pass `() => that worker` as `workerFactory` to the client's p2p options.\n */\n\nimport { BlockEngine } from \"./blockEngine\";\nimport { ShardCache } from \"../../offline/cache/ShardCache\";\nimport { shardHash } from \"../../storage/transport/ShardClient\";\n\n/** Minimal worker-scope shape (avoids needing the WebWorker tsconfig lib). */\ninterface WorkerScope {\n    onmessage: ((e: MessageEvent) => void) | null;\n    postMessage(message: unknown, transfer?: Transferable[]): void;\n}\nconst ctx = self as unknown as WorkerScope;\n\nconst engine = new BlockEngine(\n    new ShardCache(),\n    (target, frame) => {\n        const buf = frame.buffer as ArrayBuffer;\n        ctx.postMessage({ t: \"out\", target, data: buf }, [buf]);\n    },\n    shardHash,\n);\n\nctx.onmessage = (e: MessageEvent) => {\n    const m = e.data as\n        | { t: \"frame\"; peer: string; data: ArrayBuffer }\n        | { t: \"want\"; id: number; hash: string; timeout: number }\n        | { t: \"announce\"; hash: string }\n        | { t: \"close\" };\n\n    if (m.t === \"frame\") {\n        void engine.handleFrame(m.peer, new Uint8Array(m.data));\n    } else if (m.t === \"want\") {\n        void engine.want(m.hash, m.timeout).then((bytes) => {\n            const buf = bytes ? (bytes.buffer as ArrayBuffer) : null;\n            ctx.postMessage({ t: \"want-result\", id: m.id, data: buf }, buf ? [buf] : []);\n        });\n    } else if (m.t === \"announce\") {\n        engine.announce(m.hash);\n    } else if (m.t === \"close\") {\n        engine.close();\n    }\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"blockEngine.worker.js","sources":["../../src/p2p/worker/protocol.ts","../../src/p2p/worker/blockEngine.ts","../../src/offline/cache/ShardCache.ts","../../src/utilities/bytes.ts","../../src/storage/transport/ShardClient.ts","../../src/p2p/worker/blockEngine.worker.ts"],"sourcesContent":["/**\n * Bitswap-lite wire protocol for peer block exchange. Four frame types over a\n * {@link ../transport/PeerTransport} data channel:\n *\n *   WANT(hash)         — \"does anyone have this block?\" / \"send it to me\"\n *   HAVE(hash)         — \"I hold this block\" (announce / reply to a WANT)\n *   BLOCK(hash, bytes) — the block itself (verified by hash on receipt)\n *   CANCEL(hash)       — \"stop, I got it elsewhere\"\n *\n * Frames are compact binary so a 4 MiB shard isn't base64-bloated through JSON:\n *\n *   byte 0      : type (0 WANT | 1 HAVE | 2 BLOCK | 3 CANCEL)\n *   bytes 1..33 : 32-byte raw SHA-256 of the block (our shard hash, hex-decoded)\n *   bytes 33..  : payload (BLOCK only)\n *\n * Blocks are AES-GCM ciphertext, so a frame carries nothing readable; the hash\n * is the capability check (the receiver re-hashes the payload and drops a\n * mismatch). See {@link ./blockEngine}.\n */\n\nexport enum FrameType {\n    WANT = 0,\n    HAVE = 1,\n    BLOCK = 2,\n    CANCEL = 3,\n}\n\nexport interface DecodedFrame {\n    type: FrameType;\n    /** Lowercase hex SHA-256 (matches `shardHash`). */\n    hash: string;\n    /** Present only for {@link FrameType.BLOCK}. */\n    payload?: Uint8Array;\n}\n\nconst HASH_BYTES = 32;\nconst HEADER = 1 + HASH_BYTES; // type + hash\n\nfunction hexToBytes(hex: string): Uint8Array {\n    if (hex.length !== HASH_BYTES * 2) {\n        throw new Error(`protocol: expected a ${HASH_BYTES}-byte hex hash, got ${hex.length / 2} bytes`);\n    }\n    const out = new Uint8Array(HASH_BYTES);\n    for (let i = 0; i < HASH_BYTES; i++) out[i] = parseInt(hex.substr(i * 2, 2), 16);\n    return out;\n}\n\nconst HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, \"0\"));\nfunction bytesToHex(bytes: Uint8Array): string {\n    let s = \"\";\n    for (let i = 0; i < bytes.length; i++) s += HEX[bytes[i]];\n    return s;\n}\n\nfunction header(type: FrameType, hash: string, extra = 0): { buf: Uint8Array; offset: number } {\n    const buf = new Uint8Array(HEADER + extra);\n    buf[0] = type;\n    buf.set(hexToBytes(hash), 1);\n    return { buf, offset: HEADER };\n}\n\nexport function encodeWant(hash: string): Uint8Array {\n    return header(FrameType.WANT, hash).buf;\n}\n\nexport function encodeHave(hash: string): Uint8Array {\n    return header(FrameType.HAVE, hash).buf;\n}\n\nexport function encodeCancel(hash: string): Uint8Array {\n    return header(FrameType.CANCEL, hash).buf;\n}\n\nexport function encodeBlock(hash: string, payload: Uint8Array): Uint8Array {\n    const { buf, offset } = header(FrameType.BLOCK, hash, payload.length);\n    buf.set(payload, offset);\n    return buf;\n}\n\nexport function decode(frame: Uint8Array): DecodedFrame {\n    if (frame.length < HEADER) throw new Error(\"protocol: frame too short\");\n    const type = frame[0] as FrameType;\n    const hash = bytesToHex(frame.subarray(1, HEADER));\n    if (type === FrameType.BLOCK) {\n        // Copy the payload out so it doesn't alias a transferred/pooled buffer.\n        return { type, hash, payload: frame.slice(HEADER) };\n    }\n    return { type, hash };\n}\n","/**\n * `BlockEngine` — the bitswap-lite want/have ledger. Host-agnostic: it speaks\n * only to a {@link BlockStore} (get/put/has) and an `out` sink that ships\n * encoded frames to a peer (or `\"*\"` to broadcast). The host wires `out` and\n * `handleFrame` to a real transport — on the main thread or inside the Web\n * Worker (see {@link ./engineClient}) — so this class is pure and unit-testable.\n *\n * It never sees keys: blocks are AES-GCM ciphertext, addressed by SHA-256. The\n * one trust check is integrity — an inbound BLOCK is re-hashed and dropped on\n * mismatch, so a malicious peer can't poison the store (the requester just\n * falls back to origin).\n */\n\nimport {\n    FrameType,\n    decode,\n    encodeWant,\n    encodeHave,\n    encodeBlock,\n    encodeCancel,\n} from \"./protocol\";\n\nexport interface BlockStore {\n    get(hash: string): Promise<Uint8Array | null>;\n    put(hash: string, bytes: Uint8Array): Promise<void>;\n    has(hash: string): Promise<boolean>;\n}\n\n/** Ship an encoded frame to one peer, or `\"*\"` for every connected peer. */\nexport type OutSink = (target: string | \"*\", frame: Uint8Array) => void;\n\n/** Lowercase hex SHA-256 of `bytes` — injected so tests can stub it. */\nexport type Hasher = (bytes: Uint8Array) => Promise<string>;\n\ninterface PendingWant {\n    resolvers: Array<(b: Uint8Array | null) => void>;\n    timer: ReturnType<typeof setTimeout>;\n}\n\nexport class BlockEngine {\n    private readonly wants = new Map<string, PendingWant>();\n\n    constructor(\n        private readonly store: BlockStore,\n        private readonly out: OutSink,\n        private readonly hash: Hasher,\n    ) {}\n\n    /**\n     * Ask the swarm for a block. Resolves with the verified bytes, or `null` on\n     * timeout (caller then falls back to origin). Returns immediately if we\n     * already hold it; concurrent wants for the same hash share one request.\n     */\n    want(hash: string, timeoutMs: number): Promise<Uint8Array | null> {\n        return new Promise((resolve) => {\n            void this.store.get(hash).then((local) => {\n                if (local) return resolve(local);\n                const existing = this.wants.get(hash);\n                if (existing) {\n                    existing.resolvers.push(resolve);\n                    return;\n                }\n                const timer = setTimeout(() => {\n                    const w = this.wants.get(hash);\n                    this.wants.delete(hash);\n                    this.out(\"*\", encodeCancel(hash));\n                    w?.resolvers.forEach((r) => r(null));\n                }, timeoutMs);\n                this.wants.set(hash, { resolvers: [resolve], timer });\n                this.out(\"*\", encodeWant(hash));\n            });\n        });\n    }\n\n    /** Tell the swarm we now hold `hash` (so peers wanting it can pull from us). */\n    announce(hash: string): void {\n        this.out(\"*\", encodeHave(hash));\n    }\n\n    /** Handle one inbound frame from `peer`. */\n    async handleFrame(peer: string, frame: Uint8Array): Promise<void> {\n        let f;\n        try {\n            f = decode(frame);\n        } catch {\n            return; // malformed — ignore\n        }\n        switch (f.type) {\n            case FrameType.WANT: {\n                const bytes = await this.store.get(f.hash);\n                if (bytes) this.out(peer, encodeBlock(f.hash, bytes));\n                return;\n            }\n            case FrameType.HAVE: {\n                // A peer announced a block we're still waiting for → pull from them.\n                if (this.wants.has(f.hash)) this.out(peer, encodeWant(f.hash));\n                return;\n            }\n            case FrameType.BLOCK: {\n                const pending = this.wants.get(f.hash);\n                if (!pending || !f.payload) return; // unsolicited / empty — ignore\n                // Integrity: a peer can't poison the store. Drop a mismatch and\n                // keep waiting (the timeout will fall back to origin).\n                const got = await this.hash(f.payload);\n                if (got !== f.hash) return;\n                await this.store.put(f.hash, f.payload);\n                this.wants.delete(f.hash);\n                clearTimeout(pending.timer);\n                this.out(\"*\", encodeCancel(f.hash)); // others can stop sending\n                pending.resolvers.forEach((r) => r(f.payload!));\n                return;\n            }\n            case FrameType.CANCEL:\n                // We serve WANTs synchronously, so there's nothing in flight to\n                // cancel yet. Reserved for chunked-send cancellation later.\n                return;\n        }\n    }\n\n    /** Drop all pending waits (resolve null) — on teardown. */\n    close(): void {\n        for (const [, w] of this.wants) {\n            clearTimeout(w.timer);\n            w.resolvers.forEach((r) => r(null));\n        }\n        this.wants.clear();\n    }\n}\n\nexport default BlockEngine;\n","/**\n * `ShardCache` — a Cache-API-backed store for file-shard bytes. Shards are\n * content-addressed (the key IS the SHA-256 of the ciphertext), so caching them\n * is uniquely safe: a cache hit is self-validating, immutable, and shareable\n * across files. The Cache API (rather than IndexedDB) is the right home for\n * large binary blobs — it streams, it's purpose-built for response bodies, and\n * it has its own eviction.\n *\n * Keys are SYNTHETIC absolute URLs (`https://shard.muhkoo.local/<hash>`) rather\n * than the real shard endpoint, so the cache is addressable by hash alone — the\n * sync engine can re-PUT a deferred shard knowing only its hash, without\n * reconstructing the accelerator URL. We never fetch these synthetic URLs; they\n * exist only as cache keys.\n *\n * Every method degrades to a no-op / null where the Cache API is unavailable\n * (Node, Workers, insecure contexts), so callers don't need to branch.\n */\n\nconst CACHE_NAME = \"muhkoo-shards-v1\";\n\nexport class ShardCache {\n    static available(): boolean {\n        try {\n            return typeof caches !== \"undefined\";\n        } catch {\n            return false;\n        }\n    }\n\n    private key(hash: string): string {\n        return `https://shard.muhkoo.local/${encodeURIComponent(hash)}`;\n    }\n\n    private open(): Promise<Cache> {\n        return caches.open(CACHE_NAME);\n    }\n\n    /** Cached shard bytes, or `null` on miss / when unavailable. */\n    async get(hash: string): Promise<Uint8Array | null> {\n        if (!ShardCache.available()) return null;\n        try {\n            const cache = await this.open();\n            const res = await cache.match(this.key(hash));\n            if (!res) return null;\n            return new Uint8Array(await res.arrayBuffer());\n        } catch {\n            return null;\n        }\n    }\n\n    /** Store shard bytes under their hash. Best-effort. */\n    async put(hash: string, bytes: Uint8Array): Promise<void> {\n        if (!ShardCache.available()) return;\n        try {\n            const cache = await this.open();\n            await cache.put(\n                this.key(hash),\n                new Response(bytes as BodyInit, {\n                    headers: { \"content-type\": \"application/octet-stream\" },\n                }),\n            );\n        } catch {\n            /* quota / unavailable — degrade to online-only for this shard */\n        }\n    }\n\n    /** Whether a shard is present in the cache. */\n    async has(hash: string): Promise<boolean> {\n        if (!ShardCache.available()) return false;\n        try {\n            const cache = await this.open();\n            return Boolean(await cache.match(this.key(hash)));\n        } catch {\n            return false;\n        }\n    }\n}\n\nexport default ShardCache;\n","/**\n * Byte conversion helpers usable in both Node and the browser.\n *\n * Replaces Node's `Buffer` API for the small set of operations we actually\n * need in the crypto layer: hex/base64/base64url encode + decode, and array\n * concatenation. Lets `DoubleRatchet`, `KeyStore`, etc. compile against\n * platforms without `Buffer` (browsers, CF Workers).\n */\n\nconst HEX_CHARS = \"0123456789abcdef\";\n\n/** Encode a byte array as a lowercase hex string. */\nexport function toHex(bytes: Uint8Array): string {\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    const b = bytes[i];\n    out += HEX_CHARS[b >> 4] + HEX_CHARS[b & 0x0f];\n  }\n  return out;\n}\n\n/** Decode a hex string into a byte array. Accepts upper/lowercase; rejects odd-length input. */\nexport function fromHex(hex: string): Uint8Array<ArrayBuffer> {\n  if (hex.length % 2 !== 0) {\n    throw new Error(`fromHex: input length must be even (got ${hex.length})`);\n  }\n  const ab = new ArrayBuffer(hex.length / 2);\n  const out = new Uint8Array(ab);\n  for (let i = 0; i < out.length; i++) {\n    const byte = parseInt(hex.substring(i * 2, i * 2 + 2), 16);\n    if (Number.isNaN(byte)) {\n      throw new Error(`fromHex: invalid hex character at offset ${i * 2}`);\n    }\n    out[i] = byte;\n  }\n  return out;\n}\n\n/** Encode a byte array as a standard base64 string. */\nexport function toBase64(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\n/** Decode a standard base64 string to bytes. */\nexport function fromBase64(b64: string): Uint8Array<ArrayBuffer> {\n  const binary = atob(b64);\n  const ab = new ArrayBuffer(binary.length);\n  const out = new Uint8Array(ab);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\n/** Encode a byte array as a base64url string (no padding). */\nexport function toBase64Url(bytes: Uint8Array): string {\n  return toBase64(bytes).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Decode a base64url string (with or without padding) to bytes. */\nexport function fromBase64Url(b64url: string): Uint8Array<ArrayBuffer> {\n  const padded = b64url.replace(/-/g, \"+\").replace(/_/g, \"/\") +\n    \"=\".repeat((4 - (b64url.length % 4)) % 4);\n  return fromBase64(padded);\n}\n\n/** Concatenate any number of byte arrays into a single Uint8Array. */\nexport function concatBytes(...arrays: (Uint8Array | ArrayBuffer)[]): Uint8Array<ArrayBuffer> {\n  let total = 0;\n  for (const a of arrays) total += a.byteLength;\n  const ab = new ArrayBuffer(total);\n  const out = new Uint8Array(ab);\n  let offset = 0;\n  for (const a of arrays) {\n    const view = a instanceof Uint8Array ? a : new Uint8Array(a);\n    out.set(view, offset);\n    offset += view.length;\n  }\n  return out;\n}\n\n/** Encode a UTF-8 string as bytes. Thin wrapper around TextEncoder for symmetry. */\nexport function utf8Encode(s: string): Uint8Array<ArrayBuffer> {\n  // TextEncoder.encode returns Uint8Array<ArrayBufferLike>; widen to the\n  // ArrayBuffer variant explicitly so WebCrypto's BufferSource type accepts it.\n  const u8 = new TextEncoder().encode(s);\n  const ab = new ArrayBuffer(u8.byteLength);\n  const out = new Uint8Array(ab);\n  out.set(u8);\n  return out;\n}\n\n/** Decode UTF-8 bytes to a string. */\nexport function utf8Decode(bytes: Uint8Array): string {\n  return new TextDecoder().decode(bytes);\n}\n","/**\n * HTTP client for the open content-addressed shard store.\n *\n * Each shard is named by the lowercase hex SHA-256 of its ciphertext bytes.\n * The server verifies the hash on PUT, so the address authenticates the\n * contents — there's no benefit to ACLing PUT/GET, and making them open\n * enables cross-user dedup down the line.\n *\n * Wire protocol:\n *   PUT  /api/shards/:hash    body: shard bytes (application/octet-stream)\n *                             200 { ok: true, hash, size, dedup: boolean }\n *                             400 if hash doesn't match body\n *\n *   GET  /api/shards/:hash    200 with shard bytes (application/octet-stream)\n *                             404 if absent\n *\n *   HEAD /api/shards/:hash    200 if present (no body) — used by callers to\n *                             skip a PUT they'd otherwise dedup-rewrite. The\n *                             server can ignore the optimization if it wants.\n */\n\nimport { toHex } from \"../../utilities/bytes\";\n\n/**\n * How long concurrent shard reads are gathered before one batch is sent.\n *\n * Long enough to collect what a concurrent directory walk issues at the same\n * moment, short enough that a single read does not feel it.\n */\nconst SHARD_BATCH_WINDOW_MS = 6;\n\n/** Hashes per batch. Must not exceed what the server will accept. */\nconst SHARD_BATCH_MAX = 256;\n\n/**\n * Expected response bytes per batch, which a batch is split to stay under.\n *\n * The server refuses a batch above 24 MiB of shard bytes with a 413, and the\n * reads in a refused batch fail. Counting hashes alone, about 25 one-MiB\n * shards in one window - a few large files read at once - drew it. This\n * leaves the server's ceiling well clear.\n */\nconst SHARD_BATCH_BUDGET_BYTES = 16 * 1024 * 1024;\n\n/** An entry's JSON around its base64: the quoted hash, a colon, quotes and a comma, rounded up. */\nconst SHARD_BATCH_ENTRY_BYTES = 128;\n\n/**\n * What a shard adds to a batch's response: base64 is 4 bytes for every 3.\n *\n * A shard whose size the caller did not give counts as its entry alone, so\n * reads without sizes batch by count, as they always have — kept for the\n * pinned \"many concurrent reads → ONE request\" test\n * (`shard-batching.test.ts`). No SDK read path is size-less today:\n * `FileStorage.readChunk` always passes `shardSize`. The server reads and\n * base64-encodes every shard before it checks the total\n * (`ShardsController.ts`), so a very large size-less batch can fail with a\n * 5xx before the client ever sees a 413. The split in `sendShardBatch` is a\n * best-effort net for that case, not a guarantee.\n */\nfunction batchCost(size: number | undefined): number {\n    const bytes = typeof size === \"number\" && Number.isFinite(size) && size > 0 ? size : 0;\n    return Math.ceil(bytes / 3) * 4 + SHARD_BATCH_ENTRY_BYTES;\n}\n\n/** One caller of `getShard`, waiting on a batch. */\ntype ShardWaiter = { resolve: (v: Uint8Array | null) => void; reject: (e: unknown) => void };\n\n/** Decode base64 without `atob`'s per-character loop cost on large shards. */\nfunction bytesFromBase64(b64: string): Uint8Array {\n    const binary = atob(b64);\n    const out = new Uint8Array(binary.length);\n    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n    return out;\n}\n\n/** Peer head-start (ms) before origin joins the race in {@link ShardClient.getShard}. */\nconst HEDGE_MS = 500;\n\n/**\n * A content-addressed byte cache for shards (the offline layer's `ShardCache`\n * satisfies this structurally). Declared here as a minimal interface so the\n * storage layer doesn't import the offline module — keeping the dependency\n * arrow one-way (offline → storage).\n */\nexport interface ShardByteCache {\n    get(hash: string): Promise<Uint8Array | null>;\n    put(hash: string, bytes: Uint8Array): Promise<void>;\n}\n\n/**\n * A peer block source (the p2p layer's `PeerExchange` satisfies this\n * structurally). Consulted between the local cache and origin: a block fetched\n * from a peer is verified by hash before use. Declared here so the storage layer\n * doesn't import the p2p module (dependency arrow stays p2p → storage).\n */\nexport interface PeerBlockSource {\n    getBlock(hash: string, opts?: { timeoutMs?: number }): Promise<Uint8Array | null>;\n    announce(hash: string): void;\n}\n\nexport interface ShardClientOptions {\n    /** Base URL of the accelerator (e.g. `https://muhkoo-accelerator.workers.dev`). */\n    baseUrl: string;\n    /**\n     * Path prefix for the shard endpoints, joined to `baseUrl` before the\n     * hash. Defaults to `/api/shards`, which targets a global shard store\n     * (e.g. a dedicated `ShardStoreDO`). Pass a room-scoped value like\n     * `/api/spaces/{roomId}/shards` to keep shards bound to a specific\n     * `SharedSpaceDO` — that's the path the chat application uses today.\n     *\n     * Leading slash optional; trailing slash stripped. The final URL is\n     * always `${baseUrl}${normalizedPrefix}/${encodeURIComponent(hash)}`.\n     */\n    pathPrefix?: string;\n    /**\n     * Optional custom fetch implementation. Defaults to `globalThis.fetch`.\n     * Provided so callers can inject retries / auth / instrumentation.\n     */\n    fetch?: typeof fetch;\n    /**\n     * Optional offline byte cache. When present, GETs are served cache-first and\n     * populated on success, and PUTs write the cache before the network so a\n     * just-uploaded file reads back offline. See {@link ShardByteCache}.\n     */\n    cache?: ShardByteCache;\n    /**\n     * Coalesce concurrent origin reads into `POST {pathPrefix}/batch`. On by\n     * default: it is what keeps opening a project from costing one request per\n     * shard. Set false to force one-at-a-time — useful against a server without\n     * the route, though that is detected and handled automatically.\n     */\n    batchShards?: boolean;\n    /**\n     * Called when a PUT can't reach the network (offline). Lets the caller queue\n     * the upload for replay on reconnect; the bytes are already in {@link cache}\n     * keyed by `hash`, so only the hash needs recording.\n     */\n    deferUpload?: (hash: string) => Promise<void>;\n    /**\n     * Optional peer block source. When present, GETs try peers between the local\n     * cache and origin (peer blocks are verified by hash); PUTs announce the new\n     * block to peers. Best-effort — any failure falls through to origin.\n     */\n    peers?: PeerBlockSource;\n    /**\n     * When true, {@link ShardClient.putShard} returns as soon as the shard is\n     * written to {@link cache} and announced to {@link peers} — the origin PUT is\n     * fired in the BACKGROUND rather than awaited. This makes a large write's\n     * manifest available immediately (so a peer/worker can start pulling the\n     * shards over P2P right away) while origin catches up as a durable fallback.\n     * On a background-PUT failure the shard is handed to {@link deferUpload} (if\n     * present) for replay. Requires a {@link cache} so the bytes survive locally\n     * until the background upload lands. No-op without a cache.\n     */\n    backgroundUpload?: boolean;\n}\n\n/**\n * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in\n * every runtime this SDK targets.\n */\nexport async function shardHash(bytes: Uint8Array): Promise<string> {\n    const subtle = (globalThis.crypto as Crypto | undefined)?.subtle;\n    if (!subtle) {\n        throw new Error(\"shardHash: `globalThis.crypto.subtle` is unavailable in this runtime.\");\n    }\n    const digest = await subtle.digest(\"SHA-256\", bytes as BufferSource);\n    return toHex(new Uint8Array(digest));\n}\n\nexport class ShardClient {\n    private readonly baseUrl: string;\n    private readonly pathPrefix: string;\n    private readonly fetchFn: typeof fetch;\n    private readonly cache?: ShardByteCache;\n    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */\n    private pendingShards!: Map<string, { size?: number; waiters: ShardWaiter[] }>;\n    private batchTimer!: ReturnType<typeof setTimeout> | null;\n    /** False once the server is known not to have the batch route. */\n    private batchSupported!: boolean;\n    private readonly deferUpload?: (hash: string) => Promise<void>;\n    private readonly peers?: PeerBlockSource;\n    private readonly backgroundUpload: boolean;\n\n    constructor(opts: ShardClientOptions) {\n        if (!opts?.baseUrl) throw new Error(\"ShardClient: `baseUrl` is required\");\n        // Strip trailing slash so url concatenation stays clean.\n        this.baseUrl = opts.baseUrl.replace(/\\/+$/, \"\");\n        // Normalize prefix to leading-slash + no-trailing-slash form so the\n        // URL builder can blindly append `/{hash}`.\n        const rawPrefix = opts.pathPrefix ?? \"/api/shards\";\n        const withSlash = rawPrefix.startsWith(\"/\") ? rawPrefix : `/${rawPrefix}`;\n        this.pathPrefix = withSlash.replace(/\\/+$/, \"\");\n        const f = opts.fetch ?? globalThis.fetch;\n        if (typeof f !== \"function\") {\n            throw new Error(\"ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.\");\n        }\n        this.fetchFn = f.bind(globalThis);\n        this.cache = opts.cache;\n        // Coalescing state. `batchSupported` latches false against a deployment\n        // without the batch route, so we degrade once rather than per request.\n        this.pendingShards = new Map();\n        this.batchTimer = null;\n        this.batchSupported = opts.batchShards !== false;\n        this.deferUpload = opts.deferUpload;\n        this.peers = opts.peers;\n        // Background upload needs a local cache to hold the bytes until the PUT\n        // lands; without one it would race the reader against a not-yet-uploaded\n        // origin, so we quietly ignore the flag when there's no cache.\n        this.backgroundUpload = Boolean(opts.backgroundUpload && opts.cache);\n    }\n\n    /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */\n    urlForHash(hash: string): string {\n        return `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(hash)}`;\n    }\n\n    /**\n     * Upload a shard. The server verifies SHA-256(body) matches `:hash` and\n     * rejects with 400 if not, so the caller is the source of truth on\n     * naming. Re-uploading an existing shard is idempotent — the server\n     * returns `dedup: true` in that case.\n     */\n    async putShard(hash: string, bytes: Uint8Array): Promise<{ dedup: boolean }> {\n        const url = this.urlForHash(hash);\n        // Write the cache first so a just-uploaded file reads back even if the\n        // network PUT then fails (offline). The bytes are content-addressed, so\n        // this is safe to keep regardless of upload outcome.\n        if (this.cache) await this.cache.put(hash, bytes);\n        // Tell the swarm we now hold this block, so peers can pull it from us.\n        if (this.peers) this.peers.announce(hash);\n        // Background mode: the bytes are cached + announced, so return now and let\n        // origin catch up asynchronously (a peer can already pull this block). The\n        // PUT is enqueued through a bounded worker pool so a big file doesn't fire\n        // hundreds of concurrent uploads at once.\n        if (this.backgroundUpload) {\n            this.enqueueBackgroundUpload(url, hash);\n            return { dedup: false };\n        }\n        let response: Response;\n        try {\n            response = await this.fetchFn(url, {\n                method: \"PUT\",\n                headers: { \"content-type\": \"application/octet-stream\" },\n                // BufferSource is what fetch's body expects; a Uint8Array satisfies it.\n                body: bytes as BodyInit,\n            });\n        } catch (err) {\n            // Network unreachable (offline). If a defer hook is wired, queue the\n            // upload for replay and report success — the bytes are cached.\n            if (this.deferUpload) {\n                await this.deferUpload(hash);\n                return { dedup: false };\n            }\n            throw err;\n        }\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);\n        }\n        let dedup = false;\n        try {\n            const json = (await response.json()) as { dedup?: boolean };\n            dedup = Boolean(json?.dedup);\n        } catch {\n            // Server returned 200 with no body — treat as fresh upload.\n        }\n        return { dedup };\n    }\n\n    // ── bounded background-upload pool (backgroundUpload mode) ──\n    private bgActive = 0;\n    private readonly bgQueue: Array<() => void> = [];\n    private static readonly BG_CONCURRENCY = 6;\n\n    /** Queue a shard's origin PUT to run in the background under a concurrency\n     *  cap. Bytes are re-read from {@link cache} at upload time (not held in the\n     *  queue) so a large file's backlog doesn't pin a second copy in memory. */\n    private enqueueBackgroundUpload(url: string, hash: string): void {\n        const run = async () => {\n            this.bgActive++;\n            try {\n                const bytes = this.cache ? await this.cache.get(hash) : null;\n                if (bytes) await this.uploadToOrigin(url, hash, bytes);\n            } catch {\n                // Origin unreachable/failed — queue for replay if we can; otherwise\n                // the block is still cached + peer-served, so a later re-PUT covers it.\n                if (this.deferUpload) { try { await this.deferUpload(hash); } catch { /* best-effort */ } }\n            } finally {\n                this.bgActive--;\n                const next = this.bgQueue.shift();\n                if (next) next();\n            }\n        };\n        if (this.bgActive < ShardClient.BG_CONCURRENCY) void run();\n        else this.bgQueue.push(() => void run());\n    }\n\n    /** PUT the shard bytes to origin, verifying the server accepted them.\n     *  Used by the background-upload path; throws on network/HTTP failure. */\n    private async uploadToOrigin(url: string, hash: string, bytes: Uint8Array): Promise<void> {\n        const response = await this.fetchFn(url, {\n            method: \"PUT\",\n            headers: { \"content-type\": \"application/octet-stream\" },\n            body: bytes as BodyInit,\n        });\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);\n        }\n    }\n\n    /**\n     * Fetch a shard by hash. Throws if the server returns a non-200; returns\n     * `null` for 404 so callers can distinguish \"missing\" from \"errored\".\n     *\n     * `size`, the shard's byte length when known (a manifest's `shardSize`),\n     * lets concurrent reads be batched within what the server will send.\n     */\n    async getShard(hash: string, opts: { size?: number } = {}): Promise<Uint8Array | null> {\n        // Cache-first: a hit is content-verified by construction (key == hash).\n        if (this.cache) {\n            const cached = await this.cache.get(hash);\n            if (cached) return cached;\n        }\n        // No peers → straight to origin.\n        if (!this.peers) return this.fetchFromOrigin(hash, opts.size);\n\n        // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow\n        // or missing peer stall delivery — give the peer a short head start, then\n        // start origin in parallel and take whichever returns the block first.\n        const peers = this.peers;\n        return new Promise<Uint8Array | null>((resolve, reject) => {\n            let done = false;\n            let originStarted = false;\n            let timer: ReturnType<typeof setTimeout> | null = null;\n            const win = (b: Uint8Array | null) => {\n                if (done) return;\n                done = true;\n                if (timer) clearTimeout(timer);\n                resolve(b);\n            };\n            const fail = (e: unknown) => {\n                if (!done) { done = true; reject(e); }\n            };\n            const startOrigin = () => {\n                if (originStarted || done) return;\n                originStarted = true;\n                if (timer) { clearTimeout(timer); timer = null; }\n                this.fetchFromOrigin(hash, opts.size).then(win, fail);\n            };\n            timer = setTimeout(startOrigin, HEDGE_MS);\n            peers.getBlock(hash).then(\n                (b) => {\n                    if (b) {\n                        if (this.cache) void this.cache.put(hash, b);\n                        win(b); // peer delivered first\n                    } else {\n                        startOrigin(); // peer miss → don't wait out the hedge\n                    }\n                },\n                () => startOrigin(), // peer error → origin now\n            );\n        });\n    }\n\n    /**\n     * Fetch from origin, COALESCING concurrent requests into one batch.\n     *\n     * A shard is not a file. A project is thousands of small source modules,\n     * each split into shards, so reading one at a time made opening a project\n     * cost thousands of requests — 2,086 for a 519-file project. Latency, not\n     * bytes, is what that spends: Chromium took 18.4s over those requests and\n     * Brave, which filters every one, took 37.5s for identical work. Batching\n     * collapses whatever is in flight at the same moment into a single POST,\n     * which is why it helps most exactly where it hurt most.\n     *\n     * Callers are unchanged: `getShard` still asks for one shard and gets one\n     * shard. The window is a few milliseconds — long enough to gather the reads\n     * a concurrent walk issues together, short enough not to be felt by a lone\n     * read.\n     *\n     * Falls back permanently to one-at-a-time if the server has no batch route,\n     * so a new SDK keeps working against an older deployment.\n     */\n    private fetchFromOrigin(hash: string, size?: number): Promise<Uint8Array | null> {\n        if (!this.batchSupported) return this.fetchOneFromOrigin(hash);\n        return new Promise<Uint8Array | null>((resolve, reject) => {\n            const pending = this.pendingShards.get(hash);\n            if (pending) {\n                pending.waiters.push({ resolve, reject });\n                pending.size ??= size;\n                return;\n            }\n            this.pendingShards.set(hash, { size, waiters: [{ resolve, reject }] });\n            if (this.batchTimer === null) {\n                this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);\n            }\n        });\n    }\n\n    /** Send one batch of whatever has accumulated, and settle those callers. */\n    private async flushShardBatch(): Promise<void> {\n        this.batchTimer = null;\n        if (this.pendingShards.size === 0) return;\n\n        // As many as fit: at most SHARD_BATCH_MAX hashes, and a response\n        // expected to stay within SHARD_BATCH_BUDGET_BYTES. One that does not\n        // fit is skipped for a smaller one behind it. The first always goes,\n        // so a shard over the budget by itself is fetched alone.\n        const waiters: Array<readonly [string, ShardWaiter[]]> = [];\n        let cost = 0;\n        for (const [h, pending] of this.pendingShards) {\n            if (waiters.length === SHARD_BATCH_MAX) break;\n            const next = batchCost(pending.size);\n            if (waiters.length > 0 && cost + next > SHARD_BATCH_BUDGET_BYTES) continue;\n            waiters.push([h, pending.waiters]);\n            cost += next;\n        }\n        for (const [h] of waiters) this.pendingShards.delete(h);\n        // Anything over the cap or the budget waits for the next window\n        // rather than being dropped or silently truncated.\n        if (this.pendingShards.size > 0 && this.batchTimer === null) {\n            this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);\n        }\n        await this.sendShardBatch(waiters);\n    }\n\n    /** POST one batch and settle everyone waiting on it. Never throws. */\n    private async sendShardBatch(waiters: ReadonlyArray<readonly [string, ShardWaiter[]]>): Promise<void> {\n        const hashes = waiters.map(([h]) => h);\n        let shards: Record<string, string>;\n        try {\n            const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {\n                method: \"POST\",\n                headers: { \"Content-Type\": \"application/json\" },\n                body: JSON.stringify({ hashes }),\n            });\n            if (res.status === 413 && waiters.length > 1) {\n                // Too large for the server after all: a size was not given,\n                // or was wrong. Ask for each half on its own. Halving reaches\n                // one hash per batch within log2(n) levels, and one hash the\n                // server refuses is an error like any other, below.\n                // Release the body first: under undici (the CLI, Node), an\n                // unread body holds the connection until garbage collection.\n                await res.body?.cancel().catch(() => {});\n                const half = Math.ceil(waiters.length / 2);\n                await Promise.all([\n                    this.sendShardBatch(waiters.slice(0, half)),\n                    this.sendShardBatch(waiters.slice(half)),\n                ]);\n                return;\n            }\n            if (res.status === 404 || res.status === 405) {\n                // No batch route on this deployment. Stop trying, and serve\n                // everyone individually — including the batch we just gathered.\n                this.batchSupported = false;\n                for (const [h, ws] of waiters) {\n                    this.fetchOneFromOrigin(h).then(\n                        (b) => ws.forEach((w) => w.resolve(b)),\n                        (e) => ws.forEach((w) => w.reject(e)),\n                    );\n                }\n                return;\n            }\n            if (!res.ok) throw new Error(`ShardClient batch failed (${res.status}): ${await safeText(res)}`);\n            const parsed: unknown = await res.json().catch(() => null);\n            // A 200 is not proof the batch route exists. A catch-all handler, a\n            // proxy, or an older deployment can answer this POST with something\n            // else entirely, and trusting the shape would resolve every hash to\n            // `null` — reads silently returning \"missing\" for shards that are\n            // right there. Anything not shaped like a batch reply is treated as\n            // \"no batch route\", exactly like a 404.\n            const candidate = (parsed as { shards?: unknown } | null)?.shards;\n            if (!candidate || typeof candidate !== \"object\") {\n                this.batchSupported = false;\n                for (const [h, ws] of waiters) {\n                    this.fetchOneFromOrigin(h).then(\n                        (b) => ws.forEach((w) => w.resolve(b)),\n                        (e) => ws.forEach((w) => w.reject(e)),\n                    );\n                }\n                return;\n            }\n            shards = candidate as Record<string, string>;\n        } catch (err) {\n            // Offline with a cache behaves as it does for a single fetch: report\n            // absence so Reed-Solomon recovery can still be attempted.\n            for (const [, ws] of waiters) {\n                if (this.cache) ws.forEach((w) => w.resolve(null));\n                else ws.forEach((w) => w.reject(err));\n            }\n            return;\n        }\n\n        for (const [hash, ws] of waiters) {\n            const b64 = shards[hash];\n            if (typeof b64 !== \"string\") { ws.forEach((w) => w.resolve(null)); continue; }\n            let bytes: Uint8Array;\n            try { bytes = bytesFromBase64(b64); }\n            catch (e) { ws.forEach((w) => w.reject(e)); continue; }\n            if (this.cache) void this.cache.put(hash, bytes);\n            ws.forEach((w) => w.resolve(bytes));\n        }\n    }\n\n    /** Fetch a shard from origin. Returns `null` for 404 (or offline when a\n     *  cache is present, so RS recovery can proceed); throws otherwise. */\n    private async fetchOneFromOrigin(hash: string): Promise<Uint8Array | null> {\n        const url = this.urlForHash(hash);\n        let response: Response;\n        try {\n            response = await this.fetchFn(url, { method: \"GET\" });\n        } catch (err) {\n            if (this.cache) return null;\n            throw err;\n        }\n        if (response.status === 404) return null;\n        if (!response.ok) {\n            const text = await safeText(response);\n            throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);\n        }\n        const bytes = new Uint8Array(await response.arrayBuffer());\n        if (this.cache) void this.cache.put(hash, bytes);\n        return bytes;\n    }\n\n    /**\n     * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise\n     * dedup-rewrite. The server can implement this as a HEAD or return a small\n     * JSON body — we don't depend on either.\n     */\n    async hasShard(hash: string): Promise<boolean> {\n        const url = this.urlForHash(hash);\n        const response = await this.fetchFn(url, { method: \"HEAD\" });\n        return response.status === 200;\n    }\n}\n\nasync function safeText(response: Response): Promise<string> {\n    try { return await response.text(); } catch { return \"\"; }\n}\n","/**\n * Dedicated Web Worker entry that hosts a {@link ./blockEngine.BlockEngine}. The\n * blockstore is the Cache-API-backed {@link ../../offline/cache/ShardCache}\n * (the Cache API is available in workers and origin-scoped, so it's the *same*\n * store the main thread reads), and hashing uses {@link\n * ../../storage/transport/ShardClient.shardHash}.\n *\n * Message protocol (see {@link ./engineClient.WorkerEngineHost}):\n *   in : {t:\"frame\",peer,data} | {t:\"want\",id,hash,timeout} | {t:\"announce\",hash} | {t:\"close\"}\n *   out: {t:\"out\",target,data}  | {t:\"want-result\",id,data}\n *\n * Consumers instantiate this with a bundler-resolved URL, e.g.\n *   new Worker(new URL(\"@muhkoo/connect/dist/.../blockEngine.worker.js\", import.meta.url), { type: \"module\" })\n * and pass `() => that worker` as `workerFactory` to the client's p2p options.\n */\n\nimport { BlockEngine } from \"./blockEngine\";\nimport { ShardCache } from \"../../offline/cache/ShardCache\";\nimport { shardHash } from \"../../storage/transport/ShardClient\";\n\n/** Minimal worker-scope shape (avoids needing the WebWorker tsconfig lib). */\ninterface WorkerScope {\n    onmessage: ((e: MessageEvent) => void) | null;\n    postMessage(message: unknown, transfer?: Transferable[]): void;\n}\nconst ctx = self as unknown as WorkerScope;\n\nconst engine = new BlockEngine(\n    new ShardCache(),\n    (target, frame) => {\n        const buf = frame.buffer as ArrayBuffer;\n        ctx.postMessage({ t: \"out\", target, data: buf }, [buf]);\n    },\n    shardHash,\n);\n\nctx.onmessage = (e: MessageEvent) => {\n    const m = e.data as\n        | { t: \"frame\"; peer: string; data: ArrayBuffer }\n        | { t: \"want\"; id: number; hash: string; timeout: number }\n        | { t: \"announce\"; hash: string }\n        | { t: \"close\" };\n\n    if (m.t === \"frame\") {\n        void engine.handleFrame(m.peer, new Uint8Array(m.data));\n    } else if (m.t === \"want\") {\n        void engine.want(m.hash, m.timeout).then((bytes) => {\n            const buf = bytes ? (bytes.buffer as ArrayBuffer) : null;\n            ctx.postMessage({ t: \"want-result\", id: m.id, data: buf }, buf ? [buf] : []);\n        });\n    } else if (m.t === \"announce\") {\n        engine.announce(m.hash);\n    } else if (m.t === \"close\") {\n        engine.close();\n    }\n};\n"],"names":[],"mappings":"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"}

package/dist/browser/index.js

@@ -5862,6 +5862,34 @@ class ReedSolomonCodec {
 const SHARD_BATCH_WINDOW_MS = 6;
 /** Hashes per batch. Must not exceed what the server will accept. */
 const SHARD_BATCH_MAX = 256;
+/**
+ * Expected response bytes per batch, which a batch is split to stay under.
+ *
+ * The server refuses a batch above 24 MiB of shard bytes with a 413, and the
+ * reads in a refused batch fail. Counting hashes alone, about 25 one-MiB
+ * shards in one window - a few large files read at once - drew it. This
+ * leaves the server's ceiling well clear.
+ */
+const SHARD_BATCH_BUDGET_BYTES = 16 * 1024 * 1024;
+/** An entry's JSON around its base64: the quoted hash, a colon, quotes and a comma, rounded up. */
+const SHARD_BATCH_ENTRY_BYTES = 128;
+/**
+ * What a shard adds to a batch's response: base64 is 4 bytes for every 3.
+ *
+ * A shard whose size the caller did not give counts as its entry alone, so
+ * reads without sizes batch by count, as they always have — kept for the
+ * pinned "many concurrent reads → ONE request" test
+ * (`shard-batching.test.ts`). No SDK read path is size-less today:
+ * `FileStorage.readChunk` always passes `shardSize`. The server reads and
+ * base64-encodes every shard before it checks the total
+ * (`ShardsController.ts`), so a very large size-less batch can fail with a
+ * 5xx before the client ever sees a 413. The split in `sendShardBatch` is a
+ * best-effort net for that case, not a guarantee.
+ */
+function batchCost(size) {
+    const bytes = typeof size === "number" && Number.isFinite(size) && size > 0 ? size : 0;
+    return Math.ceil(bytes / 3) * 4 + SHARD_BATCH_ENTRY_BYTES;
+}
 /** Decode base64 without `atob`'s per-character loop cost on large shards. */
 function bytesFromBase64(b64) {
     const binary = atob(b64);
@@ -5889,7 +5917,7 @@ class ShardClient {
     pathPrefix;
     fetchFn;
     cache;
-    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     pendingShards;
     batchTimer;
     /** False once the server is known not to have the batch route. */
@@ -6038,8 +6066,11 @@ class ShardClient {
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
+     *
+     * `size`, the shard's byte length when known (a manifest's `shardSize`),
+     * lets concurrent reads be batched within what the server will send.
      */
-    async getShard(hash) {
+    async getShard(hash, opts = {}) {
         // Cache-first: a hit is content-verified by construction (key == hash).
         if (this.cache) {
             const cached = await this.cache.get(hash);
@@ -6048,7 +6079,7 @@ class ShardClient {
         }
         // No peers → straight to origin.
         if (!this.peers)
-            return this.fetchFromOrigin(hash);
+            return this.fetchFromOrigin(hash, opts.size);
         // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow
         // or missing peer stall delivery — give the peer a short head start, then
         // start origin in parallel and take whichever returns the block first.
@@ -6079,7 +6110,7 @@ class ShardClient {
                     clearTimeout(timer);
                     timer = null;
                 }
-                this.fetchFromOrigin(hash).then(win, fail);
+                this.fetchFromOrigin(hash, opts.size).then(win, fail);
             };
             timer = setTimeout(startOrigin, HEDGE_MS);
             peers.getBlock(hash).then((b) => {
@@ -6113,16 +6144,17 @@ class ShardClient {
      * Falls back permanently to one-at-a-time if the server has no batch route,
      * so a new SDK keeps working against an older deployment.
      */
-    fetchFromOrigin(hash) {
+    fetchFromOrigin(hash, size) {
         if (!this.batchSupported)
             return this.fetchOneFromOrigin(hash);
         return new Promise((resolve, reject) => {
-            const waiting = this.pendingShards.get(hash);
-            if (waiting) {
-                waiting.push({ resolve, reject });
+            const pending = this.pendingShards.get(hash);
+            if (pending) {
+                pending.waiters.push({ resolve, reject });
+                pending.size ??= size;
                 return;
             }
-            this.pendingShards.set(hash, [{ resolve, reject }]);
+            this.pendingShards.set(hash, { size, waiters: [{ resolve, reject }] });
             if (this.batchTimer === null) {
                 this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
             }
@@ -6133,17 +6165,33 @@ class ShardClient {
         this.batchTimer = null;
         if (this.pendingShards.size === 0)
             return;
-        const hashes = [...this.pendingShards.keys()].slice(0, SHARD_BATCH_MAX);
-        const waiters = hashes.map((h) => {
-            const w = this.pendingShards.get(h);
+        // As many as fit: at most SHARD_BATCH_MAX hashes, and a response
+        // expected to stay within SHARD_BATCH_BUDGET_BYTES. One that does not
+        // fit is skipped for a smaller one behind it. The first always goes,
+        // so a shard over the budget by itself is fetched alone.
+        const waiters = [];
+        let cost = 0;
+        for (const [h, pending] of this.pendingShards) {
+            if (waiters.length === SHARD_BATCH_MAX)
+                break;
+            const next = batchCost(pending.size);
+            if (waiters.length > 0 && cost + next > SHARD_BATCH_BUDGET_BYTES)
+                continue;
+            waiters.push([h, pending.waiters]);
+            cost += next;
+        }
+        for (const [h] of waiters)
             this.pendingShards.delete(h);
-            return [h, w];
-        });
-        // Anything over the cap waits for the next window rather than being
-        // dropped or silently truncated.
+        // Anything over the cap or the budget waits for the next window
+        // rather than being dropped or silently truncated.
         if (this.pendingShards.size > 0 && this.batchTimer === null) {
             this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
         }
+        await this.sendShardBatch(waiters);
+    }
+    /** POST one batch and settle everyone waiting on it. Never throws. */
+    async sendShardBatch(waiters) {
+        const hashes = waiters.map(([h]) => h);
         let shards;
         try {
             const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {
@@ -6151,6 +6199,21 @@ class ShardClient {
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ hashes }),
             });
+            if (res.status === 413 && waiters.length > 1) {
+                // Too large for the server after all: a size was not given,
+                // or was wrong. Ask for each half on its own. Halving reaches
+                // one hash per batch within log2(n) levels, and one hash the
+                // server refuses is an error like any other, below.
+                // Release the body first: under undici (the CLI, Node), an
+                // unread body holds the connection until garbage collection.
+                await res.body?.cancel().catch(() => { });
+                const half = Math.ceil(waiters.length / 2);
+                await Promise.all([
+                    this.sendShardBatch(waiters.slice(0, half)),
+                    this.sendShardBatch(waiters.slice(half)),
+                ]);
+                return;
+            }
             if (res.status === 404 || res.status === 405) {
                 // No batch route on this deployment. Stop trying, and serve
                 // everyone individually — including the batch we just gathered.
@@ -6526,7 +6589,8 @@ class FileStorage {
         const fetched = new Array(total).fill(null);
         const fetchInto = async (indexes) => {
             await this.runWithConcurrency(indexes.map((i) => async () => {
-                fetched[i] = await this.shards.getShard(manifest.shardHashes[i]);
+                // The size keeps a batch of concurrent reads within what the server will send.
+                fetched[i] = await this.shards.getShard(manifest.shardHashes[i], { size: manifest.shardSize });
             }));
         };
         await fetchInto(Array.from({ length: dataCount }, (_, i) => i));
@@ -6675,7 +6739,7 @@ async function parseOrThrow(response, op) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.15.0-alpha.1";
+const VERSION = "0.15.0-alpha.2";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -15082,11 +15146,19 @@ function nextTurn() {
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
  * child or it does not. Two tabs writing different directories never conflict;
- * two tabs writing the SAME directory resolve last-writer-wins at the personal
- * space, which carries an HLC per key. Orphaned records (a directory whose
- * parent entry lost the race) are unreachable rather than corrupting — they
- * cost storage until a future sweep, which is the trade this shape makes in
+ * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
+ * write sends no HLC and the personal space has no compare-and-swap: it applies
+ * puts of one key in the order they arrive, so whichever arrives last is kept,
+ * and the other tab's edit is lost. Orphaned records (a directory whose parent
+ * entry lost the race) are unreachable rather than corrupting — they cost
+ * storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
+ *
+ * Within ONE tab, writes of a record are queued and sent one at a time, in the
+ * order they were made, and a read that has to fetch a record waits for its
+ * write in flight (see `writing`). That ordering is per namespace instance
+ * only; nothing orders writes across tabs or devices - that would take a
+ * compare-and-swap at the server.
  */
 /** Refuse a directory at `path` if it would be deeper than MAX_DEPTH from the root. */
 function assertWritableDepth(path) {
@@ -15467,7 +15539,9 @@ class VfsNamespace {
      * that is often the one sent first. Then the earlier write, sealed before
      * the later edit was made, undoes it. That is how a file deleted forever
      * from the Trash, while the move that put it there was still being
-     * written, came back. So each write waits for the one before it.
+     * written, came back. So each write waits for the one before it, and a
+     * read that has to fetch the record waits for its write too: see
+     * `openDirById`.
      */
     writing = new Map();
     historyLimit;
@@ -16220,8 +16294,11 @@ class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs edit the same directory, last-writer-wins at the personal space can
-     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * tabs or devices edit the same directory, the personal space keeps
+     * whichever put arrives last (a VFS write sends no HLC, and the space
+     * applies puts of one key in arrival order), which can leave a child whose
+     * parent entry lost the race. The per-record write queue (`writing`) only
+     * orders writes within one tab. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -16379,7 +16456,41 @@ class VfsNamespace {
         // every concurrent reader to miss and fire its own request for the same
         // record — which is how loading one project turned into thousands of
         // identical `vfs/d/<id>` fetches, most of them in flight at once.
-        const pending = (async () => {
+        // Reads `pending` only after its first `await`: before that, the const is not yet initialised.
+        const load = async () => {
+            // Not while a write of this record is still in flight: see
+            // `writing`. Our own writes echo back over the personal-space
+            // socket, and `watch` drops the record each one names, so a read
+            // can miss with the write still on its way - and the store would
+            // answer with the copy from BEFORE it. An edit made to that copy
+            // is queued behind the write, and then stored over it. So wait
+            // for the latest write queued, which waits on every one before it,
+            // to land or fail - and then for any queued while this read
+            // waited, since the one it waited for may have failed with that
+            // one still on its way. A record with no write in flight is
+            // fetched at once.
+            let awaited;
+            for (let inFlight = this.writing.get(id); inFlight && inFlight !== awaited; inFlight = this.writing.get(id)) {
+                awaited = inFlight;
+                await inFlight.catch(() => { });
+            }
+            if (awaited) {
+                // A write that landed put the record it wrote back in the
+                // cache, and the next edit of this directory is made to that.
+                // Answer with it rather than fetch a second copy: two copies
+                // of one record, each edited and written, undo each other's
+                // edits. When the cache holds nothing else - the write failed,
+                // or a change since has dropped the record - ask the store.
+                const now = this.cache.get(id);
+                if (now && now !== pending)
+                    return now;
+                // Empty, when the write failed: it dropped what the cache held,
+                // and after an echo that was this very read. Put it back before
+                // asking the store, so a read that comes in meanwhile shares
+                // this copy instead of fetching a second one.
+                if (!now)
+                    this.cache.set(id, pending);
+            }
             const raw = await this.deps.store.get(dirKey(id));
             // An absent record is an EMPTY directory, not an error: the root
             // exists before anything has been written to it, and a directory is
@@ -16405,7 +16516,8 @@ class VfsNamespace {
                 throw err;
             }
             return this.readRecord(id, key, value, path);
-        })().catch((err) => {
+        };
+        const pending = load().catch((err) => {
             // A failed read must not be remembered, or one blip poisons the
             // directory for the life of the session.
             if (this.cache.get(id) === pending)
@@ -16506,7 +16618,14 @@ class VfsNamespace {
             // change the store never took - a deleted file gone from every
             // listing while it is still stored, and a retry told it does not
             // exist. Drop it, so the next read asks the store.
-            this.cache.delete(dir.id);
+            //
+            // Unless a later write of this record is already queued. It
+            // seals the record as it stands when it is sent, this edit
+            // included, so the cache shows what is about to be stored, and
+            // dropping it would only send readers to the store for an older
+            // copy. If that write fails too, it drops the cache itself.
+            if (this.writing.get(dir.id) === write)
+                this.cache.delete(dir.id);
             throw err;
         }
         finally {