cinny/README.md

# Lotus Chat

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)**  |  Forked from [Cinny](https://github.com/cinnyapp/cinny), synced through v4.12.3

---

## Licensing & Attribution

The source code is licensed under [AGPLv3](LICENSE), the same license as the upstream Cinny project. The source for this fork is public at [code.lotusguild.org/LotusGuild/cinny](https://code.lotusguild.org/LotusGuild/cinny).

The Lotus Chat logo (`public/res/Lotus.png`) is a derivative work based on the original Cinny logo by Ajay Bura and contributors, used under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The modified logo is © Lotus Guild and is also made available under CC BY 4.0.

---

## Features

### Messaging

- 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

### Calls & Voice

- 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
- AFK auto-mute: mic is automatically silenced after a configurable idle timeout (1–30 min); a toast confirms the action
- Voice channel user limit: admins can cap how many people can be in a room's call — enforced server-side for every Matrix client (not just Lotus Chat); others see "Channel Full" until a spot opens
- Custom join/leave sound effects when someone enters or leaves your call — choose Chime, Soft, Retro, or off
- Soundboard: upload your own short audio clips (like custom emojis — they sync across your devices) and play them into a call so everyone hears them
- Call quality settings: cap your microphone bitrate, screenshare bitrate, and screenshare framerate — handy on a slow connection (Settings → Calls)
- Room call permissions: admins can turn off screen sharing or make a room audio-only (no cameras) — enforced server-side for every Matrix client, and it stops an in-progress share within seconds of being switched off

### Customization & Appearance

- 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 (with improved per-layer looping, phosphor-flicker rain, fluid aurora sweep, and organic firefly bioluminescence)
- 11 seasonal & holiday theme overlays — Halloween, Christmas, New Year, Autumn, Valentine's Day, St. Patrick's Day, Earth Day, Lunar New Year, April Fools', Deep Space, and Retro Arcade; auto-selected by date with a manual override in Settings → Appearance
- Avatar decorations — 99 animated APNG overlays (Gaming, Cyber, Space, Fantasy, Nature, Spooky, Cozy, and more) that frame your avatar across the timeline, members list, and @mention autocomplete; visible to all Lotus Chat users; select in Settings → Account → Avatar Decoration
- 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

### Presence & Profile

- Discord-style presence selector: Online, Idle, Do Not Disturb, Invisible, or Auto
- Custom status message with emoji and an optional auto-clear timer (changing your status is never silently overwritten by activity events)
- 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
- Private notes on any user's profile — freeform text visible only to you, auto-saves and syncs across devices
- Unread count shown in the browser tab title

### Moderation & Privacy

- 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

### Notifications

- 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

### UX

- 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 with a live badge count on the Members button
- Homeserver support contact displayed in Help & About (MSC1929)
- Server notice rooms are visually distinct from regular DMs

---

## 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.

### Desktop-Specific Features

Beyond the web client, the desktop app adds native OS integration (Windows-focused; graceful no-ops elsewhere). See [`LOTUS_FEATURES.md`](./LOTUS_FEATURES.md#desktop-app-features) for detail.

- **Native rich notifications** — Windows toasts you can click to open the room or reply to inline, right from the toast.
- **Focus Assist sync** — Lotus silences its own notifications while Windows Focus Assist / Quiet Hours is on.
- **Windows Jump List** — right-click the taskbar icon for quick access to your most-active rooms.
- **Taskbar call controls** — Mute / Deafen / End Call buttons on the taskbar thumbnail during a call, plus call status in the volume flyout (SMTC).
- **Stays awake in calls** — the system won't sleep or dim during a voice/video call.
- **Network awareness** — reconnects promptly when Windows connectivity changes.
- **Custom window chrome** (opt-in) — a Lotus-styled title bar in place of the OS one.
- **Recursive folder drag-drop** — drop a whole folder onto the composer to upload everything inside it.
- **Automatic background updates** with a one-click update toast.

---

## 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.

### 🔱 Element Call fork ("Lotus Call") — LIVE

Voice/video channels embed **Element Call**, which is now our **self-built fork**
(`@lotusguild/element-call-embedded` `0.20.1-lotus.1`, source at
`LotusGuild/element-call`), published to our private Gitea npm registry and served
same-origin. We no longer depend on the upstream prebuilt bundle, so in-call
behavior is editable source instead of fragile DOM/widget hacks.

**Shipped via the fork:** denoise as an in-source LiveKit audio stage (survives
reconnects), in-call speaking/mute events, focus-a-participant during screenshare,
avatar decorations on EC video tiles, and a native transparent background.
**Built but dormant (need cinny UI):** real call-audio injection
(`io.lotus.inject_audio` → in-call soundboard) and quality controls
(`io.lotus.set_quality`).

The full plan and integration map is in
**[`HANDOFF_ELEMENT_CALL_FORK.md`](HANDOFF_ELEMENT_CALL_FORK.md)**; infra/hosting +
build-pipeline notes live in the `LotusGuild/matrix` repo README. Search the docs
for the **`[EC-FORK]`** tag to find every related note.

### Build

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

If the build is killed due to out-of-memory:

```bash
NODE_OPTIONS=--max_old_space_size=6144 npm run build
```

### CI/CD

```
edit → commit → git push    →    ~11 min    →    live at chat.lotusguild.org
```