Plugin API reference

Everything a Zumba plugin can declare, export and call, for API version 0.2. The interface is defined in zumba-plugin.wit; any language that compiles to a WebAssembly component can implement it. In Rust, build from the interface file with wit-bindgen. Inside the Zumba repository there's also a Rust SDK (zumba-plugin-sdk) with the same types under Rust names (run-command → run_command, insert-text → Action::InsertText), walked through in Creating a plugin; installing and the bundled plugins are covered in Plugins.

How a plugin runs

• A plugin is a WebAssembly component (wasm32-wasip2). Each plugin runs in its own zumba-plugin-host process, outside the editor, with no filesystem, network, environment or arguments of its own. It reaches the outside world only through the host functions, and only those its capabilities allow.
• activate runs once when the plugin loads: at startup, after installing, and after enabling it.
• One instance serves every call afterwards, so state kept in statics (e.g. thread_local!) survives between calls. Calls to one plugin never overlap.
• If a call traps (a panic, too much memory, out of fuel, over time), that call fails with the reason in the status bar and the plugin restarts with a fresh instance: its state is gone. activate is not called again; the contributions from the first activation stay.
• If the host process itself dies or stops answering, the editor stops it, shows the plugin as failed in Settings → Plugins, and starts it again the next time one of its commands runs.

Manifest: zumba-plugin.toml

id = "word-count"          # unique; also the install folder name
name = "Word Count"        # shown in Settings and the palette
version = "0.1.0"
api = "0.2"                # must equal the editor's API version
description = "Counts words in the selection or the active file."
capabilities = ["commands", "panels"]
wasm = "plugin.wasm"       # optional; the default

[limits]                   # optional; per call
fuel = 2000000000
memory_mb = 64
timeout_ms = 2000

Capabilities

The user sees this list before installing. Contributions and actions that need a capability the manifest doesn't have are dropped; host functions return Err("capability denied: <name>").

Limits

They apply to every call separately. Fuel is roughly one unit per WebAssembly instruction. Values above the maximum are lowered to it. Raise timeout_ms if you call fetch (it can take up to 8 s). The first call also waits while the host compiles your component, which doesn't count against timeout_ms.

Exports

A plugin exports four functions. With the Rust SDK, implement the Plugin trait (every method has a do-nothing default) and call export_plugin!(YourType).

Types

contributions

Returned by activate. Each list needs its capability; without it the list is dropped.

command

panel

theme

lsp-server

agent

An ACP agent (stdio, newline-delimited JSON-RPC) for the agent panel. Its id in the editor becomes plugin:<plugin id>/<agent id>.

context

Passed to run-command and panel-event: the editor's state at that moment.

action

What run-command and panel-event ask the editor to do, in order.

node

A panel is a flat column of nodes, top to bottom.

event

Keep what the user typed in your own state when you get change, and put it back as the input's value in render-panel, or the field resets when the panel redraws.

http-request / http-response

Host functions

Imported from zumba:plugin/host. In the Rust SDK they're plain functions: log, read_file, write_file, list_files, fetch.

Paths are always relative to the workspace. Absolute paths and .. are refused (path not allowed), and a symlink that leads outside the workspace is refused too (path escapes the workspace). Your plugin's stdout and stderr also end up in its log.

Errors come back as Err(String) with a message meant for people: pass it on in a notify or return it from run-command.

Versioning

The API version is major.minor of the WIT package (zumba:plugin@0.2.0 → "0.2"). The editor loads only plugins whose manifest api matches its own, so rebuild against the new SDK when the version changes.

Building a plugin from the interface file

You don't need the Zumba SDK: wit-bindgen and the interface file are enough. Download zumba-plugin.wit into a wit/ folder next to your Cargo.toml:

word-count/
  Cargo.toml
  zumba-plugin.toml
  wit/zumba-plugin.wit
  src/lib.rs

# Cargo.toml
[package]
name = "word-count"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
wit-bindgen = "0.63"

[profile.release]
opt-level = "s"
strip = true

// src/lib.rs
wit_bindgen::generate!({ world: "plugin", path: "wit" });

// The world already brings `Action`, `Context`, `Contributions`, `Event` and `Node` into scope.
use zumba::plugin::types::Command;

struct WordCount;

impl Guest for WordCount {
    fn activate() -> Contributions {
        Contributions {
            commands: vec![Command { id: "word-count.count".into(), title: "Word Count: Count Words".into(), keybinding: None }],
            themes: vec![],
            lsp_servers: vec![],
            agents: vec![],
            panels: vec![],
        }
    }

    fn run_command(id: String, ctx: Context) -> Result<Vec<Action>, String> {
        match id.as_str() {
            "word-count.count" => {
                let text = if ctx.selection.is_empty() { &ctx.text } else { &ctx.selection };
                Ok(vec![Action::Notify(format!("{} words", text.split_whitespace().count()))])
            }
            _ => Err(format!("unknown command {id}")),
        }
    }

    fn render_panel(_id: String) -> Vec<Node> {
        vec![]
    }

    fn panel_event(_id: String, _event: Event, _ctx: Context) -> Vec<Action> {
        vec![]
    }
}

export!(WordCount);

# zumba-plugin.toml
id = "word-count"
name = "Word Count"
version = "0.1.0"
api = "0.2"
description = "Counts words in the selection or the active file."
capabilities = ["commands"]

Build it and put the component next to the manifest:

rustup target add wasm32-wasip2
cargo build --release --target wasm32-wasip2
cp target/wasm32-wasip2/release/word_count.wasm plugin.wasm

Then Settings → Plugins → Install from folder, and run Word Count: Count Words from the palette. Host functions are in zumba::plugin::host (host::read_file("src/main.rs")).

Packaging

A plugin package is a folder (or git repository) with zumba-plugin.toml and the built component at its root. Users install it from Settings → Plugins with Install from folder or Install from git. Zumba never builds a plugin from source when installing, because a build would run code outside the sandbox: ship the built plugin.wasm.