Merkle Notes

Highlight any webpage, attach a note, and sync it directly to your collaborators. No account, no backend, no company in the middle reading your research.

Merkle Notes is a Chrome extension that does P2P collaborative annotations over WebRTC. The hard part (conflict-free merge, sync integrity) lives in an Idris 2 CRDT core with dependent types. The fun part (highlighting, room codes, peer status) is TypeScript.

Think of it as Hypothesis, except your notes stay local-first and sync peer-to-peer.

What you get

• Highlight + annotate any page. Select text, add a note, done.
• P2P sync over WebRTC data channels. STUN only, no TURN server.
• CRDT merge so concurrent edits converge without conflicts.
• Merkle tree for sync integrity. Peers handshake on root hashes, then exchange missing ops.
• Resilient anchors via XPath, CSS selectors, and fuzzy text fallback. Annotations survive minor DOM changes.
• Room codes to find peers. Same code, same BroadcastChannel namespace, same room.

Who is this for?

Journalists reviewing sources together. Study groups reading the same article. Legal researchers marking up filings. Anyone who wants shared reading notes without handing them to a SaaS vendor.

How it works (short version)

You highlight text
    -> content script builds an anchor (XPath + CSS + offsets)
    -> background worker creates a CRDT op
    -> WebRTC data channel sends it to peers
    -> peers apply the op, re-render highlights
    -> Merkle roots match, everyone converges

The Idris side proves the merge logic is total and follows an LWW join-semilattice. The JavaScript bridge handles browser IO. TypeScript runs the extension shell.

Quick start

You need

• Idris 2 0.8+
• Node.js 18+
• Google Chrome

Build

git clone https://github.com/thedhruvhegde/merkle-notes.git
cd merkle-notes
npm install
npm run build

Load in Chrome

1. Go to chrome://extensions
2. Turn on Developer mode
3. Click Load unpacked
4. Pick the dist/ folder

Use it

1. Open any webpage
2. Click the Merkle Notes icon in the toolbar
3. Copy the room code and send it to a collaborator (or join theirs)
4. Select text on the page
5. Type a note, click Highlight
6. Watch it show up on the other peer's browser

Two Chrome windows side by side is the fastest way to test.

Project layout

crdt/src/          Idris 2 CRDT core (the interesting part)
crdt/js/           Browser FFI runtime bridge
extension/src/     TypeScript Chrome extension
docs/              Architecture, lattice proofs, publishing guide
dist/              Built extension (load this in Chrome)

Idris modules

Module	What it does
CRDT.Lattice	LWW join-semilattice for timestamp ordering
CRDT.Core	SiteId, Lamport clocks, causal timestamps
CRDT.Annotation	Annotation records with dual anchors
CRDT.Ops	Op-based replication and LWW merge
CRDT.Merkle	Merkle tree for sync diff detection
CRDT.Document	Document state machine (insert/update/delete)
CRDT.Sync	Wire protocol messages

Proof sketches live in docs/LATTICE.md. Full system design in docs/ARCHITECTURE.md.

Sync protocol

Peers in the same room find each other via BroadcastChannel, then negotiate WebRTC directly:

1. Exchange SDP offer/answer + ICE candidates (STUN: stun.l.google.com:19302)
2. Open a merkle-sync data channel
3. Send HS:<merkleRoot> handshake
4. If roots differ, ship missing ops as OPS:[...]
5. Apply ops through the CRDT bridge, re-render highlights

No central server. If both peers are behind symmetric NAT, connection may fail. That is a deliberate tradeoff (no TURN bill, no relay operator).

Threat model (be honest)

• Room codes are the trust boundary. Anyone with the code can join and read notes.
• Annotations are plaintext on the wire. No E2E encryption yet.
• Storage is local (chrome.storage.local). Uninstalling the extension removes your copy.

Publishing

Chrome Web Store steps: docs/PUBLISHING.md

Version

1.0.0 - initial release. CRDT core, WebRTC sync, highlight UI, room codes.

License

MIT