Phase 2, extend agent: extension points in the main window
Status 2026-11-18. WIT: extend.wit. Result: bun test src/wasmplugins/extend/extend.test.ts in gpui-ui/: 16 pass; bun scripts/shot-wasm-extend.tsx: all 21 checks pass (headless, with the real QuickJS fixture plugin in the plugin host process); bun check in gpui-ui/: clean; the existing sidebar / shell / cards / table / itempane tests (90) still pass.
What was built
| File | What it is |
|---|---|
gpui-ui/src/wasmplugins/index.ts |
App wiring. startWasmPlugins() creates the one supervisor, collects every where:"zinc" handler, loads and starts the installed plugins, binds the window side, clears registrations on host-restart and on a plugin’s stopped / disabled / failed. Accessors for the ui and reader agents: getPluginSupervisor(), pluginSupervisor() (reactive), useWasmPlugins(), callPlugin(), onPluginRegistrationsReset(fn), addZincHandlers(). |
wasmplugins/host.ts, flag.ts, register.ts |
Light parts: supervisor holder and reset signal; the switch; the Settings > Plugins section. |
wasmplugins/extend/handler.ts |
The zinc:plugin/extend import handler (every function of the interface). plugin-host/src/imports/extend.zinc.ts re-exports it (named .zinc.ts so discoverHandlers("zinc") finds it). |
extend/registry.ts, wit.ts |
Reactive registries per extension point, namespaced by plugin; jco-shaped TS types of the WIT. |
extend/navigation.ts, bind.ts, context.ts |
The host the handler uses (selection, view, tabs, navigation), bound to the store; context and condition context; mirrors of plugin menu entries and shortcuts into registry.ts; the debounced on-event stream. |
extend/conditions.ts, cache.ts, data.ts, menus.ts, drop.ts, prefs.ts, text.ts, style.ts |
condition evaluation; the batch cache; column cells, row styles, decorations and info row values (cached, invalidated); menu resolution, on-menu-showing (120 ms), commands; file drops; plugin prefs adapter; text and colour conversion. |
extend/Sections.tsx, InfoRows.tsx, ToolbarSlot.tsx, Chrome.tsx, Tree.tsx, settings.tsx, viewSlot.tsx, columns.ts |
The UI: item pane sections, Info rows, toolbar buttons and views, menubar, banners, tabs, side panels, collection decorations and virtual collections, preference panes, the PluginView slot, table columns. |
| Edits to existing files | registry.ts (unregister functions, disabled, group "plugins"), cards/menus.ts, itempane/index.tsx, itempane/Info.tsx, Toolbar.tsx, TopBar.tsx, App.tsx, sidebar/Collections.tsx, table/defs.ts, table/headless.ts, table/Table.tsx, features.ts, platform.ts. All are no-ops while no plugin registered anything. |
extend/extend.test.ts, gpui-ui/test/wasm-extend-fixture/, gpui-ui/scripts/shot-wasm-extend.tsx |
Tests, the QuickJS fixture plugin, the headless window check. |
Run it
cd gpui-uibun checkZN_UI_STATE=off bun test src/wasmplugins/extend/extend.test.ts # builds the fixture first (about 12 s); ZN_EXTEND_FIXTURE=<built folder> skips thatbun scripts/shot-wasm-extend.tsx [dark|light] # needs no core: it makes a throw-away library and runs the core in-processTurn plugins on in the real app: Settings > Plugins (takes effect at the next start) or ZN_WASM_PLUGINS=1. Installed plugins are the folders under ZN_PLUGINS_DIR (default %APPDATA%\zotero-next-gpui\plugins), each in the layout of plugin-host/src/manifest.ts (manifest.json, transpiled/plugin.js). Off by default: with the switch off nothing starts, no menubar is drawn and the default app is unchanged.
What the tests prove
extend.test.ts: conditions; the batch cache (50 rows = one call, cached, per-key invalidation, 200-key batches, a failing call keeps the last value); the handler (namespacing, conflict, permissions ui.windows / ui.drop / ui.navigate / library.read, built-in tab kinds refused, all-or-none register-columns, navigation through a bound host, unavailable without one); menu resolution (children, conditions, patches); and the QuickJS fixture through the real supervisor: everything is registered at startup, a column for 40 rows is fetched in ONE call of 40 keys, a menu command and a toolbar click reach the plugin, the Info row value comes from the plugin, and registrations are gone after the plugin stops.
shot-wasm-extend.tsx (whole <App/>, headless): toolbar button drawn and its click reaches the plugin; item pane section header drawn; Info row label and plugin value drawn; the menubar (File / Edit / View / Go / Tools / Help) drawn with the plugin’s Tools entry and its click reaching the plugin; the item context menu entry drawn and its click reaching the plugin (items=1); the shortcut reaches the plugin; the plugin column’s cells drawn in the Classic table, fetched in batches; the plugin’s preference pane row drawn in Settings. Screenshots go to <scratch>/gpui-shots/wasm-extend-*.png.
WIT rows now implemented (interface.function)
extend.: register-menu, replace-menu-entries, patch-menu, register-section, register-info-row, refresh-info-row, register-column, register-columns, invalidate-columns, register-row-style, invalidate-row-styles, register-collection-decoration, invalidate-collection-decorations, register-virtual-collection, invalidate-virtual-collection, register-toolbar-button, set-toolbar-button-state, register-toolbar-view, register-side-panel, set-side-panel-open, register-shortcut, register-pref-pane, replace-pref-rows, open-tab, select-tab, close-tab, rename-tab, set-tab-pinned, move-tab, list-tabs, selected-tab, show-banner, hide-banner, get-context, list-selected-items, get-view, list-view-items, select-items, select-row, set-search, set-panel-visible, open-settings, open-item, register-drop-target, register-drag-format (registry only), subscribe-events, unregister.
extend-handlers. called by the host: on-menu-showing, on-menu-phase (helper only, see below), on-menu-command, on-toolbar-click, on-shortcut, on-info-row-get, on-info-row-set, on-column-values, on-row-styles, on-collection-decorations, on-virtual-collection-items, on-pref-pane-open, on-pref-pane-close, on-pref-action, on-tab-closing, on-banner-action, on-drop, on-event (selection, view, tab-selected, theme; debounced 100 ms).
How each extension point is mounted
- Menus.
library-itementries become item actions (group"plugins", last before Trash; submenus one level),library-collectioncollection actions,library-add,library-add-attachment,library-add-noteentries of the Add menu. Visible and enabled conditions andentry-patches apply when the menu is built;on-menu-showingruns for the item menu in parallel with the detail fetch (at most 120 ms). Accelerators on any entry bind a global shortcut. Real menubar: built. The top bar has room, so File / Edit / View / Go / Tools / Help sit at its left, shown only while plugins run (the default app has none). Built-in contents are small (File: the Add actions; Edit: Select all; View: panel toggles and List/Classic; Go: Library, Settings; Tools: the Tools actions; Help: empty), pluginmenubar-*entries follow after a separator.app-infofeatureextend.menubarshould be true while plugins run (lifecycle owner). The overflow “Plugins” menu was not needed. - Item pane sections. Frame (collapsible header, icon, header buttons) and body (a
PluginView) are entries of the pane’s virtual list, after the built-in sections, plus a tab in the side nav row.enabled-for,default-open,body-height, andrender-result.meta.enabledfordecides-enabledsections are honoured. Reader tabs:PluginSectionsList(Sections.tsx) takes aTabRefand an item key; the reader agent mounts it. Header button presses are forwarded topressViewButton(plugin, view, buttonId)of the ui agent’s module if it exports one. - Info rows. Three positions (start, after creators, end); value from
on-info-row-getthrough the cache, editable rows callon-info-row-set. - Columns. Id
plugin:<plugin id>:<data key>; offered in the column picker under “Plugin columns”; text, bar, rating and chips are shown as text (colour and text style are applied); one batchedon-column-valuesper screenful (up to 200 keys), cached, invalidated byinvalidate-columns, by the app’sitemsRev(any data change) and on plugin stop. Not sortable (see below). - Row styles. Background tint and text colour on plain cells of the Classic table.
- Toolbar. Buttons (toggle, badge, menu with
on-menu-showing, accelerator, conditions) and views inlibrary-toolbar(before Tools) andtop-bar(before the sync status). - Side panels, tabs, banners. Library side panels dock left or right of the library (fixed
default-width, a toggle button in the top bar); plugin tabs are chips after the reader chips and bodies in the window (store.setActiveTab("plugin:<plugin>:<tab>");on-tab-closingis honoured); banners stack above the top bar. - Shortcuts. App actions bound to the default accelerator, so Settings > Shortcuts lists and rebinds them; scope and
enabled-whenapply. - Preference panes. Each top-level pane is a Settings section (order 900+);
rowspanes use the host’s own controls bound to plugin prefs (toggle, text, secret text, number, choice, button, note, custom view),viewpanes andcustomrows arePluginViews; children draw under their parent;open-settingsgoes to the section. - Collection tree. Decorations (badge, icon, colour) after the collection name, one batch per screenful. Virtual collections (decided: in v1): rows at the end of the Collections group; choosing one replaces the list with
VirtualCollectionView, a plain list of the plugin’s items (title, type, date; click selects the item in the item pane), asked withon-virtual-collection-items(first 200 keys). Choosing any other row leaves it (“Back to library” too). - Selection and navigation.
get-context(items capped at 2000,item-countreal),list-selected-items,get-view,list-view-items(through the core, current query),select-items(store.revealItemper key),select-row,set-search,set-panel-visible,open-settings,open-item. - Drop targets.
window(App) andcollection-row(each collection row) for OS file drops; the first matching plugin target getson-drop;ignoredfalls through to the built-in import.
Stubbed or left
- Column sorting. The core sorts server-side; plugin columns have
sort: ""and ignore header clicks.sort-modeandsort-keyare not used. Needs either a core route that sorts by a key list or a client-side sort of the whole view. - Row styles only tint the row and colour plain cells (no leading icon, tooltip or style on the title cell); the card (List) view has no columns or row styles.
- Virtual collections appear at the top level only (
parentis ignored), without sorting, grouping, columns or paging beyond 200; the view cannot be left by clicking “Library” when that is already the view (use “Back to library”). - Drop targets
item-listanditem-pane,urls/text/itemspayloads, drag formats (on-drag-format): registry only. The grant id of a dropped file isdrop:<path>; whoever ownsfsmust resolve it (setDropGrantFactory). - Tab restore (
tab-spec.state,on-tab-restore),on-tab-closingfor closes the user does not start,on-menu-phase(the helper exists; the dropdown has no shown / hiding callbacks),tab-added/tab-closed/tab-movedevents (onlytab-selectedis sent). showinghooks run for the item menu, toolbar button menus and the menubar (on hover), not for collection or tab menus.entry-kindseparators are drawn;swatchis not. Entryiconandthemed-icon.dark: onlybuiltin(lucide) names are drawn;bundledandsvgfall back to the puzzle icon. Localized strings showfallback ?? iduntil thel10ninterface is wired.menu-targetstab,item-info-row,notes-add-item-note,notes-add-standalone-note,sidenav-locate: registrations are accepted and kept, nothing draws them yet (the note and info-row context menus have no host menu to join;tabneeds a tab context menu).selected-tab/list-tabs: one window (id 1); no tab strip order for built-in tabs.- Not covered by the headless script (covered by unit tests or by code only): side panels, plugin tabs, banners, virtual collections, decorations, drop targets, the
PluginViewbodies (the ui agent’s renderer: the slot shows a note untilwasmplugins/ui/index.tsexportsPluginView).
WIT changes
None. Findings that a later WIT / SDK change may want:
- A missing
bool(or other non-option) field in a record argument makes a QuickJS guest trap (“Unreachable code should not be executed”) instead of throwing a catchable error, so one forgottensortReversekills the plugin at startup. The JS SDK must fill defaults for every non-option field (the fixture spells them all out);phase2-core.mdsays “optional fields may be left out” — that holds foroption<T>, not forbool,listorenum. extend.register-pref-panerows are keyed by pref names that the host reads through theprefsinterface; this area needs the same store (see below).
Needs from other areas
- ui agent: export
PluginViewfromgpui-ui/src/wasmplugins/ui/index.tswith props{ plugin, view, surface, params?, width?, height?, visible?, onMeta? }(viewSlot.tsxhas the type), and optionallypressViewButton(plugin, view, buttonId)(a section header button press,ui-events.on-eventwithkind: press). Handlers: eitherplugin-host/src/imports/ui.zinc.ts, orwasmplugins/ui/handlers.tsexportingzincHandlers. - reader agent: handlers as
plugin-host/src/imports/reader.zinc.ts, orgpui-ui/src/reader/wasmHandlers.tsexportingzincHandlers; mountPluginSectionsList(wasmplugins/extend/Sections.tsx) andPluginSidePanels tabKind="reader"(Chrome.tsx) in reader tabs; callonPluginRegistrationsReset(fn)to drop reader registrations. The full path listindex.tstries isOPTIONAL_HANDLER_MODULES. - pkg / lifecycle: the installer writes the plugin layout of
plugin-host/src/manifest.tsunderpluginsDir()(ZN_PLUGINS_DIR);app-info.featuresextend.menubartrue while plugins run; user grants (grantsFor) beforeui.windows/ui.navigate/ui.drop/library.readbecome usable by default only if the manifest asks for them. - data / core: a
GET/PUT/DELETE /api/plugin-prefs/<plugin>/<key>route (apref-valueJSON) or a call tosetPrefsAdapterinextend/prefs.ts, so preference panes andprefs.getsee the same values;fsresolution ofdrop:<path>grants; a core route that lists items by key set would let virtual collections reuse the real list. - Coordinator:
plugin-host/src/imports/extend.zinc.tsimports fromgpui-ui/;bun checkinplugin-host/follows that import into gpui-ui (checked: clean, 81 files). Packaging:index.tsloads the optional handler modules with a variableimport()specifier, whichbun build --compilewill not follow; list them statically at packaging time. - Environment note: free space on C: dropped from 9382 to about 6700 MiB while this agent worked (other agents building); the last fixture build ran at 9382. After that only already-built output was reused.