Presence

Presence is temporary information about the users in a document. It can include names, colors, cursor positions, and selections. Strata does not save this information. It disappears when the connection closes.

Data

Presence data is defined in strata_protocol/presence. An application sends name, color, and cursor in the payload field of presence_set. The cursor value can contain a cursor position, a selection, or other temporary application data:

{
  "name": "Alice",
  "color": "#ff0000",
  "cursor": { "x": 10, "y": 20 }
}

The server adds session_id when it sends a presence_state or presence_diff frame. The server does not inspect cursor.

How presence changes

1. The application joins a document.
2. The application sends presence_set with its current metadata.
3. The server sends presence_state to the new connection. This message contains all current presence information.
4. The server sends presence_diff after a change. The diff field contains joins and leaves.
5. Applications use the latest information to show other users' cursors and selections.

Send presence_set when the local cursor or selection changes. The server sends the new presence value to the other applications.

If the payload does not match the presence schema, the server still records a placeholder. The placeholder has an empty name, an empty color, and a null cursor. Validate presence data before you send it.

After a reconnect

Presence is removed when a connection closes. After you reconnect, join the document and send presence_set again. See Reconnect.