Epic: Real-Time Collaboration & Cross-Device Sync (CRDT + Firebase)

## Summary

Add **live multi-user editing** and **offline-first cloud sync** to StickyNotes across Web + Mobile.
Use a CRDT (e.g., **Y.js**) for conflict-free merges, **Firebase Auth** for identity, **Firestore** for metadata/permissions, and **IndexedDB + Service Worker** for offline queueing and background sync.

## Why

* Current notes are single-user/local-first; collaboration is a top requested “Future Enhancement”.
* CRDTs remove merge conflicts across micro-frontends (React/Vue) and the Cordova app.
* Proper rules + roles enable safe sharing (owner/editor/viewer) without data leaks.

## Scope

### Web (React/Vue micro-frontends)

* Replace note editor content with a Y.js document (Markdown friendly).
* Presence: show active collaborators, cursors, and “typing” badges.
* Offline support: cache CRDT updates in IndexedDB; auto-reconcile on reconnect.
* UI for **Share** (email or link), role selector (owner/editor/viewer), revoke access.

### Backend/Middleware

* Lightweight **y-websocket** (or y-webrtc) provider; deploy behind existing middleware.
* Firestore collections: `users`, `notes`, `noteShares`, `noteEvents` (audit trail).
* Server clock & TTL to expire stale share links.

### Mobile (Cordova/React Native)

* Same Y.js doc; use y-indexeddb (or SQLite) adapter for offline.
* Background sync on resume / connectivity change.

### Security

* Firebase Auth for identity; Firestore **rules** to enforce owner/editor/viewer.
* Signed share links (one-time tokens), optional password on link.
* PII minimization; export data stays local unless user confirms.

## Acceptance Criteria

* ✅ Two users can edit the **same note** concurrently; changes converge with no data loss.
* ✅ Works offline: edits made while disconnected sync on reconnect.
* ✅ Presence indicators visible within < 2s.
* ✅ Share via link/email with **owner/editor/viewer** roles; revocation applies within 1 min.
* ✅ Firestore rules prevent unauthorized read/write (tested).
* ✅ Import/Export still works (CRDT doc exports to JSON/Markdown).
* ✅ Mobile build syncs the same note with web.
* ✅ Basic audit trail per note (created/edited/shared/revoked).

## Technical Notes

* **CRDT:** Y.js + y-websocket (fallback to y-webrtc if server not available).
* **Storage:**

* Firestore: note metadata (title, tags, dueDate, color, pin, shares), not the raw CRDT state.
* CRDT updates live via WS; snapshot periodically to Firestore (or Cloud Storage) for cold start.
* IndexedDB for offline queue + local snapshot.
* **Rules (sketch):**

```js
match /notes/{noteId} {
allow read: if isOwner() || isEditor() || isViewer();
allow write: if isOwner() || isEditor();
}
match /noteShares/{shareId} {
allow read, write: if isOwnerOf(resource.data.noteId);
}
```
* **Presence:** small doc in Firestore/RTDB per note: `{ uid, displayName, color, lastSeenAt }`.
* **Service Worker:** background sync tag `stickynotes-sync`; retry with exponential backoff.

## Migration Plan

1. Add metadata collections & rules → 2) Deploy y-websocket service → 3) Gate new editor behind feature flag → 4) Migrate existing notes to CRDT snapshots on first open → 5) Enable sharing UI → 6) Roll out to mobile.

## Tasks

* [ ] Set up Firestore collections & security rules + tests.
* [ ] Add y-websocket server (Dockerfile + k8s/compose manifest).
* [ ] Integrate Y.js editor in web (React/Vue micro-frontends).
* [ ] IndexedDB adapter + Service Worker background sync.
* [ ] Presence UI (avatars, cursors, typing).
* [ ] Share modal (invite by email/link, roles, revoke).
* [ ] Periodic CRDT snapshotting to Firestore/Storage.
* [ ] Mobile integration (Cordova): Y.js + offline store; connectivity listeners.
* [ ] Audit trail (`noteEvents`) + minimal viewer.
* [ ] Docs: `docs/collab-sync.md` (architecture, env vars, runbook).
* [ ] QA: offline/airplane mode, merge storms, link revoke, e2e latency.