@tuturuuu/whiteboard holds the Excalidraw-based whiteboard editor so any app
can render it. Workspace Whiteboards in apps/web is the first consumer; Meet
can reuse it without copying code. The package is framework independent: it
imports no Next.js, React Router or Cloudflare runtime code and reads no request
globals. Hosts inject identity, storage, transport and notifications.
Entry points
WhiteboardEditor loads Excalidraw and its stylesheet with a dynamic import
after mount, so importing the package costs nothing until a board renders. It
renders nothing on the server.
Adapters
The host passes these toWhiteboardEditor; all are optional.
WhiteboardPersistence:save(snapshot)stores the snapshot and returns the new revision;load()is optional and is never called by the editor. The host reads the stored snapshot with its own data layer (Workspace Whiteboards uses TanStack Query, so retries, dedupe and refetch on focus, reconnect and live-connection resume stay in the app) and passes{snapshot, revision}to the editor asstoredSnapshot. The editor applies it only when the revision is new and no local edit is unsaved. It debounces saves and saves on Cmd/Ctrl+S.WhiteboardAssets:upload(file)returns the file id the scene stores;resolveUrl(fileId)returns a fetchable URL ornull. Without it the editor offers no image upload.WhiteboardTransport:connect(handlers)returns a disconnect function;sendElementChanges,sendCursorandsendSelectionpublish to peers. Errors reported throughonStatuscarry the channel (elementsorcursors); only element failures reach the host’sonNotify. A transport serves one editor at a time: connecting while another consumer is attached throws, and reconnecting right after a disconnect reuses the open channels and replays the current status. On teardown the realtime transport waits for its departure messages to settle before closing the channels. The collaborationuserobject must be referentially stable, because a new identity reconnects the transport.
apps/web/src/lib/whiteboards/workspace-adapters.ts
(HTTP persistence and the workspaces storage bucket) and
apps/web/src/hooks/useWhiteboardCollaboration.ts (identity, presence roster and
the realtime transport on the channel whiteboard-<wsId>-<boardId>).
Element sync rules
Merging is deterministic so peers converge regardless of arrival order:- The element with the higher
versionwins. - On equal versions the lower
versionNoncewins. - On a full tie the local element stays.
Tests
Package tests cover the sync engine, merge rules, collaborator building, the realtime transport, the collaboration hook and the editor.expectPersistenceContract,
expectAssetsContract and expectTransportContract in @tuturuuu/whiteboard/testing
are the adapter contract: run them against any new adapter. Run the suite with
ttr resources run -- bun --cwd packages/whiteboard test.