ChatApp/docs/superpowers/specs/2026-05-16-fifteen-features-design.md

Fifteen-Features Initiative — Design

Date: 2026-05-16 Scope: Desktop only (Electron). Mobile is out of scope. Status: Approved by user (sections 1–6).

Problem

The desktop app has reached a stable point (encryption rolled out, Settings refactored). The user identified fifteen feature gaps to close as one coordinated initiative — quality fixes, messaging power, security UI, creative tools, and shared activities. Releasing each piecemeal would mean nine bumps and nine test cycles; instead this initiative ships as one 0.19.0 after a single end-to-end smoke pass.

Goals

• Close all fifteen features without a release until the user signs off.
• Fix the global-shortcut capture bug that currently breaks every keystroke after a hotkey is set.
• No surprise releases — every commit is git commit only, no pnpm release. Version stays on 0.18.8 throughout, bumps to 0.19.0 once.
• Each phase ends with a clean typecheck + green shared tests.

Non-Goals

• Mobile / React Native port of any of these features.
• Twitch in Watch-Together (YouTube only for the MVP).
• Chess or other mini-games beyond Tic-Tac-Toe + Vier-Gewinnt.
• Operational Transform / CRDT for the Whiteboard (snapshot model only).
• Live video preview or speaking indicators in the existing CallPreviewPanel.
• Hot-patch releases between phases.

Phasing

Phase	Theme	Features	Rough Effort
1	Quality & Fixes	Hotkey-Bug Fix, Tray-Badge Audit, Empty-States, Friend-Nicknames, Memory-Wipe	3–4 days
2	Messaging	Pinned Messages, Mentions-Notifications, GIF-Picker, View-Once Media	~1 week
3	Security & Devices	Session/Device List + Revoke	2–3 days
4	Creative Tools	Image-Annotation, Soundboard Cloud-Sync, Whiteboard (Snapshot-Sync)	~1.5 weeks
5	Activities	Watch-Together (YouTube), Mini-Games (Tic-Tac-Toe + 4-in-a-Row)	~1.5 weeks

Phases run sequentially. Within a phase, features are independent and can be implemented in any order.

Architecture (per feature)

Phase 1 — Quality & Fixes

Hotkey-Bug Fix. The current code (apps/desktop/src/lib/globalShortcut.ts) registers every hotkey through Electron's globalShortcut API, which captures system-wide. Setting "M" as Mute means "M" can't be typed anywhere on the OS while the app is running. Fix: split into two registration modes.

• Window-scoped (default): DOM keydown listener on window, only fires while the app has focus. Used for mute, deafen, hangup, screen-share, video toggle.
• Global (opt-in): Keep globalShortcut.register() for PTT and any hotkey the user explicitly toggles "Global" on.

UI change: every hotkey row in Settings → Voice → Hotkeys gets a 🌐 Global-toggle next to the key-capture button. Default off.

Tray-Badge Audit. Tray code already exists (electron/modules/tray.ts, lib/trayBadge.ts, called from ConversationsContext). Verify the count is actually pushed and the badge renders on Windows. Likely a wiring or icon-loading bug; spec-time fix scope unknown until investigated.

Empty-States. Four locations: empty chat list, empty friends list, empty conversation (just-created with no messages), empty search results. Each gets an illustration (SVG, light/dark variant), a heading, a description, and a primary action button (e.g., "Friend einladen", "Erste Nachricht schreiben"). Reuses existing icon palette.

Friend-Nicknames. Local-only override stored in localStorage keyed by userId. Surfaces wherever a profile name is shown: chat header, message bubble sender, friends list, mention autocomplete, call participant tile. UI: right-click friend in friends list → "Spitzname setzen" → input modal. Empty = use real display name.

Memory-Wipe.

• Always on sign-out: clear Stronghold (chatapp.userpriv.*), IndexedDB (soundboard, message-cache), SQLite cache, conv-key in-memory cache, localStorage except theme + locale + installId.
• Configurable on app-close (Settings → Security → "Cache beim Schließen leeren"): hooks before-quit in main process → IPC to renderer → wipe → quit. Next start requires PIN.

Phase 2 — Messaging

Pinned Messages.

• DB: pinned_messages (conversation_id uuid, message_id uuid, pinned_by uuid, pinned_at timestamptz, PK(conversation_id, message_id)). CHECK via trigger: max 5 pins per conversation.
• RLS: any accepted conv-member can SELECT / INSERT / DELETE.
• UI: right-click message → "Anpinnen" / "Anheftung aufheben". Conv header shows compact "📌 N angepinnt"-pill; click opens a right-side panel with the pinned list; clicking an item scrolls to + flashes the original message.
• Realtime: subscribe pinned_messages:<conv_id> channel for live updates.

Mentions-Notifications.

• sendEncryptedMessage parses plaintext for @<username> tokens before encrypting. Username → user_id lookup against conversation_members joined with profiles. Bulk-insert into new message_mentions (message_id, mentioned_user_id, PK both).
• RLS: mentioned user (and message author) can SELECT.
• Realtime: each client subscribes message_mentions WHERE mentioned_user_id = me. On insert → fire web/desktop notification with [@] <sender>: <decrypted snippet> and the configured mention sound. Bypasses per-conv mute.
• Per-conv setting "Nur bei @Mentions benachrichtigen" (stored alongside the existing mute setting).

GIF-Picker.

• Provider: Tenor v2 (https://tenor.googleapis.com/v2/search, no per-user key — public key passable). Trending + Search + Recent (localStorage of last 24 URLs).
• New component <GifPicker> Popover anchored to the composer's GIF button (next to attachment plus).
• On click: resolved GIF URL is fetched once, uploaded as a normal attachment (mime image/gif) so it lives in the same per-conv attachment storage and is end-to-end-encrypted like any other image. Trade-off: a sent GIF doesn't stay free — it counts as an attachment (~few MB).

View-Once Media.

• Per-attachment flag view_once boolean (new column on message_attachments).
• Sender UI: attachment-picker toggle "👁 Einmal ansehen".
• Recipient UI: bubble shows blurred lock-overlay; tap → fullscreen view; close → bubble flips to "👁 Angesehen, von ". Storage object is deleted server-side via RPC mark_attachment_viewed(p_attachment_id) triggered atomically with the view.
• Auto-purge: Supabase cron deletes view-once attachments untouched after 7 days.
• Sender sees the same "Angesehen"-bubble update (so they know it was opened).

Phase 3 — Security & Devices

Session/Device List + Revoke.

• Uses the existing devices table (telemetry only since the 0.18 encryption refactor).
• New SettingsPage tab "Geräte" between Sicherheit and Konto. Lists name · platform · last_seen per device, "Dieses Gerät"-badge for the local install.
• New column devices.revoked_at timestamptz NULL. Revoke RPC revoke_device(p_device_id uuid): requires device.user_id = auth.uid(), sets revoked_at = now().
• Realtime: every client subscribes devices:user_id=me. On its own revoked_at change → forced signOut() + Memory-Wipe + screen "Du wurdest remote abgemeldet".
• The own device's revoke button is disabled in the list (label: "Nutze Sign-out").

Phase 4 — Creative Tools

Image-Annotation vor Send.

• Attachment-picker for images shows a new "✏ Bearbeiten" button before send.
• Opens <ImageAnnotator> modal: canvas overlay on the image. Tools: pen, arrow, rectangle, circle, text, highlighter. 6 colors, 3 stroke widths. Undo/Redo stack, Reset, Save.
• On Save: canvas.toBlob({type: 'image/png'}) flattens the annotation into the original, replaces the upload-queue entry.
• Custom implementation (~400 LOC). No external dep (tldraw etc. would be overkill).

Soundboard Cloud-Sync.

• New table user_soundboards (id, user_id, name, mime, size, category, hotkey, gain, sort_order, storage_path, created_at, updated_at).
• Storage: bucket soundboards/<user_id>/<sound_id>.bin. Audio payload is encrypted client-side with the user's existing per-user X25519 key (reuses crypto/box). Server only sees ciphertext.
• Local IndexedDB stays the working store; sync is bidirectional.
• Sync engine: on app start + on every local edit (debounced 500ms), diff IndexedDB ↔ remote → upload new/changed, download remote-newer. Realtime subscription on own user_soundboards rows triggers pulls when another device of the user edits.
• Conflict resolution: last-write-wins by updated_at. UI shows "☁ Sync OK / ↑ Hochladen…/ ⚠ Konflikt" badge per sound.

Whiteboard (Snapshot-Sync).

• New tables conversation_whiteboards (id, conversation_id, owner_user_id, created_at) and whiteboard_strokes (id, whiteboard_id, author_user_id, stroke_json jsonb, created_at).
• UI: composer menu → "✏ Whiteboard" → starts a new whiteboard inline in the chat as a bubble (preview + author + "Öffnen"-button). Click → fullscreen modal with canvas.
• Tools: pen, eraser, 6 colors, 3 widths. "Clear all" with confirm dialog.
• Each pen stroke (on pointerup) inserts a row into whiteboard_strokes. Realtime subscription on whiteboard_id renders incoming strokes from other authors. Strokes are JSON: {tool, color, width, points: [[x, y, t], …]}.
• Whiteboard is permanent — bubble in the chat stays, history is preserved, anyone in the conv can reopen it later.

Phase 5 — Activities

Watch-Together (YouTube).

• New table conversation_watch_sessions (id, conversation_id, owner_user_id, video_id text, started_at, ended_at NULL, current_state jsonb). current_state = { playing: bool, position_seconds: number, updated_at_ms: number }.
• Composer → "📺 Watch Together" → modal with URL input → extract video-id (regex on YouTube URL formats) → INSERT row → inline bubble "Anna hat Watch-Together gestartet · [Beitreten]".
• Click Beitreten → fullscreen modal with YouTube IFrame Player API. Controls (play/pause/seek) by owner are broadcast via the session row's current_state update. Other clients reconcile their local player when drift > 2 seconds.
• IFrame API loaded lazily via <script src="https://www.youtube.com/iframe_api">. No build-time dep.
• Auto-end after 12h inactivity (cron). Owner-leave sets ended_at. Non-owner leave keeps session open for re-join.

Mini-Games (Tic-Tac-Toe + Vier-Gewinnt).

• Shared infrastructure for both:
  • New table conversation_games (id, conversation_id, game_type text, state jsonb, players jsonb, current_turn_user_id, winner_user_id NULL, created_at, finished_at NULL).
  • Move RPC game_make_move(p_game_id uuid, p_move jsonb). Server-authoritative state machine validates and applies the move (no client trust). Returns updated state.
  • Realtime subscription on the game row renders state.
• Tic-Tac-Toe: 3×3 board, cell index 0–8, server validates cell-is-empty + correct turn + win line detection (8 winning lines).
• Vier-Gewinnt: 7×6 board, column 0–6 with gravity, server validates column-not-full + correct turn + 4-in-row detection (horizontal/vertical/2 diagonals).
• UI: composer → "🎮 Spiel starten" → submenu (Tic-Tac-Toe / Vier-Gewinnt) → inline invite bubble. Recipient sees "Annehmen"-button. Both then see a ~250×250 board in their bubble. Click a valid cell/column = RPC move. Turn indicator + winner reveal with confetti animation (canvas-confetti).
• Scope: 1v1 only (2-player games). Group games out of scope.

Data Flow Highlights

• No race conditions on mini-game moves: server RPC is atomic via BEGIN; SELECT ... FOR UPDATE; validate; UPDATE; COMMIT;. Last-write loses.
• No race on watch-together state: owner-only writes. Other clients always reconcile from current_state.updated_at_ms.
• No race on whiteboard: strokes are append-only; concurrent strokes from multiple authors interleave naturally.
• Mentions on edit: when a message is edited, the message_mentions rows for that message are recomputed (delete-then-insert in the same RPC).

Error Handling

Case	Behavior
Hotkey conflict (same accelerator double-bound)	Capture-modal shows "Bereits belegt von ". Save disabled until user picks something else.
Tray-badge fails to render on Linux	Silent fallback to text-only tooltip; only Windows has overlay-icon API.
Friend has no nickname	Falls back to display_name.
Memory-wipe IPC times out at quit	Force-exit anyway after 2s timeout; user accepts ephemeral data may remain in OS swap.
Pinned-message limit reached (5)	"Anpinnen" action shows toast "Max 5 angepinnt — heften Sie eine andere ab".
Mention notification fires for a muted device	Always shows (mention overrides mute).
Tenor API down	GIF-Picker shows "GIFs gerade nicht verfügbar".
View-once attachment opened concurrently by two devices of recipient	First view RPC wins; second sees "Bereits angesehen".
Watch-together: video deleted from YouTube	Player surfaces YouTube's own error UI inline.
Mini-game: opponent disconnects mid-game	Game stays open. On reconnect (refresh) the latest state is fetched. After 24h auto-finishes as draw.
Whiteboard stroke insert fails	Stroke stays local; UI shows a "↻ Retry"-badge.

Testing

Per phase: typecheck (pnpm --filter @chat-app/shared typecheck + pnpm --filter @chat-app/desktop typecheck) and shared tests (pnpm --filter @chat-app/shared test) must be green.

Final smoke list (user runs after Phase 5 completes):

1. Hotkey "M" as Mute, default (window-scoped). Type "m" in Composer → letter appears, mute doesn't fire.
2. Hotkey "M" toggled to Global → "m" outside the app triggers mute.
3. Friend sends DM → tray-badge shows 1; click opens app focused.
4. Empty chat list → "Friend einladen"-button visible + functional.
5. Right-click friend → set nickname "Bestie" → chat header shows "Bestie".
6. Sign-out → Storage Inspector shows no Stronghold key, no user-priv, no conv-key cache.
7. Memory-Wipe toggle on → close app, reopen → PIN required.
8. Pin a message → conv header shows "📌 1 angepinnt" → click → side panel lists it.
9. Friend writes "@mich" → notification with [@] prefix + mention sound, even on muted conv.
10. GIF-Picker → search "cat" → click → GIF sent in chat.
11. View-once image sent → recipient opens once → bubble shows "Angesehen", image is gone.
12. Settings → Geräte → revoke another device → that device is force-signed-out.
13. Send image → "Bearbeiten" → draw arrow → send → arrow is in the final image.
14. Add soundboard sound on device A → device B (same user, different install) → sound appears.
15. Open whiteboard → friend draws → strokes appear within 1s.
16. Start Watch-Together with YouTube URL → friend joins → owner pauses → friend's player pauses.
17. Start Tic-Tac-Toe → friend accepts → alternate moves → win animation.
18. Start Vier-Gewinnt → play → 4-in-row detection correct.

Release Policy

• No pnpm release calls during Phases 1–5. Only git commit and git tag (if any) — none of which trigger upload.
• Version stays on 0.18.8 throughout. The migration files and feature commits accumulate on main.
• After the user signs off on the smoke list, a single pnpm release 0.19.0 "<combined notes>" bumps and ships everything.

Out of Scope (future)

• Mobile equivalents of any of these.
• Twitch, Vimeo, or self-hosted video in Watch-Together.
• Chess, Pong, or other mini-games beyond the two.
• Operational-transform / CRDT for Whiteboard (post-MVP if collaboration friction shows).
• Cross-conversation pinning / global pin list.
• Mention auto-suggest improvements (existing MentionAutocomplete is fine).
• Skin-tone reaction picker.
• Voice-message transcription.