# collabd - editor-agnostic collaborative editing daemon

daemon + thin adapters architecture. daemon handles yjs crdt, adapters just
hook buffer events and apply remote changes.

## status

working:
- daemon with room-based sessions
- multi-peer sync (tested with 2+ clients)
- vim9 adapter with live buffer sync
- proper crdt diffing (not delete-all-insert-all)
- integration tests for concurrent edits

not yet:
- cursor/selection sync (awareness protocol stubbed but unused)
- other editor adapters (helix, kakoune, zed)
- persistence (rooms are ephemeral)
- reconnection handling

## stack

- bun runtime
- yjs for crdt
- websocket transport
- vim9script adapter (with bun bridge since vim cant do websocket)

## running

```bash
just dev          # daemon on :4040
bun test          # unit tests
just check        # biome lint
```

## vim adapter usage

requires Vim 9.0+ (uses vim9script)

```vim
:source adapters/vim/collab.vim
:CollabJoin roomname
:CollabLeave
:CollabStatus
```

the vim plugin spawns adapters/vim/bridge.ts which handles yjs and speaks
json lines to vim via channels.

## protocol

daemon speaks json over websocket at /ws

client -> server:
  { type: "join", room: "name" }
  { type: "leave" }
  { type: "update", data: [...] }  // yjs update bytes

server -> client:
  { type: "sync", data: [...] }    // full yjs state on join
  { type: "update", data: [...] }  // remote changes
  { type: "peers", count: N }

## key files

- src/index.ts - websocket server, room routing
- src/session.ts - yjs doc per room, peer management
- src/protocol.ts - message types
- adapters/vim/bridge.ts - bun process vim spawns
- adapters/vim/collab.vim - vim9script plugin

## adding new editor adapters

each adapter needs:
1. hook buffer change events
2. send changes to daemon as yjs updates (or use a bridge like vim does)
3. receive remote updates and apply to buffer
4. optionally show peer cursors

see NOTES.txt for cell-grid vs text-crdt mode discussion.
see docs/ for full research and architecture breakdown.