1# plugin
 2
 3Lua-based plugin system for extending Matcha. Plugins are loaded from `~/.config/matcha/plugins/` and run inside a sandboxed Lua VM (no `os`, `io`, or `debug` libraries).
 4
 5## How it works
 6
 7The `Manager` creates a Lua VM at startup, registers the `matcha` module, and loads all plugins from the user's plugins directory. Plugins can be either a single `.lua` file or a directory with an `init.lua` entry point.
 8
 9Plugins interact with Matcha by registering callbacks on hooks:
10
11```lua
12local matcha = require("matcha")
13
14matcha.on("email_received", function(email)
15    matcha.log("New email from: " .. email.from)
16    matcha.notify("New mail!", 3)
17end)
18```
19
20## Lua API (`matcha` module)
21
22| Function | Description |
23|----------|-------------|
24| `matcha.on(event, callback)` | Register a callback for a hook event |
25| `matcha.log(msg)` | Log a message to stderr |
26| `matcha.notify(msg [, seconds])` | Show a temporary notification in the TUI (default 2s) |
27| `matcha.set_status(area, text)` | Set a persistent status string for a view area (`"inbox"`, `"composer"`, `"email_view"`) |
28| `matcha.set_compose_field(field, value)` | Set a compose field value (`"to"`, `"cc"`, `"bcc"`, `"subject"`, `"body"`) |
29| `matcha.bind_key(key, area, description, callback)` | Register a custom keyboard shortcut for a view area (`"inbox"`, `"email_view"`, `"composer"`) |
30
31## Hook events
32
33| Event | Callback argument | Description |
34|-------|-------------------|-------------|
35| `startup` | — | Matcha has started |
36| `shutdown` | — | Matcha is exiting |
37| `email_received` | Lua table with `uid`, `from`, `to`, `subject`, `date`, `is_read`, `account_id`, `folder` | New email arrived |
38| `email_viewed` | Same as `email_received` | User opened an email |
39| `email_send_before` | Table with `to`, `cc`, `subject`, `account_id` | About to send an email |
40| `email_send_after` | Same as `email_send_before` | Email sent successfully |
41| `folder_changed` | Folder name (string) | User switched folders |
42| `composer_updated` | Table with `body`, `body_len`, `subject`, `to`, `cc`, `bcc` | Composer content changed |
43
44## Available plugins
45
46The following example plugins ship in `~/.config/matcha/plugins/`:
47
48- `email_age.lua`
49- `recipient_counter.lua`
50
51## Files
52
53| File | Description |
54|------|-------------|
55| `plugin.go` | Plugin manager — Lua VM setup, plugin discovery and loading, notification/status state |
56| `hooks.go` | Hook definitions, callback registration, and hook invocation helpers |
57| `api.go` | `matcha` Lua module registration (`on`, `log`, `notify`, `set_status`, `set_compose_field`, `bind_key`) |