Max Litruv Boonzaayer
e058165830
Bump Vite 8, matrix-js-sdk, and related deps; fix immer/vanilla-extract imports for new majors. Replace blocking sync error dialog with background recovery on wake/offline, and disable Vite auto-open in dev. Add feature handoff documentation index.
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# Background notifications — handoff
|
|
|
|
## Summary
|
|
|
|
Paarrot keeps users notified of Matrix activity when the app is in the background: desktop tray/favicon badges, system notifications (Electron/Tauri/Android), and Android **UnifiedPush** for reliable mobile push without Google FCM dependency.
|
|
|
|
## User-facing behavior
|
|
|
|
- Unread counts update favicon (Paarrot / unread / highlight variants)
|
|
- System notifications for mentions/DMs per notification settings
|
|
- Android: requires UnifiedPush distributor (e.g. ntfy); user prompted if missing
|
|
- Foreground/background state affects sync strategy
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ClientNonUIFeatures.tsx
|
|
→ FaviconUpdater (roomToUnread atom)
|
|
→ notification listeners (tauri.ts sendNotification)
|
|
→ initPaarrotAPI + background sync lifecycle
|
|
backgroundSync.ts
|
|
→ UnifiedPush registration, pusher setup
|
|
→ setAppForegroundState / startBackgroundSync / stopBackgroundSync
|
|
tauri.ts / electron main
|
|
→ OS notification APIs, Android small icon ic_stat_paarrot
|
|
```
|
|
|
|
## Key files
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Favicon, notifications, API init, background sync hooks |
|
|
| `cinny/src/app/utils/backgroundSync.ts` | Pushers, UnifiedPush, foreground state |
|
|
| `cinny/src/app/utils/tauri.ts` | Tauri/Capacitor notification helpers |
|
|
| `cinny/src/app/features/settings/notifications/SystemNotification.tsx` | Permission UX |
|
|
| `electron/main.js` | Tray, notification IPC (if applicable) |
|
|
| `src-tauri/src/main.rs` | Tauri Android shell |
|
|
|
|
## Data model
|
|
|
|
| Key | Storage | Purpose |
|
|
|-----|---------|---------|
|
|
| `paarrot.unifiedpush.*` | localStorage prefix | UP endpoint state |
|
|
| `com.paarrot.app.android` | Pusher app id base | Android pushers |
|
|
| Matrix pusher | Homeserver | HTTP push gateway |
|
|
|
|
## Dependencies
|
|
|
|
- UnifiedPush distributor app on Android
|
|
- Notification permission (browser/OS)
|
|
- Homeserver pusher support
|
|
- `matrix-js-sdk` sync
|
|
|
|
## Integration points
|
|
|
|
- **Settings → Notifications**: rules + system permission
|
|
- **DirectTab / sidebar**: custom Paarrot SVG favicon states
|
|
- **Deep links**: notification tap → `setupNotificationTapListener`
|
|
|
|
## Testing
|
|
|
|
### Manual
|
|
|
|
1. Desktop: background app; send mention; verify system notification.
|
|
2. Verify favicon switches unread/highlight with counts.
|
|
3. Android: install ntfy; verify push when app killed.
|
|
4. Toggle notification settings; verify respect mute rules.
|
|
|
|
### Automated
|
|
|
|
- None
|
|
|
|
## Known issues & gotchas
|
|
|
|
- UnifiedPush user education string in `backgroundSync.ts` if no distributor
|
|
- Multiple runtimes: `isTauri`, `isElectron`, `isCapacitorNative` branch logic
|
|
- Pusher registration races on fast login/logout
|
|
- Android small icon: `ic_stat_paarrot` must exist in Android resources
|
|
|
|
## Future work
|
|
|
|
- iOS push strategy
|
|
- Notification action buttons (reply, mark read)
|
|
- Per-room notification channels on Android
|
|
|
|
## Related docs
|
|
|
|
- Matrix push gateway docs (upstream)
|
|
|
|
## Add your extra things here
|
|
|
|
- Constants: `PUSHER_APP_ID_BASE`, `PUSHER_STORAGE_PREFIX` in `backgroundSync.ts`
|
|
- Logo assets: `paarrot.svg`, `paarrot-unread.svg`, `paarrot-highlight.svg` in `public/res/svg/`
|