Plugin manifest and UI
Generated from the code by
apps/docs/scripts/reference.mjs: edit the source, not this page.
A plugin is a folder with a wisp-plugin.json and, for UI, one .js module. wisp checks the manifest against these keys: an unknown key is refused, with the one you probably meant. Start with Your first plugin.
Manifest keys
| Key | What it is |
|---|---|
wispPlugin |
1. Required. |
id |
Required. “user. |
name |
What the user sees it called. |
version |
Required. “1.0.0”: bump it when you change a plugin the user already has. |
api |
Required. The plugin API range it’s written for: “^1”. |
description |
One sentence: what it does for the user. |
author |
Who wrote it. |
kind |
Leave it out (“module” is for wisp’s own built-ins). |
extends |
Another plugin’s id this one adds to (rare). |
requires |
{ “ |
provides |
{ “ |
permissions |
What it may do, as permissions (“plugins:read”, “runtime:list”). Its UI’s wisp.call runs as the plugin and is checked against these, never the user’s. Each command’s permission is in the list of commands below. Switching it on is the user’s consent to them. |
server |
{ “exec”: [“ |
activation |
When it starts: “onStartup”, “onCommand: |
disable |
Built-in plugin ids it switches off while it’s on (an override; rare). |
contributes |
What it adds to wisp: the sections below. |
migrations |
A folder of forward-only SQL migrations for its own tables (a server plugin; rare). |
trust |
Ignored on install: anything installed is untrusted until the user trusts it in Settings → Plugins. |
qa |
wisp’s own QA hook; leave it out. |
contributes
| Key | What it adds |
|---|---|
commands |
[{ “id”: “user. |
events |
Events its server emits, by name and version. |
topics |
Topics its server publishes for clients to watch. |
points |
Extension points it offers other plugins (rare). |
settings |
[{ “key”: “user. |
setSettings |
{ “ |
ui |
[{ “id”: “user. |
parts |
Part names it adds for themes to style (an untrusted UI draws only kit components; it can’t style anything). |
partStyles |
A theme: { “ |
icons |
Icons it adds by name (a trusted plugin; an untrusted UI’s descriptors take no icons). |
blocks |
Answer block types it renders (its UI at shell.block). |
recipes |
Automation recipes it brings, read-only to the user. |
triggerSources |
Event names automations can start on (“on” names), known even while it’s off. |
The UI module
A contributes.ui entry’s component is a .js file in the plugin’s folder. It runs in a Worker in a sandboxed frame: no DOM, no network, no storage, no imports, one file of at most 256 KB. Its wisp has only:
wisp.render(tree): draw this tree of components (call it again to update; nodes update in place).wisp.call(command, args): run a wisp command as the plugin, checked against the plugin’s own permissions (never yours). Every command is in Commands.wisp.on(event, fn):fn(value)runs when a component withon: eventfires.
A node is a string (text) or { c: 'Component', p: { …props }, k: [ …children ], on: 'event' }. No HTML, no class, no style: anything not listed below is dropped, so a plugin always looks like wisp, in light and dark.
| Component | Props |
|---|---|
Stack |
gap: 0 · 1 · 2 · 3 · 4 · 5 · 6 · 7 · 8 · 9; align: start · center · end · stretch · baseline; justify: start · center · end · between Takes children (k). |
Inline |
gap: 0 · 1 · 2 · 3 · 4 · 5 · 6 · 7 · 8 · 9; align: start · center · end · stretch · baseline; justify: start · center · end · between Takes children (k). |
Text |
size: xs · sm · md · lg; weight: regular · medium · semibold; tone: ink · ink-2 · muted · faint · neutral · accent · good · warn · bad · info; mono: bool; truncate: bool Takes children (k). |
Button |
variant: primary · secondary · ghost · danger; size: xs · sm · md · lg; disabled: bool; label: string Fires on: a click (no value). |
Input |
value: string; placeholder: string; type: text · password · number · search; size: sm · md · lg; label: string Fires on: each edit (its text). |
Switch |
checked: bool; label: string; disabled: bool Fires on: a flip (true or false). |
Select |
value: string; items: items; placeholder: string; label: string Fires on: a pick (the item’s value). |
SettingsRow |
title: string; description: string; control: node |
ListRow |
title: string; sub: string |
Callout |
tone: neutral · accent · good · warn · bad · info; title: string Takes children (k). |
Code |
text: string; block: bool; lang: string |
Markdown |
source: string |
Where a plugin’s UI shows (attachTo.id)
| Place | Where | Drawn |
|---|---|---|
shell.settings |
a pane in Settings → Advanced | yes |
shell.side |
a side view | not drawn yet |
shell.block |
a block renderer | not drawn yet |
shell.toolbar |
a toolbar button | not drawn yet |
Limits: 10000 characters per text, 2000 nodes, 32 levels, 200 items per Select.
Themes (partStyles)
A theme is a plugin with only a manifest: contributes.partStyles maps the data-part names of what you want to restyle (see them in the browser’s inspector: data-part="composer.send") to CSS declarations. wisp writes them into the app’s @layer plugins, after its own styles, so they win without !important. They apply while the plugin is on and you trusted it: a plugin you install is untrusted until you say otherwise, and an untrusted plugin’s styles never apply.
wisp plugin install ./pink # installed, off and untrustedwisp plugin trust user.pink # its styles may applywisp plugin enable user.pink # on: the app restyles at once; disable or remove it and they go"partStyles": { ":root": { "--accent": "#d6336c" }, "composer.send": { "background": "#d6336c", "color": "#ffffff", "border-radius": "999px" }, "@dark": { ":root": { "--accent": "#ff7aa8" }, "composer.send": { "background": "#ff7aa8", "color": "#1a1a1a" } }}- A key is a part name (
composer.send: lowercase, dot-namespaced),:rootfor token overrides (custom properties only, like--accent), or@light/@darkholding the same map for that theme only (when the app’s theme is set to it, or follows the system and the system is in it). - A property is a custom property (
--anything) or one of:accent-color,align-items,align-self,backdrop-filter,background,background-color,background-image,background-position,background-repeat,background-size,border,border-bottom,border-bottom-color,border-bottom-left-radius,border-bottom-right-radius,border-bottom-style,border-bottom-width,border-color,border-left,border-left-color,border-left-style,border-left-width,border-radius,border-right,border-right-color,border-right-style,border-right-width,border-style,border-top,border-top-color,border-top-left-radius,border-top-right-radius,border-top-style,border-top-width,border-width,box-shadow,caret-color,color,column-gap,cursor,display,fill,filter,flex,flex-direction,flex-grow,flex-shrink,font-family,font-size,font-style,font-variant-numeric,font-weight,gap,height,justify-content,letter-spacing,line-height,margin,margin-bottom,margin-left,margin-right,margin-top,max-height,max-width,min-height,min-width,opacity,order,outline,outline-color,outline-offset,outline-style,outline-width,padding,padding-bottom,padding-left,padding-right,padding-top,row-gap,stroke,text-align,text-decoration,text-decoration-color,text-shadow,text-transform,transition,visibility,width. - A value is plain CSS of at most 200 characters: no
;, braces,<,>,\,@,!, comments or unbalanced quotes;url()only with adata:image/URL, and noimage-set(): a theme fetches nothing. At most 400 declarations. Anything else is refused when the plugin installs.