Prepare release 0.1.0

- Add LICENSE (ISC) and README.md
- Add documentation: architecture, codecs, getting-started, json-joy-mapping
- Reorganize demo apps: wb (HCS), wbd (Dream), wbr (Raylib)
- Remove deprecated lib_eio and crdt-eio.opam
- Fix dune-project metadata (version 0.1.0, dedupe authors)
- Update code comments to reference issue tracker

LICENSE

···
+ISC License
+
+Copyright (c) 2026 Gabriel Díaz López de la Llave
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

···
+docs/README.md

bench/dune

···
 (executable
  (name bench_main)
- (public_name crdt_bench)
- (package crdt)
  (libraries crdt unix))
 
 (executable

bin/dune

···
 (executable
- (public_name crdt)
  (name main)
- (package crdt)
- (libraries crdt))
-
-(executable
- (name rga_debug)
- (libraries crdt))
-
-(executable
- (name debug_model_codec)
  (libraries crdt))

bin/main.ml

···
-let () = print_endline "Hello, World!"
+let () =
+  let model = Crdt.Model.create 1 in
+  let view = Crdt.Model.view model in
+  ignore view

bin/wb/dune

···
+(executable
+ (name wb)
+ (libraries crdt hcs eio_main base64))

bin/wb/static

···
+../wbd/static

bin/wb/wb.ml

···
+(** Collaborative Webboard - HCS WebSocket Server
+
+    A real-time collaborative whiteboard using:
+    - HCS web server (Eio-based) with WebSocket support
+    - OCaml CRDT library for synchronization
+    - HTML Canvas + plain JS + json-joy on the client
+
+    The server maintains the authoritative CRDT state and relays binary patches
+    between clients. *)
+
+open Eio.Std
+open Crdt
+module J = Simdjsont.Json
+
+(* ============================================================================
+   Configuration
+   ============================================================================ *)
+
+let default_port = 8080
+let static_dir = "static"
+
+(* ============================================================================
+   Types
+   ============================================================================ *)
+
+type client = {
+  id : string;
+  mutable name : string;
+  websocket : Hcs.Websocket.t option;
+}
+
+type server_state = {
+  model : Model.t;
+  mutable clients : client list;
+  mutable strokes : J.t list; (* Store strokes for new clients *)
+  mutable chat_history : (string * string) list; (* (sender, text) pairs *)
+  mutex : Eio.Mutex.t;
+}
+
+(* ============================================================================
+   Utilities
+   ============================================================================ *)
+
+let generate_id () =
+  let chars = "abcdefghijklmnopqrstuvwxyz0123456789" in
+  String.init 8 (fun _ -> chars.[Random.int (String.length chars)])
+
+let log fmt =
+  Printf.ksprintf
+    (fun s ->
+      Printf.printf "[%s] %s\n%!"
+        (let t = Unix.localtime (Unix.time ()) in
+         Printf.sprintf "%02d:%02d:%02d" t.Unix.tm_hour t.Unix.tm_min
+           t.Unix.tm_sec)
+        s)
+    fmt
+
+(* ============================================================================
+   Message Protocol
+
+   Messages are JSON with a "type" field:
+   - "join": Client joining with name
+   - "patch": Binary CRDT patch (base64 encoded)
+   - "sync": Full model sync (binary, base64 encoded)
+   - "presence": Cursor position update
+   - "users": List of connected users
+   ============================================================================ *)
+
+let json_of_string s =
+  match Simdjsont.Decode.decode_string Simdjsont.Decode.value s with
+  | Ok json -> Some json
+  | Error _ -> None
+
+let string_of_json json = J.to_string json
+
+let get_string_field obj key =
+  match obj with
+  | J.Object fields ->
+      List.find_map
+        (fun (k, v) ->
+          if k = key then match v with J.String s -> Some s | _ -> None
+          else None)
+        fields
+  | _ -> None
+
+let get_float_field obj key =
+  match obj with
+  | J.Object fields ->
+      List.find_map
+        (fun (k, v) ->
+          if k = key then
+            match v with
+            | J.Float f -> Some f
+            | J.Int i -> Some (Int64.to_float i)
+            | _ -> None
+          else None)
+        fields
+  | _ -> None
+
+let get_json_field obj key =
+  match obj with
+  | J.Object fields ->
+      List.find_map (fun (k, v) -> if k = key then Some v else None) fields
+  | _ -> None
+
+let str s = J.String s
+let num f = J.Float f
+let arr items = J.Array items
+let obj fields = J.Object fields
+
+(* Build a users list message *)
+let make_users_msg clients =
+  let users =
+    List.map (fun c -> obj [ ("id", str c.id); ("name", str c.name) ]) clients
+  in
+  obj [ ("type", str "users"); ("users", arr users) ]
+
+(* Build a sync message with the full model *)
+let make_sync_msg model =
+  let binary = Model_codec.Binary.encode model in
+  let b64 = Base64.encode_string (Bytes.to_string binary) in
+  obj [ ("type", str "sync"); ("data", str b64) ]
+
+(* Build a patch relay message *)
+let make_patch_msg patch_b64 sender_id =
+  obj
+    [ ("type", str "patch"); ("data", str patch_b64); ("from", str sender_id) ]
+
+(* Build a presence message *)
+let make_presence_msg client_id client_name x y =
+  obj
+    [
+      ("type", str "presence");
+      ("id", str client_id);
+      ("name", str client_name);
+      ("x", num x);
+      ("y", num y);
+    ]
+
+(* Build a stroke history message *)
+let make_stroke_history_msg strokes =
+  obj [ ("type", str "stroke_history"); ("strokes", arr strokes) ]
+
+(* Build a chat history message *)
+let make_chat_history_msg history =
+  let messages =
+    List.map
+      (fun (sender, text) -> obj [ ("sender", str sender); ("text", str text) ])
+      history
+  in
+  obj [ ("type", str "chat_history"); ("messages", arr messages) ]
+
+(* ============================================================================
+   WebSocket Handlers
+   ============================================================================ *)
+
+let send_to_ws ws msg_str =
+  match Hcs.Websocket.send_text ws msg_str with Ok () -> () | Error _ -> ()
+
+let broadcast_to_others state sender_id msg_json =
+  let msg_str = string_of_json msg_json in
+  List.iter
+    (fun client ->
+      if client.id <> sender_id then
+        match client.websocket with
+        | Some ws -> send_to_ws ws msg_str
+        | None -> ())
+    state.clients
+
+let broadcast_to_all state msg_json =
+  let msg_str = string_of_json msg_json in
+  List.iter
+    (fun client ->
+      match client.websocket with
+      | Some ws -> send_to_ws ws msg_str
+      | None -> ())
+    state.clients
+
+let handle_message state client msg_str =
+  match json_of_string msg_str with
+  | None -> log "Invalid JSON from %s" client.id
+  | Some json -> (
+      match get_string_field json "type" with
+      | Some "patch" -> (
+          (* Client sent a patch - decode, apply, and relay *)
+          match get_string_field json "data" with
+          | Some b64 -> (
+              match Base64.decode b64 with
+              | Ok patch_bytes -> (
+                  let patch_buf = Bytes.of_string patch_bytes in
+                  match Patch_codec_binary.decode patch_buf with
+                  | Ok patch ->
+                      Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+                          (* Apply patch to server model *)
+                          Patch.iter_with_id
+                            (fun id op -> Model.apply_op state.model id op)
+                            patch);
+                      (* Relay to other clients *)
+                      broadcast_to_others state client.id
+                        (make_patch_msg b64 client.id);
+                      log "Patch from %s applied and relayed" client.name
+                  | Error e ->
+                      log "Failed to decode patch from %s: %s" client.name e)
+              | Error _ ->
+                  log "Failed to decode base64 patch from %s" client.name)
+          | None -> ())
+      | Some "presence" ->
+          (* Cursor position update - relay to others *)
+          let x = Option.value (get_float_field json "x") ~default:0.0 in
+          let y = Option.value (get_float_field json "y") ~default:0.0 in
+          broadcast_to_others state client.id
+            (make_presence_msg client.id client.name x y)
+      | Some "drawing" -> (
+          (* Real-time drawing update - relay to others without storing *)
+          let from_json = get_json_field json "from" in
+          let to_json = get_json_field json "to" in
+          let color = get_string_field json "color" in
+          let size = get_float_field json "size" in
+          match (from_json, to_json) with
+          | Some from_pt, Some to_pt ->
+              let drawing_msg =
+                obj
+                  [
+                    ("type", str "drawing");
+                    ("from", from_pt);
+                    ("to", to_pt);
+                    ("color", str (Option.value color ~default:"#000000"));
+                    ("size", num (Option.value size ~default:3.0));
+                  ]
+              in
+              broadcast_to_others state client.id drawing_msg
+          | _ -> ())
+      | Some "stroke" -> (
+          (* Completed stroke - store and relay to others *)
+          match get_json_field json "data" with
+          | Some stroke_data ->
+              Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+                  state.strokes <- state.strokes @ [ stroke_data ]);
+              let relay_msg =
+                obj [ ("type", str "stroke"); ("data", stroke_data) ]
+              in
+              broadcast_to_others state client.id relay_msg;
+              log "Stroke from %s stored and relayed" client.name
+          | None -> ())
+      | Some "chat" -> (
+          (* Chat message - store and relay to others with sender name *)
+          match get_string_field json "text" with
+          | Some text ->
+              Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+                  state.chat_history <-
+                    state.chat_history @ [ (client.name, text) ];
+                  (* Keep only last 100 messages *)
+                  if List.length state.chat_history > 100 then
+                    state.chat_history <-
+                      List.filteri
+                        (fun i _ -> i >= List.length state.chat_history - 100)
+                        state.chat_history);
+              let chat_msg =
+                obj
+                  [
+                    ("type", str "chat");
+                    ("sender", str client.name);
+                    ("text", str text);
+                  ]
+              in
+              broadcast_to_others state client.id chat_msg;
+              log "Chat from %s: %s" client.name text
+          | None -> ())
+      | Some "request_sync" ->
+          (* Client requesting full sync *)
+          let sync_msg =
+            Eio.Mutex.use_ro state.mutex (fun () -> make_sync_msg state.model)
+          in
+          (match client.websocket with
+          | Some ws -> send_to_ws ws (string_of_json sync_msg)
+          | None -> ());
+          log "Sync sent to %s" client.name
+      | Some "set_name" -> (
+          (* Client setting their display name *)
+          match get_string_field json "name" with
+          | Some new_name ->
+              let users_msg =
+                Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+                    (* Update the client's name *)
+                    client.name <- new_name;
+                    make_users_msg state.clients)
+              in
+              (* Broadcast updated user list to all *)
+              broadcast_to_all state users_msg;
+              log "Client %s set name to '%s'" client.id new_name
+          | None -> ())
+      | Some other -> log "Unknown message type '%s' from %s" other client.name
+      | None -> log "Message without type from %s" client.name)
+
+let handle_websocket state (ws : Hcs.Websocket.t) =
+  (* Generate client ID *)
+  let client_id = generate_id () in
+  let client =
+    { id = client_id; name = "User-" ^ client_id; websocket = Some ws }
+  in
+
+  (* Add client to state *)
+  Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+      state.clients <- client :: state.clients);
+
+  log "Client %s connected" client.id;
+
+  (* Send initial sync *)
+  let sync_msg, users_msg, stroke_history_msg, chat_history_msg =
+    Eio.Mutex.use_ro state.mutex (fun () ->
+        ( make_sync_msg state.model,
+          make_users_msg state.clients,
+          make_stroke_history_msg state.strokes,
+          make_chat_history_msg state.chat_history ))
+  in
+
+  send_to_ws ws
+    (string_of_json (obj [ ("type", str "welcome"); ("id", str client_id) ]));
+  send_to_ws ws (string_of_json sync_msg);
+  send_to_ws ws (string_of_json users_msg);
+  send_to_ws ws (string_of_json stroke_history_msg);
+  send_to_ws ws (string_of_json chat_history_msg);
+
+  (* Broadcast new user to others *)
+  broadcast_to_others state client_id users_msg;
+
+  (* Message loop *)
+  let rec loop () =
+    match Hcs.Websocket.recv_message ws with
+    | Error Hcs.Websocket.Connection_closed ->
+        (* Client disconnected *)
+        let users_msg =
+          Eio.Mutex.use_rw ~protect:true state.mutex (fun () ->
+              state.clients <-
+                List.filter (fun c -> c.id <> client_id) state.clients;
+              make_users_msg state.clients)
+        in
+        broadcast_to_all state users_msg;
+        log "Client %s disconnected" client.id
+    | Error (Hcs.Websocket.Protocol_error msg) ->
+        log "Protocol error from %s: %s" client.id msg
+    | Error (Hcs.Websocket.Io_error msg) ->
+        log "IO error from %s: %s" client.id msg
+    | Ok (_opcode, msg) ->
+        handle_message state client msg;
+        loop ()
+  in
+  loop ()
+
+(* ============================================================================
+   HTTP Handler with Routing
+   ============================================================================ *)
+
+let make_handler ~fs ~static_path _state (req : Hcs.Server.request) =
+  let target = req.target in
+  let path =
+    match String.index_opt target '?' with
+    | Some i -> String.sub target 0 i
+    | None -> target
+  in
+  (* Route /ws separately, everything else is static *)
+  if path = "/ws" then
+    (* This shouldn't be reached because WebSocket is handled separately *)
+    Hcs.Server.respond ~status:`Bad_request
+      "WebSocket connections should use the /ws endpoint"
+  else
+    (* Serve static files *)
+    let static_handler = Hcs.Plug.Static.server ~fs static_path in
+    static_handler req
+
+(* ============================================================================
+   Main
+   ============================================================================ *)
+
+let () =
+  Random.self_init ();
+
+  (* Initialize server state with empty model *)
+  let state =
+    {
+      model = Model.create (Random.int 1000000);
+      clients = [];
+      strokes = [];
+      chat_history = [];
+      mutex = Eio.Mutex.create ();
+    }
+  in
+
+  (* Initialize the model with a root object for strokes *)
+  let root_obj_id = Clock.tick state.model.clock.local in
+  let root_obj = Node.make_obj ~id:root_obj_id in
+  Model.add_node state.model root_obj;
+  Node.set_val state.model.root ~value:root_obj_id;
+
+  (* Get port from environment or use default *)
+  let port =
+    match Sys.getenv_opt "PORT" with
+    | Some p -> ( try int_of_string p with _ -> default_port)
+    | None -> default_port
+  in
+
+  (* Find static directory *)
+  let static_path =
+    let candidates =
+      [
+        static_dir;
+        "bin/wb/" ^ static_dir;
+        Filename.concat (Filename.dirname Sys.executable_name) static_dir;
+      ]
+    in
+    List.find_opt Sys.file_exists candidates |> Option.value ~default:static_dir
+  in
+
+  log "Starting Webboard server (HCS) on http://localhost:%d" port;
+  log "Static files from: %s" static_path;
+
+  Eio_main.run @@ fun env ->
+  let net = Eio.Stdenv.net env in
+  let fs = Eio.Stdenv.fs env in
+  Switch.run @@ fun sw ->
+  let config =
+    Hcs.Server.websocket_config |> Hcs.Server.with_port port
+    |> Hcs.Server.without_gc_tuning
+  in
+  let handler = make_handler ~fs ~static_path state in
+  let ws_handler ws = handle_websocket state ws in
+  Hcs.Server.run ~sw ~net ~config ~ws_handler handler

bin/webboard/dune bin/wbd/dune

···
 (executable
- (name webboard)
+ (name wbd)
  (libraries crdt dream base64 lwt)
  (preprocess
   (pps lwt_ppx)))

bin/whiteboard/dune

···
-(executable
- (name whiteboard)
- (public_name crdt-whiteboard)
- (package crdt)
- (libraries crdt crdt_eio eio_main raylib simdjsont))

bin/whiteboard/whiteboard.ml

···
-(** Collaborative Whiteboard Demo
-
-    A real-time collaborative whiteboard with:
-    - Drawing with multiple colors and brush sizes
-    - Real-time cursor presence
-    - Chat functionality
-    - Multi-user networking via Eio
-
-    Usage: ./whiteboard --name "Alice" --host # Start as server ./whiteboard
-    --name "Bob" --connect 192.168.1.1 # Connect to server ./whiteboard --name
-    "Carol" # Local-only mode *)
-
-[@@@warning "-69-32-27-26"]
-
-open Raylib
-module J = Simdjsont.Json
-
-(* ============================================================================
-   Configuration & Scaling
-   ============================================================================ *)
-
-let base_width = 1200
-let base_height = 800
-let default_port = 9999
-let max_chat_messages = 50
-let presence_timeout = 10.0 (* Time before cursor fades *)
-let user_timeout = 30.0 (* Time before user is removed from list *)
-
-let sync_interval =
-  0.5 (* Presence update interval - reduced to avoid flooding *)
-
-(* Mutable layout values that update on resize *)
-let window_width = ref base_width
-let window_height = ref base_height
-
-(* DPI scale - set once at startup based on display, doesn't change on resize *)
-let dpi_scale = ref 1.0
-
-(* Scale for DPI only (not window size) *)
-let scale x = int_of_float (float_of_int x *. !dpi_scale)
-let scalef x = x *. !dpi_scale
-
-(* Get mouse position *)
-let get_mouse_pos () =
-  let mx = float_of_int (get_mouse_x ()) in
-  let my = float_of_int (get_mouse_y ()) in
-  (mx, my)
-
-(* Fixed UI element sizes (scaled for DPI only) *)
-let margin () = scale 10
-let sidebar_width () = scale 280
-let palette_height () = scale 50
-let chat_height () = scale 280
-
-(* Layout calculations - canvas grows/shrinks with window, other elements stay fixed *)
-let canvas_x () = margin ()
-let canvas_y () = margin ()
-
-let canvas_width () =
-  !window_width - canvas_x () - sidebar_width () - (margin () * 2)
-
-let canvas_height () = !window_height - (margin () * 2) - palette_height ()
-let sidebar_x () = !window_width - sidebar_width () - margin ()
-let chat_y () = !window_height - chat_height () - margin ()
-let presence_y () = canvas_y ()
-let presence_height () = chat_y () - presence_y () - margin ()
-
-(* ============================================================================
-   Types
-   ============================================================================ *)
-
-type point = { x : float; y : float }
-
-type stroke = {
-  stroke_id : string;
-  color : int; (* Store as int for serialization *)
-  thickness : float;
-  points : point list;
-}
-
-type user_presence = {
-  user_id : string;
-  user_name : string;
-  cursor_x : float;
-  cursor_y : float;
-  user_color : int;
-  last_seen : float;
-}
-
-type chat_message = {
-  msg_id : string;
-  sender : string;
-  text : string;
-  timestamp : float;
-}
-
-type app_mode = Local | Server | Client of string
-
-type drawing_segment = {
-  draw_user_id : string;
-  draw_color : int;
-  draw_thickness : float;
-  draw_from : point;
-  draw_to : point;
-}
-
-type net_message =
-  | MsgStroke of stroke
-  | MsgDrawing of drawing_segment
-  | MsgPresence of user_presence
-  | MsgChat of chat_message
-  | MsgSync of {
-      strokes : stroke list;
-      messages : chat_message list;
-      users : user_presence list;
-    }
-  | MsgJoin of { user_id : string; user_name : string; user_color : int }
-  | MsgLeave of { user_id : string }
-
-type app_state = {
-  mutable mode : app_mode;
-  mutable my_id : string;
-  mutable my_name : string;
-  mutable my_color : int;
-  mutable is_drawing : bool;
-  mutable current_stroke : point list;
-  mutable strokes : stroke list;
-  mutable brush_color : int;
-  mutable brush_size : float;
-  mutable palette_index : int;
-  users : (string, user_presence) Hashtbl.t; (* user_id -> presence *)
-  mutable messages : chat_message list;
-  mutable chat_input : string;
-  mutable chat_focused : bool;
-  mutable connected : bool;
-  mutable last_presence_sync : float;
-  mutable name_input : string;
-  mutable entering_name : bool;
-  (* Remote drawings: segments from other users currently being drawn *)
-  mutable remote_drawings : drawing_segment list;
-  (* Eio streams for message passing *)
-  incoming : net_message Eio.Stream.t;
-  outgoing : net_message Eio.Stream.t;
-}
-
-(* ============================================================================
-   Colors
-   ============================================================================ *)
-
-(* Multiple palettes - each has black, white, and 8 colors *)
-(* Palette 0: Pastel light *)
-let palette_pastel_light =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xffb3baff;
-    0xffdfbaff;
-    0xffffbaff;
-    0xbaffc9ff;
-    0xbae1ffff;
-    0xbac8ffff;
-    0xe0baffff;
-    0xffbaffff;
-  |]
-
-(* Palette 1: Pastel medium *)
-let palette_pastel_medium =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xf8a5a5ff;
-    0xf8cba5ff;
-    0xf8f8a5ff;
-    0xa5f8b8ff;
-    0xa5d8f8ff;
-    0xa5a5f8ff;
-    0xd8a5f8ff;
-    0xf8a5d8ff;
-  |]
-
-(* Palette 2: Pastel muted *)
-let palette_pastel_muted =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xd4a5a5ff;
-    0xd4bfa5ff;
-    0xd4d4a5ff;
-    0xa5d4b0ff;
-    0xa5c4d4ff;
-    0xa5a5d4ff;
-    0xc4a5d4ff;
-    0xd4a5c4ff;
-  |]
-
-(* Palette 3: Soft warm *)
-let palette_soft_warm =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xe8998dff;
-    0xeab69fff;
-    0xead89fff;
-    0xb5deadff;
-    0x9fd5e8ff;
-    0x9fb5e8ff;
-    0xc49fe8ff;
-    0xe89fc4ff;
-  |]
-
-(* Palette 4: Soft cool *)
-let palette_soft_cool =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0x9db5c4ff;
-    0x9dc4b5ff;
-    0xb5c49dff;
-    0xc4b59dff;
-    0xc49db5ff;
-    0xb59dc4ff;
-    0x9dc5c4ff;
-    0xa5c4c4ff;
-  |]
-
-(* Palette 5: Vibrant *)
-let palette_vibrant =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xff6b6bff;
-    0xffa94dff;
-    0xffd93dff;
-    0x6bcb77ff;
-    0x4d96ffff;
-    0x6b5bffff;
-    0xc56bffff;
-    0xff6bb5ff;
-  |]
-
-(* Palette 6: Earth tones *)
-let palette_earth =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xc9a87cff;
-    0xa8c97cff;
-    0x7cc9a8ff;
-    0x7ca8c9ff;
-    0xa87cc9ff;
-    0xc97ca8ff;
-    0xb5a88fff;
-    0x8fb5a8ff;
-  |]
-
-(* Palette 7: Classic *)
-let palette_classic =
-  [|
-    0x000000ff;
-    0xffffffff;
-    0xff0000ff;
-    0xff8000ff;
-    0xffff00ff;
-    0x00ff00ff;
-    0x00ffffff;
-    0x0000ffff;
-    0x8000ffff;
-    0xff00ffff;
-  |]
-
-let all_palettes =
-  [|
-    palette_pastel_light;
-    palette_pastel_medium;
-    palette_pastel_muted;
-    palette_soft_warm;
-    palette_soft_cool;
-    palette_vibrant;
-    palette_earth;
-    palette_classic;
-  |]
-
-let num_palettes = Array.length all_palettes
-
-(* Get current palette colors *)
-let get_palette idx = all_palettes.(idx mod num_palettes)
-
-let user_colors =
-  [|
-    0xe74c3cff;
-    0x2ecc71ff;
-    0x3498dbff;
-    0x9b59b6ff;
-    0xf1c40fff;
-    0xe67e22ff;
-    0x1abc9cff;
-    0x34495eff;
-  |]
-
-let color_of_int n =
-  Color.create
-    ((n lsr 24) land 0xff)
-    ((n lsr 16) land 0xff)
-    ((n lsr 8) land 0xff)
-    (n land 0xff)
-
-let get_user_color idx = user_colors.(abs idx mod Array.length user_colors)
-
-(* ============================================================================
-   Utilities
-   ============================================================================ *)
-
-let generate_id () =
-  Random.self_init ();
-  String.init 8 (fun _ ->
-      let n = Random.int 36 in
-      if n < 10 then Char.chr (48 + n) else Char.chr (97 + n - 10))
-
-let current_time () = Unix.gettimeofday ()
-let clamp v lo hi = max lo (min hi v)
-
-let point_in_rect x y rx ry rw rh =
-  x >= float_of_int rx
-  && x <= float_of_int (rx + rw)
-  && y >= float_of_int ry
-  && y <= float_of_int (ry + rh)
-
-(* ============================================================================
-   JSON Serialization using Simdjsont
-   ============================================================================ *)
-
-(* Helper to build JSON objects *)
-let obj members = J.Object members
-let arr items = J.Array items
-let str s = J.String s
-let num f = J.Float f
-let int_num i = J.Float (Float.of_int i)
-let mem k v = (k, v)
-
-(* Encode to JSON string - MUST be minified (no newlines) for line-based protocol *)
-let json_to_string json = J.to_string json
-
-(* Build JSON for point *)
-let point_to_json p = arr [ num p.x; num p.y ]
-
-(* Build JSON for stroke (with or without type tag) *)
-let stroke_to_json_obj ~with_type s =
-  let base =
-    [
-      mem "i" (str s.stroke_id);
-      mem "c" (int_num s.color);
-      mem "k" (num s.thickness);
-      mem "p" (arr (List.map point_to_json s.points));
-    ]
-  in
-  obj (if with_type then mem "t" (str "s") :: base else base)
-
-(* Build JSON for user/presence (with or without type tag) *)
-let user_to_json_obj ~with_type p =
-  let base =
-    [
-      mem "i" (str p.user_id);
-      mem "n" (str p.user_name);
-      mem "x" (num p.cursor_x);
-      mem "y" (num p.cursor_y);
-      mem "c" (int_num p.user_color);
-      mem "s" (num p.last_seen);
-    ]
-  in
-  obj (if with_type then mem "t" (str "p") :: base else base)
-
-(* Build JSON for chat message (with or without type tag) *)
-let chat_to_json_obj ~with_type m =
-  let base =
-    [
-      mem "i" (str m.msg_id);
-      mem "n" (str m.sender);
-      mem "x" (str m.text);
-      mem "s" (num m.timestamp);
-    ]
-  in
-  obj (if with_type then mem "t" (str "m") :: base else base)
-
-(* Build JSON for join message *)
-let join_to_json_obj user_id user_name user_color =
-  obj
-    [
-      mem "t" (str "j");
-      mem "i" (str user_id);
-      mem "n" (str user_name);
-      mem "c" (int_num user_color);
-    ]
-
-(* Build JSON for leave message *)
-let leave_to_json_obj user_id = obj [ mem "t" (str "l"); mem "i" (str user_id) ]
-
-(* Build JSON for sync message *)
-let sync_to_json_obj strokes messages users =
-  obj
-    [
-      mem "t" (str "y");
-      mem "s" (arr (List.map (stroke_to_json_obj ~with_type:false) strokes));
-      mem "m" (arr (List.map (chat_to_json_obj ~with_type:false) messages));
-      mem "u" (arr (List.map (user_to_json_obj ~with_type:false) users));
-    ]
-
-(* Build JSON for drawing segment (real-time line) *)
-let drawing_to_json_obj d =
-  obj
-    [
-      mem "t" (str "d");
-      mem "i" (str d.draw_user_id);
-      mem "c" (int_num d.draw_color);
-      mem "k" (num d.draw_thickness);
-      mem "f" (point_to_json d.draw_from);
-      mem "o" (point_to_json d.draw_to);
-    ]
-
-(* Convert message to JSON string *)
-let message_to_json = function
-  | MsgStroke s -> json_to_string (stroke_to_json_obj ~with_type:true s)
-  | MsgDrawing d -> json_to_string (drawing_to_json_obj d)
-  | MsgPresence p -> json_to_string (user_to_json_obj ~with_type:true p)
-  | MsgChat m -> json_to_string (chat_to_json_obj ~with_type:true m)
-  | MsgJoin { user_id; user_name; user_color } ->
-      json_to_string (join_to_json_obj user_id user_name user_color)
-  | MsgLeave { user_id } -> json_to_string (leave_to_json_obj user_id)
-  | MsgSync { strokes; messages; users } ->
-      json_to_string (sync_to_json_obj strokes messages users)
-
-(* JSON parsing helpers *)
-let get_string_field obj key =
-  List.find_map
-    (fun (k, v) ->
-      if k = key then match v with J.String s -> Some s | _ -> None else None)
-    obj
-
-let get_int_field obj key =
-  List.find_map
-    (fun (k, v) ->
-      if k = key then
-        match v with
-        | J.Float f -> Some (Float.to_int f)
-        | J.Int i -> Some (Int64.to_int i)
-        | _ -> None
-      else None)
-    obj
-
-let get_float_field obj key =
-  List.find_map
-    (fun (k, v) ->
-      if k = key then
-        match v with
-        | J.Float f -> Some f
-        | J.Int i -> Some (Int64.to_float i)
-        | _ -> None
-      else None)
-    obj
-
-let get_array_field obj key =
-  List.find_map
-    (fun (k, v) ->
-      if k = key then match v with J.Array items -> Some items | _ -> None
-      else None)
-    obj
-
-(* Parse point from JSON *)
-let parse_point_json = function
-  | J.Array [ J.Float x; J.Float y ] -> Some { x; y }
-  | J.Array [ J.Int x; J.Int y ] ->
-      Some { x = Int64.to_float x; y = Int64.to_float y }
-  | J.Array [ J.Float x; J.Int y ] -> Some { x; y = Int64.to_float y }
-  | J.Array [ J.Int x; J.Float y ] -> Some { x = Int64.to_float x; y }
-  | _ -> None
-
-(* Parse stroke from JSON object members *)
-let parse_stroke_json obj =
-  let stroke_id =
-    Option.value (get_string_field obj "i") ~default:(generate_id ())
-  in
-  let color = Option.value (get_int_field obj "c") ~default:0x000000ff in
-  let thickness = Option.value (get_float_field obj "k") ~default:3.0 in
-  let points =
-    match get_array_field obj "p" with
-    | Some items -> List.filter_map parse_point_json items
-    | None -> []
-  in
-  { stroke_id; color; thickness; points }
-
-(* Parse presence/user from JSON object members *)
-let parse_presence_json obj =
-  let user_id = Option.value (get_string_field obj "i") ~default:"" in
-  let user_name = Option.value (get_string_field obj "n") ~default:"?" in
-  let cursor_x = Option.value (get_float_field obj "x") ~default:0.0 in
-  let cursor_y = Option.value (get_float_field obj "y") ~default:0.0 in
-  let user_color = Option.value (get_int_field obj "c") ~default:0x808080ff in
-  let last_seen =
-    Option.value (get_float_field obj "s") ~default:(current_time ())
-  in
-  { user_id; user_name; cursor_x; cursor_y; user_color; last_seen }
-
-(* Parse chat from JSON object members *)
-let parse_chat_json obj =
-  let msg_id =
-    Option.value (get_string_field obj "i") ~default:(generate_id ())
-  in
-  let sender = Option.value (get_string_field obj "n") ~default:"?" in
-  let text = Option.value (get_string_field obj "x") ~default:"" in
-  let timestamp =
-    Option.value (get_float_field obj "s") ~default:(current_time ())
-  in
-  { msg_id; sender; text; timestamp }
-
-(* Parse array of objects *)
-let parse_array_json items parse_fn =
-  List.filter_map
-    (function J.Object obj -> Some (parse_fn obj) | _ -> None)
-    items
-
-(* Parse drawing segment from JSON object members *)
-let parse_drawing_json obj =
-  let user_id = Option.value (get_string_field obj "i") ~default:"" in
-  let color = Option.value (get_int_field obj "c") ~default:0x000000ff in
-  let thickness = Option.value (get_float_field obj "k") ~default:3.0 in
-  let from_point =
-    match get_array_field obj "f" with
-    | Some items -> (
-        match parse_point_json (J.Array items) with
-        | Some p -> p
-        | None -> { x = 0.; y = 0. })
-    | None -> { x = 0.; y = 0. }
-  in
-  let to_point =
-    match get_array_field obj "o" with
-    | Some items -> (
-        match parse_point_json (J.Array items) with
-        | Some p -> p
-        | None -> { x = 0.; y = 0. })
-    | None -> { x = 0.; y = 0. }
-  in
-  {
-    draw_user_id = user_id;
-    draw_color = color;
-    draw_thickness = thickness;
-    draw_from = from_point;
-    draw_to = to_point;
-  }
-
-(* Parse a network message from JSON string *)
-let parse_message json_str =
-  match Simdjsont.Decode.decode_string Simdjsont.Decode.value json_str with
-  | Error _ -> None
-  | Ok (J.Object obj) -> (
-      match get_string_field obj "t" with
-      | Some "s" -> Some (MsgStroke (parse_stroke_json obj))
-      | Some "d" -> Some (MsgDrawing (parse_drawing_json obj))
-      | Some "p" -> Some (MsgPresence (parse_presence_json obj))
-      | Some "m" -> Some (MsgChat (parse_chat_json obj))
-      | Some "j" ->
-          let user_id = Option.value (get_string_field obj "i") ~default:"" in
-          let user_name =
-            Option.value (get_string_field obj "n") ~default:"?"
-          in
-          let user_color =
-            Option.value (get_int_field obj "c") ~default:0x808080ff
-          in
-          Some (MsgJoin { user_id; user_name; user_color })
-      | Some "l" ->
-          let user_id = Option.value (get_string_field obj "i") ~default:"" in
-          Some (MsgLeave { user_id })
-      | Some "y" ->
-          let strokes =
-            match get_array_field obj "s" with
-            | Some items -> parse_array_json items parse_stroke_json
-            | None -> []
-          in
-          let messages =
-            match get_array_field obj "m" with
-            | Some items -> parse_array_json items parse_chat_json
-            | None -> []
-          in
-          let users =
-            match get_array_field obj "u" with
-            | Some items -> parse_array_json items parse_presence_json
-            | None -> []
-          in
-          Some (MsgSync { strokes; messages; users })
-      | _ -> None)
-  | Ok _ -> None
-
-(* ============================================================================
-   State Management
-   ============================================================================ *)
-
-let create_state ~incoming ~outgoing mode name =
-  Random.self_init ();
-  let my_id = generate_id () in
-  let my_color = get_user_color (Hashtbl.hash my_id) in
-  {
-    mode;
-    my_id;
-    my_name = name;
-    my_color;
-    is_drawing = false;
-    current_stroke = [];
-    strokes = [];
-    brush_color = 0x000000ff;
-    brush_size = 3.0;
-    palette_index = 0;
-    users = Hashtbl.create 32;
-    messages = [];
-    chat_input = "";
-    chat_focused = false;
-    connected = false;
-    last_presence_sync = 0.0;
-    name_input = name;
-    entering_name = name = "";
-    remote_drawings = [];
-    incoming;
-    outgoing;
-  }
-
-let send_message state msg = Eio.Stream.add state.outgoing msg
-
-let add_stroke state stroke ~broadcast =
-  if not (List.exists (fun s -> s.stroke_id = stroke.stroke_id) state.strokes)
-  then begin
-    state.strokes <- state.strokes @ [ stroke ];
-    if broadcast then send_message state (MsgStroke stroke)
-  end
-
-let add_chat state msg ~broadcast =
-  if not (List.exists (fun m -> m.msg_id = msg.msg_id) state.messages) then begin
-    state.messages <- state.messages @ [ msg ];
-    if List.length state.messages > max_chat_messages then
-      state.messages <-
-        List.filteri
-          (fun i _ -> i >= List.length state.messages - max_chat_messages)
-          state.messages;
-    if broadcast then send_message state (MsgChat msg)
-  end
-
-let update_user state user ~broadcast =
-  Hashtbl.replace state.users user.user_id user;
-  if broadcast then send_message state (MsgPresence user)
-
-let process_incoming state =
-  (* Non-blocking take from stream *)
-  let rec drain () =
-    match Eio.Stream.take_nonblocking state.incoming with
-    | None -> ()
-    | Some msg ->
-        (match msg with
-        | MsgStroke s -> add_stroke state s ~broadcast:false
-        | MsgDrawing d when d.draw_user_id <> state.my_id ->
-            (* Add to remote drawings for rendering *)
-            state.remote_drawings <- d :: state.remote_drawings;
-            (* Limit to last 100 segments to prevent memory issues *)
-            if List.length state.remote_drawings > 100 then
-              state.remote_drawings <-
-                List.filteri (fun i _ -> i < 100) state.remote_drawings
-        | MsgDrawing _ -> ()
-        | MsgPresence p when p.user_id <> state.my_id ->
-            update_user state p ~broadcast:false
-        | MsgPresence _ -> ()
-        | MsgChat m -> add_chat state m ~broadcast:false
-        | MsgJoin { user_id; user_name; user_color }
-          when user_id <> state.my_id && user_id <> "" ->
-            let p =
-              {
-                user_id;
-                user_name;
-                cursor_x = 0.;
-                cursor_y = 0.;
-                user_color;
-                last_seen = current_time ();
-              }
-            in
-            update_user state p ~broadcast:false;
-            add_chat state
-              {
-                msg_id = generate_id ();
-                sender = "System";
-                text = user_name ^ " joined";
-                timestamp = current_time ();
-              }
-              ~broadcast:false
-        | MsgJoin _ -> ()
-        | MsgLeave { user_id } -> (
-            let user = Hashtbl.find_opt state.users user_id in
-            Hashtbl.remove state.users user_id;
-            (* Clear remote drawings from this user *)
-            state.remote_drawings <-
-              List.filter
-                (fun d -> d.draw_user_id <> user_id)
-                state.remote_drawings;
-            match user with
-            | Some u ->
-                add_chat state
-                  {
-                    msg_id = generate_id ();
-                    sender = "System";
-                    text = u.user_name ^ " left";
-                    timestamp = current_time ();
-                  }
-                  ~broadcast:false
-            | None -> ())
-        | MsgSync { strokes; messages; users } ->
-            List.iter (fun s -> add_stroke state s ~broadcast:false) strokes;
-            List.iter (fun m -> add_chat state m ~broadcast:false) messages;
-            List.iter
-              (fun u ->
-                if u.user_id <> state.my_id then
-                  update_user state u ~broadcast:false)
-              users);
-        drain ()
-  in
-  drain ()
-
-let cleanup_users state =
-  let now = current_time () in
-  let to_remove =
-    Hashtbl.fold
-      (fun user_id u acc ->
-        if user_id <> state.my_id && now -. u.last_seen >= user_timeout then
-          user_id :: acc
-        else acc)
-      state.users []
-  in
-  List.iter (Hashtbl.remove state.users) to_remove
-
-(* ============================================================================
-   Networking with Eio
-   ============================================================================ *)
-
-(* Set TCP_NODELAY on a socket to disable Nagle's algorithm for low latency *)
-let set_tcp_nodelay flow =
-  match Eio_unix.Resource.fd_opt flow with
-  | Some fd ->
-      Eio_unix.Fd.use_exn "setsockopt" fd (fun unix_fd ->
-          Unix.setsockopt unix_fd Unix.TCP_NODELAY true)
-  | None -> ()
-
-(* Read a line from an Eio flow *)
-let read_line flow buf_reader =
-  let buf = Buffer.create 256 in
-  let rec loop () =
-    match Eio.Buf_read.any_char buf_reader with
-    | '\n' -> Some (Buffer.contents buf)
-    | c ->
-        Buffer.add_char buf c;
-        loop ()
-  in
-  try loop () with End_of_file -> None
-
-(* Write a line to an Eio flow *)
-let write_line flow line = Eio.Flow.copy_string (line ^ "\n") flow
-
-(* Client info tracked by server - using polymorphic type for flow *)
-type 'a client_info = {
-  client_flow : 'a;
-  mutable client_user_id : string option;
-}
-
-(* Handle a single client connection (server-side) *)
-let handle_client ~sw ~state ~clients ~clients_mutex client_info =
-  let flow = client_info.client_flow in
-  set_tcp_nodelay flow;
-  let buf_reader = Eio.Buf_read.of_flow ~max_size:65536 flow in
-
-  (* Send sync to new client *)
-  let my_presence =
-    {
-      user_id = state.my_id;
-      user_name = state.my_name;
-      cursor_x = 0.;
-      cursor_y = 0.;
-      user_color = state.my_color;
-      last_seen = current_time ();
-    }
-  in
-  let all_users =
-    my_presence :: Hashtbl.fold (fun _ u acc -> u :: acc) state.users []
-  in
-  let sync =
-    MsgSync
-      { strokes = state.strokes; messages = state.messages; users = all_users }
-  in
-  (try write_line flow (message_to_json sync) with _ -> ());
-
-  (* Read messages from client *)
-  let rec read_loop () =
-    match read_line flow buf_reader with
-    | None -> () (* Client disconnected *)
-    | Some line -> (
-        match parse_message line with
-        | Some msg ->
-            (* Track user_id from join message *)
-            (match msg with
-            | MsgJoin { user_id; _ } ->
-                client_info.client_user_id <- Some user_id
-            | _ -> ());
-            (* Send to main via stream *)
-            Eio.Stream.add state.incoming msg;
-            (* Broadcast to other clients *)
-            Eio.Mutex.use_rw ~protect:true clients_mutex (fun () ->
-                List.iter
-                  (fun ci ->
-                    if ci.client_flow != flow then
-                      try write_line ci.client_flow (message_to_json msg)
-                      with _ -> ())
-                  !clients);
-            (* If join, send server info back *)
-            (match msg with
-            | MsgJoin _ -> (
-                let server_join =
-                  MsgJoin
-                    {
-                      user_id = state.my_id;
-                      user_name = state.my_name;
-                      user_color = state.my_color;
-                    }
-                in
-                try write_line flow (message_to_json server_join) with _ -> ())
-            | _ -> ());
-            read_loop ()
-        | None -> read_loop ())
-  in
-  Fun.protect
-    ~finally:(fun () ->
-      (* Send leave message when client disconnects *)
-      (match client_info.client_user_id with
-      | Some user_id ->
-          let leave_msg = MsgLeave { user_id } in
-          (* Notify server's main loop *)
-          Eio.Stream.add state.incoming leave_msg;
-          (* Broadcast to other clients *)
-          Eio.Mutex.use_rw ~protect:true clients_mutex (fun () ->
-              List.iter
-                (fun ci ->
-                  if ci.client_flow != flow then
-                    try write_line ci.client_flow (message_to_json leave_msg)
-                    with _ -> ())
-                !clients)
-      | None -> ());
-      (* Remove from client list *)
-      Eio.Mutex.use_rw ~protect:true clients_mutex (fun () ->
-          clients := List.filter (fun ci -> ci.client_flow != flow) !clients))
-    read_loop
-
-(* Server: accept connections and broadcast outgoing messages *)
-let run_server ~sw ~net ~state ~clock port =
-  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, port) in
-  let socket = Eio.Net.listen ~sw ~backlog:16 ~reuse_addr:true net addr in
-  let clients = ref [] in
-  let clients_mutex = Eio.Mutex.create () in
-
-  Printf.printf "Server listening on port %d\n%!" port;
-  state.connected <- true;
-
-  (* Fiber to broadcast outgoing messages from main *)
-  Eio.Fiber.fork ~sw (fun () ->
-      while true do
-        let msg = Eio.Stream.take state.outgoing in
-        let json = message_to_json msg in
-        Eio.Mutex.use_rw ~protect:true clients_mutex (fun () ->
-            clients :=
-              List.filter
-                (fun ci ->
-                  try
-                    write_line ci.client_flow json;
-                    true
-                  with _ -> false)
-                !clients)
-      done);
-
-  (* Accept connections *)
-  while true do
-    Eio.Net.accept_fork ~sw socket
-      ~on_error:(fun _ -> ())
-      (fun flow addr ->
-        Printf.printf "Client connected\n%!";
-        let client_info = { client_flow = flow; client_user_id = None } in
-        Eio.Mutex.use_rw ~protect:true clients_mutex (fun () ->
-            clients := client_info :: !clients);
-        handle_client ~sw ~state ~clients ~clients_mutex client_info)
-  done
-
-(* Client: connect and relay messages *)
-let run_client ~sw ~net ~state ~clock host port =
-  (* Parse IP address from dotted decimal string using Unix *)
-  let inet_addr = Unix.inet_addr_of_string host in
-  let ip_bytes =
-    (* inet_addr is abstract, but we can get the string representation and parse it *)
-    let s = Unix.string_of_inet_addr inet_addr in
-    (* For IPv4, convert "a.b.c.d" to 4 bytes *)
-    let parts = String.split_on_char '.' s in
-    String.init 4 (fun i -> Char.chr (int_of_string (List.nth parts i)))
-  in
-  let ip = Eio.Net.Ipaddr.of_raw ip_bytes in
-  let addr = `Tcp (ip, port) in
-  let flow = Eio.Net.connect ~sw net addr in
-  set_tcp_nodelay flow;
-  let buf_reader = Eio.Buf_read.of_flow ~max_size:65536 flow in
-
-  Printf.printf "Connected to server\n%!";
-  state.connected <- true;
-
-  (* Send join *)
-  let join =
-    MsgJoin
-      {
-        user_id = state.my_id;
-        user_name = state.my_name;
-        user_color = state.my_color;
-      }
-  in
-  write_line flow (message_to_json join);
-
-  (* Fiber to send outgoing messages *)
-  Eio.Fiber.fork ~sw (fun () ->
-      try
-        while true do
-          let msg = Eio.Stream.take state.outgoing in
-          write_line flow (message_to_json msg)
-        done
-      with _ -> ());
-
-  (* Read from server *)
-  let rec read_loop () =
-    match read_line flow buf_reader with
-    | None -> ()
-    | Some line -> (
-        match parse_message line with
-        | Some msg ->
-            Eio.Stream.add state.incoming msg;
-            read_loop ()
-        | None -> read_loop ())
-  in
-  read_loop ()
-
-(* ============================================================================
-   Input Handling
-   ============================================================================ *)
-
-let handle_name_input state ~start_network =
-  if not state.entering_name then ()
-  else begin
-    let rec get_chars () =
-      let key = get_char_pressed () in
-      let code = Uchar.to_int key in
-      if code >= 32 && code < 127 && String.length state.name_input < 20 then begin
-        state.name_input <- state.name_input ^ String.make 1 (Char.chr code);
-        get_chars ()
-      end
-    in
-    get_chars ();
-
-    if is_key_pressed Key.Backspace && String.length state.name_input > 0 then
-      state.name_input <-
-        String.sub state.name_input 0 (String.length state.name_input - 1);
-
-    if is_key_pressed Key.Enter && String.length state.name_input > 0 then begin
-      state.my_name <- state.name_input;
-      state.entering_name <- false;
-      start_network ()
-    end
-  end
-
-let handle_drawing state =
-  if state.entering_name then ()
-  else
-    let mx, my = get_mouse_pos () in
-    let in_canvas =
-      point_in_rect mx my (canvas_x ()) (canvas_y ()) (canvas_width ())
-        (canvas_height ())
-    in
-
-    if in_canvas && not state.chat_focused then begin
-      if is_mouse_button_pressed MouseButton.Left then begin
-        state.is_drawing <- true;
-        state.current_stroke <- [ { x = mx; y = my } ]
-      end
-      else if is_mouse_button_down MouseButton.Left && state.is_drawing then begin
-        match state.current_stroke with
-        | p :: _ when ((mx -. p.x) ** 2.) +. ((my -. p.y) ** 2.) > 9. ->
-            let new_point = { x = mx; y = my } in
-            state.current_stroke <- new_point :: state.current_stroke;
-            (* Send real-time drawing update *)
-            send_message state
-              (MsgDrawing
-                 {
-                   draw_user_id = state.my_id;
-                   draw_color = state.brush_color;
-                   draw_thickness = state.brush_size;
-                   draw_from = p;
-                   draw_to = new_point;
-                 })
-        | _ -> ()
-      end
-      else if is_mouse_button_released MouseButton.Left && state.is_drawing then begin
-        state.is_drawing <- false;
-        if List.length state.current_stroke > 1 then begin
-          let stroke =
-            {
-              stroke_id = generate_id ();
-              color = state.brush_color;
-              thickness = state.brush_size;
-              points = List.rev state.current_stroke;
-            }
-          in
-          add_stroke state stroke ~broadcast:true
-        end;
-        state.current_stroke <- []
-      end
-    end
-    else if is_mouse_button_released MouseButton.Left then begin
-      state.is_drawing <- false;
-      state.current_stroke <- []
-    end
-
-let handle_palette state =
-  if state.entering_name then ()
-  else
-    let palette_y = canvas_y () + canvas_height () + scale 10 in
-    let swatch = scale 30 in
-    let mx, my = get_mouse_pos () in
-
-    if is_mouse_button_pressed MouseButton.Left then
-      let palette = get_palette state.palette_index in
-      Array.iteri
-        (fun i c ->
-          let sx = canvas_x () + scale 70 + (i * (swatch + scale 5)) in
-          if point_in_rect mx my sx palette_y swatch swatch then
-            state.brush_color <- c)
-        palette
-
-let handle_brush_size_and_palette state =
-  if state.entering_name || state.chat_focused then ()
-  else
-    let wheel = get_mouse_wheel_move () in
-    if wheel <> 0. then begin
-      if is_key_down Key.Left_shift || is_key_down Key.Right_shift then begin
-        (* Shift + Wheel: cycle palette *)
-        let delta = if wheel > 0. then 1 else -1 in
-        state.palette_index <-
-          (state.palette_index + delta + num_palettes) mod num_palettes
-      end
-      else
-        (* Wheel alone: change brush size *)
-        state.brush_size <- clamp (state.brush_size +. (wheel *. 2.)) 1. 30.
-    end
-
-let handle_chat state =
-  if state.entering_name then ()
-  else
-    let mx, my = get_mouse_pos () in
-    let input_y = chat_y () + chat_height () - scale 35 in
-
-    if is_mouse_button_pressed MouseButton.Left then
-      state.chat_focused <-
-        point_in_rect mx my (sidebar_x ()) input_y (sidebar_width ()) (scale 30);
-
-    if state.chat_focused then begin
-      let rec get_chars () =
-        let key = get_char_pressed () in
-        let code = Uchar.to_int key in
-        if code >= 32 && code < 127 then begin
-          state.chat_input <- state.chat_input ^ String.make 1 (Char.chr code);
-          get_chars ()
-        end
-      in
-      get_chars ();
-
-      if is_key_pressed Key.Backspace && String.length state.chat_input > 0 then
-        state.chat_input <-
-          String.sub state.chat_input 0 (String.length state.chat_input - 1);
-
-      if is_key_pressed Key.Enter && String.length state.chat_input > 0 then begin
-        let msg =
-          {
-            msg_id = generate_id ();
-            sender = state.my_name;
-            text = state.chat_input;
-            timestamp = current_time ();
-          }
-        in
-        add_chat state msg ~broadcast:true;
-        state.chat_input <- ""
-      end;
-
-      if is_key_pressed Key.Escape then state.chat_focused <- false
-    end
-
-let handle_shortcuts state =
-  if state.entering_name || state.chat_focused then ()
-  else if is_key_pressed Key.C then state.strokes <- []
-
-let handle_resize () =
-  (* Update window dimensions - DPI scale stays constant *)
-  let w = get_screen_width () in
-  let h = get_screen_height () in
-  if w <> !window_width || h <> !window_height then begin
-    window_width := w;
-    window_height := h
-  end
-
-let handle_input state ~start_network =
-  handle_resize ();
-  handle_name_input state ~start_network;
-  handle_drawing state;
-  handle_palette state;
-  handle_brush_size_and_palette state;
-  handle_chat state;
-  handle_shortcuts state
-
-(* ============================================================================
-   Rendering
-   ============================================================================ *)
-
-let draw_name_dialog state =
-  let dw = scale 500 in
-  let dh = scale 180 in
-  let dx = (!window_width - dw) / 2 in
-  let dy = (!window_height - dh) / 2 in
-
-  draw_rectangle 0 0 !window_width !window_height (Color.create 0 0 0 180);
-  draw_rectangle dx dy dw dh Color.raywhite;
-  draw_rectangle_lines dx dy dw dh Color.darkgray;
-
-  draw_text "Enter Your Name"
-    (dx + scale 140)
-    (dy + scale 25)
-    (scale 28) Color.darkgray;
-
-  let ix = dx + scale 50 in
-  let iy = dy + scale 70 in
-  let iw = dw - scale 100 in
-  draw_rectangle ix iy iw (scale 50) Color.white;
-  draw_rectangle_lines ix iy iw (scale 50) Color.blue;
-  draw_text (state.name_input ^ "_")
-    (ix + scale 15)
-    (iy + scale 12)
-    (scale 26) Color.black;
-
-  draw_text "Press ENTER to continue"
-    (dx + scale 140)
-    (dy + scale 140)
-    (scale 18) Color.gray
-
-let draw_stroke stroke =
-  match stroke.points with
-  | [] | [ _ ] -> ()
-  | points ->
-      let color = color_of_int stroke.color in
-      let rec draw = function
-        | [] | [ _ ] -> ()
-        | p1 :: p2 :: rest ->
-            draw_line_ex (Vector2.create p1.x p1.y) (Vector2.create p2.x p2.y)
-              stroke.thickness color;
-            draw (p2 :: rest)
-      in
-      draw points
-
-let draw_current_stroke state =
-  if state.is_drawing && List.length state.current_stroke > 1 then begin
-    let color = color_of_int state.brush_color in
-    let points = List.rev state.current_stroke in
-    let rec draw = function
-      | [] | [ _ ] -> ()
-      | p1 :: p2 :: rest ->
-          draw_line_ex (Vector2.create p1.x p1.y) (Vector2.create p2.x p2.y)
-            state.brush_size color;
-          draw (p2 :: rest)
-    in
-    draw points
-  end
-
-let draw_remote_drawings state =
-  List.iter
-    (fun d ->
-      let color = color_of_int d.draw_color in
-      draw_line_ex
-        (Vector2.create d.draw_from.x d.draw_from.y)
-        (Vector2.create d.draw_to.x d.draw_to.y)
-        d.draw_thickness color)
-    state.remote_drawings
-
-let draw_canvas state =
-  let cx, cy, cw, ch =
-    (canvas_x (), canvas_y (), canvas_width (), canvas_height ())
-  in
-  draw_rectangle cx cy cw ch Color.white;
-  draw_rectangle_lines cx cy cw ch Color.lightgray;
-
-  begin_scissor_mode cx cy cw ch;
-  List.iter draw_stroke state.strokes;
-  draw_remote_drawings state;
-  draw_current_stroke state;
-
-  (* Other users' cursors - skip if outside canvas (cursor at -1,-1) *)
-  let now = current_time () in
-  Hashtbl.iter
-    (fun _ u ->
-      if
-        u.user_id <> state.my_id
-        && now -. u.last_seen < presence_timeout
-        && u.cursor_x >= 0. && u.cursor_y >= 0.
-      then begin
-        let color = color_of_int u.user_color in
-        draw_circle (int_of_float u.cursor_x) (int_of_float u.cursor_y)
-          (scalef 6.) color;
-        draw_circle_lines (int_of_float u.cursor_x) (int_of_float u.cursor_y)
-          (scalef 7.) Color.black;
-        draw_text u.user_name
-          (int_of_float u.cursor_x + scale 12)
-          (int_of_float u.cursor_y - scale 6)
-          (scale 14) color
-      end)
-    state.users;
-  end_scissor_mode ()
-
-let draw_palette state =
-  let py = canvas_y () + canvas_height () + scale 10 in
-  let swatch = scale 30 in
-  let palette = get_palette state.palette_index in
-
-  draw_text "Color:" (canvas_x ()) (py + scale 5) (scale 18) Color.darkgray;
-
-  Array.iteri
-    (fun i c ->
-      let sx = canvas_x () + scale 70 + (i * (swatch + scale 5)) in
-      draw_rectangle sx py swatch swatch (color_of_int c);
-      if c = state.brush_color then
-        draw_rectangle_lines (sx - 2) (py - 2) (swatch + 4) (swatch + 4)
-          Color.gold
-      else draw_rectangle_lines sx py swatch swatch Color.darkgray)
-    palette;
-
-  let size_x =
-    canvas_x () + scale 70
-    + (Array.length palette * (swatch + scale 5))
-    + scale 30
-  in
-  draw_text
-    (Printf.sprintf "Size: %.0f" state.brush_size)
-    size_x
-    (py + scale 5)
-    (scale 18) Color.darkgray;
-  draw_circle
-    (size_x + scale 100)
-    (py + scale 15)
-    state.brush_size
-    (color_of_int state.brush_color)
-
-let draw_users state =
-  let sx, sy, sw, sh =
-    (sidebar_x (), presence_y (), sidebar_width (), presence_height ())
-  in
-  draw_rectangle sx sy sw sh Color.raywhite;
-  draw_rectangle_lines sx sy sw sh Color.lightgray;
-
-  draw_text "Users Online"
-    (sx + scale 10)
-    (sy + scale 10)
-    (scale 22) Color.darkgray;
-
-  let status, color =
-    match state.mode with
-    | Local -> ("Local Mode", Color.gray)
-    | Server ->
-        ( (if state.connected then "Hosting" else "Starting..."),
-          if state.connected then Color.green else Color.orange )
-    | Client _ ->
-        ( (if state.connected then "Connected" else "Connecting..."),
-          if state.connected then Color.green else Color.orange )
-  in
-  draw_text status (sx + scale 10) (sy + scale 40) (scale 16) color;
-
-  let y = ref (sy + scale 70) in
-  draw_circle
-    (sx + scale 20)
-    (!y + scale 10)
-    (scalef 8.)
-    (color_of_int state.my_color);
-  draw_text (state.my_name ^ " (you)") (sx + scale 40) !y (scale 16) Color.black;
-  y := !y + scale 30;
-
-  let now = current_time () in
-  (* Sort users by user_id for stable ordering *)
-  let sorted_users =
-    Hashtbl.fold (fun _ u acc -> u :: acc) state.users []
-    |> List.sort (fun a b -> String.compare a.user_id b.user_id)
-  in
-  List.iter
-    (fun u ->
-      if u.user_id <> state.my_id then begin
-        let alpha =
-          if now -. u.last_seen < presence_timeout then 255 else 100
-        in
-        let c = color_of_int u.user_color in
-        let c = Color.create (Color.r c) (Color.g c) (Color.b c) alpha in
-        draw_circle (sx + scale 20) (!y + scale 10) (scalef 8.) c;
-        draw_text u.user_name
-          (sx + scale 40)
-          !y (scale 16)
-          (if alpha = 255 then Color.black else Color.gray);
-        y := !y + scale 30
-      end)
-    sorted_users
-
-let draw_chat state =
-  let sx, cy, sw, ch =
-    (sidebar_x (), chat_y (), sidebar_width (), chat_height ())
-  in
-  draw_rectangle sx cy sw ch Color.raywhite;
-  draw_rectangle_lines sx cy sw ch Color.lightgray;
-
-  draw_text "Chat" (sx + scale 10) (cy + scale 10) (scale 22) Color.darkgray;
-
-  let msg_y = ref (cy + scale 40) in
-  let msg_h = ch - scale 80 in
-  let line_h = scale 22 in
-  let max_visible = msg_h / line_h in
-  let visible =
-    let total = List.length state.messages in
-    if total > max_visible then
-      List.filteri (fun i _ -> i >= total - max_visible) state.messages
-    else state.messages
-  in
-
-  begin_scissor_mode sx (cy + scale 40) sw msg_h;
-  List.iter
-    (fun m ->
-      let text = Printf.sprintf "%s: %s" m.sender m.text in
-      let max_chars = sw / scale 8 in
-      let display =
-        if String.length text > max_chars then
-          String.sub text 0 (max_chars - 3) ^ "..."
-        else text
-      in
-      let color = if m.sender = "System" then Color.blue else Color.black in
-      draw_text display (sx + scale 10) !msg_y (scale 16) color;
-      msg_y := !msg_y + line_h)
-    visible;
-  end_scissor_mode ();
-
-  let iy = cy + ch - scale 35 in
-  let input_bg = if state.chat_focused then Color.white else Color.lightgray in
-  draw_rectangle (sx + scale 5) iy (sw - scale 10) (scale 30) input_bg;
-  draw_rectangle_lines
-    (sx + scale 5)
-    iy
-    (sw - scale 10)
-    (scale 30)
-    (if state.chat_focused then Color.blue else Color.gray);
-
-  let display =
-    if state.chat_input = "" && not state.chat_focused then "Type to chat..."
-    else state.chat_input ^ if state.chat_focused then "_" else ""
-  in
-  draw_text display
-    (sx + scale 12)
-    (iy + scale 6)
-    (scale 16)
-    (if state.chat_input = "" && not state.chat_focused then Color.gray
-     else Color.black)
-
-let draw_help state =
-  let py = canvas_y () + canvas_height () + palette_height () + scale 5 in
-  draw_text
-    (Printf.sprintf
-       "LMB: Draw | Wheel: Size | Shift+Wheel: Palette (%d/%d) | C: Clear"
-       (state.palette_index + 1) num_palettes)
-    (canvas_x ()) py (scale 14) Color.gray
-
-let render state =
-  begin_drawing ();
-  clear_background (Color.create 240 240 240 255);
-
-  draw_canvas state;
-  draw_palette state;
-  draw_users state;
-  draw_chat state;
-  draw_help state;
-
-  if state.entering_name then draw_name_dialog state;
-  end_drawing ()
-
-(* ============================================================================
-   Update
-   ============================================================================ *)
-
-let update_presence state =
-  if state.entering_name then ()
-  else
-    let now = current_time () in
-    if now -. state.last_presence_sync > sync_interval then begin
-      state.last_presence_sync <- now;
-      let mx, my = get_mouse_pos () in
-      (* Always send presence to keep connection alive, use -1,-1 when outside canvas *)
-      let in_canvas =
-        point_in_rect mx my (canvas_x ()) (canvas_y ()) (canvas_width ())
-          (canvas_height ())
-      in
-      let cursor_x, cursor_y = if in_canvas then (mx, my) else (-1., -1.) in
-      let p =
-        {
-          user_id = state.my_id;
-          user_name = state.my_name;
-          cursor_x;
-          cursor_y;
-          user_color = state.my_color;
-          last_seen = now;
-        }
-      in
-      update_user state p ~broadcast:true
-    end
-
-let update state ~start_network =
-  handle_input state ~start_network;
-  process_incoming state;
-  update_presence state;
-  cleanup_users state
-
-(* ============================================================================
-   Main
-   ============================================================================ *)
-
-let parse_args () =
-  let mode = ref Local in
-  let name = ref "" in
-  let i = ref 1 in
-  while !i < Array.length Sys.argv do
-    (match Sys.argv.(!i) with
-    | "--host" | "-h" -> mode := Server
-    | ("--connect" | "-c") when !i + 1 < Array.length Sys.argv ->
-        incr i;
-        mode := Client Sys.argv.(!i)
-    | ("--name" | "-n") when !i + 1 < Array.length Sys.argv ->
-        incr i;
-        name := Sys.argv.(!i)
-    | s when String.length s > 0 && s.[0] <> '-' && !mode = Local ->
-        mode := Client s
-    | _ -> ());
-    incr i
-  done;
-  (!mode, !name)
-
-let () =
-  let mode, name = parse_args () in
-
-  Eio_main.run @@ fun env ->
-  Eio.Switch.run @@ fun sw ->
-  let net = Eio.Stdenv.net env in
-  let clock = Eio.Stdenv.clock env in
-
-  (* Create message streams *)
-  let incoming = Eio.Stream.create 100 in
-  let outgoing = Eio.Stream.create 100 in
-  let state = create_state ~incoming ~outgoing mode name in
-
-  (* Track if networking has been started *)
-  let network_started = ref false in
-
-  (* Function to start networking (called when name is entered) *)
-  let start_network () =
-    if not !network_started then begin
-      network_started := true;
-      match state.mode with
-      | Local -> ()
-      | Server ->
-          Eio.Fiber.fork ~sw (fun () ->
-              run_server ~sw ~net ~state ~clock default_port)
-      | Client host ->
-          Eio.Fiber.fork ~sw (fun () ->
-              run_client ~sw ~net ~state ~clock host default_port)
-    end
-  in
-
-  (match mode with
-  | Local -> Printf.printf "Local mode\n%!"
-  | Server -> Printf.printf "Server mode on port %d\n%!" default_port
-  | Client h -> Printf.printf "Connecting to %s:%d\n%!" h default_port);
-
-  (* Start networking if name provided *)
-  if name <> "" then start_network ();
-
-  set_config_flags [ ConfigFlags.Msaa_4x_hint; ConfigFlags.Window_resizable ];
-  init_window base_width base_height "CRDT Whiteboard";
-  set_window_min_size 800 600;
-  (* Don't use Raylib's FPS limiter - it blocks and prevents Eio fibers from running *)
-  set_target_fps 0;
-
-  (* Initial dimensions *)
-  window_width := get_screen_width ();
-  window_height := get_screen_height ();
-
-  (* Get DPI scale from system - this detects HiDPI displays *)
-  let dpi_vec = get_window_scale_dpi () in
-  let detected_dpi = max (Vector2.x dpi_vec) (Vector2.y dpi_vec) in
-  (* Use DPI scale if > 1, otherwise use 1.0 *)
-  dpi_scale := if detected_dpi > 1.0 then detected_dpi else 1.0;
-  Printf.printf "DPI scale: %.2f (detected: %.2f x %.2f)\n%!" !dpi_scale
-    (Vector2.x dpi_vec) (Vector2.y dpi_vec);
-
-  let frame_time = 1.0 /. 60.0 in
-  (* Target 60 FPS *)
-  let last_frame = ref (Eio.Time.now clock) in
-
-  while not (window_should_close ()) do
-    update state ~start_network;
-    render state;
-
-    (* Use Eio sleep for frame timing - this allows network fibers to run *)
-    let now = Eio.Time.now clock in
-    let elapsed = now -. !last_frame in
-    let sleep_time = frame_time -. elapsed in
-    if sleep_time > 0.001 then Eio.Time.sleep clock sleep_time;
-    last_frame := Eio.Time.now clock
-  done;
-
-  if state.connected then
-    send_message state (MsgLeave { user_id = state.my_id });
-
-  close_window ();
-  Printf.printf "Goodbye!\n%!"

crdt-eio.opam

···
-# This file is generated by dune, edit dune-project instead
-opam-version: "2.0"
-synopsis: "Eio effect handler for CRDT library"
-description:
-  "Eio-based effect handler for the CRDT library, enabling high-performance concurrent IO for real-time collaborative applications."
-maintainer: ["Guillermo Diaz-Romero <[e-mail]>"]
-authors: ["Guillermo Diaz-Romero <[e-mail]>"]
-license: "MIT"
-tags: ["crdt" "eio" "async" "io"]
-homepage: "https://github.com/gdiazlo/crdt"
-doc: "https://github.com/gdiazlo/crdt"
-bug-reports: "https://github.com/gdiazlo/crdt/issues"
-depends: [
-  "ocaml" {>= "5.2"}
-  "dune" {>= "3.20" & >= "3.20"}
-  "crdt" {= version}
-  "eio" {>= "1.0"}
-  "alcotest" {with-test}
-  "eio_main" {with-test}
-  "odoc" {with-doc}
-]
-build: [
-  ["dune" "subst"] {dev}
-  [
-    "dune"
-    "build"
-    "-p"
-    name
-    "-j"
-    jobs
-    "@install"
-    "@runtest" {with-test}
-    "@doc" {with-doc}
-  ]
-]
-dev-repo: "git+https://github.com/gdiazlo/crdt.git"
-x-maintenance-intent: ["(latest)"]

crdt.opam

···
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
+version: "0.1.0"
 synopsis: "OCaml CRDT library compatible with json-joy"
 description:
-  "A full OCaml 5.4 CRDT library implementing the json-joy specification. Includes JSON CRDT document model, patch operations, multiple codec formats, and JSON-Rx RPC for real-time synchronization."
-maintainer: ["Guillermo Diaz-Romero <[e-mail]>"]
-authors: ["Guillermo Diaz-Romero <[e-mail]>"]
-license: "MIT"
+  "A full OCaml CRDT library implementing the json-joy specification. Includes JSON CRDT document model, patch operations, multiple codec formats, and JSON-Rx RPC for real-time synchronization."
+maintainer: ["Gabriel Díaz"]
+authors: ["Gabriel Díaz"]
+license: "ISC"
 tags: ["crdt" "json-crdt" "collaborative-editing" "json-joy" "ocaml"]
-homepage: "https://github.com/gdiazlo/crdt"
-doc: "https://github.com/gdiazlo/crdt"
-bug-reports: "https://github.com/gdiazlo/crdt/issues"
+homepage: "https://tangled.org/gdiazlo.tngl.sh/crdt"
+doc: "https://tangled.org/gdiazlo.tngl.sh/crdt"
+bug-reports: "https://tangled.org/gdiazlo.tngl.sh/crdt/issues"
 depends: [
   "ocaml" {>= "5.2"}
   "dune" {>= "3.20" & >= "3.20"}
···
     "@doc" {with-doc}
   ]
 ]
-dev-repo: "git+https://github.com/gdiazlo/crdt.git"
+dev-repo: "git+https://tangled.org/gdiazlo.tngl.sh/crdt"
 x-maintenance-intent: ["(latest)"]

docs/README.md

···
+# OCaml CRDT Library
+
+A full OCaml 5.2+ implementation of JSON CRDTs compatible with [json-joy](https://github.com/streamich/json-joy).
+
+## Overview
+
+This library provides:
+
+- **JSON CRDT Document Model** - 7 node types for representing any JSON structure
+- **Patch Operations** - 18 opcodes for document mutations
+- **Multiple Codec Formats** - Verbose, Compact, Binary, Sidecar, Indexed
+- **JSON-Rx RPC Protocol** - Real-time synchronization over WebSocket/TCP
+- **Full ClockVector Support** - Multi-session conflict resolution
+
+## Installation
+
+```bash
+opam install crdt
+```
+
+## Quick Example
+
+```ocaml
+open Crdt
+
+(* Create a new document *)
+let model = Model.create 12345
+
+(* Build a patch to set root to an object with a "name" field *)
+let patch = Patch_builder.create model
+  |> Patch_builder.set_root_obj
+  |> Patch_builder.set_string "name" "Alice"
+  |> Patch_builder.build
+
+(* Apply the patch *)
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch;
+
+(* View the document as JSON *)
+let json = Model.view model
+(* => Object [("name", String "Alice")] *)
+
+(* Encode to binary for transmission *)
+let bytes = Model_codec.Binary.encode model
+```
+
+## Documentation
+
+- [Architecture](architecture.md) - Module structure and design
+- [json-joy Mapping](json-joy-mapping.md) - TypeScript to OCaml mapping
+- [Codecs](codecs.md) - Encoding formats explained
+- [Getting Started](getting-started.md) - Tutorial with examples
+
+## Compatibility
+
+This library is wire-compatible with json-joy. Documents encoded in one can be decoded in the other. The conformance test suite in `test/fixtures/traces/` validates this compatibility.
+
+## Module Index
+
+| Module | Description |
+|--------|-------------|
+| `Crdt.Model` | Document container |
+| `Crdt.Patch` | Operation batch |
+| `Crdt.Node` | 7 CRDT node types |
+| `Crdt.Op` | 18 operation opcodes |
+| `Crdt.Clock` | Logical timestamps |
+| `Crdt.Rx` | JSON-Rx RPC protocol |
+| `Crdt.Model_codec` | All codec formats |
+
+## Demo Applications
+
+Three demo applications showcase real-time collaboration between OCaml (this library) and TypeScript (json-joy):
+
+### wb - HCS WebSocket Server
+
+A collaborative whiteboard server using the [HCS](https://github.com/dialohq/hcs) HTTP library (Eio-based).
+
+```bash
+dune exec bin/wb/wb.exe
+# or with custom port
+PORT=3000 dune exec bin/wb/wb.exe
+```
+
+- **Runtime**: Eio (OCaml 5 effects)
+- **Protocol**: WebSocket with JSON messages
+- **Frontend**: HTML Canvas + json-joy
+- **Features**: Drawing, presence cursors, chat, stroke history
+
+Open `http://localhost:8080` in multiple browsers to collaborate.
+
+### wbd - Dream WebSocket Server
+
+Same whiteboard application using the [Dream](https://aantron.github.io/dream/) framework (Lwt-based).
+
+```bash
+dune exec bin/wbd/wbd.exe
+```
+
+- **Runtime**: Lwt (promise-based async)
+- **Protocol**: WebSocket with JSON messages
+- **Frontend**: Shared with wb (`static/`)
+
+Useful for comparing Eio vs Lwt implementations.
+
+### wbr - Raylib Native GUI
+
+A native desktop whiteboard using [Raylib](https://www.raylib.com/) for graphics.
+
+```bash
+dune exec bin/wbr/wbr.exe -- --name "Alice" --host        # Start server
+dune exec bin/wbr/wbr.exe -- --name "Bob" --connect HOST  # Connect to server
+dune exec bin/wbr/wbr.exe -- --name "Carol"               # Local-only mode
+```
+
+- **Runtime**: Eio with Raylib bindings
+- **Protocol**: Binary TCP with length-prefixed frames
+- **Features**: Drawing, colors, brush sizes, presence, chat panel
+
+### Interoperability
+
+All demos demonstrate interoperability with json-joy:
+
+1. **Wire format**: Binary patches encoded by OCaml can be decoded by json-joy and vice versa
+2. **Web frontend**: The HTML/JS frontend uses json-joy for CRDT operations
+3. **Sync protocol**: JSON-Rx messages are compatible between implementations
+
+## License
+
+ISC

docs/architecture.md

···
+# Architecture
+
+## Module Organization
+
+```
+crdt/
+├── Core Types
+│   ├── Clock          Logical timestamps and clock vectors
+│   ├── Session        Session ID constants
+│   ├── Value          JSON values + CBOR extensions
+│   └── Pointer        JSON Pointer (RFC 6901)
+│
+├── Document Model
+│   ├── Node           7 CRDT node types
+│   ├── Rga            Replicated Growable Array
+│   ├── Model          Document container
+│   └── Model_api      High-level editing API
+│
+├── Patch Operations
+│   ├── Op             18 operation opcodes
+│   ├── Patch          Patch container
+│   └── Patch_builder  Builder pattern for patches
+│
+├── Codecs
+│   ├── Model_codec          Unified interface
+│   ├── Model_codec_verbose  Human-readable JSON
+│   ├── Model_codec_compact  Compact JSON
+│   ├── Model_codec_sidecar  View + metadata split
+│   ├── Model_codec_indexed  Flat timestamp map
+│   ├── Patch_codec          Verbose patch JSON
+│   ├── Patch_codec_compact  Compact patch JSON
+│   └── Patch_codec_binary   Binary patch format
+│
+├── RPC
+│   ├── Rx             Message types
+│   ├── Rx_codec       Message encoding
+│   ├── Rx_server      Server dispatcher
+│   └── Rx_client      Client correlator
+│
+├── IO
+│   ├── Io_intf        Effect-based IO signatures
+│   └── Io_unix        Unix blocking handler
+│
+└── Extensions
+    ├── Counter        PN-Counter on vec
+    └── Mval           Multi-value register on arr
+```
+
+## Core Concepts
+
+### Timestamps
+
+Every node and operation has a unique timestamp `{sid; time}`:
+
+```ocaml
+type timestamp = {
+  sid : int;   (* Session ID - identifies the replica *)
+  time : int;  (* Logical time - monotonically increasing *)
+}
+```
+
+Timestamps provide:
+- **Unique identity** - No two operations share a timestamp
+- **Causal ordering** - Higher time = happened later (within session)
+- **Conflict resolution** - LWW uses timestamp comparison
+
+### Clock Vector
+
+Tracks observed timestamps from all sessions:
+
+```ocaml
+type clock_vector = {
+  local : logical_clock;           (* This session's clock *)
+  peers : (int * int) list;        (* Observed (sid, time) pairs *)
+}
+```
+
+### Document Model
+
+A `Model.t` contains:
+
+```ocaml
+type t = {
+  clock : Clock.clock_vector;      (* Vector clock *)
+  root : Node.t;                   (* Root val node at (0,0) *)
+  index : Node.t NodeIndex.t;      (* Timestamp -> Node map *)
+}
+```
+
+The root is always a `val` node at timestamp `(0, 0)`. It points to the actual document content.
+
+### Node Types
+
+Seven node types represent different JSON structures:
+
+| Node | JSON Type | CRDT Type | Description |
+|------|-----------|-----------|-------------|
+| `con` | any | Immutable | Constant value (primitives, nested refs) |
+| `val` | - | LWW Register | Mutable reference to another node |
+| `obj` | object | LWW-Map | String-keyed map |
+| `vec` | - | LWW Tuple | Fixed slots (0-255) |
+| `arr` | array | RGA | Ordered list of references |
+| `str` | string | RGA | Mutable text |
+| `bin` | - | RGA | Mutable binary data |
+
+### RGA (Replicated Growable Array)
+
+The core algorithm for `arr`, `str`, and `bin` nodes. Each element has a unique timestamp allowing:
+
+- Concurrent insertions without conflicts
+- Tombstone-based deletion
+- Deterministic ordering across replicas
+
+```ocaml
+type 'a chunk = {
+  id : Clock.timestamp;     (* First element's ID *)
+  span : int;               (* Number of elements *)
+  data : 'a;                (* Content (string/bytes/refs) *)
+  deleted : bool;           (* Tombstone flag *)
+}
+
+type 'a t = {
+  chunks : 'a chunk list;   (* Ordered chunks *)
+}
+```
+
+### Patch Operations
+
+18 opcodes modify the document:
+
+**Creation** (consume 1 ID each):
+- `new_con` - Create constant node
+- `new_val` - Create value node
+- `new_obj` - Create object node
+- `new_vec` - Create vector node
+- `new_str` - Create string node
+- `new_bin` - Create binary node
+- `new_arr` - Create array node
+
+**Mutation**:
+- `ins_val` - Set value reference
+- `ins_obj` - Set object entries
+- `ins_vec` - Set vector slot
+- `ins_str` - Insert text (consumes N IDs for N chars)
+- `ins_bin` - Insert bytes (consumes N IDs for N bytes)
+- `ins_arr` - Insert array element
+
+**Update**:
+- `upd_arr` - Update array element in place
+
+**Delete**:
+- `del` - Delete ranges from RGA nodes
+
+**Utility**:
+- `nop` - No-op padding
+
+### Patch Structure
+
+```ocaml
+type t = {
+  id : Clock.timestamp;    (* Starting timestamp *)
+  ops : Op.op_data list;   (* Sequence of operations *)
+}
+```
+
+Operations are assigned consecutive IDs based on their span. For example, `ins_str` with "hello" consumes 5 IDs.
+
+## Data Flow
+
+```
+User Edit
+    │
+    ▼
+Patch_builder ──► Patch ──► Model.apply_op
+    │                              │
+    ▼                              ▼
+Patch_codec ◄──────────────► Model_codec
+    │                              │
+    ▼                              ▼
+  Wire                           Wire
+(JSON/Binary)                 (JSON/Binary)
+```
+
+## Thread Safety
+
+The library is not thread-safe by default. Use external synchronization (e.g., `Eio.Mutex`) when sharing models across fibers/threads.

docs/codecs.md

···
+# Codec Formats
+
+This library supports multiple encoding formats for documents and patches, matching json-joy's codec system.
+
+## Document Codecs
+
+### Binary (Recommended for Wire)
+
+Compact binary format optimized for size and speed.
+
+```ocaml
+(* Encode *)
+let bytes = Model_codec.Binary.encode model
+
+(* Decode *)
+let model = Model_codec.Binary.decode bytes
+```
+
+**Characteristics:**
+- Smallest size
+- Fastest encode/decode
+- Not human-readable
+- Use for: Network transmission, storage
+
+### Verbose JSON
+
+Human-readable JSON with explicit structure.
+
+```ocaml
+let json = Model_codec_verbose.encode model
+let model = Model_codec_verbose.decode json
+```
+
+**Example output:**
+```json
+{
+  "root": [0, 0],
+  "clock": {"sid": 12345, "time": 5},
+  "nodes": [
+    {"type": "val", "id": [0, 0], "value": [12345, 1]},
+    {"type": "obj", "id": [12345, 1], "entries": [
+      {"key": "name", "value": [12345, 2], "ts": [12345, 3]}
+    ]},
+    {"type": "con", "id": [12345, 2], "value": "Alice"}
+  ]
+}
+```
+
+**Use for:** Debugging, logging, human inspection
+
+### Compact JSON
+
+Compressed JSON with type codes instead of names.
+
+```ocaml
+let json = Model_codec_compact.encode model
+let model = Model_codec_compact.decode json
+```
+
+**Example output:**
+```json
+[
+  [0, 12345, 5],
+  [1, 0, 0, 12345, 1],
+  [3, 12345, 1, [["name", 12345, 2, 12345, 3]]],
+  [0, 12345, 2, "Alice"]
+]
+```
+
+**Use for:** JSON APIs where size matters
+
+### Sidecar
+
+Separates the document view from CRDT metadata.
+
+```ocaml
+let (view, sidecar) = Model_codec_sidecar.encode model
+let model = Model_codec_sidecar.decode view sidecar
+```
+
+**Use for:** 
+- Serving view to read-only clients
+- Caching views separately from metadata
+- Progressive loading
+
+### Indexed
+
+Flat map keyed by timestamp strings.
+
+```ocaml
+let json = Model_codec_indexed.encode model
+let model = Model_codec_indexed.decode json
+```
+
+**Example output:**
+```json
+{
+  "0.0": {"type": "val", "value": "12345.1"},
+  "12345.1": {"type": "obj", "entries": {"name": "12345.2"}},
+  "12345.2": {"type": "con", "value": "Alice"}
+}
+```
+
+**Use for:** Random access by timestamp, database storage
+
+## Patch Codecs
+
+### Verbose JSON
+
+```ocaml
+let json = Patch_codec.encode patch
+let patch = Patch_codec.decode json
+```
+
+**Example:**
+```json
+{
+  "id": [12345, 0],
+  "ops": [
+    {"op": "new_obj"},
+    {"op": "ins_val", "obj": [0, 0], "value": [12345, 0]},
+    {"op": "new_con", "value": "Alice"},
+    {"op": "ins_obj", "obj": [12345, 0], "entries": [
+      ["name", [12345, 1]]
+    ]}
+  ]
+}
+```
+
+### Compact JSON
+
+```ocaml
+let json = Patch_codec_compact.encode patch
+let patch = Patch_codec_compact.decode json
+```
+
+### Binary
+
+```ocaml
+let bytes = Patch_codec_binary.encode patch
+let patch = Patch_codec_binary.decode bytes
+```
+
+## Format Comparison
+
+| Format | Size | Speed | Human-Readable | Use Case |
+|--------|------|-------|----------------|----------|
+| Binary | Smallest | Fastest | No | Wire, storage |
+| Compact JSON | Small | Fast | Partially | JSON APIs |
+| Verbose JSON | Large | Moderate | Yes | Debugging |
+| Sidecar | Medium | Moderate | View only | Read-only clients |
+| Indexed | Medium | Fast lookup | Partially | Databases |
+
+## CBOR Support
+
+Low-level CBOR primitives are available:
+
+```ocaml
+(* Encode value to CBOR *)
+let cbor_bytes = Cbor_simd.encode value
+
+(* Decode CBOR to value *)
+let value = Cbor_simd.decode cbor_bytes
+```
+
+CBOR is used internally by the binary codec.
+
+## Codec Selection Guide
+
+```
+Need smallest size?
+  └─► Binary
+
+Need JSON compatibility?
+  ├─► API responses → Compact JSON
+  └─► Debugging → Verbose JSON
+
+Need view/metadata separation?
+  └─► Sidecar
+
+Need random timestamp access?
+  └─► Indexed
+```

docs/getting-started.md

···
+# Getting Started
+
+## Installation
+
+```bash
+opam install crdt
+```
+
+## Basic Usage
+
+### Creating a Document
+
+```ocaml
+open Crdt
+
+(* Create a new document with session ID 12345 *)
+let model = Model.create 12345
+```
+
+The session ID should be unique per replica/user. Use a random number or derive from user ID.
+
+### Building and Applying Patches
+
+```ocaml
+(* Create a patch that sets root to an object with fields *)
+let patch = Patch_builder.create model
+  |> Patch_builder.set_root_obj
+  |> Patch_builder.set_string "title" "Hello"
+  |> Patch_builder.set_int "count" 42
+  |> Patch_builder.build
+
+(* Apply the patch *)
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+```
+
+### Viewing the Document
+
+```ocaml
+(* Get the document as a Value.t *)
+let view = Model.view model
+
+(* Pattern match on the value *)
+match view with
+| Value.Object fields ->
+    List.iter (fun (k, v) ->
+      Printf.printf "%s = %s\n" k (Value.to_string v)
+    ) fields
+| _ -> ()
+```
+
+### Encoding for Transmission
+
+```ocaml
+(* Binary (smallest, fastest) *)
+let bytes = Model_codec.Binary.encode model
+
+(* JSON (human-readable) *)
+let json = Model_codec_verbose.encode model
+```
+
+### Decoding
+
+```ocaml
+(* From binary *)
+let model = Model_codec.Binary.decode bytes
+
+(* From JSON *)
+let model = Model_codec_verbose.decode json
+```
+
+## Working with Text
+
+```ocaml
+(* Create a document with a text field *)
+let model = Model.create 1
+
+let patch = Patch_builder.create model
+  |> Patch_builder.set_root_obj
+  |> Patch_builder.set_text "content" "Hello, World!"
+  |> Patch_builder.build
+
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+
+(* Later, insert text at position *)
+let insert_patch = Patch_builder.create model
+  |> Patch_builder.insert_text_at ~field:"content" ~pos:7 "CRDT "
+  |> Patch_builder.build
+
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) insert_patch
+(* Result: "Hello, CRDT World!" *)
+```
+
+## Working with Arrays
+
+```ocaml
+let model = Model.create 1
+
+(* Create array with initial elements *)
+let patch = Patch_builder.create model
+  |> Patch_builder.set_root_arr
+  |> Patch_builder.arr_push_string "first"
+  |> Patch_builder.arr_push_string "second"
+  |> Patch_builder.build
+
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+```
+
+## Synchronization
+
+### Encoding Patches for Network
+
+```ocaml
+(* Sender side *)
+let patch_bytes = Patch_codec_binary.encode patch
+(* Send patch_bytes over network *)
+
+(* Receiver side *)
+match Patch_codec_binary.decode patch_bytes with
+| Ok patch ->
+    Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+| Error msg ->
+    Printf.eprintf "Decode error: %s\n" msg
+```
+
+### Forking for New Session
+
+```ocaml
+(* Create a replica with a new session ID *)
+let replica = Model.fork model 67890
+```
+
+## JSON-Rx RPC
+
+For real-time sync over WebSocket:
+
+```ocaml
+open Crdt
+
+(* Create a request *)
+let req = Rx.request ~id:1 ~method_:"sync" ()
+
+(* Encode to JSON *)
+let json = Rx_codec.encode_message req
+
+(* Parse response *)
+match Rx_codec.decode_message json with
+| Ok (Rx.Response { id; data }) ->
+    Printf.printf "Got response %d\n" id
+| Ok (Rx.Error { id; error }) ->
+    Printf.printf "Got error %d\n" id
+| _ -> ()
+```
+
+## Example: Collaborative Counter
+
+```ocaml
+open Crdt
+
+(* Each user has their own model *)
+let alice_model = Model.create 1
+let bob_model = Model.create 2
+
+(* Alice initializes the counter *)
+let init_patch = Patch_builder.create alice_model
+  |> Patch_builder.set_root_obj
+  |> Patch_builder.set_int "count" 0
+  |> Patch_builder.build
+
+Patch.iter_with_id (fun id op -> Model.apply_op alice_model id op) init_patch;
+
+(* Sync to Bob *)
+let bytes = Model_codec.Binary.encode alice_model in
+let bob_model = Model_codec.Binary.decode bytes
+
+(* Alice increments *)
+let alice_inc = Patch_builder.create alice_model
+  |> Patch_builder.set_int "count" 1
+  |> Patch_builder.build
+
+(* Bob increments concurrently *)
+let bob_inc = Patch_builder.create bob_model
+  |> Patch_builder.set_int "count" 1
+  |> Patch_builder.build
+
+(* Apply both patches to both models - LWW resolves conflict *)
+Patch.iter_with_id (fun id op -> Model.apply_op alice_model id op) alice_inc;
+Patch.iter_with_id (fun id op -> Model.apply_op alice_model id op) bob_inc;
+
+Patch.iter_with_id (fun id op -> Model.apply_op bob_model id op) bob_inc;
+Patch.iter_with_id (fun id op -> Model.apply_op bob_model id op) alice_inc;
+
+(* Both models converge to the same state *)
+```
+
+## Next Steps
+
+- See [Architecture](architecture.md) for module details
+- See [json-joy Mapping](json-joy-mapping.md) for TypeScript comparison
+- See [Codecs](codecs.md) for encoding options
+- Check `bin/wb/` for an HCS WebSocket server example
+- Check `bin/wbd/` for a Dream WebSocket server example
+- Check `bin/wbr/` for a Raylib GUI example

docs/json-joy-mapping.md

···
+# json-joy to OCaml Mapping
+
+This document maps concepts between [json-joy](https://github.com/streamich/json-joy) (TypeScript) and this OCaml implementation.
+
+## Type Mapping
+
+### Core Types
+
+| json-joy (TypeScript) | OCaml | Notes |
+|----------------------|-------|-------|
+| `ITimestamp` | `Clock.timestamp` | `{sid: int; time: int}` |
+| `ITimespan` | `Clock.timespan` | `{sid; time; span}` |
+| `ClockVector` | `Clock.clock_vector` | Vector clock with local + peers |
+| `ServerClockVector` | `Clock.clock_vector` | Same type, server context |
+
+### Document Model
+
+| json-joy | OCaml | Notes |
+|----------|-------|-------|
+| `Model` | `Crdt.Model.t` | Document container |
+| `JsonNode` | `Crdt.Node.t` | Sum type for all nodes |
+| `ConNode` | `Node.Con of con_node` | Constant value |
+| `ValNode` | `Node.Val of val_node` | LWW register |
+| `ObjNode` | `Node.Obj of obj_node` | LWW-Map |
+| `VecNode` | `Node.Vec of vec_node` | Fixed tuple |
+| `ArrNode` | `Node.Arr of arr_node` | RGA list |
+| `StrNode` | `Node.Str of str_node` | RGA string |
+| `BinNode` | `Node.Bin of bin_node` | RGA binary |
+
+### Operations
+
+| json-joy | OCaml | ID Span |
+|----------|-------|---------|
+| `NewConOp` | `Op.New_con` | 1 |
+| `NewValOp` | `Op.New_val` | 1 |
+| `NewObjOp` | `Op.New_obj` | 1 |
+| `NewVecOp` | `Op.New_vec` | 1 |
+| `NewStrOp` | `Op.New_str` | 1 |
+| `NewBinOp` | `Op.New_bin` | 1 |
+| `NewArrOp` | `Op.New_arr` | 1 |
+| `InsValOp` | `Op.Ins_val` | 0 |
+| `InsObjOp` | `Op.Ins_obj` | 0 |
+| `InsVecOp` | `Op.Ins_vec` | 0 |
+| `InsStrOp` | `Op.Ins_str` | len(text) |
+| `InsBinOp` | `Op.Ins_bin` | len(bytes) |
+| `InsArrOp` | `Op.Ins_arr` | 1 |
+| `UpdArrOp` | `Op.Upd_arr` | 0 |
+| `DelOp` | `Op.Del` | 0 |
+| `NopOp` | `Op.Nop` | configurable |
+
+### Codecs
+
+| json-joy Class | OCaml Module |
+|----------------|--------------|
+| `VerboseJsonEncoder` | `Model_codec_verbose` |
+| `VerboseJsonDecoder` | `Model_codec_verbose` |
+| `CompactJsonEncoder` | `Model_codec_compact` |
+| `CompactJsonDecoder` | `Model_codec_compact` |
+| `SidecarEncoder` | `Model_codec_sidecar` |
+| `SidecarDecoder` | `Model_codec_sidecar` |
+| `IndexedEncoder` | `Model_codec_indexed` |
+| `IndexedDecoder` | `Model_codec_indexed` |
+| `StructuralBinaryEncoder` | `Model_codec.Binary` |
+| `StructuralBinaryDecoder` | `Model_codec.Binary` |
+| `Encoder` (patch) | `Patch_codec` |
+| `Decoder` (patch) | `Patch_codec` |
+| `BinaryEncoder` (patch) | `Patch_codec_binary` |
+| `BinaryDecoder` (patch) | `Patch_codec_binary` |
+
+### JSON-Rx
+
+| json-joy | OCaml |
+|----------|-------|
+| `RxRequest` | `Rx.Request` |
+| `RxResponse` | `Rx.Response` |
+| `RxError` | `Rx.Error` |
+| `RxNotification` | `Rx.Notification` |
+| `RxSubscribe` | `Rx.Subscribe` |
+| `RxUnsubscribe` | `Rx.Unsubscribe` |
+| `RxData` | `Rx.Data` |
+| `RxComplete` | `Rx.Complete` |
+
+## Code Comparison
+
+### Creating a Document
+
+**TypeScript (json-joy):**
+```typescript
+import {Model} from 'json-joy/lib/json-crdt';
+
+const model = Model.create();
+model.api.root({
+  name: 'Alice',
+  age: 30
+});
+```
+
+**OCaml:**
+```ocaml
+open Crdt
+
+let model = Model.create 12345 in
+let patch = Patch_builder.create model
+  |> Patch_builder.set_root_obj
+  |> Patch_builder.set_string "name" "Alice"
+  |> Patch_builder.set_int "age" 30
+  |> Patch_builder.build in
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+```
+
+### Encoding to Binary
+
+**TypeScript:**
+```typescript
+import {encode} from 'json-joy/lib/json-crdt/codec/structural/binary';
+
+const bytes = encode(model);
+```
+
+**OCaml:**
+```ocaml
+let bytes = Model_codec.Binary.encode model
+```
+
+### Applying a Patch
+
+**TypeScript:**
+```typescript
+model.applyPatch(patch);
+```
+
+**OCaml:**
+```ocaml
+Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch
+```
+
+### Viewing Document as JSON
+
+**TypeScript:**
+```typescript
+const json = model.view();
+```
+
+**OCaml:**
+```ocaml
+let json = Model.view model
+```
+
+## Architectural Differences
+
+| Aspect | json-joy | OCaml crdt |
+|--------|----------|------------|
+| Style | OOP with classes | Functional with modules |
+| Mutability | Mutable by default | Explicit mutable fields |
+| Error handling | Exceptions | `Result` types in codecs |
+| Async | Promises | Effects (Io_intf) |
+| Encoding | Encoder/Decoder classes | `encode`/`decode` functions |
+
+## Wire Compatibility
+
+Documents and patches encoded by one implementation can be decoded by the other. The binary format is identical.
+
+Test traces in `test/fixtures/traces/` validate this:
+
+```
+traces/
+├── text/
+│   ├── sequential/    # Single-user editing traces
+│   └── concurrent/    # Multi-user conflict traces
+├── fuzzer/            # Randomly generated operations
+└── json/              # JSON document traces
+```
+
+Each trace contains:
+- `ops.json` - Original operations
+- `model.bin` - Binary encoded final state
+- `model.compact.json` - Compact JSON encoded
+- `patches.bin` - Binary encoded patches

dune-project

···
 (lang dune 3.20)
 
 (name crdt)
+(version 0.1.0)
 
 (generate_opam_files true)
 
 (source
- (github gdiazlo/crdt))
+ ; (tangled @gdiazlo.tngl.sh/simdjsont)
+ (uri git+https://tangled.org/gdiazlo.tngl.sh/crdt))
 
-(authors "Guillermo Diaz-Romero <[e-mail]>")
+(authors "Gabriel Díaz")
 
-(maintainers "Guillermo Diaz-Romero <[e-mail]>")
+(maintainers "Gabriel Díaz")
 
-(license MIT)
-
-(documentation https://github.com/gdiazlo/crdt)
+(license ISC)
+(homepage https://tangled.org/gdiazlo.tngl.sh/crdt)
+(bug_reports https://tangled.org/gdiazlo.tngl.sh/crdt/issues)
+(documentation https://tangled.org/gdiazlo.tngl.sh/crdt)
 
 (package
  (name crdt)
  (synopsis "OCaml CRDT library compatible with json-joy")
  (description
-  "A full OCaml 5.4 CRDT library implementing the json-joy specification. \
+  "A full OCaml CRDT library implementing the json-joy specification. \
    Includes JSON CRDT document model, patch operations, multiple codec formats, \
    and JSON-Rx RPC for real-time synchronization.")
   (depends
···
  (tags
   (crdt json-crdt collaborative-editing json-joy ocaml)))
 
-(package
- (name crdt-eio)
- (synopsis "Eio effect handler for CRDT library")
- (description
-  "Eio-based effect handler for the CRDT library, enabling high-performance \
-   concurrent IO for real-time collaborative applications.")
- (depends
-  (ocaml (>= 5.2))
-  (dune (>= 3.20))
-  (crdt (= :version))
-  (eio (>= 1.0))
-  (alcotest :with-test)
-  (eio_main :with-test))
- (tags
-  (crdt eio async io)))
+

lib/model.ml

···
                 else c)
               chunks
           in
-          (* Rebuild the RGA - not ideal but works *)
+          (* NOTE: Rebuilding RGA - in-place update would be more efficient *)
           let _ = updated in
-          (* TODO: proper in-place update *)
           ()
       | _ -> ())
   | Op.Op_del { del_obj; del_what } -> (

lib/rga.ml

···
 (** Compare two timestamps for RGA ordering. Higher timestamp wins (inserted
     later in logical time). Tie-break by session ID (higher wins).
 
-    TODO: This needs to match json-joy's algorithm exactly. Currently the
-    tie-breaking for concurrent inserts may differ. *)
+    NOTE: This may not match json-joy's exact ordering for concurrent inserts.
+    See issue crdt-4pq for json-joy compatibility work. *)
 let compare_for_rga (a : Clock.timestamp) (b : Clock.timestamp) =
   (* First compare by time (descending - higher time first) *)
   let time_cmp = compare b.time a.time in

lib_eio/dune

···
-(library
- (name crdt_eio)
- (public_name crdt-eio)
- (libraries crdt eio))

lib_eio/io_eio.ml

···
-(** Eio-based effect handler for async IO.
-
-    This module provides an effect handler that uses Eio for high-performance
-    concurrent IO. It integrates with the Eio scheduler for proper fiber support.
-
-    Usage:
-    {[
-      Eio_main.run @@ fun env ->
-      let net = Eio.Stdenv.net env in
-      Eio.Switch.run @@ fun sw ->
-      let sock = Eio.Net.connect ~sw net (`Tcp (addr, port)) in
-      Io_eio.run_two_way sock (fun () ->
-        let data = Crdt.Io_intf.read_string 100 in
-        (* ... process data ... *)
-      )
-    ]}
-
-    @see Crdt.Io_intf for the effect definitions *)
-
-(** {1 Low-Level IO Operations} *)
-
-(** Read exactly n bytes from a source. Raises End_of_file if EOF is reached
-    before all bytes are read. *)
-let read_exact (source : _ Eio.Flow.source) n =
-  let buf = Cstruct.create n in
-  let rec loop pos =
-    if pos >= n then ()
-    else
-      let sub = Cstruct.sub buf pos (n - pos) in
-      let r = Eio.Flow.single_read source sub in
-      if r = 0 then raise End_of_file else loop (pos + r)
-  in
-  loop 0;
-  Cstruct.to_bytes buf
-
-(** Write all bytes to a sink. *)
-let write_all (sink : _ Eio.Flow.sink) buf =
-  let cs = Cstruct.of_bytes buf in
-  Eio.Flow.write sink [ cs ]
-
-(** Read a single byte *)
-let read_one_byte source =
-  let buf = Cstruct.create 1 in
-  let r = Eio.Flow.single_read source buf in
-  if r = 0 then raise End_of_file else Cstruct.get_uint8 buf 0
-
-(** Write a single byte *)
-let write_one_byte sink b =
-  let buf = Cstruct.create 1 in
-  Cstruct.set_uint8 buf 0 b;
-  Eio.Flow.write sink [ buf ]
-
-(** Read a 4-byte big-endian integer *)
-let read_int32_be source =
-  let buf = read_exact source 4 in
-  let b0 = Char.code (Bytes.get buf 0) in
-  let b1 = Char.code (Bytes.get buf 1) in
-  let b2 = Char.code (Bytes.get buf 2) in
-  let b3 = Char.code (Bytes.get buf 3) in
-  (b0 lsl 24) lor (b1 lsl 16) lor (b2 lsl 8) lor b3
-
-(** Write a 4-byte big-endian integer *)
-let write_int32_be sink n =
-  let buf = Bytes.create 4 in
-  Bytes.set buf 0 (Char.chr ((n lsr 24) land 0xff));
-  Bytes.set buf 1 (Char.chr ((n lsr 16) land 0xff));
-  Bytes.set buf 2 (Char.chr ((n lsr 8) land 0xff));
-  Bytes.set buf 3 (Char.chr (n land 0xff));
-  write_all sink buf
-
-(** {1 Effect Handlers} *)
-
-(** Run a function with Eio IO using a bidirectional flow (e.g., TCP socket).
-
-    This handler intercepts IO effects and translates them to Eio operations. *)
-let run_two_way (flow : _ Eio.Flow.two_way) f =
-  let bytes_read = ref 0 in
-  let bytes_written = ref 0 in
-  Effect.Deep.match_with f ()
-    {
-      retc = (fun x -> x);
-      exnc = raise;
-      effc =
-        (fun (type a) (eff : a Effect.t) ->
-          match eff with
-          | Crdt.Io_intf.Read_bytes n ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let result = read_exact flow n in
-                  bytes_read := !bytes_read + n;
-                  Effect.Deep.continue k result)
-          | Crdt.Io_intf.Write_bytes data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_all flow data;
-                  bytes_written := !bytes_written + Bytes.length data;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_byte ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let b = read_one_byte flow in
-                  bytes_read := !bytes_read + 1;
-                  Effect.Deep.continue k b)
-          | Crdt.Io_intf.Write_byte b ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_one_byte flow b;
-                  bytes_written := !bytes_written + 1;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Yield ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  Eio.Fiber.yield ();
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_frame ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len = read_int32_be flow in
-                  let data = read_exact flow len in
-                  bytes_read := !bytes_read + 4 + len;
-                  Effect.Deep.continue k data)
-          | Crdt.Io_intf.Write_frame data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len = Bytes.length data in
-                  write_int32_be flow len;
-                  write_all flow data;
-                  bytes_written := !bytes_written + 4 + len;
-                  Effect.Deep.continue k ())
-          | _ -> None);
-    }
-
-(** Run a function with Eio IO using separate source and sink flows.
-
-    Useful when you have separate read and write channels. *)
-let run_split ~(source : _ Eio.Flow.source) ~(sink : _ Eio.Flow.sink) f =
-  Effect.Deep.match_with f ()
-    {
-      retc = (fun x -> x);
-      exnc = raise;
-      effc =
-        (fun (type a) (eff : a Effect.t) ->
-          match eff with
-          | Crdt.Io_intf.Read_bytes n ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let result = read_exact source n in
-                  Effect.Deep.continue k result)
-          | Crdt.Io_intf.Write_bytes data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_all sink data;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_byte ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let b = read_one_byte source in
-                  Effect.Deep.continue k b)
-          | Crdt.Io_intf.Write_byte b ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_one_byte sink b;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Yield ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  Eio.Fiber.yield ();
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_frame ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len = read_int32_be source in
-                  let data = read_exact source len in
-                  Effect.Deep.continue k data)
-          | Crdt.Io_intf.Write_frame data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len = Bytes.length data in
-                  write_int32_be sink len;
-                  write_all sink data;
-                  Effect.Deep.continue k ())
-          | _ -> None);
-    }
-
-(** {1 Network Operations} *)
-
-(** Connect to a TCP server and run a function with the connection.
-
-    @param sw Eio switch for resource management
-    @param net Eio network capability
-    @param host Hostname or IP address
-    @param port Port number
-    @param f Function to run with the connection *)
-let connect ~sw ~net ~host ~port f =
-  let addr =
-    match Eio.Net.getaddrinfo_stream net host ~service:(string_of_int port) with
-    | [] -> failwith ("Could not resolve: " ^ host)
-    | addr :: _ -> addr
-  in
-  let flow = Eio.Net.connect ~sw net addr in
-  run_two_way flow f
-
-(** Listen on a TCP port and run a handler for each connection.
-
-    @param sw Eio switch for resource management
-    @param net Eio network capability
-    @param port Port number to listen on
-    @param handler Function to handle each connection *)
-let serve ~sw ~net ~port ~handler =
-  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, port) in
-  let sock = Eio.Net.listen ~sw net ~backlog:128 ~reuse_addr:true addr in
-  let rec accept_loop () =
-    Eio.Net.accept_fork sock ~sw
-      ~on_error:(fun exn ->
-        Eio.traceln "Handler error: %s" (Printexc.to_string exn))
-      (fun flow _addr -> run_two_way flow handler);
-    accept_loop ()
-  in
-  accept_loop ()
-
-(** Serve connections concurrently using Eio fibers with backpressure.
-
-    @param sw Eio switch for resource management
-    @param net Eio network capability
-    @param port Port number to listen on
-    @param max_fibers Maximum concurrent fibers (default 100)
-    @param handler Function to handle each connection *)
-let serve_concurrent ~sw ~net ~port ?(max_fibers = 100) ~handler =
-  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, port) in
-  let sock = Eio.Net.listen ~sw net ~backlog:128 ~reuse_addr:true addr in
-  let sem = Eio.Semaphore.make max_fibers in
-  let rec accept_loop () =
-    Eio.Semaphore.acquire sem;
-    Eio.Net.accept_fork sock ~sw
-      ~on_error:(fun exn ->
-        Eio.Semaphore.release sem;
-        Eio.traceln "Handler error: %s" (Printexc.to_string exn))
-      (fun flow _addr ->
-        Fun.protect
-          (fun () -> run_two_way flow handler)
-          ~finally:(fun () -> Eio.Semaphore.release sem));
-    accept_loop ()
-  in
-  accept_loop ()
-
-(** {1 Buffered IO} *)
-
-(** Run with buffered reading for improved performance on many small reads. *)
-let run_buffered (flow : _ Eio.Flow.two_way) f =
-  let reader = Eio.Buf_read.of_flow flow ~max_size:(64 * 1024) in
-  let bytes_written = ref 0 in
-  Effect.Deep.match_with f ()
-    {
-      retc = (fun x -> x);
-      exnc = raise;
-      effc =
-        (fun (type a) (eff : a Effect.t) ->
-          match eff with
-          | Crdt.Io_intf.Read_bytes n ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let cs = Eio.Buf_read.take n reader in
-                  Effect.Deep.continue k (Bytes.of_string cs))
-          | Crdt.Io_intf.Write_bytes data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_all flow data;
-                  bytes_written := !bytes_written + Bytes.length data;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_byte ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let c = Eio.Buf_read.any_char reader in
-                  Effect.Deep.continue k (Char.code c))
-          | Crdt.Io_intf.Write_byte b ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  write_one_byte flow b;
-                  bytes_written := !bytes_written + 1;
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Yield ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  Eio.Fiber.yield ();
-                  Effect.Deep.continue k ())
-          | Crdt.Io_intf.Read_frame ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len_bytes = Eio.Buf_read.take 4 reader in
-                  let b0 = Char.code len_bytes.[0] in
-                  let b1 = Char.code len_bytes.[1] in
-                  let b2 = Char.code len_bytes.[2] in
-                  let b3 = Char.code len_bytes.[3] in
-                  let len = (b0 lsl 24) lor (b1 lsl 16) lor (b2 lsl 8) lor b3 in
-                  let data = Eio.Buf_read.take len reader in
-                  Effect.Deep.continue k (Bytes.of_string data))
-          | Crdt.Io_intf.Write_frame data ->
-              Some
-                (fun (k : (a, _) Effect.Deep.continuation) ->
-                  let len = Bytes.length data in
-                  write_int32_be flow len;
-                  write_all flow data;
-                  bytes_written := !bytes_written + 4 + len;
-                  Effect.Deep.continue k ())
-          | _ -> None);
-    }
-
-(** {1 Utility Functions} *)
-
-(** Run two fibers concurrently: one for reading, one for writing. Useful for
-    duplex protocols where reads and writes happen independently. *)
-let run_duplex ~flow ~reader ~writer =
-  Eio.Fiber.both
-    (fun () -> run_two_way flow reader)
-    (fun () -> run_two_way flow writer)