LOTUS_TODO_REFERENCE.md

# Lotus Chat — Implementation Reference for Backlog

**Date:** June 2026

This document provides technical guidance, file paths, and architectural notes for unimplemented items in `LOTUS_TODO.md` to assist engineers during development.

---

## 🧵 Priority 3 — Higher Complexity

### P3-8 · Thread Panel (Full Side Drawer)

**⚠️ Largest Feature**

- **Objective:** Add a right-side drawer to view and reply to threads (`m.thread` relations).
- **Key Files to Reference:**
  - `src/app/features/room/RoomView.tsx`: Main layout. Needs to render the new `ThreadPanel` component conditionally.
  - `src/app/features/room/MembersDrawer.tsx`: Use this as a pattern for side drawers (fixed width, toggleable).
  - `src/app/features/room/message/Message.tsx`: Check `isThreadedMessage` logic and the `onReplyClick(ev, true)` handler.
- **Architecture:**
  - Create `activeThreadEventIdAtom` in a new state file.
  - `ThreadPanel` should reuse `Timeline` components but filter for events where `m.relates_to.event_id === activeThreadEventId` and `rel_type === 'm.thread'`.
  - **SDK API:** Use `mx.getThread(eventId)` or the aggregations API: `GET /rooms/{roomId}/relations/{eventId}/m.thread`.
- **Note:** `RoomTimeline.tsx` currently has `handleReplyClick` (Line 978) which already supports starting threads.

---

## 🛠️ Priority 4 — Specialized Features

### P4-3 · Knock-to-join Notifications for Admins

- **Objective:** Alert admins when users are knocking and provide an easy way to approve/deny.
- **Key Files:**
  - `src/app/features/room/MembersDrawer.tsx`: Already contains logic to show "Pending Requests" (Line 412).
  - `src/app/hooks/useRoomsNotificationPreferences.ts`: Add logic to detect `Membership.Knock` events in joined rooms where the user has invite permissions.
- **Implementation:**
  - Create a hook `usePendingKnocks(room)` that returns `room.getMembersWithMembership(Membership.Knock)`.
  - Add a notification badge to the "Members" icon in the room header if knocks > 0.

### P4-4 · Math / LaTeX Rendering

- **Objective:** Render `$...$` and `$$...$$` blocks using KaTeX.
- **Key Files:**
  - `src/app/utils/sanitize.ts`: **Critical.** The sanitizer currently strips many tags. You must allow specific KaTeX/MathML outputs.
  - `src/app/plugins/react-custom-html-parser.ts`: Add a custom rule to detect LaTeX patterns in plain text or handle the specific HTML from the server.
  - `src/app/styles/CustomHtml.css.ts`: Add KaTeX CSS import/styles.

---

## 🎨 Priority 5 — Gamer / Aesthetic / Customization

### P5-1 · Custom Accent Color Picker

- **Objective:** User-defined accent color for non-TDS themes.
- **Key Files:**
  - `src/app/hooks/useTheme.ts`: Central theme logic.
  - `src/app/state/settings.ts`: Add `customAccentColor: string` to the settings atom.
- **Implementation:**
  - Inject a `<style>` block into `<head>` that overrides CSS variables.
  - **Variables to target:** `--lt-accent-orange`, `--lt-accent-cyan`, `--lt-accent-green` (or their non-TDS equivalents in `folds`).

### P5-10 · Voice Channel User Limit

- **Objective:** Prevent joining a voice channel if the user limit is reached.
- **Key Files:**
  - `src/app/features/call/CallView.tsx`: Join logic site.
- **Implementation:**
  - In `CallPrescreen` (Line 77), retrieve the `io.lotus.voice_limit` state event from the room.
  - Compare `callMembers.length` with the `max_users` value from the event content.
  - If current members >= limit, disable the `canJoin` flag and display a "Channel Full" message.

### P5-13 · Avatar Frame / Border Decorations

- **Objective:** Add cosmetic frames around user avatars.
- **Key Files:**
  - `src/app/components/user-avatar/UserAvatar.tsx`: Rendering site.
- **Implementation:**
  - Add an optional `frameName` prop to the `UserAvatar` component.
  - Since `folds` components like `AvatarImage` are restrictive, wrap the entire return value (both fallback and image paths) in a new `Box` container that applies the frame/glow effects via CSS.

### P5-21 · Custom @Mention Highlight Color

- **Objective:** Persistent background highlight for messages that mention the user.
- **Key Files:**
  - `src/app/components/message/layout/layout.css.ts`: Styling site.
  - `src/app/features/room/message/Message.tsx`: Logic site.
- **Implementation:**
  - In `layout.css.ts`, add a `mention` variant to the `MessageBase` recipe that sets a static `backgroundColor`.
  - In `Message.tsx`, pass the `isMentioned` boolean (Line 800) into the `MessageBase` component as a new prop to trigger the highlight variant.

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

- **Objective:** Inline reply in OS notifications.
- **Key Files:**
  - `src/sw.ts`: Handle the `notificationclick` event.
- **Implementation:**
  - Check for `event.reply` in the service worker.
  - Use the `accessToken` and `baseUrl` stored in the `sessions` map (already implemented in `sw.ts`) to send a Matrix message via `fetch` directly from the Service Worker.
  - **Crucial:** Ensure the message is sent as a relation if the notification was for a thread.

---

## 🧪 Pending Audits Guidance

### Audit-3 · Profile Banner Image

- **Task:** Check if MSC4133 or Matrix v1.16 defines a banner field.
- **Update:** Matrix spec does not currently have a stable `m.banner` field. Most clients use `org.matrix.msc4133.banner_url` (unstable).
- **Recommendation:** Use `mx.http.authedRequest` to experiment with this field on `matrix.lotusguild.org`.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00			`# Lotus Chat — Implementation Reference for Backlog`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00			`Date: June 2026`

			This document provides technical guidance, file paths, and architectural notes for unimplemented items in `LOTUS_TODO.md` to assist engineers during development.

			`---`

			`## 🧵 Priority 3 — Higher Complexity`

			`### P3-8 · Thread Panel (Full Side Drawer)`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00			`⚠️ Largest Feature`

fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00			- Objective: Add a right-side drawer to view and reply to threads (`m.thread` relations).
			`- Key Files to Reference:`
			- `src/app/features/room/RoomView.tsx`: Main layout. Needs to render the new `ThreadPanel` component conditionally.
			- `src/app/features/room/MembersDrawer.tsx`: Use this as a pattern for side drawers (fixed width, toggleable).
			- `src/app/features/room/message/Message.tsx`: Check `isThreadedMessage` logic and the `onReplyClick(ev, true)` handler.
			`- Architecture:`
			- Create `activeThreadEventIdAtom` in a new state file.
			- `ThreadPanel` should reuse `Timeline` components but filter for events where `m.relates_to.event_id === activeThreadEventId` and `rel_type === 'm.thread'`.
			- SDK API: Use `mx.getThread(eventId)` or the aggregations API: `GET /rooms/{roomId}/relations/{eventId}/m.thread`.
			- Note: `RoomTimeline.tsx` currently has `handleReplyClick` (Line 978) which already supports starting threads.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`---`

			`## 🛠️ Priority 4 — Specialized Features`

			`### P4-3 · Knock-to-join Notifications for Admins`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: Alert admins when users are knocking and provide an easy way to approve/deny.`
			`- Key Files:`
			- `src/app/features/room/MembersDrawer.tsx`: Already contains logic to show "Pending Requests" (Line 412).
			- `src/app/hooks/useRoomsNotificationPreferences.ts`: Add logic to detect `Membership.Knock` events in joined rooms where the user has invite permissions.
			`- Implementation:`
			- Create a hook `usePendingKnocks(room)` that returns `room.getMembersWithMembership(Membership.Knock)`.
			`- Add a notification badge to the "Members" icon in the room header if knocks > 0.`
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`### P4-4 · Math / LaTeX Rendering`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			- Objective: Render `$...$` and `$$...$$` blocks using KaTeX.
			`- Key Files:`
			- `src/app/utils/sanitize.ts`: Critical. The sanitizer currently strips many tags. You must allow specific KaTeX/MathML outputs.
			- `src/app/plugins/react-custom-html-parser.ts`: Add a custom rule to detect LaTeX patterns in plain text or handle the specific HTML from the server.
			- `src/app/styles/CustomHtml.css.ts`: Add KaTeX CSS import/styles.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`---`

			`## 🎨 Priority 5 — Gamer / Aesthetic / Customization`

			`### P5-1 · Custom Accent Color Picker`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: User-defined accent color for non-TDS themes.`
			`- Key Files:`
			- `src/app/hooks/useTheme.ts`: Central theme logic.
			- `src/app/state/settings.ts`: Add `customAccentColor: string` to the settings atom.
			`- Implementation:`
			- Inject a `<style>` block into `<head>` that overrides CSS variables.
			- Variables to target: `--lt-accent-orange`, `--lt-accent-cyan`, `--lt-accent-green` (or their non-TDS equivalents in `folds`).
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`### P5-10 · Voice Channel User Limit`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: Prevent joining a voice channel if the user limit is reached.`
			`- Key Files:`
			- `src/app/features/call/CallView.tsx`: Join logic site.
			`- Implementation:`
			- In `CallPrescreen` (Line 77), retrieve the `io.lotus.voice_limit` state event from the room.
			- Compare `callMembers.length` with the `max_users` value from the event content.
			- If current members >= limit, disable the `canJoin` flag and display a "Channel Full" message.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`### P5-13 · Avatar Frame / Border Decorations`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: Add cosmetic frames around user avatars.`
			`- Key Files:`
			- `src/app/components/user-avatar/UserAvatar.tsx`: Rendering site.
			`- Implementation:`
			- Add an optional `frameName` prop to the `UserAvatar` component.
			- Since `folds` components like `AvatarImage` are restrictive, wrap the entire return value (both fallback and image paths) in a new `Box` container that applies the frame/glow effects via CSS.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`### P5-21 · Custom @Mention Highlight Color`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: Persistent background highlight for messages that mention the user.`
			`- Key Files:`
			- `src/app/components/message/layout/layout.css.ts`: Styling site.
			- `src/app/features/room/message/Message.tsx`: Logic site.
			`- Implementation:`
			- In `layout.css.ts`, add a `mention` variant to the `MessageBase` recipe that sets a static `backgroundColor`.
			- In `Message.tsx`, pass the `isMentioned` boolean (Line 800) into the `MessageBase` component as a new prop to trigger the highlight variant.
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`### P5-20 · Quick Reply from Browser Notification`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Objective: Inline reply in OS notifications.`
			`- Key Files:`
			- `src/sw.ts`: Handle the `notificationclick` event.
			`- Implementation:`
			- Check for `event.reply` in the service worker.
			- Use the `accessToken` and `baseUrl` stored in the `sessions` map (already implemented in `sw.ts`) to send a Matrix message via `fetch` directly from the Service Worker.
			`- Crucial: Ensure the message is sent as a relation if the notification was for a thread.`
docs: add feature reference, bug tracker, and implementation notes 2026-06-09 18:35:59 -04:00
			`---`

			`## 🧪 Pending Audits Guidance`

			`### Audit-3 · Profile Banner Image`
fix: ESLint errors and Prettier formatting 2026-06-10 22:55:32 -04:00
			`- Task: Check if MSC4133 or Matrix v1.16 defines a banner field.`
			- Update: Matrix spec does not currently have a stable `m.banner` field. Most clients use `org.matrix.msc4133.banner_url` (unstable).
			- Recommendation: Use `mx.http.authedRequest` to experiment with this field on `matrix.lotusguild.org`.