Skip to content

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.” (lowercase, dots or dashes): a plugin you install is always user.*; wisp’s own ids are reserved.
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 { “”: “” }: plugins it needs on. A built-in plugin carries wisp’s version: “^1.0.0-0” takes this alpha and every 1.x (a plain “^1” waits for 1.0.0).
provides { “”: { “version”: “1.0.0” } }: a contract it implements (rare).
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”: [“”, …args] }: a process of its own, started in its folder with an emptied environment, speaking JSON-RPC. Leave it out for a plugin that is only UI and settings. (“builtin” is wisp’s own crates only.)
activation When it starts: “onStartup”, “onCommand:”, “onView:”, … (kinds below). Lazy is better: the first event that needs it.
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..”, “title”: “…”, “readOnly”: true }]: commands its server answers (ids start with the plugin’s id).
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..”, “type”: “bool”, “default”: false, “title”: “…” }]: settings of its own (types below), shown in Settings.
setSettings { “”: value }: values it sets for other plugins’ settings while it’s on (a theme, a preset).
ui [{ “id”: “user..pane”, “attachTo”: { “id”: “shell.settings”, “input”: “pane” }, “component”: “./ui.js#default”, “title”: “…” }]: what it shows. component is a .js module in its folder, run in a sandboxed Worker; where it may show is below.
parts Part names it adds for themes to style (an untrusted UI draws only kit components; it can’t style anything).
partStyles A theme: { “”: { “”: “” } }, plus “:root” for token overrides (–accent) and “@light” / “@dark” for one theme only. Applies in the app’s @layer plugins while the plugin is on and you trusted it (wisp plugin trust ); an untrusted plugin’s styles never apply. Only the properties and values listed under Themes below pass.
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 with on: event fires.

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.

Terminal window
wisp plugin install ./pink # installed, off and untrusted
wisp plugin trust user.pink # its styles may apply
wisp 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), :root for token overrides (custom properties only, like --accent), or @light / @dark holding 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 a data:image/ URL, and no image-set(): a theme fetches nothing. At most 400 declarations. Anything else is refused when the plugin installs.