WASM plugins for Zinc: design index (phase 1)
Zinc’s own plugin system: WebAssembly components with WIT interfaces. A plugin written for it can do what a Zotero plugin can do (the target is the current Zotero, 10; plugins written for Zotero 7–9 are covered too), including full UI customization through declarative UI trees. Phase 1 was design only: WIT files, a manifest schema, a UI tree schema, and per-area parity tables against Zotero’s source. Phase 2 built the host (jco under Bun, one Worker per plugin); phase 3 moved to Wasmtime (phase3-wasmtime-plan.md), and the Worker runner has since been removed: Wasmtime (zhw) is the only runner (phase3-runner.md). How Zotero’s plugin API changed from 7 to 11, and what that means for porting: zotero-versions.md.
Read RULES.md first for the ground rules, and the runtime spike (wasm-plugins-spike.md in the spike worktree) for why plugins are components in a separate process.
To write a plugin, start with Writing a Zinc plugin. If you use an AI coding agent, give it the agent skills for plugin authors: zinc-plugin-create makes a new plugin, zinc-plugin-port ports a Zotero plugin. How users turn plugins on and manage them: Plugins in the user guide.
Area reports and totals
Totals are tallied by script from the status column of each report’s parity tables (reconciled 2026-11-18).
| Area | Report | WIT file | What it covers | Rows | Covered | Partial | Not planned |
|---|---|---|---|---|---|---|---|
| lifecycle | lifecycle.md | lifecycle.wit, types.wit, world.wit | Package and manifest, install / startup / shutdown / uninstall, prefs, secrets, strings (Fluent), network, files and file grants, timers, clipboard, shell, log, helpers, permissions | 114 | 77 | 15 | 22 |
| library | library.md | library.wit | Items, collections, tags, searches, attachments and files, full text, schema, citations, translators, sync, change notifications | 133 | 69 | 39 | 25 |
| extend | extend.md | extend.wit | Menus, item pane sections and rows, columns, collection tree, toolbar, shortcuts, preference panes, tabs, banners, selection, drag and drop | 126 | 86 | 16 | 24 |
| ui | ui.md | ui.wit, ui-schema/ | The declarative UI tree, styles, events, views, dialogs, prompts, windows, toasts, popovers | 102 | 73 | 19 | 10 |
| reader | reader.md | reader.wit | Reader events and panels, annotations, selection, themes, note editor | 105 | 73 | 20 | 12 |
| Total | 580 | 378 | 109 | 93 |
Other files
plugin-api/manifest.schema.json: JSON Schema for themanifest.jsonat the root of a plugin package.$defs.capabilitylists all 36 permission ids with risk tiers (x-risk).plugin-api/ui-schema/ui-tree.schema.json: the nested JSON form of a UI tree.plugin-api/wit/world.wit: worldplugin(every interface) andplugin-minimal(app, prefs, l10n, log, timers, extend, ui; nofs,clipboard,shell,reader).
The WIT package
One package, zinc:plugin@0.1.0, spread over seven files.
| Interface | File | Direction | Purpose |
|---|---|---|---|
types |
types.wit | shared | Keys, ids, error, json, localized-string, icon-ref, color (and color-token), item-ref, file-grant, pref-value |
lifecycle |
lifecycle.wit | plugin exports | install, startup, shutdown, uninstall, main-window-load, main-window-unload |
events |
lifecycle.wit | plugin exports | Callbacks for prefs, timers, plugin events, locale, permissions |
app, plugins |
lifecycle.wit | host imports | App info and feature ids, windows, readiness; plugin records, updates |
prefs, secrets |
lifecycle.wit | host imports | Plugin preferences (and how UI controls bind to them); keys in the OS credential store |
l10n, log, timers, util |
lifecycle.wit | host imports | Strings and formatting; log; clock and timers; helpers |
net, net-events |
lifecycle.wit | imports, plugin exports | HTTP; download progress |
fs, clipboard, shell |
lifecycle.wit | host imports | Files in four roots and the file dialogs (the one set); clipboard (the one set); open URL, open file, reveal (the one set) |
permissions |
lifecycle.wit | host imports | Check and request permissions |
library, attachments, fulltext, schema, cite, translate, sync-control, data-utils, notifier |
library.wit | host imports | The library |
notifier-handler |
library.wit | plugin exports | Change event batches (data only: no UI-state types) |
extend |
extend.wit | host imports | Extension points in the main window |
extend-handlers |
extend.wit | plugin exports | Menu commands, column values, drops, and the selection, view, tab and theme events |
ui |
ui.wit | host imports | UI tree types, dialogs and prompts, windows, toasts, theme |
ui-events |
ui.wit | plugin exports | Mount, update, the one event entry point on-event, row ranges, suggestions |
annotations, reader, note-editor |
reader.wit | host imports | Annotations, readers, note editor |
reader-events, note-events |
reader.wit | plugin exports | Reader and note editor callbacks |
Check the whole package from the worktree root:
bunx @bytecodealliance/jco types plugin-api/wit --world-name plugin -o "$TEMP/zn-wit-check"bunx @bytecodealliance/jco types plugin-api/wit --world-name plugin-minimal -o "$TEMP/zn-wit-check-min"Reconciled on 2026-11-18
Five areas were written in parallel. The coordinator’s reconcile pass made them one design. What was merged (the area that owned the concept kept its design):
- One clipboard, one URL opener, one set of file dialogs. Kept:
clipboard.write/read,shell.open-url,fs.pick-open/pick-save/pick-directory. Removed:ui.copy-text,ui.read-clipboard-text,ui.open-url,ui.pick-files/pick-folder/pick-saveand their types. One file-grant type:types.file-grant(id,name,is-directory,size). Theidisfs.root::granted(id), andfs.read,fs.read-range,fs.writeturn it into bytes (the missing “token to bytes” path). Picks and drops arrive as the same record (ui.drop-info.files,extend.drop-payload.files);fs.list-grantswas added. The idsui.pick-files,ui.file-dialogsandui.clipboard-readare gone: a user’s pick is the consent. - Dialogs and prompts have one owner,
ui. Extend has none and refers to ui.open-dialog,open-windowandset-theme-overridenow returnresult<_, error>, because they need permissions or have a limit. - Extend placeholders (
node,node-event,form-values,file-grant) were already replaced by the extend area with the ui types; the reconcile confirmed it.ui-events.on-eventis the one event entry point (a section header button press iskind: presswithhandler= the button id). Reader had no placeholders. - One colour type:
types.color(token, token with alpha, fixed, pair per mode) withtypes.color-token, moved from ui. The oldtypes.color(hex or free token string) is gone. Annotation colours stay hex strings. themed-iconstays in extend: only extend uses it (ui and reader take oneicon-ref).- One item reference:
types.item-refreplaced the local one inannotations. Batch summaries:library.get-summaries(keys, fields, expand, include-trashed)is the “get items by keys with a field list” call for extend. Annotation items are served byannotationsonly; the library’s item calls refuse them.cite.formatgainednote-citationoutput for the note editor. - One dotted permission style, 36 ids, all in
manifest.schema.jsonwith risk tiers: 14library.*;clipboard.read/write;shell.open-url/open-file/reveal;plugins.read;prefs.app-read;ui.webview/windows/theme/drop/navigate;reader.read/control/ui/themes;annotations.read/write;note-editor.read/write/control/ui. (net.hostsis a list, not an id.) - Prefs and ui agree: the
prefsdoc comment says howui.node-props.prefandextend.setting-rowcontrols bind (same rules asgetandset, types per control,secretvalues insecretsas “pref:”). - Selection, view, tab and theme events come only from
extend.subscribe-events.notifier.object-typelosttab,itemtree,itempane,infobox. - Surfaces:
ui.surfacelists every surface extend and reader use.info-rowanditem-pane-header(unused) were removed;ui.window-kindwas removed (tabs and side panels areextend.open-tabandregister-side-panel).extend.menu-entry.swatch(atypes.color) was added for the reader’s menus. world.witwas checked against the files: every host interface is imported and every callback interface exported, names match the files.plugin-minimalstays and imports nofs,clipboard,shellorreader. Theapp-info.featuresids of all areas are in one doc comment.- Others: the reader’s view-state JSON has one owner (reader), with
attachments.get-view-stateas the stored copy;file-filterwas duplicated in ui and fs (the ui copy is gone with the dialogs);fulltext.get-contentandreader.get-page-textboth stay.
Decisions (user, 2026-11-18)
- Real menubar. Phase 2 adds a File / Edit / View / Go / Tools / Help menubar; plugin
menubar-*entries go into the named menu. The overflow “Plugins” menu is only a fallback until it exists. - Plugin sections in reader tabs. Item pane sections and the
notes-add-*menus appear in reader tabs, as in Zotero. - Virtual collections in v1. Plugins can add rows to the collection tree (
extend.register-virtual-collection). - A change log in the core. Phase 2 adds a change log and event stream to Zinc’s core, so
notifiersees every change, not only the plugin layer’s own writes.
Open questions for the user
Collected from the five reports (duplicates merged). Nothing here blocks phase 1.
Runtime and platform
- Re-entrancy while a call waits (lifecycle 1, extend 1, ui). While a plugin is suspended in a host import (JSPI:
net.send;ui.run-dialogwas removed in phase 3: dialogs useopen-dialogand acloseevent), may the host call another export of the same instance (a menu command,on-eventfor the dialog’s own buttons)? If not,uidrops its waiting calls and a guest SDK wrapsopen-dialoginto an awaitable. Needs a phase 2 spike. - Code signing and a store (lifecycle 2). Pin a hash and show a prompt only, or add publisher signatures or an allowlisted registry?
- Lazy start by default, and static
contributes(lifecycle 3, extend 3). Start plugins lazily when they listcontributes? Should menus, columns, section headers and preference rows be declarable in the manifest? - Zotero ports (lifecycle 4). Keep the JS-sandbox compat layer in parallel, or map
Zotero.*calls onto the WIT at build time? - App prefs allowlist (lifecycle 5, library, reader 5). Which Zinc settings and which
reader.*prefs mayprefs.get-appread, and may any be written (for example “default citation style”)? - Plugin data on uninstall (lifecycle 6). Delete
dataand prefs by default (the design), or keep them like Zotero? - WebSocket and SSE (lifecycle 7). Needed in 0.1?
- External viewers (lifecycle 8). Allow a user-chosen external program per file type as a Zinc setting that plugins can only trigger?
Library
- Read-only SQL view schema later? (library 1).
- Permission scope (library 2): per library or per collection?
- Permanent delete (library 3): allow
erasebehindlibrary.erasewith a prompt, or trash only? - First-class
duplicate-item,move-item-to-library,convert-to-stored-filechanges (library 4). - Plugin-supplied translators (library 5): run in the core’s translator sandbox, or only existing ones (the WIT offers the second)?
- Cap values (library 6): query page 1000, file read 8 MiB, upload 64 MiB, event queue 256 are guesses.
- Audit trail of plugin writes in the sync layer (library 7).
Main window (extend)
Real menubar(extend 2). Decided: yes (see “Decisions” below).Plugin sections in the reader(extend 4, reader). Decided: yes.Virtual collections(extend 5). Decided: yes, in v1.- Cells (extend 6): is the closed
cell-bodyset enough, or may a cell hold a smallui.tree? (Recommended: no.) - Banners (extend 7): keep a tiny public API, or toasts only?
UI (ui)
set-theme-override(ui 1): colours from plugins wanted, or never?- Custom fonts from the plugin package (ui 2): v1 or later?
web-viewcaps and z-order (ui 3): 2 per plugin, 4 total, drawn above GPUIX content: acceptable?embed.note-editoredit access (ui 4): edit, or read-only first?- JSON form only for JS guests (ui 5), typed form for Rust only?
- Drag to the OS from plugin UI (ui 6): allow or not?
- Small ui gaps (extend): a “close all toasts” call and a “choose from a list” prompt; row-style data on table nodes. Open, optional.
Reader
- EPUB and snapshot parity at launch (reader 1): plugin UI in the web reader, or PDF first?
- Selection text and privacy (reader 2): page text as a separate, higher-risk permission?
- Page overlays (reader 3): shapes only, or add
labelandiconshapes? - Link lists and PDF internals (reader 4):
get-page-links, PDF metadata? - Note editor toolbar (reader 6): an extension point in the note-editor fork, or the head strip only?
- Per-annotation private plugin data (reader 7): a store, or the plugin’s own storage?
- Read Aloud (reader 8): the one command, or a fuller interface when Zinc has the feature?
- Image and text annotation tools (reader 9): the WIT creates them before the tools exist: acceptable?
What the reconcile could not settle by itself
- The two parts that depend on a phase 2 spike: question 1 above, and how the host serves reader UI in the EPUB and snapshot web reader (question 28).
- No JSON Schema validator was run against sample manifests or sample UI trees (none is installed and
bun installis not allowed in this phase). Both schema files parse and every$refinui-tree.schema.jsonresolves.