ChatApp/docs/superpowers/plans/2026-05-16-phase6-performance.md

# Phase 6 — Performance Pack

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax. This plan is grouped into 3 risk tiers — Group A is parallel-safe quick wins, Group B is medium-scope, Group C is audits.

**Goal:** A focused performance pass after the fifteen-features initiative shipped. Faster startup, smoother long chats, smaller bundle, less main-thread blocking on PIN-unlock, no UX regressions.

**Rollback anchor:** tag `pre-phase6-perf` → `888ed1b` (already pushed to origin).

**Strategy:** ship Group A first (5 tiny safe wins ≈ 5h), pause + smoke-test, then B (medium ≈ 2-3 days), then C (audits ≈ 1 day). No release between groups; one combined release at the very end.

---

## Group A — Safe quick wins (~5h, low risk)

### T1: Lazy-load four fat modals

**What:** Convert eager imports of `WhiteboardModal`, `WatchTogetherModal`, `ImageAnnotator`, `GameModal` to `React.lazy(() => import(...))` inside `ConversationPage.tsx`. Wrap each conditional render in `<Suspense fallback={null}>`.

**Why:** These modals total ~200-300 KB (canvas-confetti dep, IFrame player loader, ImageAnnotator's full op-stack, etc.) and render in <1 % of sessions. Initial bundle drops by that amount → faster cold load.

**Files:** `apps/desktop/src/pages/ConversationPage.tsx` only.

**Risk:** trivial. `Suspense` with `fallback={null}` means a few ms blank flicker the first time each modal opens (chunk download). Acceptable.

**Effort:** ~30 min.

---

### T2: `prefers-reduced-motion` global rule

**What:**
- Global CSS rule in `apps/desktop/src/index.css` (or wherever global styles live): `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition: none !important; animation: none !important; } }`.
- Gate the confetti burst in `GameModal.tsx` behind `window.matchMedia('(prefers-reduced-motion: reduce)').matches`.

**Why:** Accessibility + CPU savings for users who set the OS preference. Confetti is the most visible offender.

**Risk:** very low. Tailwind already respects motion-reduce variants in some classes; this is the global default.

**Effort:** ~30 min.

---

### T3: Memoize `MessageBubble` + audit callback stability

**What:**
- Wrap `MessageBubble` export in `React.memo` with shallow equality (default).
- Audit the message-list render site (ConversationPage or a MessagesList component) — every callback prop passed into the row (`onReply`, `onPin`, `onDelete`, …) must be `useCallback`-stable with no per-render closures. Replace anonymous `() => doX(message.id)` patterns with stable handlers that receive the id at call time.

**Why:** Typing in the composer currently re-runs the entire `messages.map(...)` and re-renders every bubble. With memoization + stable callbacks, only the new bubble appears; existing rows stay mounted. Big win on long chats.

**Risk:** medium-low. Possible bugs if a callback captures stale state (e.g. closure over `pinnedSet` that doesn't update). Mitigation: pass volatile state as props on the bubble and let `React.memo` handle the diff.

**Effort:** ~2h.

---

### T4: Memoize icon components (pragmatic "sprite-sheet" alternative)

**What:** Original idea was a real SVG sprite-sheet (single `<svg>` with `<symbol>` defs + `<use href="#name">`). Pragmatic alternative: wrap every icon component in `React.memo`. They're pure functions of `className`/`...props` so memoization is free, and 90 % of the perf win (avoiding React reconciliation on identical icon trees) comes from this without the sprite refactor risk.

**Files:** `apps/desktop/src/components/icons.tsx` (or `icons/` folder — whichever the codebase uses).

**Why:** Real sprite-sheet is invasive (refactor 60+ icon usages, change className/fill inheritance). Memoizing achieves the bulk of the win at <30 min effort. Real sprite-sheet stays available as a follow-up if bundle-analyzer (T11) shows icons are a top-3 bundle hog.

**Risk:** none — `React.memo` is purely a perf hint.

**Effort:** ~30 min.

---

### T5: Pre-warm Supabase + avatar loading hints

**What:**
- In `AuthContext.tsx`, fire one trivial query early (e.g. `supabase.from('profiles').select('id').limit(1)`) so the connection is warm by the time the user does anything.
- Audit `<img>` tags for avatars: add `loading="lazy"` to off-screen ones (chat list rows below the fold, deep history) and keep `loading="eager"` only for above-the-fold (current conv header, top of chat list).

**Why:** First real query after login currently pays cold-connection latency (~100-200 ms). Pre-warm hides it. Lazy avatars stop the browser from hammering Supabase Storage on initial render.

**Risk:** none.

**Effort:** ~1h.

---

### Group A final gate

- [ ] `pnpm --filter @chat-app/shared typecheck && pnpm --filter @chat-app/desktop typecheck`
- [ ] `pnpm --filter @chat-app/shared test -- --run` (still 71/71)
- [ ] User smoke-test: cold-start the app, send a few messages, type in composer, open one of the 4 modals — verify nothing broke + the visible improvements (faster initial render, smoother typing in long chats).
- [ ] Tag `phase6a-done` for incremental rollback granularity if Group B introduces issues.

---

## Group B — Medium scope (~2-3 days, moderate risk)

### T6: Web-Worker for Argon2 + crypto_box_open (PIN-unlock path)

**What:**
- Create `apps/desktop/src/lib/workers/crypto.worker.ts` that imports libsodium-wrappers and exposes a postMessage RPC: `{ op: 'unsealUserKey', sealedKey, pin, salt, kdfParams }` → `{ privateKey: Uint8Array }` (transferred).
- Build with Vite's worker syntax: `new Worker(new URL('./workers/crypto.worker.ts', import.meta.url), { type: 'module' })`.
- Refactor `apps/desktop/src/lib/userIdentity.ts`'s `unlockUserKey` (and any other hot Argon2 callers) to call the worker instead of the inline crypto backend.

**Why:** PIN-unlock currently runs Argon2id (~1-2 sec on mid hardware) on the main thread → UI freeze during login. Worker offloads it, login screen stays responsive.

**Risk:** medium. libsodium-wrappers needs to be initialized in both contexts. structured-clone transfers `Uint8Array` cleanly. The risk is that libsodium-wrappers might ship a bigger worker bundle than expected (we accept the trade-off because the main bundle gets smaller too).

**Effort:** ~1 day. Includes typing the postMessage RPC + ensuring the existing PIN-unlock flow keeps its error semantics (wrong PIN, etc.).

---

### T7: WebP thumbnails for image attachments

**What:**
- When sending an image attachment: in addition to encrypting+uploading the full image (`<convId>/<attachmentId>.bin`), generate a 320×320 max-dim WebP thumb via `<canvas>.toBlob({ type: 'image/webp', quality: 0.7 })`, encrypt with the SAME per-attachment key, upload to `<convId>/<attachmentId>-thumb.bin`.
- `MessageBubble` image render: try downloading the thumb first; fall back to full image on 404 (graceful for pre-Phase-6 attachments).
- Click-to-expand: fetch the full image.

**Why:** A 5 MB image in the chat scroll loads 5 MB even off-screen. Thumb is ~10-30 KB. Scroll is silky, bandwidth drops 99 %.

**Files:** `packages/shared/src/chat/attachments.ts` (extend `encryptAndUploadAttachment` to optionally generate+upload thumb), `apps/desktop/src/components/MessageBubble.tsx` (try-thumb-first logic), maybe `Lightbox.tsx` (full image on click).

**Schema:** none — naming-convention based, 404-fallback preserves backward compat.

**Risk:** low-medium. Edge cases: very small images (thumb is bigger than full → skip thumb gen), animated GIFs (don't generate static-frame thumb, just use full).

**Effort:** ~½ day.

---

### T8: Virtual-scroll for message list

**What:**
- `pnpm --filter @chat-app/desktop add react-virtuoso`
- Replace the message-list `.map(...)` in (likely) `ConversationPage.tsx` / `MessagesList.tsx` with `<Virtuoso>`.
- Configure: `data={messages}`, `itemContent={(_, msg) => <MessageBubble ... />}`, `followOutput="smooth"` for auto-scroll on new messages, `initialTopMostItemIndex={messages.length - 1}` to start at bottom.
- If date-day headers exist: switch to `<GroupedVirtuoso>` with `groupCounts` + `groupContent`.

**Why:** Long conversations (1000+ messages) currently render all rows → scroll jank, layout thrashing. Virtuoso renders only visible rows + a small overscan buffer.

**Risk:** medium-high. Things that can go wrong:
- Scroll-anchor preservation when Pinned-Messages panel opens.
- Auto-scroll-to-bottom on send.
- Smooth-scroll-to-message when clicking a pin or a reply.
- Image-load reflow (Virtuoso handles this but needs proper height detection).

Mitigation: thorough manual smoke-test before commit. Keep the old render behind a feature flag for one release if jitters appear.

**Effort:** ~½ day to 1 day depending on edge cases.

---

### T9: PIN-Idle-Auto-Lock

**What:**
- Settings → Sicherheit: new toggle "Auto-Lock nach Inaktivität" + dropdown (5 / 15 / 30 / 60 Minuten). Default OFF.
- localStorage key `chatapp.autoLockMinutes` (or similar) — added to `PRESERVE_LOCAL_STORAGE` so memory-wipe doesn't disable the setting silently (same pattern as wipe-on-close toggle).
- In `AuthContext` (or a new top-level hook): listen on `keydown` / `mousedown` / `pointermove`, reset a timer on each event. When the timer fires: `wipeLocalState(uid)` + navigate to `/device` (the PIN-unlock screen).

**Why:** Spec mentioned this as polish + a Security win — laptop left unattended, auto-locks after X min, attacker can't read messages without PIN.

**Risk:** low. The wipe-on-close infrastructure (P1.T12-T13) already handles all the local-state clearing — same call site.

**Effort:** ~½ day.

---

### T10: i18next tree-shake audit

**What:**
- `pnpm --filter @chat-app/desktop add -D i18next-parser`
- Configure it to scan `apps/desktop/src/**/*.{ts,tsx}` for `t('app:...')` calls + extract used keys.
- Diff against `apps/desktop/locales/de/app.json` (or wherever the resource files live). List dead keys.
- Prune them. Verify nothing visible regresses.

**Why:** Resource files accumulate keys from removed/redesigned features. Smaller resource bundle = faster app start (in-memory JSON parse).

**Risk:** low — `t()` always falls back to `defaultValue` if a key is missing, so even an accidental over-prune doesn't crash the UI; it just shows the German default.

**Effort:** ~2h (mostly looking at the diff + judgment calls).

---

### Group B final gate

- [ ] Both typechecks green
- [ ] All shared tests green
- [ ] User smoke-test: cold start (Argon2 worker), open a long chat (virtual scroll), send an image (thumb generation), idle 5+min (auto-lock if enabled), check console for noise.
- [ ] Tag `phase6b-done`.

---

## Group C — Audits + judgment calls (~1 day)

### T11: Bundle-analyzer audit + targeted dep swaps

**What:**
- `pnpm dlx vite-bundle-visualizer` against the desktop build → outputs HTML report.
- Review the treemap. Common offenders to check:
  - Full lodash vs lodash-es (or no lodash at all if only a few utils)
  - Moment.js vs date-fns / native `Intl.DateTimeFormat`
  - Multiple realtime/socket clients
  - Icon libs pulling all icons
  - Dev-only deps accidentally in prod bundle
- Apply targeted swaps (max ~3-5) based on the worst findings.

**Why:** Shrinks bundle further beyond T1's lazy-load. Each ~50 KB shaved is a real cold-start win.

**Files:** `apps/desktop/package.json`, the consumer files that import from swapped deps.

**Risk:** variable per swap. A Moment-to-date-fns swap touches many call sites. Cap at the 3 biggest offenders to keep risk bounded.

**Effort:** ~2h audit + variable fixes (estimate 2-3h additional).

---

### T12: Optimistic-UI audit + targeted gap fills

**What:**
- Audit each user-write action across the app:
  - `send` (message) → likely already optimistic; verify
  - `editEncryptedMessage` → likely already optimistic
  - Pin / unpin
  - Add / remove reaction (doesn't exist yet — skip)
  - Vote on poll
  - Revoke device
  - Toggle mentions-only
  - Toggle mute
- For each action that currently waits for the server roundtrip before updating local state: add optimistic-update with rollback on error.

**Why:** Perceived latency drops to ~0 ms for most clicks. Server roundtrip happens silently.

**Risk:** medium. Each optimistic-update is its own potential rollback bug. Mitigation: only touch actions where rollback is straightforward (e.g. a toggle's previous state is trivially recoverable). Skip if rollback is hairy.

**Effort:** ~1 day total (each action is ~30-60 min including verification).

---

### Group C final gate

- [ ] Both typechecks green, all shared tests green
- [ ] Bundle size measured before/after (note in report)
- [ ] User smoke-test of any actions that gained optimistic UI

---

## Deferred / skipped (with reasoning)

### Realtime-Channel-Pooling

**Skipped for now.** The current UI keeps only one conversation actively open at a time. Concurrent channels at steady state are typically 5-8 (auth-self, conversations-list, current conv messages, current conv typing, mentions, maybe whiteboard / game / watch). Pooling into a single multiplexed channel would require a manager singleton + per-call-site refactor (~15-20 sites), with a meaningful risk of subtle realtime bugs during the transition.

**Reconsider when:** sustained active channel count exceeds 15, or Supabase invoices a noticeable channel-quota line item. Then a focused 1-day refactor with thorough realtime smoke testing makes sense.

---

## Release strategy

- No `pnpm release` between Group A/B/C — single combined release after Group C (or earlier if Group B+C get deferred).
- Suggested version when releasing: `0.20.0` (combines unreleased Phase 5 + 5C + Phase 6).
- Rollback at any commit boundary via `git reset --hard pre-phase6-perf` (Group A) or `git reset --hard phase6a-done` / `phase6b-done` (per-group).