Plugin UI: the declarative tree
Area: ui. Files: plugin-api/wit/ui.wit (interfaces ui and ui-events), plugin-api/ui-schema/ui-tree.schema.json.
A Zotero plugin builds UI with the DOM, XUL, Zotero’s custom elements (chrome/content/zotero/elements/, 56 files) and CSS. A Zinc plugin cannot touch a DOM. It returns a UI tree as data. The host renders it with Zinc’s own GPUIX/Solid components (gpui-ui/src/ui/: Button, TextInput, Select, Checkbox, Switch, Tabs, Resizable, menus, dialogs, popovers; tokens in theme.ts) and sends events back as calls with a handler id.
Summary of the design
- Trees are JSON (phase 3). The phase 2 flat WIT tree (
nodes: list<node>with child indices) is gone: WIT forbids recursive types and the typed style records made Rust builds take minutes. A tree, a patch set, a row’s or cell’s custom content and styles are JSON strings, specified byplugin-api/ui-schema/ui-tree.schema.json($defs.tree,patchSet,rowContent/node,style,namedStyles). Every node has an optionalkeyfor identity. The text below that says “flat” or lists WIT node records describes the same shape as the schema’s node kinds. - One spelling. Both SDKs build the JSON form (JS nested objects, Rust
serdebuilders); the host validates it against the schema (fullmode in tests and debug builds,cheapin release). - Events are handler ids. Any node carries
events: list<event-binding>. The plugin getsui-events.on-event(instance, ui-event)and returns the nextrender-result. Debounce, throttle and key filters are part of the binding, so the host only calls the plugin when it must. - Host-kept state, plugin-owned values. Text being typed, scroll, selection and open/closed state live in the host. A plugin-supplied value (
value,open,selected, …) is applied only when it differs from the last value the plugin sent. To force a reset to the same value, change the node’skey. - Updates. Default is “return the whole tree” (the host diffs by key, so GPUIX only touches what changed). Big trees can send
patch-sets. Big lists are pulled: the host asks for row ranges. - Style is tokens plus a small set of raw values, not CSS. Theme tokens, light/dark color pairs, spacing scale, named styles, hover/pressed/focus states. Plugins can contribute colors to Zinc’s own theme (
set-theme-override). - Drawing: a vector
canvasdraw list. Web content: a sandboxedweb-viewnode (permission, count limit). Zinc’s own components: anembednode (note editor, item box, tags box, pickers).
Process boundary and cost
All calls cross into the plugin host process (spike: about 50 µs per round trip, plus lowering of the arguments). The rules that follow from that:
| Situation | What happens |
|---|---|
| Typing in a field | Host keeps the text. change (commit) is the default event. input is opt-in with debounce-ms. |
| Hover, scroll, resize, drag of a split or column | Host only. Events exist but are opt-in and throttled. |
| Canvas pan/zoom | Host transforms the draw list itself (pan-zoom); view-changed is throttled. Shape hit-testing and hover tips run in the host (hit, hover-tip). |
| Table with 50,000 rows | rows-source.virtual: host calls render-range for the visible window plus overscan, a few times per second at most. |
| Autocomplete | Local items need no call; dynamic calls suggest after debounce-ms. |
| Preference pane control | node-props.pref binds to a plugin pref with no call. |
| Async result (network answer) | Plugin calls ui.push(instance, result). |
| Stale events | Events carry rev; the plugin can ignore events for a tree it already replaced. A patch with the wrong base-rev is dropped and the host calls resync. |
Estimate (not measured): a 300-node tree is a few tens of KB lowered; one mount/on-event round trip stays well under a millisecond plus the plugin’s own work. A hung plugin is stopped by the plugin host (the other plugins keep running); its views show a “plugin not responding” placeholder.
What plugins build in practice
Taken from Zinc’s Zotero-plugin test corpus (docs/developer-guide/zotero-plugins.md in the zotero-plugins worktree: make-it-red, linter, pdf-translate, reference, actions-tags, better-notes) and from Zotero’s plugin APIs (itemPaneManager.js, menuManager.js):
- Item pane sections with a header, buttons and a body: lists of references, translated titles, relation graphs, backlinks (reference, pdf-translate, better-notes).
- Settings panes: checkboxes, text fields, dropdowns, sections, tables with editable rows, icon buttons, preference bindings (linter, actions-tags, reference).
- Menu items and submenus, some dynamic (
onShowing). - Dialogs with forms and buttons; progress windows; prompts; command-palette overlays (zotero-plugin-toolkit
Prompt). - A virtualized table (actions-tags), item and collection pickers (better-notes), a note editor (better-notes), a relation graph (better-notes).
- CSS that recolors or hides parts of Zotero (make-it-red, many small plugins).
- Embedded web pages (a few plugins; translation and AI-chat panels).
1. Parity table: elements and APIs plugins use
Status is the last column.
| Zotero capability (source) | Zinc WIT | Status |
|---|---|---|
button, html:button, toolbarbutton (XUL/HTML) |
node-kind.button (look, size, icon, pressed toggle, loading) |
covered |
checkbox, input[type=checkbox] |
checkbox (with indeterminate) |
covered |
moz-toggle / switch |
switch |
covered |
radiogroup, radio |
radio-group |
covered |
menulist, menupopup, menuitem, html:select |
select (groups, search, multiple) |
covered |
html:input text/search/password, textbox, search-textbox, quick-search-textbox, query-textbox |
text-input (kind, clear-button, suggest) |
covered |
html:textarea |
text-input with multiline, min-rows, max-rows |
covered |
input[type=number] |
number-input |
covered |
input[type=color], color-picker (elements/colorPicker.js) |
color-input with swatches |
covered |
input[type=range] |
slider |
covered |
input[type=date/time] |
date-input |
covered |
input[type=file], FilePicker |
fs.pick-open, fs.pick-save, fs.pick-directory (lifecycle; the ui area has no file dialogs). A button press calls them. Results are types.file-grants, never paths; fs.read and fs.write turn a grant into bytes |
covered |
hbox, vbox, box, html:div |
box with style.direction, gap, align-items |
covered |
grid, rows, columns, row |
grid (columns, rows, spans in style.grid-column) |
covered |
scrollbox, overflow: auto |
scroll (scroll-to, stick-to-end) |
covered |
splitter |
split (sizes, min-sizes, persist-key, collapsible) |
covered |
tabbox, tabs, tab, tabpanels |
tabs (keep-alive, closable, badge) |
covered |
deck |
deck |
covered |
groupbox, caption |
group |
covered |
html:details/summary, collapsible-section (elements/collapsibleSection.js) |
section (open, summary, count, buttons, persist-key) |
covered |
label, description, html:span/p/h1-h6 |
text (kinds, runs with bold/italic/mono/links) |
covered |
html:a, zotero-text-link (elements/textLink.js) |
link, or a link run in text |
covered |
html:img, image |
image (asset, PNG/JPEG bytes, SVG rasterized, attachment thumbnail) |
covered |
icons in -moz-context-properties style (icon/darkIcon) |
ui-icon = icon-ref (builtin, bundled with -dark variant, svg), icon node |
covered |
html:progress, progressmeter |
progress (bar, ring, spinner) |
covered |
separator, spacer, toolbarseparator |
separator, spacer |
covered |
toolbar, toolbarbutton groups |
toolbar (overflow) |
covered |
richlistbox, richlistitem, richlistcheckbox (elements/richlistCheckbox.js) |
list-view with custom row content (row.content) |
covered |
legacy listbox, XUL tree |
list-view / table with tree: true |
covered |
VirtualizedTable (React, used by actions-tags, better-notes pickers) |
table with rows-source.virtual and ui-events.render-range |
covered |
html:table |
table |
covered |
menupopup as context menu, contextmenu attribute |
node-props.context-menu, ui.popup-menu |
covered |
panel, popup, html:dialog anchored panels |
popover node (placement, arrow, dismiss) |
covered |
tooltip, tooltiptext, title |
node-props.tooltip (text) |
partial (plain text only; no rich tooltip content) |
html:canvas 2D |
canvas (vector draw list, hit testing, pan/zoom) |
partial (no per-pixel drawing, no WebGL; see Canvas) |
html:iframe, xul:browser |
web-view (sandbox, host allow-list, messaging) |
partial (permission, count limit, placed over the UI; see Web content) |
innerHTML, bodyXHTML (itemPaneManager.js) |
rich-text html-subset and markdown |
partial (safe subset; no scripts, styles, forms, iframes) |
Plugin-defined customElements.define |
Plugin functions that build node subtrees; named styles for reuse | not planned (needs a DOM; a function returning nodes does the same job) |
Direct DOM edits of Zotero’s own windows (getElementById, insertBefore, appendChild into zotero-items-tree) |
Extension points in extend (sections, menus, columns, toolbar slots) |
not planned (Zinc’s UI is native GPUIX, not DOM; the corpus shows this cannot work) |
Inline and linked CSS for the plugin’s own UI (style="", <style>, <link>) |
style, named-style, state-styles, color tokens and themed-color |
partial (no selectors, cascade only for text; see Styling) |
| CSS that recolors Zotero (make-it-red) | ui.set-theme-override (token colors, light and dark) |
partial (colors only, user can switch off) |
| CSS that hides, resizes or reflows built-in Zotero UI | none | not planned (arbitrary restyling breaks native components; use extend to hide registered items, theme tokens for color) |
CSS animations, @keyframes, transitions |
icon.spin, progress, skeleton; the host animates its own state changes |
partial |
@font-face, custom fonts |
font-family is sans, title or mono |
not planned (v1; see open questions) |
| DOM events: click, dblclick, contextmenu, input, change, keydown/up, focus, blur, scroll, mouseover/out, resize | event-kind + event-binding (debounce, throttle, key filter) |
covered |
submit of a form |
form node, submit event with form-field list |
covered |
Drag and drop (dragstart, drop, Zotero.DragDrop) |
draggable, drop-target, drop event (items, text, files as types.file-grant, custom) |
partial (no drags out to the OS, no arbitrary MIME types) |
focus(), tabindex, autofocus |
auto-focus, render-result.focus, ui.focus, a11y.tab-index |
covered |
aria-*, role |
a11y record on every node |
covered |
data-l10n-id, .ftl, Zotero.getString |
ui-text = localized-string (Fluent id and args resolved by the host, so locale changes need no call) |
covered |
dir="rtl", logical CSS |
edges.start/end, theme-info.rtl, host mirrors layout |
covered |
navigator.clipboard.writeText, copyTextToClipboard |
clipboard.write (lifecycle; the ui area has no clipboard calls) |
covered |
navigator.clipboard.readText |
clipboard.read (lifecycle; permission clipboard.read) |
covered |
Zotero.launchURL, openLink |
shell.open-url (lifecycle; a link node with a url target needs no call) |
covered |
Services.prompt.alert/confirm/prompt, Zotero.alert |
ui.alert, ui.confirm, ui.prompt |
covered |
Services.prompt.confirmEx (up to 3 buttons, checkbox) |
ui.confirm (checkbox) or ui.open-dialog (any buttons; the pressed button arrives as a close event) |
covered |
window.openDialog with plugin XHTML, zotero-plugin-toolkit Dialog |
ui.open-dialog (answer in the close event), update-dialog, close-dialog, dialog-spec |
covered |
Zotero.ProgressWindow and toolkit ProgressWindowHelper |
ui.show-toast, update-toast, close-toast (lines with progress, actions) |
covered |
Plugin windows (window.open, openWindowByType) |
ui.open-window (an OS window; permission ui.windows; returns result) |
covered |
Custom main tabs (Zotero_Tabs.add content) |
extend.open-tab: the tab content is a ui view with surface.tab (ui.window-kind was removed so there is one way to make a tab) |
covered |
Command palette / overlay (toolkit Prompt, DOM in main window) |
popover or open-window with a text-input + list-view; global shortcut in extend |
partial (no overlay above the whole window; a modal dialog is the nearest) |
Zotero.PreferencePanes.register XHTML with preference="..." |
surface.preferences-pane view; node-props.pref binds controls to plugin prefs with no call |
covered |
ItemPaneManager.registerSection: onInit, onItemChange, onRender, onAsyncRender, onToggle, onDestroy |
ui-events.mount, update-context, visibility, unmount; async work uses ui.push |
covered (registration is in extend) |
Section hook args setL10nArgs, setEnabled, setSectionSummary, setSectionButtonStatus, refresh |
render-result.meta (view-meta), ui.refresh |
covered |
Section header (icon, l10n), sidenav, sectionButtons (onClick) |
registration in extend; button presses arrive as press with the button id; states via view-meta.buttons |
partial (registration shape is extend’s) |
ItemPaneManager.registerInfoRow (custom Info row: label, editable value) |
extend.register-info-row, on-info-row-get, on-info-row-set (plain text values; ui.surface.info-row was removed, there is no view for a row) |
covered |
MenuManager.registerMenu MenuData (menuType menuitem, separator, submenu; l10nID, icon, darkIcon, menus) |
ui.menu, menu-item (adds check, radio, heading, danger, hidden) |
covered |
MenuData hooks onShowing, onShown, onHiding, onHidden, enableForTabTypes; targets such as main/library/item |
registration and hooks in extend; menu is the data they return |
partial |
| Reader panels, toolbars, popups (reader plugin events) | surface.reader-sidebar, reader-overlay views; events in reader |
partial (owned by reader) |
| Zotero’s own item pane header and Info fields editable by plugins | none | not planned (native components; use embed.item-box for a copy) |
2. Parity table: every file in chrome/content/zotero/elements/
| Zotero element (file) | Zinc equivalent | Status |
|---|---|---|
abstractBox.js (abstract-box) |
embed abstract-box |
covered |
advancedSearchDeck.js, advancedSearchPane.js, zoteroSearch.js (zoterosearch, search-condition-group, zoterosearchcondition, zoterosearchtextbox, zoterosearchagefield) |
embed search-builder (search JSON in and out) |
covered |
annotationItemsPane.js, attachmentAnnotationsBox.js |
embed attachment-annotations |
partial (read-only list in v1; reader surface is reader’s) |
annotationRow.js, noteRow.js, attachmentRow.js |
Compose with list-view rows and text/icon/button |
covered |
attachmentBox.js, attachmentsBox.js |
embed attachments-box |
covered |
attachmentPreview.js, attachmentPreviewBox.js |
embed attachment-preview; or image attachment thumbnail |
covered |
autocompleteTextArea.js, shadowAutocompleteInput.js |
text-input with suggest |
covered |
base.js (XULElementBase, framework class) |
Not a component | not planned (framework base class for Zotero’s own elements; no equivalent needed) |
bubbleInput.js (bubble-input) |
token-input |
covered |
collapsibleSection.js |
section |
covered |
colorPicker.js |
color-input |
covered |
contextNotesList.js, contextPane.js, notesContext.js (reader context pane) |
surface.side-panel / reader-sidebar views |
partial (reader area owns the panel) |
duplicatesMergePane.js, mergeGroup.js (merge-group, merge-pane) |
Build from table and radio-group; merging through the library interface |
partial (no ready-made merge UI) |
editableText.js (editable-text) |
text-input with look: inline |
covered |
fileRenamingSettings.js |
Built-in settings control | not planned (specific to Zotero’s own file-renaming preference; a plugin builds its own from controls) |
guidancePanel.js |
popover with arrow (anchored to a plugin node) |
partial (cannot point at Zinc’s own built-in elements) |
itemBox.js (info-box) |
embed item-box |
covered |
itemDetails.js, itemPane.js, itemPaneContainerBase.mjs, itemPaneSectionElementBase.mjs, itemPaneCustomSection.js, itemPaneHeader.js, itemPaneSidenav.js, itemMessagePane.js |
Item pane host; plugin body is a view; registration in extend |
partial (frame and sidenav are Zinc’s own; callout replaces item-message-pane for in-body messages) |
itemTreeMenuBar.js |
Menu registration in extend |
partial |
librariesCollectionsBox.js |
embed libraries-collections-box |
covered |
libraryView.js (library-view) |
embed collection-picker |
covered |
menulistItemTypes.js (menulist-item-types) |
select filled with item types from the library interface |
covered |
noteBox.js, notesBox.js, relatedBox.js, tagsBox.js |
embed notes-box, related-box, tags-box |
covered |
noteEditor.js (note-editor, links-box) |
embed note-editor |
partial (the host offers its note editor with item key and read-only; no access to editor internals, so better-notes’ deep editor patching is not possible; plugin uses reader’s note-editor interface) |
publicationsLicenseInfo.js |
Content for My Publications | not planned (Zinc has no My Publications; rich-text shows any license text) |
queryTextbox.js, quickSearchTextbox.js, searchTextbox.js |
text-input kind: search |
covered |
richlistCheckbox.js |
list-view row with a checkbox |
covered |
splitMenuButton.js |
button with menu and menu-mode: split |
covered |
styleConfigurator.js (locale-selector, style-selector, style-configurator) |
embed style-picker; select for locale |
covered |
tabContent.js, tabsMenuPanel.js |
Main tab strip | not planned (Zinc’s own chrome; plugins add tabs through extend/open-window) |
utils/collapsiblePane.mjs |
Internal helper | not planned (implementation detail of section) |
Counts for this area, tallied by script over both tables above: 102 rows; covered 73, partial 19, not planned 10.
3. Node component reference
| Node kind | Main fields | Events it can fire | GPUIX base | Zotero equivalent |
|---|---|---|---|---|
box |
style only | press, hover, focus, key, drop, context-menu | div |
hbox, vbox, div |
grid |
columns, rows, gaps |
as box | div grid |
grid |
scroll |
axis, scroll-to, stick-to-end |
scroll | scroller | scrollbox |
split |
orientation, sizes, min-sizes, persist-key |
resize | Resizable |
splitter |
tabs |
tabs, selected, look, keep-alive |
change (tab key), close | Tabs |
tabbox |
deck |
selected |
none | switch | deck |
section |
title, open, summary, buttons |
toggle, press (button id) | itempane/kit Section |
collapsible-section |
group, card |
caption |
none | div |
groupbox |
toolbar |
overflow |
none | div |
toolbar |
text, link |
kind, runs, target |
press (link) | text |
label, description, a |
image, icon |
source, fit, alt; icon, spin |
press | img, svg |
img, image |
progress, badge, callout, skeleton |
value, tone, dismissible |
close | custom | progressmeter, item-message-pane |
rich-text, code |
format, source; language |
press (link handler) | markdown renderer | innerHTML, pre |
button |
look, size, pressed, menu, loading |
press, context-menu | Button |
button, toolbarbutton, split-menu-button |
checkbox, switch, radio-group |
checked/on/value |
change | Checkbox, Switch |
checkbox, radiogroup |
select |
options, value, multiple |
change | Select |
menulist |
text-input |
value, kind, look, multiline, suggest |
input, change, submit, focus, blur, key | TextInput |
textbox, textarea, editable-text |
number-input, slider, color-input, date-input |
value, ranges | input, change | custom | input types |
token-input |
tokens, suggest, allow-new |
change | custom | bubble-input |
form |
busy |
submit | div |
form |
list-view |
rows, selection, selected |
select, activate, press, context-menu, drop, scroll | virtual list | richlistbox |
table |
columns, rows, sort, tree |
select, activate, sort, resize, toggle, context-menu, drop | table/Table |
VirtualizedTable |
popover |
open, placement, arrow |
close | Popover |
panel, popup |
canvas |
ops, pan-zoom, view |
press, pointer-*, wheel, view-changed | custom paint | html:canvas |
web-view |
source, sandbox, allow-hosts |
message, web | webview/ host |
iframe, browser |
embed |
component, params |
embed, change | native Zinc components | Zotero custom elements |
Every node also has key, name, pref, class, style, states, a11y, tooltip, context-menu, disabled, hidden, draggable, drop-target, auto-focus.
4. Design notes
Flat node list, and why
A recursive node is illegal in WIT. The options were (a) a JSON string (what the spike did), (b) a flat list with child indices, (c) a resource per node. (c) turns every node into a boundary call. (a) loses typing, so errors show at run time and nothing validates in Rust. The flat list keeps a typed contract, crosses the boundary once, and is easy to diff because the host builds the keyed tree from it. The nested JSON form is kept as a convenience, with a schema, because it is the natural thing for JS and for tools that generate UI. Node order does not matter except for children; a node used by two parents is an error.
Identity, state and two-way binding
keynames a node across renders. Without it, identity is position among siblings.- The host owns edit state. Controlled values follow the “apply only when the plugin’s value changed” rule, so a re-render triggered by something else never overwrites what the user is typing.
form+namegives onesubmitevent with all values;ui.form-valuesreads them at any time; the dialog’scloseevent (kindform) delivers them when it closes.prefgives zero-call binding for preference panes.
Updates
mount,update-contextandon-eventeach return arender-result(content-update):unchanged,json(a whole tree) orpatch(a JSON patch set). One call, whole answer.patch-setops:set-node,replace,insert,remove,move,set-styles, all by key. Use them when a tree is large and a change is small (a table cell, a log line).- The host always diffs; patches only save serialization.
- Async work calls
ui.push. The host batches pushes per frame. view-metareplaces Zotero’s section helper calls (title args, enabled, summary, button status).
Large lists
rows-source.virtual gives a row count and a row height. The host calls render-range(start, count) for the window plus overscan. Sorting is a request parameter (range-request.sort), so the plugin sorts, not the host. Tree tables expose only visible rows: on toggle the plugin returns a new count and the host re-requests. Inline rows (up to a few hundred) can be sorted by the host from cell.sort-value.
Styling and “full customization” without CSS
Plugins get: layout (flex, grid, absolute), size, spacing on a 4 px scale, colors from theme tokens (the names in theme.ts), eight categorical palette colors, fixed colors per mode (themed-color), border, radius, shadow, opacity, font size/family/weight, text wrap and clamp, cursor, hover/pressed/focus/disabled/selected states, named styles for reuse. Icons are built-in names, bundled SVG/PNG (with -dark variants) or inline SVG. Raster pictures are image nodes.
Limits: no selectors, no descendant rules, no calc, no transforms outside canvas, no pseudo-elements, no custom fonts, no z-order above host chrome, no styling of built-in Zinc controls. Text properties inherit; everything else does not.
How Zotero plugins inject CSS today and what covers each case:
| Use | Covered by |
|---|---|
| Style the plugin’s own pane, dialog or section | style, named-style, states (covered) |
| Light and dark variants of its own colors | color-token, themed-color (covered) |
| Recolor the whole app (make-it-red) | set-theme-override with ui.theme permission (covered for colors) |
| Change fonts, density, row height of built-in lists | not available; Zinc’s own appearance settings do this |
| Hide or move built-in buttons and rows | not available; extend can hide only what a plugin registered |
| Icons for toolbar and menu items | icon-ref bundled/svg (covered) |
set-theme-override shows in Settings > Plugins with a switch; with several plugins the last enabled wins per token.
Canvas
Choice: a vector draw list (canvas.ops: rect, ellipse, line, polyline, path, text, image, groups) plus image nodes for rasters.
- GPUIX’s
<svg>paints only an alpha mask (one color), so “return an SVG string” cannot draw a colored chart. Animagenode with SVG source is rasterized by the host in full color and covers static pictures. - Interactive graphs (better-notes’ relation graph, citation networks, timelines) need hit-testing and pan/zoom. With raster bytes, every hover would be a round trip. With a draw list, the host tests
hitshapes, showshover-tip, and pans and zooms with no calls; the plugin hearspress,pointer-*andview-changed. - Text size:
ui.measure-textbatches measurements for label layout. - Cost: a draw list of 10,000 ops is lowered per update; use
patchor fewer ops (polylines with flatpoints). - Not offered: per-pixel drawing, WebGL, offscreen canvases. A plugin that needs them renders to PNG in WASM and shows an
image, or usesweb-view.
Web content
Zinc’s gpui-ui/src/webview/ is WebView2 in its own owned popup window placed over a placeholder (GPUIX has no web element), about 100-200 MB per instance, created only when used. So web-view is offered with these limits, enforced by the host:
- Permission
ui.webview; the manifest listsnethosts.allow-hostsmust be a subset. - At most 2 live views per plugin and 4 in total; a view that is hidden or scrolled out is released and reloaded when shown (state is lost unless
persist-storage). - Own WebView2 profile per plugin (cookies and storage separate from Zinc and other plugins).
htmlandassetsources come from an opaque per-plugin origin with a strict content security policy: no network exceptallow-hosts, nofile:, no access to Zinc’s local server ports.- No
evalfrom the plugin. Communication iswindow.zinc.postMessage/web-post-messageJSON only. - It is drawn above GPUIX content: popovers and menus over it are cut (the host cuts holes for toasts as it does today). Do not place a popover over a web view.
- Navigation outside the allow-list is blocked and reported as a
webevent; the plugin may then callshell.open-url. - Not available in Zinc builds without WebView2 (
webViewSupported()false);theme-info/lifecycle features list reports it.
Host components (embed)
Plugins such as better-notes embed Zotero’s own elements. embed draws Zinc’s native equivalents with the plugin’s data: note editor, item box, tags, related, attachments, notes, attachment preview and annotations, item and collection pickers, search builder, style picker. Each needs the matching library permission (read for display; write for editing components). Parameters are JSON so components can grow without a WIT change. Events return as embed with a JSON payload.
Accessibility and localization
Every node has an a11y record. Defaults come from the component (a button is a button). Icon-only buttons must set a11y.label; an image needs alt or a11y.hidden. ui-text.localized is resolved by the host against the plugin’s Fluent files and the current locale, so a locale change re-resolves text with no plugin call. Layout uses start/end and mirrors for right-to-left locales.
Rust and JS ergonomics
All records have many optional fields. Rust guests are expected to use an SDK of builders (phase 2). JS guests use the JSON form, where options are just missing keys and enums are strings. Both end in the same flat tree.
Host limits (proposed, to be set in phase 2)
| Limit | Value |
|---|---|
| Nodes per tree | 5,000 (inline rows count; use virtual rows beyond that) |
| Tree depth | 64 |
| Draw ops per canvas | 20,000 |
| Image bytes per node | 4 MB; 32 MB per plugin in total |
| Update rate | at most 30 push per second per instance; extra pushes are merged |
on-event / render-range time limit |
1 s, then the last good tree stays and the plugin is flagged |
| Open dialogs | 1 modal, 3 modeless per plugin |
5. Open questions for the user
- Is
set-theme-override(colors from plugins) wanted, or should plugins never touch Zinc’s global look? - Custom fonts from the plugin package: allow in v1 (needs GPUIX font loading per plugin) or leave out?
web-viewcaps (2 per plugin, 4 total) and the “drawn above everything” behavior: acceptable?- Should
embed.note-editoroffer edit access to plugins, or read-only first? - Should the JSON form be the only form given to JS guests (smaller SDK), with the typed form for Rust only?
- Drag and drop to the OS (files out of Zinc) from plugin UI: allow or not?
6. Needs from other areas
Resolved in the reconcile of 2026-11-18 (see README):
- Colour: there is one colour type,
types.color(token, token with alpha, fixed, pair per mode), withtypes.color-token, moved from this file; extend uses it,ui-tree.schema.jsondocuments its JSON form. - Permission ids:
ui.webview,ui.windows,ui.theme(andui.drop,ui.navigatefrom extend) are in the manifest schema;ui.clipboard-readandui.file-dialogswere removed with the calls they guarded.world.witimportsuiand exportsui-events. The features list namesui.webviewandui.embed.<component>. - Extend: extend has no placeholders; it registers views and calls
ui-events.mount, usesui.render-result,ui.ui-eventandui.form-fieldand oneon-evententry point. Dialogs and prompts have one owner (this area); extend refers to it. Menu data isui.menufor popup menus and nodes; registered menus useextend.menu-entry. - Reader: reader panels, overlays and strips are
surface.reader-sidebar,reader-overlay,toolbar-slotandpopoverviews (confirmed); page overlays are drawn fromreader-events.render-overlayshapes, socanvasneeds no page coordinates. The attachment preview that reader row 22 asked for isembed-component.attachment-preview(already here). For the reader strips,view-context.heightholds the fixed strip height (the host’s toolbar or annotation header height) andwidththe space available; a popover gets the host’s chosen size. - Prefs:
node-props.prefbinds throughprefs.getandprefs.setrules in the plugin’s own namespace; theprefsinterface lists which control binds to which pref type. - Files:
drop-info.filescarriestypes.file-grant;fs.readandfs.writeturn it into bytes.ui.open-window,open-dialogandset-theme-overridenow returnresult<_, error>so a missing permission or a second modal dialog has an answer.
Still open: none from this area’s list. The “close all toasts” call and a “choose from a list” prompt that extend asked for are open (see extend.md).