Writing a Zinc plugin
A Zinc plugin is a WebAssembly component that implements the plugin world or one of its smaller family worlds (plugin-api/wit/world.wit). You write it in Rust or JavaScript,
build it with one command, and Zinc loads it into a separate plugin host process. That host is Wasmtime (zhw), the only runner; the component is precompiled to a .cwasm when the plugin is installed (phase3-runner.md). The SDKs hide the parts of the world you do not use:
the world exports 48 callback functions, and a plugin writes only the ones it needs.
With an AI coding agent, install the agent skills for plugin authors instead of walking through this page by hand: zinc-plugin-create scaffolds, builds, tests and packages a new plugin, and zinc-plugin-port assesses and ports a Zotero plugin.
Start
Rust (plugin-api/sdk/rust, crate zinc-plugin). Copy plugin-api/samples/word-count, rename it, and edit manifest.json and src/lib.rs.
[lib]crate-type = ["cdylib"][dependencies]zinc-plugin = { path = "<zinc>/plugin-api/sdk/rust", features = ["ui"] } # pick the world, see below[workspace] # keeps the crate out of a parent workspaceuse zinc_plugin::prelude::*;
struct Hello;impl Plugin for Hello { // every method has a no-op default fn startup(_d: PluginData, _why: Reason) -> Result<(), Error> { reg::register_menu(&menu::registration("hello", MenuTarget::MenubarTools, vec![MenuEntryBuilder::item("hello.say", "Say hello").build()]))?; Ok(()) } fn on_menu_command(_menu: String, entry: String, _checked: Option<bool>, _ctx: Context) -> Result<(), Error> { if entry == "hello.say" { log::info("hello"); } Ok(()) }}zinc_plugin::export_plugin!(Hello);Rust: pick a world with a cargo feature. Each feature selects a subset world (or full for everything); the highest feature wins. Because UI trees and patches are serialized as JSON (plugin-api/ui-schema/ui-tree.schema.json), every feature—including dialogs, ui, and full—compiles in seconds.
| feature | world | adds | compile (incremental) |
|---|---|---|---|
| none | plugin-core |
lifecycle, events, app, prefs, l10n, log, timers | ~2 s |
library |
plugin-library |
library, attachments, fulltext, schema, cite, translate, sync-control, data-utils, notifier | ~4 s |
extend |
plugin-extend |
menus, columns, panes, sections (registration only), extend-handlers | ~5 s |
dialogs |
plugin-dialogs |
ui imports (toasts, windows, push) without ui-events. Toasts only: a dialog’s outcome arrives as a close event on ui-events, so any dialog with an outcome needs ui |
~5 s |
ui |
plugin-ui |
ui imports + ui-events callbacks (mounted views, sections, dialogs with outcomes) |
~6 s |
mcp |
plugin-mcp |
plugin-library plus tools for AI agents (see “Exposing tools to AI agents (MCP)”) |
~5 s |
reader |
plugin-reader |
annotations, reader, note-editor, reader-events, note-events | ~6 s |
full (or reader + dialogs/ui) |
plugin |
everything, including net, fs, clipboard, shell, secrets | ~8 s |
Plugin state lives in thread_local! statics (callbacks are plain functions; the guest is single threaded).
JavaScript (plugin-api/sdk/js, QuickJS). Copy plugin-api/sdk/js/template (or samples/quick-tags).
import { definePlugin, ext } from "<zinc>/plugin-api/sdk/js/src/index.ts";import extend from "zinc:plugin/extend@0.1.0"; // the WIT interfaces are default importsconst plugin = definePlugin({ lifecycle: { startup() { extend.registerMenu(ext.menu("hello", "menubar-tools", [ext.entry("hello.say", "Say hello")])); } }, extendHandlers: { onMenuCommand(menu, entry) { /* ... */ } },});export const { lifecycle, events, netEvents, notifierHandler, uiEvents, extendHandlers, readerEvents, noteEvents } = plugin;Names follow jco: functions and fields are camelCase, enums are strings ("library-item"), variants are { tag, val }, an option is the value
or undefined, u64 is a BigInt. A callback that returns result<_, error> fails by throwing: fail("not-found", "no such item"). An import that
fails throws an object with .payload (the error variant). Types: bun plugin-api/sdk/js/scripts/gen-types.ts writes them from the WIT into
sdk/js/types/; add "include": ["<zinc>/plugin-api/sdk/js/types/index.d.ts"] to your tsconfig. Typecheck with bun check.
Build
bun plugin-host/scripts/build-plugin.ts <plugin dir> [--out <dir>] # Rust: cargo --target wasm32-wasip2bun plugin-api/sdk/js/scripts/build.ts <plugin dir> [--out <dir>] # JS: bundle the SDK in, componentize-qjsOutput (default <dir>/dist): manifest.json (with the sha256 added), plugin.wasm. Rust needs the
wasm32-wasip2 target and a recent toolchain. JS needs plugin-host/node_modules. Running a plugin needs the zhw binary
(cd plugin-host-wasmtime && cargo build --release).
Manifest and permissions
manifest.json follows plugin-api/manifest.schema.json. The parts you always write: id (name@domain), name, version (semver), zinc.api_version ("0.1"),
main (wasm, world), permissions. Default prefs go in default_prefs; localized strings in locale/. main.world names the world the component was built for (a JS build uses it as the componentize input; for Rust the cargo feature decides and the field is informational, but keep it true). The samples word-count, quick-tags and highlight-export set it to plugin; mcp-tools sets plugin-mcp.
A plugin can do only what permissions.capabilities lists (37 ids, with risk tiers in the schema) and the user grants. Calling an import without its permission returns
error::permission-denied(<id>). Network hosts are listed in permissions.net.hosts. Ask for the least: library.read for reading, library.write for
library.apply, library.fulltext.read for indexed text, annotations.read / annotations.write, reader.ui for reader menus and buttons, ui.windows
for extra windows, mcp.expose to offer tools to AI agents. Dialogs, toasts, prefs and logging need none. Put a sentence in permission_reasons for each: the install prompt shows it.
The extension points
All are registered in lifecycle.startup. Zinc removes them when the plugin stops. Callbacks arrive through the exported interfaces; the SDK
trait method for each is in parentheses (Rust) and the export name in brackets (JS).
| What | Register | Callback |
|---|---|---|
| Menu entries (item, collection, menubar, tab, …) | extend.register-menu(menu-registration) |
on-menu-command [extendHandlers.onMenuCommand], on-menu-showing for dynamic entries |
| Item list column | extend.register-column |
on-column-values(data-key, keys) returns one cell per key |
| Item pane section | extend.register-section |
ui-events.mount(instance, ctx) with ctx.view == pane-id, returns a tree; events come to on-event (Rust on_ui_event) |
| Settings pane | extend.register-pref-pane with setting-rows bound to prefs (no callback needed) |
on-pref-action for buttons |
| Toolbar button, shortcut, tab, banner, side panel | register-toolbar-button, register-shortcut, open-tab, show-banner, register-side-panel |
on-toolbar-click, on-shortcut, … |
| Reader toolbar button, reader menus, overlays, panels | reader.register-listener (target slot(toolbar) or menu(...)), register-overlay, register-panel |
reader-events.build-menu / on-menu-command (Rust build_reader_menu / on_reader_menu_command), render-overlay |
| Library changes | notifier.observe |
notifier-handler.on-events |
| Dialogs, prompts, toasts | ui.open-dialog (wrapped by SDK ui.dialog / ui::open_dialog_with), ui.confirm, ui.prompt, ui.show-toast |
dialog close and control events through ui-events.on-event |
UI trees and dialogs
A view returns a tree of nodes (box, text, button, text-input, checkbox, select, section, form, callout, table, …) serialized as JSON matching plugin-api/ui-schema/ui-tree.schema.json. Events name a handler id; you answer with the next tree or a JSON patch (content-update.patch).
// Rust: serde tree builders, serialized to JSONui::render(ui::column().gap(2) .child(ui::heading("Title")) .child(ui::text_input("").name("q").placeholder("search")) .child(ui::button("Go").on(EventKind::Press, "go")))// JS: the nested JSON form (plugin-api/ui-schema/ui-tree.schema.json)ui.render(ui.column({ style: { gap: 2 } }, ui.heading("Title"), ui.textInput("", { name: "q" }), ui.button("Go", { on: { press: "go" } })))Dialogs open non-blockingly via ui.open-dialog, and report their outcome ({ button, values }) through close events on ui-events.on-event (the pressed button first, then the form values). Because the event arrives on ui-events, a dialog with an outcome needs the ui feature or world; dialogs alone only covers toasts. ui.alert, confirm and prompt still block, which is fine because they show no plugin content. There is no blocking run-dialog (removed in phase 3):
- JS:
ui.dialog(ui.dialogSpec(title, content, buttons)).then((outcome) => { ... })(orawait ui.dialog(...)) returns a Promise resolved automatically bydefinePluginwhen the dialog’scloseevent arrives. - Rust:
ui::open_dialog_with(&spec, |outcome| { ... })orui::ask(title, content, "OK", |values| { ... })registers a continuation callback invoked automatically byGlue<P>when the dialog’scloseevent arrives. Read form values withui::field_text(&values, "name")/ui.fieldValue(values, "name").
Exposing tools to AI agents (MCP)
A plugin can offer tools to AI agents through Zinc’s MCP server: declare them in manifest.json (mcp.tools) or register them at run time, and answer calls in mcp-handler.on-mcp-call (JS defineTool, Rust mcp::Tool). It needs the mcp.expose permission and the user’s per-plugin switch in Settings > Plugins, which is off by default. See mcp.md and the sample plugin-api/samples/mcp-tools.
Installing and managing
Pack the build output for users with bun .claude/skills/zinc-plugin-create/scripts/pack.ts <out>. It writes <id>-<version>.zplugin (a zip), or with --wasm one <id>-<version>.wasm: plugin.wasm with the manifest, strings, icons and assets zipped into a custom section named zinc:package (plugin-host/src/package/wasm-package.ts). Custom sections carry no code, so the file is still the same component. The installer reads the manifest from the section without running anything, cuts the section out, and checks main.sha256 against what is left, so both forms install byte-identical code. The .wasm is larger (the code is not compressed); a .wasm without the section is refused. Since 0.2.3 users install either from Settings > Plugins > Install from file…: the app calls PluginManager.installPackage (plugin-host/src/package/installer.ts, see phase2-pkg.md) with the install prompt (gpui-ui/src/wasmplugins/ui/install.tsx), which shows your permission_reasons grouped by risk; high-risk permissions start unticked. Each installed plugin then has an on/off switch, Remove, and Review permissions… when an update waits for approval, next to the global “Enable plugins” switch (applied at the next start) and the per-plugin MCP switch above. The app code is installPluginPackage, setPluginEnabled, removePlugin and approvePluginPermissions in gpui-ui/src/wasmplugins/index.ts; gpui-ui/src/wasmplugins/install.test.ts drives them with a built plugin, and gpui-ui/scripts/shot-plugins.tsx screenshots the section and the prompt. What users see: Plugins in the user guide. For quick tests without installing, ZN_WASM_PLUGIN_DIRS loads built folders straight away.
Testing without Zinc
plugin-api/samples/test.ts is a template: build the plugin, load it with createPluginSupervisor, answer imports with stub where: "zinc" handlers
that record calls, then sup.call(id, "extend-handlers", "on-menu-command", [...]) and assert on the recorded calls.