Phase 2, sdk agent: guest SDKs and sample plugins
Status 2026-11-18. Not finished: the Rust SDK and the two Rust samples have never been compiled, and samples/test.ts has never run. See “Result” for why.
What was built
| Path | What it is |
|---|---|
plugin-api/sdk/rust/ (zinc-plugin) |
Rust SDK. src/lib.rs generates the bindings for the full plugin world with wit-bindgen (pub_export_macro, default_bindings_module), re-exports imports as host::* and exported types as callbacks::*. src/plugin.rs: trait Plugin (all 48 callbacks with default no-op bodies; two name clashes renamed: on_host_event, on_ui_event, build_reader_menu, on_reader_menu_command), Glue<P> implementing the eight Guest traits, macro export_plugin!(MyType). Builders: text (localized strings, IntoText), err, menu (entries, conditions), reg (column, section, setting rows, pref pane, reader listeners), ui (nested El tree flattened to the typed node list, dialogs, toasts, form values), json (serde_json, escape_html), log. |
plugin-api/sdk/js/ (@zinc/plugin-sdk) |
JS SDK. scripts/gen-types.ts runs jco types and writes types/ (per-interface .d.ts, ambient.d.ts for import x from "zinc:plugin/x@0.1.0", exports.d.ts) and src/generated/exports.ts (the 48 export functions with return types). All generated and git-ignored. src/plugin.ts: definePlugin (defaults for every export), fail. src/ui.ts: nested-JSON builders, render, toTree (JSON to the typed flat tree for dialogs), dialogSpec, toastSpec, fieldValue. src/ext.ts: menu, column, section, settings, reader listener helpers. scripts/build.ts: bundles the SDK into the entry, then calls plugin-host/scripts/build-plugin.ts. template/: starting point. |
plugin-api/samples/{word-count,quick-tags,highlight-export} |
The three samples, each with manifest.json, source, README.md. |
plugin-api/samples/test.ts, support/host-entry.ts |
The test (below). |
docs/developer-guide/wasm-plugins/writing-a-plugin.md |
The author guide. |
How the “about 40 stubs” problem is solved: Plugin is one trait whose methods all have defaults; Glue<P> implements every generated Guest trait by calling P, and export_plugin! exports Glue<P> with with_types_in. JS: definePlugin builds the full export object from the generated function list, so a missing function is a no-op, an empty list, or unavailable, never a trap.
How to run
bun plugin-api/sdk/js/scripts/gen-types.ts # JS types from the WITbun check # in plugin-api/sdk/jsbun plugin-api/samples/test.ts [--only name] [--keep] # builds, loads and checks the three samples (needs > 9 GiB free on %TEMP%'s drive)Result
- Verified:
gen-types.ts(37.d.tsfiles, 28 imports, 8 exports, 48 export functions);bun checkinsdk/jsclean; the JS samplequick-tagsbuilds throughsdk/js/scripts/build.tsandbuild-plugin.tsagainst the fullpluginworld (43 s, 5.6 MB component, 313 async imports, 48 async exports), so the QuickJS guest with SDK bundling anddefinePlugincomponentizes. - Not verified: everything Rust, and every test run. Two attempts to compile the SDK (
cargo check --target wasm32-wasip2; then a probe crate with onlygenerate!forplugin-minimal) did not finish in 20 and 5 minutes;rustcgrew past 7 GB resident and the free space onC:fell from 11 GB to 6.2 GB (page file and other agents’ builds), below the 9216 MiB floor of RULES-phase2.md. I killed the compiles and stopped building.test.tsalso refuses to run below that floor. samples/test.tsis written but has not been executed. It builds the three samples, loads each through the supervisor with stubwhere: "zinc"handlers and a host entry that switches off the host process’s own handler discovery (so the other agents’ real handlers cannot interfere), callsstartup, then the main exports, and asserts on what was registered and called (about 75 checks: word-count column, section, pref pane, pref change; quick-tags menu, dialog form,library.applyadd-tags, toast, cancel, truncated selection; highlight-export two reader listeners, note HTML, escaping, ordering, filters).
To finish: free disk, then bun plugin-api/samples/test.ts, and fix the compile errors in sdk/rust (the trait and builders were written from the WIT by hand, so type-name mistakes are likely; the compiler will list them).
Likely compile problem to look at first
The generated bindings for the full world are huge (about 400 imported functions with deep records: ui.style has 50 fields, node-kind 40 cases). If the compile stays that slow, options: (1) generate bindings only for the imports plugins use, with wit-bindgen’s with/skip or a purpose-built smaller world (the world file is not mine: see below); (2) split ui and reader out of the SDK behind cargo features, each using its own world; (3) opt-level is irrelevant for check, so this is rustc front-end cost: try RUSTFLAGS=-Zthreads on nightly, or codegen-units/lto only affect later stages.
WIT rows now implemented
None: the SDKs and samples are guests. They exercise (once run) extend.register-menu, register-column, register-section, register-pref-pane, invalidate-columns, prefs.observe, prefs.get, library.apply, library.get-summaries, fulltext.get-content, annotations.list-annotations, reader.register-listener, ui.run-dialog, ui.show-toast, log.write, and the callbacks extend-handlers.on-menu-command / on-column-values, ui-events.mount / on-event, reader-events.on-menu-command, events.on-pref-changed, via stubs.
Stubbed or left
- Rust builders cover the common nodes (box, card, section, text, button, text input, checkbox, select, form, callout, badge, progress); other node kinds: use
El::new(NodeKind::...). No table or list builders.regcovers column, section, settings, reader listeners; other registrations: fill the WIT records by hand. - JS
toTreesupports the same common nodes; anything else throws a clear error (useui.renderJSON for views). - No Fluent file loading helper;
text::l10nonly builds the reference. - Samples use
pluginworld (notplugin-minimal) because they call library, reader and annotations.
WIT changes
None made. Suggested (not made):
dialog-spec.content,window-spec.contentare typedtree, while views can return the nested JSON. JS guests have to flatten the tree themselves (sdk/js/src/ui.tstoTree), which duplicates the host’s JSON-to-flat conversion. Suggest acontent-update-like variant (or an extracontent-json: option<json>) on those two records.- No
Defaultfor records in Rust.style,node-props,column-registrationand others have 20 to 50 fields; the SDK writes them out by hand (ui::style(),reg::column). WIT has no default values; nothing to change, but any new field in those records breaks the SDK compile until updated (the compile error says where). - Reader toolbar
on-menu-commandreceives the entry id ascommandis assumed by the highlight-export sample; reader.md should say so forslot(toolbar)listeners with astatic-menu. - The
worlddoc says a plugin must export every function; with thepluginworld that is what makes the SDK necessary. A smaller world per extension point family (for exampleplugin-ui,plugin-reader) would let a plugin export onlylifecycleand the callbacks it uses, and would also shrink the generated Rust bindings.
Needs from other areas
- core / host: an option on
createPluginSupervisor(orhost-main.ts) to skipdiscoverHandlers("host"), so tests with stub handlers need no source rewriting (samples/support/host-entry.tspatches that one call at load time and fails loudly if the line changes). - core:
build-plugin.tsfor Rust usescargo metadatapackages[0]; fine for the samples (each is its own workspace root). - Whoever owns the installer: the layout and an install command;
writing-a-plugin.mdsays “no installer yet”.