# Lotus Chat — Work Backlog

**Repo:** `lotus` branch at `https://code.lotusguild.org/LotusGuild/cinny`  
**Deploy:** push to `lotus` → CI → auto-deploy to `chat.lotusguild.org` (~11 min)

---

## ⚠️ TDS DESIGN LAW — READ BEFORE TOUCHING ANY UI

> **ALL Lotus Terminal Design System (TDS) styling — colors, animations, glows, borders, fonts, spacing — MUST come exclusively from `/root/code/web_template/base.css` CSS variables.**
> Do NOT hardcode hex values. Do NOT invent new variable names. Do NOT deviate from the design tokens defined in that file.
> The canonical variable reference: `--lt-accent-orange`, `--lt-accent-cyan`, `--lt-accent-green`, `--lt-glow-orange`, `--lt-box-glow-*`, `--lt-border-color`, etc.
> Reference implementation for code patterns: `/root/code/tinker_tickets/` (markdown.js, base.js, ticket.css)
> This rule applies to EVERY task in this file without exception.

---

## 🧩 NATIVE-CINNY LAW — EVERY FEATURE MUST FEEL LIKE STOCK CINNY

> **Every feature we implement must feel native to the upstream Cinny app — indistinguishable from something the Cinny team would have shipped.** Reference: <https://github.com/cinnyapp/cinny>.
>
> Concretely this means:
>
> - **Use the `folds` design system, not bespoke UI.** Build with folds primitives (`Button`, `Chip`, `IconButton`, `Menu`, `MenuItem`, `Dialog`, `Modal`, `Input`, `Switch`, `Badge`, `SettingTile`, `SequenceCard`, etc.) and folds tokens (`color.*`, `config.space.*`, `config.radii.*`, `config.borderWidth.*`). No hardcoded hex/`rgba()` for UI chrome, no invented/undefined CSS variables.
> - **Match Cinny's existing patterns.** Before adding UI, find the closest existing Cinny component/flow and mirror it (e.g. a new dropdown uses `Button`+`PopOut`+`Menu`+`MenuItem` like the rest; a new modal has a `Header` with a close `IconButton`; a new setting is a `SettingTile` inside a `SequenceCard`). Consistency with stock Cinny beats personal style.
> - **Lotus-custom additions should be unobtrusive** and fit Cinny's visual language, spacing, and interaction conventions — a stranger using Cinny should not be able to tell which features are ours.
>
> **The ONE exception:** explicit **Lotus Terminal Design System (TDS)** features, which intentionally have their own distinct look and follow the **TDS Design Law** above. TDS styling is opt-in (only active in Lotus Terminal mode); everything else must look and feel like native Cinny.

---

Completed features are documented in [LOTUS_FEATURES.md](./LOTUS_FEATURES.md).

---

## 🔎 Audit findings — Wave 1 (2026-07)

Bug-hunt of the Tier-1 high-risk areas (notifications/unread/receipts, threads, calls host-side, Element Call fork) by 4 parallel deep-audit agents. `[T#]`=threads, `[N#]`=notifications, `[C#]`=calls host, `[EC#]`=fork.

**✅ FIXED (2026-07):** all 🔴 (T1, N1, N2); web 🟠 (T2, T4, N3, N4); calls-host 🟠 (C-H1, C-H2, C-H3) + 🟡 (C-M3, C-M4, C-M5, C-M6, C-L4, C-L6) — reviewed (the C-H2 AFK rewrite + C-H1 rejoin guard verified). EC-fork 🟡 (EC1–EC6) fixed on `element-call:lotus` (**needs a republish**). Web + calls gate-green (677 tests + `threadReceipt.test.ts` locking the T1 regression). **Still open (low tail):** C-M1/C-M2 (DOM-hack fragility — retire via the fork), C-L1/L2/L3/L5/L7/L8, and N5, N6, T5, T6, T7.

### 🔴 High — data-integrity / broken core UX

| ID     | Defect                                                                                                                                                                                                                                                                                                                                                                                      | File:line                                                                                            | Repro                                                                                                                                                                                                                    | Fix sketch                                                                                                                                             |
| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **T1** | **`markThreadAsRead` corrupts the room's MAIN read marker** — sends `sendReadReceipt(latestEvent, Read)` with `unthreaded` omitted (→false); `latestEvent` is the thread **root** when replies aren't loaded, so the SDK writes a `thread_id:"main"` receipt at the old root → `getEventReadUpTo` jumps back → room re-lights. **Same class as the P6 regression, second path.** CONFIRMED. | `features/room/thread/useThread.ts:172` (fired on mount by `ThreadPanel.tsx:145-167`)                | Open a thread whose root is an older message (or any thread before replies load) → previously-read main messages resurface as unread; room dot won't clear. **Likely a live cause of the current "unread won't clear."** | Mirror `notifications.ts`: use `thread.lastReply()` and bail if null, or `if (latestEvent.getId() === thread.id) return;` — only receipt a real reply. |
| **N1** | Favicon + tab-title unread count **double-counts space aggregates** — `putUnreadInfo` writes an entry for the leaf room AND every ancestor space; `FaviconUpdater` sums **all** map entries. CONFIRMED.                                                                                                                                                                                     | `pages/client/ClientNonUIFeatures.tsx:97-103` (FaviconUpdater) vs `state/room/roomToUnread.ts:67-74` | A room w/ 3 highlights nested in Space→Subspace → tab title reads `(9)` not `(3)`. Orphan-only users unaffected (why it hid).                                                                                            | Sum only leaf entries (skip aggregates: leaves have `from:null`), or compute from `mx.getRooms()`.                                                     |
| **N2** | **Missed notifications/sounds** — the `deliverNotification` dedupe cache (`unreadCacheRef`) is written only on incoming messages, never cleared on read. `unreadInfo.total` resets to 0 on read but the cache keeps the stale value. CONFIRMED.                                                                                                                                             | `pages/client/ClientNonUIFeatures.tsx:364-408`                                                       | DM cadence "msg→read→msg→read…": after the first, every later message's notification+sound is suppressed (`unreadEqual(1,1)`).                                                                                           | Clear/refresh `unreadCacheRef` from a `RoomEvent.Receipt` listener, or dedupe on last-notified `eventId` (as the thread path already does).            |

### 🟠 Medium — visible wrong behavior

| ID         | Defect                                                                                                                                                                                                                                                                                                     | File:line                                                              | Notes                                                                                                      |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| **T4**     | Explicit per-thread **"All" override is defeated** by the room-count gate: `deliverNotification` returns early on `unreadInfo.total===0` and dedupes on `unreadEqual`, but a non-mention thread reply in a Mentions-only room doesn't bump the count → "notify all replies" silently drops. CONFIRMED.     | `ClientNonUIFeatures.tsx:370-380` vs `:489-502`                        | Don't gate the thread path on room `total`; dedupe on thread event id (`lastNotifiedThreadRef`) only.      |
| **N3/T3+** | **Muted-thread-only room gets a phantom unread dot** — `getUnreadInfos` pushes a `{0,0}` entry (roomHaveNotification true from the muted thread's server count), which still lights the nav row + pollutes "unread only" filters. CONFIRMED.                                                               | `utils/room.ts:261-278`                                                | Don't push when `getUnreadInfo`→`{0,0}` and `roomHaveUnread` is false.                                     |
| **N4/T3**  | Reading a thread **DELETEs the whole room badge** — `handleReceipt` unconditionally `DELETE`s on any of my receipts; if the thread was already read (no `UnreadNotifications` PUT follows) the room's legit main-timeline badge vanishes until the next event. Also a PUT/DELETE ordering race. PLAUSIBLE. | `state/room/roomToUnread.ts:243-263`                                   | For threaded receipts, recompute via `getUnreadInfo` PUT instead of blanket DELETE.                        |
| **T2**     | Thread **"Jump to Latest" doesn't reset the virtual window** — only bumps scroll count; when scrolled up with live replies arriving, newest replies aren't rendered so the chip lands on a mid/old event. CONFIRMED.                                                                                       | `features/room/thread/ThreadTimeline.tsx:462-468`                      | Re-anchor with `setTimeline(getInitialThreadTimeline(...))` like the main timeline's `handleJumpToLatest`. |
| **C-H1**   | `forceState()` **re-runs on every `JoinCall`** (no once-guard) → on an EC reconnect it resets live mic/video/deafen back to the join-time snapshot, clobbering the user's mid-call toggles. PLAUSIBLE (structurally confirmed).                                                                            | `plugins/call/CallEmbed.ts:362-364,502-509` + `CallControl.ts:141-156` | Guard `onCallJoined` to `forceState` only on first join, or re-apply _current_ state on rejoin.            |
| **C-H2**   | AFK auto-mute monitors the **browser default mic**, not EC's selected device → measures silence while the user talks on a non-default mic → **auto-mutes an active speaker**; also a 2nd OS mic indicator. PLAUSIBLE.                                                                                      | `hooks/useAfkAutoMute.ts:39-40`                                        | Acquire with EC's selected `deviceId`, or tap EC's existing track.                                         |
| **C-H3**   | Screenshare/spotlight **state observer goes stale** — `bodyMutationObserver` uses `subtree:false`, so when EC re-renders its controls subtree `observeControls()` never re-runs and the reflected screenshare/spotlight boolean freezes. PLAUSIBLE.                                                        | `plugins/call/CallControl.ts:168-200,274-287`                          | Observe the stable controls container with `subtree:true`, or re-query on each mutation.                   |

### 🟡 Low / minor / cosmetic / perf

- **Calls host:** C-M1 deafen DOM-fallback leaks late-added `<audio>` tracks; C-M2 `.click()`-by-testid toggles silently no-op if EC renames; C-M3 `setQuality` not join-gated (pends to 10s timeout) — mirror the deafen gate; C-M4 End button spins forever if EC ACKs hangup but never echoes Close (add fallback dispose timeout); C-M5 PTT while deafened silently un-deafens on key-up; C-M6 `screenshareAudioMuted` never reset when screenshare stops; C-L1 AFK mic not released if EC elides the echo; C-L2 ringtone-preview global cross-cancel; C-L3 first incoming ring after cold load can be silent (ringtones ctx not unlocked); C-L4 deafen M-key bound to window only (not iframe); C-L5 speaker-observer churn on every membership change; C-L6 setState-after-unmount (IncomingCallListener, CallSoundboard 30s timer); C-L7 all-muted DOM-fallback miscount if EC label format differs; C-L8 PiP sw/nw resize anchor jitter at min size.
- **Notifications:** N5 `deleteUnreadInfo` `?? roomId` spreads a string into chars (latent/unreachable; should be `?? []`) — `roomToUnread.ts:85`; N6 per-message read-receipt avatars may not refresh on membership change (`RoomMemberEvent.Membership` on `Room` may not bubble) — `useRoomReadPositions.ts:57-61`.
- **Threads:** T5 `participating` detection is server-bundle-only (`thread.hasCurrentUserParticipated`) → can under-notify a thread you just replied to; T6 room "Mentions & Keywords" not honored for participated/Default thread replies (over-notify, partly masked by T4); T7 account-data thread-mute write is a lost-update read-modify-write race.
- **EC fork (needs a republish):** EC1 `lotusQuality` 500ms re-apply `setTimeout` never cleared → fires on torn-down rooms; EC2/EC3 `lotusQuality`+`lotusAudioInject` subscribe to the remote-gated `livekitRoomItems$` (no-op when alone) — should use `allConnections$` like denoise; EC4 `lotusDecorations` keeps module-scoped per-call state (cosmetic leak into next call — the last deafen-class sibling); EC5 `lotusDecorations` inline `subscribe` re-subscribes every render; EC6 `lotusFocus` clears the pin on a payload missing `userId` (should keep current).

**Verified sound (spot-check list):** `markAsRead` (no root fallback), `useRoomsListener` variable-arity fix, `unreadEqual`, `getUnreadInfo` muted-thread subtraction, own-reply suppression, single-owner timeline rule, `lotusDeafen` (closure-scoped), denoise processor lifecycle, PTT stuck-mic hardening + editable-target guard, PiP position validation, embed single-dispose. (Full per-area "looks-correct" lists in the audit run.)

---

## 🔎 Audit findings — Wave 2 (2026-07)

Tier-2 bug-hunt (desktop/native, crypto/session/infra, messaging data) by 3 parallel agents. `[D#]`=desktop/native, `[F#]`=crypto/session/infra, `[M#]`=messaging.

**✅ FIXED (2026-07):**

- **🔴/security:** F1 (search-cache DECRYPTED plaintext never wiped on server-forced logout → now `deleteSearchCacheDatabase()` on that path); D1 (Linux no-sleep was totally broken — zbus inhibit bound to a dropped connection; now a long-lived connection in managed state); M1/M2 (bookmarks + user-notes account-data **lost-update** data-loss → serialized via `latestRef`+write-queue like `useReminders`).
- **🟠:** M3 (reminder cross-instance race → hoisted the queue to module scope); M4 (image compression flattened transparent PNGs to black + stripped EXIF orientation → skip PNG, `createImageBitmap` orientation, `.jpg` rename); M6 (export "all" had unbounded pagination/OOM → 200-page cap + Cancel button + incremental `oldestTs`); D2 (desktop taskbar/Unity badge double-counted spaces — same as favicon N1 → leaf-only sum); D3 (tray DND desynced from `manualDndAtom` after reload → `get_tray_dnd` re-hydrate); F4 (search-cache delete falsely reported success while `onblocked` → wait for real delete, 3s cap).
- **🟡:** M5 (MediaGallery lightbox opened the wrong item — index drift; shared `getThumbMxc` guard); M8 (audio playback-rate reset on async decrypt → re-apply on loadedmetadata/play); D5 (updater never relaunched → `app.restart()` + terminal UI state).

**⚠️ FLAGGED — product decision (not auto-changed):**

- **F2 — DECIDED (keep ON, 2026-07):** URL previews stay **default ON in encrypted rooms** (`settings.ts encUrlPreview: true`) per user preference — the deliberate Lotus "URL Preview Default in Encrypted Rooms" feature. (Trade-off acknowledged: the homeserver fetches links from E2EE messages; users can turn it off per-room.)

**Won't-fix / by-design:** M7 (scheduledMessages clamps a past target to 1s — intentional + unit-tested; the modal already guards ≥60s).

**Still open (low tail / follow-ups):**

- **D4** cold-start deep link may navigate twice (idempotent; guard the argv path). **D6** WinRT rich-toast AUMID never registered → P5-41 quick-reply / P5-35 click-to-open are inert on Windows (falls back to plain toast) — a wiring task. **D7** Unity badge `application://cinny.desktop` id may not match the installed `.desktop` basename (runtime-verify on the `.deb`/AppImage).
- **F3** session blob unconditionally wins over legacy keys even if legacy is fresher (downgrade-then-upgrade → stale token → forced re-login); **F5** OIDC refresh drops `expiresAt`/id-token claims on persist; **F6** server-forced logout leaves a stale token in the SW + skips issuer revocation (token already revoked server-side — minor).
- **Nit:** ForwardMessageDialog doesn't strip `m.mentions` → forwarding can re-ping.

**Verified sound (spot-checks):** media-auth token only in the `Authorization` header (never a URL); `removeFallbackSession` clears all credential keys; session cross-tab sync; the opt-in search gate; `cryptoCallbacks`; SW precache (no stale SPA shell); Windows `SetThreadExecutionState` main-thread clear; native IPC surface matches end-to-end; GDI/COM/jumplist/thumbbar resource hygiene; `useReminders` serialization template; forward multi-select index alignment; KaTeX (`trust:false`, no XSS); `mathParse`; `searchCache` merge/coverage; ScheduleMessageModal local-tz + ≥60s guard; polls 2–10 bounds; edit-history pagination; `useLocalTime` DST.

---

## 🔎 Audit findings — Wave 3 (2026-07)

Tier-3 bug-hunt (theming/visual, presence/UX/composer, rooms-customization/moderation) by 3 parallel agents. Higher-severity than expected in the non-theming areas. `[P#]`=presence/UX, `[H#]`=rooms/moderation, `[T#]`=theming.

**✅ FIXED (2026-07), reviewed + gate-green (677 tests):** the ACL cluster [H1–H4] (empty-allow block, self-ban warning w/ case-insensitive glob match, glob validation, confirm dialog), [P1] wrong-room menu, [P2] presence override, [H6] insights overflow, [H7/H8] mod-log labels, [P3/P4/P5] mute-restore + status-expiry + timezone-`m.tz`, [P6–P9] favorites/charCount/DM-preview, and theming [T-P1/P2/P4/P5]. **[H5] invite-QR ✅ FIXED (2026-07):** now generated locally via `qrcode.react` (no api.qrserver.com); removed from the prod CSP.

**🔴 High (fixing/fixed this pass):**

- **[H1–H4] Server ACL editor can brick a room's federation in one click** — no guard against saving an **empty allow-list** (denies every server → room partitioned, unrecoverable), no warning on **denying/omitting your own homeserver**, glob validation **rejects valid patterns** (`1.2.3.*`, `*.evil.*`), and a single Save writes `m.room.server_acl` with no confirmation. → adding empty-allow block, self-ban warning (`mx.getDomain()`), glob validation, and a confirm dialog.
- **[P1] Room context menu acts on the WRONG room after a live reorder** — `RoomNavItem` keyed by list `index`, so an open menu rebinds to a different room on activity-sort reorder → Leave/Mute/Favorite hits the wrong room. → key by `roomId`.
- **[P2] Setting a status message force-flips presence to `online`** — overrides Invisible/DND/Idle (an Invisible user is outed as online). → derive presence from the `presenceStatus` setting.
- **[H5] Invite QR leaks room identity to a third party** — the QR is fetched from `api.qrserver.com` (`RoomShareInvite.tsx`). **DEFERRED — needs a bundled QR lib** (none in deps); generate locally instead of a remote call.

**🟠 Medium (fixing/fixed):**

- **[H6] RoomInsights `Math.min(...allTs)`** spread overflowed the call stack on a large timeline → **FIXED** (single-pass min/max). [H7] policy-list mislabels `org.matrix.mjolnir.ban` + empty recommendation badge; [H8] activity-log mislabels knock→join and invite-retraction.
- **[P3] Timed-mute timers never restored on startup** → a mute set before a reload stays stuck forever; re-arm/expire persisted timers on client init. **[P4]** custom-status auto-clear **never fires** (timer lives in the Settings modal) → move to an always-mounted watcher. **[P5]** timezone written to `im.lotus.timezone` but read from the `m.tz` profile field → invisible to other users despite the "visible to others" copy; also PUT `m.tz`.
- **[T-P1] Decoration picker eager-loads ~100 animated PNGs** (jank/CPU) → `loading="lazy"`. **[T-P2]** a redundant always-on animated `<body>` compositor layer when glassmorphism is off → gate on `glassmorphismSidebar`. **[T-P4]** `prefers-reduced-motion` sampled once, never re-subscribed → a `useReducedMotion()` hook.

**🟡 Low (fixing/open):** [P6/P7] favorites collapse chevron doesn't hide + filter ignores favorites; [P8] `charCount` not reset on send; [P9] encrypted DM preview stale until next event (listen for `Decrypted`); [P10] presence badge not seeded when the User appears late; [T-P5] decoration `<img>` stuck hidden on a recycled node; [H10] room-name setter fire-and-forget/silent length reject; theming [T-P3/P6/P7/P8] preview-grid perf + seasonal-swatch viewport-units + mutual-exclusion UX asymmetry (mostly acceptable); `App.tsx` mention-color assumes 6-digit hex.

**Verified sound (spot-checks):** NO theming leaks (all backgrounds/overlays pure-CSS; `lotus-boot`/`LotusDecorationPusher` timers self-clean; NightLight unmounts + `pointerEvents:none`; reduced-motion honored on load); favorites use per-room `m.tag` (**no** account-data race); bookmarks serialization intact; toast queue self-dismiss + dedup; composer-toolbar config; CollapsibleBody ResizeObserver; syntax highlighter renders React children (**no XSS**); Report Room endpoint (MSC4151); knock badge gated on PL; ACL event wire shape.

---

## ✅ Done — Awaiting Verification

Built and gate-green; verify per [LOTUS_TESTING.md](./LOTUS_TESTING.md), then they graduate to LOTUS_FEATURES.md. (Open bugs + the verification backlog now live in this file and LOTUS_TESTING.md.)

| Feature                                                                           | Test guide        |
| :-------------------------------------------------------------------------------- | :---------------- |
| Full-Screen Camera Broadcasts (per-participant focus)                             | A5 / G2           |
| Advanced search filters (sender/date/has-link/has:image·file·video/pinned/recent) | K2 / M1 / M2 / M4 |
| Custom Accent Color Picker (non-TDS themes)                                       | M3                |
| 5 Color Theme Presets (Cyberpunk/Ocean/Blood Red/Matrix/Midnight)                 | M5                |
| Intersection-based lazy media loading                                             | H1                |
| Context-aware thumbnail previews                                                  | H2                |
| Desktop — proactive update notifications (Tauri)                                  | J1                |
| Remind Me Later                                                                   | K1                |
| Mobile Bookmarks access                                                           | E5                |
| In-Call Soundboard (P5-15, uploadable clips → real call inject)                   | D2-7              |
| Call Quality Controls (P5-31, user + room-admin caps)                             | D2-8              |
| Call Permissions (P5-31, hard server-side screenshare/camera policy)              | D2-9              |

---

Legend:

- `[AUDIT REQUIRED]` — at least one assumption needs code/server verification before implementing
- `[SERVER CHECK]` — depends on a Synapse feature or MSC; verify on `matrix.lotusguild.org`
- `[LOW PRIORITY]` — implement after all higher-priority items
- `[EXTREME COMPLEXITY]` — multi-sprint, plan separately before touching
- `[BLOCKED]` — cannot build until a server upgrade, upstream MSC, or dependency resolves
- `[IMPROVE]` — feature exists in upstream Cinny; this task enhances it for Lotus Chat

Status: `[ ]` pending · `[~]` in progress · `[x]` completed

---

## Server Capabilities (as of June 2026)

- **Homeserver:** `matrix.lotusguild.org`
- **Synapse version:** `1.155.0` (2026-06-18) — fully up to date; last version for Debian 12 (LXC 151 already on Debian 13 Trixie)
- **Matrix spec:** up to `v1.12` formally; newer MSC features via `unstable_features`

### Confirmed facts

| Finding                                                                                                                                                  | Impact                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **MSC flags ON:** `msc4140` · `msc3771` · `msc3440.stable` · `msc4133.stable` · `simplified_msc3575` · `msc4222` · `msc3266` · `msc3401_matrix_rtc`      | All safe to use now                                                                                     |
| **MSC flags OFF:** `msc4306` (thread subscriptions) · `msc3882` · `msc3912` · `msc4155`                                                                  | These features are BLOCKED                                                                              |
| **MSC3266** room summary: flag `msc3266_enabled: true` set but `GET /v1/rooms/{id}/summary` still returns 404 (M_UNRECOGNIZED)                           | Room Preview BLOCKED — endpoint not implemented in Synapse 1.155                                        |
| **MSC3892** relation redaction: not in flags                                                                                                             | Reaction Redaction feature BLOCKED                                                                      |
| **MSC4260** report user: `POST /_matrix/client/v3/users/{userId}/report` returns **200** ✅                                                              | **Report User UNBLOCKED** — endpoint live since Synapse 1.133; ready to build                           |
| **MSC4151** report room: HTTP 405 on GET = endpoint exists (POST only)                                                                                   | Report Room live ✅                                                                                     |
| `folds AvatarImage` does NOT accept children                                                                                                             | Add frame/overlay inside `UserAvatar.tsx` itself — optional `frameName` prop                            |
| No in-app toast system exists (was)                                                                                                                      | Built `ToastProvider` + Jotai queue; at `App.tsx:65`                                                    |
| `useUnverifiedDeviceCount()` hook exists                                                                                                                 | `src/app/hooks/useDeviceVerificationStatus.ts:65-106`                                                   |
| Voice player: `AudioContent.tsx:44-223`                                                                                                                  | Playback rate on hidden `<audio>` at line 217                                                           |
| `CallControl.setMicrophone(bool)` at `CallControl.ts:206-212`                                                                                            | For AFK auto-mute                                                                                       |
| `CallControl.toggleSound()` at `CallControl.ts:230-251`                                                                                                  | Push-to-deafen — just wire a hotkey to this                                                             |
| matrix-js-sdk has NO arbitrary profile field methods                                                                                                     | Use `mx.http.authedRequest()` for MSC4133                                                               |
| Sanitizer (`sanitize.ts`) allows table, div, span, a, code, hr                                                                                           | LFG HTML card is safe locally; test on Element/FluffyChat                                               |
| Sanitizer STRIPS `<math>`/MathML tags                                                                                                                    | Math/LaTeX task must also modify sanitizer                                                              |
| Service worker EXISTS at `src/sw.ts`                                                                                                                     | Quick-reply task: add `notificationclick` handler                                                       |
| `knockSupported()` utility exists at `matrix.ts:376-391`                                                                                                 | Knock UX: only need "Request to Join" in `RoomIntro.tsx`                                                |
| `KeywordMessages.tsx` already has custom keyword push rules                                                                                              | Full push rule editor: only non-keyword rule types need new UI                                          |
| `getMatrixToRoom()` in `matrix-to.ts` generates invite URLs                                                                                              | Invite link: just add QR code to room settings                                                          |
| ~~Cindy CANNOT inject audio into EC call stream~~ **UNBLOCKED by EC fork** — `io.lotus.inject_audio` widget action publishes a clip as a real call track | In-call soundboard CAN now mix into the call (no longer local-only); needs cinny UI to drive the action |
| Folds uses vanilla-extract in non-TDS, NOT CSS custom properties                                                                                         | Custom accent color: must create new vanilla-extract theme variant dynamically                          |
| Theme presets need ~50 CSS custom properties each                                                                                                        | Significant design work before coding                                                                   |
| `useCallSpeakers.ts` CSS MutationObserver polling                                                                                                        | Visual speaking indicator: TDS ring animation on top of existing data                                   |
| MSC3489/3672 live location: BOTH false on server                                                                                                         | Live Location BLOCKED                                                                                   |

---

## Key File Reference

| What you need                    | File                                                          | Lines               |
| -------------------------------- | ------------------------------------------------------------- | ------------------- |
| Global keydown hook              | `src/app/hooks/useKeyDown.ts`                                 | whole file          |
| Room navigation                  | `src/app/hooks/useRoomNavigate.ts`                            | 19-72               |
| All room IDs atom                | `src/app/state/room-list/roomList.ts`                         | `allRoomsAtom`      |
| Room unread counts               | `src/app/state/room/roomToUnread.ts`                          | `roomToUnreadAtom`  |
| Overlay portal provider          | `src/app/pages/App.tsx`                                       | 65                  |
| Portal container div             | `index.html`                                                  | 101                 |
| Room settings tabs               | `src/app/features/room-settings/RoomSettings.tsx`             | 27-56               |
| State event read/write pattern   | `src/app/features/common-settings/general/RoomEncryption.tsx` | 42-52               |
| Power level checker              | `src/app/hooks/usePowerLevels.ts`                             | whole file          |
| Slash command registration       | `src/app/hooks/useCommands.ts`                                | 140-537             |
| Chat background picker           | `src/app/features/settings/general/General.tsx`               | 945-981             |
| Chat backgrounds definition      | `src/app/features/lotus/chatBackground.ts`                    | whole file          |
| Matrix.to URL builder            | `src/app/plugins/matrix-to.ts`                                | `getMatrixToRoom()` |
| Media event content types        | `src/app/types/matrix/common.ts`                              | 46-91               |
| Media URL conversion             | `src/app/utils/matrix.ts`                                     | `mxcUrlToHttp()`    |
| Message pagination (search)      | `src/app/features/message-search/useMessageSearch.ts`         | 74-121              |
| Infinite pagination pattern      | `src/app/features/message-search/MessageSearch.tsx`           | 234-365             |
| Poll event format                | `src/app/components/message/content/PollContent.tsx`          | 1-320               |
| Theme class application          | `src/app/hooks/useTheme.ts`                                   | 25-60               |
| Animations file                  | `src/app/styles/Animations.css.ts`                            | whole file          |
| Message status (EventStatus)     | `src/app/features/room/message/Message.tsx`                   | 84-142              |
| Call member change events        | `src/app/hooks/useCall.ts`                                    | 37-52               |
| Mic control in calls             | `src/app/plugins/call/CallControl.ts`                         | 206-212             |
| Device verification hook         | `src/app/hooks/useDeviceVerificationStatus.ts`                | 65-106              |
| Knock room support check         | `src/app/utils/matrix.ts`                                     | 376-391             |
| Room join button location        | `src/app/components/room-intro/RoomIntro.tsx`                 | 25-119              |
| Notification mute via push rules | `src/app/hooks/useRoomsNotificationPreferences.ts`            | 110-150             |
| Message text body CSS            | `src/app/components/message/layout/layout.css.ts`             | 182-205             |

---

## Priority 3 — Higher complexity / lower daily frequency

### [~] P3-4 · Accessibility Improvements (WCAG 2.1 AA) — COMPLIANCE PASS DONE (2026-07), ⚠️ AWAITING LIVE AXE/SR AUDIT

**Shipped (compliance + shortcuts-help tier):** messages `role="article"` + collapsed-message sender/time announced to AT (the biggest gap — collapsed rows had no sender for a screen reader); ~10 unlabeled form inputs + Media Gallery / Search overlays named; emoji/emoticon aria-labels; typing indicator now announced via a `role="status"` live region; editing a message announces "Editing message from X"; focus now returns to the trigger on close of 4 genuine dialogs (RoomIntro/Reactions/RoomViewHeader-topic/Search — inline popouts correctly left); a `?` keyboard-shortcuts help dialog; and a **jsx-a11y lint gate** (curated ARIA-correctness + label rules, enforced in CI) to prevent regressions. Already-good before this pass: skip link + landmarks, timeline `role="log"`/`aria-live`, ~99% icon-button labels, labeled editor.
**DEFERRED (documented):** virtualization keeps scrolled-away history out of the a11y tree (architectural; the live-region announces newly-arriving messages) — not re-architected to avoid perf regression; roving-tabindex + command palette + section-jump shortcuts (user-deferred); the live axe-core / VoiceOver+NVDA audit → LOTUS_TESTING §P.

_Original scope (for reference):_

**What:** Comprehensive audit and fix pass targeting the critical user paths:

- Room list navigation (keyboard-only)
- Reading messages in the timeline (screen reader announces new messages)
- Composing and sending a reply
- Opening and closing modals (focus trap, return focus)
- ARIA labels on all icon-only buttons

**Scope:** Do NOT attempt to make every corner of the app AA-compliant in one pass — focus on the golden path (open app → find room → read → reply → send).  
**[AUDIT REQUIRED]** — Run an automated audit first: `npx axe-core` or browser DevTools accessibility tree. Document every violation before writing a single line of code. Prioritize by severity (critical > serious > moderate).

**Investigation Findings:**

- **Root Cause:** Inconsistent focus management, missing `aria-live` regions for dynamic timeline updates, and sparse global keyboard shortcuts.
- **Approach:** Standardize `focus-trap-react` usage (reference `RoomNavItem.tsx`). Add `aria-live` regions to the timeline. Expand `useKeyDown.ts` for section navigation shortcuts.
- **Complexity:** Medium-High (audit is the main work).

---

### [~] P3-8 · Thread Panel (full side drawer) — IMPLEMENTED (2026-07), ⚠️ AWAITING LIVE QA

Built per the design below (4-agent build + 2-agent review). Gates green (tsc/eslint/build/tests). **Release note: threaded replies no longer render inline in the main timeline — roots show a "N replies" chip that opens the panel.**

**Manual QA checklist (post-deploy):**

1. Reply in Thread (message menu) → panel opens; send text/upload/emoji into it (appears pending → confirmed)
2. Reply to a reply inside the panel → event carries `m.thread` + `m.in_reply_to` with `is_falling_back:false`
3. Main timeline: root + chip only (replies absent); chip count/time updates live; unread badge appears for others' thread replies and clears after viewing the panel
4. Room badge clears via normal markAsRead even with unread threads (unthreaded receipt)
5. Reload: partitioning persists; encrypted-room threads decrypt (back-pagination too)
6. Escape / × closes; mobile = fullscreen panel; switching rooms and back restores the open thread  
   **What:** A right-side drawer for threaded conversations. Currently "Reply in Thread" exists but there is no panel to read or write thread replies.

Features:

- Click "Reply in Thread" → opens thread drawer on the right
- Thread root event shown at the top of the panel
- Full message rendering for all in-thread replies (reuse timeline components)
- Reply input at the bottom (full composer with formatting, emoji, etc.)
- Unread count badge on the thread button in the main timeline
- Keyboard shortcut to close thread panel

**Architecture:**

- New Jotai atom: `activeThreadEventId: string | null`
- New component: `src/app/features/room/thread/ThreadPanel.tsx`
- Rendered alongside `RoomView` as a conditional right panel (mirror the members drawer pattern)
- Filter events in timeline to `m.thread` relation for the active root event ID
- Shares the same `mx` client and room reference as the main timeline

**[AUDIT REQUIRED]** — Deeply audit how `m.thread` relation events are currently stored and retrieved in the matrix-js-sdk. Understand the thread aggregation API: `GET /rooms/{roomId}/relations/{eventId}/m.thread`. Check if `RoomTimeline.tsx` currently filters out thread replies from the main timeline (it should — confirm).

**Investigation Findings:**

- **Root Cause:** Current `m.thread` events are treated as standard `m.room.message` events and rendered in the main timeline.
- **Approach:** Introduce new Jotai atom `activeThreadEventId`. Create `ThreadPanel.tsx`. Update `RoomTimeline.tsx` to filter out thread relations (`m.relates_to`). Implement aggregation fetch using `GET /rooms/{roomId}/relations/{eventId}/m.thread`. Use `thread.timelineSet` directly for the most accurate thread view.
- **Complexity:** High.

---

## Priority 4 — Specialized, high complexity, or low priority

### [x] P4-7 · Virtualized Infinite Scroll for Search Results — ALREADY IMPLEMENTED (found 2026-07)

**What:** Replace the manual "load more" button with an automated, virtualized infinite scroll for search results.  
**Status:** Done in a prior session — `MessageSearch.tsx` already uses `useVirtualizer` (~line 336) over the result groups AND auto-fetches the `nextToken` page when the last virtual item scrolls into view (~line 469) via `useInfiniteQuery`. Nothing left to build.

### [~] P4-8 · Encrypted Message Search Indexing & Caching — IMPLEMENTED (2026-07), opt-in

**Shipped:** `src/app/utils/searchCache.ts` — raw-IndexedDB per-room index (`lotus-search-cache`) of decrypted search rows + coverage markers, merged into local search (in-memory-wins dedupe). **Opt-in, default OFF** (stores plaintext at rest) with a privacy note, Clear button, and logout wipe. Awaiting live QA (LOTUS_TESTING outstanding-verification backlog).

### [~] P4-1 · Thread Notification Mode Per-Thread — IMPLEMENTED (2026-07), ⚠️ AWAITING LIVE QA

**Shipped (Slack-style):** default = **Participating** (notified only for threads you've posted in or where you're @mentioned); per-thread override **All / Mentions-only / Mute** via the bell menu in the thread panel header; modes sync across devices (`io.lotus.thread_notifications` account data, pruned on write). Mute also suppresses the chip badge and subtracts the thread from the room's sidebar badge (client-side). Also fixed the underlying path: thread replies are notified via exactly one handler (room-level `ThreadEvent.NewReply`), with the main-timeline notifier + unread binder thread-guarded, and live badge refresh on `RoomEvent.UnreadNotifications`.

**Manual QA checklist (post-deploy):**

1. Friend replies in a thread YOU posted in → notification + sound; in a thread you never touched → silent (chip badge only)
2. @mention in any thread → notified regardless of participation
3. Set a thread to Mute → no notifications, chip badge gone (bell-mute glyph), room sidebar badge drops by that thread's count
4. Set to All → every reply notifies; Mentions-only → only @mentions
5. Second device shows the same per-thread modes (account-data sync)
6. Room-level Mute still silences everything incl. thread overrides
   **Known caveats:** Mentions-only can under-notify in E2EE rooms (decision runs pre-decryption — same class as the existing notifier); muted-thread badge subtraction is Lotus-only (other clients still count them).

---

### [ ] P4-2 · Thread Subscriptions (MSC4306) [BLOCKED]

**Spec:** MSC4306 (Synapse experimental). Depends on Thread Panel (#P3-8).  
**What:** "Follow thread" button to receive notifications for a thread you haven't posted in. Uses MSC4306 subscription endpoint.  
**[SERVER CHECK]** — `org.matrix.msc4306 = false` on `matrix.lotusguild.org` — BLOCKED until server enables it.  
**Complexity:** Medium (after thread panel exists).

---

### [ ] P4-4 · Math / LaTeX Rendering in Messages (LOW PRIORITY)

**Spec:** CS-API §11.5 (stable) — `formatted_body` can contain LaTeX.  
**What:** Render `$...$` or `$$...$$` LaTeX expressions in message bodies. Use KaTeX (lightweight, ~100KB, renders server-side-compatible CSS). Must gracefully fall back to raw LaTeX text if KaTeX fails.  
**Note:** This is LOW PRIORITY — only useful for academic/technical communities. Implement last.  
**[AUDIT REQUIRED]** — Confirm KaTeX bundle size impact on the Vite bundle. Check if matrix-js-sdk's HTML sanitizer strips LaTeX before it reaches the renderer. The formatted_body sanitization pipeline is the main risk here. (Confirmed: sanitizer STRIPS `<math>` tags — must be patched alongside the renderer.)  
**Complexity:** Low-Medium.

---

### [ ] P4-5 · Live Location Sharing (MSC3489 + MSC3672) (LOW PRIORITY, HIGH COMPLEXITY) [BLOCKED]

**Spec:** MSC3489 + MSC3672. Implemented in Element Web.  
**Note:** Static location sharing is already implemented. This adds live/real-time GPS beacons. Very low priority per user preference.  
**What:** Start sharing live location → creates `m.beacon_info` state event → client posts `m.beacon` events on a timer → other users see your position update live on a map.  
**[SERVER CHECK]** — `org.matrix.msc3489 = false` AND `org.matrix.msc3672 = false` on `matrix.lotusguild.org` — BLOCKED.  
**Complexity:** High. Requires background geolocation API + live map rendering.

---

### [~] P4-6 · OIDC / SSO Next-Gen Auth (MSC3861) — CLIENT-SIDE BUILT, awaiting live verification

**Spec:** MSC3861 / MSC2965, Matrix spec v1.15. OAuth2-native auth via a Matrix Authentication Service (MAS).  
**Scope decision (2026-06):** CLIENT-ONLY. We implemented OIDC login _in the Lotus client_ so it can sign into next-gen homeservers (mozilla.org, eventually matrix.org). We deliberately did **not** convert lotusguild's own Synapse to MAS (no account migration; lotusguild keeps password + legacy Authelia SSO).  
**Built (matrix-js-sdk already ships the OIDC API; this was wiring):**

- Discovery: `cs-api.ts` `getOidcIssuer()` (stable `m.authentication` + msc2965). Flow hint: `useParsedLoginFlows` `getOidcCompatibilityFlag()` (MSC3824).
- Login: `pages/auth/oidc/{oidcConfig,oidcLoginUtil,oidcState}.ts` (dynamic registration + cache, PKCE authorize), `login/OidcLogin.tsx`, issuer-gated `Login.tsx`.
- Callback: `oidc/OidcCallback.tsx` + `App.tsx` short-circuit (non-hash redirect path).
- Session/refresh: `state/sessions.ts` OIDC fields, `client/{oidcTokenRefresher,oidcLogout}.ts`, `initMatrix.ts` wiring.
- Account mgmt: `settings/account/OidcManageAccount.tsx`.
- 13 unit tests (discovery/flow/session/cache/callback parsing). All gates green.
  **Awaiting verification (needs a real MSC3861 server — lotusguild is NOT one):** deploy + log into **mozilla.org** (requires adding mozilla to the deployed `config.json` homeserverList + its domains to the CSP `connect-src`/`img-src` — see below), OR run a local `matrix-authentication-service` + Synapse `msc3861` dev loop.  
  **Mozilla.org test enablement: ALREADY DEPLOYED (verified 2026-07)** — `matrix/cinny/config.json` homeserverList includes `mozilla.org` and the nginx CSP `connect-src` includes the mozilla/modular/vector domains (`matrix/cinny/nginx.conf:42`). **Nothing blocks the test — just pick mozilla.org on the login screen and complete an OIDC login.**

---

## Priority 5 — Gamer / Aesthetic / Customization

### [MOVED] P5-9 · LFG (Looking for Group) Command → LotusBot

**Decision:** Implemented as `!lfg` in LotusBot rather than a client slash command. Bot-side rendering works consistently across all Matrix clients; client-side enhanced cards would only be visible to Lotus Chat users and require sanitizer auditing. The bot can also support richer flows (list active LFGs, DM interested players, auto-expire posts).

---

### [~] P5-15 · In-Call Soundboard — IMPLEMENTED (⚠️ awaiting live verification, D2-7)

**What:** Soundboard button in the call controls bar → popout grid of the user's clips; clicking one plays it **into the call** as a real published track (peers hear it) and locally (presser hears it). Clips are **user-uploadable, just like custom emojis/stickers**.  
**🔱 [EC-FORK] Fork side + cinny side DONE.** The fork ships `io.lotus.inject_audio` (`LotusWidgetActions.InjectAudio`, allow-listed in `widget.ts`), armed via the `lotusAudioInject=1` flag; it publishes a clip as a separate LiveKit track — a **real** in-call soundboard mixed into the call, not local-only. cinny now drives it.  
**Shipped (cinny):**

- Clips stored in `io.lotus.soundboard` account data → **synced across devices like emoji/sticker packs** (`useSoundboard` hook; `AccountDataEvent.LotusSoundboard`).
- Upload audio (≤1 MB, ≤40 clips) → `mx.uploadContent` → mxc; play resolves mxc → authed download → `blob:` object URL (the widget can't fetch authenticated media itself) → `control.injectAudio(url, volume)` + local playback.
- `CallSoundboard.tsx` popout in the call bar (upload / play / delete), gated on the `soundboardEnabled` setting (Settings → General → Calls, + volume slider).  
  **Remaining:** a dedicated Settings management page (optional — upload/delete already live in the popout); a small default clip set; live verification (D2-7). Files: `utils/soundboardClips.ts`, `hooks/useSoundboard.ts`, `features/call/CallSoundboard.tsx`, `plugins/call/CallControl.ts#injectAudio`.  
  **Complexity:** Medium — done.

---

### [~] P5-20 · Quick Reply from Browser Notification

**What:** Inline reply field in browser notification toasts via Notification Actions API. Reply sends as threaded reply to the triggering message.  
**[AUDIT REQUIRED]** (1) Verify browser Notification Actions API support in target browsers. (2) Confirmed: service worker EXISTS at `src/sw.ts` — add `notificationclick` handler there.  
**Complexity:** Medium-High.  
**Partial Fix Applied ⚠️ UNTESTED:** Notifications now (a) show the real message body (`username: message` instead of "New inbox notification from..."), (b) click navigates directly to the room at the specific event (not the inbox), (c) `window.focus()` called on click so the tab comes to front, (d) reminder toasts also link to the specific event. Full inline-reply via Notification Actions API still needs the SW `push`+`notificationclick` pipeline (requires switching from `new Notification()` to `showNotification()` through the SW).

---

### [x] P5-30 · Advanced ML Noise Suppression (Krisp-style)

**What:** High-end background noise cancellation using a pre-trained ML model (RNNoise) running in the browser. Removes dogs, fans, and keyboard clicks from the mic stream.  
**Shipped:** 3-tier setting (Off / Browser-native / ML) in Settings → General → Calls.  
**🔱 [EC-FORK] DONE — moved in-source (2026-06).** ML denoise is now a first-class audio stage **inside** the forked Element Call: a LiveKit `TrackProcessor<Audio>` activated by `lotusDenoiseSource=1` (cinny sets it when ML is selected). The old build-time `getUserMedia`/`index.html` monkeypatch is **removed**. Because EC re-runs the processor on every (re)publish, denoise now **survives reconnects and mic-device switches** — this is the A7 fix (see `LOTUS_TESTING.md` §D2-1). The processor degrades to the raw mic rather than going silent.  
**Key decision:** LiveKit's Krisp filter is LiveKit-Cloud-only (we self-host the SFU); EC's own RNNoise PR #3892 is unmerged. Owning the fork let us implement the in-source stage directly.

**Models — all in-source in the fork:**

- [x] **DeepFilterNet 3** (48 kHz, **ML default**) · **DTLN** (16 kHz) · **RNNoise** (48 kHz) · **Speex** (48 kHz) — all four wired and selectable; dropdown ordered best-quality first. Tier default is **Browser-native**.
- [x] **Quality tuning (2026-07):** dry/wet **attenuation floor** (~-16 dB, RNNoise/Speex only — the "robotic" fix; DTLN/DFN would comb-filter), **gate-after-ML**, **DFN level 80→60**. Floor tunable via `lotusDenoiseFloor`.
- [x] **AEC/AGC (2026-07):** echo-cancellation ON; **AGC OFF for the ML tier** (`autoGainControl=false`, threaded through EC `UrlParams`→`ConnectionFactory`) so browser AGC doesn't fight the model; playback confirmed no AEC-defeat.
- [x] **Reliability (2026-07):** never-silent watchdog, resume-timeout, WASM-cache reject-eviction, activate-off-local-participant, init/build leak fixes.
- [ ] **Open verification:** real-call by-ear **A/B** — model choice, floor value, AGC on/off (RNNoise known-weak historically). `LOTUS_TESTING.md` §D2-1 / J2.
- [ ] **GTCRN (RESEARCHED — DEFERRED):** tiny MIT 16 kHz model that beats RNNoise, but **no drop-in browser package** — needs a ~1-week from-scratch build: `onnxruntime-web` (WASM, 1 thread) in a **Web Worker** (ORT can't run in an AudioWorklet — issue #13072) behind a custom AudioWorklet ring-buffer node presenting as an `AudioNode`; model `gtcrn_simple.onnx` (~300 KB, stateful — thread `conv/tra/inter` caches per frame); we write STFT/iSTFT (n_fft 512/hop 256). Assets ~3–4 MB via the `lotusDenoise()` vite plugin. Registration checklist known (both repos, incl. the 2nd `denoisePipeline.ts` used by the DenoiseTester). **Revisit only if low-power quality is insufficient after validating the current tuning.**
- [ ] **Desktop-only / HW-gated (future):** FRCRN or NVIDIA Maxine (RTX/Tensor only) — impossible in-browser; would run in the Tauri Rust backend + bridge a virtual mic into the webview. Detect capability; web falls back to RNNoise.
- **Excluded:** Krisp (LiveKit Cloud only); FRCRN/Maxine on web (GPU/server-bound).

---

### [~] P5-31 · Granular Voice & Screenshare Quality Controls — IMPLEMENTED (⚠️ awaiting live verification, D2-8)

**What:** Let users (and room admins) adjust audio bitrate and screenshare bitrate/framerate.  
**🔱 [EC-FORK] Fork side + client side DONE.** The fork ships `io.lotus.set_quality` (`LotusWidgetActions.SetQuality`) that applies audio/screenshare encoding params (`RTCRtpSender.setParameters`, all simulcast encodings, re-applied on `TrackUnmuted`/republish) inside EC. cinny now drives it.

**Shipped (cinny):**

1. **User settings** (Settings → General → Calls): Microphone Bitrate, Screenshare Bitrate, Screenshare Framerate (`callAudioBitrate` / `screenshareBitrate` / `screenshareFramerate`).
2. **Room-admin caps**: `io.lotus.room_quality` state event (`StateEvent.LotusRoomQuality`) + `RoomQuality.tsx` in Room Settings → General → Voice (mirrors `RoomVoiceLimit`).
3. **Apply logic**: `useCallQuality` (wired in `CallEmbedProvider`'s `CallUtils`) builds `min(user setting, room cap)` and sends `io.lotus.set_quality` on join / when settings change (`utils/callQuality.ts`, unit-tested).

**Server-side enforcement (DONE — matrix repo):** extended `voice-limit-guard.py` (LXC 151) to also read `io.lotus.room_quality` and hard-enforce a **publish-source policy** for ALL clients.

- **Reality (researched, primary-source, LiveKit 1.9.11):** numeric bitrate/fps caps **cannot** be hard-enforced server-side — LiveKit is a pure SFU (forwards, never transcodes); there is NO bitrate/fps field in the JWT grant, `RoomConfiguration`, server `limit:` config, or any admin RPC, and stock Element Call ignores room metadata / custom claims for publish quality. So numeric caps stay **cooperative** (our fork honors them via `min()` → `set_quality`, already shipped).
- **What IS hard-enforced cross-client:** `VideoGrant.canPublishSources`. The guard holds the LiveKit secret, so when `io.lotus.room_quality` sets `allow_screenshare:false` / `allow_camera:false` it re-signs the issued JWT with a narrowed source list → the SFU refuses those tracks for **every** client (Element, FluffyChat, our fork). Mic always kept. Fail-open; unit-tested (`livekit/test_voice_limit_guard.py`). Admin UI: Room Settings → Voice → **Call Permissions** switches. cinny also hides the blocked buttons.
- **Live (mid-call) enforcement — DONE:** the JWT re-sign covers new joins; for participants **already in the call**, a background reconcile loop in the guard calls LiveKit `UpdateParticipant` every ~3 s to narrow `canPublishSources`, which unpublishes an in-progress screenshare/camera **server-side for all clients** and blocks re-publish (verified LiveKit 1.9.11 auto-unpublishes on permission narrowing). Only removes forbidden sources (never grants), preserves other permission flags, no-ops once compliant. So flipping a room audio-only kills live cameras/screenshares within ~one interval.
- **Not enforceable / deferred:** numeric server enforcement (impossible — see above); screenshare **resolution** control (`set_quality` covers bitrate + framerate; resolution needs a `getDisplayMedia` hook inside the fork).

**Complexity:** DONE — client (cooperative numeric caps) + server (hard publish-source policy). Only the physically-impossible numeric server enforcement is out of scope.

---

### [~] P5-35 · Desktop — Notification Click Opens Room — IMPLEMENTED (Tier B, via the P5-41 WinRT toast: click → open room, reply → send); native CI-compile-pending, runtime-verify on Windows

**What:** Clicking a system tray notification navigates to the relevant room. Quick-reply from the notification toast would send the reply without opening the window.  
**Status:** Deferred (Tier B). Note: the "can't compile-test without a Windows build environment" premise is **outdated** — CI now compiles Windows (Gitea self-hosted `windows` runner + GitHub `windows-latest`), and `windows`-crate/COM code already ships (e.g. `set_badge_count`, and the Tier A jump list). This still depends on P5-41 (the WinRT toast + custom activator), so it rides with that; it was not part of the Tier A wave.  
**Note:** Tray icon and `matrix:` deep links already bring the window forward on most interactions. Revisit when tauri-plugin-notification gains click handler support upstream.  
**Complexity:** High (platform-specific native code required).

---

### [~] P5-36 · Desktop — Windows Jump List — IMPLEMENTED (Tier A); native CI-compile-pending, runtime-verify on Windows

**What:** Right-clicking the taskbar icon shows a jump list with recent/favorite rooms for quick navigation.  
**Status:** Deferred — implementing the Windows COM jump list API in Tauri requires iterating on C++/COM code that can only be compile-checked on Windows, making blind CI iteration impractical.  
**Action when unblocked:** Revisit when a Tauri plugin abstracts the Windows Shell `ICustomDestinationList` interface, or when a Windows build environment is available for local iteration.  
**Complexity:** High (Windows-only native COM).

---

### [~] P5-41 · Desktop — Native WinRT Toast Notifications — IMPLEMENTED (Tier B; ToastNotification + reply input + in-process Activated; falls back to tauri-plugin-notification); native CI-compile-pending. Runtime needs a Start-menu shortcut + matching AppUserModelID to surface

**What:** Replace emulated notifications with native WinRT Toast notifications.  
**Approach:** Implement native WinRT Toast integration using `windows-rs` to enable full Action Center integration, including native Quick Reply functionality.

### [~] P5-42 · Desktop — Persistent Background Sync — IMPLEMENTED (Batch 3, pragmatic keep-alive); native CI-compile-pending, runtime-verify on Windows

**What:** Keep receiving messages/notifications instantly while the app is closed to the tray.  
**Shipped approach (80/20):** rather than a multi-sprint headless Rust sync client, disable Chromium background throttling via WebView2 `additional_browser_args` (`--disable-background-timer-throttling --disable-renderer-backgrounding --disable-backgrounding-occluded-windows`, added to the existing Tauri default args) so the existing JS Matrix `/sync` loop keeps running full-speed in the tray. Windows/WebView2 only; does not block system sleep. See `cinny-desktop/src-tauri/src/lib.rs` (WebviewWindowBuilder).  
**Deferred (not needed):** the full headless Rust sidecar — only revisit if WebView2 ever hard-suspends despite these flags (would require a second Matrix client with its own /sync + push-rule eval + E2EE-aware notification content).

### [~] P5-43 · Desktop — System Media Transport Controls (SMTC) — IMPLEMENTED (Tier A); CI-compile-pending; SMTC may need an active media/audio session to surface — verify on Windows

**What:** Integrate with Windows SMTC for volume flyout call/media control.  
**Approach:** Use Windows SMTC API to expose call status, mic mute/unmute, and media controls to the Windows volume flyout/media overlay.

### [~] P5-44 · Desktop — Taskbar Thumbnail Toolbar — IMPLEMENTED (Tier A); native CI-compile-pending, runtime-verify on Windows

**What:** Add persistent call controls to the taskbar preview.  
**Approach:** Implement a COM thumbnail toolbar in the application preview window, featuring Mute/Deafen/End Call buttons.

### [~] P5-46 · Desktop — System Power Management (Call Continuity) — IMPLEMENTED (Tier A reference); web verified; native CI-compile-pending (Windows only; macOS/Linux no-op TODO)

**What:** Prevent system sleep/hibernate during active calls.  
**Approach:** Use Tauri/Rust `power-manager` or platform-specific APIs to block system power saving states while a voice/video session is active.

### [~] P5-47 · Desktop — TDS-Styled Native Window Chrome — IMPLEMENTED (Tier A, OPT-IN/default-off, runtime-reversible); web verified; native CI-compile-pending

**What:** Replace system titlebar with custom Lotus TDS chrome.  
**Approach:** Configure Tauri window (`decorations: false`) and implement custom, TDS-token compliant titlebar controls (Close/Max/Min) for a cohesive UI.

### [~] P5-48 · Desktop — Native File System Drag-and-Drop Improvements — IMPLEMENTED (recursive folder upload, web-verified: tsc/build/tests). SCOPED-OUT: `.lnk` shortcut resolution (webview never exposes a dropped file's OS path → native can't resolve the target) and "Send To" (installer/registry shell integration) — deferred

**What:** Enhance drag-and-drop support for Windows.  
**Approach:** Improve handling for Windows file shortcuts, recursive folder uploads, and shell-integrated "Send To" context menu actions.

### [~] P5-49 · Desktop — Network Awareness (NCSI Integration) — IMPLEMENTED (Tier A; INetworkListManager poll → mx.retryImmediately); native CI-compile-pending, runtime-verify on Windows

**What:** Proactively detect Windows network connectivity changes.  
**Approach:** Integrate with the Windows Network Connectivity Status Indicator (NCSI) API to improve offline mode transition latency and network recovery.

### [WON'T FIX] P5-50 · Desktop — Windows Hardware-Accelerated Media Pipeline

**What:** Replace standard browser decoding with native Windows Media Foundation.  
**Why won't-fix (researched):** WebRTC media (the call pipeline) lives entirely inside WebView2/Chromium — you cannot inject Media Foundation/DirectShow into WebRTC's decode path from the Tauri host. Chromium already uses the platform's hardware decoders (D3D11VA/MF) where the GPU supports the codec, so there is no separate CPU pipeline to offload. Not actionable as described.

### [DEFERRED] P5-51 · Desktop — Federated "Identity Contexts" (Isolation Manager)

**What:** Compartmentalize sessions, local databases, and caches into isolated "Contexts" (e.g. Work vs. Personal) with a zero-leak boundary.  
**Decision:** Deferred (reviewed 2026-07). Multi-sprint, and it touches the auth/crypto/storage core — not worth the risk/effort for a niche need right now. Kept here with a concrete spec so it's actionable later.

**Future-work spec (why it's big):** the app is currently **single-session**.

- Session lives in `src/app/state/sessions.ts` under fixed localStorage keys — `cinny_access_token`, `cinny_device_id`, `cinny_user_id`, `cinny_hs_base_url`, plus the OIDC keys (`cinny_refresh_token`, `cinny_expires_at`, `cinny_oidc_*`).
- Persistence lives in `src/client/initMatrix.ts`: two fixed IndexedDB stores — `web-sync-store` (`IndexedDBStore`) and `crypto-store` (`IndexedDBCryptoStore`) — feeding one `createClient(...)`.

True per-context isolation would require: (1) namespace every localStorage key per context (`ctx:<id>:cinny_*`); (2) per-context IndexedDB dbNames for **both** the sync store and the crypto store; (3) a context registry + switcher UI (create/rename/delete/switch); (4) full client teardown + re-init on switch (`initMatrix` currently assumes one global client); (5) per-context settings + notification/quiet-hours state; (6) careful crypto-store isolation so device keys never bleed across contexts. **Smaller intermediate step** if demand appears: plain multi-account (fast account switch) _without_ the hard isolation boundary — much less risky, reuses most of the login flow.  
**Priority:** Extreme Low (Multi-sprint/Architectural).

### [DROPPED] P5-52 · Desktop — Room-Level Sync Governor (Performance Control)

**What:** Granular per-room sync tuning (frequency, event-type filtering).  
**Why dropped (reviewed 2026-07):** matrix-js-sdk can't do **true** per-room sync filtering — all room events still come down the single `/sync` stream, so "disable typing/receipts in heavy rooms" can only be a **cosmetic client-side hide**, not an actual performance/bandwidth win. That, plus the UX-complexity risk flagged originally, makes it not worth building. If per-room quieting is ever wanted, add a simple "mute typing & receipts in this room" toggle to normal room settings — not a "governor."

### [DEFERRED] P5-53 · Desktop — Local-Only "Scripting" Plugin System (Tampermonkey-like)

**What:** A sandboxed environment for local execution of user scripts on Matrix events.  
**Decision:** Deferred (reviewed 2026-07). A full WASM execution engine + script registry + management UI + security model is a large surface for a very small (power-user) audience.  
**Recommended lighter alternative (the ~80/20) if we ever want event automation:** a built-in **automation-rules** feature — declarative "when an incoming event matches X (room / sender / keyword / type) → notify / play sound / highlight / auto-react" rules, configured in Settings. Covers the realistic use cases (custom alerts, keyword pings) with **no arbitrary code execution**, so no sandbox/security burden. Build that instead of a scripting engine if the need arises.

### [~] P5-55 · Desktop — Composer Toolbar Drag-and-Drop Reordering — IMPLEMENTED (Tier A); web-verified (tsc/build/tests). Awaiting live UX check

**What:** Allow users to reorder toolbar icons via drag-and-drop.  
**Approach:** Extend the current settings-based toolbar toggle system to include a drag-and-drop UI mode in the composer settings, allowing users to personalize their icon order.

### [~] P5-56 · Desktop — Windows "Focus Assist" (DND) Sync — IMPLEMENTED (Tier B; SHQueryUserNotificationState poll → suppresses notifications+sounds via the quiet-hours gate); native CI-compile-pending, runtime-verify on Windows

**What:** Automatically toggle notification state based on Windows Focus Assist.  
**Approach:** Integrate with the Windows `NotificationCenter` / `Focus` state via Tauri/Rust to automatically enable/disable Lotus Chat's internal notification suppression mode when Windows Focus Assist is toggled.

### [~] P5-57 · Desktop — Visual Draft Persistence Indicator — IMPLEMENTED (Tier A); web-verified. Awaiting live UX check

---

## 🚀 Features to Add

- [ ] **Mobile Audit:** Comprehensive audit of all features in LOTUS_FEATURES.md for mobile PWA usability and layout responsiveness.

---

## Blocked Features

These features are confirmed desirable but cannot be built until the listed dependency is resolved.
Check back after each Synapse upgrade — re-run `/matrix/client/versions` and `unstable_features` to see if they've become available.

### [BLOCKED] · Live Location Sharing (MSC3489 + MSC3672)

**Blocked by:** `org.matrix.msc3489 = false` AND `org.matrix.msc3672 = false` on `matrix.lotusguild.org` (confirmed from unstable_features).  
**What it would do:** Real-time GPS beacon streaming upgrading the existing static location share.  
**Action when unblocked:** Both MSCs must be enabled on the homeserver before any client work.

### [BLOCKED] · Reaction / Relation Redaction (MSC3892)

**Blocked by:** `org.matrix.msc3892` = false on `matrix.lotusguild.org`  
**What it would do:** Cleanly remove a reaction without redacting the parent message.  
**Current behavior:** Full event redaction — acceptable fallback, no user-facing issue.  
**Action when unblocked:** Find `onReactionToggle` redaction call site; swap in MSC3892 endpoint with fallback.

### [BLOCKED] · Room Preview Before Joining (MSC3266)

**Blocked by:** `GET /_matrix/client/v1/rooms/{roomId}/summary` returns `M_UNRECOGNIZED` 404 — endpoint not implemented in Synapse 1.155. Config flag `msc3266_enabled: true` is set but has no effect; Synapse appears not to have shipped a stable implementation at the v1 path. Verified 2026-06-18.  
**What it would do:** Show room name, topic, avatar, member count before joining.  
**Action when unblocked:** Re-test after each future Synapse upgrade.

### [BLOCKED] · Thread Subscriptions (MSC4306)

**Blocked by:** `org.matrix.msc4306` = false on `matrix.lotusguild.org`  
**What it would do:** Follow a thread without posting; get notifications for replies.  
**Action when unblocked:** Add "Follow thread" button in the thread panel header (depends on #P3-8 Thread Panel).

### [DONE] · Report User (MSC4260) ✅

**Previously blocked by:** Server spec v1.12, but `POST /_matrix/client/v3/users/{userId}/report` was confirmed **200** on 2026-06-18 (live since Synapse 1.133.0).  
**What it does:** Reports a specific user to homeserver admins (separate from reporting a message).  
**Note:** Report Message already exists in upstream Cinny. This adds Report User to the profile panel.  
**Implemented 2026-06-18:** `ReportUserModal.tsx` added at `src/app/features/room/ReportUserModal.tsx`. Button wired into `UserRoomProfile.tsx` between UserModeration and UserDeviceSessions (hidden for own profile). Category dropdown + reason text, inline success/error feedback, auto-close 1500ms after success.

---

## Pending Audits

### [DEFERRED] Audit-3 · Profile banner image — Matrix protocol support — RESEARCHED (2026-07)

**Finding:** [MSC4427 — Custom banners for user profiles](https://github.com/matrix-org/matrix-spec-proposals/pull/4427) defines a `banner_url` profile field on top of the MSC4133 extensible-profile system (which our server supports, `uk.tcpip.msc4133.stable = true`, and which became stable in Matrix v1.16). However MSC4427 is an **open proposal, not merged** — no cross-client standard yet, so per this item's own rule: do not implement. **Revisit when MSC4427 merges** (implementation would then be small: read/write the field via the MSC4133 profile API + render a banner in UserHero/profile popouts).

---

## Priority 6 — Post-audit batches (2026-07)

Buildable follow-ups surfaced by the deep-audit wave. Web Push (N107) deliberately deferred. **macOS is out of scope for all of these — Linux is the parity target (Windows already has most native features).**

### [~] P6-1 · Desktop — cross-platform parity (Linux + Windows; NO macOS) — IMPLEMENTED (2026-07); native CI-compile-pending, runtime-verify on Linux

From the desktop audit. Round out the native app now that the full Rust stack compiles:

- **No-sleep during calls on Linux** — `power.rs` is Windows-only (`SetThreadExecutionState`); add a Linux inhibitor (`org.freedesktop.login1.Manager.Inhibit` / ScreenSaver inhibit via zbus/D-Bus) so the display/system doesn't sleep mid-call.
- **Taskbar/launcher unread badge on Linux** — `set_badge_count` is Windows-only; add Unity/`com.canonical.Unity.LauncherEntry` (D-Bus) count where supported.
- **Launch-on-login** — add `tauri-plugin-autostart` (cross-platform) + a Settings/tray toggle.
- **Tray "Do Not Disturb" toggle** — the tray menu is Open/Quit only; add a DND item (reuses the Focus-Assist suppression atom path) so users can silence notifications from the tray.
  CI-compile-verified (Windows + Linux runners); no local Rust.

### [~] P6-2 · Element Call fork — retire the remaining DOM hacks — DEAFEN DONE (2026-07), Phase-2 pending publish

**Shipped (Phase 1):** new `io.lotus.set_deafen` action in the fork (`lotusDeafen.ts`) sets remote `RemoteParticipant.setVolume` per source (mic + screenshare-audio), persisting to late joiners — replaces the brittle `CallControl.setSound`/`applyScreenshareAudioMuted` `<audio>.muted` iframe-DOM hack. cinny now sends it (join-gated) alongside the retained DOM hack (transitional). Folded into unpublished fork `0.20.1-lotus.2`.
**Phase 2 (needs user publish):** publish `0.20.1-lotus.2` to npm → bump cinny pin `lotus.1`→`lotus.2` → delete the DOM `.muted` code. See HANDOFF §12.4.
**DEFERRED (rationale):** the `useCallSpeakers` DOM-scrape is a dormant _fallback_ behind `io.lotus.call_state` (deleting only removes the safety net); the `.click()`-by-`data-testid` UI toggles (screenshare/grid/spotlight/reactions/settings) are low-value and would balloon fork surface for buttons that just trigger EC's own UI.
**Divergence:** deafen doesn\'t silence soundboard/`Unknown`-source audio (setVolume type limit) — confirm UX.

_Original scope below._

### [ ] P6-2b · Element Call fork — remaining DOM hacks (deferred pieces)

Replace cinny's fragile iframe-`contentDocument` reaches with proper `io.lotus.*` widget actions in the fork (`LotusGuild/element-call`), which break on EC re-renders/version bumps:

- **Deafen / screenshare-audio-mute** → an `io.lotus` action that mutes/attenuates `RemoteAudioTrack`s at the LiveKit source (replaces `CallControl.ts` `setSound`/`applyScreenshareAudioMuted` DOM `.muted` poking).
- **UI-toggle actions** (screenshare/spotlight/reactions/settings) → replace the `.click()`-by-`data-testid` calls.
- Retire the `useCallSpeakers` DOM-scrape fallback once `io.lotus.call_state` is verified.
  Fork commits are local (coordinator); publishing needs the user's npm token.

### [~] P6-3 · Web UX wins - DONE (2026-07): forward multi-select + live bookmark previews

**Shipped:** Forward Message multi-select (checkbox rooms + "Send to N", batch `Promise.allSettled` with partial-failure summary; content builder extracted to tested `forwardContent.ts`). Live bookmark previews (`BookmarksPanel` renders the live event via `useRoomEvent` - edits + redactions - snapshot as fallback / left-room). Both `lotus`, gate-green (665 tests).

_Original scope:_

### [ ] P6-3-orig · Web UX wins (from the audit ADD list)

- **Forward to multiple rooms** — multi-select (checkbox + "Send to N") in `ForwardMessageDialog` (currently one room per open, capped at 60).
- **Live bookmark previews** — `BookmarksPanel` shows a stale snapshot captured at save time; resolve live from the event when cached (edits/redactions), fall back to the snapshot.
- Other small paper-cuts as scoped.

### [~] P6-4 · Hygiene sweep - TRIMMED (2026-07): security headers only

**Shipped:** HSTS + Permissions-Policy on the real prod nginx (`matrix/cinny/nginx.conf`, already had X-Frame/CSP/Referrer) + synced the `contrib/nginx` + `contrib/caddy` examples (also fixed the caddy `try_files` SPA fallback). Permissions-Policy allows `self` for the features the app uses (camera/mic/display-capture/geolocation/autoplay/fullscreen), denies unused. **User must `nginx -s reload` on the LXC + verify calls/location still work.**
**WON'T-DO (rationale):** patch-package migration - the current `patch-folds.mjs` is already robust (fails hard on drift) and patch-package would be more brittle to folds restructuring; `types/matrix` drift - risky spot-fixes with no concrete bug; build-config streamlining - build is already ~5s. Known follow-up: nginx `add_header` isn't inherited by the cache `location` blocks (pre-existing; the SPA entry `/` still gets all headers, so HSTS is delivered).

_Original scope:_

### [ ] P6-4-orig · Hygiene sweep

- `patch-folds.mjs` (edits `node_modules` directly) → `patch-package`.
- `contrib/nginx` + `contrib/caddy`: security headers (HSTS/CSP), `try_files` over rewrites, fix the caddy placeholder path.
- `types/matrix/` drift (mirrors SDK types) — spot-fix the highest-risk.
- Build-config: streamline `lotusDenoise` sequential `fs` work + redundant `viteStaticCopy` renames.

---

## 📚 Implementation Reference

Exhaustive, low-level implementation details for backlog items. Follow these patterns to ensure code is "Lotus-perfect" (idiomatic, performant, and TDS-compliant).

### P3-8 · Thread Panel (Full Side Drawer) — 🟢 FULL DESIGN (2026-07, ready to execute)

**Decisions (each backed by SDK evidence in node_modules/matrix-js-sdk):**

| Question         | Decision                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Thread rendering | **New lean `ThreadTimeline`** reusing `Message`, `useVirtualPaginator`, and RoomTimeline's exported timeline helpers (lines 156-227). Do NOT refactor 2214-line RoomTimeline (its ~35 hooks are hardwired to the room live timeline).                                                                                                                                                                                                |
| threadSupport    | **Enable `threadSupport: true`** in `initMatrix.ts` (~line 39). ⚠️ Thread replies then LEAVE the main timeline (`room.js eventShouldLiveIn` → `shouldLiveInRoom:false`), retroactively on reload — MUST ship the "N replies" summary chip in the same release. Roots stay in both timelines.                                                                                                                                         |
| State            | `roomIdToActiveThreadIdAtomFamily` (per-room, mirrors `roomIdToReplyDraftAtomFamily`) in new `state/room/thread.ts` + `getThreadDraftKey(roomId, threadRootId)` = `` `${roomId}::${threadRootId}` ``                                                                                                                                                                                                                                 |
| Composer         | **Reuse RoomInput**: add optional `threadRootId` prop; scope its 3 atom-family lookups by draftKey (isolates thread drafts from the main composer); pass `threadRootId ?? null` at all 7 `mx.sendMessage/sendEvent` call sites — the SDK's `addThreadRelationIfNeeded` then emits spec-correct `m.thread` relations incl. reply-in-thread. Separate `useEditor()` instance in the panel. Hide schedule + commands in thread mode v1. |
| Unreads          | v1 = unread badge on the summary chip (`room.getThreadUnreadNotificationCount` — counts already synced independent of threadSupport) + `markThreadAsRead` threaded receipt when panel open at bottom.                                                                                                                                                                                                                                |
| Mobile           | Pure CSS like `MembersDrawer.css.ts`: fixed width toRem(360) desktop, `position:fixed; inset:0` under 750px.                                                                                                                                                                                                                                                                                                                         |

**Critical side-effect fixes (one-liners, land FIRST):**

1. `initMatrix.ts` → `threadSupport: true`.
2. `utils/notifications.ts:24` → `sendReadReceipt(latestEvent, type, /*unthreaded*/ true)` — otherwise markAsRead becomes `main`-scoped and room badges stick permanently unread (room unread total includes thread counts).

**Known SDK traps (verified):**

- **Local echo gap:** chronological pending ordering means the thread timelineSet never receives pending events (`canContain` rejects; `room.getPendingEvents()` THROWS in this mode) — ThreadTimeline must render its own pending strip via `RoomEvent.LocalEchoUpdated` filtering on `threadRootId`, deduped against `thread.findEventById`.
- **Bootstrap:** `room.getThread(id) ?? room.createThread(id, room.findEventById(id), [], false)` — the SDK auto-fetches via `/relations` and inserts the root at top; gate rendering on `thread.initialEventsFetched`; decrypt with `decryptAllTimelineEvent` after init + each pagination.
- **Deep links:** `getEventTimeline(mainSet, threadEventId)` returns undefined for thread events — redirect jump-to-event to the panel (best-effort v1).
- **Summary chip** must render from the server-aggregated bundle (`unsigned['m.relations']['m.thread']`) so it works before any Thread object exists.
- Room-list "latest message" preview may show the root, not the newest reply — cosmetic, accept v1.

**File inventory — new:** `state/room/thread.ts` (+test), `features/room/thread/{useThread.ts, threadSummary.ts(+test), ThreadTimeline.tsx(+css), ThreadPanel.tsx(+css), ThreadSummary.tsx, index.ts}`, `hooks/useThreadSummary.ts`. **Edited:** `initMatrix.ts` + `utils/notifications.ts` (coordinator, step 0), `RoomInput.tsx` (threadRootId prop), `RoomTimeline.tsx` (handleReplyClick startThread → open panel; ThreadSummary chips at the two Message call sites; Reply onThreadClick; deep-link redirect), `components/message/Reply.tsx`, `Room.tsx` (render panel after MediaGallery block, gated `!callView && activeThreadId`, `key={roomId+threadId}`).

**4-agent partition:** step 0 (coordinator one-liners) → A: state+SDK glue (+tests) · B: ThreadTimeline (largest; copies the `useTimelinePagination` pattern rather than exporting it) · C: RoomInput changes · D: panel shell + RoomTimeline/Reply integration — all parallel against pinned interface contracts → coordinator wires Room.tsx + gates.

**Verification:** gates (tsc/eslint/build/tests) + post-merge manual QA: open thread via chip/menu/indicator; pending→confirmed echo; `is_falling_back:false` on reply-in-thread; main timeline shows root+chip only; badge clears; reload keeps partitioning; encrypted threads decrypt. **Release note required:** threaded replies no longer render inline in the main timeline.

---

### P4-4 · Math / LaTeX Rendering

**Mechanism:** KaTeX injection into the HTML parser.

- **Sanitizer (`src/app/utils/sanitize.ts`):** Allow KaTeX-specific tags and classes (e.g., `span`, `annotation`, `math`). Use a specialized allowed list for math blocks.
  > [Gemini_Found] `sanitize.ts` uses **`sanitize-html`** (not DOMPurify) with an explicit allowlist (`allowedTags`) and `disallowedTagsMode: 'discard'`. All MathML tags are currently absent from the allowlist and are silently stripped. Update `permittedHtmlTags` to include: `<math>`, `<mi>`, `<mo>`, `<mn>`, `<ms>`, `<mtext>`, `<mspace>`, `<mrow>`, `<mfrac>`, `<msqrt>`, `<mroot>`, `<mstyle>`, `<merror>`, `<mpadded>`, `<mphantom>`, `<mfenced>`, `<menclose>`, `<msub>`, `<msup>`, `<msubsup>`, `<munder>`, `<mover>`, `<munderover>`, `<mmultiscripts>`, `<mtable>`, `<mtr>`, `<mtd>`, `<maligngroup>`, `<malignmark>`, and `annotation`. Also add the required MathML attributes (e.g. `xmlns`, `display`, `mathvariant`) to `permittedTagToAttributes`.
- **Parser (`src/app/plugins/react-custom-html-parser.tsx`):** Detect `$ ... $` and `$$ ... $$` patterns in text nodes:
  ```tsx
  if (node.type === 'text') {
    const parts = node.data.split(/(\$\$.*?\$\$|\$.*?\$)/g);
    return parts.map((p) => {
      if (p.startsWith('$')) return <KaTeX math={p.replace(/\$/g, '')} />;
      return p;
    });
  }
  ```
- **CSS (`src/app/styles/CustomHtml.css.ts`):** Import `katex/dist/katex.min.css` only when a math block is rendered to save initial bundle size.

---

### P4-6 · OIDC / SSO Next-Gen Auth (MSC3861)

**Mechanism:** Matrix Authentication Service (MAS) Integration.

- **Architecture:** Shift from password-based `/login` to OAuth2 `authorization_code` flow.
- **Key Files:** `src/app/pages/auth/Login.tsx` and `src/app/hooks/useAuth.ts`.
- **Implementation:** Use `oidc-client-ts` or a similar lightweight OIDC library. Check for `m.authentication` in `/.well-known/matrix/client`. Redirect to the MAS authorization endpoint. Handle the callback in a new `OidcCallback` route and store the OIDC `refresh_token`.

---

### P5-1 · Custom Accent Color Picker (Non-TDS only)

**Mechanism:** Dynamic CSS variable injection.

- **Setting (`src/app/state/settings.ts`):** Add `customAccentColor: string` (hex).
- **Manager (`src/app/pages/ThemeManager.tsx`):** Inside the `useEffect` that monitors theme changes:
  ```typescript
  if (!lotusTerminal && customAccentColor) {
    document.documentElement.style.setProperty('--lt-accent-orange', customAccentColor);
    document.documentElement.style.setProperty('--lt-accent-orange-glow', `${customAccentColor}80`);
  }
  ```
- **UI (`src/app/features/settings/general/General.tsx`):** Use `<Input type="color">`. Hide this section if `lotusTerminal` is `true`.

---

### P5-15 · In-Call Soundboard

**Mechanism:** Local-to-Global Audio Bridge via Web Audio API.

- Create an `AudioContext` and a `MediaStreamDestinationNode`.
- Create an `AudioBufferSourceNode` for each clip.
- Route the mic `MediaStream` and the clip source to the destination node.
- Pass the destination's `.stream` to the call bridge.

> ⚠️ **[Gemini_Found — CORRECTED]** Gemini originally suggested using LiveKit's `LocalAudioTrack.replaceTrack()` to mix audio into the call stream. This is **not possible** from Lotus Chat's realm: Element Call runs in a **cross-origin iframe** controlled via `matrix-widget-api` (postMessage). LiveKit's JS SDK and its `LocalAudioTrack` live inside EC's sandboxed context — inaccessible from our code. This directly contradicts the confirmed constraint already listed in the Server Capabilities table: _"Cindy CANNOT inject audio into EC call stream — In-call soundboard must be redesigned as local-only."_ The soundboard must be a local-playback-only feature (output through the user's speakers, not mixed into the call audio stream).
>
> 🔱 **[EC-FORK — RESOLVED]** Both the original claim and the earlier "practical blocker still holds" correction are now **outdated**. EC is same-origin **and** we own the source, so we no longer reach into EC's module scope from cinny — instead the fork **exposes the inject point itself**: the `io.lotus.inject_audio` widget action (`LotusWidgetActions.InjectAudio`) publishes a clip as a separate LiveKit track from inside EC. A **real** in-call soundboard (mixed into the call, not local-only) is therefore unblocked, and the cinny-side soundboard UI is now **built** (P5-15 above): uploadable clips played into the call via this action, stored in `io.lotus.soundboard` account data.

---

### P5-20 · Quick Reply from Browser Notification

**Mechanism:** Service Worker `notificationclick` Action.

> [Gemini_Found] Implementation detail: `serviceWorkerRegistration.showNotification()` should be used instead of `new Notification()` so that the service worker can listen to the `notificationclick` event. `new Notification()` creates notifications that are bound to the client page, not the SW.

```typescript
// src/sw.ts
self.addEventListener('notificationclick', (event) => {
  if (event.action === 'reply' && event.reply) {
    const { roomId, threadId } = event.notification.data;
    const session = sessions.get(event.clientId);
    fetch(`${session.baseUrl}/_matrix/client/v3/rooms/${roomId}/send/m.room.message`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${session.accessToken}` },
      body: JSON.stringify({
        msgtype: 'm.text',
        body: event.reply,
        'm.relates_to': threadId ? { rel_type: 'm.thread', event_id: threadId } : undefined,
      }),
    });
  }
});
```

---

### P5-30 · Advanced ML Noise Suppression — Model Roadmap

See shipped implementation in LOTUS_FEATURES.md → "Noise Suppression (Advanced Multi-Tier)".

**Models status:**

- **RNNoise** (sapphi, 48 kHz) — ✅ working, default fallback. Keep — runs on any hardware.
- **Speex** (sapphi, 48 kHz) — ✅ working, low value; candidate to drop.
- **DTLN** (@workadventure, 16 kHz) — 🟡 wired; sample-rate fix applied (was robotic at 48 kHz). **TODO: verify in a real call.** Narrowband (16 kHz) = slightly telephone-y even when correct.

**Constraints:** client-side AudioWorklet, fully self-hosted, no GPU, self-hosted SFU (no LiveKit Cloud).

**Roadmap:**

- [ ] Verify DTLN 16 kHz fix in a real call.
- [ ] **DeepFilterNet 3** — best self-hostable upgrade: Rust→WASM, CPU real-time, 48 kHz fullband. Self-host `df_bg.wasm` + DFN3 ONNX model; wire a 48 kHz worklet. Audio quality unverifiable without a real-call test.
- [ ] **Desktop-only / HW-gated:** FRCRN (Alibaba) or NVIDIA Maxine (RTX/Tensor only). Runs in Tauri Rust backend + bridges a virtual mic into the webview. Must detect capability; web + weak HW falls back to RNNoise/DTLN.

---

### P5-31 · Granular Voice & Screenshare Quality Controls

**Mechanism:** WebRTC Encoding Parameters + Backend Quality Guard.

- **State Event:** `io.lotus.room_quality` (state key `""`) containing:
  ```json
  { "audio_bitrate": 128000, "screen_max_res": "1080p", "screen_max_fps": 60 }
  ```
- **Screenshare:** In `src/app/plugins/call/CallControl.ts`, map the "Quality" setting to `getDisplayMedia` constraints.
- **Audio Bitrate:** After the call joins, find the `RTCRtpSender` for the audio track:
  ```typescript
  const sender = peerConnection.getSenders().find((s) => s.track?.kind === 'audio');
  const params = sender.getParameters();
  params.encodings[0].maxBitrate = roomBitrate || 128000;
  await sender.setParameters(params);
  ```
- **Backend Sidecar:** Extend `voice-limit-guard.py` (LXC 151) to fetch `io.lotus.room_quality` and inject limits into the LiveKit JWT or return them as an authorized config packet.

---

### [x] P5-40 · Desktop — Proactive Update Notifications (Tauri) — DONE (already shipped: `TauriUpdateFeature` in ClientNonUIFeatures.tsx polls every 12h + fires the sticky update toast)

**Key Files:** `src/app/hooks/useTauriUpdater.ts`, `src/app/pages/client/ClientNonUIFeatures.tsx`, `src/app/features/toast/LotusToastContainer.tsx`.

1. Create a `TauriUpdateFeature` component. Use `useTauriUpdater()` to get the `check` function and `status`.
2. In a `useEffect`, call `check()` on mount and then on a `setInterval` (every 12 hours).
3. When status transitions to `{ state: 'available', version: '...' }`, fire a Lotus Toast: "Lotus Chat v[version] is available!" with an "Update" button that calls `install()`.
4. Store `lastCheck` timestamp in `localStorage` to prevent redundant checks on refresh.

---

### Mobile Bookmarks Visibility Fix

**Issue:** `ClientLayout.tsx` explicitly restricts `BookmarksPanel` to `ScreenSize.Desktop` (lines 51-56).

```tsx
// ClientLayout.tsx
{
  bookmarksOpen && (
    <BookmarksPanel
      onClose={() => setBookmarksOpen(false)}
      isMobile={screenSize !== ScreenSize.Desktop}
    />
  );
}
```

`BookmarksPanel.tsx` already supports the `isMobile` prop (line 127) to enable full-screen absolute positioning. No other changes required.

---

### Remind Me Later (Slack-style)

**Mechanism:** Account Data + Timer/Service Worker.

- **Storage (`src/app/hooks/useReminders.ts`):** Store in account data `io.lotus.reminders` as `Array<{ id: string, roomId: string, eventId: string, timestamp: number }>`.
- **Context Menu (`src/app/features/room/message/MessageContextMenu.tsx`):** Add "Remind me" option → opens date/time picker modal (reuse `JumpToTime.tsx` logic).
- **Trigger (foreground):** `setTimeout` in a hook inside `ReminderMonitor` in `ClientNonUIFeatures.tsx` → pushes to `toastQueueAtom` in `state/toast.ts` when due.
- **Trigger (background):** Use Service Worker — `setTimeout` in the main thread will not fire when the PWA is suspended.

---

### Mobile Usability Audit — Methodology

1. **Viewport & Touch:** All interactive elements must have at least `44px × 44px` touch targets. Audit for horizontal overflow (horizontal scrolling must be disabled).
2. **Modal Responsiveness:** All modals (Settings, Profile, etc.) MUST cover the full screen on mobile, not float as overlays.
3. **Sidebar / Panels:** On mobile, sidebar panels (Members, Bookmarks, Media) must become full-screen overlays (using a `Drawer` or `Modal` pattern) rather than side-by-side flexbox panels.
4. **Input & Composer:** Ensure the composer doesn't get obscured by the mobile keyboard. Test focus trap and blur behaviors.

---

## Implementation Notes

### ⚠️ TDS DESIGN LAW (repeated here for emphasis)

> Every TDS color, animation, glow, border, shadow, and font value MUST come from `/root/code/web_template/base.css`.  
> Never hardcode hex values. Never invent CSS variable names.  
> Key variables: `--lt-accent-orange` · `--lt-accent-cyan` · `--lt-accent-green` · `--lt-glow-*` · `--lt-box-glow-*` · `--lt-border-color` · `--lt-font-mono`  
> Reference implementation: `/root/code/tinker_tickets/` (markdown.js, base.js, ticket.css)  
> This applies without exception to every task marked `[IMPROVE]`, `[Build]`, or any UI change.

### Design Rules

- All new components must respect both TDS dark (`LotusTerminalTheme`) and TDS light (`LotusTerminalLightTheme`) modes
- Non-TDS theme work (custom accent color, theme presets) uses vanilla-extract theme files — match the pattern in `src/lotus-terminal.css.ts`
- Code syntax highlighting token classes: `.tok-kw .tok-str .tok-num .tok-cmt .tok-fn` (defined in `web_template/base.css`)
- `folds AvatarImage` does NOT accept children — wrap Avatar components externally for overlays/frames/borders

### CI/CD Pipeline

```
edit → commit → git push origin lotus
→ Gitea Actions: tsc --noEmit, eslint, prettier (~3 min)
→ Webhook: lotus_deploy.sh on LXC 106 polls CI, then npm ci && npm run build → rsync
→ Live at chat.lotusguild.org (~11 min total)
```

### Per-Feature Checklist (before marking complete)

- [ ] `npx tsc --noEmit` — zero TypeScript errors
- [ ] `npx eslint src/` — zero new errors (warnings OK if pre-existing)
- [ ] `npx prettier --check src/` — formatting passes
- [ ] `README.md` updated (Lotus-custom features only — not upstream Cinny features)
- [ ] `landing/index.html` updated if the feature appears in the comparison table
- [ ] Visually tested at `chat.lotusguild.org` after CI deploys

### Homeserver Access (for server audits)

- **Synapse (Matrix):** LXC 151 on `compute-storage-01` — `pct exec 151 -- bash`
- **Config:** `/etc/matrix-synapse/homeserver.yaml`
- **Version check:** `curl -s https://matrix.lotusguild.org/_matrix/client/versions`

---

## Element Call fork — operational reference

_Ported from the retired `HANDOFF_ELEMENT_CALL_FORK.md` (2026-07; full history in git). The fork lives at `LotusGuild/element-call` (branch `lotus`, forked from upstream tag `v0.20.1`); cinny consumes it as the npm package `@lotusguild/element-call-embedded`, whose built bundle is copied into `public/element-call/`._

**Publish a new fork version (manual; needs the Gitea npm token):**

1. In the fork, bump `embedded/web/package.json` version (current unpublished: `0.20.1-lotus.2`).
2. Build: `pnpm run build:embedded` (Node 24, pnpm 10.33.0; output → repo `dist/`, staged into `embedded/web/dist`).
3. `cd embedded/web && npm version <tag> --no-git-tag-version && npm publish` to the Gitea registry (`code.lotusguild.org`). Publicly readable; only publishing needs the token.
4. In cinny: bump the `@lotusguild/element-call-embedded` pin (`package.json`, currently `0.20.1-lotus.1`) → the new version, `npm install`, build.

**`io.lotus.*` widget actions (fork ↔ cinny host):**
| Action | Direction | Purpose | Fork module |
| :-- | :-- | :-- | :-- |
| `io.lotus.call_state` | EC→host | speaker/mute/camera state stream (URL `lotusCallState=1`) | `lotusCallState.ts` |
| `io.lotus.focus_participant` | host→EC | spotlight a participant (works during screenshare) | `lotusFocus.ts` |
| `io.lotus.inject_audio` | host→EC | soundboard clip mixed into the call (URL `lotusAudioInject=1`) | `lotusAudioInject.ts` |
| `io.lotus.set_quality` | host→EC | audio/screenshare bitrate/fps caps | `lotusQuality.ts` |
| `io.lotus.decorations` | host→EC | in-call avatar decorations | `lotusDecorations.ts` |
| `io.lotus.set_deafen` | host→EC | deafen / screenshare-audio-mute at the LiveKit source (P6-2) | `lotusDeafen.ts` |

Also flag-gated (URL params): `lotusTransparent`/`lotusTheme` (theme), `lotusDenoiseSource=1` (in-source ML denoise). New toWidget actions must be added to the enum + `LOTUS_TO_WIDGET_ACTIONS` in `src/lotus/lotusActions.ts` and only SENT after call-join (else a 10s timeout). **P6-2 phase 2 pending:** after publishing lotus.2, bump the cinny pin + delete the `CallControl.ts` `<audio>.muted` fallback.

---

## 🔴 Open — Actionable

### 🧨 Encryption / E2EE — ⚠️ EXTREME COMPLEXITY · 🧠 PLANNING SESSION REQUIRED · 👤 SENIOR ENGINEER

> 🧰 **Investigation kit ready (2026-07):** `LOTUS_E2EE_INVESTIGATION.md` (git history)
> has the per-KE capture runbook (console signatures, synapse-side queries, the
> KE-1→KE-2 causality decision tree, ranked remediations), and the client now
> ships a **Crypto Diagnostics** capture helper (Settings) — run it during the
> next affected call and download the report before starting any fix.

> **Observed live in prod 2026-06-30** on `chat.lotusguild.org` during a 2-person
> **Element Call** (E2EE enabled). These span **client rust-crypto (via
> `matrix-js-sdk@41.6.0-rc.0`) ↔ Synapse ↔ Element Call's MatrixRTC E2EE** and are
> very likely **interrelated** (see KE-1 → KE-2). Do **not** spot-fix — they need
> a dedicated cross-system planning session with the homeserver owner. Capture
> full client console + a synapse-side trace for the same call before starting.
> **None of these are caused by the EC fork work** (the issues reproduce on the
> old build; the local mic/denoise path is unrelated to key distribution).

- **KE-1 — One-time-key (OTK) upload conflict storm (CRITICAL, root-cause candidate).**
  `POST /_matrix/client/v3/keys/upload` returns `400 M_UNKNOWN: One time key
signed_curve25519:AAAAAAAAAGQ already exists. Old key: {…} new key: {…}` —
  firing **continuously** (many/sec). The client repeatedly tries to publish an
  OTK at a key id the server already holds **with a different value**, i.e. the
  rust-crypto key store and Synapse have **diverged OTK state**. Impact: floods
  the crypto outgoing-request loop and is the prime suspect for the downstream
  missing-key failures (no fresh OTKs ⇒ no new Olm sessions ⇒ undecryptable
  to-device key events). _Investigate:_ device/key-store reset-or-restore
  mismatch, OTK id-counter desync, RC-SDK (`41.6.0-rc.0`) regression, or a
  Synapse OTK bug. Repro signature: grep console for `already exists`.
  **Extreme — planning session.**
  **Update 2026-07 (investigation §6):** upstream `matrix-rust-sdk#5200` (still
  OPEN) confirms the mechanism — on the 400, `mark_request_as_sent()` never fires
  so the SDK re-issues the identical upload forever. **`41.7.0` does NOT fix it**
  (crypto-wasm 17→18.3.1 has no OTK/upload change; 18.3.x was to-device security
  only) — the SDK-pin lever is closed. Root cause = **store↔server OTK
  divergence**; the leading **web-specific** trigger is that cinny never calls
  **`navigator.storage.persist()`**, so the IndexedDB crypto store is evictable
  while the `localStorage` session/device-id survives → device resurrects with a
  blank store → re-uploads OTKs the server still holds. **Actionable preventive
  fix (buildable now, no call needed):** request persistent storage on login
  (+ optional multi-tab guard + 400-loop→recovery-prompt). Healing an already-
  diverged device still needs a clean **logout+login** (not just "clear
  storage"). Full runbook (synapse SQL, capture checklist, §6 diagnosis) is in git history at `LOTUS_E2EE_INVESTIGATION.md` (removed 2026-07).

- **KE-2 — Element Call media keys not arriving/decrypting → audio & video cut out (CRITICAL).**
  `MissingKey: missing key at index N for participant @user`, `skipping decryption
due to missing key`, `MissingKey: key set not found for @user at index 0`, and
  rust-crypto `WARN … Received an unexpected encrypted to-device event …
event_type="io.element.call.encryption_keys"`. EC distributes per-participant
  media keys as **encrypted to-device `io.element.call.encryption_keys`** events;
  these aren't being received/decrypted in order, so remote LiveKit audio/video
  can't be decrypted — **this is the "friend's audio cuts out occasionally"
  symptom.** Almost certainly downstream of **KE-1** (broken Olm sessions). Spans
  EC's MatrixRTC E2EE + rust-crypto to-device + Synapse. **Extreme — planning
  session.**

- **KE-3 — Timeline decryption error: missing `algorithm` field (HIGH).**
  `Error decrypting event (… type=m.room.encrypted …): DecryptionError[msg:
missing field 'algorithm' at line 1 column 138 …]`. A malformed/legacy
  encrypted event (or a serialization mismatch in the RC SDK) that rust-crypto
  can't parse. Lower frequency than KE-1/2 but a distinct decode-path failure —
  capture the offending event id (`$SASBBzoqj…` seen) and inspect its raw content.

- **KE-4 — MatrixRTC delayed-event / membership timeouts (MEDIUM-HIGH, reliability).**
  `[MembershipManager] Network local timeout error while sending event, immediate
retry … AbortError: Restart delayed event timed out before the HS responded`,
  with repeated `org.matrix.msc4157.update_delayed_event`. MSC4140/4157
  delayed-event reliability against `matrix.lotusguild.org` — can cause stale/ghost
  call membership and missed leave events. May be partly **homeserver
  responsiveness**; correlate with synapse latency/load. Include in the same
  planning session since it shares the call-reliability + HS-interaction surface.

### Security & Privacy

- **N97 — Access token stored in plaintext `localStorage`** (`state/sessions.ts`), vulnerable to XSS; device ID likewise. Architectural — needs a token-protection / session-storage redesign.
- ~~**Session writes are non-atomic and not cross-tab synced**~~ — **done (2026-07):** atomic single-key `cinny_session_v1` blob (legacy-key migration + dual-write) + `subscribeSessionChanges`/`useSessionSync` cross-tab reload. (The plaintext-token concern in N97 above is the remaining, separate architectural item.)
- **Persisted PII without encryption:** user status message + expiry (`settings/account/Profile.tsx`), unsent composer drafts (`room/RoomInput.tsx`). Leak risk on shared devices.

### PWA / Offline / Notifications

- **N107 — SW has no `push` handler** — Web Push delivery is entirely non-functional. Needs a `push` listener + a Matrix push-gateway integration.
- **No app-asset caching strategy** (`src/sw.ts`) — no offline capability.
- ~~**`manifest: false`** may block PWA install~~ — **verified OK (2026-06):** `index.html` links `/manifest.json`, which exists in `public/` and is copied to `dist/`; VitePWA intentionally doesn't generate one. Not a bug.

### Dependencies & Build

- ~~**`matrix-js-sdk` pinned to a Release Candidate**~~ — **done (2026-07):** moved to `41.7.0` stable (crypto-wasm 18.3.1 security bump). Deep-audit dep triage: all 16 npm advisories are dev-only/unreachable/dead-dep — zero shipped exposure; dead `dompurify` removed. `@atlaskit`/build-tool pins remain review-worthy but low priority.
- **Build-time overhead:** `lotusDenoise` does heavy sequential `fs` work in `closeBundle`; `viteStaticCopy` config is complex with redundant renames — could be streamlined.

### Code Hygiene / DevEx

- **Automated test suite — 561+ tests across 65+ modules, a hard CI gate.** `npm test` runs Node's built-in runner via `tsx` (not vitest — Vite 8 is ahead of vitest's range) and **blocks the build job on failure**. Broad pure-logic coverage: utils (common, regex, sanitize/XSS, time, matrix, matrix-uia, mimeTypes, sort, accentColor, findAndReplace, AsyncSearch, ASCIILexicalTable, keyboard, room, matrix-crypto, featureCheck, syntaxHighlight, imageCompression, user-agent, callSounds), state (settings, sessions, recentSearches, upload, typingMembers, lists, room-list, toast, scheduledMessages, backupRestore, callEmbed/callPreferences, spaceRooms, …), plugins (matrix-to, call/utils, via-servers, bad-words, recent-emoji, custom-emoji, markdown block/inline/utils), OIDC (cs-api, useParsedLoginFlows, oidcState), lotus/avatarDecorations, message-search, search filters. Prevention work has caught + fixed **4 real bugs** (`findAndReplace` infinite-loop; `getSettings` crash-on-load when storage is blocked; `isMacOS` never matching modern Macs; `isMLDenoiseSupported` throwing `ReferenceError` instead of returning false on browsers lacking the `AudioWorkletNode` binding). **Next:** component/integration tests (the untestable-under-tsx DOM/React surface).
- **Extensive `as any` casts** across `src/` — gradual typing cleanup.
- **`types/matrix/` mirrors SDK types** instead of importing them — drift risk.
- ~~**Hardcoded CDN URL** should move to an env var~~ — **done:** `avatarDecorations.ts` already honors a `VITE_DECORATION_CDN` env override (lines 14-16); the in-repo literal is only the default. Nothing left.
- **`patch-folds.mjs` edits `node_modules` directly** — consider `patch-package`.
- **Infra docs:** `contrib/nginx` lacks security headers (HSTS/CSP) + uses rewrites over `try_files`; `contrib/caddy` has a placeholder path. CI/CD (`prod-deploy.yml`): sequential deploy, aggressive 1-min Netlify timeout, `package-manager-cache: false`.
- **README:** keep the fork-sync version + logo path current. (`CONTRIBUTING.md` is intentionally left as upstream Cinny's — not a Lotus concern.)
- **Architecture notes (low priority):** deep `features/` + `hooks/` nesting, many small coupled hooks, possible dead CSS/components, `SpacingVariant` / `DropTarget` recipe simplification.
- **Git workflow (forward-looking):** keep commits scoped — past monolithic "fix all bugs" commits and inconsistent prefixes hurt `git bisect`.

### Big Projects

- ~~**#5 — Seasonal themes & chat-background redesign.**~~ **DONE (2026-06/07):** 11 seasonal/holiday overlays shipped and later toned down + given a settings preview grid; all 19 chat backgrounds redesigned (Carbon + Aurora kept per user preference), one design sprint each, GPU-friendly CSS with `prefers-reduced-motion` + pause toggle. Remaining polish rides normal bug flow, not a "big project."