Working in Citet

Collaboration

Multiple authors can edit the same document at the same time. Changes from all collaborators appear immediately, and the system handles conflicting edits automatically — you never lose a keystroke.

Real-time editing

When you open a file, the editor joins a live session for that file. Edits from everyone in the session appear in your editor within milliseconds. There is no "save and push" step — the document is always up to date.

The online count in the header shows how many people currently have the project open. Each collaborator's cursor is visible in the editor with a distinct color assigned automatically.

▶How real-time sync works

Each open file is a Yjs CRDT document. When you open a file, the browser connects to the Hocuspocus WebSocket server (services/realtime-hocuspocus), syncs missing operations from S3, and streams operations bidirectionally.

Local edits apply immediately to the in-browser document (no round-trip delay), then stream to the server and to all other connected clients. Because the data structure is a CRDT, concurrent edits from any number of clients produce a deterministic result regardless of network ordering. There are no merge conflicts.

WebSocket tokens use HS256 HMAC-SHA256, shared between the web app (COLLAB_JWT_SECRET) and the Hocuspocus server. Tokens have a short TTL (configurable via COLLAB_TOKEN_TTL_SECONDS, default 300 s). Each token encodes the user ID, project ID, file ID, and the allowed scopes (collab:read / collab:write).

Offline editing

If you lose your internet connection, you can keep writing. Changes are saved locally and sync automatically when the connection returns. Offline sessions can last for hours; the merge when you reconnect is identical to what would have happened if you had been online the whole time.

▶How offline sync works

Yjs document state is persisted to IndexedDB in the browser. While offline, new operations accumulate in the local document. On reconnect, the Hocuspocus provider replays the buffered operations against the server's current state using the CRDT merge algorithm. The result is the same as if both writers had been online simultaneously.

Presence

Connected collaborators appear as avatars in the project header. Each collaborator has a cursor color that is visible in the editor at their current position as you scroll.

Presence is live and ephemeral — it disappears when someone closes the tab or goes offline. VSCode and Neovim users show up in the same presence list as browser users.

Project roles

Each project member has one of four roles:

→Owner: full access: project settings, member management, archive, compile, and edit.
→Collaborator: can edit files, compile, and add comments. Cannot change project settings or manage members.
→Reviewer: can read and add comments, without editing or compiling.
→Viewer: read-only access, without editing, compiling, or commenting.

The owner can change any member's role at any time, except their own (to prevent accidental lock-out). Owners cannot demote themselves while they are the only owner.

Inviting members

Open Project settings → Members or use the command palette: Manage members.
Enter the collaborator's email address and select a role.
If email delivery is configured, they receive a project link. Existing verified accounts receive access immediately; other invitations remain pending until sign-in with a verified matching email address.

Pending invitations can be revoked before they are redeemed. Project settings reports email delivery failures; repeat the invitation to retry, or share the project link directly.

Working with VSCode and Neovim users

Collaborators using the VSCode or Neovim integrations are full participants in the same editing session. Their edits appear in the browser and vice versa, and they show up in the presence list. See Editor integrations for setup instructions.