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
+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