Apply the auto-fixable lint rules and the formatter, and drop the Vite build artifacts.
Checks / checks (push) Successful in 2m11s
Trigger cinny-mobile / dispatch (push) Successful in 1s

This commit is contained in:
2026-11-01 04:23:53 +11:00
parent 3cd159a63e
commit a6ad8651b3
605 changed files with 11480 additions and 9125 deletions
+30 -17
View File
@@ -11,6 +11,7 @@ The API server starts automatically when you run Paarrot. It listens on `http://
**Option 1: Using Postman**
Import the Postman collection for easy testing:
1. Open Postman
2. Click **Import** → **File**
3. Select `paarrot-api.postman_collection.json`
@@ -19,16 +20,19 @@ Import the Postman collection for easy testing:
The collection is automatically updated on git push.
**Option 2: Using the test script**
```bash
node test-api.js
```
**Option 3: Using curl**
```bash
./test-api.sh
```
**Option 4: Manual curl commands**
```bash
# Health check
curl http://127.0.0.1:33384/health
@@ -46,22 +50,22 @@ curl -X POST http://127.0.0.1:33384/message/current \
### Common Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Check if API is running |
| `/status` | GET | Get app status (mute, deafen, etc.) |
| `/mute/toggle` | POST | Toggle microphone mute |
| `/deafen/toggle` | POST | Toggle deafen |
| `/channels` | GET | Get list of rooms |
| `/channel` | POST | Switch to a room |
| `/message/current` | POST | Send message to current room |
| `/room/current` | GET | Get current room info |
| `/messages/groups` | GET | Last N messages across groups (`?limit=10`) |
| `/messages/dms` | GET | Last N messages across DMs (`?limit=10`) |
| `/messages/combined` | GET | Last N messages across groups + DMs (`?limit=10`) |
| `/unreads/groups` | GET | Unread group conversations |
| `/unreads/dms` | GET | Unread DM conversations |
| `/unreads/combined` | GET | Unread groups + DMs |
| Endpoint | Method | Description |
| -------------------- | ------ | ------------------------------------------------- |
| `/health` | GET | Check if API is running |
| `/status` | GET | Get app status (mute, deafen, etc.) |
| `/mute/toggle` | POST | Toggle microphone mute |
| `/deafen/toggle` | POST | Toggle deafen |
| `/channels` | GET | Get list of rooms |
| `/channel` | POST | Switch to a room |
| `/message/current` | POST | Send message to current room |
| `/room/current` | GET | Get current room info |
| `/messages/groups` | GET | Last N messages across groups (`?limit=10`) |
| `/messages/dms` | GET | Last N messages across DMs (`?limit=10`) |
| `/messages/combined` | GET | Last N messages across groups + DMs (`?limit=10`) |
| `/unreads/groups` | GET | Unread group conversations |
| `/unreads/dms` | GET | Unread DM conversations |
| `/unreads/combined` | GET | Unread groups + DMs |
## 🎮 Stream Deck Integration
@@ -69,10 +73,12 @@ curl -X POST http://127.0.0.1:33384/message/current \
2. Create buttons with these settings:
**Mute Toggle Button:**
- URL: `http://127.0.0.1:33384/mute/toggle`
- Method: POST
**Quick Message Button:**
- URL: `http://127.0.0.1:33384/message/current`
- Method: POST
- Body: `{"message": "BRB!"}`
@@ -82,6 +88,7 @@ curl -X POST http://127.0.0.1:33384/message/current \
To enable full functionality, you need to implement the action handlers in the Cinny frontend:
1. Import the API handler in your app initialization:
```typescript
import { initPaarrotAPI } from './app/paarrot-api';
@@ -98,6 +105,7 @@ initPaarrotAPI(matrixClient);
## 📖 Full Documentation
See [API.md](API.md) for complete API documentation including:
- All available endpoints
- Request/response formats
- Error handling
@@ -107,6 +115,7 @@ See [API.md](API.md) for complete API documentation including:
## 🛠️ Configuration
Edit `electron/api-server.js` to customize:
- Port number (default: 33384)
- Timeout duration (default: 10s)
- CORS settings
@@ -114,11 +123,13 @@ Edit `electron/api-server.js` to customize:
## 🐛 Troubleshooting
**API not responding:**
1. Check if Paarrot is running
2. Look for "Paarrot API server listening" in console logs
3. Verify port 33384 is not in use: `lsof -i :33384`
**Actions not working:**
1. Check browser console for errors
2. Ensure `initPaarrotAPI()` is called in your app
3. Implement the TODO items in `paarrot-api.ts`
@@ -144,6 +155,7 @@ Edit `electron/api-server.js` and change the port number in the constructor.
## 💡 Examples
**Python Script:**
```python
import requests
@@ -155,12 +167,13 @@ toggle_mute()
```
**JavaScript:**
```javascript
async function sendQuickMessage(msg) {
const res = await fetch('http://127.0.0.1:33384/message/current', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: msg })
body: JSON.stringify({ message: msg }),
});
return res.json();
}
+105 -78
View File
@@ -22,6 +22,7 @@ Check if the API server is running.
**Endpoint**: `GET /health`
**Response**:
```json
{
"status": "ok",
@@ -39,6 +40,7 @@ Get the current status of the app (mute, deafen, current room, etc.).
**Endpoint**: `GET /status`
**Response**:
```json
{
"success": true,
@@ -60,6 +62,7 @@ Set the mute status.
**Endpoint**: `POST /mute`
**Request Body**:
```json
{
"muted": true
@@ -67,6 +70,7 @@ Set the mute status.
```
**Response**:
```json
{
"success": true,
@@ -85,6 +89,7 @@ Toggle the current mute status.
**Endpoint**: `POST /mute/toggle`
**Response**:
```json
{
"success": true,
@@ -103,6 +108,7 @@ Set the deafen status (deafening also mutes).
**Endpoint**: `POST /deafen`
**Request Body**:
```json
{
"deafened": true
@@ -110,6 +116,7 @@ Set the deafen status (deafening also mutes).
```
**Response**:
```json
{
"success": true,
@@ -128,6 +135,7 @@ Toggle the current deafen status.
**Endpoint**: `POST /deafen/toggle`
**Response**:
```json
{
"success": true,
@@ -146,6 +154,7 @@ Switch to a different Matrix room.
**Endpoint**: `POST /channel`
**Request Body**:
```json
{
"roomId": "!abc123:matrix.org"
@@ -153,6 +162,7 @@ Switch to a different Matrix room.
```
**Response**:
```json
{
"success": true,
@@ -172,6 +182,7 @@ Get a list of available rooms/channels.
**Endpoint**: `GET /channels`
**Response**:
```json
{
"success": true,
@@ -212,6 +223,7 @@ Send a message to a specific room.
**Endpoint**: `POST /message`
**Request Body**:
```json
{
"roomId": "!abc123:matrix.org",
@@ -220,6 +232,7 @@ Send a message to a specific room.
```
**Response**:
```json
{
"success": true,
@@ -239,6 +252,7 @@ Send a message to the currently active room.
**Endpoint**: `POST /message/current`
**Request Body**:
```json
{
"message": "Hello from the API!"
@@ -246,6 +260,7 @@ Send a message to the currently active room.
```
**Response**:
```json
{
"success": true,
@@ -265,6 +280,7 @@ Get information about the currently active room.
**Endpoint**: `GET /room/current`
**Response**:
```json
{
"success": true,
@@ -287,9 +303,11 @@ Get the most recent messages across joined group channels (non-DMs).
**Endpoint**: `GET /messages/groups`
**Query Parameters**:
- `limit` (optional) — number of messages to return (1–100, default `10`)
**Response**:
```json
{
"success": true,
@@ -323,6 +341,7 @@ Get the most recent messages across joined direct messages.
**Endpoint**: `GET /messages/dms`
**Query Parameters**:
- `limit` (optional) — number of messages to return (1–100, default `10`)
**Response**: same shape as groups, with `"scope": "dms"`.
@@ -336,6 +355,7 @@ Get the most recent messages across groups and DMs together.
**Endpoint**: `GET /messages/combined`
**Query Parameters**:
- `limit` (optional) — number of messages to return (1–100, default `10`)
**Response**: same shape as groups, with `"scope": "combined"`.
@@ -349,6 +369,7 @@ List joined group channels that currently have unread activity.
**Endpoint**: `GET /unreads/groups`
**Response**:
```json
{
"success": true,
@@ -409,6 +430,7 @@ All endpoints return error responses in the following format:
```
Common HTTP status codes:
- `200 OK` - Request successful
- `400 Bad Request` - Missing or invalid parameters
- `404 Not Found` - Endpoint not found
@@ -443,7 +465,7 @@ const fetch = require('node-fetch');
// Toggle mute
async function toggleMute() {
const response = await fetch('http://127.0.0.1:33384/mute/toggle', {
method: 'POST'
method: 'POST',
});
const data = await response.json();
console.log('Muted:', data.data.muted);
@@ -454,9 +476,9 @@ async function sendMessage(roomId, message) {
const response = await fetch('http://127.0.0.1:33384/message', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
'Content-Type': 'application/json',
},
body: JSON.stringify({ roomId, message })
body: JSON.stringify({ roomId, message }),
});
const data = await response.json();
console.log('Message sent:', data.data.eventId);
@@ -499,14 +521,17 @@ To integrate with Stream Deck:
Example configurations:
**Mute Toggle Button**:
- URL: `http://127.0.0.1:33384/mute/toggle`
- Method: POST
**Deafen Toggle Button**:
- URL: `http://127.0.0.1:33384/deafen/toggle`
- Method: POST
**Send Quick Message**:
- URL: `http://127.0.0.1:33384/message/current`
- Method: POST
- Body: `{"message": "BRB!"}`
@@ -524,82 +549,80 @@ Add this to your app initialization:
```typescript
// Listen for API actions from the Electron API server
if (window.electron?.api?.onAction) {
window.electron.api.onAction(async (action: {
action: string;
params: any;
responseChannel: string;
}) => {
try {
let result;
switch (action.action) {
case 'toggle-mute':
// Toggle microphone mute
result = await toggleMicrophone();
break;
case 'set-mute':
// Set microphone mute state
result = await setMicrophone(action.params.muted);
break;
case 'toggle-deafen':
// Toggle deafen (mute speakers)
result = await toggleDeafen();
break;
case 'set-deafen':
// Set deafen state
result = await setDeafen(action.params.deafened);
break;
case 'change-channel':
// Navigate to a different room
result = await changeRoom(action.params.roomId);
break;
case 'get-channels':
// Get list of rooms
result = await getRoomList();
break;
case 'send-message':
// Send message to specific room
result = await sendMessage(action.params.roomId, action.params.message);
break;
case 'send-message-current':
// Send message to current room
result = await sendMessageToCurrent(action.params.message);
break;
case 'get-current-room':
// Get current room info
result = await getCurrentRoomInfo();
break;
case 'get-status':
// Get current app status
result = await getAppStatus();
break;
default:
throw new Error(`Unknown action: ${action.action}`);
window.electron.api.onAction(
async (action: { action: string; params: any; responseChannel: string }) => {
try {
let result;
switch (action.action) {
case 'toggle-mute':
// Toggle microphone mute
result = await toggleMicrophone();
break;
case 'set-mute':
// Set microphone mute state
result = await setMicrophone(action.params.muted);
break;
case 'toggle-deafen':
// Toggle deafen (mute speakers)
result = await toggleDeafen();
break;
case 'set-deafen':
// Set deafen state
result = await setDeafen(action.params.deafened);
break;
case 'change-channel':
// Navigate to a different room
result = await changeRoom(action.params.roomId);
break;
case 'get-channels':
// Get list of rooms
result = await getRoomList();
break;
case 'send-message':
// Send message to specific room
result = await sendMessage(action.params.roomId, action.params.message);
break;
case 'send-message-current':
// Send message to current room
result = await sendMessageToCurrent(action.params.message);
break;
case 'get-current-room':
// Get current room info
result = await getCurrentRoomInfo();
break;
case 'get-status':
// Get current app status
result = await getAppStatus();
break;
default:
throw new Error(`Unknown action: ${action.action}`);
}
// Send success response back
window.electron.api.sendResponse(action.responseChannel, {
success: true,
data: result,
});
} catch (error) {
// Send error response back
window.electron.api.sendResponse(action.responseChannel, {
success: false,
error: error.message,
});
}
// Send success response back
window.electron.api.sendResponse(action.responseChannel, {
success: true,
data: result
});
} catch (error) {
// Send error response back
window.electron.api.sendResponse(action.responseChannel, {
success: false,
error: error.message
});
}
});
},
);
}
```
@@ -627,16 +650,19 @@ The API server can be configured by modifying `electron/api-server.js`:
## Troubleshooting
**API server not starting**:
- Check if port 33384 is already in use
- Check console logs for errors
- Verify Express is installed: `npm install express cors body-parser`
**Actions not working**:
- Ensure the client-side handler is implemented
- Check browser console for errors
- Verify the action names match between API server and client
**Timeout errors**:
- Actions must respond within 10 seconds
- Check if the Matrix client is initialized
- Verify the action handler is registered
@@ -646,6 +672,7 @@ The API server can be configured by modifying `electron/api-server.js`:
## Future Enhancements
Potential features to add:
- WebSocket support for real-time events
- Authentication with API keys
- Voice channel controls (join/leave)
+6 -1
View File
@@ -5,6 +5,7 @@ The Paarrot desktop client includes a powerful plugin system that allows you to
## What are Plugins?
Plugins are small JavaScript modules that run inside Paarrot and can:
- Add custom commands
- Modify the UI
- React to Matrix events
@@ -53,6 +54,7 @@ Use the search bar to filter plugins by name, description, author, or tags.
⚠️ **Important Security Information**
Plugins run with access to your Matrix client and can:
- Read your messages
- Send messages on your behalf
- Access your room list
@@ -79,6 +81,7 @@ Want to create your own plugin? Check out the [Plugin API Reference](docs/PLUGIN
- `plugin-metadata.json` - Plugin information
2. Implement the plugin interface:
```javascript
module.exports = {
onLoad: async (context) => {
@@ -87,7 +90,7 @@ module.exports = {
},
onUnload: async () => {
// Cleanup when disabled
}
},
};
```
@@ -98,6 +101,7 @@ module.exports = {
## Plugin API
Plugins have access to:
- **Matrix Client**: Full matrix-js-sdk client instance
- **React**: For building UI components
- **Commands**: Register custom slash commands
@@ -134,6 +138,7 @@ Check out the `example-plugin/` directory for a simple example, or the `plugins/
### Performance Issues
If Paarrot becomes slow:
1. Disable plugins one by one to identify the culprit
2. Check for memory leaks in the console
3. Contact the plugin author with details
+231 -210
View File
@@ -27,6 +27,7 @@ Complete reference for developing plugins for Paarrot/Cinny Desktop.
### Plugin Location
Plugins are installed in:
- **Windows**: `%APPDATA%\paarrot\plugins\<plugin-name>\`
- **Linux**: `~/.config/Paarrot/plugins/<plugin-name>/`
- **macOS**: `~/Library/Application Support/Paarrot/plugins/<plugin-name>/`
@@ -59,38 +60,38 @@ Plugins are installed in:
```javascript
module.exports = {
name: "My Plugin",
version: "1.0.0",
name: 'My Plugin',
version: '1.0.0',
dependencies: {
// "other-plugin": "^1.0.0"
},
/**
* Called when plugin loads
* @param {PluginContext} ctx - Plugin context
*/
onLoad: async (ctx) => {
ctx.log('Plugin loaded!');
// Initialize your plugin here
ctx.commands.register({
name: "hello",
description: "Say hello",
run: () => "Hello, world!"
name: 'hello',
description: 'Say hello',
run: () => 'Hello, world!',
});
},
/**
* Called when plugin unloads
*/
onUnload: async () => {
console.log('Plugin unloaded');
},
/**
* API for other plugins
*/
exports: null
exports: null,
};
```
@@ -106,7 +107,7 @@ interface PluginContext {
matrixClient: MatrixClient;
React: typeof import('react');
lucide: typeof import('lucide-react');
commands: CommandsAPI;
messages: MessagesAPI;
ui: UIAPI;
@@ -129,54 +130,57 @@ Register slash commands that users can type in chat.
```javascript
ctx.commands.register({
name: "mycommand",
description: "Does something cool",
args: ["arg1", "arg2"], // Optional
name: 'mycommand',
description: 'Does something cool',
args: ['arg1', 'arg2'], // Optional
run: (args) => {
// Return string to send as message
return `Got args: ${args.arg1}, ${args.arg2}`;
}
},
});
```
#### Examples
**Simple command:**
```javascript
ctx.commands.register({
name: "shrug",
description: "Send a shrug emoji",
run: () => "¯\\_(ツ)_/¯"
name: 'shrug',
description: 'Send a shrug emoji',
run: () => '¯\\_(ツ)_/¯',
});
// Usage: /shrug
```
**Command with arguments:**
```javascript
ctx.commands.register({
name: "greet",
description: "Greet someone",
args: ["name"],
run: ({ name }) => `Hello, ${name || 'stranger'}!`
name: 'greet',
description: 'Greet someone',
args: ['name'],
run: ({ name }) => `Hello, ${name || 'stranger'}!`,
});
// Usage: /greet Alice
```
**Advanced command:**
```javascript
ctx.commands.register({
name: "calc",
description: "Simple calculator",
args: ["expression"],
name: 'calc',
description: 'Simple calculator',
args: ['expression'],
run: ({ expression }) => {
try {
const sanitized = expression.replace(/[^0-9+\-*/().\s]/g, '');
const result = Function(`'use strict'; return (${sanitized})`)();
return `${expression} = ${result}`;
} catch (err) {
return "Invalid expression";
return 'Invalid expression';
}
}
},
});
// Usage: /calc 2 + 2 * 3
```
@@ -214,7 +218,7 @@ ctx.messages.onBeforeSend((msg) => {
if (msg.content.includes('secret')) {
msg.content = msg.content.replace(/secret/g, '█████');
}
// Add prefix
msg.content = `[Bot] ${msg.content}`;
});
@@ -231,7 +235,7 @@ ctx.messages.onReceive((msg) => {
ctx.notify({
title: 'Important Message',
body: msg.content,
type: 'info'
type: 'info',
});
}
});
@@ -240,15 +244,16 @@ ctx.messages.onReceive((msg) => {
#### Real-World Examples
**Auto-expand abbreviations:**
```javascript
ctx.messages.onBeforeSend((msg) => {
const expansions = {
'brb': 'be right back',
'omw': 'on my way',
'gtg': 'got to go',
'afk': 'away from keyboard'
brb: 'be right back',
omw: 'on my way',
gtg: 'got to go',
afk: 'away from keyboard',
};
Object.entries(expansions).forEach(([abbr, full]) => {
const regex = new RegExp(`\\b${abbr}\\b`, 'gi');
msg.content = msg.content.replace(regex, full);
@@ -257,6 +262,7 @@ ctx.messages.onBeforeSend((msg) => {
```
**Add auto-shrug to questions:**
```javascript
ctx.messages.onBeforeSend((msg) => {
if (msg.content.trim().endsWith('?')) {
@@ -266,6 +272,7 @@ ctx.messages.onBeforeSend((msg) => {
```
**Track mentions:**
```javascript
ctx.messages.onReceive((msg) => {
const userId = ctx.matrixClient.getUserId();
@@ -300,21 +307,25 @@ Register custom UI renderers for messages, images, and other content types.
```javascript
// Custom message renderer
ctx.ui.registerRenderer("message", (msg, defaultRenderer) => {
ctx.ui.registerRenderer('message', (msg, defaultRenderer) => {
// Custom logic
if (msg.sender?.includes('bot')) {
// Return custom React component
return ctx.React.createElement('div', {
style: { background: 'yellow' }
}, msg.content);
return ctx.React.createElement(
'div',
{
style: { background: 'yellow' },
},
msg.content,
);
}
// Fall back to default
return defaultRenderer?.();
});
// Custom image renderer
ctx.ui.registerRenderer("image", (data, defaultRenderer) => {
ctx.ui.registerRenderer('image', (data, defaultRenderer) => {
// Add custom effects, borders, etc.
return defaultRenderer?.();
});
@@ -328,14 +339,11 @@ interface UIAPI {
unregisterButton(id: string): void;
registerRenderer(
type: string,
renderer: (data: any, defaultRenderer?: () => ReactNode) => ReactNode
renderer: (data: any, defaultRenderer?: () => ReactNode) => ReactNode,
): void;
}
type CustomRenderer = (
data: any,
defaultRenderer?: () => ReactNode
) => ReactNode;
type CustomRenderer = (data: any, defaultRenderer?: () => ReactNode) => ReactNode;
```
---
@@ -354,30 +362,30 @@ ctx.ui.registerButton({
location: 'text-composer-toolbar',
label: 'My Tool',
icon: '🔧',
onClick: () => ctx.log('clicked!')
onClick: () => ctx.log('clicked!'),
});
```
#### UI Locations — Nav List Rows
| Location | Where it appears |
|---|---|
| `channel-list` | Space channel list, below Lobby and Message Search |
| `home-section` | Home panel, inside the Rooms category above the room list |
| Location | Where it appears |
| ----------------- | ----------------------------------------------------------- |
| `channel-list` | Space channel list, below Lobby and Message Search |
| `home-section` | Home panel, inside the Rooms category above the room list |
| `direct-messages` | DMs panel, below "Create Chat" and above the CHATS dropdown |
#### UI Locations — Icon Buttons
| Location | Where it appears |
|---|---|
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
| `composer-actions` | Left side of the composer, beside the `+` attach button |
| `room-header` | Top room header bar, before the ⋮ menu |
| `room-menu` | Room ⋮ dropdown menu |
| `message-actions` | Message hover action bar |
| `user-menu` | Right-click popup on the user avatar |
| `search-notification-section` | Notifications page header (right side) |
| `sidebar-actions` | Left sidebar — above Explore Servers icon, and above Search icon in the sticky bottom section |
| Location | Where it appears |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
| `composer-actions` | Left side of the composer, beside the `+` attach button |
| `room-header` | Top room header bar, before the ⋮ menu |
| `room-menu` | Room ⋮ dropdown menu |
| `message-actions` | Message hover action bar |
| `user-menu` | Right-click popup on the user avatar |
| `search-notification-section` | Notifications page header (right side) |
| `sidebar-actions` | Left sidebar — above Explore Servers icon, and above Search icon in the sticky bottom section |
#### Positioning
@@ -390,9 +398,9 @@ ctx.ui.registerButton({
position: {
after: 'emoji-picker-button',
group: 'my-tools',
order: 1
order: 1,
},
onClick: () => ctx.log('clicked!')
onClick: () => ctx.log('clicked!'),
});
```
@@ -407,10 +415,17 @@ ctx.ui.unregisterButton('my-button');
```typescript
type UILocation =
| 'channel-list' | 'direct-messages' | 'home-section'
| 'text-composer-toolbar' | 'composer-actions'
| 'room-header' | 'room-menu' | 'message-actions'
| 'user-menu' | 'search-notification-section' | 'sidebar-actions';
| 'channel-list'
| 'direct-messages'
| 'home-section'
| 'text-composer-toolbar'
| 'composer-actions'
| 'room-header'
| 'room-menu'
| 'message-actions'
| 'user-menu'
| 'search-notification-section'
| 'sidebar-actions';
interface UIButtonDefinition {
id: string;
@@ -443,47 +458,47 @@ Define settings that users can configure in the UI.
ctx.settings.define({
// Boolean toggle
enableFeature: {
type: "boolean",
label: "Enable Feature",
description: "Toggle this feature on/off",
default: true
type: 'boolean',
label: 'Enable Feature',
description: 'Toggle this feature on/off',
default: true,
},
// String input
apiKey: {
type: "string",
label: "API Key",
description: "Your API key",
default: ""
type: 'string',
label: 'API Key',
description: 'Your API key',
default: '',
},
// Number input
maxRetries: {
type: "number",
label: "Max Retries",
description: "Maximum retry attempts",
default: 3
type: 'number',
label: 'Max Retries',
description: 'Maximum retry attempts',
default: 3,
},
// Select dropdown
theme: {
type: "select",
label: "Theme",
description: "Choose a theme",
type: 'select',
label: 'Theme',
description: 'Choose a theme',
options: [
{ value: "dark", label: "Dark Mode" },
{ value: "light", label: "Light Mode" }
{ value: 'dark', label: 'Dark Mode' },
{ value: 'light', label: 'Light Mode' },
],
default: "dark"
default: 'dark',
},
// Color picker
accentColor: {
type: "color",
label: "Accent Color",
description: "Choose your accent color",
default: "#6366f1"
}
type: 'color',
label: 'Accent Color',
description: 'Choose your accent color',
default: '#6366f1',
},
});
```
@@ -528,9 +543,9 @@ Register custom themes that appear in the theme selector dropdown. Themes use CS
```javascript
ctx.themes.register({
id: "my-theme",
name: "My Custom Theme",
kind: "dark", // "light" or "dark"
id: 'my-theme',
name: 'My Custom Theme',
kind: 'dark', // "light" or "dark"
css: `
body.plugin-my-plugin-my-theme {
background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
@@ -543,7 +558,7 @@ ctx.themes.register({
.plugin-my-plugin-my-theme {
--tc-link: hsl(213, 100%, 80%);
}
`
`,
});
```
@@ -563,6 +578,7 @@ Example: plugin ID `my-plugin` + theme ID `dark-blue` = `.plugin-my-plugin-dark-
#### CSS Custom Properties
Available CSS variables you can override:
- `--tc-link` - Link color
- `--mx-uc-1` through `--mx-uc-8` - Matrix user ID colors (for different users)
- `--font-emoji` - Emoji font family
@@ -571,6 +587,7 @@ Available CSS variables you can override:
#### Styling Elements
Common selectors to style:
- `body.plugin-{pluginId}-{themeId}` - Body background
- `.plugin-{pluginId}-{themeId} #root` - Main app container
- `.plugin-{pluginId}-{themeId} [role="navigation"]` - Navigation sidebar
@@ -582,11 +599,12 @@ Common selectors to style:
#### Examples
**Dark Theme with Gradients:**
```javascript
ctx.themes.register({
id: "midnight",
name: "Midnight Blue 🌙",
kind: "dark",
id: 'midnight',
name: 'Midnight Blue 🌙',
kind: 'dark',
css: `
body.plugin-my-plugin-midnight {
background: linear-gradient(135deg, #0a192f 0%, #112240 50%, #1a365d 100%);
@@ -613,16 +631,17 @@ ctx.themes.register({
.plugin-my-plugin-midnight {
--tc-link: hsl(213, 100%, 80%);
}
`
`,
});
```
**Light Theme:**
```javascript
ctx.themes.register({
id: "sunrise",
name: "Sunrise ☀️",
kind: "light",
id: 'sunrise',
name: 'Sunrise ☀️',
kind: 'light',
css: `
body.plugin-my-plugin-sunrise {
background: linear-gradient(135deg, #fff4e6 0%, #ffe0b2 50%, #ffcc80 100%);
@@ -645,16 +664,17 @@ ctx.themes.register({
.plugin-my-plugin-sunrise {
--tc-link: hsl(30, 100%, 40%);
}
`
`,
});
```
**Minimal Theme:**
```javascript
ctx.themes.register({
id: "forest",
name: "Forest Green 🌲",
kind: "dark",
id: 'forest',
name: 'Forest Green 🌲',
kind: 'dark',
css: `
body.plugin-my-plugin-forest {
background: #1a2f23;
@@ -671,14 +691,14 @@ ctx.themes.register({
--mx-uc-7: hsl(135, 60%, 70%);
--mx-uc-8: hsl(155, 60%, 70%);
}
`
`,
});
```
#### Unregister Theme
```javascript
ctx.themes.unregister("my-theme");
ctx.themes.unregister('my-theme');
```
#### API Reference
@@ -699,6 +719,7 @@ interface PluginTheme {
```
**Notes:**
- CSS is injected once when the plugin loads (not per theme change)
- Theme IDs are automatically prefixed with `plugin-{pluginId}-` to avoid conflicts
- Theme class names follow the pattern: `.plugin-{pluginId}-{themeId}`
@@ -717,19 +738,19 @@ Hook into raw Matrix events for advanced functionality.
```javascript
// Room messages
ctx.matrix.on("m.room.message", (event) => {
ctx.matrix.on('m.room.message', (event) => {
const content = event.getContent();
ctx.log('Message:', content.body);
});
// Membership changes
ctx.matrix.on("m.room.member", (event) => {
ctx.matrix.on('m.room.member', (event) => {
const content = event.getContent();
ctx.log('Membership:', content.membership);
});
// Timeline events
ctx.matrix.on("Room.timeline", (event) => {
ctx.matrix.on('Room.timeline', (event) => {
if (event.getType() === 'm.room.message') {
const sender = event.getSender();
ctx.log('Timeline event from:', sender);
@@ -737,7 +758,7 @@ ctx.matrix.on("Room.timeline", (event) => {
});
// Sync state
ctx.matrix.on("sync", (state, prevState) => {
ctx.matrix.on('sync', (state, prevState) => {
ctx.log('Sync state:', state);
});
```
@@ -749,10 +770,10 @@ const handler = (event) => {
ctx.log('Event received');
};
ctx.matrix.on("m.room.message", handler);
ctx.matrix.on('m.room.message', handler);
// Later...
ctx.matrix.off("m.room.message", handler);
ctx.matrix.off('m.room.message', handler);
```
#### API Reference
@@ -765,6 +786,7 @@ interface MatrixEventsAPI {
```
**Common Event Types:**
- `m.room.message` - Room messages
- `m.room.member` - Membership changes
- `m.room.name` - Room name changes
@@ -784,11 +806,11 @@ Run periodic tasks or delayed actions.
// Run every 30 seconds
const intervalId = ctx.timers.setInterval(() => {
ctx.log('Periodic task running');
// Do something periodically
const stats = {
timestamp: Date.now(),
setting: ctx.settings.get('theme')
setting: ctx.settings.get('theme'),
};
ctx.log('Stats:', stats);
}, 30000);
@@ -805,9 +827,9 @@ const timeoutId = ctx.timers.setTimeout(() => {
ctx.notify({
title: 'Reminder',
body: 'This is a delayed notification',
type: 'info'
type: 'info',
});
}, 10000); // 10 seconds
}, 10000); // 10 seconds
// Clear timeout
ctx.timers.clearTimeout(timeoutId);
@@ -844,8 +866,8 @@ ctx.notify('Hello, world!');
ctx.notify({
title: 'Plugin Alert',
body: 'Something important happened!',
type: 'info', // 'info' | 'success' | 'error' | 'warning'
duration: 5000 // milliseconds (optional)
type: 'info', // 'info' | 'success' | 'error' | 'warning'
duration: 5000, // milliseconds (optional)
});
```
@@ -856,30 +878,28 @@ ctx.notify({
ctx.notify({
title: 'Success',
body: 'Operation completed successfully!',
type: 'success'
type: 'success',
});
// Error notification
ctx.notify({
title: 'Error',
body: 'Something went wrong',
type: 'error'
type: 'error',
});
// Warning
ctx.notify({
title: 'Warning',
body: 'This action cannot be undone',
type: 'warning'
type: 'warning',
});
```
#### API Reference
```typescript
type NotificationFunction = (
options: NotificationOptions | string
) => void;
type NotificationFunction = (options: NotificationOptions | string) => void;
interface NotificationOptions {
title: string;
@@ -916,13 +936,14 @@ ctx.error('Error details:', errorObject);
type LogFunction = (...args: any[]) => void;
interface PluginContext {
log: LogFunction; // Info level
warn: LogFunction; // Warning level
error: LogFunction; // Error level
log: LogFunction; // Info level
warn: LogFunction; // Warning level
error: LogFunction; // Error level
}
```
**Note:** All logs are visible in:
- Browser console (F12)
- Plugin logs panel (Settings → Plugins → Logs) - coming soon
@@ -937,21 +958,21 @@ Export functions and data for other plugins to use.
```javascript
module.exports = {
// ... onLoad, onUnload ...
exports: {
version: "1.0.0",
version: '1.0.0',
utils: {
greet: (name) => `Hello, ${name}!`,
processText: (text) => text.toUpperCase(),
getStats: () => ({
version: "1.0.0",
features: ['commands', 'settings']
})
}
}
version: '1.0.0',
features: ['commands', 'settings'],
}),
},
},
};
```
@@ -963,11 +984,11 @@ const otherPlugin = ctx.require('other-plugin-id');
if (otherPlugin) {
const greeting = otherPlugin.utils.greet('World');
ctx.log(greeting); // "Hello, World!"
ctx.log(greeting); // "Hello, World!"
const processed = otherPlugin.utils.processText('hello');
ctx.log(processed); // "HELLO"
ctx.log(processed); // "HELLO"
const stats = otherPlugin.utils.getStats();
ctx.log('Stats:', stats);
}
@@ -1018,7 +1039,7 @@ ctx.log('Sync state:', syncState);
// Send custom event
await ctx.matrixClient.sendEvent(roomId, 'm.room.message', {
msgtype: 'm.text',
body: 'Hello from plugin!'
body: 'Hello from plugin!',
});
```
@@ -1026,7 +1047,7 @@ await ctx.matrixClient.sendEvent(roomId, 'm.room.message', {
```typescript
interface PluginContext {
matrixClient: MatrixClient; // Full Matrix.js SDK client
matrixClient: MatrixClient; // Full Matrix.js SDK client
}
```
@@ -1043,122 +1064,122 @@ Here's a complete plugin that demonstrates all features:
* Example Plugin - All Features
*/
module.exports = {
name: "Example Plugin",
version: "1.0.0",
name: 'Example Plugin',
version: '1.0.0',
dependencies: {},
onLoad: async (ctx) => {
ctx.log('🚀 Plugin loading...');
// === COMMANDS ===
ctx.commands.register({
name: "hello",
description: "Say hello",
run: () => "Hello, world!"
name: 'hello',
description: 'Say hello',
run: () => 'Hello, world!',
});
ctx.commands.register({
name: "greet",
description: "Greet someone",
args: ["name"],
run: ({ name }) => `Hello, ${name}!`
name: 'greet',
description: 'Greet someone',
args: ['name'],
run: ({ name }) => `Hello, ${name}!`,
});
// === INTERCEPTORS ===
ctx.messages.onBeforeSend((msg) => {
// Auto-expand abbreviations
msg.content = msg.content.replace(/\bbrb\b/gi, 'be right back');
// Add emoji if enabled
if (ctx.settings.get('addEmoji')) {
msg.content += ' ✨';
}
});
ctx.messages.onReceive((msg) => {
// Track keywords
const keywords = ctx.settings.get('keywords') || '';
keywords.split(',').forEach(keyword => {
keywords.split(',').forEach((keyword) => {
if (msg.content.includes(keyword.trim())) {
ctx.notify(`Keyword detected: ${keyword}`);
}
});
});
// === SETTINGS ===
ctx.settings.define({
addEmoji: {
type: "boolean",
label: "Add Emoji",
description: "Add sparkles to messages",
default: false
type: 'boolean',
label: 'Add Emoji',
description: 'Add sparkles to messages',
default: false,
},
keywords: {
type: "string",
label: "Track Keywords",
description: "Comma-separated keywords to track",
default: "important,urgent"
type: 'string',
label: 'Track Keywords',
description: 'Comma-separated keywords to track',
default: 'important,urgent',
},
theme: {
type: "select",
label: "Theme",
type: 'select',
label: 'Theme',
options: [
{ value: "light", label: "Light" },
{ value: "dark", label: "Dark" }
{ value: 'light', label: 'Light' },
{ value: 'dark', label: 'Dark' },
],
default: "dark"
}
default: 'dark',
},
});
// === THEMES ===
ctx.themes.register({
id: "example-theme",
name: "Example Theme",
kind: "dark",
id: 'example-theme',
name: 'Example Theme',
kind: 'dark',
colors: {
background: "#1a1a2e",
surface: "#16213e",
primary: "#0f3460",
secondary: "#533483",
onBackground: "#ffffff",
onSurface: "#e0e0e0"
}
background: '#1a1a2e',
surface: '#16213e',
primary: '#0f3460',
secondary: '#533483',
onBackground: '#ffffff',
onSurface: '#e0e0e0',
},
});
// === MATRIX EVENTS ===
ctx.matrix.on("m.room.message", (event) => {
ctx.matrix.on('m.room.message', (event) => {
const content = event.getContent();
if (content.body?.includes('example')) {
ctx.log('Keyword found in message');
}
});
// === BACKGROUND TASKS ===
ctx.timers.setInterval(() => {
ctx.log('Periodic check');
}, 60000); // Every minute
}, 60000); // Every minute
// === NOTIFICATIONS ===
ctx.notify({
title: 'Example Plugin',
body: 'Plugin loaded successfully!',
type: 'success'
type: 'success',
});
// === EXPORTS ===
this.exports = {
version: "1.0.0",
greet: (name) => `Hello, ${name}!`
version: '1.0.0',
greet: (name) => `Hello, ${name}!`,
};
ctx.log('✅ Plugin loaded');
},
onUnload: async () => {
console.log('Plugin unloaded');
},
exports: null
exports: null,
};
```
@@ -1179,10 +1200,10 @@ onLoad: async (ctx) => {
ctx.notify({
title: 'Plugin Error',
body: error.message,
type: 'error'
type: 'error',
});
}
}
};
```
### Cleanup
@@ -1194,9 +1215,9 @@ onUnload: async () => {
// Timers are auto-cleared
// Event handlers are auto-removed
// Settings are persisted automatically
console.log('Plugin unloaded');
}
};
```
### Settings Validation
@@ -1205,7 +1226,7 @@ Validate settings before use:
```javascript
const maxRetries = ctx.settings.get('maxRetries') || 3;
const keywords = (ctx.settings.get('keywords') || '').split(',').filter(k => k.trim());
const keywords = (ctx.settings.get('keywords') || '').split(',').filter((k) => k.trim());
```
### Logging
@@ -1213,9 +1234,9 @@ const keywords = (ctx.settings.get('keywords') || '').split(',').filter(k => k.t
Use appropriate log levels:
```javascript
ctx.log('Info message'); // Normal operation
ctx.warn('Warning message'); // Potential issues
ctx.error('Error message'); // Actual errors
ctx.log('Info message'); // Normal operation
ctx.warn('Warning message'); // Potential issues
ctx.error('Error message'); // Actual errors
```
### Performance
+64 -65
View File
@@ -15,26 +15,26 @@ Buttons render in two visual styles depending on location — **nav list rows**
These render as full-width list entries matching the style of built-in items like "Create Room" and "Message Search":
| Location | Where it appears |
|---|---|
| `channel-list` | Space channel list, below Lobby and Message Search |
| `home-section` | Home panel, inside the Rooms category above the room list |
| Location | Where it appears |
| ----------------- | ----------------------------------------------------------------------- |
| `channel-list` | Space channel list, below Lobby and Message Search |
| `home-section` | Home panel, inside the Rooms category above the room list |
| `direct-messages` | Direct Messages panel, below "Create Chat" and above the CHATS dropdown |
### Icon Buttons
These render as compact icon buttons inline with other toolbar/header controls:
| Location | Where it appears |
|---|---|
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
| `composer-actions` | Left side of the composer, beside the `+` attach button |
| `room-header` | Top room header bar, before the ⋮ menu button |
| `room-menu` | Room ⋮ dropdown menu |
| `message-actions` | Message hover action bar |
| `user-menu` | Right-click popup on the user avatar |
| `search-notification-section` | Notifications page header (right side) |
| `sidebar-actions` | Left sidebar — appears in **two** places: above the Explore Servers icon, and above the Search icon in the sticky bottom section |
| Location | Where it appears |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
| `composer-actions` | Left side of the composer, beside the `+` attach button |
| `room-header` | Top room header bar, before the ⋮ menu button |
| `room-menu` | Room ⋮ dropdown menu |
| `message-actions` | Message hover action bar |
| `user-menu` | Right-click popup on the user avatar |
| `search-notification-section` | Notifications page header (right side) |
| `sidebar-actions` | Left sidebar — appears in **two** places: above the Explore Servers icon, and above the Search icon in the sticky bottom section |
> 💡 **Tip:** Install the [example-showcase-plugin](example-showcase-plugin/) to see exactly where each location appears in the UI!
@@ -46,7 +46,7 @@ These render as compact icon buttons inline with other toolbar/header controls:
module.exports = {
name: 'my-plugin',
version: '1.0.0',
onLoad: (context) => {
context.ui.registerButton({
id: 'my-button',
@@ -55,13 +55,13 @@ module.exports = {
icon: '🎨',
onClick: () => {
context.log('Button clicked!');
}
},
});
},
onUnload: () => {
// Buttons are automatically cleaned up on plugin unload
}
},
};
```
@@ -80,8 +80,8 @@ context.ui.registerButton({
position: {
before: 'emoji-picker-button', // Place before emoji picker
// OR
after: 'sticker-button' // Place after sticker button
}
after: 'sticker-button', // Place after sticker button
},
});
```
@@ -97,8 +97,8 @@ context.ui.registerButton({
icon: '1️⃣',
position: {
group: 'my-plugin-tools',
order: 1 // Lower numbers appear first
}
order: 1, // Lower numbers appear first
},
});
context.ui.registerButton({
@@ -108,8 +108,8 @@ context.ui.registerButton({
icon: '2️⃣',
position: {
group: 'my-plugin-tools',
order: 2
}
order: 2,
},
});
```
@@ -126,8 +126,8 @@ context.ui.registerButton({
position: {
group: 'my-tools',
after: 'emoji-picker-button',
order: 1
}
order: 1,
},
});
context.ui.registerButton({
@@ -137,8 +137,8 @@ context.ui.registerButton({
icon: '🔨',
position: {
group: 'my-tools',
order: 2
}
order: 2,
},
});
```
@@ -148,7 +148,7 @@ context.ui.registerButton({
module.exports = {
name: 'custom-tools',
version: '1.0.0',
onLoad: (context) => {
// Nav list row — appears below "Create Chat" in the DMs panel
context.ui.registerButton({
@@ -156,7 +156,7 @@ module.exports = {
location: 'direct-messages',
label: 'Favourites',
icon: '⭐',
onClick: () => context.log('Favourites clicked!')
onClick: () => context.log('Favourites clicked!'),
});
// Nav list row — appears in the space channel list
@@ -165,7 +165,7 @@ module.exports = {
location: 'channel-list',
label: 'Quick Access',
icon: '⚡',
onClick: () => context.log('Quick access clicked!')
onClick: () => context.log('Quick access clicked!'),
});
// Icon button — appears in the message composer toolbar
@@ -176,9 +176,9 @@ module.exports = {
icon: '𝐁',
position: {
group: 'custom-formatting',
order: 1
order: 1,
},
onClick: () => context.log('Bold clicked!')
onClick: () => context.log('Bold clicked!'),
});
// Icon button — appears in the room header
@@ -188,7 +188,7 @@ module.exports = {
label: 'Special Search',
icon: '🔍',
position: { after: 'search-button' },
onClick: () => context.log('Special search clicked!')
onClick: () => context.log('Special search clicked!'),
});
// Sidebar icon — appears above Explore and above Search
@@ -197,13 +197,13 @@ module.exports = {
location: 'sidebar-actions',
label: 'Plugin Panel',
icon: '🧩',
onClick: () => context.log('Plugin panel clicked!')
onClick: () => context.log('Plugin panel clicked!'),
});
},
onUnload: () => {
// All registered buttons are automatically cleaned up
}
},
};
```
@@ -228,13 +228,12 @@ const button: UIButtonDefinition = {
position: {
group: 'my-tools',
after: 'emoji-picker',
order: 1
order: 1,
},
onClick: () => console.log('Clicked!')
onClick: () => console.log('Clicked!'),
};
```
## Basic Usage
### Simple Button
@@ -243,7 +242,7 @@ const button: UIButtonDefinition = {
module.exports = {
name: 'my-plugin',
version: '1.0.0',
onLoad: (context) => {
context.ui.registerButton({
id: 'my-button',
@@ -252,13 +251,13 @@ module.exports = {
icon: '🎨',
onClick: () => {
context.log('Button clicked!');
}
},
});
},
onUnload: () => {
// Buttons are automatically cleaned up on plugin unload
}
},
};
```
@@ -277,8 +276,8 @@ context.ui.registerButton({
position: {
before: 'emoji-picker-button', // Place before emoji picker
// OR
after: 'sticker-button' // Place after sticker button
}
after: 'sticker-button', // Place after sticker button
},
});
```
@@ -294,8 +293,8 @@ context.ui.registerButton({
icon: '1️⃣',
position: {
group: 'my-plugin-tools',
order: 1 // Lower numbers appear first
}
order: 1, // Lower numbers appear first
},
});
context.ui.registerButton({
@@ -305,8 +304,8 @@ context.ui.registerButton({
icon: '2️⃣',
position: {
group: 'my-plugin-tools',
order: 2
}
order: 2,
},
});
```
@@ -323,8 +322,8 @@ context.ui.registerButton({
position: {
group: 'my-tools',
after: 'emoji-picker-button',
order: 1
}
order: 1,
},
});
context.ui.registerButton({
@@ -334,8 +333,8 @@ context.ui.registerButton({
icon: '🔨',
position: {
group: 'my-tools',
order: 2
}
order: 2,
},
});
```
@@ -345,7 +344,7 @@ context.ui.registerButton({
module.exports = {
name: 'custom-tools',
version: '1.0.0',
onLoad: (context) => {
// Nav list row — appears below "Create Chat" in the DMs panel
context.ui.registerButton({
@@ -353,7 +352,7 @@ module.exports = {
location: 'direct-messages',
label: 'Favourites',
icon: '⭐',
onClick: () => context.log('Favourites clicked!')
onClick: () => context.log('Favourites clicked!'),
});
// Nav list row — appears in the space channel list
@@ -362,7 +361,7 @@ module.exports = {
location: 'channel-list',
label: 'Quick Access',
icon: '⚡',
onClick: () => context.log('Quick access clicked!')
onClick: () => context.log('Quick access clicked!'),
});
// Icon button — appears in the message composer toolbar
@@ -373,9 +372,9 @@ module.exports = {
icon: '𝐁',
position: {
group: 'custom-formatting',
order: 1
order: 1,
},
onClick: () => context.log('Bold clicked!')
onClick: () => context.log('Bold clicked!'),
});
// Icon button — appears in the room header
@@ -385,7 +384,7 @@ module.exports = {
label: 'Special Search',
icon: '🔍',
position: { after: 'search-button' },
onClick: () => context.log('Special search clicked!')
onClick: () => context.log('Special search clicked!'),
});
// Sidebar icon — appears above Explore and above Search
@@ -394,13 +393,13 @@ module.exports = {
location: 'sidebar-actions',
label: 'Plugin Panel',
icon: '🧩',
onClick: () => context.log('Plugin panel clicked!')
onClick: () => context.log('Plugin panel clicked!'),
});
},
onUnload: () => {
// All registered buttons are automatically cleaned up
}
},
};
```
@@ -425,8 +424,8 @@ const button: UIButtonDefinition = {
position: {
group: 'my-tools',
after: 'emoji-picker',
order: 1
order: 1,
},
onClick: () => console.log('Clicked!')
onClick: () => console.log('Clicked!'),
};
```
+35 -16
View File
@@ -5,18 +5,21 @@ All requested features have been implemented! 🎉
## ✅ Implemented Features
### 1. ✅ Enhanced Slash Commands
- **Simple commands**: `ctx.commands.register({ name: "shrug", run: () => "¯\\_(ツ)_/¯" })`
- **Commands with args**: `ctx.commands.register({ name: "echo", args: ["text"], run: ({ text }) => text })`
- Automatic argument parsing
- Execution API: `ctx.commands.execute(name, args)`
### 2. ✅ Message Interceptors
- **Before send**: `ctx.messages.onBeforeSend((msg) => { msg.content = "modified" })`
- **On receive**: `ctx.messages.onReceive((msg) => { /* process */ })`
- Full MessageContext with content, roomId, metadata
- Async support for interceptors
### 3. ✅ Custom Renderers & Button Registration
- **Register renderer**: `ctx.ui.registerRenderer("message", (msg, defaultRenderer) => { /* render */ })`
- **Unregister renderer**: `ctx.ui.unregisterRenderer("message")`
- **Register button**: `ctx.ui.registerButton({ id, location, label, icon, onClick })`
@@ -29,6 +32,7 @@ All requested features have been implemented! 🎉
- See [PLUGIN_BUTTON_API.md](PLUGIN_BUTTON_API.md) for full reference
### 4. ✅ Settings UI Per Plugin
- **Define schema**: `ctx.settings.define({ theme: { type: "select", options: [...] } })`
- **Supported types**: string, number, boolean, select, color
- **Get/Set**: `ctx.settings.get(key)` / `ctx.settings.set(key, value)`
@@ -36,24 +40,28 @@ All requested features have been implemented! 🎉
- No JSON editing needed!
### 5. ✅ Hot Reload
- **API**: `pluginRegistry.reloadPlugin(pluginId, newPlugin, newContext)`
- Auto-cleanup of old plugin resources
- Maintains enabled/disabled state
- Dev-friendly workflow
### 6. ✅ Dependency System
- **Declare**: `dependencies: { "paarrot.core-utils": "^1.0.0" }`
- **Require**: `const utils = ctx.require("paarrot.utils")`
- Error handling for missing dependencies
- Plugin exports system
### 7. ✅ Raw Matrix Events Hook
- **Full SDK access**: `ctx.matrix.on("m.room.message", (ev) => { })`
- **Any event type**: Room.timeline, sync, RoomState.events, etc.
- Direct Matrix.js SDK integration
- Power users will go nuts!
### 8. ✅ Background Tasks / Intervals
- **Interval**: `ctx.timers.setInterval(() => { /* cursed shit */ }, 10000)`
- **Timeout**: `ctx.timers.setTimeout(() => { }, 5000)`
- **Clear**: `ctx.timers.clearInterval(id)` / `ctx.timers.clearTimeout(id)`
@@ -61,12 +69,14 @@ All requested features have been implemented! 🎉
- Perfect for bots, reminders, auto-cleanup
### 9. ✅ Notifications API
- **Simple**: `ctx.notify("Oi")`
- **Advanced**: `ctx.notify({ title: "Oi", body: "New message from Steve", type: "info" })`
- Action buttons support
- Custom duration
### 10. ✅ Plugin Logs Panel
- **Logging**: `ctx.log()`, `ctx.warn()`, `ctx.error()`
- Per-plugin log storage
- Visible in `pluginRegistry.getLogs(pluginId)`
@@ -85,16 +95,19 @@ All requested features have been implemented! 🎉
## 📁 Files Changed
### Core System
- [`PluginAPI.ts`](cinny/src/app/features/settings/plugins/PluginAPI.ts) - Enhanced with all APIs
- [`PluginLoader.tsx`](cinny/src/app/features/settings/plugins/PluginLoader.tsx) - Complete rewrite with context creation
- [`index.ts`](cinny/src/app/features/settings/plugins/index.ts) - Exports updated
### Documentation
- [`PLUGIN_DEVELOPMENT.md`](cinny/src/app/features/settings/plugins/PLUGIN_DEVELOPMENT.md) - Comprehensive guide
- [`PLUGINS.md`](PLUGINS.md) - User guide
- [`example-plugin/index.js`](example-plugin/index.js) - Full-featured example
### Integration
- [`ClientRoot.tsx`](cinny/src/app/pages/client/ClientRoot.tsx) - PluginLoader integrated
- [`main.js`](electron/main.js) - IPC handler for reading plugin code
- [`preload.js`](electron/preload.js) - readPluginCode API exposed
@@ -103,32 +116,36 @@ All requested features have been implemented! 🎉
## 🚀 Usage Examples
### Command with Args
```javascript
ctx.commands.register({
name: "echo",
args: ["text"],
run: ({ text }) => text
name: 'echo',
args: ['text'],
run: ({ text }) => text,
});
```
### Message Interceptor
```javascript
ctx.messages.onBeforeSend((msg) => {
if (msg.content === "brb") {
msg.content = "be right back ya legend";
if (msg.content === 'brb') {
msg.content = 'be right back ya legend';
}
});
```
### Custom Settings
```javascript
ctx.settings.define({
theme: { type: "select", options: ["dark", "light"] },
spamFilter: { type: "boolean", default: true }
theme: { type: 'select', options: ['dark', 'light'] },
spamFilter: { type: 'boolean', default: true },
});
```
### Background Tasks
```javascript
ctx.timers.setInterval(() => {
// do cursed shit every 10s
@@ -136,15 +153,17 @@ ctx.timers.setInterval(() => {
```
### Raw Matrix Events
```javascript
ctx.matrix.on("m.room.message", (ev) => {
ctx.matrix.on('m.room.message', (ev) => {
ctx.log('Message:', ev.getContent().body);
});
```
### Plugin Dependencies
```javascript
const utils = ctx.require("paarrot.utils");
const utils = ctx.require('paarrot.utils');
utils.doSomething();
```
@@ -155,43 +174,43 @@ interface PluginContext {
pluginId: string;
matrixClient: MatrixClient;
React: typeof import('react');
commands: {
register: (command: PluginCommand) => void;
unregister: (name: string) => void;
execute: (name: string, args: Record<string, any>) => Promise<string | void>;
};
messages: {
onBeforeSend: (interceptor: MessageInterceptor) => void;
onReceive: (interceptor: MessageInterceptor) => void;
};
ui: {
registerButton: (button: UIButtonDefinition) => void;
unregisterButton: (id: string) => void;
registerRenderer: (type: string, renderer: CustomRenderer) => void;
unregisterRenderer: (type: string) => void;
};
settings: {
define: (schema: SettingsSchema) => void;
get: <T = any>(key: string) => T | undefined;
set: (key: string, value: any) => void;
};
matrix: {
on: (eventType: string, handler: (event: MatrixEvent) => void) => void;
off: (eventType: string, handler: (event: MatrixEvent) => void) => void;
};
timers: {
setInterval: (callback: () => void, ms: number) => number;
setTimeout: (callback: () => void, ms: number) => number;
clearInterval: (id: number) => void;
clearTimeout: (id: number) => void;
};
notify: (options: NotificationOptions | string) => void;
log: (...args: any[]) => void;
warn: (...args: any[]) => void;
+4 -4
View File
@@ -20,8 +20,8 @@
## Key files
| Path | Role |
|------|------|
| Path | Role |
| -------------- | --------------------- |
| `path/to/file` | <!-- what it does --> |
## Data model
@@ -29,8 +29,8 @@
<!-- Matrix state events, account data types, local storage keys. -->
| Key / event | Scope | Shape |
|-------------|-------|-------|
| | | |
| ----------- | ----- | ----- |
| | | |
## Dependencies
+8 -8
View File
@@ -25,14 +25,14 @@ tauri.ts → native notification APIs
## Key files
| Path | Role |
|------|------|
| `cinny/capacitor.config.json` | Capacitor app id, web dir |
| `src-tauri/src/main.rs` | Tauri Android entry |
| `cinny/src/app/utils/tauri.ts` | Platform detection, notifications |
| `cinny/src/app/utils/backgroundSync.ts` | UnifiedPush registration |
| `cinny/src/app/utils/androidShare.ts` | Share target handling |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Share listener wiring |
| Path | Role |
| ---------------------------------------------------- | --------------------------------- |
| `cinny/capacitor.config.json` | Capacitor app id, web dir |
| `src-tauri/src/main.rs` | Tauri Android entry |
| `cinny/src/app/utils/tauri.ts` | Platform detection, notifications |
| `cinny/src/app/utils/backgroundSync.ts` | UnifiedPush registration |
| `cinny/src/app/utils/androidShare.ts` | Share target handling |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Share listener wiring |
## Data model
+20 -20
View File
@@ -25,29 +25,29 @@ ClientRoot (authenticated)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/auth/login/Login.tsx` | Login hub |
| `cinny/src/app/pages/auth/login/PasswordLoginForm.tsx` | Password login |
| `cinny/src/app/pages/auth/login/TokenLogin.tsx` | Access token login |
| `cinny/src/app/pages/auth/SSOLogin.tsx` | SSO redirect |
| `cinny/src/app/pages/auth/register/Register.tsx` | Registration |
| `cinny/src/app/pages/auth/register/PasswordRegisterForm.tsx` | Password register |
| `cinny/src/app/pages/auth/reset-password/ResetPassword.tsx` | Password reset |
| `cinny/src/app/pages/auth/ServerPicker.tsx` | Homeserver selection |
| `cinny/src/app/pages/auth/AuthLayout.tsx` | Auth chrome + logo |
| `cinny/src/app/pages/auth/login/loginUtil.ts` | Login helpers |
| `cinny/src/app/pages/auth/register/registerUtil.ts` | Register helpers |
| `cinny/src/app/state/sessions.ts` | Session storage |
| `cinny/src/client/initMatrix.ts` | Client init from session |
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Post-login redirect |
| Path | Role |
| ------------------------------------------------------------ | ------------------------ |
| `cinny/src/app/pages/auth/login/Login.tsx` | Login hub |
| `cinny/src/app/pages/auth/login/PasswordLoginForm.tsx` | Password login |
| `cinny/src/app/pages/auth/login/TokenLogin.tsx` | Access token login |
| `cinny/src/app/pages/auth/SSOLogin.tsx` | SSO redirect |
| `cinny/src/app/pages/auth/register/Register.tsx` | Registration |
| `cinny/src/app/pages/auth/register/PasswordRegisterForm.tsx` | Password register |
| `cinny/src/app/pages/auth/reset-password/ResetPassword.tsx` | Password reset |
| `cinny/src/app/pages/auth/ServerPicker.tsx` | Homeserver selection |
| `cinny/src/app/pages/auth/AuthLayout.tsx` | Auth chrome + logo |
| `cinny/src/app/pages/auth/login/loginUtil.ts` | Login helpers |
| `cinny/src/app/pages/auth/register/registerUtil.ts` | Register helpers |
| `cinny/src/app/state/sessions.ts` | Session storage |
| `cinny/src/client/initMatrix.ts` | Client init from session |
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Post-login redirect |
## Data model
| Key | Storage | Content |
|-----|---------|---------|
| Session store | localStorage | access token, user id, device id, hs url |
| `setAfterLoginRedirectPath` | sessionStorage/memory | deep link target after login |
| Key | Storage | Content |
| --------------------------- | --------------------- | ---------------------------------------- |
| Session store | localStorage | access token, user id, device id, hs url |
| `setAfterLoginRedirectPath` | sessionStorage/memory | deep link target after login |
## Dependencies
@@ -24,25 +24,25 @@ Other clients / Profile.tsx
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/utils/imageMetadata.ts` | Unified embed/extract API |
| `cinny/src/app/utils/pngMetadata.ts` | PNG tEXt chunks |
| `cinny/src/app/utils/jpegMetadata.ts` | JPEG XMP APP1 |
| `cinny/src/app/utils/webpMetadata.ts` | WebP XMP |
| `cinny/src/app/utils/gifMetadata.ts` | GIF application extension |
| Path | Role |
| ----------------------------------------------------- | ----------------------------- |
| `cinny/src/app/utils/imageMetadata.ts` | Unified embed/extract API |
| `cinny/src/app/utils/pngMetadata.ts` | PNG tEXt chunks |
| `cinny/src/app/utils/jpegMetadata.ts` | JPEG XMP APP1 |
| `cinny/src/app/utils/webpMetadata.ts` | WebP XMP |
| `cinny/src/app/utils/gifMetadata.ts` | GIF application extension |
| `cinny/src/app/features/settings/account/Profile.tsx` | Settings UI + upload pipeline |
## Data model
Metadata keys (embedded in binary image, not Matrix):
| Key | Format | Notes |
|-----|--------|-------|
| `paarrot:color` | All | Accent color hex |
| `paarrot:banner` | PNG (+ unified API) | Banner image URL |
| `paarrot:borderColor` | PNG | Border accent |
| `paarrot:gradient` | PNG | Gradient spec |
| Key | Format | Notes |
| --------------------- | ------------------- | ---------------- |
| `paarrot:color` | All | Accent color hex |
| `paarrot:banner` | PNG (+ unified API) | Banner image URL |
| `paarrot:borderColor` | PNG | Border accent |
| `paarrot:gradient` | PNG | Gradient spec |
XMP namespace: `http://paarrot.app/ns/1.0/`
@@ -27,22 +27,22 @@ tauri.ts / electron main
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Favicon, notifications, API init, background sync hooks |
| `cinny/src/app/utils/backgroundSync.ts` | Pushers, UnifiedPush, foreground state |
| `cinny/src/app/utils/tauri.ts` | Tauri/Capacitor notification helpers |
| `cinny/src/app/features/settings/notifications/SystemNotification.tsx` | Permission UX |
| `electron/main.js` | Tray, notification IPC (if applicable) |
| `src-tauri/src/main.rs` | Tauri Android shell |
| Path | Role |
| ---------------------------------------------------------------------- | ------------------------------------------------------- |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Favicon, notifications, API init, background sync hooks |
| `cinny/src/app/utils/backgroundSync.ts` | Pushers, UnifiedPush, foreground state |
| `cinny/src/app/utils/tauri.ts` | Tauri/Capacitor notification helpers |
| `cinny/src/app/features/settings/notifications/SystemNotification.tsx` | Permission UX |
| `electron/main.js` | Tray, notification IPC (if applicable) |
| `src-tauri/src/main.rs` | Tauri Android shell |
## Data model
| Key | Storage | Purpose |
|-----|---------|---------|
| `paarrot.unifiedpush.*` | localStorage prefix | UP endpoint state |
| `com.paarrot.app.android` | Pusher app id base | Android pushers |
| Matrix pusher | Homeserver | HTTP push gateway |
| Key | Storage | Purpose |
| ------------------------- | ------------------- | ----------------- |
| `paarrot.unifiedpush.*` | localStorage prefix | UP endpoint state |
| `com.paarrot.app.android` | Pusher app id base | Android pushers |
| Matrix pusher | Homeserver | HTTP push gateway |
## Dependencies
+15 -15
View File
@@ -27,24 +27,24 @@ SpecVersions in ClientRoot
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/components/title-bar/TitleBar.tsx` | Desktop title bar |
| `cinny/src/app/components/splash-screen/SplashScreen.tsx` | Splash |
| `cinny/src/app/pages/client/WelcomePage.tsx` | Welcome / download links |
| `cinny/src/app/components/account-switcher/AccountSwitcher.tsx` | Multi-account |
| `cinny/src/app/components/update-notification/UpdateNotification.tsx` | Auto-update UI |
| `cinny/src/app/pages/FeatureCheck.tsx` | Browser capability gate |
| `cinny/src/app/pages/client/SpecVersions.tsx` | HS version warning |
| `cinny/src/app/pages/client/SyncStatus.tsx` | Sync indicator |
| `cinny/src/app/pages/ConfigConfig.tsx` | Config load error UI |
| `cinny/src/app/components/ClientConfigLoader.tsx` | Load config.json |
| Path | Role |
| --------------------------------------------------------------------- | ------------------------ |
| `cinny/src/app/components/title-bar/TitleBar.tsx` | Desktop title bar |
| `cinny/src/app/components/splash-screen/SplashScreen.tsx` | Splash |
| `cinny/src/app/pages/client/WelcomePage.tsx` | Welcome / download links |
| `cinny/src/app/components/account-switcher/AccountSwitcher.tsx` | Multi-account |
| `cinny/src/app/components/update-notification/UpdateNotification.tsx` | Auto-update UI |
| `cinny/src/app/pages/FeatureCheck.tsx` | Browser capability gate |
| `cinny/src/app/pages/client/SpecVersions.tsx` | HS version warning |
| `cinny/src/app/pages/client/SyncStatus.tsx` | Sync indicator |
| `cinny/src/app/pages/ConfigConfig.tsx` | Config load error UI |
| `cinny/src/app/components/ClientConfigLoader.tsx` | Load config.json |
## Data model
| Key | Storage |
|-----|---------|
| Sessions | multi-account in sessions.ts |
| Key | Storage |
| -------------- | ---------------------------- |
| Sessions | multi-account in sessions.ts |
| electron-store | window bounds (main process) |
## Dependencies
@@ -26,15 +26,15 @@ Imported by room-settings and space-settings shells
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/common-settings/general/RoomProfile.tsx` | Name/topic/avatar |
| `cinny/src/app/features/common-settings/general/RoomJoinRules.tsx` | Join rules |
| `cinny/src/app/features/common-settings/general/RoomEncryption.tsx` | E2E toggle |
| `cinny/src/app/features/common-settings/general/EmbedFilters.tsx` | Room-wide embed filters |
| `cinny/src/app/features/common-settings/members/Members.tsx` | Member management |
| `cinny/src/app/features/common-settings/permissions/PowersEditor.tsx` | Power levels |
| `cinny/src/app/features/common-settings/developer-tools/` | Dev event tools |
| Path | Role |
| --------------------------------------------------------------------- | ----------------------- |
| `cinny/src/app/features/common-settings/general/RoomProfile.tsx` | Name/topic/avatar |
| `cinny/src/app/features/common-settings/general/RoomJoinRules.tsx` | Join rules |
| `cinny/src/app/features/common-settings/general/RoomEncryption.tsx` | E2E toggle |
| `cinny/src/app/features/common-settings/general/EmbedFilters.tsx` | Room-wide embed filters |
| `cinny/src/app/features/common-settings/members/Members.tsx` | Member management |
| `cinny/src/app/features/common-settings/permissions/PowersEditor.tsx` | Power levels |
| `cinny/src/app/features/common-settings/developer-tools/` | Dev event tools |
## Data model
+12 -12
View File
@@ -26,18 +26,18 @@ State: createRoomModal.ts, createSpaceModal.ts
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/create-room/CreateRoomModal.tsx` | Room create + sub-room parent update |
| `cinny/src/app/features/create-space/CreateSpaceModal.tsx` | Space create |
| `cinny/src/app/features/create-chat/` | DM flows |
| `cinny/src/app/features/add-existing/AddExisting.tsx` | Add to space |
| `cinny/src/app/features/create-room/CreateRoom.tsx` | Standalone create page |
| `cinny/src/app/features/create-space/CreateSpace.tsx` | Standalone space create |
| `cinny/src/app/state/createRoomModal.ts` | Modal state + parent room id |
| `cinny/src/app/state/createSpaceModal.ts` | Space modal state |
| `cinny/src/app/pages/client/create/Create.tsx` | Create hub route |
| `cinny/src/app/pages/client/home/CreateRoom.tsx` | Home create entry |
| Path | Role |
| ---------------------------------------------------------- | ------------------------------------ |
| `cinny/src/app/features/create-room/CreateRoomModal.tsx` | Room create + sub-room parent update |
| `cinny/src/app/features/create-space/CreateSpaceModal.tsx` | Space create |
| `cinny/src/app/features/create-chat/` | DM flows |
| `cinny/src/app/features/add-existing/AddExisting.tsx` | Add to space |
| `cinny/src/app/features/create-room/CreateRoom.tsx` | Standalone create page |
| `cinny/src/app/features/create-space/CreateSpace.tsx` | Standalone space create |
| `cinny/src/app/state/createRoomModal.ts` | Modal state + parent room id |
| `cinny/src/app/state/createSpaceModal.ts` | Space modal state |
| `cinny/src/app/pages/client/create/Create.tsx` | Create hub route |
| `cinny/src/app/pages/client/home/CreateRoom.tsx` | Home create entry |
## Data model
@@ -23,23 +23,23 @@ settings emojis-stickers + common-settings emojis
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/plugins/custom-emoji/PackMetaReader.ts` | Read pack metadata |
| `cinny/src/app/plugins/custom-emoji/PackImageReader.ts` | Single image |
| `cinny/src/app/plugins/custom-emoji/PackImagesReader.ts` | Bulk images |
| `cinny/src/app/plugins/custom-emoji/ImagePack.ts` | Pack model |
| `cinny/src/app/plugins/custom-emoji/types.ts` | Types |
| `cinny/src/app/plugins/emoji.ts` | Shortcode rendering |
| `cinny/src/app/plugins/recent-emoji.ts` | Recent emoji helper |
| `cinny/src/app/components/image-pack-view/ImagePackView.tsx` | Pack browser UI |
| `cinny/src/app/hooks/useImagePackRooms.ts` | Rooms with packs |
| Path | Role |
| ------------------------------------------------------------ | ------------------- |
| `cinny/src/app/plugins/custom-emoji/PackMetaReader.ts` | Read pack metadata |
| `cinny/src/app/plugins/custom-emoji/PackImageReader.ts` | Single image |
| `cinny/src/app/plugins/custom-emoji/PackImagesReader.ts` | Bulk images |
| `cinny/src/app/plugins/custom-emoji/ImagePack.ts` | Pack model |
| `cinny/src/app/plugins/custom-emoji/types.ts` | Types |
| `cinny/src/app/plugins/emoji.ts` | Shortcode rendering |
| `cinny/src/app/plugins/recent-emoji.ts` | Recent emoji helper |
| `cinny/src/app/components/image-pack-view/ImagePackView.tsx` | Pack browser UI |
| `cinny/src/app/hooks/useImagePackRooms.ts` | Rooms with packs |
## Data model
| Event | Purpose |
|-------|---------|
| `im.ponies.room_emotes` | Room emoji pack definition |
| Event | Purpose |
| ----------------------- | -------------------------------------- |
| `im.ponies.room_emotes` | Room emoji pack definition |
| Image pack account data | User/global packs (see emoji-stickers) |
## Dependencies
@@ -21,13 +21,13 @@ common-settings/developer-tools/
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/settings/developer-tools/DevelopTools.tsx` | User-level dev tools |
| `cinny/src/app/features/settings/developer-tools/AccountData.tsx` | Account data viewer |
| `cinny/src/app/features/common-settings/developer-tools/DevelopTools.tsx` | Room dev tools entry |
| `cinny/src/app/features/common-settings/developer-tools/StateEventEditor.tsx` | Edit state events |
| `cinny/src/app/features/common-settings/developer-tools/SendRoomEvent.tsx` | Send events |
| Path | Role |
| ----------------------------------------------------------------------------- | -------------------- |
| `cinny/src/app/features/settings/developer-tools/DevelopTools.tsx` | User-level dev tools |
| `cinny/src/app/features/settings/developer-tools/AccountData.tsx` | Account data viewer |
| `cinny/src/app/features/common-settings/developer-tools/DevelopTools.tsx` | Room dev tools entry |
| `cinny/src/app/features/common-settings/developer-tools/StateEventEditor.tsx` | Edit state events |
| `cinny/src/app/features/common-settings/developer-tools/SendRoomEvent.tsx` | Send events |
## Data model
@@ -24,19 +24,19 @@ mDirectAtom — direct room index
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/client/direct/Direct.tsx` | DM list |
| `cinny/src/app/pages/client/direct/DirectCreate.tsx` | Create DM |
| `cinny/src/app/pages/client/direct/useDirectRooms.ts` | List logic |
| `cinny/src/app/pages/client/sidebar/DirectTab.tsx` | Sidebar tab |
| `cinny/src/app/state/mDirectList.ts` | `mDirectAtom` |
| `cinny/src/app/hooks/useDirectUsers.ts` | DM user helpers |
| Path | Role |
| ----------------------------------------------------- | --------------- |
| `cinny/src/app/pages/client/direct/Direct.tsx` | DM list |
| `cinny/src/app/pages/client/direct/DirectCreate.tsx` | Create DM |
| `cinny/src/app/pages/client/direct/useDirectRooms.ts` | List logic |
| `cinny/src/app/pages/client/sidebar/DirectTab.tsx` | Sidebar tab |
| `cinny/src/app/state/mDirectList.ts` | `mDirectAtom` |
| `cinny/src/app/hooks/useDirectUsers.ts` | DM user helpers |
## Data model
| Key | Scope |
|-----|-------|
| Key | Scope |
| ---------- | ------------------------------------------ |
| `m.direct` | User account data — map userId → roomIds[] |
## Dependencies
@@ -24,26 +24,26 @@ useSecretStorage, useKeyBackup, useVerificationRequest hooks
## Key files
| Path | Role |
|------|------|
| `cinny/src/client/secretStorageKeys.ts` | SSSS key handling |
| `cinny/src/app/features/settings/devices/Devices.tsx` | Device list |
| `cinny/src/app/features/settings/devices/Verification.tsx` | Verification UI |
| `cinny/src/app/features/settings/devices/LocalBackup.tsx` | Key export |
| `cinny/src/app/features/settings/devices/OtherDevices.tsx` | Remote sessions |
| `cinny/src/app/components/DeviceVerification.tsx` | Incoming verify modal |
| `cinny/src/app/components/BackupRestore.tsx` | Auto restore |
| `cinny/src/app/components/SecretStorage.tsx` | Passphrase setup |
| `cinny/src/app/hooks/useSecretStorage.ts` | Secret storage API |
| `cinny/src/app/hooks/useKeyBackup.ts` | Backup API |
| `cinny/src/app/pages/client/sidebar/UnverifiedTab.tsx` | Unverified badge |
| Path | Role |
| ---------------------------------------------------------- | --------------------- |
| `cinny/src/client/secretStorageKeys.ts` | SSSS key handling |
| `cinny/src/app/features/settings/devices/Devices.tsx` | Device list |
| `cinny/src/app/features/settings/devices/Verification.tsx` | Verification UI |
| `cinny/src/app/features/settings/devices/LocalBackup.tsx` | Key export |
| `cinny/src/app/features/settings/devices/OtherDevices.tsx` | Remote sessions |
| `cinny/src/app/components/DeviceVerification.tsx` | Incoming verify modal |
| `cinny/src/app/components/BackupRestore.tsx` | Auto restore |
| `cinny/src/app/components/SecretStorage.tsx` | Passphrase setup |
| `cinny/src/app/hooks/useSecretStorage.ts` | Secret storage API |
| `cinny/src/app/hooks/useKeyBackup.ts` | Backup API |
| `cinny/src/app/pages/client/sidebar/UnverifiedTab.tsx` | Unverified badge |
## Data model
| Store | Purpose |
|-------|---------|
| IndexedDB crypto | Olm account, Megolm sessions |
| SSSS | Cross-signing keys, backup key |
| Store | Purpose |
| ------------------- | ----------------------------------------- |
| IndexedDB crypto | Olm account, Megolm sessions |
| SSSS | Cross-signing keys, backup key |
| Matrix account data | `m.cross_signing.*`, `m.secret_storage.*` |
## Dependencies
@@ -25,25 +25,25 @@ text-area plugin (legacy/plain areas in some UI)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/components/editor/Editor.tsx` | Main Slate editor |
| `cinny/src/app/components/editor/Toolbar.tsx` | Formatting toolbar |
| `cinny/src/app/components/editor/input.ts` | Parse into editor |
| `cinny/src/app/components/editor/output.ts` | Serialize to Matrix |
| `cinny/src/app/components/editor/autocomplete/` | Mention/emoji menus |
| `cinny/src/app/features/room/RoomInput.tsx` | Room composer wrapper |
| `cinny/src/app/plugins/text-area/` | Plain text area utilities |
| `cinny/src/app/hooks/useFilePasteHandler.ts` | Paste files |
| `cinny/src/app/hooks/useFileDrop.ts` | Drag-drop files |
| `cinny/src/app/state/room/roomInputDrafts.ts` | Draft persistence |
| Path | Role |
| ----------------------------------------------- | ------------------------- |
| `cinny/src/app/components/editor/Editor.tsx` | Main Slate editor |
| `cinny/src/app/components/editor/Toolbar.tsx` | Formatting toolbar |
| `cinny/src/app/components/editor/input.ts` | Parse into editor |
| `cinny/src/app/components/editor/output.ts` | Serialize to Matrix |
| `cinny/src/app/components/editor/autocomplete/` | Mention/emoji menus |
| `cinny/src/app/features/room/RoomInput.tsx` | Room composer wrapper |
| `cinny/src/app/plugins/text-area/` | Plain text area utilities |
| `cinny/src/app/hooks/useFilePasteHandler.ts` | Paste files |
| `cinny/src/app/hooks/useFileDrop.ts` | Drag-drop files |
| `cinny/src/app/state/room/roomInputDrafts.ts` | Draft persistence |
## Data model
| Key | Storage |
|-----|---------|
| `roomIdToMsgDraftAtomFamily` | localStorage per room |
| `roomIdToUploadItemsAtomFamily` | pending uploads |
| Key | Storage |
| ------------------------------- | --------------------- |
| `roomIdToMsgDraftAtomFamily` | localStorage per room |
| `roomIdToUploadItemsAtomFamily` | pending uploads |
## Dependencies
+14 -14
View File
@@ -25,23 +25,23 @@ preload / contextBridge → window.electron in renderer
## Key files
| Path | Role |
|------|------|
| `electron/main.js` | Main process entry |
| `electron/api-server.js` | Local HTTP API |
| `electron/preload.js` (if exists) | IPC bridge |
| `electron-builder.json5` | Packaging config |
| `package.json` (root) | `npm run dev`, build scripts |
| `dev-app-update.yml` | Update channel config |
| `cinny/src/app/components/title-bar/TitleBar.tsx` | Custom title bar UI |
| `build-resources/` | Linux after-install, icons |
| Path | Role |
| ------------------------------------------------- | ---------------------------- |
| `electron/main.js` | Main process entry |
| `electron/api-server.js` | Local HTTP API |
| `electron/preload.js` (if exists) | IPC bridge |
| `electron-builder.json5` | Packaging config |
| `package.json` (root) | `npm run dev`, build scripts |
| `dev-app-update.yml` | Update channel config |
| `cinny/src/app/components/title-bar/TitleBar.tsx` | Custom title bar UI |
| `build-resources/` | Linux after-install, icons |
## Data model
| Store | Tool | Contents |
|-------|------|----------|
| `electron-store` | main.js | Window bounds, user prefs |
| UserData | Electron | plugins, caches |
| Store | Tool | Contents |
| ---------------- | -------- | ------------------------- |
| `electron-store` | main.js | Window bounds, user prefs |
| UserData | Electron | plugins, caches |
Protocol: `PROTOCOL_SCHEME = 'paarrot'` in main.js
+13 -13
View File
@@ -21,22 +21,22 @@ useRoomWideEmbedFilters (room state)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/hooks/useRoomEmbedFilters.ts` | Hooks, types, combine logic |
| `cinny/src/types/matrix/room.ts` | `StateEvent.RoomEmbedFilters` |
| `cinny/src/app/features/room/ThreadView.tsx` | Consumer |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Consumer |
| `cinny/src/app/features/common-settings/general/EmbedFilters.tsx` | Room-wide settings UI |
| `cinny/src/app/components/RenderMessageContent.tsx` | Embed render gating |
| `cinny/src/app/features/forum/useForumMessageRenderOptions.ts` | Forum post embed options |
| Path | Role |
| ----------------------------------------------------------------- | ----------------------------- |
| `cinny/src/app/hooks/useRoomEmbedFilters.ts` | Hooks, types, combine logic |
| `cinny/src/types/matrix/room.ts` | `StateEvent.RoomEmbedFilters` |
| `cinny/src/app/features/room/ThreadView.tsx` | Consumer |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Consumer |
| `cinny/src/app/features/common-settings/general/EmbedFilters.tsx` | Room-wide settings UI |
| `cinny/src/app/components/RenderMessageContent.tsx` | Embed render gating |
| `cinny/src/app/features/forum/useForumMessageRenderOptions.ts` | Forum post embed options |
## Data model
| Key | Scope | Content |
|-----|-------|---------|
| `im.paarrot.embed_filters` | Room account data (per user) | `{ disabledPatterns: string[] }` |
| `im.paarrot.room.embed_filters` | Room state | `{ disabledPatterns: string[] }` |
| Key | Scope | Content |
| ------------------------------- | ---------------------------- | -------------------------------- |
| `im.paarrot.embed_filters` | Room account data (per user) | `{ disabledPatterns: string[] }` |
| `im.paarrot.room.embed_filters` | Room state | `{ disabledPatterns: string[] }` |
Patterns are JavaScript `RegExp` strings — invalid regex can throw; handle at input time.
+16 -16
View File
@@ -24,25 +24,25 @@ Settings / common-settings EmojisStickers pages
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/hooks/useEmojiUsage.ts` | Usage stats in account data |
| `cinny/src/app/utils/telegramStickerImport.ts` | Telegram Bot API import |
| `cinny/src/app/features/settings/emojis-stickers/TelegramImport.tsx` | Import UI |
| `cinny/src/app/features/settings/emojis-stickers/EmojisStickers.tsx` | Settings hub |
| `cinny/src/app/features/settings/emojis-stickers/UserPack.tsx` | User pack editor |
| `cinny/src/app/features/settings/emojis-stickers/GlobalPacks.tsx` | Global packs |
| `cinny/src/app/plugins/custom-emoji/` | Custom emoji pack reader |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | `EmojiStyleFeature` |
| `cinny/src/app/state/settings.ts` | `EmojiStyle` enum |
| Path | Role |
| -------------------------------------------------------------------- | --------------------------- |
| `cinny/src/app/hooks/useEmojiUsage.ts` | Usage stats in account data |
| `cinny/src/app/utils/telegramStickerImport.ts` | Telegram Bot API import |
| `cinny/src/app/features/settings/emojis-stickers/TelegramImport.tsx` | Import UI |
| `cinny/src/app/features/settings/emojis-stickers/EmojisStickers.tsx` | Settings hub |
| `cinny/src/app/features/settings/emojis-stickers/UserPack.tsx` | User pack editor |
| `cinny/src/app/features/settings/emojis-stickers/GlobalPacks.tsx` | Global packs |
| `cinny/src/app/plugins/custom-emoji/` | Custom emoji pack reader |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | `EmojiStyleFeature` |
| `cinny/src/app/state/settings.ts` | `EmojiStyle` enum |
## Data model
| Key | Scope | Content |
|-----|-------|---------|
| `paarrot.favemojis` | User account data | Emoji usage counts |
| `cinny_telegram_bot_token` | localStorage | Telegram bot token (TelegramImport) |
| `im.ponies.room_emotes` | Room state | Standard Matrix emoji packs |
| Key | Scope | Content |
| -------------------------- | ----------------- | ----------------------------------- |
| `paarrot.favemojis` | User account data | Emoji usage counts |
| `cinny_telegram_bot_token` | localStorage | Telegram bot token (TelegramImport) |
| `im.ponies.room_emotes` | Room state | Standard Matrix emoji packs |
## Dependencies
+6 -6
View File
@@ -24,12 +24,12 @@ client/explore/
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/client/explore/Explore.tsx` | Explore hub |
| `cinny/src/app/pages/client/explore/Server.tsx` | Server directory |
| `cinny/src/app/pages/client/explore/Featured.tsx` | Featured list |
| `cinny/src/app/pages/client/sidebar/ExploreTab.tsx` | Sidebar entry |
| Path | Role |
| --------------------------------------------------- | -------------------- |
| `cinny/src/app/pages/client/explore/Explore.tsx` | Explore hub |
| `cinny/src/app/pages/client/explore/Server.tsx` | Server directory |
| `cinny/src/app/pages/client/explore/Featured.tsx` | Featured list |
| `cinny/src/app/pages/client/sidebar/ExploreTab.tsx` | Sidebar entry |
| `cinny/src/app/hooks/useRoomDirectoryVisibility.ts` | Directory visibility |
## Data model
+22 -22
View File
@@ -27,31 +27,31 @@ Routing: `getSpaceDefaultPath` + `shouldShowForumLobby` in path utils / room uti
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/forum/ForumFeedPage.tsx` | Main feed page |
| `cinny/src/app/features/forum/ForumSpaceLayout.tsx` | Layout shell |
| `cinny/src/app/features/forum/ForumAwareSpaceLayout.tsx` | Forum vs non-forum switch |
| `cinny/src/app/features/forum/forumFeed.ts` | Post aggregation, root detection |
| `cinny/src/app/features/forum/types.ts` | ForumTopic, ForumPost, etc. |
| `cinny/src/app/features/forum/ForumBoardView.tsx` | Board listing |
| `cinny/src/app/features/forum/ForumThreadDetail.tsx` | Thread view |
| `cinny/src/app/features/forum/ForumNewPostModal.tsx` | Create post |
| `cinny/src/app/features/forum/ForumReplyComposer.tsx` | Replies |
| `cinny/src/app/features/forum/useForumBoard.ts` | Board data hook |
| `cinny/src/app/features/forum/useForumRoomLiveUpdates.ts` | Live timeline sync |
| `cinny/src/app/pages/pathUtils.ts` | Forum routing |
| Path | Role |
| --------------------------------------------------------- | -------------------------------- |
| `cinny/src/app/features/forum/ForumFeedPage.tsx` | Main feed page |
| `cinny/src/app/features/forum/ForumSpaceLayout.tsx` | Layout shell |
| `cinny/src/app/features/forum/ForumAwareSpaceLayout.tsx` | Forum vs non-forum switch |
| `cinny/src/app/features/forum/forumFeed.ts` | Post aggregation, root detection |
| `cinny/src/app/features/forum/types.ts` | ForumTopic, ForumPost, etc. |
| `cinny/src/app/features/forum/ForumBoardView.tsx` | Board listing |
| `cinny/src/app/features/forum/ForumThreadDetail.tsx` | Thread view |
| `cinny/src/app/features/forum/ForumNewPostModal.tsx` | Create post |
| `cinny/src/app/features/forum/ForumReplyComposer.tsx` | Replies |
| `cinny/src/app/features/forum/useForumBoard.ts` | Board data hook |
| `cinny/src/app/features/forum/useForumRoomLiveUpdates.ts` | Live timeline sync |
| `cinny/src/app/pages/pathUtils.ts` | Forum routing |
## Data model
| Signal | Purpose |
|--------|---------|
| `m.room.create` `type: m.forum` | Matrix forum room type |
| `im.paarrot.room.kind: forum_space` | Paarrot forum classification |
| `com.matrixsso.title` on messages | Forum post title (legacy/custom) |
| `formatted_body` with `<h1>` | Root post detection |
| `m.relates_to` threads | Replies and edits |
| `im.paarrot.sub_rooms` | Topic room hierarchy (see sub-rooms) |
| Signal | Purpose |
| ----------------------------------- | ------------------------------------ |
| `m.room.create` `type: m.forum` | Matrix forum room type |
| `im.paarrot.room.kind: forum_space` | Paarrot forum classification |
| `com.matrixsso.title` on messages | Forum post title (legacy/custom) |
| `formatted_body` with `<h1>` | Root post detection |
| `m.relates_to` threads | Replies and edits |
| `im.paarrot.sub_rooms` | Topic room hierarchy (see sub-rooms) |
## Dependencies
@@ -21,17 +21,17 @@ useAsyncSearch or similar for filtering
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/search/Search.tsx` | Modal UI |
| `cinny/src/app/state/searchModal.ts` | Open/close state |
| `cinny/src/app/pages/client/sidebar/SearchTab.tsx` | Sidebar entry |
| Path | Role |
| -------------------------------------------------- | ---------------- |
| `cinny/src/app/features/search/Search.tsx` | Modal UI |
| `cinny/src/app/state/searchModal.ts` | Open/close state |
| `cinny/src/app/pages/client/sidebar/SearchTab.tsx` | Sidebar entry |
## Data model
| Key | Storage |
|-----|---------|
| `searchModal` atom | memory |
| Key | Storage |
| ------------------ | ------- |
| `searchModal` atom | memory |
## Dependencies
@@ -24,32 +24,32 @@ DirectTab.tsx → useDirectRooms.ts
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/client/home/Home.tsx` | Home room list UI |
| `cinny/src/app/pages/client/home/useHomeRooms.ts` | Room list logic + Paarrot room kind |
| `cinny/src/app/pages/client/SidebarNav.tsx` | Sidebar tab bar |
| `cinny/src/app/pages/client/sidebar/HomeTab.tsx` | Home tab |
| `cinny/src/app/pages/client/sidebar/DirectTab.tsx` | DMs tab + favicon logos |
| `cinny/src/app/pages/client/sidebar/InboxTab.tsx` | Inbox tab |
| `cinny/src/app/pages/client/sidebar/ExploreTab.tsx` | Explore tab |
| `cinny/src/app/pages/client/sidebar/SearchTab.tsx` | Search tab |
| `cinny/src/app/pages/client/sidebar/SettingsTab.tsx` | Settings tab |
| `cinny/src/app/pages/client/sidebar/SpaceTabs.tsx` | Space context tabs |
| `cinny/src/app/pages/client/home/HomeThreadsCategory.tsx` | Threads grouping |
| `cinny/src/app/hooks/useRoomListReorder.ts` | DnD reorder |
| `cinny/src/app/hooks/useSidebarItems.ts` | Sidebar item model |
| Path | Role |
| --------------------------------------------------------- | ----------------------------------- |
| `cinny/src/app/pages/client/home/Home.tsx` | Home room list UI |
| `cinny/src/app/pages/client/home/useHomeRooms.ts` | Room list logic + Paarrot room kind |
| `cinny/src/app/pages/client/SidebarNav.tsx` | Sidebar tab bar |
| `cinny/src/app/pages/client/sidebar/HomeTab.tsx` | Home tab |
| `cinny/src/app/pages/client/sidebar/DirectTab.tsx` | DMs tab + favicon logos |
| `cinny/src/app/pages/client/sidebar/InboxTab.tsx` | Inbox tab |
| `cinny/src/app/pages/client/sidebar/ExploreTab.tsx` | Explore tab |
| `cinny/src/app/pages/client/sidebar/SearchTab.tsx` | Search tab |
| `cinny/src/app/pages/client/sidebar/SettingsTab.tsx` | Settings tab |
| `cinny/src/app/pages/client/sidebar/SpaceTabs.tsx` | Space context tabs |
| `cinny/src/app/pages/client/home/HomeThreadsCategory.tsx` | Threads grouping |
| `cinny/src/app/hooks/useRoomListReorder.ts` | DnD reorder |
| `cinny/src/app/hooks/useSidebarItems.ts` | Sidebar item model |
## Data model
| Source | Data |
|--------|------|
| `allRoomsAtom` | Joined rooms |
| `roomToUnreadAtom` | Badge state |
| `mDirectAtom` | DM room mapping |
| Source | Data |
| ---------------------- | ------------------------------- |
| `allRoomsAtom` | Joined rooms |
| `roomToUnreadAtom` | Badge state |
| `mDirectAtom` | DM room mapping |
| `im.paarrot.sub_rooms` | Nested children (see sub-rooms) |
| `im.paarrot.room.kind` | Room classification |
| localStorage | Category collapse, room order |
| `im.paarrot.room.kind` | Room classification |
| localStorage | Category collapse, room order |
## Dependencies
@@ -22,21 +22,21 @@ ClientRoomsNotificationPreferences.tsx — bulk prefs
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/client/inbox/Inbox.tsx` | Inbox layout |
| `cinny/src/app/pages/client/inbox/Invites.tsx` | Invites UI |
| `cinny/src/app/pages/client/inbox/Notifications.tsx` | Notifications list |
| `cinny/src/app/state/room-list/inviteList.ts` | `allInvitesAtom` |
| `cinny/src/app/pages/client/ClientRoomsNotificationPreferences.tsx` | Room notif prefs |
| `cinny/src/app/pages/client/sidebar/InboxTab.tsx` | Sidebar entry |
| `cinny/src/app/hooks/useRoomsNotificationPreferences.ts` | Prefs hook |
| Path | Role |
| ------------------------------------------------------------------- | ------------------ |
| `cinny/src/app/pages/client/inbox/Inbox.tsx` | Inbox layout |
| `cinny/src/app/pages/client/inbox/Invites.tsx` | Invites UI |
| `cinny/src/app/pages/client/inbox/Notifications.tsx` | Notifications list |
| `cinny/src/app/state/room-list/inviteList.ts` | `allInvitesAtom` |
| `cinny/src/app/pages/client/ClientRoomsNotificationPreferences.tsx` | Room notif prefs |
| `cinny/src/app/pages/client/sidebar/InboxTab.tsx` | Sidebar entry |
| `cinny/src/app/hooks/useRoomsNotificationPreferences.ts` | Prefs hook |
## Data model
| Source | Data |
|--------|------|
| Sync | `m.room.member` invite membership |
| Source | Data |
| ------------ | --------------------------------------- |
| Sync | `m.room.member` invite membership |
| Account data | push rules, per-room notification prefs |
## Dependencies
@@ -22,12 +22,12 @@ Route: _JOIN_PATH in Router.tsx
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/join-before-navigate/JoinBeforeNavigate.tsx` | Preview + join UI |
| `cinny/src/app/components/RoomSummaryLoader.tsx` | Fetch room preview |
| `cinny/src/app/hooks/useRoomNavigate.ts` | Post-join navigation |
| `cinny/src/app/state/joiningProgress.ts` | Join in progress UX |
| Path | Role |
| -------------------------------------------------------------------- | -------------------- |
| `cinny/src/app/features/join-before-navigate/JoinBeforeNavigate.tsx` | Preview + join UI |
| `cinny/src/app/components/RoomSummaryLoader.tsx` | Fetch room preview |
| `cinny/src/app/hooks/useRoomNavigate.ts` | Post-join navigation |
| `cinny/src/app/state/joiningProgress.ts` | Join in progress UX |
## Data model
+20 -20
View File
@@ -23,29 +23,29 @@ Space route → Lobby.tsx (SpaceCardLobby)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/lobby/Lobby.tsx` | Main lobby view |
| `cinny/src/app/features/lobby/LobbyHeader.tsx` | Space header |
| `cinny/src/app/features/lobby/LobbyHero.tsx` | Hero banner area |
| `cinny/src/app/features/lobby/SpaceHierarchy.tsx` | Room tree/cards |
| `cinny/src/app/features/lobby/DnD.tsx` | Drag and drop |
| `cinny/src/app/features/lobby/RoomItem.tsx` | Room card |
| `cinny/src/app/state/closedLobbyCategories.ts` | Collapsed categories |
| `cinny/src/app/state/hooks/closedLobbyCategories.ts` | Jotai hook |
| `cinny/src/app/pages/pathUtils.ts` | `getSpaceLobbyPath`, forum routing |
| `cinny/src/app/utils/room.ts` | `shouldShowForumLobby`, `getStateEvent` |
| `cinny/src/types/matrix/room.ts` | `RoomType.Forum`, `PaarrotRoomKind` |
| Path | Role |
| ---------------------------------------------------- | --------------------------------------- |
| `cinny/src/app/features/lobby/Lobby.tsx` | Main lobby view |
| `cinny/src/app/features/lobby/LobbyHeader.tsx` | Space header |
| `cinny/src/app/features/lobby/LobbyHero.tsx` | Hero banner area |
| `cinny/src/app/features/lobby/SpaceHierarchy.tsx` | Room tree/cards |
| `cinny/src/app/features/lobby/DnD.tsx` | Drag and drop |
| `cinny/src/app/features/lobby/RoomItem.tsx` | Room card |
| `cinny/src/app/state/closedLobbyCategories.ts` | Collapsed categories |
| `cinny/src/app/state/hooks/closedLobbyCategories.ts` | Jotai hook |
| `cinny/src/app/pages/pathUtils.ts` | `getSpaceLobbyPath`, forum routing |
| `cinny/src/app/utils/room.ts` | `shouldShowForumLobby`, `getStateEvent` |
| `cinny/src/types/matrix/room.ts` | `RoomType.Forum`, `PaarrotRoomKind` |
## Data model
| Event / field | Purpose |
|---------------|---------|
| `m.space.child` | Child room membership + `order` |
| `im.paarrot.sub_rooms` | Paarrot nested children (see sub-rooms handoff) |
| `im.paarrot.room.kind` | e.g. `forum_space` for forum behavior |
| `m.room.create` `type` | `m.forum` for forum rooms |
| Local: `closedLobbyCategories` | UI collapse state (not Matrix) |
| Event / field | Purpose |
| ------------------------------ | ----------------------------------------------- |
| `m.space.child` | Child room membership + `order` |
| `im.paarrot.sub_rooms` | Paarrot nested children (see sub-rooms handoff) |
| `im.paarrot.room.kind` | e.g. `forum_space` for forum behavior |
| `m.room.create` `type` | `m.forum` for forum rooms |
| Local: `closedLobbyCategories` | UI collapse state (not Matrix) |
## Dependencies
+24 -24
View File
@@ -25,14 +25,14 @@ Navigation for room changes uses `setPaarrotNavigate()` registered from the Reac
## Key files
| Path | Role |
|------|------|
| `electron/api-server.js` | Express routes, IPC bridge to renderer |
| `electron/main.js` | Starts `PaarrotAPIServer` with the main window |
| `cinny/src/app/paarrot-api.ts` | Action handlers (mute, deafen, channel, message, status) |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Calls `initPaarrotAPI()` and `setPaarrotNavigate()` |
| `test-api.js` / `test-api.sh` | Smoke tests for endpoints |
| `paarrot-api.postman_collection.json` | Postman collection (generated) |
| Path | Role |
| ---------------------------------------------------- | -------------------------------------------------------- |
| `electron/api-server.js` | Express routes, IPC bridge to renderer |
| `electron/main.js` | Starts `PaarrotAPIServer` with the main window |
| `cinny/src/app/paarrot-api.ts` | Action handlers (mute, deafen, channel, message, status) |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Calls `initPaarrotAPI()` and `setPaarrotNavigate()` |
| `test-api.js` / `test-api.sh` | Smoke tests for endpoints |
| `paarrot-api.postman_collection.json` | Postman collection (generated) |
## Data model
@@ -40,22 +40,22 @@ No persistent storage. Actions read/write ephemeral app state (current room, cal
### IPC actions (renderer)
| Action | Params | Returns |
|--------|--------|---------|
| `get-status` | — | mute, deafen, currentRoom, connected, userId |
| `toggle-mute` / `set-mute` | `{ muted? }` | `{ muted }` |
| `toggle-deafen` / `set-deafen` | `{ deafened? }` | `{ deafened }` |
| `change-channel` | `{ roomId }` | navigation result |
| `get-channels` | — | room list |
| `send-message` | `{ roomId, message }` | send result |
| `send-message-current` | `{ message }` | send to active room |
| `get-current-room` | — | current room id |
| `get-messages-groups` | `{ limit? }` | recent messages across group channels |
| `get-messages-dms` | `{ limit? }` | recent messages across DMs |
| `get-messages-combined` | `{ limit? }` | recent messages across groups + DMs |
| `get-unreads-groups` | — | unread group conversations |
| `get-unreads-dms` | — | unread DM conversations |
| `get-unreads-combined` | — | unread groups + DMs |
| Action | Params | Returns |
| ------------------------------ | --------------------- | -------------------------------------------- |
| `get-status` | — | mute, deafen, currentRoom, connected, userId |
| `toggle-mute` / `set-mute` | `{ muted? }` | `{ muted }` |
| `toggle-deafen` / `set-deafen` | `{ deafened? }` | `{ deafened }` |
| `change-channel` | `{ roomId }` | navigation result |
| `get-channels` | — | room list |
| `send-message` | `{ roomId, message }` | send result |
| `send-message-current` | `{ message }` | send to active room |
| `get-current-room` | — | current room id |
| `get-messages-groups` | `{ limit? }` | recent messages across group channels |
| `get-messages-dms` | `{ limit? }` | recent messages across DMs |
| `get-messages-combined` | `{ limit? }` | recent messages across groups + DMs |
| `get-unreads-groups` | — | unread group conversations |
| `get-unreads-dms` | — | unread DM conversations |
| `get-unreads-combined` | — | unread groups + DMs |
## Dependencies
+14 -14
View File
@@ -25,23 +25,23 @@ initMatrix.ts
## Key files
| Path | Role |
|------|------|
| `cinny/src/client/initMatrix.ts` | createClient, start/stop, logout, cache clear |
| `cinny/src/client/secretStorageKeys.ts` | SSSS / secret storage callbacks |
| `cinny/src/app/pages/client/ClientRoot.tsx` | Bootstrap, providers, title bar |
| `cinny/src/app/hooks/useMatrixClient.ts` | React context for `MatrixClient` |
| `cinny/src/app/hooks/useSyncState.ts` | Sync state subscription |
| `cinny/src/app/pages/client/SyncStatus.tsx` | Sync indicator UI |
| `cinny/src/app/components/splash-screen/SplashScreen.tsx` | Loading shell |
| Path | Role |
| --------------------------------------------------------- | --------------------------------------------- |
| `cinny/src/client/initMatrix.ts` | createClient, start/stop, logout, cache clear |
| `cinny/src/client/secretStorageKeys.ts` | SSSS / secret storage callbacks |
| `cinny/src/app/pages/client/ClientRoot.tsx` | Bootstrap, providers, title bar |
| `cinny/src/app/hooks/useMatrixClient.ts` | React context for `MatrixClient` |
| `cinny/src/app/hooks/useSyncState.ts` | Sync state subscription |
| `cinny/src/app/pages/client/SyncStatus.tsx` | Sync indicator UI |
| `cinny/src/app/components/splash-screen/SplashScreen.tsx` | Loading shell |
## Data model
| Store | Backend | Purpose |
|-------|---------|---------|
| IndexedDB sync store | matrix-js-sdk | Room timeline cache |
| IndexedDB crypto store | matrix-js-sdk | Olm/Megolm keys |
| Session | localStorage | Auth credentials |
| Store | Backend | Purpose |
| ---------------------- | ------------- | ------------------- |
| IndexedDB sync store | matrix-js-sdk | Room timeline cache |
| IndexedDB crypto store | matrix-js-sdk | Olm/Megolm keys |
| Session | localStorage | Auth credentials |
## Dependencies
@@ -26,18 +26,18 @@ image-viewer/, video-viewer/ — fullscreen media
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/components/upload-card/UploadCardRenderer.tsx` | Upload UI |
| `cinny/src/app/state/upload.ts` | Upload state |
| `cinny/src/app/state/room/roomInputDrafts.ts` | `TUploadItem` |
| `cinny/src/app/utils/matrix.ts` | `encryptFile`, upload helpers |
| `cinny/src/app/components/url-preview/` | Link embed cards |
| `cinny/src/app/components/image-viewer/` | Image lightbox |
| `cinny/src/app/components/video-viewer/` | Video player |
| `cinny/src/app/hooks/useMediaAuthentication.ts` | Authenticated media URLs |
| `cinny/src/app/hooks/useAuthenticatedMediaUrl.ts` | MXC → HTTP with auth |
| `cinny/src/app/components/message/content/` | Image/video/thumbnail content |
| Path | Role |
| ------------------------------------------------------------- | ----------------------------- |
| `cinny/src/app/components/upload-card/UploadCardRenderer.tsx` | Upload UI |
| `cinny/src/app/state/upload.ts` | Upload state |
| `cinny/src/app/state/room/roomInputDrafts.ts` | `TUploadItem` |
| `cinny/src/app/utils/matrix.ts` | `encryptFile`, upload helpers |
| `cinny/src/app/components/url-preview/` | Link embed cards |
| `cinny/src/app/components/image-viewer/` | Image lightbox |
| `cinny/src/app/components/video-viewer/` | Video player |
| `cinny/src/app/hooks/useMediaAuthentication.ts` | Authenticated media URLs |
| `cinny/src/app/hooks/useAuthenticatedMediaUrl.ts` | MXC → HTTP with auth |
| `cinny/src/app/components/message/content/` | Image/video/thumbnail content |
## Data model
@@ -24,18 +24,18 @@ msgContent.ts — content type detection
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/components/RenderMessageContent.tsx` | Main render entry |
| `cinny/src/app/plugins/react-custom-html-parser.tsx` | HTML → React |
| `cinny/src/app/plugins/markdown/` | Markdown rules + parsers |
| `cinny/src/app/plugins/react-prism/ReactPrism.tsx` | Code highlighting |
| `cinny/src/app/plugins/emoji.ts` | Emoji shortcodes |
| `cinny/src/app/plugins/matrix-to.ts` | matrix.to link handling |
| `cinny/src/app/plugins/bad-words.ts` | Content filter hook |
| `cinny/src/app/plugins/color.ts` | Text color |
| `cinny/src/app/utils/sanitize.ts` | HTML sanitization |
| `cinny/src/app/features/room/msgContent.ts` | Message content helpers |
| Path | Role |
| ---------------------------------------------------- | ------------------------ |
| `cinny/src/app/components/RenderMessageContent.tsx` | Main render entry |
| `cinny/src/app/plugins/react-custom-html-parser.tsx` | HTML → React |
| `cinny/src/app/plugins/markdown/` | Markdown rules + parsers |
| `cinny/src/app/plugins/react-prism/ReactPrism.tsx` | Code highlighting |
| `cinny/src/app/plugins/emoji.ts` | Emoji shortcodes |
| `cinny/src/app/plugins/matrix-to.ts` | matrix.to link handling |
| `cinny/src/app/plugins/bad-words.ts` | Content filter hook |
| `cinny/src/app/plugins/color.ts` | Text color |
| `cinny/src/app/utils/sanitize.ts` | HTML sanitization |
| `cinny/src/app/features/room/msgContent.ts` | Message content helpers |
## Data model
@@ -22,13 +22,13 @@ Router may mount search under client routes
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/message-search/MessageSearch.tsx` | Main UI |
| `cinny/src/app/features/message-search/useMessageSearch.ts` | Search logic |
| `cinny/src/app/features/message-search/SearchInput.tsx` | Query field |
| `cinny/src/app/features/message-search/SearchFilters.tsx` | Filters |
| `cinny/src/app/features/message-search/SearchResultGroup.tsx` | Result list |
| Path | Role |
| ------------------------------------------------------------- | ------------ |
| `cinny/src/app/features/message-search/MessageSearch.tsx` | Main UI |
| `cinny/src/app/features/message-search/useMessageSearch.ts` | Search logic |
| `cinny/src/app/features/message-search/SearchInput.tsx` | Query field |
| `cinny/src/app/features/message-search/SearchFilters.tsx` | Filters |
| `cinny/src/app/features/message-search/SearchResultGroup.tsx` | Result list |
## Data model
+12 -12
View File
@@ -22,18 +22,18 @@ Plugin folder (index.js + plugin-metadata.json)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/settings/plugins/PluginLoader.tsx` | Load/enable/disable plugins |
| `cinny/src/app/features/settings/plugins/PluginAPI.ts` | Re-exports plugin-manager + app hooks |
| `cinny/src/app/features/settings/plugins/Plugins.tsx` | Settings UI (installed + marketplace) |
| `cinny/src/app/features/settings/plugins/PluginButtonSlot.tsx` | Icon button injection |
| `cinny/src/app/features/settings/plugins/PluginNavSlot.tsx` | Nav row injection |
| `cinny/src/app/features/settings/plugins/PluginSidebarSlot.tsx` | Sidebar icon injection |
| `cinny/src/app/features/settings/plugins/types.ts` | Local types |
| `cinny/src/app/features/settings/plugins/PLUGIN_DEVELOPMENT.md` | Author-facing dev guide |
| `example-plugin/` | Reference plugin at repo root |
| `cinny/docs/PLUGIN_*.md` | API reference docs |
| Path | Role |
| --------------------------------------------------------------- | ------------------------------------- |
| `cinny/src/app/features/settings/plugins/PluginLoader.tsx` | Load/enable/disable plugins |
| `cinny/src/app/features/settings/plugins/PluginAPI.ts` | Re-exports plugin-manager + app hooks |
| `cinny/src/app/features/settings/plugins/Plugins.tsx` | Settings UI (installed + marketplace) |
| `cinny/src/app/features/settings/plugins/PluginButtonSlot.tsx` | Icon button injection |
| `cinny/src/app/features/settings/plugins/PluginNavSlot.tsx` | Nav row injection |
| `cinny/src/app/features/settings/plugins/PluginSidebarSlot.tsx` | Sidebar icon injection |
| `cinny/src/app/features/settings/plugins/types.ts` | Local types |
| `cinny/src/app/features/settings/plugins/PLUGIN_DEVELOPMENT.md` | Author-facing dev guide |
| `example-plugin/` | Reference plugin at repo root |
| `cinny/docs/PLUGIN_*.md` | API reference docs |
## Data model
+12 -12
View File
@@ -23,21 +23,21 @@ Bot → state im.paarrot.ui
## Key files
| Path | Role |
|------|------|
| `cinny/src/types/matrix/room.ts` | `StateEvent.PaarrotUi`, `MessageEvent.PaarrotUiAction`, node types |
| `cinny/src/app/utils/room.ts` | `getPaarrotUiContent`, `hasRoomAppUi` |
| `cinny/src/app/features/room/Room.tsx` | Takeover branch + Show chat / Show app |
| `cinny/src/app/features/room-app/` | `RoomAppView`, schema renderer, CSS sanitize/scope |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Hides `im.paarrot.ui.action` |
| `cinny/src/app/features/room-settings/permissions/usePermissionItems.ts` | Permission labels |
| Path | Role |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `cinny/src/types/matrix/room.ts` | `StateEvent.PaarrotUi`, `MessageEvent.PaarrotUiAction`, node types |
| `cinny/src/app/utils/room.ts` | `getPaarrotUiContent`, `hasRoomAppUi` |
| `cinny/src/app/features/room/Room.tsx` | Takeover branch + Show chat / Show app |
| `cinny/src/app/features/room-app/` | `RoomAppView`, schema renderer, CSS sanitize/scope |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Hides `im.paarrot.ui.action` |
| `cinny/src/app/features/room-settings/permissions/usePermissionItems.ts` | Permission labels |
## Data model
| Event | Kind | Content |
|-------|------|---------|
| `im.paarrot.ui` | state (`""`) | `{ version, title?, css?, root }` |
| `im.paarrot.ui.action` | timeline | `{ action, component_id, value?, values?, ui_event_id? }` |
| Event | Kind | Content |
| ---------------------- | ------------ | --------------------------------------------------------- |
| `im.paarrot.ui` | state (`""`) | `{ version, title?, css?, root }` |
| `im.paarrot.ui.action` | timeline | `{ action, component_id, value?, values?, ui_event_id? }` |
See [samples/](./samples/) for pasteable Developer Tools payloads.
+6 -6
View File
@@ -25,13 +25,13 @@ Used by Home.tsx, space sidebars, forum sidebars
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/room-nav/RoomNavItem.tsx` | Main room row |
| `cinny/src/app/features/room-nav/RoomNavCategoryButton.tsx` | Category header |
| `cinny/src/app/features/room-nav/UnjoinedSubRoomItem.tsx` | Unjoined sub-room |
| Path | Role |
| --------------------------------------------------------------- | ----------------- |
| `cinny/src/app/features/room-nav/RoomNavItem.tsx` | Main room row |
| `cinny/src/app/features/room-nav/RoomNavCategoryButton.tsx` | Category header |
| `cinny/src/app/features/room-nav/UnjoinedSubRoomItem.tsx` | Unjoined sub-room |
| `cinny/src/app/features/room-nav/CallParticipantsIndicator.tsx` | In-call indicator |
| `cinny/src/app/features/room-nav/styles.css.ts` | Nav styles |
| `cinny/src/app/features/room-nav/styles.css.ts` | Nav styles |
## Data model
@@ -23,15 +23,15 @@ roomSettings.ts atom — which page open
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/room-settings/RoomSettings.tsx` | Settings shell |
| `cinny/src/app/features/room-settings/general/` | General tab |
| `cinny/src/app/features/room-settings/permissions/` | Permissions |
| `cinny/src/app/features/room-settings/sub-rooms/SubRooms.tsx` | Sub-rooms (Paarrot) |
| `cinny/src/app/state/roomSettings.ts` | Modal/page state |
| `cinny/src/app/state/hooks/roomSettings.ts` | Open/close hooks |
| `cinny/src/app/features/common-settings/` | Shared setting pages |
| Path | Role |
| ------------------------------------------------------------- | -------------------- |
| `cinny/src/app/features/room-settings/RoomSettings.tsx` | Settings shell |
| `cinny/src/app/features/room-settings/general/` | General tab |
| `cinny/src/app/features/room-settings/permissions/` | Permissions |
| `cinny/src/app/features/room-settings/sub-rooms/SubRooms.tsx` | Sub-rooms (Paarrot) |
| `cinny/src/app/state/roomSettings.ts` | Modal/page state |
| `cinny/src/app/state/hooks/roomSettings.ts` | Open/close hooks |
| `cinny/src/app/features/common-settings/` | Shared setting pages |
## Data model
+23 -23
View File
@@ -27,32 +27,32 @@ Hooks: useVirtualPaginator, useRoomLatestRenderedEvent, useMarkAsRead
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/room/Room.tsx` | Room entry |
| `cinny/src/app/features/room/RoomView.tsx` | Main layout |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Timeline |
| `cinny/src/app/features/room/RoomInput.tsx` | Composer |
| `cinny/src/app/features/room/ThreadView.tsx` | Thread panel |
| `cinny/src/app/features/room/RoomViewHeader.tsx` | Header bar |
| `cinny/src/app/features/room/message/Message.tsx` | Single message |
| `cinny/src/app/features/room/message/Reactions.tsx` | Reaction row |
| `cinny/src/app/features/room/message/MessageEditor.tsx` | Edit message |
| `cinny/src/app/features/room/CommandAutocomplete.tsx` | Slash commands |
| `cinny/src/app/features/room/reaction-viewer/ReactionViewer.tsx` | Who reacted |
| `cinny/src/app/features/room/jump-to-time/JumpToTime.tsx` | Time jump UI |
| `cinny/src/app/features/room/room-pin-menu/RoomPinMenu.tsx` | Pinned messages |
| `cinny/src/app/components/RenderMessageContent.tsx` | Content render + embeds |
| `cinny/src/app/hooks/useVirtualPaginator.ts` | Timeline pagination |
| Path | Role |
| ---------------------------------------------------------------- | ----------------------- |
| `cinny/src/app/features/room/Room.tsx` | Room entry |
| `cinny/src/app/features/room/RoomView.tsx` | Main layout |
| `cinny/src/app/features/room/RoomTimeline.tsx` | Timeline |
| `cinny/src/app/features/room/RoomInput.tsx` | Composer |
| `cinny/src/app/features/room/ThreadView.tsx` | Thread panel |
| `cinny/src/app/features/room/RoomViewHeader.tsx` | Header bar |
| `cinny/src/app/features/room/message/Message.tsx` | Single message |
| `cinny/src/app/features/room/message/Reactions.tsx` | Reaction row |
| `cinny/src/app/features/room/message/MessageEditor.tsx` | Edit message |
| `cinny/src/app/features/room/CommandAutocomplete.tsx` | Slash commands |
| `cinny/src/app/features/room/reaction-viewer/ReactionViewer.tsx` | Who reacted |
| `cinny/src/app/features/room/jump-to-time/JumpToTime.tsx` | Time jump UI |
| `cinny/src/app/features/room/room-pin-menu/RoomPinMenu.tsx` | Pinned messages |
| `cinny/src/app/components/RenderMessageContent.tsx` | Content render + embeds |
| `cinny/src/app/hooks/useVirtualPaginator.ts` | Timeline pagination |
## Data model
| Source | Data |
|--------|------|
| Matrix sync | `m.room.message`, edits, reactions, pins |
| Room account data | drafts (`roomInputDrafts`) |
| `im.paarrot.embed_filters` | Personal embed blocks |
| `im.paarrot.room.embed_filters` | Room-wide embed blocks |
| Source | Data |
| ------------------------------- | ---------------------------------------- |
| Matrix sync | `m.room.message`, edits, reactions, pins |
| Room account data | drafts (`roomInputDrafts`) |
| `im.paarrot.embed_filters` | Personal embed blocks |
| `im.paarrot.room.embed_filters` | Room-wide embed blocks |
## Dependencies
@@ -24,26 +24,26 @@ Router.tsx — route tree + loaders/guards
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/Router.tsx` | Full route tree |
| `cinny/src/app/pages/paths.ts` | Path constants |
| `cinny/src/app/pages/pathUtils.ts` | Path builder utilities |
| `cinny/src/app/pages/App.tsx` | RouterProvider setup |
| `cinny/src/app/pages/client/ClientLayout.tsx` | Authenticated layout shell |
| `cinny/src/app/pages/client/SidebarNav.tsx` | Left sidebar tabs |
| `cinny/src/app/pages/MobileFriendly.tsx` | Mobile nav adapters |
| `cinny/src/app/hooks/useRoomNavigate.ts` | Imperative room navigation |
| `cinny/src/app/hooks/useNavToActivePathMapper.ts` | Restore last path |
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Login redirect |
| `cinny/src/app/components/AnimatedOutlet.tsx` | Route transitions |
| Path | Role |
| ------------------------------------------------- | -------------------------- |
| `cinny/src/app/pages/Router.tsx` | Full route tree |
| `cinny/src/app/pages/paths.ts` | Path constants |
| `cinny/src/app/pages/pathUtils.ts` | Path builder utilities |
| `cinny/src/app/pages/App.tsx` | RouterProvider setup |
| `cinny/src/app/pages/client/ClientLayout.tsx` | Authenticated layout shell |
| `cinny/src/app/pages/client/SidebarNav.tsx` | Left sidebar tabs |
| `cinny/src/app/pages/MobileFriendly.tsx` | Mobile nav adapters |
| `cinny/src/app/hooks/useRoomNavigate.ts` | Imperative room navigation |
| `cinny/src/app/hooks/useNavToActivePathMapper.ts` | Restore last path |
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Login redirect |
| `cinny/src/app/components/AnimatedOutlet.tsx` | Route transitions |
## Data model
| Key | Purpose |
|-----|---------|
| `navToActivePath` atom | Per-context last URL |
| URL path params | roomId, spaceId, eventId |
| Key | Purpose |
| ---------------------- | ------------------------ |
| `navToActivePath` atom | Per-context last URL |
| URL path params | roomId, spaceId, eventId |
## Dependencies
@@ -21,13 +21,13 @@ spaceSettings.ts atom
## Key files
| Path | Role |
|------|------|
| Path | Role |
| --------------------------------------------------------- | -------------- |
| `cinny/src/app/features/space-settings/SpaceSettings.tsx` | Settings shell |
| `cinny/src/app/features/space-settings/general/` | General tab |
| `cinny/src/app/features/space-settings/permissions/` | Permissions |
| `cinny/src/app/state/spaceSettings.ts` | Open state |
| `cinny/src/app/state/hooks/spaceSettings.ts` | Hooks |
| `cinny/src/app/features/space-settings/general/` | General tab |
| `cinny/src/app/features/space-settings/permissions/` | Permissions |
| `cinny/src/app/state/spaceSettings.ts` | Open state |
| `cinny/src/app/state/hooks/spaceSettings.ts` | Hooks |
## Data model
@@ -22,35 +22,35 @@ ClientBindAtoms.tsx binds Matrix events → atom updates
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/state/settings.ts` | User settings atom |
| `cinny/src/app/state/sessions.ts` | Auth sessions |
| `cinny/src/app/state/room-list/roomList.ts` | `allRoomsAtom`, ordering |
| `cinny/src/app/state/room/roomToUnread.ts` | Unread counts |
| `cinny/src/app/state/room/roomInputDrafts.ts` | Composer drafts + uploads |
| `cinny/src/app/state/room/roomToParents.ts` | Space parent mapping |
| `cinny/src/app/state/mDirectList.ts` | Direct message index |
| `cinny/src/app/state/navToActivePath.ts` | Last active path per context |
| `cinny/src/app/state/closedNavCategories.ts` | Collapsed nav sections |
| `cinny/src/app/state/closedLobbyCategories.ts` | Collapsed lobby categories |
| `cinny/src/app/state/createRoomModal.ts` | Create room modal state |
| `cinny/src/app/state/createSpaceModal.ts` | Create space modal state |
| `cinny/src/app/state/searchModal.ts` | Global search modal |
| `cinny/src/app/state/utils/atomWithLocalStorage.ts` | Persistence helper |
| `cinny/src/app/pages/client/ClientBindAtoms.ts` | Matrix → atom bindings |
| Path | Role |
| --------------------------------------------------- | ---------------------------- |
| `cinny/src/app/state/settings.ts` | User settings atom |
| `cinny/src/app/state/sessions.ts` | Auth sessions |
| `cinny/src/app/state/room-list/roomList.ts` | `allRoomsAtom`, ordering |
| `cinny/src/app/state/room/roomToUnread.ts` | Unread counts |
| `cinny/src/app/state/room/roomInputDrafts.ts` | Composer drafts + uploads |
| `cinny/src/app/state/room/roomToParents.ts` | Space parent mapping |
| `cinny/src/app/state/mDirectList.ts` | Direct message index |
| `cinny/src/app/state/navToActivePath.ts` | Last active path per context |
| `cinny/src/app/state/closedNavCategories.ts` | Collapsed nav sections |
| `cinny/src/app/state/closedLobbyCategories.ts` | Collapsed lobby categories |
| `cinny/src/app/state/createRoomModal.ts` | Create room modal state |
| `cinny/src/app/state/createSpaceModal.ts` | Create space modal state |
| `cinny/src/app/state/searchModal.ts` | Global search modal |
| `cinny/src/app/state/utils/atomWithLocalStorage.ts` | Persistence helper |
| `cinny/src/app/pages/client/ClientBindAtoms.ts` | Matrix → atom bindings |
## Data model
Most state is **local only** (not Matrix). Exceptions: settings that also write account data (notification prefs via separate hooks).
| Atom area | Persists? |
|-----------|-----------|
| settings | localStorage |
| room list order | localStorage |
| drafts | localStorage |
| unread | memory (derived from sync) |
| modals | memory |
| Atom area | Persists? |
| --------------- | -------------------------- |
| settings | localStorage |
| room list order | localStorage |
| drafts | localStorage |
| unread | memory (derived from sync) |
| modals | memory |
## Dependencies
+9 -9
View File
@@ -21,15 +21,15 @@ Stream Deck button press
## Key files
| Path | Role |
|------|------|
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/manifest.json` | Plugin manifest |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.js` | Action implementations |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.html` | Property inspector UI |
| `streamdeck-plugin/build.js` | Build `.streamDeckPlugin` bundle |
| `streamdeck-plugin/validate.js` | Manifest validation |
| `streamdeck-plugin/README.md` | User install guide |
| `streamdeck-plugin/QUICKSTART.md` | Dev quickstart |
| Path | Role |
| --------------------------------------------------------------------- | -------------------------------- |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/manifest.json` | Plugin manifest |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.js` | Action implementations |
| `streamdeck-plugin/com.paarrot.streamdeck.sdPlugin/plugin/index.html` | Property inspector UI |
| `streamdeck-plugin/build.js` | Build `.streamDeckPlugin` bundle |
| `streamdeck-plugin/validate.js` | Manifest validation |
| `streamdeck-plugin/README.md` | User install guide |
| `streamdeck-plugin/QUICKSTART.md` | Dev quickstart |
## Data model
+12 -12
View File
@@ -25,21 +25,21 @@ Room state: im.paarrot.sub_rooms { children: string[] }
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/hooks/useRoomSubRooms.ts` | Hook + `PaarrotSubRoomsContent` type |
| `cinny/src/types/matrix/room.ts` | `StateEvent.PaarrotSubRooms` |
| `cinny/src/app/pages/client/home/Home.tsx` | Renders nested list |
| `cinny/src/app/features/room-nav/RoomNavItem.tsx` | Add sub-room action |
| `cinny/src/app/features/room-nav/UnjoinedSubRoomItem.tsx` | Unjoined child UI |
| `cinny/src/app/features/room-settings/sub-rooms/SubRooms.tsx` | Settings page |
| `cinny/src/app/features/create-room/CreateRoomModal.tsx` | Appends new room to parent state |
| `cinny/src/app/features/lobby/SpaceHierarchy.tsx` | Lobby hierarchy integration |
| Path | Role |
| ------------------------------------------------------------- | ------------------------------------ |
| `cinny/src/app/hooks/useRoomSubRooms.ts` | Hook + `PaarrotSubRoomsContent` type |
| `cinny/src/types/matrix/room.ts` | `StateEvent.PaarrotSubRooms` |
| `cinny/src/app/pages/client/home/Home.tsx` | Renders nested list |
| `cinny/src/app/features/room-nav/RoomNavItem.tsx` | Add sub-room action |
| `cinny/src/app/features/room-nav/UnjoinedSubRoomItem.tsx` | Unjoined child UI |
| `cinny/src/app/features/room-settings/sub-rooms/SubRooms.tsx` | Settings page |
| `cinny/src/app/features/create-room/CreateRoomModal.tsx` | Appends new room to parent state |
| `cinny/src/app/features/lobby/SpaceHierarchy.tsx` | Lobby hierarchy integration |
## Data model
| Event | State key | Content |
|-------|-----------|---------|
| Event | State key | Content |
| ---------------------- | ------------ | ---------------------------------------------------- |
| `im.paarrot.sub_rooms` | `""` (empty) | `{ children: string[] }` — room IDs in display order |
Power levels: treat like other state events; editors need `state_default` or explicit level for `im.paarrot.sub_rooms`.
@@ -24,21 +24,21 @@ vanilla-extract / folds tokens in colors.css.ts
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/pages/ThemeManager.tsx` | Route-level theme |
| `cinny/src/app/state/settings.ts` | Settings including theme |
| `cinny/src/app/hooks/useTheme.ts` | Theme hook |
| `cinny/src/colors.css.ts` | Color tokens |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Page zoom CSS |
| `cinny/src/app/hooks/useViewTransitions.ts` | View transitions |
| `cinny/src/app/hooks/useMessageSpacing.ts` | Message density |
| `cinny/public/themes/` | Bundled theme files (if present) |
| Path | Role |
| ---------------------------------------------------- | -------------------------------- |
| `cinny/src/app/pages/ThemeManager.tsx` | Route-level theme |
| `cinny/src/app/state/settings.ts` | Settings including theme |
| `cinny/src/app/hooks/useTheme.ts` | Theme hook |
| `cinny/src/colors.css.ts` | Color tokens |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Page zoom CSS |
| `cinny/src/app/hooks/useViewTransitions.ts` | View transitions |
| `cinny/src/app/hooks/useMessageSpacing.ts` | Message density |
| `cinny/public/themes/` | Bundled theme files (if present) |
## Data model
| Key | Storage |
|-----|---------|
| Key | Storage |
| -------------- | ------------------------------------------- |
| `settingsAtom` | theme, pageZoom, messageSpacing, emojiStyle |
## Dependencies
+14 -14
View File
@@ -24,25 +24,25 @@ SettingsPages enum
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/settings/Settings.tsx` | Settings modal shell |
| `cinny/src/app/features/settings/general/General.tsx` | General prefs |
| Path | Role |
| ----------------------------------------------------- | ------------------------- |
| `cinny/src/app/features/settings/Settings.tsx` | Settings modal shell |
| `cinny/src/app/features/settings/general/General.tsx` | General prefs |
| `cinny/src/app/features/settings/account/Profile.tsx` | Profile + avatar metadata |
| `cinny/src/app/features/settings/notifications/` | Notification rules |
| `cinny/src/app/features/settings/audio/Audio.tsx` | Call audio devices |
| `cinny/src/app/features/settings/devices/` | Sessions & verification |
| `cinny/src/app/features/settings/about/About.tsx` | About page |
| `cinny/src/app/state/settings.ts` | Settings atom |
| `cinny/src/app/pages/client/sidebar/SettingsTab.tsx` | Entry point |
| `cinny/src/app/features/settings/notifications/` | Notification rules |
| `cinny/src/app/features/settings/audio/Audio.tsx` | Call audio devices |
| `cinny/src/app/features/settings/devices/` | Sessions & verification |
| `cinny/src/app/features/settings/about/About.tsx` | About page |
| `cinny/src/app/state/settings.ts` | Settings atom |
| `cinny/src/app/pages/client/sidebar/SettingsTab.tsx` | Entry point |
## Data model
| Key | Storage |
|-----|---------|
| Key | Storage |
| -------------- | --------------------------------------------- |
| `settingsAtom` | localStorage (theme, zoom, emoji style, etc.) |
| Profile | Matrix account data + avatar MXC |
| Push rules | Homeserver account data |
| Profile | Matrix account data + avatar MXC |
| Push rules | Homeserver account data |
## Dependencies
+17 -17
View File
@@ -23,26 +23,26 @@ useCallService (CallProvider)
## Key files
| Path | Role |
|------|------|
| `cinny/src/app/features/call/useCall.ts` | React context, global CallService ref |
| `cinny/src/app/features/call/CallService.ts` | Core call logic |
| `cinny/src/app/features/call/types.ts` | CallState, ActiveCall, events |
| `cinny/src/app/features/call/useRtcConfig.ts` | Homeserver RTC / LiveKit discovery |
| `cinny/src/app/features/call/CallOverlay.tsx` | Full-screen call UI |
| `cinny/src/app/features/call/DockedCallPanel.tsx` | Docked UI |
| `cinny/src/app/features/call/SidebarDockedCallPanel.tsx` | Sidebar variant |
| `cinny/src/app/features/call/useRemoteCursor.ts` | Screen-share cursor sync |
| `cinny/src/app/features/call/CallSounds.ts` | Join/leave sounds |
| `cinny/src/app/features/room-nav/CallParticipantsIndicator.tsx` | Nav badge |
| `cinny/src/types/matrix/room.ts` | `StateEvent.CallMember` |
| Path | Role |
| --------------------------------------------------------------- | ------------------------------------- |
| `cinny/src/app/features/call/useCall.ts` | React context, global CallService ref |
| `cinny/src/app/features/call/CallService.ts` | Core call logic |
| `cinny/src/app/features/call/types.ts` | CallState, ActiveCall, events |
| `cinny/src/app/features/call/useRtcConfig.ts` | Homeserver RTC / LiveKit discovery |
| `cinny/src/app/features/call/CallOverlay.tsx` | Full-screen call UI |
| `cinny/src/app/features/call/DockedCallPanel.tsx` | Docked UI |
| `cinny/src/app/features/call/SidebarDockedCallPanel.tsx` | Sidebar variant |
| `cinny/src/app/features/call/useRemoteCursor.ts` | Screen-share cursor sync |
| `cinny/src/app/features/call/CallSounds.ts` | Join/leave sounds |
| `cinny/src/app/features/room-nav/CallParticipantsIndicator.tsx` | Nav badge |
| `cinny/src/types/matrix/room.ts` | `StateEvent.CallMember` |
## Data model
| Key | Scope | Notes |
|-----|-------|-------|
| `org.matrix.msc3401.call.member` | Room state | Call membership |
| LiveKit JWT / room | Ephemeral | From homeserver RTC focus |
| Key | Scope | Notes |
| -------------------------------- | ---------- | ------------------------- |
| `org.matrix.msc3401.call.member` | Room state | Call membership |
| LiveKit JWT / room | Ephemeral | From homeserver RTC focus |
Call mute/deafen/video state lives in `CallService` memory, not Matrix account data.