weave

Real-time multiplayer canvas with a hand-rolled CRDT. Open the same room in two tabs and watch shapes, freehand ink, images and live cursors merge conflict-free, with no server-side lock. Go offline, keep drawing, reconnect — the two diverged boards snap back to the same pixels. And because every edit is an immutable op, you can scrub the board's whole history like a video.

messaging is delivery. weave is convergence. The hard part isn't the WebSocket — it's the replicated data type underneath that makes concurrent edits provably agree, and the event-sourced op-log that turns "every change ever" into time-travel.

▶ Try it right now — jinwovo.github.io/weave

No install, no server, nothing to sign up for. The convergence playground puts two real replicas of this CRDT in one page, joined only by a simulated hostile network. Draw on both sides, crank up latency, drop and duplicate packets, cut the wire — the state fingerprints diverge in front of you and snap back to ≡ the moment delivery resumes. Hit ▶ run the story for a 20-second guided tour:

The full multiplayer app (below) is the same CRDT with a WebSocket and an op-log behind it:

---

Why it's different

Every distinctive feature falls out of the architecture, not bolted-on UI:

Feature	Powered by
🟢 Multiplayer, conflict-free — concurrent edits never clobber	the CRDT (LWW-Map over HLC)
✍️ Collaborative text — two people type in one note, character by character	a sequence CRDT (Fugue, TPDS 2025), proven by a fault-injection sim
↶ Undo / redo — Ctrl+Z works with live collaboration, not against it	inverse ops re-authored with a fresh stamp (LWW always wins)
👀 Live presence — see peers' cursors and the shape they're drawing before they commit	ephemeral draft preview fanned out on the cursor channel
🔌 Offline-resilient — keep editing while disconnected, reconnect → auto-merge	optimistic local CRDT + op outbox + reconcile
🧪 Convergence playground — break the network yourself, watch replicas reconverge	two in-page replicas over a simulated adversarial network
🧵 Interleaving lab — the same partitioned keystrokes through RGA and Fugue, live	RGA shuffles the authors together; Fugue keeps each block intact
🕐 Time-travel — scrub / replay the board's entire history	the append-only op-log (event sourcing)
📚 Hourly board + archive — fresh canvas each hour, past hours browsable read-only	op-log bucketed by room base@<hour>
🖼 Images (paste / drop), ✏️ ink, ▭ shapes, ⤡ resize, 🧽 erase	all just shapes in the same convergent document

Problem

Multiplayer editing (Figma / Excalidraw / tldraw) needs shared state that:

1. lets many people edit the same object simultaneously without a central lock,
2. survives offline edits and reconnects without losing work, and
3. converges — every replica that has seen the same edits shows the identical board.

A naïve "broadcast every change" approach silently diverges the moment two people touch the same thing at once. The correct tool is a CRDT (Conflict-free Replicated Data Type), and the correctness has to be proven, not eyeballed.

Design

A board is a map shapeId → ShapeState. Every property of a shape is an independent Last-Writer-Wins register stamped with a Hybrid Logical Clock timestamp + actor id (globally unique, totally ordered). merge is the field-wise → key-wise least upper bound, which is commutative, associative and idempotent — a join-semilattice, the sufficient condition for convergence. Operations are applied by merging the delta they imply, so they are immune to reordering and duplication. The server is a dumb relay + persistence layer, never the source of truth.

The same op-log is also an event store: replaying any prefix of it reconstructs the board at that moment — which is exactly what powers time-travel. And a room is bucketed as base@<hoursSinceEpoch>, so the live board resets every hour while each past hour stays preserved under its own room id and remains browsable.

See docs/adr/0001-lww-map-crdt-over-hlc.md for the decision and the alternatives (OT, RGA/YATA, OR-Set, off-the-shelf Yjs) that were rejected.

LWW is the right call for geometry and style, but text has to merge character-by-character — so text content is a sequence CRDT of its own. It started as RGA (ADR-0002), which converges but can interleave two users' concurrent runs of text — a limitation that ADR documented on day one. It is now Fugue (Weidner & Kleppmann, “The Art of the Fugue”, IEEE TPDS 2025 · ADR-0005): each character is a node in a tree — hung to the right of its predecessor, or to the left of the element it displaces — so a run of typing forms a chain that concurrent runs cannot thread through. Deletes are tombstones, ops buffer until their dependency arrives (delivery is at-least-once and unordered), and every character carries a unique HLC id. It backs sticky / text shape bodies live — double-click a note and two people can type into it at once — and the interleaving lab lets you watch RGA fail where Fugue holds.

Undo/redo falls out of the same model. There is no "previous document" to rewind to — the log is append-only and shared — so each local edit records an inverse op (move → move-back, create → delete, delete → re-create) that undo re-authors with a fresh timestamp. Because the board is last-writer-wins, a fresh stamp always wins, so "undo" is just "author the reverse edit now" — which commutes with everyone else's concurrent edits: undo my move after you recolor the same shape and your color stays. Per-user stack, zero server involvement. See docs/adr/0003-inverse-op-undo.md.

Live presence is the same ephemeral channel as cursors. While you drag out a shape or ink a stroke, the in-progress draft is broadcast (throttled, never persisted) so collaborators watch it form — a translucent fill with a dashed outline in your colour — and disappears the instant you commit or cancel. So you don't just see where someone is, you see what they're about to draw.

Architecture

flowchart LR
    subgraph CA["client A · browser"]
        DA["CanvasDoc + HlcClock<br/>optimistic · offline outbox"]
    end
    subgraph CB["client B · browser"]
        DB["CanvasDoc + HlcClock<br/>optimistic · offline outbox"]
    end

    subgraph APP["weave app · Spring Boot 4.1"]
        WS["WebSocket relay"]
        HTTP["HTTP API<br/>/history · /epochs"]
    end

    R[("Redis Pub/Sub<br/>ops · cursors fan-out")]
    PG[("PostgreSQL<br/>append-only op-log")]

    DA <-->|ops| WS
    DB <-->|ops| WS
    WS -->|persist| PG
    WS -->|publish| R
    R -->|fan-out| WS
    HTTP -->|replay| PG
    DA -. "time-travel · reconnect" .-> HTTP
    DB -. "time-travel · reconnect" .-> HTTP

Loading

A client applies each op to its local CanvasDoc immediately (optimistic), then sends it over the WebSocket. The relay persists it to the append-only op-log and publishes it to Redis; the Redis echo is the single broadcast path, so every instance — the origin included — relays an op to its own sockets. A late joiner gets a snapshot; time-travel and the hourly archive read that same op-log over HTTP. The server stores and fans out — it never decides the state; the CRDT does.

Cold-start recovery is bounded, not lifetime-long. A background sweeper materialises each busy room's fold into a canvas_snapshot row (every register with its HLC timestamp, tombstones included — lossless at the CRDT level), watermarked by an insertion-order seq. Rebuilding a room then folds snapshot + tail instead of the whole log — O(tail), tail ≤ threshold + one sweep window. It's exact, not approximate: the document fold is a join-semilattice, so folding any subset then the rest — any order, any overlap — rebuilds the identical document (property-tested). The watermark only advances past a grace window so a seq handed out before its transaction commits can never be skipped, and /history still reads the full log — snapshots bound recovery, they don't rewrite history. (ADR-0004)

Offline → reconnect → reconverge

The op-log + CRDT make a dropped connection a non-event: keep editing, reconnect, and the diverged boards merge by themselves.

sequenceDiagram
    participant A as client A
    participant S as weave app
    participant L as op-log (Postgres)
    participant B as client B

    Note over A: 🔌 offline
    A->>A: edit locally (optimistic) + queue in outbox
    B->>S: edit (online)
    S->>L: append op

    Note over A: 🌐 reconnect
    A->>S: flush outbox
    S->>L: append (idempotent · room, actor, hlc)
    A->>S: GET /history
    S-->>A: full op-log
    A->>A: merge — LWW by HLC
    Note over A,B: converged — identical board

Loading

Verification

The convergence guarantee is enforced by property-based tests (jqwik), not anecdotes:

• order- & duplication-independence — any delivery order of an op-log yields the same doc;
• partition → gossip → convergence — replicas that each saw only a slice of the edits all reconcile to the identical board after exchanging state;
• semilattice laws — merge is commutative, associative and idempotent;
• HLC algorithm — monotonic ticks, counter reset on physical progress, receive-side advance;
• sequence CRDTs (Fugue + RGA) — concurrently-authored text ops, delivered in every order with duplicates, converge to one string (character-level, not LWW);
• non-interleaving — the property RGA cannot offer: concurrent runs typed at the same position (forward and prepending) stay contiguous under Fugue, across 300 randomized adversarial schedules each — plus the paper's canonical YATA-anomaly vector ("axb" is forbidden; RGA produces exactly it) and a differential test that runs one editing session through both CRDTs;
• deterministic fault-injection simulation — a Jepsen-lite / DST harness: 3–4 replicas under an adversarial network (delay, reorder, drop-and-redeliver, duplicate) converge across 400 seeds, every run reproducible from its seed;
• the snapshot contract — folding any prefix into a materialised snapshot, then the tail — shuffled, with part of the prefix re-delivered on top — rebuilds the exact full document.

./gradlew :crdt-core:test     # 27 tests

The sync server is proven end-to-end against real Postgres + Redis (Testcontainers): ops authored by one WebSocket client fan out to another, land in the durable op-log exactly once (a duplicate is absorbed by the (room, actor, hlc) constraint), and a late-joining client converges to the identical board from the snapshot alone — purely by replaying the op-log through the CRDT. SnapshotIntegrationTest additionally proves the sweeper snapshots a busy room, a cold start folds only the tail beyond the watermark, and the bounded rebuild — including a tombstone, a post-snapshot resurrection, and an idempotent double-refresh — equals the full-log fold exactly.

./gradlew :app:test           # 12 tests (Testcontainers PG + Redis)

Multi-instance convergence is proven by MultiInstanceConvergenceTest, which boots two app contexts sharing one Postgres + Redis and asserts an op authored on instance 1 reaches a client on instance 2 — only possible via the Redis fan-out. A k6 load test (load/convergence.js) across a 2-instance cluster measured op fan-out latency at median 16 ms · p90 70 ms for ~100 ops/s (77k messages fanned out, p99 ≈ 550 ms tail on a cold local run).

k6 run load/convergence.js    # against two instances on :8103 and :8104

The convergence playground

The property tests prove convergence under an adversarial network; the playground is that exact fault model made interactive, so you can watch the proof instead of taking the README's word for it:

• Two real replicas — each pane owns its own CanvasDoc, HLC clock and per-shape Fugue text, running the same TypeScript CRDT as the live client, and they exchange the same wire format the WebSocket protocol uses. The only thing simulated is the network.
• An honest fault model — sliders for latency (±45% jitter, so packets genuinely reorder), loss and duplication, plus a one-click partition. Ops are reliable: a lost packet visibly dies mid-wire (✕) and is retransmitted until it lands — at-least-once, exactly like the real client's outbox against the server's idempotent op-log — and duplicates are absorbed because merge is idempotent. Cursors and draft previews are ephemeral: lost is lost, like the real cursor channel.
• Falsifiable convergence — each pane shows a live fingerprint of its full CRDT state (every register with its HLC stamp, tombstones included, every text node). The badge compares them: ≠ while partitioned, ≡ once every op has been delivered. If the fingerprints ever differed with nothing in flight, the badge has a dedicated "this should be impossible" state — it has never rendered.

The README GIF above is recorded by scripts/capture-playground.mjs, which drives the ▶ run the story tour against the exact static build GitHub Pages serves and fails unless the badge passes through the partition act and returns to CONVERGED with equal fingerprints — so the demo can't silently rot.

The interleaving lab

Below the playground sits a second experiment: the same partitioned editing session — two users each prepending items to one shared todo list — run through both of weave's sequence CRDTs at once. Every keystroke gets the identical HLC stamp in both engines; only the placement rule differs. RGA (timestamp-ordered, weave's original text type) converges to a fully shuffled B/A/B/A merge; Fugue keeps each author's items contiguous. Convergence was never the question — what the merged text reads like is.

scripts/capture-lab.mjs records this GIF and fails unless RGA interleaves (≥3 author blocks), Fugue holds at exactly 2, and both engines' replica pairs end converged — the anomaly and the fix are both asserted, not narrated.

Stack

• crdt-core — pure Java 21, zero production dependencies; tests on jqwik + JUnit 5.
• app — Spring Boot 4.1: WebSocket relay, idempotent op-log on PostgreSQL (Flyway), Redis pub/sub fan-out, snapshot replay, and HTTP …/history + …/epochs endpoints (time-travel & archive).
• web — Next.js 15 + Canvas client: shapes, freehand pen, sticky text, images (paste/drop), resize, eraser, undo/redo (Ctrl+Z), live cursors, presence. A faithful TypeScript port of the CRDT gives local-first optimistic edits that converge with the server and every client — including offline edits that flush + reconcile on reconnect. Plus time-travel replay, the hourly archive, and the playground (/playground) — the same client CRDT over an in-page simulated network, statically exported to GitHub Pages (no backend at all).
• observability — Micrometer metrics on /actuator/prometheus, scraped by Prometheus into a provisioned Grafana dashboard: active sessions/rooms, op ingest rate + persist latency (p50/p95/p99 via histogram buckets), HTTP p95 per route, JVM heap, and the snapshot row — snapshots written, cold-start tail size, refresh/replay latency.

Local ports (per workspace registry): app 8103, PostgreSQL 5437, Redis 6383, front 3009, Prometheus 9099, Grafana 3011. Container prefix weave-.

Roadmap

Phase	Scope	Status
P0	Pure-Java CRDT core (LWW-Map over HLC) + property-based convergence proof	✅ done
P1	Spring Boot 4.1 sync server: WebSocket relay, idempotent op-log, Redis fan-out, snapshot replay	✅ done
P2	Next.js + Canvas client: shapes, pen, sticky text, images, resize, eraser, live cursors, presence	✅ done
P3	Distinctive layer: time-travel replay · offline → reconnect reconvergence · hourly board + archive	✅ done
P4	Multi-instance convergence (two app instances share Postgres + Redis) + k6 fan-out-latency load test	✅ done
P5	Playwright two-client demo GIF + product polish (PNG export, copy-link)	✅ done
P6	Sequence CRDT (RGA) collaborative text + deterministic fault-injection sim · Prometheus + Grafana observability	✅ done
P7	Undo / redo via inverse ops — per-user, concurrency-safe, zero server change	✅ done
P8	Snapshot-accelerated replay — lossless CRDT snapshots + seq watermark + grace window; cold start folds O(tail), proven exact by property test	✅ done
P9	Convergence playground — two in-page replicas over a simulated adversarial network (latency/loss/dup/partition), state fingerprints, scripted tour; deployed server-less to GitHub Pages	✅ done
P10	Fugue text CRDT (Weidner & Kleppmann, IEEE TPDS 2025) replaces RGA — non-interleaving concurrent text, proven by new property tests + 400-seed DST · interleaving lab in the playground runs RGA vs Fugue on identical keystrokes	✅ done

Quickstart

Zero-install: the playground runs the CRDT entirely in your browser. Everything below is for the full multiplayer stack.

On Windows, one command brings up the whole stack (Docker Desktop → containers → app → web) and opens the board — it skips whatever is already running:

powershell -ExecutionPolicy Bypass -File scripts/dev-up.ps1

Or piece by piece:

git clone https://github.com/jinwovo/weave && cd weave

./gradlew :crdt-core:test     # P0 convergence proofs (no Docker needed)

docker compose up -d          # weave-postgres (5437) + weave-redis (6383)
./gradlew :app:test           # sync-server proof (Testcontainers spins its own PG + Redis)
./gradlew :app:bootRun        # run the sync server on http://localhost:8103  (WS: /ws?room=&actor=)

cd web && npm install && npm run dev    # canvas client on http://localhost:3009
# open two tabs at http://localhost:3009/?room=demo — draw, paste an image, go offline, hit 🕐 / 📚

The client tells you when the sync server isn't reachable (drawing still works locally — live cursors, history and the archive are what need it).