Local-first · Deterministic · CRDT
Build collaborative systemsconverge NodalMerge is a replication engine built around deterministic history replay.
Write locally, merge concurrently, converge deterministically — with full
audit-grade replay semantics.
Deterministic replay Canonical resolution Speculative writes Authority policies WebSocket-first IndexedDB persistence Audit-grade history
Choose your path
Frontend developer
Backend / operator
Platform team
You’re building a collaborative UI — real-time editing, presence, offline-first UX.
Install the SDK
npm install nodalmerge-sdk-js
Connect a room
const sdk = await createNodalMergeSdk ({ wsUrl: "ws://localhost:7878/ws/runtime" , roomId: "my-room" , transport: { mode: "auto" }, reconnect: { enabled: true } }); await sdk . room . connect ();
Read and write synced state
sdk . sync . set ( "profile/name" , "Alice" ); sdk . sync . push (); const name = sdk . sync . get ( "profile/name" );
JavaScript SDK Full API reference — sync, text, presence, blobs, offline, and config.
SDK overview Pick the right surface, understand intent vs canonical patterns.
Subscriptions Event subscriptions, runtime message types, lifecycle hooks.
Collab text playground Interact with RGA text ops and DAG replay live.
You’re running or embedding the runtime — server setup, persistence, topology, auth.
Start the server
cargo run - p nodalmerge - server -- \ -- store . / data \ -- metrics - addr 127.0 . 0.1 : 9090
Verify health
curl http://127.0.0.1:9090/metrics
Server listens at ws://127.0.0.1:7878/ws/<room>.
Lock down auth
Set set-room-key with an Ed25519 key and configure set-policy rules
before routing production traffic.
Server setup Binary flags, storage options, and launch validation.
Persistence SQLite node storage, blob backends, peer-local IndexedDB, and recovery.
Security and auth Ed25519 room keys, JWT tokens, and policy rule wiring.
WebSocket commands Full command/response contract including topology and archive ops.
You’re evaluating or onboarding a team — architecture understanding, runbooks, validation.
Run the apps
Start the demo host and playground apps locally to validate
end-to-end SDK, WASM, and protocol behavior before writing integration code.
Follow the onboarding paths
Use the guided onboarding paths below to build team-wide baseline confidence.
First hour path Run host + apps, validate collaboration flows, inspect protocol evidence.
First day builder path Move from setup to a small collaborative prototype with validation.
Frontend app team path SDK + WASM baseline, subscription patterns, text and presence validation.
Platform operator path Host readiness, incident evidence collection, and support posture.
Core capabilities
🔀
Deterministic CRDT merge
All peers converge to the same canonical state regardless of write order or network partitions.
📼
Replay-grade history DAG
Every change is a node in an append-only DAG. Replay any window, branch, or ancestor state on demand.
✈️
Full offline queue
Writes queue locally while disconnected and flush deterministically on reconnect — no data loss.
🏛️
Authority-scoped policies
Lock write authority to specific key paths and peers. Policy violations are rejected, not silently dropped.
🧵
RGA collaborative text
Character-level RGA with tombstone semantics, anchor-based positioning, and per-glyph attribution.
🔍
Canonical projections
Register query specs, build paginated projections at any checkpoint, and invalidate on schema change.
Reference sections
Architecture System model, CRDT behavior, replay semantics, speculative vs authoritative, and topology boundaries.
Protocol Message-level sync, reconciliation flow, blob transfer, and failure semantics.
SDK JavaScript and React integration — sync, text anchors, presence, offline, projections, and config.
API and commands Full WebSocket command/response contract, capability gates, and rejection taxonomy.
Operators Setup, persistence, GC lifecycle, observability, topology, and replay operations.
Benchmarks Performance expectations and runtime attribution guidance.
Guides Practical implementation guides for real product workflows.
Tutorials Hands-on walkthroughs: protocol tracing, incident triage, replay inspection.
Developer experience apps
Five interactive playground apps Infinite room workspace, collab text, protocol inspector, replay lab, and collab
maps — local playgrounds for exercising SDK, replay, and protocol behavior live.
See developer-experience/apps for what each app
demonstrates and how to run them. Suggested first hour
Run the quickstart
Start a local server and validate your first room end-to-end.
→ Quickstart
Follow the first-hour onboarding path
Validate SDK + WASM flows, inspect protocol behavior, check presence and replay evidence.
→ First hour path
Explore the interactive apps
Read the architecture fundamentals
Configure your production baseline
