pub enum ScriptCommand {
Show 59 variants
Print(String),
AddClicks(i32),
SetString {
key: String,
value: String,
},
SetText {
target_id: String,
text: String,
},
SetSrc {
target_id: String,
path: String,
},
SetTimer {
name: String,
millis: u64,
repeat: bool,
},
CancelTimer {
name: String,
},
Fetch {
url: String,
tag: String,
},
Http {
method: String,
url: String,
headers: Vec<(String, String)>,
body: Option<String>,
timeout_ms: Option<u64>,
credentials: Credentials,
tag: String,
},
SetResponseStatus {
status: u16,
},
SetResponseHeader {
name: String,
value: String,
},
Redirect {
location: String,
},
SetSignal {
name: String,
value: String,
},
SetProperty {
key: PropertyKey,
value: PropertyValue,
},
SetArray {
name: String,
items: Vec<HashMap<String, String>>,
},
Notify {
title: String,
body: String,
},
NotifyEx {
id: String,
title: String,
body: String,
options: String,
actions: String,
},
ClipboardWrite {
text: String,
},
ClipboardRead {
tag: String,
},
OpenUrl {
url: String,
},
OpenPath {
path: String,
},
RevealPath {
path: String,
},
KeepAwake {
name: String,
reason: String,
},
AllowSleep {
name: String,
},
CopyImageToClipboard {
path: String,
},
SaveClipboardImage {
path: String,
},
RegisterTrayIcon {
id: String,
icon_path: String,
tooltip: Option<String>,
menu: String,
template: bool,
},
UnregisterTrayIcon {
id: String,
},
SetClasses {
target_id: String,
classes: String,
},
SetColorScheme {
name: String,
},
OpenFileDialog {
kind: FileDialogKind,
tag: String,
filters: Vec<(String, Vec<String>)>,
default_name: Option<String>,
},
RegisterHotkey {
name: String,
accelerator: String,
},
UnregisterHotkey {
name: String,
},
SetAttr {
node: u64,
name: String,
value: String,
},
RemoveAttr {
node: u64,
name: String,
},
SetNodeText {
node: u64,
text: String,
},
ClassAdd {
node: u64,
class: String,
},
ClassRemove {
node: u64,
class: String,
},
ClassToggle {
node: u64,
class: String,
},
SetStyleProp {
node: u64,
name: String,
value: String,
},
RemoveStyleProp {
node: u64,
name: String,
},
Spawn {
tag: String,
reserved: u64,
},
Insert {
parent: u64,
node: u64,
before: u64,
},
ReplaceWith {
old: u64,
new: u64,
},
RemoveNode {
node: u64,
},
CloneNode {
source: u64,
reserved: u64,
},
SetInnerMarkup {
node: u64,
markup: String,
},
SpawnFragment {
key: String,
args: Vec<(String, String)>,
children: Vec<(String, u64)>,
reserved: u64,
},
BindEvent {
node: u64,
event_type: String,
capture: bool,
token: u64,
},
UnbindEvent {
token: u64,
},
WindowSetTitle {
title: String,
},
WindowSetSize {
width: f32,
height: f32,
},
AddRecentFile {
path: String,
label: String,
},
ListRecentFiles {
tag: String,
},
ClearRecentFiles,
SetAutostart {
on: bool,
},
QueryAutostart {
tag: String,
},
RequestFrame,
SetLocale {
tag: String,
},
}Expand description
One side-effect a script wants to apply to the app this tick.
V1 is intentionally small: just enough to demo end-to-end. Future
variants will cover SetComponent, SpawnEntity, DespawnEntity,
RegisterTimer, etc., keyed by an entity id type that’s stable across
the script ABI boundary.
Variants are append-only; see SCRIPT_WIRE_VERSION.
Variants§
Print(String)
Append a line to the app’s diagnostic output.
AddClicks(i32)
Add n to the app’s click counter (consumed in app-defined ways -
the host doesn’t know about Clicks, it just emits this token).
SetString
Free-form key/value the app can interpret. Strings only for now.
SetText
Replace the TextContent of the entity whose LumenId matches
target_id (set in markup via id="...").
SetSrc
Replace the asset path on an <image> entity. The runtime
strips the old LoadedImage / LoadedSvg / ImageLoadFailed
component, installs a fresh ImageSource, and the asset
pipeline re-decodes on the next tick. Used by scripts to swap
icons in response to runtime state (e.g. weather code ->
icons/sun.png).
Fields
SetTimer
Schedule a named timer. The runtime calls the script’s
on_timer(name) handler when it fires.
Fields
CancelTimer
Cancel a pending or repeating timer by name. No-op if absent.
Fetch
Issue an HTTP GET. The runtime spawns the request off-thread and
fires on_fetch(tag, body) when the response arrives.
This is the simple sugar; Self::Http is the general form and
shares the same off-thread transport and completion channel.
Http
Issue a general HTTP request. The runtime performs it off-thread
(one worker per request) and, once the reply is marshalled back
onto the ECS/UI thread, fires on_http(tag, response) where
response is a map #{ ok, status, headers, body, error }.
Request/reply shape is modeled on Qt’s
QNetworkRequest/QNetworkReply (method + url + headers + body
in; status + headers + body + error out); the worker->UI-thread
marshalling before any signal is touched mirrors Slint’s
invoke_from_event_loop discipline. web-fetch-like: a 4xx /
5xx is a completed reply the script can branch on (via
response.ok / response.status), not an error.
Fields
timeout_ms: Option<u64>Optional per-request timeout in milliseconds (None = no
client-imposed deadline).
credentials: CredentialsWhether the request carries the page’s credentials. Only a browser transport acts on it.
SetResponseStatus
Set the status code of the response the document is being rendered for.
A page rendered per request answers with more than markup: a page for a record nobody has says so with a 404, and a form that rejects what it was sent says so with a 422. Nothing outside a server render reads this.
SetResponseHeader
Set a header on the response the document is being rendered for.
Setting the same name twice replaces the value. The renderer decides what a script may set: a name that would rewrite how the body is framed, or one carrying a line break, is refused and reported.
Redirect
Answer the request with a redirect instead of a document.
The render stops where it is: whatever the app had rendered is dropped, because a visitor being sent elsewhere never sees it.
SetSignal
Write value into the named slot of the reactive [Signals]
map. Any entity carrying a Bind* component pointing at this name
re-renders next tick. Strings only at this layer; numeric / bool
signals are stringified before storage.
SetProperty
Typed write into lumen_core::property_store::PropertyStore.
Unlike Self::SetSignal, this variant carries a typed
[PropertyValue] (i64 / f64 / bool / color / vec2 / arc-str /
custom) and lands directly in the typed cell - no stringify, no
[Signals] mirror. Used by typed Rhai builtins
(signal_set_int / _float / _bool / _color) and the C
FFI typed setters when they want to enqueue through the script
command bus instead of the cross-thread push_external_property
channel. The Rhai host today prefers the channel path
(immediate, no tick round-trip); this variant is the
equivalent for hosts that want to defer until the next
apply_script_commands drain (gives the system one
frame to coalesce typed writes).
Fields
key: PropertyKeyProperty key (global or entity-scoped).
value: PropertyValueNew typed value. A
Custom
payload cannot be encoded; see crate::wire::property_value.
SetArray
Replace the named entry in the reactive ArraySignals map with a
fresh ordered vector of records. Each record’s field values are
pre-stringified at the script boundary so the receiving system
doesn’t need to deserialize per-frame. Any <for each="<name>">
reconciler then spawns / despawns child markup to match.
Fields
Notify
Show a native desktop notification. Cross-platform via
notify-rust (libnotify on Linux, NSUserNotification on macOS,
Toast on Windows).
NotifyEx
Show a native desktop notification carrying an icon, an urgency,
and action buttons. Pressing a button fires
on_notification_action(id, action_id).
Fields
ClipboardWrite
Put text on the system clipboard.
ClipboardRead
Request the system clipboard’s text. The runtime reads it and
fires on_clipboard(tag, text).
OpenUrl
Open a URL with the user’s default handler (browser, mail client).
OpenPath
Open a filesystem path with the platform’s default application. Relative paths resolve against the app directory.
RevealPath
Show a file in the platform’s file manager. Relative paths resolve against the app directory.
KeepAwake
Hold off the screensaver and system sleep under name until a
matching ScriptCommand::AllowSleep. Repeating a live name
replaces its request rather than stacking a second one.
Fields
AllowSleep
Release the sleep inhibit registered under name. No-op when the
name is unknown.
CopyImageToClipboard
Reads the PNG at path and writes its pixels to the system clipboard.
path is resolved relative to the app directory by the runtime handler.
SaveClipboardImage
Pulls the current clipboard image (when present) and writes it as PNG to path. Failures log to stderr.
RegisterTrayIcon
Registers or replaces a system tray icon on macOS, Windows, and
Linux. icon_path resolves relative to the app dir.
Fields
Context-menu items as "id:Label|-|id2:Label2", where - is a
separator. Picking one fires on_menu(id). Empty means no menu.
UnregisterTrayIcon
Drops a previously-registered tray icon by id.
SetClasses
Replace the LumenClasses of the entity whose LumenId
matches target_id (or the root entity when target_id is
"<root>"). Triggers a runtime CSS re-apply (K9) - the
downstream system detects Changed<LumenClasses> on the root
and re-spawns the tree with the new class set.
Fields
SetColorScheme
Switch the app’s color scheme. The runtime parses name into a
lumen_core::components::ColorScheme and hands it to the style
manager, which re-resolves every theme token. An unknown name is
logged and ignored.
Fields
OpenFileDialog
Open a native file dialog (open, multi-open, save, or folder
pick). The runtime serves the dialog on the main thread via
rfd, then fires on_file_picked(tag, path) /
on_files_picked(tag, paths_joined_by_pipe) /
on_folder_picked(tag, path) (or the per-id on() route)
once the user closes it.
Fields
kind: FileDialogKindWhat kind of dialog to show.
RegisterHotkey
Register an OS-level global hotkey. Accelerator strings follow
the keyboard-types/Electron convention ("CommandOrControl+S",
"Alt+Space", "F11"). on_hotkey(name) fires every time the
OS dispatches the chord regardless of window focus.
Fields
UnregisterHotkey
Unregister a previously-registered hotkey by name. No-op if the name is unknown.
SetAttr
Set an attribute on a node addressed by packed handle. KNOWN attrs
(id, class, src, text, disabled, …) route to their typed
component; everything else lands in the generic
lumen_core::components::LumenAttributes map.
Fields
RemoveAttr
Remove an attribute from a node addressed by packed handle.
SetNodeText
Replace a node’s text content (node.set_text).
ClassAdd
Add one class to a node’s class list (incremental, idempotent).
ClassRemove
Remove one class from a node’s class list.
ClassToggle
Toggle one class on a node’s class list.
SetStyleProp
Set an inline style property (element.style), the highest cascade
tier the runtime re-apply reads.
RemoveStyleProp
Remove an inline style property.
Spawn
Create a fresh detached element with markup tag tag. reserved
is the token the host minted synchronously so the same tick’s
chained mutations address the node; the applier maps it onto the
entity it spawns.
Fields
reserved: u64Reserved spawn token (see
lumen_core::node::reserve_node_token).
Insert
Attach node under parent. before (when non-zero) is a
reference child to insert ahead of (insert_before); zero appends
at the end (append / set_parent / move_to / reparent all
route here).
Fields
ReplaceWith
Replace old with new in old’s parent, then despawn old’s
subtree (replaceWith).
Fields
RemoveNode
Detach and despawn a node and its whole subtree (node.remove).
CloneNode
Deep-clone source’s subtree into a fresh detached node. reserved
is the token the host minted for the clone root.
Fields
SetInnerMarkup
Replace node’s children with the subtree parsed from markup
(element.innerHTML = ...). The markup is parsed by the injected
front-end and spawned through the same path the <for> reconciler
uses, so layout / style / paint stay consistent.
Guarded: parsing needs the injected markup front-end
(SourceParser is a runtime concept), which is present on
the dev / from-source run path but absent in the precompiled-artifact
path; there it is a no-op. Do not feed untrusted content; this
injects live markup (XSS-adjacent).
Fields
SpawnFragment
Instantiate the compiled fragment key into a fresh detached
subtree. reserved is the token the host minted for the instance
root, so the same tick’s Insert attaches it.
args binds the fragment’s parameters, in use-site order; a
parameter absent here takes its declared default, and one with
neither resolves empty. Arguments substitute once, at instantiation:
a value that changes while the app runs belongs in a bind-*
attribute inside the fragment body.
children maps a slot name to a node that already exists, which the
applier moves into that slot. Passing live handles is what keeps the
applier off the script VM: a caller composing nested fragments
instantiates the inner ones first and passes their roots in.
Fields
BindEvent
Bind an event handler to a node. token is the off token the host
minted synchronously; the host holds the handler closure keyed by
the same token, and the applier records (node, event_type, capture)
in the host-neutral binding registry the dispatcher consults.
handler_ref is the token (a host-neutral reference), consistent
with the reserved-token model the structural commands use.
Fields
UnbindEvent
Unbind a previously-bound event handler by its off token
(removeEventListener). No-op if the token is unknown.
WindowSetTitle
Set the OS window title (window.set_title).
WindowSetSize
Resize the OS window to width x height logical pixels
(window.set_size).
AddRecentFile
Record path as recently opened (move-to-front, capped list).
Relative paths resolve against the app directory.
Fields
ListRecentFiles
Request the recent-files list. The runtime reads it and fires
on_recent_files(tag, paths), most recent first, paths joined by
|.
ClearRecentFiles
Remove every entry from the recent-files list.
SetAutostart
Enable or disable launching this app at login.
QueryAutostart
Request the current autostart state. The runtime reads it and fires
on_autostart_enabled(tag) or on_autostart_disabled(tag).
RequestFrame
Ask for one on_frame(dt) call on the next tick.
The browser’s requestAnimationFrame: one request buys one callback,
and a callback that wants another asks again. An app that stops asking
stops being ticked for it, so an animation costs frames only while it
is running.
SetLocale
Switch the app to another locale. The catalogue, the locale-aware formatters and the base writing direction all move together, and every element the markup marked is rebuilt from the new catalogue on the tick the switch lands.
A locale the app has no catalogue for is not an error: every message
falls back to the text the author wrote, which is what naming such a
locale in lumen.toml already does. A tag that is not BCP-47 is
logged and ignored.
Implementations§
Source§impl ScriptCommand
impl ScriptCommand
Sourcepub fn mutates_dom(&self) -> bool
pub fn mutates_dom(&self) -> bool
Whether the command changes the tree rather than the state behind it, which is what the DOM applier answers for.
Sourcepub fn builds_nodes(&self) -> bool
pub fn builds_nodes(&self) -> bool
Whether the command adds, removes or moves a node, rather than writing onto one the markup already declares.
A node a script builds is built by running the script, so anything producing a document without running one for the full life of the app has to know that these went by: a page rendered on a server carries the markup, the state and what the run wrote onto the nodes it found, and the nodes a script went on to create arrive when the browser runs it.
Trait Implementations§
Source§impl Clone for ScriptCommand
impl Clone for ScriptCommand
Source§fn clone(&self) -> ScriptCommand
fn clone(&self) -> ScriptCommand
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more