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.
97 lines
2.9 KiB
Markdown
97 lines
2.9 KiB
Markdown
# Electron desktop shell — handoff
|
|
|
|
## Summary
|
|
|
|
The desktop app wraps the Cinny/Paarrot web UI in Electron: custom title bar, system tray, deep links (`paarrot://`), auto-updates, plugin filesystem access, screen capture for calls, and the local HTTP API server.
|
|
|
|
## User-facing behavior
|
|
|
|
- Frameless/custom **title bar** with window controls (Windows/Linux)
|
|
- Minimize to **tray**; close may minimize instead of quit (platform config)
|
|
- `paarrot://` URL protocol for room links
|
|
- Auto-update checks (electron-updater)
|
|
- Plugins read/write under `%APPDATA%\paarrot\`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
electron/main.js (main process)
|
|
→ BrowserWindow → Vite dev server or built cinny dist
|
|
→ IPC: plugins, screen capture, clipboard, updates
|
|
→ PaarrotAPIServer
|
|
→ Tray + protocol handler paarrot://
|
|
preload / contextBridge → window.electron in renderer
|
|
```
|
|
|
|
## Key files
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `electron/main.js` | Main process entry |
|
|
| `electron/api-server.js` | Local HTTP API |
|
|
| `electron/preload.js` (if exists) | IPC bridge |
|
|
| `electron-builder.json5` | Packaging config |
|
|
| `package.json` (root) | `npm run dev`, build scripts |
|
|
| `dev-app-update.yml` | Update channel config |
|
|
| `cinny/src/app/components/title-bar/TitleBar.tsx` | Custom title bar UI |
|
|
| `build-resources/` | Linux after-install, icons |
|
|
|
|
## Data model
|
|
|
|
| Store | Tool | Contents |
|
|
|-------|------|----------|
|
|
| `electron-store` | main.js | Window bounds, user prefs |
|
|
| UserData | Electron | plugins, caches |
|
|
|
|
Protocol: `PROTOCOL_SCHEME = 'paarrot'` in main.js
|
|
|
|
## Dependencies
|
|
|
|
- `electron`, `electron-updater`, `electron-store`
|
|
- `electron-builder` for CI releases
|
|
- Vite dev server port **38347**; static server **44548** in dev
|
|
|
|
## Integration points
|
|
|
|
- **local-api**: started with main window
|
|
- **Plugins**: filesystem paths under `paarrot` app name
|
|
- **Voice calls**: `desktopCapturer` for screen share
|
|
- **Deep links**: pending deep link queue until client ready
|
|
|
|
## Testing
|
|
|
|
### Manual
|
|
|
|
1. `npm run dev` — window loads, title bar draggable.
|
|
2. Register `paarrot://` link; opens correct room.
|
|
3. Tray icon present; restore from tray.
|
|
4. Build installer; auto-update check (staging).
|
|
5. Install plugin to AppData path; loader finds it.
|
|
|
|
### Automated
|
|
|
|
- CI: `.gitea/workflows/build.yml`
|
|
|
|
## Known issues & gotchas
|
|
|
|
- `isDev` detection: `NODE_ENV` or `!app.isPackaged`
|
|
- Protocol registration differs Windows vs Linux (`after-install.sh`)
|
|
- Single instance lock for deep links — see `pendingDeepLink` in main.js
|
|
- Title bar hit-testing CSS sensitive on Windows 11
|
|
|
|
## Future work
|
|
|
|
- macOS menu bar parity
|
|
- Code signing documentation for Windows
|
|
- Consolidate magic ports into shared config
|
|
|
|
## Related docs
|
|
|
|
- [local-api HANDOFF](../local-api/HANDOFF.md)
|
|
- Root [README.md](../../../../README.md) — build instructions
|
|
|
|
## Add your extra things here
|
|
|
|
- Dev URLs: `VITE_DEV_SERVER = http://localhost:38347`, `PORT = 44548`
|
|
- App userData folder name: `paarrot` (matches plugin paths in README)
|