docs: add feature reference, bug tracker, and implementation notes

- LOTUS_FEATURES.md: full reference of every custom Lotus feature with implementation details, file paths, and API notes - LOTUS_BUGS.md: audit of confirmed bugs with root causes and fixes - LOTUS_TODO_REFERENCE.md: technical implementation notes for backlog items - LOTUS_TODO.md: trim completed audit results section, link to FEATURES doc - README.md: rewrite to marketing-friendly feature list format; fix incorrect claim that screenshare auto-reverts view to grid (removed) Fix: auto-revert spotlight on screenshare was removed (600ms grid-click caused fullscreen to show avatars); corrected in LOTUS_FEATURES.md and removed from README.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-09 18:35:59 -04:00
parent 7e4178f7e2
commit ea15db430c
5 changed files with 1192 additions and 1160 deletions
@@ -0,0 +1,146 @@
+# Lotus Chat — Bug Report & Technical Audit
+**Date:** June 2026
+
+This document tracks identified bugs, edge cases, and architectural discrepancies found during the audit of the Lotus Chat codebase. Recommended fixes are provided for each item.
+
+---
+
+## 🚩 Critical & UI Bugs
+
+### 1. Drag-and-Drop Overlay Persistence
+**File:** `src/app/hooks/useFileDrop.ts`
+**Status:** Confirmed (Backlog item #!BUG)
+
+*   **Issue:** The file drop overlay remains visible if a user drags a file over the browser window and then moves the mouse out of the window without dropping.
+*   **Root Cause:** The `dragleave` event does not reliably decrement the internal `dragCounter` when the mouse leaves the browser viewport entirely.
+*   **Recommended Fix:** Update the `handleDragLeave` function to detect when the mouse has left the window by checking if `evt.relatedTarget` is null.
+
+### 2. Stale Member List in Verification Banner
+**File:** `src/app/hooks/useDeviceVerificationStatus.ts`
+**Status:** High Priority
+
+*   **Issue:** The "Unverified Device Warning" banner may fail to appear for users who join a room after it has already been opened in the client.
+*   **Root Cause:** The `memberIds` array is memoized only on `room.roomId`. New members joining the room do not trigger a recalculation of the list, meaning their devices are never checked.
+*   **Recommended Fix:** Add the room's joined member count to the memoization dependencies.
+
+### 3. Night Light Overlay Coverage (Portal Issue)
+**File:** `src/app/pages/App.tsx`
+**Status:** UI Consistency
+
+*   **Issue:** The Night Light (blue light filter) overlay is rendered inside the `#root` div. However, Cinny's modals, tooltips, and popouts are rendered inside a sibling `#portalContainer`.
+*   **Impact:** Modals and tooltips will appear at full brightness, bypassing the filter.
+*   **Recommended Fix:** Move the `NightLightOverlay` component to the end of `document.body` or utilize a Portal to render it inside `#portalContainer` with a high z-index (e.g., 9999).
+
+### 4. Decrypted Media Memory Leak (Gallery & Lightbox)
+**File:** `src/app/features/room/MediaGallery.tsx`
+**Status:** Performance / Memory
+
+*   **Issue:** Every image in the gallery history is decrypted and converted to a Blob URL simultaneously.
+*   **Impact:** Scrolling through long room histories can consume gigabytes of RAM, as Blob URLs are not revoked until the gallery is closed.
+*   **Recommended Fix:** Implement virtualization for the gallery grid. Only decrypt and create URLs for items currently in or near the viewport.
+
+---
+
+## 🎨 UI/UX & Visual Consistency
+
+### 1. Search Button Hidden in E2EE Rooms
+**File:** `src/app/features/room/RoomViewHeader.tsx`
+**Status:** Major UX Regression
+
+*   **Issue:** The message search icon is hidden in encrypted rooms.
+*   **Impact:** Users cannot access the "Encrypted Room Search" feature (local cache scan) from the room header, even though the feature is implemented and functional in the search page.
+*   **Recommended Fix:** Remove the `!encryptedRoom` condition from the Search button renderer in the header.
+
+### 2. TDS Design Law Violations (Hardcoded Hex)
+**Files:** `src/app/components/GifPicker.tsx`, `src/app/components/VoiceMessageRecorder.tsx`
+**Status:** Styling Integrity
+
+*   **Issue:** Multiple custom components use hardcoded hex values (e.g., `#FF6B00`, `#060c14`) instead of the CSS variables defined in `lotus-terminal.css.ts`.
+*   **Impact:** These components will not adapt if theme tokens are updated in the central TDS file, and they bypass the "Design Law" established in the backlog.
+*   **Recommended Fix:** Replace all hardcoded hex values with `var(--lt-accent-orange)`, `var(--lt-bg-secondary)`, etc.
+
+### 3. Missing CSS Variable `--bg-surface-variant`
+**Files:** `src/app/features/message-search/MessageSearch.tsx`, `src/app/components/VoiceMessageRecorder.tsx`
+**Status:** UI Bug
+
+*   **Issue:** Components use `var(--bg-surface-variant)`, which is not defined in either `index.css` or `lotus-terminal.css.ts`.
+*   **Impact:** Backgrounds for the voice recorder and search cache panels appear transparent or fall back to browser defaults.
+*   **Recommended Fix:** Define `--bg-surface-variant` in both global themes and the TDS theme, or switch to using `--bg-surface-low`.
+
+### 4. Recent vs. Top Emoji Logic Discrepancy
+**File:** `src/app/plugins/recent-emoji.ts`
+**Status:** Logic Inconsistency
+
+*   **Issue:** The "Quick Reactions" hover bar is described as showing the "3 most recently used emojis." However, the implementation sorts by `usage count`, meaning it actually shows the "most frequently used" emojis.
+*   **Impact:** If a user uses a new emoji, it will not appear in the quick reactions until its total usage count exceeds the current top 3. This contradicts user expectations for a "recently used" list.
+*   **Recommended Fix:** Update `getRecentEmojis` to sort by the order in the array (which is unshifted in `addRecentEmoji`) or add a timestamp to each emoji entry in the account data to allow true chronological sorting.
+
+---
+
+## 🔍 Technical Refinements
+
+### 1. Incomplete Python Comment Highlighting
+**File:** `src/app/utils/syntaxHighlight.ts`
+**Status:** Medium Priority
+
+*   **Issue:** Python comments (`#`) are only highlighted if they appear at the very start of a line. Inline comments like `print("hello") # comment` are treated as plain text.
+*   **Recommended Fix:** Update the detection logic to allow `#` after whitespace or tabs.
+
+```typescript
+// Recommended
+(i === 0 || code[i - 1] === '\n' || code[i - 1] === ' ' || code[i - 1] === '\t')
+```
+
+### 2. Duplicate Bookmarking Race Condition
+**File:** `src/app/hooks/useBookmarks.ts`
+**Status:** Data Integrity
+
+*   **Issue:** Rapidly clicking the bookmark button can trigger multiple `setAccountData` calls that read from the same stale local cache, potentially overwriting each other.
+*   **Recommended Fix:** Implement a queue or locking mechanism for account data updates to ensure atomicity.
+
+### 3. Presence Updater Matrix Base URL Access
+**File:** `src/app/hooks/usePresenceUpdater.ts`
+**Status:** Best Practice
+
+*   **Issue:** The code uses a hacky cast: `(mx as unknown as { baseUrl: string }).baseUrl`.
+*   **Recommended Fix:** Use the standard SDK method `mx.getHomeserverUrl()`.
+
+### 4. Encrypted Search Misses Historic Events
+**File:** `src/app/features/message-search/useLocalMessageSearch.ts`
+**Status:** Functional Limitation
+
+*   **Issue:** The search only scans `room.getLiveTimeline().getEvents()`.
+*   **Impact:** If a user has scrolled back and loaded historic messages into linked timelines, those messages will be ignored by the search.
+*   **Recommended Fix:** Iterate through all timelines in the room's primary `TimelineSet` using `room.getUnfilteredTimelineSet().getTimelines()`.
+
+### 5. useAccountDataCallback Memoization Risk
+**File:** `src/app/hooks/useAccountDataCallback.ts`
+**Status:** Maintenance Risk
+
+*   **Issue:** The hook attaches/detaches a Matrix event listener every time the `onAccountData` callback changes. If a component using this hook does not memoize the callback (via `useCallback`), the listener will be churned on every render.
+*   **Impact:** Potential performance degradation and subtle event-handling bugs if listeners are added/removed multiple times per second.
+*   **Recommended Fix:** Add a JSDoc warning to the hook file instructing developers to always wrap the callback in `useCallback`.
+
+---
+
+## 📝 Documentation & Accessibility
+
+### 1. Documentation Discrepancy (EC Spotlight)
+**Files:** `LOTUS_FEATURES.md` vs `matrix/README.md`
+
+*   **Issue:** `LOTUS_FEATURES.md` claims there is an "Auto-revert spotlight on screenshare" feature. `matrix/README.md` correctly states this was **removed** as it broke fullscreen views.
+*   **Action:** Update `LOTUS_FEATURES.md` to remove the mention.
+
+### 2. Presence Badge Accessibility
+**File:** `src/app/components/presence/Presence.tsx`
+**Status:** Accessibility
+
+*   **Issue:** `aria-labelledby` refers to a Tooltip ID that may not be in the DOM when the badge is first read by a screen reader.
+*   **Recommended Fix:** Add a descriptive `aria-label` directly to the `Badge` component (e.g., `aria-label="Status: Online"`).
+
+### 3. Missing Status Tooltip on Text
+**File:** `src/app/features/room/MembersDrawer.tsx`
+**Status:** UX Improvement
+
+*   **Issue:** In the members drawer, the status message text is truncated but does not have a tooltip. The tooltip only exists on the small presence dot.
+*   **Recommended Fix:** Wrap the status text in a `TooltipProvider` to allow users to read long status messages.
@@ -0,0 +1,776 @@
+# Lotus Chat — Feature Reference
+
+Everything added to Lotus Chat beyond upstream Cinny v4.12.1.
+Last updated: June 2026.
+
+---
+
+## Table of Contents
+
+1. [Branding & Identity](#branding--identity)
+2. [LotusGuild Terminal Design System (TDS) v1.2](#lotusguild-terminal-design-system-tds-v12)
+3. [Animated Chat Backgrounds (P5-4)](#animated-chat-backgrounds-p5-4)
+4. [Glassmorphism Sidebar (P5-3)](#glassmorphism-sidebar-p5-3)
+5. [Night Light / Blue Light Filter (P5-5)](#night-light--blue-light-filter-p5-5)
+6. [Voice / Video Call Improvements](#voice--video-call-improvements)
+7. [Per-Message Read Receipts](#per-message-read-receipts)
+8. [Delivery Status Indicators](#delivery-status-indicators)
+9. [Messaging Enhancements](#messaging-enhancements)
+10. [Presence](#presence)
+11. [UX & Composer](#ux--composer)
+12. [Room Customization](#room-customization)
+13. [Moderation](#moderation)
+14. [Notifications](#notifications)
+15. [Server Integration](#server-integration)
+16. [Infrastructure](#infrastructure)
+17. [Key Custom Files](#key-custom-files)
+
+---
+
+## Branding & Identity
+
+- Package renamed to `lotus-chat`; description updated in `package.json`
+- App title set to "Lotus Chat" throughout (window title, meta tags, manifest)
+- Favicon, PWA icons (all sizes), and Apple touch icons replaced with `Lotus.png`
+- Lotus logo displayed in the About dialog and Auth page
+- Auth footer: dynamic version pulled from `package.json`; links to `lotusguild.org`, `chat.lotusguild.org`, and `matrix.lotusguild.org`
+- Welcome page tagline: "A Matrix client for Lotus Guild"
+- Encryption key export filename changed to `lotus-keys.txt`
+- `manifest.json` updated with Lotus name, description, and branding colors
+
+---
+
+## LotusGuild Terminal Design System (TDS) v1.2
+
+### Dark Mode — `LotusTerminalTheme`
+
+A CRT terminal aesthetic applied globally when the TDS theme is active.
+
+**Visual effects:**
+- Scanline overlay via repeating `linear-gradient` pseudo-element
+- Vignette via radial-gradient overlay
+- Phosphor glow on text and accents via `text-shadow` / `box-shadow`
+
+**Color palette:**
+| Token | Value | Role |
+|---|---|---|
+| `--lt-bg` | `#030508` | Page/panel background |
+| `--lt-accent-orange` | `#FF6B00` | Primary accent |
+| `--lt-accent-cyan` | `#00D4FF` | Secondary accent |
+| `--lt-accent-green` | `#00FF88` | Success / active states |
+| `--lt-text` | `#c4d9ee` | Body text |
+
+**Typography & chrome:**
+- Monospace font stack applied to all UI elements
+- Terminal-style scrollbars (thin, accent-colored track)
+
+**Decorative patterns:**
+- Custom hex-grid CSS background pattern
+- Circuit-board CSS background pattern (switchable)
+
+**Boot sequence:**
+- Matrix-style boot messages on the welcome page; press Escape to skip
+- Implemented in `src/lotus-boot.ts`
+
+**CSS variable family:** all custom tokens use the `--lt-*` prefix, defined in `src/lotus-terminal.css.ts`.
+
+### Light Mode — `LotusTerminalLightTheme`
+
+A full light-palette counterpart to the dark TDS theme.
+
+**Color palette:**
+| Token | Light Value | Role |
+|---|---|---|
+| `--lt-bg` | `#edf0f5` | Page/panel background |
+| `--lt-accent-orange` | `#c44e00` | Primary accent |
+| `--lt-accent-cyan` | `#0062b8` | Secondary accent |
+| `--lt-accent-green` | `#006d35` | Success / active states |
+| `--lt-text` | `#111827` | Body text |
+
+**Differences from dark mode:**
+- CRT effects (scanlines, vignette, phosphor glow) are disabled
+- Scoped to `html[data-theme="light"] body.lotusTerminalBodyClass` to avoid bleed into non-TDS themes
+- `ThemeManager.tsx` is responsible for setting the `data-theme` attribute on the `<html>` element when theme changes
+
+### Chat Background Patterns (20+ static)
+
+A library of CSS-only background patterns for the chat area, all using CSS custom properties so they adapt automatically to both TDS dark and light palettes:
+
+- Blueprint grid
+- Carbon fiber
+- Starfield
+- Topographic contours
+- Herringbone
+- Crosshatch
+- Chevron
+- Polka dots
+- Triangles
+- Plaid
+- (and additional variants)
+
+---
+
+## Animated Chat Backgrounds (P5-4)
+
+Five CSS-only animated wallpapers implemented with vanilla-extract keyframes. No `<canvas>` element is used — all animation is pure CSS.
+
+### Available Animations
+
+**Digital Rain**
+Two-layer vertical stripe scroll with parallax effect. Wide stripes animate at 8s, narrow stripes at 4s, creating depth.
+
+**Star Drift**
+Three-layer radial-gradient dot field drifting diagonally across the viewport. Each layer moves at a distinct speed and angle.
+
+**Grid Pulse**
+Neon grid lines that expand and contract via a `backgroundSize` keyframe. Grid color follows `--lt-accent-cyan` in dark mode.
+
+**Aurora Flow**
+Four radial-gradient ellipses sweeping across a 200% canvas. Colors use the TDS green/cyan/orange palette and blend softly.
+
+**Fireflies**
+Three layers of warm glowing dots that drift slowly. Dot color follows `--lt-accent-orange` for a warm bioluminescent feel.
+
+### API
+
+```ts
+getChatBg(bg: ChatBg, isDark: boolean, pauseAnimations?: boolean): CSSProperties
+```
+
+Strips all `animation` properties from the returned style object when either `pauseAnimations` is `true` or the `prefers-reduced-motion: reduce` media query is active.
+
+### Settings Integration
+
+A "Pause Background Animations" toggle is exposed in **Settings → Appearance**. The preference is persisted and read by `getChatBg()` at render time.
+
+### Files
+
+- `src/app/styles/Animations.css.ts` — vanilla-extract keyframe definitions
+- `src/app/features/lotus/chatBackground.ts` — `getChatBg()` implementation and pattern registry
+
+---
+
+## Glassmorphism Sidebar (P5-3)
+
+An optional frosted-glass sidebar style toggled in **Settings → Appearance**.
+
+**Implementation:**
+- `SidebarGlass` vanilla-extract class applies `background: rgba(3, 5, 8, 0.55)` and `backdropFilter: blur(12px)` to the sidebar element
+- `SidebarNav.tsx` uses a `useEffect` to mirror the active chat background onto `document.body` when the glassmorphism setting is enabled, so the blur filter has meaningful content to work through
+- Degrades gracefully on browsers without `backdrop-filter` support (falls back to the semi-transparent background)
+
+---
+
+## Night Light / Blue Light Filter (P5-5)
+
+A warm orange overlay rendered over the entire UI to reduce blue light emission.
+
+**Implementation:**
+- `NightLightOverlay` component mounted directly in `App.tsx`
+- CSS: `position: fixed; inset: 0; pointer-events: none; z-index: 9998`
+- Orange tint color with configurable opacity
+- **Controls:** Toggle to enable/disable + intensity slider ranging from 5% to 80% opacity
+- Settings persisted via the standard Lotus settings store
+
+---
+
+## Voice / Video Call Improvements
+
+### Element Call Upgrade
+
+Upgraded embedded Element Call widget from **0.16.3** to **0.19.4**.
+
+### Camera Default Off
+
+Camera starts disabled on join. The `cameraOnJoin` setting is explicitly opt-in and is not persisted to `localStorage` between sessions, preventing the previous behavior where a prior-session preference could unexpectedly enable the camera.
+
+### UI Fixes
+
+- **Deafen button** — corrected tooltip text that was previously swapped with the mute tooltip
+- **Screenshare confirmation** — a confirmation dialog is shown before initiating a screenshare broadcast to the room
+- **Auto-revert spotlight on screenshare** — removed; the 600ms grid-revert click was causing fullscreen screenshare to show avatar tiles instead of the screen. EC now handles layout natively.
+
+### Push to Talk (PTT)
+
+- Configurable keybind; defaults to `Space`
+- Visual indicator shown in both TDS and non-TDS themes while PTT is active
+- Event listener attached to both the main window and the Element Call iframe's `contentWindow` to ensure reliable capture regardless of focus
+- Mic state is preserved correctly when switching into or out of PTT mode
+
+### Push to Deafen
+
+`M` key triggers `toggleSound()` in `CallControls.tsx`, toggling the deafen state without requiring a mouse click.
+
+### Noise Suppression Toggle
+
+A `noiseSuppression` URL parameter is passed to the Element Call widget URL, allowing the noise suppression feature to be toggled from within Lotus settings.
+
+### Call Button Scoping
+
+The call button is shown only in DMs and invite-only rooms that do not have an `m.space.parent` event. It is hidden in public rooms and space channels to avoid accidental broadcast calls.
+
+### Picture-in-Picture (PiP)
+
+- 280×158px floating window that stays on screen when navigating away from the call room
+- Draggable via pointer events with a 5px movement threshold to distinguish drags from clicks; touch events are supported
+- Clicking the PiP window navigates back to the call room
+- Implemented with an imperative `useEffect` style for position overrides because `useCallEmbedPlacementSync` writes geometry directly onto the DOM element, making declarative approaches unreliable
+
+### Call Embed Positioning
+
+- Uses `getBoundingClientRect()` (viewport-relative) instead of the previous `offsetTop`/`offsetLeft` (parent-relative) calculations, fixing misalignment in scrolled layouts
+- Position is synced on mount via `useEffect` with a `ResizeObserver` to handle dynamic layout changes
+
+### Dark Mode in Element Call
+
+`applyStyles()` injects `:root { color-scheme: dark | light }` into the Element Call iframe after the user joins. The theme is also updated when `setTheme()` is called, keeping the call UI in sync with the Lotus theme selection.
+
+### Call Embed Wallpaper
+
+The active `chatBackground` pattern is applied to the `div[data-call-embed-container]` wrapper. The iframe's `html, body` are forced to `background: none !important` so the host pattern shows through.
+
+### TDS Typing Indicator
+
+The animated typing indicator dots use `var(--lt-accent-orange)` as their color when the TDS theme is active, matching the terminal aesthetic.
+
+---
+
+## Per-Message Read Receipts
+
+A full per-message read receipt system showing exactly who has seen each message.
+
+### Core Hook — `useRoomReadPositions`
+
+```ts
+useRoomReadPositions(room: Room): Map<eventId, userId[]>
+```
+
+- Listens to `Room.localEchoUpdated` and `RoomMember.typing` events to stay reactive
+- Debounced 150ms to avoid excessive re-renders during rapid receipt updates
+- Located at `src/app/hooks/useRoomReadPositions.ts`
+
+### `nearestRenderableId()`
+
+A utility that walks backward through the event timeline from a given event ID to find the nearest event that is actually rendered (skipping reactions, edits, and other non-display events). Used to map a user's read position to a visible message.
+
+### `ReadPositionsContext`
+
+React context at `src/app/features/room/ReadPositionsContext.ts` that provides the positions map to all timeline components without prop drilling.
+
+### `ReadReceiptAvatars`
+
+A pill of overlapping 24px user avatars displayed at the bottom-right of each message. Shows a maximum of 5 avatars; additional readers are shown as an overflow count (e.g., `+3`).
+
+### "Seen by" Modal — `EventReaders`
+
+Clicking the avatar pill opens a modal (`src/app/components/event-readers/EventReaders.tsx`) listing:
+- User avatar
+- Display name
+- Formatted timestamp of when the receipt was recorded
+- Respects the `hour24Clock` setting for timestamp formatting
+
+---
+
+## Delivery Status Indicators
+
+Visual feedback on message delivery state, shown on the sender's own messages:
+
+| State | Indicator |
+|---|---|
+| Sending (local echo) | ⟳ rotating clock icon |
+| Sent (server ACK received) | ✓ checkmark |
+| Failed | ✕ in red; orange glow in TDS |
+
+The indicator is hidden once the server confirms the event (when the internal status transitions to `null`), keeping the timeline clean for settled messages.
+
+---
+
+## Messaging Enhancements
+
+### Rich Room Topics
+
+- Topic `formatted_body` is rendered via `sanitizeCustomHtml` + `html-react-parser`, supporting bold, italic, links, and other inline HTML
+- The room header shows a plain-text preview of the topic
+- Clicking the topic preview opens a full modal with the formatted body
+- The room settings topic editor includes a formatting toolbar with **B**, *I*, ~~S~~, and `code` buttons
+
+### Edit History Viewer
+
+`EditHistoryModal.tsx` fetches and displays the full edit history of a message.
+
+- API: `GET /_matrix/client/v1/rooms/{roomId}/relations/{eventId}/m.replace`
+- E2EE fix: the "Original" entry uses `getClearContent()` to retrieve the decrypted content rather than the encrypted payload
+- Accessible from the message context menu
+
+### Inline GIF Preview
+
+- Detects Giphy and Tenor share URLs via pattern matching on the message body
+- Renders matched URLs as `<img loading="lazy">` inline in the message
+- URL is proxied through the Matrix `/_matrix/media/v3/preview_url` endpoint to avoid mixed-content issues
+
+### GIF Picker
+
+- Giphy-powered picker accessible from the composer toolbar
+- The button is only shown when `gifApiKey` is set in `config.json`
+- Selected GIFs are sent as `m.image` events
+- Picker UI is styled with TDS variables when the TDS theme is active
+- Located at `src/app/components/GifPicker.tsx`
+
+### Message Forwarding
+
+Context menu → **Forward** allows forwarding a message to any room the user is a member of.
+
+### Draft Persistence
+
+- Composer drafts are stored in `localStorage` keyed by `roomId`
+- Draft is cleared on successful send
+- The Jotai atom is the primary source of truth; `localStorage` is only read on room mount
+
+### Message Search Date Range
+
+- The search panel accepts `from_ts` and `to_ts` values (epoch milliseconds) passed to the search API
+- A chip shows the active date range with an **×** button to clear it
+
+### Image / Video Captions
+
+Images and videos can be sent with a caption. The caption and media are sent as a single event.
+
+### Location Sharing
+
+`m.location` events render an inline map tile using the coordinates from the event content.
+
+### Deleted Message Placeholders
+
+Redacted events display "This message has been deleted" along with the redaction reason if one was provided, rather than leaving a blank gap in the timeline. This is a one-line change in the `eventRenderer` filter.
+
+### Message Bookmarks
+
+- Bookmarks are stored in `io.lotus.bookmarks` account data, syncing across all devices
+- Maximum of 500 bookmarked entries
+- `BookmarksPanel.tsx` is a sidebar panel accessible from the navigation rail
+- Hook: `src/app/hooks/useBookmarks.ts`
+
+### Message Scheduling
+
+- Implements MSC4140 delayed events for scheduling messages to be sent at a future time
+- `ScheduleMessageModal.tsx` provides the date/time picker UI
+- A collapsible "Scheduled" tray in the room shows all pending scheduled messages with individual cancel buttons
+- Utilities in `src/app/utils/scheduledMessages.ts`
+
+### File Upload Compression (opt-in)
+
+- Implemented in `UploadCardRenderer.tsx`
+- Uses the Canvas API: `canvas.toBlob(callback, 'image/jpeg', 0.82)` for compression
+- A `Switch` toggle in the upload preview UI lets the user opt in per upload
+- Shows before and after file sizes so the user can evaluate the tradeoff
+- Works on all image types except SVG (which cannot be drawn to canvas)
+- On send, the original uncompressed MXC URL is deleted from the media store
+- On cancel, any orphaned MXC from a prior upload is cleaned up via `tryDeleteMxcContent()`
+
+### Richer URL Preview Cards
+
+`UrlPreviewCard.tsx` implements 13 domain-specific card layouts:
+
+| Domain | Layout |
+|---|---|
+| YouTube | Thumbnail, title, channel, duration |
+| Vimeo | Thumbnail, title, author |
+| GitHub | Repo name, description, stars/forks/language |
+| Twitter / X | Avatar, display name, handle, tweet body |
+| Reddit | Subreddit, post title, score, comment count |
+| Spotify | Album art, track/album/playlist name, artist |
+| Twitch | Stream thumbnail, streamer, game, viewer count |
+| Steam | Header image, game name, price, rating |
+| Wikipedia | Article title, extract excerpt |
+| Discord | Server name, invite metadata |
+| npm | Package name, version, description, weekly downloads |
+| Stack Overflow | Question title, vote/answer count, tags |
+| IMDb | Poster, title, year, rating |
+
+Generic (non-domain-specific) cards display a Google S2 favicon. Empty or unparseable preview responses are suppressed entirely rather than showing a blank card.
+
+### Poll Creation
+
+- `PollCreator.tsx` creates stable `m.poll.start` events
+- Supports 2 to 10 answer options
+- Supports both single-choice and multiple-choice modes
+- Accessible via the `Icons.OrderList` button in the composer toolbar
+
+### Poll Display
+
+`PollContent.tsx` renders polls in read-only mode. Handles both the stable `m.poll` format and the legacy MSC3381 unstable `org.matrix.msc3381.poll.start` format. Displays current vote counts and a note directing users to Element to cast votes.
+
+### Voice Message Playback Speed
+
+`AudioContent.tsx` adds a playback speed cycle button to voice message players. Available speeds: `[0.75, 1, 1.5, 2]×`. A `useEffect` sets `audioElement.playbackRate` whenever the speed selection changes.
+
+---
+
+## Presence
+
+### Discord-Style Presence Selector
+
+A presence status selector in the user panel offering five modes:
+
+| Mode | Matrix broadcast |
+|---|---|
+| Online | `online` |
+| Idle | `unavailable` |
+| Do Not Disturb | `unavailable` + `status_msg: 'dnd'` |
+| Invisible | `offline` |
+| Auto | Standard Matrix presence lifecycle |
+
+- Selection persists via the `presenceStatus` setting
+- `usePresenceUpdater` short-circuits its automatic presence updates when a manual mode (anything other than Auto) is selected
+
+### Custom Status Message
+
+- Up to 64 characters of free text plus an emoji
+- Optional auto-clear timer with presets: 30 minutes, 1 hour, 4 hours, 1 day, 3 days, 7 days
+- Status is broadcast via `mx.setPresence({ status_msg: ... })`
+- Character counter appears at 56/64 characters remaining to warn of the limit
+
+### Presence Badges
+
+`PresenceBadge` component displays a colored dot indicating presence state. Used in:
+- Members drawer
+- User settings panel
+
+### Presence Avatar Ring
+
+`PresenceRingAvatar` wraps any avatar component using `React.cloneElement` to inject an `outline: 2px solid` ring whose color maps to the user's presence state. `outlineOffset: 2px` ensures the ring sits cleanly outside the avatar regardless of the avatar's `border-radius`.
+
+Applied in:
+- Message timeline
+- Members drawer
+- `@mention` autocomplete dropdown
+- Inbox / notifications panel
+
+### Document Title Unread Count
+
+The browser tab title updates to reflect unread state:
+- `(N) Lotus Chat` — N unread messages
+- `· Lotus Chat` — unread activity without a specific count
+- `Lotus Chat` — no unread items
+
+### Extended Profile Fields
+
+Supports MSC4133 custom profile fields via `PUT /_matrix/client/unstable/uk.tcpip.msc4133/{userId}/{field}`:
+- `m.pronouns` — displayed in profile panels
+- `m.tz` — IANA timezone string (e.g., `America/New_York`)
+
+Hook: `src/app/hooks/useExtendedProfile.ts`
+
+### User Local Time
+
+When a user has `m.tz` set in their profile:
+- Their profile panel shows a clock icon, their current local time, and the timezone abbreviation
+- The displayed time updates every 60 seconds
+- Respects the global `hour24Clock` setting for 12h/24h formatting
+
+Hook: `src/app/hooks/useLocalTime.ts`
+
+---
+
+## UX & Composer
+
+### Message Length Counter
+
+A character count indicator is shown in the composer when `charCount > 0`. The counter resets to zero when switching rooms.
+
+### Quick Emoji Reactions on Hover
+
+A hover toolbar appears over messages, showing the 3 most recently used emojis (sourced from `ElementRecentEmoji` account data) as one-click reaction buttons. The buttons are positioned between the emoji-board button and the Reply button. Clicking a quick reaction closes any open emoji picker.
+
+### In-App Notification Toasts
+
+`LotusToastContainer.tsx` displays rich in-app notification toasts with:
+- 24px sender avatar
+- Sender display name
+- Message body preview
+- Room name
+- × dismiss button
+- 4-second auto-dismiss timeout
+- Slide-in animation via `@keyframes lotusToastIn`
+
+OS-level notifications are unchanged and still fire when the window is not focused.
+
+### Collapsible Long Messages
+
+Messages exceeding a configurable line threshold are truncated with a "Show more" toggle.
+
+- Default threshold: 20 lines
+- Threshold is configurable in **Settings → Appearance**
+- Uses CSS `max-height` + `overflow: hidden` with a smooth transition
+- Transition is disabled when `prefers-reduced-motion: reduce` is active
+
+### Message Send Animation
+
+A subtle animation plays on the sender's own messages as they appear in the timeline:
+- `transform: scale(0.97) → scale(1)` combined with `opacity: 0.4 → 1`
+- Duration: 0.15s, ease-out
+- Only applied to the current user's outgoing messages
+- Disabled when `prefers-reduced-motion: reduce` is active
+
+### Right-Click Room Context Menu
+
+Right-clicking a room in the sidebar opens a context menu with:
+- **Mute** with a duration submenu: 15 minutes, 1 hour, 8 hours, 24 hours, Indefinite
+- **Copy Room Link** — copies the `matrix.to` URI to clipboard
+- **Mark as Read** — marks all events in the room as read
+- **Leave Room** — with a confirmation step
+- **Room Settings** — opens the room settings panel
+
+### Unverified Device Warning
+
+- Controlled by the `warnOnUnverifiedDevices` setting (off by default)
+- When enabled, a `Warning.Container` banner is displayed above the composer in encrypted rooms that have unverified device sessions
+- The warning is informational only and never blocks sending
+
+### Sidebar Room Filter
+
+A text input at the top of the room list filters rooms by display name in real time. The filter is cleared automatically when switching sidebar tabs.
+
+### DM Last Message Preview
+
+Direct message entries in the sidebar show:
+- A 48-character truncated preview of the last message body
+- A relative timestamp (e.g., "2m ago")
+- Reactivity via `useRoomLatestRenderedEvent`
+- Encrypted messages show "Encrypted message" if decryption fails; successfully decrypted messages show their plaintext preview
+
+### Room Sort Order
+
+The room list sort order can be configured in **Settings → Appearance**:
+- Recent Activity (default)
+- A → Z (alphabetical)
+- Unread First
+
+Persists via the `homeRoomSort` setting.
+
+### Favorite Rooms
+
+- Rooms can be favorited via the `m.favourite` tag (standard Matrix tag)
+- A "Favorites" section appears above the main room list when any rooms are favorited
+- Favorited rooms display a star indicator in the sidebar
+- Favorites sync across all devices via account data
+
+### Invite Link + QR Code
+
+`RoomShareInvite.tsx` provides a shareable invite UI:
+- 160×160px QR code generated via `api.qrserver.com`
+- "Copy Link" button to copy the `matrix.to` URI
+- Also accessible via a toggle button (⊞) in the Invite modal
+
+### Private Read Receipts
+
+A toggle in **Settings → Privacy** switches between sending `m.read` (public receipts) and `m.read.private` (private receipts visible only to the sender and the server).
+
+### Media Gallery
+
+`MediaGallery.tsx` — a right-side drawer for browsing room media.
+
+- Three tabs: **Images**, **Videos**, **Files**
+- Reads already-decrypted events from the room timeline
+- Encrypted images show a lock placeholder rather than an error
+- "Load More" button triggers `mx.paginateEventTimeline()` to fetch older media
+
+### Knock-to-Join
+
+- `RoomIntro.tsx` shows a "Request to Join" button for knock-restricted rooms
+- Clicking sends `mx.knockRoom(roomId)` with an optional reason
+- The members drawer shows a "Pending Requests" section for room admins, listing users who have knocked
+
+### Code Syntax Highlighting (TDS)
+
+`syntaxHighlight.ts` provides TDS-aware syntax highlighting using inline styles derived from `--lt-accent-*` CSS variables. Supported languages: JavaScript, TypeScript, JSX, TSX, Python, Rust. Falls back to ReactPrism for unsupported languages.
+
+### Room Emoji Prefix
+
+A leading emoji in a room name is rendered at 1.15× size in the sidebar for visual hierarchy. An emoji picker button (😊) is added to all room name input fields, prepending the selected emoji to the room name.
+
+---
+
+## Room Customization
+
+### Personal Room Name Overrides
+
+- Users can set a personal display name for any room, stored in `io.lotus.room_names` account data
+- A pencil indicator in the sidebar shows rooms with active overrides
+- Overrides sync across all devices
+- Applied consistently in: room header, sidebar, room intro, and call overlay
+
+### Export Room History
+
+`ExportRoomHistory.tsx` exports a room's message history in three formats:
+
+- **Plain Text** — human-readable transcript
+- **JSON** — raw event data
+- **HTML** — styled, self-contained page
+
+Features:
+- Optional date range filter
+- Progress indicator during export
+- Uses `mx.paginateEventTimeline()` to retrieve history in chunks
+- E2EE-aware: exports decrypted content for rooms the user has keys for
+
+### Room Activity / Mod Log
+
+`RoomActivityLog.tsx` provides a searchable log of administrative events in the room:
+
+- Member join/leave/kick/ban events
+- Power level changes
+- Room name, topic, avatar, and ACL changes
+- Human-readable descriptions for each event type
+- Type filter to narrow results
+- "Load More" button for pagination
+
+### Server ACL Editor
+
+`RoomServerACL.tsx` — UI for editing `m.room.server_acl` state events.
+
+- Separate allow and deny server lists
+- Wildcard validation (e.g., `*.example.com`)
+- "Allow IP literal addresses" toggle
+- Read-only for users without admin power level
+
+### Room Stats / Insights
+
+`RoomInsights.tsx` (not shown by default; accessible as a non-default tab in room settings).
+
+- Top 5 most active members (bar chart by message count)
+- Top 5 most-used reactions
+- Media breakdown by type (images, videos, files)
+- 24-hour activity heatmap showing message volume by hour of day
+
+---
+
+## Moderation
+
+### Report Room
+
+`ReportRoomModal.tsx` provides a UI for reporting a room to the homeserver.
+
+- API: `POST /_matrix/client/v3/rooms/{roomId}/report`
+- Category dropdown for classifying the report
+- Modal auto-closes 1.5 seconds after a successful submission
+- Hidden for rooms the user owns and for server notice rooms
+
+### Policy List / Ban List Viewer
+
+Accessible via **Room/Space Settings → Policy Lists** (admin only).
+
+- Displays the room's subscribed policy lists in read-only format
+- Subscribe (join) and unsubscribe (leave) controls for each list
+- Enforcement is delegated to Draupnir or equivalent tooling; Lotus only manages list membership
+
+---
+
+## Notifications
+
+### Custom Notification Sounds
+
+- `messageSoundId` and `inviteSoundId` settings select from a predefined map
+- Sound options defined in `notificationSounds.ts` as `NOTIFICATION_SOUND_MAP`
+- Preview (▶) buttons in the settings panel let users audition sounds before selecting
+- Separate sound selection for: `notification`, `invite`, `call`, `none`
+
+### Notification Quiet Hours
+
+- Controlled by `quietHoursEnabled`, `quietHoursStart`, and `quietHoursEnd` settings
+- Correctly handles overnight spans (e.g., 22:00 → 07:00)
+- Gates both `notify()` (visual/OS notifications) and `playSound()` (audio alerts)
+- When active, notifications are silently dropped rather than queued
+
+### Full Push Rule Editor
+
+A complete UI for managing Matrix push notification rules:
+
+- Displays rules by kind: `override`, `room`, `sender`, `underride`
+- Enable/disable toggle per rule
+- Delete button for removable rules
+- Add-rule form for creating new `room` and `sender` rules
+
+---
+
+## Server Integration
+
+### Server Support Contact
+
+- Fetches `/.well-known/matrix/support` on the user's homeserver
+- Contact information is displayed in **Settings → Help & About**
+- Styled with TDS cyan when the TDS theme is active
+- Degrades gracefully with no error shown on 404 responses
+
+### Server Notices
+
+`m.server_notice` rooms receive special treatment:
+- A `Chip variant="Warning"` badge reading "Server Notice" is shown in the room header
+- The composer is read-only (no message input)
+- Invite, Report Room, and Room Settings menu items are hidden
+
+---
+
+## Infrastructure
+
+### Authenticated Media
+
+`mxcUrlToHttp()` calls now use the correct argument order for MSC3916 authenticated media:
+
+```ts
+mxcUrlToHttp(mx, mxcUrl, useAuthentication, width, height, 'crop')
+```
+
+The `useAuthentication` parameter was previously mispositioned, causing unauthenticated requests to be sent for media in rooms that required authentication.
+
+### Upstream Tracking
+
+- An `upstream` git remote pointing to `github.com/cinnyapp/cinny` is maintained for merge tracking
+- A daily divergence check runs via `cinny-upstream-check.sh` on LXC 106
+- This enables prompt review of upstream security patches and feature releases
+
+### Rolldown CJS Interop — millify
+
+`src/app/plugins/millify.ts` re-exports `millify` as a named import to bypass the `__toESM` interop bug in the Rolldown bundler, which caused the default export of CJS modules to be undefined at runtime.
+
+### Sentry Noise Filter
+
+`ignoreErrors: ['Request timed out']` is added to `Sentry.init()` to suppress a high-volume, low-signal error caused by transient network conditions. This keeps the Sentry issue queue focused on actionable errors.
+
+### URL Preview Default in Encrypted Rooms
+
+The `encUrlPreview` setting defaults to `true` rather than `false`. A security advisory chip in **Settings → Privacy** explains the tradeoff (the homeserver can see which URLs are being previewed) so users can make an informed choice.
+
+---
+
+## Key Custom Files
+
+| File | Purpose |
+|---|---|
+| `src/lotus-terminal.css.ts` | TDS CSS variable definitions, scanline/vignette effects, dark + light palette tokens |
+| `src/lotus-boot.ts` | Matrix-style boot sequence animation on the welcome page |
+| `src/app/hooks/useRoomReadPositions.ts` | Reactive hook returning `Map<eventId, userId[]>` for per-message read receipts |
+| `src/app/features/room/ReadPositionsContext.ts` | React context providing read positions map to timeline components |
+| `src/app/components/read-receipt-avatars/` | `ReadReceiptAvatars` component — overlapping avatar pill with overflow count |
+| `src/app/components/event-readers/EventReaders.tsx` | "Seen by" modal listing readers with display name and timestamp |
+| `src/app/components/GifPicker.tsx` | Giphy-powered GIF picker, TDS-styled, gated on `gifApiKey` in config |
+| `src/app/features/call/CallControls.tsx` | Push to Deafen (M key), PTT visual indicator, TDS typing dots |
+| `src/app/plugins/call/CallControl.ts` | `onControlMutation()` state tracking, screenshare audio mute logic, call button scoping |
+| `src/app/components/CallEmbedProvider.tsx` | PiP window, draggable overlay, navigate-on-click, imperative geometry sync |
+| `src/app/plugins/call/CallEmbed.ts` | `getBoundingClientRect()`-based embed positioning, ResizeObserver sync, dark mode injection |
+| `src/app/plugins/millify.ts` | Named re-export of `millify` to fix Rolldown `__toESM` CJS interop bug |
+| `src/app/features/room/MediaGallery.tsx` | Images/Videos/Files gallery drawer with pagination and E2EE awareness |
+| `src/app/features/room/PollCreator.tsx` | Poll creation UI for stable `m.poll.start`, single/multiple choice, 2–10 options |
+| `src/app/features/common-settings/general/RoomShareInvite.tsx` | QR code + copy link invite sharing modal |
+| `src/app/utils/syntaxHighlight.ts` | TDS-aware syntax highlighter using `--lt-accent-*` inline styles |
+| `src/app/features/room-settings/ExportRoomHistory.tsx` | Plain Text / JSON / HTML room history export with date range and E2EE support |
+| `src/app/features/room-settings/RoomActivityLog.tsx` | Human-readable mod log for member and state change events |
+| `src/app/features/room-settings/RoomServerACL.tsx` | `m.room.server_acl` editor with allow/deny lists and wildcard validation |
+| `src/app/features/room-settings/RoomInsights.tsx` | Room stats: top members, top reactions, media breakdown, activity heatmap |
+| `src/app/features/bookmarks/BookmarksPanel.tsx` | Bookmarks sidebar panel backed by `io.lotus.bookmarks` account data |
+| `src/app/hooks/useBookmarks.ts` | Hook for reading and mutating the bookmarks account data entry |
+| `src/app/features/room/ScheduleMessageModal.tsx` | MSC4140 delayed event scheduling UI with date/time picker |
+| `src/app/utils/scheduledMessages.ts` | Helpers for creating, listing, and cancelling MSC4140 delayed events |
+| `src/app/hooks/useExtendedProfile.ts` | MSC4133 extended profile fields (`m.pronouns`, `m.tz`) read/write |
+| `src/app/hooks/useLocalTime.ts` | Derives current local time from `m.tz` profile field, updates every 60s |
+| `src/app/components/url-preview/UrlPreviewCard.tsx` | 13 domain-specific URL preview layouts plus generic fallback with favicon |
@@ -0,0 +1,99 @@
+# 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`.
@@ -1,280 +1,149 @@
 # Lotus Chat

-A Matrix client for [Lotus Guild](https://lotusguild.org) — forked from [Cinny](https://github.com/cinnyapp/cinny) v4.12.1.
+A Matrix chat client built for Lotus Guild — fast, private, and packed with the features you actually want.

-Deployed at [chat.lotusguild.org](https://chat.lotusguild.org).
+**Deployed at [chat.lotusguild.org](https://chat.lotusguild.org)** &nbsp;|&nbsp; Forked from [Cinny](https://github.com/cinnyapp/cinny) v4.12.1

 ---

-## Changes from upstream Cinny
+## Features

-### Branding & Identity
+### Messaging

- Package renamed to `lotus-chat`, description updated to "Lotus Chat — Matrix client for Lotus Guild"
- App title changed from "Cinny" to "Lotus Chat" throughout
- Favicon, PWA icons, and all icon sizes (57×57 → 180×180 Apple touch icons) replaced with Lotus.png variants
- Logo in About dialog and Auth page replaced with official Lotus.png
- Auth footer rewritten: shows dynamic version from `package.json`, links to lotusguild.org, chat.lotusguild.org, and matrix.lotusguild.org
- Welcome page tagline changed from "Yet another matrix client" to "A Matrix client for Lotus Guild"
- Encryption key export filename changed from `cinny-keys.txt` to `lotus-keys.txt`
- `manifest.json` updated with Lotus name, description, and branding colors
+- See who has read each message, and track delivery status (sending / sent / failed)
+- Bookmark any message and revisit saved messages from the sidebar
+- Schedule messages to send at a specific time
+- Click "edited" on any message to see the full edit history
+- Drafts are saved automatically and survive page reloads
+- Long messages collapse automatically — click "Read more" to expand
+- Forward messages to other rooms
+- Create and view polls directly in chat
+- Share your location with an inline map embed
+- Add captions to image and video uploads
+- Optionally compress images before uploading — shows before/after file sizes
+- GIF links from Giphy and Tenor auto-preview inline
+- Search for and send GIFs from a built-in GIF picker
+- Control voice message playback speed: 0.75× / 1× / 1.5× / 2×
+- Search messages with a date range filter
+- Room topics support rich formatting (bold, links, italics)
+- Deleted messages show a placeholder instead of disappearing
+- Code blocks highlight syntax for JS/TS, Python, and Rust
+- Rich link preview cards for YouTube, GitHub, Twitter/X, Reddit, Spotify, Twitch, Steam, Wikipedia, Discord, npm, Stack Overflow, and IMDb

-### LotusGuild Terminal Design System (TDS) v1.2
+### Calls & Voice

-A full custom theme engine layered on top of Cinny's vanilla-extract theming:
+- Push to Talk with a configurable keybind (default: Space)
+- Push to Deafen with the M key
+- Camera starts turned off by default when joining a call
+- Screenshare requires confirmation before going live
+- Toggle noise suppression on or off
+- Calls float in a draggable picture-in-picture window when you navigate away
+- Your chat background shows through the call view
+- Dark/light mode inside calls matches your Lotus Chat theme
+- Calls are available in DMs and private groups only — no accidental mass rings

-**Dark mode** (`LotusTerminalTheme`):
- CRT terminal aesthetic: scanline overlay, vignette, phosphor glow
- Palette: bg `#030508`, orange `#FF6B00`, cyan `#00D4FF`, green `#00FF88`, text `#c4d9ee`
- Monospace font stack, terminal-style scrollbars
- Custom hex-grid and circuit-board CSS background patterns
- Matrix-style boot messages on the welcome page (press Escape to skip)
- CSS variables: `--lt-*` family covering colors, glow effects, borders, animations
+### Customization & Appearance

-**Light mode** (`LotusTerminalLightTheme`):
- Full light palette: bg `#edf0f5`, orange `#c44e00`, cyan `#0062b8`, green `#006d35`, text `#111827`
- No CRT effects (scanlines, vignette disabled)
- Light-mode scrollbars, adjusted code block colors, semantic color overrides
- Scoped to `html[data-theme="light"] body.lotusTerminalBodyClass`
- `ThemeManager.tsx` sets `data-theme` attribute based on active theme kind
+- LotusGuild Terminal Design System (TDS) — a CRT terminal-inspired dark theme
+- TDS light mode variant for daytime use
+- 20+ static chat background patterns
+- 5 animated chat backgrounds: Digital Rain, Star Drift, Grid Pulse, Aurora Flow, Fireflies
+- Toggle to pause background animations
+- Glassmorphism sidebar — frosted glass effect that lets the background show through
+- Night Light / blue light filter with an adjustable intensity slider
+- Emoji prefixes on room names render larger in the sidebar (e.g. 🎮 general)
+- Rename any room for yourself only — other members see the original name
+- Emoji picker on all room name inputs

-**Chat Backgrounds** (20+ custom patterns, all TDS-aware):
- Blueprint grid, carbon fiber, starfield, topographic contours, herringbone, crosshatch
- Chevron, polka dots, triangles, plaid
- All patterns use CSS custom properties — adapt to both TDS dark and light themes
- Settings toggle for showing per-message sender profiles
+### Presence & Profile

-### Voice / Video Call Improvements
+- Discord-style presence selector: Online, Idle, Do Not Disturb, Invisible, or Auto
+- Custom status message with emoji and an optional auto-clear timer
+- Colored presence ring on member avatars (green / yellow / red)
+- Profile fields for pronouns and timezone
+- When a user's timezone is set, their current local time appears in their profile
+- Unread count shown in the browser tab title

- **Element Call 0.19.4**: Upgraded from 0.16.3. Dist copied to `public/element-call/` by vite at build time.
- **Camera default OFF**: Camera no longer persists across sessions via localStorage. Always starts disabled. Optional `cameraOnJoin` setting for explicit opt-in.
- **Deafen button**: Tooltip corrected to "Deafen" / "Undeafen" (was "Turn Off Sound" / "Turn On Sound")
- **Screenshare confirmation**: A confirm dialog appears before screenshare is broadcast to call participants
- **Auto-revert spotlight on screenshare**: When someone starts screensharing, EC normally forces all participants into spotlight view. Patched in `CallControl.ts` `onControlMutation()` — detects the screenshare button going `primary` and clicks `gridButton` after 600ms to revert to grid layout. Participants choose to watch screenshare manually.
- **Push to Talk (PTT)**:
-  - Configurable keybind (default: Space) via Settings > General > Calls
-  - Mic activates on keydown, deactivates on keyup; mic muted on tab blur/focus to prevent stuck-on mic
-  - Visual indicator: plain folds `Chip` by default; when LotusGuild TDS is active: orange `PTT — Hold SPACE` / green `● LIVE` in JetBrains Mono
-  - Listens on both main window and EC iframe `contentWindow` for reliable key capture
-  - Implemented via `CallControl.setMicrophone()` public method on the widget bridge
-  - **Mic state preservation**: when enabling PTT mode mid-call, the user's previous mic state is saved and restored when PTT is disabled — prevents unwanted unmute if the user had manually muted before switching to PTT.
- **Noise suppression toggle**: Settings > General > Calls — passes `noiseSuppression` URL parameter to the embedded Element Call widget
- **Call button scoping**: The upstream Cinny 4.12.1 call button (voice + video dropdown) is restricted to DMs and private group chats only. Specifically: direct messages, or invite-only rooms that have no `m.space.parent` state event (i.e. not a space/guild text channel). Public rooms and space channels are excluded to prevent accidental mass-notifications. `Room.tsx` switches to CallView layout when a call embed is active in the current room.
- **Poll display**: `m.poll.start` events (both stable Matrix 1.7 `m.poll` content key and MSC3381 unstable `org.matrix.msc3381.poll.start`) render as read-only poll cards inside the standard message bubble — question and answer options shown. Registered as top-level event renderers AND inside the `EncryptedContent` callback so encrypted polls also display after decryption. "Open in Element to vote" note displayed. Implemented in `PollContent.tsx`.
- **Deleted message placeholder**: Redacted `m.room.message`, `m.room.encrypted`, and `m.sticker` events no longer disappear from the timeline. Instead they reach the existing `RedactedContent` component (trash icon + italic "This message has been deleted" with reason if provided), matching Element, FluffyChat, Commet, and Nheko behaviour. One-line change in the `eventRenderer` filter in `RoomTimeline.tsx`.
- **Picture-in-picture (PiP)**: When navigating away from a call room while in an active call, the call embed shrinks to a 280x158px floating window in the bottom-right corner. The PiP window is **draggable** — drag it anywhere on screen to move it out of the way. Clicking (without dragging) navigates back to the call room. Drag vs click distinguished by a 5px movement threshold; touch drag supported. Imperative style overrides on `callEmbedRef.current` via `useEffect` — a wrapper div cannot be used because `useCallEmbedPlacementSync` writes `top/left/width/height` directly onto that element.
- **Call embed positioning**: `useCallEmbedPlacementSync` uses `getBoundingClientRect()` (not `offsetTop/Left`) for accurate viewport-relative coordinates on the `position:fixed` container. Position is synced immediately on mount via `useEffect` in addition to the ResizeObserver, so the embed is placed correctly the instant the call view renders. The `[pipMode, callVisible]` effect in `CallEmbedProvider` only clears pip-specific styles when actually exiting pip mode — no longer clobbers the position set by `syncCallEmbedPlacement` on every `callVisible` toggle.
- **Dark mode in element-call**: After joining, `CallEmbed.applyStyles()` injects `:root { color-scheme: dark|light }` into the iframe document so `@media (prefers-color-scheme)` rules inside element-call resolve to the correct Cinny theme regardless of the OS system preference. `themeKind` is stored on the `CallEmbed` instance and updated on every `setTheme()` call, so live theme switching also re-injects the CSS. Without this, users with OS light mode would see a white background even when Cinny is in dark mode.
- **Call embed wallpaper**: The user's `chatBackground` pattern (Blueprint, Carbon, Stars…) is applied as the `backgroundImage`/`backgroundColor` of `div[data-call-embed-container]` when the call is in full view (not PiP). The iframe `html, body` is forced to `background: none !important` so the pattern shows through. When `chatBackground` is `none`, behaviour is unchanged.
+### Moderation & Privacy

-### Moderation
+- Report any room to homeserver admins from the room menu
+- View policy lists and ban lists (Draupnir-compatible, read-only)
+- Toggle private read receipts so others can't see when you've read messages
+- Optional warning when an encrypted room contains unverified devices
+- Full push rule editor in notification settings
+- View and edit Server ACL rules in room settings
+- Filterable room activity / mod log (joins, kicks, bans, power level changes, etc.)
+- Room stats and insights panel (active members, top reactions, media breakdown, activity heatmap)
+- Export room history as plain text, JSON, or HTML with optional date range filter

- **Report Room**: A "Report Room" option in the room header menu (⋮) allows users to report a room to homeserver admins with a reason and abuse category (Spam / Harassment / Inappropriate Content / Other). Calls `POST /_matrix/client/v3/rooms/{roomId}/report` (MSC4151, confirmed supported on matrix.lotusguild.org). Implemented in `ReportRoomModal.tsx` with loading/success/error states.
- **Policy List / Ban List Viewer (MSC2313)**: A "Policy Lists" tab in Room / Space Settings (admin-only, power-level gated) shows all subscribed `m.policy.rule.*` rooms and their contents — banned users, banned rooms, and banned servers — each with entity, reason, and recommendation fields. Subscribe (join the policy room) and Unsubscribe (leave) actions are provided. Enforcement remains solely with the Draupnir bot; this UI is a read-only complement.
+### Notifications

-### Messaging Enhancements
+- In-app toast notifications appear bottom-right when the window is focused
+- Custom notification sounds per category (messages, invites)
+- Quiet hours — suppress notifications during a configured time window
+- Click a toast to jump directly to the room or DM

- **Rich room topics**: Room topics that contain formatted text (bold, links, italic) are now rendered with full HTML formatting. Falls back to plain text if no `formatted_body` is present. Activates when any room admin sets a formatted topic.
- **Edit history viewer**: Clicking the "edited" label on any edited message opens a modal showing every prior version with timestamps. Fetches all `m.replace` relations for the event and displays them oldest-to-newest. Previously the "edited" label was visible but unclickable. E2EE fix: the "Original" entry now uses `getClearContent()` (bypasses the replacing-event chain, returns the decrypted pre-edit body) instead of `event.content` which is still raw ciphertext for encrypted messages — fixes "(no text)" shown for almost all E2EE message originals.
- **Inline GIF preview**: Giphy and Tenor share links sent as plain text auto-embed as animated GIFs inline in the timeline. URL patterns are detected client-side; the image is fetched via the homeserver's `/_matrix/media/v3/preview_url` proxy (no direct contact with Giphy/Tenor from the client). Rendered as `<img loading="lazy">` — respects the existing URL preview enabled/disabled setting.
- **GIF picker**: Giphy-powered GIF search and send. Button appears in the message composer only when `gifApiKey` is set in `config.json`. Sends GIF as `m.image` — fetches blob, uploads via `mx.uploadContent`, sends with `mx.sendMessage`. `FocusTrap` handles click-outside / Escape to close. When TDS is active: dark navy background (`#060c14`), orange dim border, `// GIF_SEARCH` header, CSS overrides for Giphy SDK search bar (dark bg, orange border/focus ring, JetBrains Mono), custom orange scrollbar. All TDS styles live in `lotus-terminal.css.ts` — no runtime `<style>` injection, eliminating flash of unstyled content.
- **Message forwarding**: Forward any message to any room from the message context menu.
- **Draft persistence**: Unsent message drafts survive page reload via `localStorage` (`draft-msg-<roomId>`). Jotai in-memory atom is primary; localStorage is used as fallback on reload and cleared on send.
- **Message search date range**: From/To date pickers in the search filter bar. Sends `from_ts`/`to_ts` epoch ms to the Matrix `/search` endpoint. Chip shows active range with X to clear.
- **Image/video captions**: Caption text field on image and video upload — sent as a single event with the media.
- **Location sharing**: Map embed view for incoming location events + static share button. Renders `m.location` events inline with a map tile.
- **Deleted message placeholders**: Redacted `m.room.message`, `m.room.encrypted`, and `m.sticker` events render as "This message has been deleted" with reason (if provided) rather than disappearing. One-line change in the `eventRenderer` filter in `RoomTimeline.tsx`.
- **Message bookmarks / saved messages**: Right-click any message → "Bookmark" / "Remove Bookmark". A star icon in the sidebar nav opens `BookmarksPanel.tsx` — a right-side panel listing all saved messages with room name, preview text, relative timestamp, filter input, "Jump to message" deep-link, and individual remove buttons. Stored in `io.lotus.bookmarks` account data (max 500 entries); syncs across devices. Implemented in `src/app/features/bookmarks/BookmarksPanel.tsx` + `src/app/hooks/useBookmarks.ts`.
- **Message scheduling (MSC4140)**: Clock button next to send opens `ScheduleMessageModal.tsx` with a message textarea and datetime picker. Messages sent via the MSC4140 delayed events API (`org.matrix.msc4140`), confirmed supported on `matrix.lotusguild.org`. A collapsible tray above the composer lists pending scheduled messages with Cancel buttons. Utilities in `src/app/utils/scheduledMessages.ts`.
- **Richer link preview cards**: `UrlPreviewCard.tsx` renders domain-specific cards for 13 sites: YouTube (thumbnail + ▶ play overlay), Vimeo, GitHub (repo parse), Twitter/X (tweet text + media parse), Reddit (subreddit + upvotes + comments), Spotify (artwork), Twitch (LIVE badge + game), Steam, Wikipedia, Discord (server invite), npm, Stack Overflow, and IMDb (poster). Generic cards gain a favicon from Google's S2 service. Cards that produce no renderable content are suppressed.
- **File upload compression (opt-in)**: JPEG and PNG files in the upload preview show a "Compress" checkbox. When checked, a Canvas API call (`toBlob(..., 'image/jpeg', 0.82)`) compresses the image client-side. Original and compressed sizes are shown side-by-side. Compression is strictly opt-in — unchecked by default, skipped for GIF/SVG/WebP.
+### UX

-### Room Customization
-
- **Personal room name overrides**: Right-click any room in the sidebar → "Rename for me…" to set a local display name visible only to you. Other members see the original name unchanged. A small pencil icon marks rooms with a custom local name. Stored in Matrix account data (`io.lotus.room_names`). Uses `io.lotus.room_names` account data key (based on MSC4431).
- **Export room history**: Room Settings → Export tab. Supports Plain Text, JSON, and HTML formats with optional start/end date range filters. Paginates backwards via `mx.paginateEventTimeline()` with a live progress counter. E2EE-aware — events that failed decryption are skipped rather than exported as garbled ciphertext. Downloads via `Blob` + `<a download>`. Implemented in `src/app/features/room-settings/ExportRoomHistory.tsx`.
- **Room activity / mod log**: Room Settings → Activity tab. Filterable log of `m.room.member` (join/leave/kick/ban/unban/invite), `m.room.power_levels`, `m.room.name`, `m.room.topic`, `m.room.avatar`, and `m.room.server_acl` events. Human-readable descriptions, relative timestamps, type-filter dropdown, Load More pagination, and auto-paginate on mount. Implemented in `src/app/features/room-settings/RoomActivityLog.tsx`.
- **Server ACL editor**: Room Settings → Server ACL tab. Reads and writes `m.room.server_acl` state events. Editable allow and deny server lists with wildcard pattern validation (`*.example.com`). "Allow IP literal addresses" toggle. Read-only view shown to users without the required power level. Implemented in `src/app/features/room-settings/RoomServerACL.tsx`.
- **Room stats / insights**: Room Settings → Insights tab (not the default tab). Derives all statistics from the local timeline cache only; a disclaimer banner clarifies this. Shows top 5 active members (bar chart), top 5 reactions (emoji chips), media breakdown (images/videos/audio/files tiles), and a 24-hour activity heatmap (CSS bar chart). Implemented in `src/app/features/room-settings/RoomInsights.tsx`.
-
-### Per-Message Read Receipts
-
-Full per-message read receipt system — shows who has read each message directly in the timeline.
-
-**Architecture:**
- `useRoomReadPositions(room)` hook — computes a `Map<eventId, userId[]>` from all joined members' `room.getEventReadUpTo()` positions. Subscribes to `RoomEvent.Receipt` for live updates (debounced at 150ms to batch burst updates from mass-read events).
- `nearestRenderableId(liveEvents, evtId)` — receipts can land on reaction/edit events that `RoomTimeline` skips (renders `null`). This walks backwards from the receipt event through the live timeline until it finds a non-reaction/non-edit event to attach to.
- `ReadPositionsContext` — React context providing the positions map from `RoomTimeline` down to all `Message` instances without prop drilling.
- `ReadReceiptAvatars` component — renders a pill-shaped row of overlapping `StackedAvatar` circles (24px, `SurfaceVariant` outline) below messages with readers. Pill uses `color.SurfaceVariant.Container` background for visibility on any wallpaper. Max 5 avatars shown + `+N` overflow count. Avatar fallback uses `colorMXID(userId)` for distinctive per-user color.
- Clicking the pill opens the **"Seen by" modal** (`EventReaders`) listing all readers with their avatar, display name, and a formatted read timestamp ("Today at 3:42 PM", "Yesterday at 10:15 AM", "May 14 at 9:00 AM"). Timestamps use `room.getReadReceiptForUserId(userId)?.data.ts` and respect the user's 24-hour clock setting.
- Authenticated media (`mxcUrlToHttp` utility) used for all avatar loads, matching the correct Lotus utility signature.
-
-### Delivery Status Indicators
-
-Own messages display a small status marker below the message content (when no read receipts are visible yet):
- `⟳` — message is being sent / encrypting
- `✓` — message confirmed sent (local echo)
- `✕` — message failed to send (shown in red; orange glow in TDS mode)
- Status hidden once the server confirms receipt (`status === null`) — read receipts take over at that point
-
-### URL Preview Cards (TDS)
-
-URL preview cards (`UrlPreviewCard`) styled for terminal mode:
- Dark transparent background with cyan border-left accent (Anduril Orange)
- Link text in cyan, hover switches to orange with glow
- Light TDS variant: off-white background with blue accent
-
-### Reaction Chips (TDS)
-
-Emoji reaction buttons styled for terminal mode via `button[data-reaction-key]` selector:
- Unselected: `rgba(0,212,255,0.06)` background, cyan border
- Hover: brighter background + box-shadow glow
- Own reaction (aria-pressed=true): orange tint `rgba(255,107,0,0.12)`, orange border
- Light TDS: equivalent blue/orange variants
-
-
-### DM Call Improvements
-
-
- **Incoming call ring**: DM calls trigger a ring tone with Answer/Decline UI. 30-second auto-dismiss if unanswered. Implemented in `Room.tsx` and `RoomViewHeader.tsx`.
-
-### Room Customization
-
- **Room emoji prefix**: A leading emoji in a room name (e.g. 🎮 general) renders at 1.15× size in the sidebar for visual impact. Matrix room names already support Unicode — this is purely a rendering enhancement in `RoomNavItem.tsx`. All three room-name inputs (Create Room, Room Settings, "Rename for me…" dialog) now include a 😊 emoji picker button that prepends the selected emoji to the name field.
-
-### Presence
-
- **Discord-style presence selector**: Clicking your avatar in the bottom-left sidebar opens a popout with five status options — Online (green), Idle (yellow), Do Not Disturb (red, broadcasts `unavailable` with `status_msg: 'dnd'`), Invisible (grey outline, broadcasts `offline`), and Auto (activity-tracking, the original behaviour). The selected status persists across reloads via the settings atom. A colored badge on the avatar reflects the current status at a glance. `usePresenceUpdater` short-circuits immediately for manual modes; full idle-timer and visibility-change logic only runs in Auto mode. Settings also exposed via `src/app/state/settings.ts` (`presenceStatus` field).
- **Custom status message**: Set a short status text (up to 64 characters) with an emoji picker, shown below your display name in member lists and presence displays. Accessible via Settings → Account → Profile. Includes an **auto-clear timer** (options: 30 minutes, 1 hour, 4 hours, 1 day, 3 days, 7 days) — after the timer expires, the status is automatically cleared by setting `status_msg: ''` via `mx.setPresence`. A character counter (shown when ≥ 56/64 chars) prevents overflow. Implemented in `src/app/features/settings/account/Profile.tsx`.
- **Presence badges on members**: Online/busy/away dots shown next to users in the room members drawer and settings members panel (`PresenceBadge` component from `src/app/components/presence/Presence.tsx`).
- **Presence avatar border ring**: A 2px colored `outline` ring on user avatars throughout the app shows presence at a glance — green (online), yellow (idle), red (DND), no ring (offline). Implemented as `PresenceRingAvatar` component (`src/app/components/presence/PresenceRingAvatar.tsx`) using `React.cloneElement` to inject `outline` + `outlineOffset` directly onto the child `Avatar` element — the ring follows the avatar's actual `border-radius` regardless of shape. Applied to: message timeline sender avatars, members drawer, @mention autocomplete, and inbox notification senders.
- **Document title unread count**: Tab title updates to `(N) Lotus Chat` for mentions, `· Lotus Chat` for unreads, `Lotus Chat` when clear.
- **Extended profile fields (MSC4133)**: Settings → Account → Profile includes Pronouns (`m.pronouns`) and Timezone (`m.tz`) fields, saved via MSC4133 `PUT /_matrix/client/unstable/uk.tcpip.msc4133/{userId}/{field}`. Both fields are displayed in user profile panels. Implemented via `src/app/hooks/useExtendedProfile.ts`.
- **User local time in profile**: When a user has `m.tz` set, their profile panel shows a clock icon, their current local time, and the timezone abbreviation (e.g. EST, JST). Updates every 60 seconds. Respects the viewer's `hour24Clock` setting. Implemented via `src/app/hooks/useLocalTime.ts`.
-
-### UX & Composer
-
- **Message length counter**: A muted character counter appears just left of the send button while typing, disappearing when the composer is empty. Resets on room switch.
- **Quick emoji reactions on hover**: The 3 most-recently-used emoji reactions appear directly in the message hover toolbar (between the emoji-board button and Reply), so reacting requires a single click rather than opening the 3-dots menu first. Clicking a quick-reaction also closes any open emoji picker. Powered by `useRecentEmoji` sourced from Matrix account data.
- **In-app notification toasts**: When a message or invite notification fires and the browser window is focused, a slim TDS-styled toast card slides in from the bottom-right instead of triggering an OS notification. Card shows: 24px avatar (initials fallback), sender name in orange, truncated message body, room name, × dismiss, 4 s auto-dismiss. Clicking navigates directly to the correct room (DM or home path) or the invites inbox. OS notifications are unchanged when the window is not focused. Implemented in `src/app/features/toast/LotusToastContainer.tsx` + `src/app/state/toast.ts`.
- **Collapsible long messages**: Messages exceeding ~20 lines are auto-collapsed with a "Read more ↓" button. Click to expand inline; a "Collapse ↑" button re-folds. Threshold (in lines) configurable in Settings → Appearance. Uses CSS `max-height` + `overflow: hidden` — works correctly with code blocks and embedded media. Respects `prefers-reduced-motion`.
- **Message send animation**: Own sent messages fade and scale into the timeline (0.15 s ease-out: `scale(0.97)→scale(1)`, `opacity 0.4→1`). Incoming messages are unaffected. Respects `prefers-reduced-motion`.
- **Right-click room context menu**: Expanded sidebar room context menu — **Mute** now opens a duration submenu (15 min / 1 hr / 8 hr / 24 hr / Indefinite) with auto-restore after the selected window; **Copy Room Link** copies the `matrix.to` URL with a "Copied!" flash; **Mark as Read** marks the room read to the latest event; plus Leave Room and Room Settings shortcuts.
- **Unverified device warning**: `warnOnUnverifiedDevices` setting (default off). When enabled via Settings → General → Privacy, a warning banner appears above the composer in encrypted rooms that contain unverified devices, showing the count. Sending is never blocked — the banner is informational only. Uses the existing `useUnverifiedDeviceCount()` hook.
- **Sidebar room filter**: A search-icon input at the top of the Home and DMs sidebar tabs filters rooms by display name in real time. Clears on tab switch. Styled to match the members-drawer search bar (`size="400"`, search prefix icon).
- **DM last message preview**: Each DM row in the sidebar shows a truncated message body (48 chars) and relative timestamp (`Xm`, `Xhr`, `Yesterday`, `D MMM`) below the room name, sourced reactively from `useRoomLatestRenderedEvent`. Encrypted rooms show "Encrypted message" only on actual decryption failure.
- **Room sort order**: Sort icon in the Rooms sidebar header lets users sort non-space rooms by Recent Activity (default), A→Z, or Unread First. Persists via `homeRoomSort` setting.
- **Favorite rooms**: Right-click any room → "Add to Favorites" / "Remove from Favorites". Favorited rooms (using the standard Matrix `m.favourite` tag) appear in a collapsible "Favorites" section above the main room list on the Home tab. Syncs across devices via account data.
- **Poll creation**: Polls can be created directly from the composer — `Icons.OrderList` button opens a modal with question field, 2–10 answer options (add/remove), and Single/Multiple choice toggle. Sends a stable `m.poll.start` event. (Poll display & voting were already supported.)
- **Voice message playback speed**: `0.75×` → `1×` → `1.5×` → `2×` speed toggle pill on voice message player — cycles on click via `playbackRate` on the `<audio>` element.
- **Invite link + QR code**: Room settings → General shows a "Share Room" tile with the `matrix.to` invite URL and a QR code. The Invite modal also has a `⊞` toggle button showing a QR panel when clicked. Both use `api.qrserver.com` (added to CSP on LXC 106).
- **Private read receipts**: Settings → General → Privacy — "Private Read Receipts" toggle. When on, sends `m.read.private` instead of `m.read` so other room members can't see when you've read messages.
- **Media gallery**: A right-side drawer (photo icon in room header, Desktop only) showing Images | Videos | Files tabs. Reads already-decrypted timeline events — works in E2EE rooms. Encrypted-blob images show a lock-icon placeholder. Load More paginates backwards via `mx.paginateEventTimeline()`.
- **Knock-to-join**: When a room's join rule is `knock`, RoomIntro shows "Request to Join" (calls `mx.knockRoom()`) with "Request sent" pending state. Room admins see a "Pending Requests" section in the members drawer with Approve / Deny buttons.
- **Code syntax highlighting** (TDS mode): Fenced code blocks in messages highlight keywords (cyan), strings (green), numbers (orange), comments (italic dim), function names (purple) using inline `--lt-accent-*` CSS variables. Custom tokenizer in `syntaxHighlight.ts` — supports JS/TS/JSX/TSX, Python, Rust. Falls back to ReactPrism for other languages.
-
-### Settings (Appearance)
-
- **Animated Chat Backgrounds**: Five CSS-only animated wallpapers added to the background picker — Digital Rain (two-layer vertical stripe scroll with parallax), Star Drift (three-layer radial-gradient star field drifting diagonally), Grid Pulse (neon grid lines expanding/contracting via `backgroundSize` keyframe), Aurora Flow (four radial gradient ellipses sweeping across a 200% canvas), Fireflies (three layers of glowing dots drifting). All use vanilla-extract `keyframes()` — no canvas, GPU-composited. Respects `prefers-reduced-motion: reduce` (animation stripped at call time). "Pause Background Animations" toggle in Settings → Appearance provides an in-app override. Implemented in `src/app/styles/Animations.css.ts` + `src/app/features/lotus/chatBackground.ts`.
- **Glassmorphism Sidebar**: Settings → Appearance toggle (off by default). When enabled, the left sidebar becomes semi-transparent (`background: rgba(3,5,8,0.55)`) with `backdrop-filter: blur(12px)` so chat background patterns show through as a frosted glass effect. Fix: the active chat background is mirrored onto `document.body` via `useEffect` in `SidebarNav.tsx` so the blur has content to work through (previously the sidebar was a flex sibling with nothing physically behind it). Implemented as a vanilla-extract `SidebarGlass` class applied to the `<Sidebar>` container in `SidebarNav.tsx`.
-
-
- **Night Light / Blue Light Filter**: Warm orange overlay (`rgba(255,140,0,N%)`) across the entire UI. Toggle + intensity slider (5–80%) in Settings → Appearance. `position:fixed; pointer-events:none; z-index:9998`. Persists across sessions.
-
-### Notification Enhancements
-
- **Custom notification sounds**: `messageSoundId` / `inviteSoundId` settings select per-category notification sound (`notification.ogg`, `invite.ogg`, `call.ogg`, or None). Settings → Notifications expands the sound toggle with Message Sound + Invite Sound selects and ▶ preview buttons. Shared `notificationSounds.ts` module.
- **Notification quiet hours**: `quietHoursEnabled` / `quietHoursStart` / `quietHoursEnd` settings suppress all desktop notifications and sounds during a configured time window. Handles overnight spans (e.g. 23:00–08:00). Settings → Notifications: Quiet Hours card with toggle + start/end time pickers.
- **Full push rule editor**: Settings → Notifications → Advanced Push Rules section. Covers override, room, sender, and underride rule kinds. Each row has a human-readable label for built-in rules, an enable/disable toggle, and a delete button for custom rules. An add-rule form at the bottom of the room and sender sections lets users create new per-room or per-sender push rules by entering the room/user ID.
-
-### Calls (Extended)
-
- **Push-to-Deafen**: Press `M` during a call to toggle speaker mute (deafen). Configurable in Settings → General → Calls alongside the PTT key. Skips editable elements; guards `e.repeat`; uses `el.ownerDocument.body` for iframe safety.
- **TDS typing indicator dots**: When Lotus Terminal mode is active, the animated typing indicator dots turn TDS orange (`var(--lt-accent-orange)`) via `color: currentColor` inheritance.
-
-### Server Integration
-
- **Server support contact (MSC1929)**: Settings → Help & About displays the homeserver admin contact fetched from `/.well-known/matrix/support`. Shows the admin's Matrix ID and a link to the support page when the homeserver has configured this endpoint. Degrades gracefully when not configured (section is hidden on 404 or network error). In TDS mode the contact text and link render in `--lt-accent-cyan`. Implemented in `src/app/features/settings/about/About.tsx`.
- **Server notices**: Rooms of type `m.server_notice` (system messages from the homeserver) now render with a distinct "Server Notice" `<Chip variant="Warning">` badge in the room header and a disabled composer showing "This is a server notice room — you cannot send messages here." Previously indistinguishable from regular DMs. Badge in `src/app/features/room/RoomViewHeader.tsx`; composer guard in `src/app/features/room/RoomInput.tsx`.
-
-### Infrastructure
-
- **Authenticated media**: All avatar/media loads use `mxcUrlToHttp(mx, mxcUrl, useAuthentication, w, h, 'crop')` from `../../utils/matrix` — the Lotus utility that handles MSC3916 authenticated media. (Upstream Cinny uses the SDK method with incorrect argument order for authenticated endpoints.)
- **Upstream tracking**: `git remote add upstream https://github.com/cinnyapp/cinny.git`. Merge strategy: `git fetch upstream && git merge upstream/main`. Daily check via `cinny-upstream-check.sh` on LXC 106 — notifies Matrix on new upstream commits.
- **Rolldown CJS interop — millify**: `src/app/plugins/millify.ts` uses a named import (`import { millify as millifyPlugin } from 'millify'`) instead of a default import. Rolldown's `__toESM` helper with `mode=1` sets `a.default = module_object` (not the function itself) when `hasOwnProperty` prevents the copy — calling `millifyPlugin()` would throw `(0, zc.default) is not a function`. Named import bypasses the interop entirely.
- **Sentry noise filter**: `ignoreErrors: ['Request timed out']` added to `Sentry.init` in `src/index.tsx` to suppress unhandled rejections from the matrixRTC delayed-event heartbeat (matrix-sdk) and the widget PostmessageTransport initial-load race (matrix-widget-api). Neither is actionable from client code.
- **URL preview default in encrypted rooms**: `encUrlPreview` default changed from `false` to `true` in `src/app/state/settings.ts`. A security note is shown next to the toggle in Settings → General explaining that the homeserver fetches the URL (and sees it) but not the message content.
+- Filter and search rooms in the sidebar
+- Favorite rooms sync across devices and appear in a pinned section
+- Sort rooms by recent activity, alphabetical, or unread first
+- DM rows show a message preview and relative timestamp
+- Right-click a room for a context menu: mute with duration, copy link, mark as read
+- Quick emoji reactions appear on message hover — one click to react
+- Knock-to-join: request access to a room; admins approve or deny from the members list
+- Media gallery drawer: browse all images, videos, and files shared in a room
+- Invite link and QR code in room settings
+- Pending knock requests shown in the members list for room admins
+- Homeserver support contact displayed in Help & About (MSC1929)
+- Server notice rooms are visually distinct from regular DMs

 ---

-## Build
+## Desktop App
+
+Lotus Chat has a desktop app for Windows, macOS, and Linux. It wraps the same web client in a native window with automatic background updates — no need to reinstall for new versions.
+
+### Download
+
+Download the latest release from the [Releases page on code.lotusguild.org](https://code.lotusguild.org).
+
+### SmartScreen Warning (Windows)
+
+When you first run the installer on Windows, you may see a popup that says **"Windows protected your PC"** with the app listed as an unknown publisher. This is normal.
+
+**Why it happens:** Windows SmartScreen flags any app that does not have an expensive commercial code-signing certificate from a major CA. Lotus Chat is signed with its own key for update verification, but that key is not in Microsoft's pre-approved list.
+
+**How to install anyway:**
+
+1. Click **"More info"** in the SmartScreen dialog.
+2. A **"Run anyway"** button will appear.
+3. Click it to proceed with installation.
+
+After the first install, automatic in-app updates handle all future versions — you will not see this prompt again for updates.
+
+---
+
+## For Developers
+
+The source code lives in `/root/code/cinny`. All changes should be made on the `lotus` branch. Push to `origin/lotus` and CI will automatically build and deploy to [chat.lotusguild.org](https://chat.lotusguild.org) in approximately 11 minutes — no manual build or deploy steps required.
+
+See [LOTUS_FEATURES.md](LOTUS_FEATURES.md) for the full feature changelog and [LOTUS_TODO.md](LOTUS_TODO.md) for the work backlog.
+
+### Build

 ```bash
-npm ci
-npm run build   # outputs to dist/
+npm ci && npm run build   # outputs to dist/
 ```

-Vite's render-chunks phase requires ~6 GB Node heap. If OOM killed, set:
+If the build is killed due to out-of-memory:
+
 ```bash
 NODE_OPTIONS=--max_old_space_size=6144 npm run build
 ```

-## Development workflow
-
-All code changes should be made in the local clone at `/root/code/cinny` on the dev box, then committed and pushed to `origin/lotus`. The CI/CD pipeline handles everything from there — no manual build or deploy steps needed.
+### CI/CD

 ```
-edit → commit → git push    # ~11 minutes → auto-deployed to chat.lotusguild.org
+edit → commit → git push    →    ~11 min    →    live at chat.lotusguild.org
 ```
-
-Pipeline (`.gitea/workflows/ci.yml` + `lotus_deploy.sh` on LXC 106):
-1. Push triggers a Gitea Actions build — TypeScript check, ESLint, Prettier, bundle size report
-2. Build must pass as the CI gate; quality checks are informational (`continue-on-error`)
-3. A Gitea webhook fires `lotus_deploy.sh` on LXC 106, which polls the API until CI passes (up to 15 min), then pulls `origin/lotus`, runs `npm ci && npm run build`, and rsyncs to `/var/www/html/`
-
-LXC 106's stored Gitea credential is **read-only** — it can only pull. Pushes must be done from the dev box with your personal credentials (entered manually, never cached).
-
-## Deployment
-
-Built files are served from `/var/www/html/` on LXC 106 (nginx). Config lives at `/opt/lotus-cinny/config.json` (vite copies it to `dist/`):
-
-```json
-{
-  "defaultHomeserver": 0,
-  "homeserverList": ["matrix.lotusguild.org"],
-  "allowCustomHomeservers": false,
-  "gifApiKey": "<giphy_key>"
-}
-```
-
-## Key Custom Files
-
-| File | Purpose |
-|------|---------|
-| `src/lotus-terminal.css.ts` | All TDS CSS tokens, global styles, light/dark variants |
-| `src/lotus-boot.ts` | Boot sequence animation (runs once per session) |
-| `src/app/hooks/useRoomReadPositions.ts` | Per-message read receipt position map |
-| `src/app/features/room/ReadPositionsContext.ts` | React context for read positions |
-| `src/app/components/read-receipt-avatars/` | Read receipt avatar pill component |
-| `src/app/components/event-readers/EventReaders.tsx` | "Seen by" modal with timestamps |
-| `src/app/components/GifPicker.tsx` | GIF search + send |
-| `src/app/features/call/CallControls.tsx` | PTT badge + keybind logic |
-| `src/app/plugins/call/CallControl.ts` | EC widget bridge (screenshare revert, PTT mic) |
-| `src/app/components/CallEmbedProvider.tsx` | PiP + draggable call embed, call wallpaper carry-over |
-| `src/app/plugins/call/CallEmbed.ts` | EC widget bridge: iframe setup, `color-scheme` dark/light injection, built-in control hiding, theme sync |
-| `src/app/plugins/millify.ts` | Named import fix for Rolldown CJS interop (prevents `zc.default is not a function` crash) |
-| `src/app/features/room/MediaGallery.tsx` | Right-side media gallery drawer (images/videos/files) |
-| `src/app/features/room/PollCreator.tsx` | Poll creation modal (single/multiple choice, 2–10 options) |
-| `src/app/features/common-settings/general/RoomShareInvite.tsx` | Invite link + QR code tile for room settings |
-| `src/app/utils/syntaxHighlight.ts` | TDS code syntax tokenizer (JS/TS/Python/Rust → inline CSS vars) |
-| `src/app/features/room-settings/ExportRoomHistory.tsx` | Export room messages to plain text / JSON / HTML with date range filter and E2EE awareness |
-| `src/app/features/room-settings/RoomActivityLog.tsx` | Filterable mod log of room state events (joins, kicks, bans, power level changes, etc.) |
-| `src/app/features/room-settings/RoomServerACL.tsx` | Server ACL viewer/editor (allow/deny lists, IP literal toggle, power-level gated) |
-| `src/app/features/room-settings/RoomInsights.tsx` | Room stats panel: top members bar chart, top reactions, media breakdown, 24h heatmap |
-| `src/app/features/bookmarks/BookmarksPanel.tsx` | Saved messages sidebar panel with filter, jump-to-message, and remove |
-| `src/app/hooks/useBookmarks.ts` | Read/write `io.lotus.bookmarks` account data for message bookmarks |
-| `src/app/features/room/ScheduleMessageModal.tsx` | Schedule-message modal with datetime picker; sends via MSC4140 delayed events API |
-| `src/app/utils/scheduledMessages.ts` | Utilities for MSC4140 scheduled message state and cancel endpoint |
-| `src/app/hooks/useExtendedProfile.ts` | Read/write MSC4133 extended profile fields (`m.pronouns`, `m.tz`) |
-| `src/app/hooks/useLocalTime.ts` | Formats user local time from `m.tz` IANA zone; updates every 60 s |
-| `src/app/components/url-preview/UrlPreviewCard.tsx` | Domain-specific URL preview cards for 13 sites + generic favicon fallback |