feat(presence): board-level awareness via Yjs (#43)

[Musiker15]

Summary

Adds a Yjs-Awareness presence layer on top of the existing E2EE WebSocket relay so users on the same board can see each other (closes #43, except live cursors — see scope note).

• Avatar stack (max 5 + "+N") top-right of the board header — who else is on this board right now
• Per-card viewer dots in the kanban view when another user has a card drawer open
• Deterministic colour per userId (HSL hash) — stable across reloads, same on every peer

Zero-knowledge posture

• Awareness payload is {userId, color, viewing?} only — no email, no card title, no description bytes
• Updates are XChaCha20-Poly1305-sealed under the BoardKey (AAD board:<id>:awareness) before they hit the relay; the server sees opaque base64
• color is a deterministic HSL hash of userId so peers can derive it themselves; we send it anyway to save a round-trip per user observed
• Yjs Awareness auto-expires stale states after ~30s. We refresh every 10s so it never trips for a live peer; on destroy we explicitly broadcast a null state so peers see us leave immediately

Transport

src/server/ws/index.ts gains a second room kind:

Room	Mechanism	Late-joiner sync	Use
card:<id>	Y.Doc	request-state from one peer (Yjs merges)	card description CRDT
board:<id>	Y.Awareness	request-state from all peers (per-clientID, no merge)	presence

Workspace-member authorization for board rooms (authorizeBoardJoin). Card-room semantics are unchanged.

Files

File	Why
src/lib/realtime/awareness.ts	BoardPresenceProvider — mirrors CardWsProvider's lifecycle but encodes Yjs awareness updates instead of Y.Doc updates
src/lib/realtime/user-color.ts	Pure HSL hash, no client-only deps, unit-testable
src/hooks/use-board-presence.ts	React hook → stable peer list + setViewing callback
src/server/ws/index.ts	New parseBoardId + authorizeBoardJoin; branch in handleJoin for the all-peers seed
src/app/(app)/workspaces/[wsId]/boards/[boardId]/board-client.tsx	Mounts hook, mirrors openCardId into awareness, builds viewersByCard, renders <PresenceStack> in header
src/app/(app)/workspaces/[wsId]/boards/[boardId]/kanban-view.tsx	Takes viewersByCard, renders viewer dot stack next to the Open button
tests/unit/user-color.test.ts	6 cases — determinism, HSL shape, negative-mod normalisation, empty-input

Test plan

• pnpm typecheck clean
• pnpm lint clean
• pnpm test --run — 113 tests pass (107 prior + 6 new)
• pnpm build — production build succeeds
• Manual: two browser sessions on the same board → both see each other in the avatar stack
• Manual: one closes the tab → disappears from the stack within ~30s (or immediately if clean disconnect)
• Manual: user A opens a card in the drawer → user B sees the coloured dots on that card in the kanban view
• Manual: reload — same colour for the same user

Scope note: live cursors

The other half of issue #43 (live cursors inside the description editor) is deliberately out of scope. The description is currently a plain <textarea> synced via Y.Text observation, not a CRDT-backed editor like TipTap or CodeMirror. Cursor rendering needs an editor that exposes cursor positions as observable state — that's a separate change (likely a new ADR + an editor swap).

🤖 Generated with Claude Code