Skip to content
ZincGitHubDownload

Plugin UI: the declarative tree

View as Markdown

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 by plugin-api/ui-schema/ui-tree.schema.json ($defs.tree, patchSet, rowContent/node, style, namedStyles). Every node has an optional key for 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 serde builders); the host validates it against the schema (full mode in tests and debug builds, cheap in release).
  • Events are handler ids. Any node carries events: list<event-binding>. The plugin gets ui-events.on-event(instance, ui-event) and returns the next render-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’s key.
  • 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 canvas draw list. Web content: a sandboxed web-view node (permission, count limit). Zinc’s own components: an embed node (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

  • key names 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 + name gives one submit event with all values; ui.form-values reads them at any time; the dialog’s close event (kind form) delivers them when it closes.
  • pref gives zero-call binding for preference panes.

Updates

  1. mount, update-context and on-event each return a render-result (content-update): unchanged, json (a whole tree) or patch (a JSON patch set). One call, whole answer.
  2. patch-set ops: 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).
  3. The host always diffs; patches only save serialization.
  4. Async work calls ui.push. The host batches pushes per frame.
  5. view-meta replaces 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. An image node 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 hit shapes, shows hover-tip, and pans and zooms with no calls; the plugin hears press, pointer-* and view-changed.
  • Text size: ui.measure-text batches measurements for label layout.
  • Cost: a draw list of 10,000 ops is lowered per update; use patch or fewer ops (polylines with flat points).
  • Not offered: per-pixel drawing, WebGL, offscreen canvases. A plugin that needs them renders to PNG in WASM and shows an image, or uses web-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 lists net hosts. allow-hosts must 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).
  • html and asset sources come from an opaque per-plugin origin with a strict content security policy: no network except allow-hosts, no file:, no access to Zinc’s local server ports.
  • No eval from the plugin. Communication is window.zinc.postMessage / web-post-message JSON 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 web event; the plugin may then call shell.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

  1. Is set-theme-override (colors from plugins) wanted, or should plugins never touch Zinc’s global look?
  2. Custom fonts from the plugin package: allow in v1 (needs GPUIX font loading per plugin) or leave out?
  3. web-view caps (2 per plugin, 4 total) and the “drawn above everything” behavior: acceptable?
  4. Should embed.note-editor offer edit access to plugins, or read-only first?
  5. Should the JSON form be the only form given to JS guests (smaller SDK), with the typed form for Rust only?
  6. 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), with types.color-token, moved from this file; extend uses it, ui-tree.schema.json documents its JSON form.
  • Permission ids: ui.webview, ui.windows, ui.theme (and ui.drop, ui.navigate from extend) are in the manifest schema; ui.clipboard-read and ui.file-dialogs were removed with the calls they guarded. world.wit imports ui and exports ui-events. The features list names ui.webview and ui.embed.<component>.
  • Extend: extend has no placeholders; it registers views and calls ui-events.mount, uses ui.render-result, ui.ui-event and ui.form-field and one on-event entry point. Dialogs and prompts have one owner (this area); extend refers to it. Menu data is ui.menu for popup menus and nodes; registered menus use extend.menu-entry.
  • Reader: reader panels, overlays and strips are surface.reader-sidebar, reader-overlay, toolbar-slot and popover views (confirmed); page overlays are drawn from reader-events.render-overlay shapes, so canvas needs no page coordinates. The attachment preview that reader row 22 asked for is embed-component.attachment-preview (already here). For the reader strips, view-context.height holds the fixed strip height (the host’s toolbar or annotation header height) and width the space available; a popover gets the host’s chosen size.
  • Prefs: node-props.pref binds through prefs.get and prefs.set rules in the plugin’s own namespace; the prefs interface lists which control binds to which pref type.
  • Files: drop-info.files carries types.file-grant; fs.read and fs.write turn it into bytes. ui.open-window, open-dialog and set-theme-override now return result<_, 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).