Skip to content
ZincGitHubDownload

Rules for the WASM plugin API agents, phase 1 (2026-11-18)

View as Markdown

Goal

Zinc gets its own plugin system: WebAssembly components with WIT interfaces. A plugin written for it must be able to do everything a Zotero 7 plugin can do, including full UI customization. Phase 1 is DESIGN ONLY:

  1. Find every capability a Zotero plugin has in your area (from Zotero’s source, not from memory).
  2. Write the WIT interface that gives a Zinc WASM plugin the same capability.
  3. Write a parity table that maps each Zotero capability to your WIT, with a status.

Phase 2 (a later round, not now) builds the host. Do not write host code, TypeScript, Rust or tests in this phase.

Five agents, one worktree

All five agents work at the same time in C:\Users\abora\zotero-next\.claude\worktrees\wasm-plugins (branch claude/wasm-plugins, cut from main). Each agent owns files. Edit only your own files.

Area Owner files
lifecycle plugin-api/wit/types.wit, plugin-api/wit/world.wit, plugin-api/wit/lifecycle.wit, plugin-api/manifest.schema.json, docs/developer-guide/wasm-plugins/lifecycle.md, docs/developer-guide/wasm-plugins/README.md
library plugin-api/wit/library.wit, docs/developer-guide/wasm-plugins/library.md
extend plugin-api/wit/extend.wit, docs/developer-guide/wasm-plugins/extend.md
ui plugin-api/wit/ui.wit, plugin-api/ui-schema/ (new folder), docs/developer-guide/wasm-plugins/ui.md
reader plugin-api/wit/reader.wit, docs/developer-guide/wasm-plugins/reader.md
  • All WIT files are in one package: package zinc:plugin@0.1.0;. Each file holds one or more interface blocks.
  • Shared types (item key, library id, error, JSON string alias, icon reference, localized string) go in types.wit. Only lifecycle edits it. If you need a shared type, define it locally in your own interface first, and list it under “Needs from other areas” in your report. The coordinator merges duplicates after phase 1.
  • world.wit (owned by lifecycle) imports and exports the interfaces of all areas. Use these interface names so the world can reference them before your file is final: lifecycle, library, notifier, prefs, extend, ui, reader. You may add more interfaces in your own file; list their names in your report.
  • If you need a change in a file you do not own, do not make it. Write it under “Needs from other areas”.
  • Never run git commands that change state (commit, stash, checkout, reset, restore, clean, add, merge, rebase). Read-only git is fine. The coordinator commits.

Decisions already made (from the spike)

Read C:\Users\abora\zotero-next\.claude\worktrees\wasm-plugin-spike-b1f662\docs\developer-guide\wasm-plugins-spike.md and the spike’s WIT at ...\wasm-plugin-spike-b1f662\spikes\wasm-plugins\wit\plugin.wit. In short:

  • Plugins are WebAssembly components (the component model, WIT interfaces), run by Wasmtime (zhw).
  • All plugins run in one separate “plugin host” process (zhw), one instance per plugin. A hung plugin is stopped by Wasmtime’s epoch interruption and disabled alone; the process restarts only if it dies. So every host call crosses a process boundary: design for few, coarse calls (batch reads, return lists, no per-row callbacks in hot paths such as item tree cell rendering; prefer declarative data the host renders).
  • Host imports can be async: the host suspends the plugin while it waits for the answer.
  • Plugins get no WASI: no files, no network, no clock, no env except what Zinc’s own interfaces give. If Zotero gives a plugin a capability (HTTP, files, timers), design a Zinc interface for it, gated by a permission declared in the manifest.
  • Guests are written in Rust or JS (QuickJS). Keep the WIT easy to use from both: plain records, variants, lists, options, results; resource types only where a handle with a lifetime is really needed.
  • Plugin UI is declarative: the plugin returns a UI tree (data), the host renders it with Zinc’s own components and theme. The plugin never touches a DOM. Events come back to the plugin as calls with an id. This is how “full UI customization” is reached: through a rich enough component set and extension points, not raw DOM access.

Sources of truth

  • Zotero’s source (sparse, shallow, current main): C:\Users\abora\AppData\Local\Temp\zotero-src. Read-only. Add paths with git -C <that dir> sparse-checkout add --no-cone <path>. Key paths: chrome/content/zotero/xpcom/pluginAPI/, chrome/content/zotero/elements/, chrome/content/zotero/xpcom/reader.js, xpcom/notifier.js, xpcom/prefs.js, xpcom/plugins.js, xpcom/data/, xpcom/search.js, zoteroPane.js, tabs.js, contextPane.js, itemTree.jsx, collectionTree.jsx. Sparse-add more (for example chrome/content/zotero/xpcom/data, xpcom/translation) as you need.
  • Zotero 7 developer docs: https://www.zotero.org/support/dev/zotero_7_for_developers ; windingwind/zotero-plugin-toolkit and windingwind/zotero-types on GitHub (what real plugins use in practice).
  • Zinc’s Zotero-compat layer (a different, JS-sandbox approach; useful as a map of what Zinc already exposes and how): C:\Users\abora\zotero-next\.claude\worktrees\zotero-plugins\gpui-ui\src\plugins\ and its doc ...\zotero-plugins\docs\developer-guide\zotero-plugins.md. Read-only.
  • Zinc itself, in your worktree: gpui-ui/src/ (the UI: itempane/, table/, sidebar/, reader/ including reader/plugins.ts, settings/, shell/, ui/, theme.ts), core/ (the local server; core/schema.sql), and docs/developer-guide/http-api.md, architecture.md, database.md.

Checking your WIT

From the worktree root:

Terminal window
bunx @bytecodealliance/jco types plugin-api/wit --world-name plugin -o "$TEMP/zn-wit-check-<area>"

It parses the whole package, so another agent’s half-finished file can break it. If the error is in a file you do not own, check your own file alone: copy it with a minimal world into $TEMP/zn-wit-check-<area>-solo/ and run the same command there. Fix only errors in your own files.

Safety

  • Never open or write data/library.sqlite, C:\Users\abora\Zotero\*, or anything on ports 23119 / 23120.
  • Bun only: bun, bunx. No node, npm or npx. No cargo in this phase.
  • Disk C: is nearly full. Do not run bun install in the worktree. Write scratch output only under %TEMP%.
  • No pushes, no network posts. Reading web pages and downloading Zotero’s own source from github.com/zotero is fine.

Report

Write docs/developer-guide/wasm-plugins/<area>.md:

  1. Parity table. One row per Zotero API / element / event / option in your area, found in Zotero’s source. Columns: Zotero capability (with source file), Zinc WIT (interface.function or type), status covered / partial (say what is missing) / not planned (say why: what in Zinc’s design makes it impossible or unwise, and what a plugin should do instead).
  2. Design notes: the main choices in your WIT and why (process boundary, batching, permissions, Rust/JS ergonomics).
  3. Open questions for the user.
  4. Needs from other areas.

Your final message: three lines. Line 1: counts of covered / partial / not planned. Line 2: WIT check result. Line 3: the report path.