v0.3.5 — theme system, plugin platform, sectioned Settings, tab animations
- Themes: built-in presets (Ember/Forest/Ocean/Rosé) + custom-theme editor (per-token color pickers, live preview, JSON export/import). src/themes.ts. - Plugin platform: JS/ESM plugins loaded via blob-module import (CSP script-src blob:), Host SDK with menu / file-context / view / submit-hook contribution points + permission model. Backend commands to list/read/enable/ install/remove plugins under <config>/plugins/. Example plugin + PLUGINS.md. - Settings redesigned into a sectioned hub (General / Appearance / Plugins); Themes and Plugins moved in, removed from the Actions menu. - "NEW" badge on History commits submitted < 3h ago. - Smooth tab transitions: sliding underline + content fade on Changes/History, and matching fades on the view-panel and dock tab groups. - Fix: settings close button used the default browser style. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
103
PLUGINS.md
Normal file
103
PLUGINS.md
Normal file
@ -0,0 +1,103 @@
|
||||
# Exbyte Depot — Plugins
|
||||
|
||||
Plugins add features on top of the core app so the base stays lean and specialised
|
||||
work ships (and updates) independently.
|
||||
|
||||
## What language?
|
||||
**JavaScript / TypeScript.** A plugin is a plain **ES module** that exports
|
||||
`activate(host)`. Author in TypeScript if you like, then compile to a single JS
|
||||
file (`esbuild index.ts --bundle --format=esm --outfile=index.js`). No build step
|
||||
is required for plain JS.
|
||||
|
||||
Why JS and not native? The app's Rust backend is compiled and sealed; the extensible
|
||||
surface is the webview. Plugins run in the app's webview and reach the app **only**
|
||||
through the `host` object — never `invoke` directly.
|
||||
|
||||
## How plugins are loaded
|
||||
The app reads the plugin's entry source from disk (Rust) and imports it as an ES
|
||||
module from a `blob:` URL — **no `eval`**, and it stays inside the CSP
|
||||
(`script-src 'self' blob:`). Disabled plugins are never imported.
|
||||
|
||||
## Anatomy
|
||||
```
|
||||
my-plugin/
|
||||
plugin.json # manifest
|
||||
index.js # ES module exporting activate(host)
|
||||
```
|
||||
|
||||
### plugin.json
|
||||
```json
|
||||
{
|
||||
"id": "my-plugin", // unique; [A-Za-z0-9-_.]
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "You",
|
||||
"description": "What it does.",
|
||||
"entry": "index.js", // must stay inside the plugin folder
|
||||
"minAppVersion": "0.3.5",
|
||||
"permissions": ["p4:read", "notify"],
|
||||
"contributes": { "menu": true, "views": ["notes"], "fileContext": true, "submitHooks": true }
|
||||
}
|
||||
```
|
||||
|
||||
### Permissions (declared, shown to the user)
|
||||
| permission | grants |
|
||||
|---|---|
|
||||
| `p4:read` | read-only p4: `opened, dirs, describe, changeSizes, clientSpec` on `host.p4` |
|
||||
| `p4:write` | mutating p4: `add, edit, del, sync, reconcile` on `host.p4` |
|
||||
| `notify` | native notifications via `host.notify` |
|
||||
|
||||
Without a permission, the matching APIs are simply absent (or no-ops). `host.storage`,
|
||||
`host.clipboard`, `host.flash`, `host.info`, `host.t`, `host.theme` are always available.
|
||||
|
||||
## The `host` SDK
|
||||
```ts
|
||||
host.version // Host SDK version, e.g. "1.0"
|
||||
host.plugin // { id, name, dir }
|
||||
host.has(perm) // boolean
|
||||
|
||||
host.p4.<method>(...) // Promise — only the whitelisted set your perms allow
|
||||
host.info() // { userName, clientName, clientRoot } | null
|
||||
host.selectedFile() // { depotFile } | null
|
||||
host.refresh() // re-read the Changes view
|
||||
host.theme() // current theme's CSS-var overrides
|
||||
|
||||
host.ui.addMenuItem(label, run) // Actions-menu action
|
||||
host.ui.addFileContextItem(label, run(file)) // right-click a file
|
||||
host.ui.addView({ id, title, render(el, host) })// a panel; render into a DOM element (return an optional cleanup fn)
|
||||
host.ui.addSubmitHook(run(files) => {ok, message}) // block/allow a commit
|
||||
|
||||
host.flash(text, isError?) // toast
|
||||
host.notify(title, body) // native notification (needs "notify")
|
||||
host.clipboard.write(text) // Promise
|
||||
host.storage.get/set/remove(key) // per-plugin localStorage namespace
|
||||
host.t(key, params?) // app i18n
|
||||
host.log(...args) // console, tagged with the plugin id
|
||||
```
|
||||
|
||||
## Contribution points
|
||||
- **Menu items** and **views** appear in the **Actions** menu.
|
||||
- **File context items** appear when you right-click a file in Changes.
|
||||
- **Submit hooks** run before a commit is finalised; returning `{ ok:false, message }`
|
||||
prompts the user to confirm or cancel. (This is exactly where a reference-integrity
|
||||
guard, size check, or lint would live.)
|
||||
|
||||
## Import methods
|
||||
1. **Install from folder** — Actions → Plugins… → *Install from folder…* → pick a folder
|
||||
that contains `plugin.json`. It's copied into the app's plugins folder.
|
||||
2. **Drop-in** — Actions → Plugins… → *Open plugins folder*, drop `my-plugin/` in there,
|
||||
then *Reload*.
|
||||
3. **(Planned) Registry** — a signed registry (`exbyte-depot-plugins` repo, minisign-signed
|
||||
bundles) for one-click install/updates, reusing the app's updater signing infra.
|
||||
|
||||
## Try the example
|
||||
`plugins-examples/hello-exbyte/` demonstrates all four contribution points plus storage,
|
||||
clipboard, info and notifications. Install it from folder, then:
|
||||
- Actions → **Say hello 👋** and Actions → **Workspace Notes**
|
||||
- right-click a file → **Copy depot path (plugin)**
|
||||
- try to commit a file named `wip*` → the submit guard warns.
|
||||
|
||||
## Safety
|
||||
Plugins run in-app on the main thread — install only ones you trust. The `id` is
|
||||
path-validated, the entry cannot escape the plugin folder, and each plugin's storage
|
||||
is namespaced. A plugin that throws is isolated and does not crash the app.
|
||||
Reference in New Issue
Block a user