browsermesh-sync

CRDT sync engine, delta sync, file transfer, and real-time collaboration for BrowserMesh.

Why this exists

browsermesh-primitives ships the raw CRDT types (VectorClock, LWWRegister, GCounter, PNCounter, ORSet, RGA, LWWMap) but has no opinion about how a whole document made of several of them gets synchronized, chunked into transferable deltas, or reconciled after a schema change. browsermesh-sync is that layer: SyncDocument/MeshSyncEngine compose primitives' CRDT classes into a synchronizable document, DeltaLog/DeltaEncoder/SyncCoordinator turn ongoing changes into transportable deltas instead of resending full state, MeshFileTransfer/ChunkStore extend the same content-addressed approach to binary files, and CollabSession/YjsAdapter bridge to real-time collaborative editing. It depends on browsermesh-primitives directly -- SyncDocument's field types are primitives' CRDT classes, not a reimplementation of them.

Used by

@johnhenry/browsermesh-apps requires this package as a non-optional peer (unlike browsermesh-core/browsermesh-transport/browsermesh-discovery, which are optional there) -- it's load-bearing, not an add-on. MeshSyncEngine/InMemorySyncStorage back mesh-sync.mjs and mesh-kv.mjs's replicated key-value store; ChunkStore backs mesh-torrent.mjs and peer-ipfs.mjs's content-addressed chunk storage; and IndexedDBChunkStore/IndexedDBSyncStorage (this package's durable, browser-persisted storage adapters) back cloud-storage-backend.mjs and manifest-sync.mjs, the storage layer underneath browsermesh-apps's CloudStorage SDK.

Provenance

Extracted from the private clawser monorepo (previously packages/browsermesh-sync), where it was manually published to npm, unscoped, as [email protected] (2026-07-17) with no CI ever automating that publish. This is its first release as part of the @johnhenry/browsermesh monorepo; the version restarts at 0.0.0 per family convention.

Modules

| Module | Key Exports | |--------|-------------| | sync | SyncDocument, MeshSyncEngine, InMemorySyncStorage | | delta-sync | SyncCoordinator, DeltaLog, DeltaEncoder, DeltaDecoder, DeltaBranch | | migration | MigrationEngine, MigrationPlan, DualActiveWindow | | files | MeshFileTransfer, ChunkStore, FileDescriptor, TransferOffer | | cidv1 | computeCidV1, buildUnixfsFile, buildUnixfsDirectory, verifyBlock, parseCid, cidV1FromSha256Hex, sha256HexFromCid | | collab | CollabSession, YjsAdapter, AwarenessState | | collab-bridge | CollabBridge, CollabManager | | memory-sync | AgentMemorySync, MemoryEntry, ConflictEntry |

IPFS CIDv1 / UnixFS addressing (opt-in)

ChunkStore.computeCid(data) still returns a SHA-256 hex digest by default. For real IPFS addresses (CIDv1, sha2-256, base32, raw leaves, dag-pb/UnixFS):

await ChunkStore.computeCid(bytes, { format: 'cidv1' }); // raw-leaf CIDv1
const { cid, blocks, files } = await buildUnixfsDirectory({ 'index.html': bytes });
await verifyBlock(someCid, blockBytes); // accepts SHA-256 hex or CIDv1

Output matches ipfs add -r --cid-version=1 --raw-leaves (256 KiB fixed chunks, balanced layout, 174 links max). Directories needing HAMT sharding (serialized node over 256 KiB) are rejected.

Install

npm install @johnhenry/browsermesh-sync @johnhenry/browsermesh-primitives

Usage

import { MeshSyncEngine, MeshFileTransfer, CollabSession } from '@johnhenry/browsermesh-sync';

License

MIT