Writing an extension

An extension is a small Rust crate, compiled to a WebAssembly component and shipped beside a manifest.toml. It can give Lumi:

• Actions — commands a person binds to a shortcut, a leader menu step, a double-tap or an Fn combination, like any built-in action.
• Flow nodes — steps that appear in the Flow Editor's palette and run on the items that reach them.
• Settings — a form Lumi draws for it under Settings → Extensions.
• Windows — dialogs of its own, drawn from HTML files in the package.

It runs in Lumi's sandbox and reaches exactly what its manifest declares. That is enforced by Lumi on every call the extension makes, not by review: an extension that never declared network cannot reach the network whatever its code tries.

What you need

• A Rust toolchain with the WebAssembly component target:

  rustup target add wasm32-wasip2

• Lumi on the same Mac, to install and run what you build.

A first extension

cargo new --lib hello-lumi
cd hello-lumi

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

[dependencies]
# Until the crate is on crates.io, it is taken from the store's repository.
# The tag names the interface version, so an update to the SDK is a choice
# you make.
lumi-extension-api = { git = "https://github.com/thiennguyen93/lumi-store", tag = "api-v0.2.0" }
serde_json = "1"

use lumi_extension_api as lumi;

struct Hello;

impl lumi::Guest for Hello {
    fn run_command(name: String, _params: String) -> Result<String, String> {
        match name.as_str() {
            "greet" => {
                let found = lumi::selection()?;
                lumi::alert(&format!("You selected {} characters", found.text.chars().count()))?;
                Ok("greeted".to_string())
            }
            other => Err(format!("no {other} command")),
        }
    }

    fn run_node(name: String, _params: String, _items: String) -> Result<String, String> {
        Err(format!("no {name} node"))
    }

    fn run_ui(window: String, _request: String) -> Result<String, String> {
        Err(format!("no {window} window"))
    }

    fn on_lifecycle(_event: lumi::Lifecycle) -> Result<(), String> {
        Ok(())
    }
}

lumi::register!(Hello);

[extension]
id = "dev.you.hello"
name = "Hello"
version = "0.1.0"
description = "Counts what you selected."
author = "You"
capabilities = ["accessibility"]

[[command]]
name = "greet"
label = "Count the selection"

cargo build --release --target wasm32-wasip2

mkdir -p package
cp manifest.toml package/
cp target/wasm32-wasip2/release/hello_lumi.wasm package/extension.wasm
tar -czf dev.you.hello.tar.gz -C package .

How a run works

Every call into an extension — a command, a flow node, a request from one of its windows — is one run, and a run is bounded:

The first two stop the run where it stands: a run that asks for more memory, or is still going at fifteen seconds, is ended and the person is told the extension was stopped. Lumi itself carries on — that is the point of the sandbox.

The next two are refusals rather than stops. Past the 200th call, every call into Lumi answers an error instead of doing anything, and with ? that ends your run on the spot. A call refused for a missing capability still counts toward the 200. An answer over 4 MiB is replaced with an error saying how large it was.

The last one is not per run: a fifth run started while four of yours are still going is refused straight away rather than queued, with a sentence saying the extension is busy. A window that fires requests in a loop is the usual way to meet it — send the next one when the last has answered.

A component may also define at most 4 memories, 16 tables and 32 instances. Rust's wasm32-wasip2 toolchain builds one memory, two tables and three instances, so this only matters to a component built some other way.

A flow node's run is ended when the person presses Stop on the flow, not only the steps after it.

A run starts from nothing each time: there is no state carried between runs in memory. What must last goes in your settings, which Lumi stores for you.

Where next