Whiteboard Concepts

Rooms, scenes, appliances, members, camera viewport, operation log, undo/redo and replay semantics.

Version v1.0.0 · Updated 2026-10-28 · revision 1

The whiteboard domain model is small, but every invariant affects the client experience. This page defines the vocabulary reused by the REST and SDK pages.

Room#

A room is the smallest isolation unit of whiteboard content. Every room has a globally unique uuid, the owning project's appUUID, the owning account's teamUUID, and:

• phase: active (read/write), banned (writes and token minting are rejected), closed (permanently read-only).
• limit: maximum number of members holding the writer / admin role at the same time; 0 means unlimited.
• version: room version incremented by every mutation; clients use it to detect that they are behind.
• currentScenePath: the current scene path, /init by default.

A room token is bound to one room; project credentials (Basic) authorise every room of that project.

Scene#

A scene is one whiteboard page with a path such as /deck/page1: /deck is the directory and page1 is the page name. Rules:

• Paths start with / and must not contain // or ...
• Page names are unique within a directory, contain no /, and are 1..64 characters long.
• A page may carry a background image (ppt: src, width, height).
• Switching a scene only updates currentScenePath; it never changes content.

Appliance and stroke#

The appliance enum contains pencil, pencilEraser, eraser, rectangle, ellipse, shape, selector, hand, clicker and laserPointer.

A stroke carries the appliance, colour (#rrggbb), width (1..64), point list (up to 4096 points), author memberId and sequence seq. Erasing never deletes the record: it sets erased to true so replay can rebuild what was on screen at the time.

Member#

Clients register a member when joining a room (the memberId is supplied by the client; a room token authorises the scene rather than a fixed identity). The member record stores the role, current appliance, colour, width and the undo/redo step counts.

Camera / viewport#

The viewport is the camera's visible area in world coordinates: x, y, width, height, scale. The viewport belongs to the room, not to a member, so late joiners and replay start from the same place.

Operation log and undo/redo#

Every mutation appends an operation with a monotonic seq, the type, member, scene, room version and payload. Undo/redo are isolated per member:

• Undo: find that member's most recent visible, non-erased stroke in the current scene and mark it undone.
• Redo: only when the member has appended no newer stroke afterwards, restore the most recent undone stroke.
• Records are never physically deleted, so replay and audit can see the complete history.

Replay#

The replay endpoint orders the operation log by time and returns an offset (milliseconds relative to the first retained operation) together with the operation. A player uses that to play, pause, seek and end; the snapshot endpoint returns the same authoritative state for offline rendering.

Token roles#

Project credentials are equivalent to admin and must stay on the server.