SDK reference

lumi-extension-api is the crate your extension depends on. Import it under a short name and everything below is one path away:

use lumi_extension_api as lumi;

What each call costs

Every function below exists whether or not your manifest declares what it needs. An undeclared one is refused when it is called, with an error that names the capability — so the person who sees it is you, with the manifest open.

Every call into Lumi except about and license spends from one allowance of 200 per run, so a loop of alerts runs dry long before it can flood the screen. The call is spent before its capability is checked, so a refused call counts too. Past the allowance every call answers an error — and settings(), which has no error to give, answers an empty object, so read your settings early in a run rather than after a long loop.

Your extension

Guest and register!

The trait you implement and the macro that wires it up. Call register! once, at the crate root, on the type that implements Guest.

impl lumi::Guest for MyExtension {
    fn run_command(name: String, params: String) -> Result<String, String>;
    fn run_node(name: String, params: String, items: String) -> Result<String, String>;
    fn run_ui(window: String, request: String) -> Result<String, String>;
    fn on_lifecycle(event: lumi::Lifecycle) -> Result<(), String>;
    fn on_event(name: String, payload: String) -> Result<(), String>;
}

lumi::register!(MyExtension);

Answer the names you do not know with an error rather than a panic. A panic is reported to the person as the extension having crashed on an error of its own, with no more detail than that; the backtrace goes to Lumi's log. An error's text is cut to 64 KiB.

on_lifecycle(event)

pub enum Lifecycle {
    Installed,
    Updated(String), // the version that was replaced
    Uninstalling,
}

Three moments in your extension's life, each told to it once:

Nothing to do is the ordinary answer:

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

The rules, all of which follow from nobody having pressed anything:

• Only while switched on. A switched-off extension is not told it was updated or uninstalled — off means none of its code runs.
• Nobody sees the answer. An error is written to Lumi's log, never shown.
• It cannot stop anything. An Uninstalling that fails or runs out of time is logged, and the uninstall goes ahead.
• Installed and Updated run after the install has finished, on their own, with the same allowance and deadline as a command.
• It takes one of your four runs at once. A hook that arrives while four runs of yours are going is skipped and logged — Uninstalling included.
• Uninstalling is short and has no windows. The person is waiting on the Uninstall button, so it has five seconds, and your ui/ files are about to be deleted, so open_window is refused. Open a web page with open_url instead — which needs applications, plus network for a web address.

fn on_lifecycle(event: lumi::Lifecycle) -> Result<(), String> {
    match event {
        lumi::Lifecycle::Installed => lumi::open_window("welcome"),
        lumi::Lifecycle::Updated(from) => lumi::alert(&format!("Updated from {from}")),
        lumi::Lifecycle::Uninstalling => lumi::open_url("https://example.dev/why-uninstall"),
    }
}

A Welcome window is an ordinary [[window]]: declare it, and open it from Installed.

on_event(name, payload)

Something that happened outside your extension, which it asked to hear. The payload is a JSON object with a "v" field for its own version; a new kind of event is a new name, so this method is the last one the trait gains for it. An extension that asks to hear nothing is never called, and answers Ok(()):

fn on_event(_name: String, _payload: String) -> Result<(), String> {
    Ok(())
}

The events Lumi sends today:

It runs under on_lifecycle's rules — only while switched on, its answer only written to Lumi's log, one of your four runs at once — and two more that follow from nobody having pressed anything: open_window cannot open a panel from here, and paste is refused.

selection and keyboard-selection are the exception, because the person selecting is the moment: its run may open_window one panel declared position = "selection", once, within two seconds of the selection and only while it is still the person's latest. The panel opens beside that selection without the keyboard, whatever its focus says, and goes at their next click, key or scroll. The run may set that panel's size, material, theme and anchor and post to it; paste, replace_selection, replace_selection_and_select, set_pinned and opening Settings are still refused.

fn on_event(name: String, payload: String) -> Result<(), String> {
    if name == "selection" {
        let said: serde_json::Value = serde_json::from_str(&payload).map_err(|e| e.to_string())?;
        lumi::post("bar", &said.to_string())?;
        return lumi::open_window("bar");
    }
    Ok(())
}

settings() and setting(name)

pub fn settings() -> serde_json::Value
pub fn setting(name: &str) -> Option<String>

Your [[settings]] values as the person saved them, one key per field, with defaults filled in for anything untouched. A field declared scope = "profile" holds the live profile's value. setting is the shortcut for one string field.

Settings are fixed for the length of a run: a save in Lumi while your code is running reaches the next run. Your own set_setting is the exception — the rest of the run reads what it saved.

set_setting(name, value)

pub fn set_setting(name: &str, value: &str) -> Result<(), String>

Saves one setting, as a save from your Settings page does — for a menu row that switches it without the person opening the page:

lumi::set_setting("method", "vni")?;

The value is text, as every setting is ("true" and "false" for a bool). It is held to the field's own rules — a value they refuse is refused with the sentence the page would show — filed under the live profile for a field declared scope = "profile", and told to your open pages. Only for something the person did: a command, a menu bar row or one of your windows. Needs Lumi 1.61.0.

open_window(name)

pub fn open_window(name: &str) -> Result<(), String>

Opens — or brings forward — one of the windows your manifest declares. A name the manifest does not declare is refused. A window with copies is opened copy by copy, open_window("card-3"), in this call and every other that names a window. One already up is focused, never closed, your command's own press included; for a key that also puts it away, see window_state below. See Windows.

It is refused from run_node too: a flow runs in the background, and a dialog out of a flow nobody just pressed is not something a flow may do yet. And it is refused from Uninstalling, since your ui/ files are about to go.

pub fn open_window_on(name: &str, beside: &str) -> Result<(), String>

open_window_on is open_window on the display your window beside stands on now. A window that opens where it was left (remember-frame) opens at that place carried to this display — as far from the same edges, the nearer of left and right and of top and bottom, held inside — and one that opens at a corner or in the middle opens at that one of this display; one that opens at the pointer or a selection opens there, as ever. One already up is focused where it stands; with beside not on screen, or on the same display, it is open_window. It is for a smaller window standing in for a bigger one, opened as the bigger one is put away — a browser minimized to a pill — which should appear on the display the person was looking at. Open it before you hide_window the bigger one, while that one is still on screen to be measured. Both are names your manifest declares (Lumi 1.65.0).

pub fn open_window_at(name: &str, beside: &str, corner: &str) -> Result<(), String>

open_window_at is open_window at a corner of your window beside as it stands now: the panel opens with its corner on that window's same corner — "top-left", "top-right", "bottom-left" or "bottom-right", or "center" for its middle on that one's middle — held inside the display beside is on, against its edge where it would run past it. A window hide_window took away counts as standing where it was, since that is where show_window puts it back. It is for a smaller window standing in for a bigger one, which should appear where that one was — a pill at the foot of the browser minimized to it:

lumi::open_window_at("pill", "browser", "bottom-right")?;
lumi::hide_window("browser")?;

A panel only — macOS places a window as it opens — and not one Lumi places beside the selection, the menu bar item or another window. One already up is focused where it stands; with beside neither on screen nor stepped aside it is open_window. Both are names your manifest declares (Lumi 1.75.0).

open_window_after(name, after_ms)

pub fn open_window_after(name: &str, after_ms: u32) -> Result<(), String>

open_window, after_ms milliseconds from now — from the run of a selection or keyboard-selection event only, as its one opening of the panel beside that selection. It answers at once; the panel opens when the time is up, unless the person has pressed, typed or scrolled since — then it never opens — or the selection is two seconds old. At most 1000; 0 is open_window. Refused from any other run.

For a panel that waits for the person to finish: a double-click may yet become a triple-click, and the selection event's clickInterval says for how long. Waited out, the double-click's panel opens; cut short by the third click, it never shows, and the triple-click's own run opens one.