lumen_script/

lib.rs

//! Scripting backend trait (v2) + the `ScriptCommand` enum scripts emit.
//!
//! `lumen-core` does not depend on this crate. Scripts run inside
//! host-generic systems provided by `lumen-script`; those systems
//! drain the [`ScriptCommand`]s the host produced this tick and forward
//! them onto the ECS message bus for the embedder's applier.
//!
//! Concrete implementations live in runtime modules (`lumen-candela` and the
//! other hosts under `std/`). Each provides a [`ScriptHost`] that runs
//! whatever language it speaks, exposing the host-neutral registries (command
//! sink, signal mirror, per-id handlers, derivations) the generic runtime
//! drives, and registers its language through [`language::ScriptLanguage`].

#![forbid(unsafe_code)]
#![warn(missing_docs)]

/// Binding a browser add-on's described functions into the hosts, on every
/// target.
pub mod addon;
pub mod builtins;

/// The applier behind the `clipboard_write` and `clipboard_read` builtins,
/// running on whichever clipboard backend the app was assembled with.
pub mod clipboard;

/// Host-neutral read side of the dynamic DOM API: `query` / `get_by_id` /
/// traversal over the per-tick [`lumen_core::node::DomIndex`] snapshot.
pub mod node_query;

/// Host-neutral event object, binding registry, and propagation driver
/// (phase 4): `n.on(type, handler)` / `off()`, the current-event cell, and
/// the capture -> target -> bubble dispatch.
pub mod event;

/// Host-neutral low-level introspection read surface (phase 5): post-layout
/// geometry, full computed style + provenance, typed component reads, tree
/// serialization, and global runtime state.
pub mod introspect;

/// Runtime event dispatch (phase 4): input messages -> DOM events ->
/// propagation, one pass per event over every installed host. See
/// [`dom_events::deliver_input_events`].
pub mod dom_events;

/// Script languages as host modules register them, and the table that
/// reaches an installed host. See [`language::ScriptLanguage`].
pub mod language;

/// Script-facing drag-and-drop event dispatchers (`on_drop` /
/// `on_drag_start`). See the module docs.
pub mod dnd;

/// Builtins whose subsystem the running engine was linked without, and the
/// once-per-builtin warning a call to one of them prints.
pub mod unlinked;

/// The HTTP seam behind `fetch()` / `http()`: the
/// [`HttpClient`](http::HttpClient) trait and its request and response types,
/// plus the [`HttpDispatch`](http::HttpDispatch) trait that decides who runs a
/// request. `lumen-http-ureq` is the client Lumen ships.
pub mod http;

/// Host-generic ECS driver: dispatchers, derivation fixed-point, mirror
/// sync, timers, HTTP fetch, and [`runtime::ScriptPlugin`]. Formerly the
/// `lumen-script-runtime` crate; folded in with its flat surface
/// re-exported at the crate root for source compatibility.
pub mod runtime;

/// The host-neutral native-function description ([`ScriptFn`]) and the
/// app-wide channel plugins register them through.
pub mod script_fn;

/// The builtin surface every host shares, described once as [`ScriptFn`]s.
pub mod builtin_fns;

/// The `parse_json` and `parse_markdown` walks behind two of those builtins,
/// each gated by its own Cargo feature. See the module docs.
pub mod text_parse;

/// The encoded form of the script surface: the version the shapes below are
/// pinned at, and the adapters for the two property-store types
/// [`ScriptCommand::SetProperty`] carries.
pub mod wire;

use std::collections::HashSet;

use lumen_core::warn_line;
use serde::{Deserialize, Serialize};
use thiserror::Error;

use crate::runtime::prefix;

pub use builtin_fns::{builtin_script_fns, parse_dialog_filter_spec};
pub use builtins::{BuiltinFn, BuiltinParam};
pub use dnd::{dispatch_drag_start_to_script, dispatch_drops_to_script};
pub use dom_events::{
    EventHosts, PendingDomEvents, deliver_input_events, deliver_state_events,
    queue_pointer_and_key_events, queue_state_events, register_dom_event_messages,
    register_event_host,
};
pub use http::{
    Credentials, DisabledHttpClient, HttpClient, HttpDispatch, HttpDone, HttpHook, HttpRequest,
    HttpResponse, ThreadDispatch, UnknownCredentials,
};
pub use language::{
    MarkupBlock, MarkupBlockError, ScriptCompile, ScriptHostAccess, ScriptLanguage,
    ScriptLanguageAppExt, ScriptLanguages, ScriptProgram, UnknownLanguage, install_program,
};
pub use lumen_ir::source_map::SourceMap;
pub use runtime::*;
pub use script_fn::{
    Arity0, CallScratch, IntoScriptFn, MAX_VARIADIC_ARITY, ScriptField, ScriptFn, ScriptFnAppExt,
    ScriptFnBody, ScriptFnBuilder, ScriptFnCx, ScriptFnRegistry, ScriptFnStore, ScriptNs,
    ScriptParam, ScriptPrelude, ScriptResult, ScriptRet, ScriptSig, ScriptStruct, ScriptTy,
    ScriptType, with_call_scratch,
};
pub use wire::{PluginEvent, SCRIPT_WIRE_VERSION, push_plugin_event};

/// Errors a [`ScriptHost`] can surface from `load` or `tick`.
///
/// Structured compile errors carry the source URI and the offending
/// `(line, col)` so editor / LSP layers can place a squiggle without
/// re-parsing the error message. `Runtime` is still a free-form string;
/// Rhai's runtime errors don't always carry positions and the
/// trait-level shape is "best effort".
#[derive(Debug, Error)]
pub enum ScriptError {
    /// Source failed to parse / compile.
    #[error("script compile error at {uri}:{line}:{col}: {message}")]
    Compile {
        /// Origin URI (e.g. `"main.cdl"` or `"lumen://app/main.cdl"`);
        /// `"<inline>"` when the source has no associated URI.
        uri: String,
        /// 1-based line number reported by the parser. `0` when the
        /// position is unknown.
        line: u32,
        /// 1-based column number reported by the parser. `0` when the
        /// position is unknown.
        col: u32,
        /// Stringified parser message (sans position prefix).
        message: String,
    },
    /// Source compiled but execution failed.
    #[error("script runtime error: {0}")]
    Runtime(String),
}

impl ScriptError {
    /// Point a compile error in a concatenated program at the file and line
    /// the author wrote.
    ///
    /// `uri` is the program's own name and `map` says where each of its
    /// pieces was read from. An error about another file (a module the
    /// program imports) already names that file and is returned unchanged,
    /// as is a runtime error or one with no known line.
    #[must_use]
    pub fn relocate(self, uri: &str, map: &lumen_ir::source_map::SourceMap) -> Self {
        match self {
            Self::Compile {
                uri: at,
                line,
                col,
                message,
            } if at == uri && line > 0 => match map.locate(line) {
                Some((file, line)) if !file.is_empty() => Self::Compile {
                    uri: file.to_owned(),
                    line,
                    col,
                    message,
                },
                _ => Self::Compile {
                    uri: at,
                    line,
                    col,
                    message,
                },
            },
            other => other,
        }
    }

    /// Build a `Compile` with no specific position info. Equivalent to
    /// the previous `Compile(String)` shape; used by backends that
    /// can't surface line/col yet.
    pub fn compile(message: impl Into<String>) -> Self {
        Self::Compile {
            uri: "<inline>".to_string(),
            line: 0,
            col: 0,
            message: message.into(),
        }
    }
}

/// 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`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ScriptCommand {
    /// Append a line to the app's diagnostic output.
    Print(String),
    /// 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).
    AddClicks(i32),
    /// Free-form key/value the app can interpret. Strings only for now.
    SetString {
        /// Key (e.g. `"title"`, `"label"`).
        key: String,
        /// Value.
        value: String,
    },
    /// Replace the `TextContent` of the entity whose `LumenId` matches
    /// `target_id` (set in markup via `id="..."`).
    SetText {
        /// Target entity id.
        target_id: String,
        /// New text content.
        text: String,
    },
    /// 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`).
    SetSrc {
        /// Target entity id.
        target_id: String,
        /// New asset path. Resolved relative to the app directory at
        /// load time on the parser side; runtime mutations pass paths
        /// through verbatim, so authors should compose relative paths
        /// against their own app root (e.g. `"icons/sun.png"`).
        path: String,
    },
    /// Schedule a named timer. The runtime calls the script's
    /// `on_timer(name)` handler when it fires.
    SetTimer {
        /// Timer name, also passed as the `on_timer` argument.
        name: String,
        /// Delay until first fire, in milliseconds.
        millis: u64,
        /// If true, reschedule with the same interval after each fire.
        repeat: bool,
    },
    /// Cancel a pending or repeating timer by name. No-op if absent.
    CancelTimer {
        /// Timer name to cancel.
        name: String,
    },
    /// 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.
    Fetch {
        /// URL to GET.
        url: String,
        /// Identifier the script gets back in `on_fetch(tag, body)`.
        tag: String,
    },
    /// 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.
    Http {
        /// HTTP method (`GET`, `POST`, `PUT`, `DELETE`, ...). Case-insensitive.
        method: String,
        /// Target URL.
        url: String,
        /// Request headers as ordered key/value pairs.
        headers: Vec<(String, String)>,
        /// Optional request body. `None` sends no body.
        body: Option<String>,
        /// Optional per-request timeout in milliseconds (`None` = no
        /// client-imposed deadline).
        timeout_ms: Option<u64>,
        /// Whether the request carries the page's credentials. Only a
        /// browser transport acts on it.
        credentials: crate::http::Credentials,
        /// Identifier echoed back in `on_http(tag, response)`.
        tag: String,
    },
    /// 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.
    SetResponseStatus {
        /// HTTP status code.
        status: u16,
    },
    /// 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.
    SetResponseHeader {
        /// Header name.
        name: String,
        /// Header value.
        value: String,
    },
    /// 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.
    Redirect {
        /// Where the visitor is sent, as a path or an absolute URL.
        location: String,
    },
    /// 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.
    SetSignal {
        /// Signal name.
        name: String,
        /// New value.
        value: String,
    },
    /// 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).
    SetProperty {
        /// Property key (global or entity-scoped).
        #[serde(with = "crate::wire::property_key")]
        key: lumen_core::property_store::PropertyKey,
        /// New typed value. A
        /// [`Custom`](lumen_core::property_store::PropertyValue::Custom)
        /// payload cannot be encoded; see [`crate::wire::property_value`].
        #[serde(with = "crate::wire::property_value")]
        value: lumen_core::property_store::PropertyValue,
    },
    /// 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.
    SetArray {
        /// Array name.
        name: String,
        /// Items, each a flat map of field -> stringified value.
        items: Vec<std::collections::HashMap<String, String>>,
    },
    /// Show a native desktop notification. Cross-platform via
    /// `notify-rust` (libnotify on Linux, NSUserNotification on macOS,
    /// Toast on Windows).
    Notify {
        /// Notification summary / title.
        title: String,
        /// Body text.
        body: String,
    },
    /// Show a native desktop notification carrying an icon, an urgency,
    /// and action buttons. Pressing a button fires
    /// `on_notification_action(id, action_id)`.
    NotifyEx {
        /// Stable id echoed back in `on_notification_action`.
        id: String,
        /// Notification summary / title.
        title: String,
        /// Body text.
        body: String,
        /// Settings as `"icon:name-or-path|urgency:critical"`. Unknown
        /// keys are ignored; empty means no icon and normal urgency.
        options: String,
        /// Buttons as `"id:Label|id2:Label2"`. Empty means no buttons.
        actions: String,
    },
    /// Put `text` on the system clipboard.
    ClipboardWrite {
        /// Text to copy.
        text: String,
    },
    /// Request the system clipboard's text. The runtime reads it and
    /// fires `on_clipboard(tag, text)`.
    ClipboardRead {
        /// Identifier the script gets back in the event handler.
        tag: String,
    },
    /// Open a URL with the user's default handler (browser, mail client).
    OpenUrl {
        /// Absolute URL, including its scheme.
        url: String,
    },
    /// Open a filesystem path with the platform's default application.
    /// Relative paths resolve against the app directory.
    OpenPath {
        /// Path to open.
        path: String,
    },
    /// Show a file in the platform's file manager. Relative paths resolve
    /// against the app directory.
    RevealPath {
        /// Path to reveal.
        path: String,
    },
    /// 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.
    KeepAwake {
        /// Identifier used to release the request later.
        name: String,
        /// Human-readable reason shown by the platform's power settings.
        reason: String,
    },
    /// Release the sleep inhibit registered under `name`. No-op when the
    /// name is unknown.
    AllowSleep {
        /// Identifier matching the previous `KeepAwake` call.
        name: String,
    },
    /// 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.
    CopyImageToClipboard {
        /// Source PNG path.
        path: String,
    },
    /// Pulls the current clipboard image (when present) and writes it as PNG to `path`. Failures log to stderr.
    SaveClipboardImage {
        /// Destination PNG path.
        path: String,
    },
    /// Registers or replaces a system tray icon on macOS, Windows, and
    /// Linux. `icon_path` resolves relative to the app dir.
    RegisterTrayIcon {
        /// Stable id; clicks fire `on_tray(id)`.
        id: String,
        /// Path to a PNG icon.
        icon_path: String,
        /// Optional hover tooltip.
        tooltip: Option<String>,
        /// Context-menu items as `"id:Label|-|id2:Label2"`, where `-` is a
        /// separator. Picking one fires `on_menu(id)`. Empty means no menu.
        menu: String,
        /// macOS template-image flag: treat a monochrome icon as a
        /// template and recolour it for the active menu-bar theme.
        template: bool,
    },
    /// Drops a previously-registered tray icon by id.
    UnregisterTrayIcon {
        /// Matching id from `RegisterTrayIcon`.
        id: String,
    },
    /// 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.
    SetClasses {
        /// Target entity id, or the sentinel `<root>` to address the
        /// markup root.
        target_id: String,
        /// Whitespace-separated class names - same shape as
        /// `class="..."` markup attr.
        classes: String,
    },
    /// 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.
    SetColorScheme {
        /// One of `"default"`, `"force-light"`, `"force-dark"`,
        /// `"prefer-light"`, `"prefer-dark"`. `"default"` follows the OS.
        name: String,
    },
    /// 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.
    OpenFileDialog {
        /// What kind of dialog to show.
        kind: FileDialogKind,
        /// Identifier the script gets back in the event handler.
        tag: String,
        /// Filter list: `(label, extensions)` pairs. Empty = no
        /// filter (show all files).
        filters: Vec<(String, Vec<String>)>,
        /// Default filename suggestion for `Save`. Ignored for the
        /// other kinds.
        default_name: Option<String>,
    },
    /// 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.
    RegisterHotkey {
        /// Identifier the script gets back in `on_hotkey(name)`.
        name: String,
        /// Accelerator string. See `global-hotkey::HotKey::from_str`.
        accelerator: String,
    },
    /// Unregister a previously-registered hotkey by name. No-op if
    /// the name is unknown.
    UnregisterHotkey {
        /// Identifier matching the previous `RegisterHotkey` call.
        name: String,
    },
    // -- dynamic DOM: change things (phase 2) --------------------------
    /// 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.
    SetAttr {
        /// Target node (packed handle or reserved spawn token).
        node: u64,
        /// Attribute name.
        name: String,
        /// New value.
        value: String,
    },
    /// Remove an attribute from a node addressed by packed handle.
    RemoveAttr {
        /// Target node.
        node: u64,
        /// Attribute name to clear.
        name: String,
    },
    /// Replace a node's text content (`node.set_text`).
    SetNodeText {
        /// Target node.
        node: u64,
        /// New text.
        text: String,
    },
    /// Add one class to a node's class list (incremental, idempotent).
    ClassAdd {
        /// Target node.
        node: u64,
        /// Class name to add.
        class: String,
    },
    /// Remove one class from a node's class list.
    ClassRemove {
        /// Target node.
        node: u64,
        /// Class name to remove.
        class: String,
    },
    /// Toggle one class on a node's class list.
    ClassToggle {
        /// Target node.
        node: u64,
        /// Class name to toggle.
        class: String,
    },
    /// Set an inline style property (`element.style`), the highest cascade
    /// tier the runtime re-apply reads.
    SetStyleProp {
        /// Target node.
        node: u64,
        /// CSS property name.
        name: String,
        /// CSS value.
        value: String,
    },
    /// Remove an inline style property.
    RemoveStyleProp {
        /// Target node.
        node: u64,
        /// CSS property name to clear.
        name: String,
    },

    // -- dynamic DOM: build things (phase 3) ---------------------------
    /// 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.
    Spawn {
        /// Markup tag (`div`, `button`, ...).
        tag: String,
        /// Reserved spawn token (see
        /// [`lumen_core::node::reserve_node_token`]).
        reserved: u64,
    },
    /// 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).
    Insert {
        /// Parent node.
        parent: u64,
        /// Node to attach (detaching it from any current parent).
        node: u64,
        /// Reference child to insert before, or `0` to append.
        before: u64,
    },
    /// Replace `old` with `new` in `old`'s parent, then despawn `old`'s
    /// subtree (`replaceWith`).
    ReplaceWith {
        /// Node being replaced (removed after).
        old: u64,
        /// Replacement node, moved into `old`'s slot.
        new: u64,
    },
    /// Detach and despawn a node and its whole subtree (`node.remove`).
    RemoveNode {
        /// Node to remove.
        node: u64,
    },
    /// Deep-clone `source`'s subtree into a fresh detached node. `reserved`
    /// is the token the host minted for the clone root.
    CloneNode {
        /// Node to clone (with descendants).
        source: u64,
        /// Reserved spawn token for the clone root.
        reserved: u64,
    },
    /// 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`](crate) 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).
    SetInnerMarkup {
        /// Target node whose children are replaced.
        node: u64,
        /// Markup fragment to parse and spawn as the new children.
        markup: String,
    },
    /// 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.
    SpawnFragment {
        /// Key of the fragment to instantiate.
        key: String,
        /// Arguments as `(parameter name, value)` pairs.
        args: Vec<(String, String)>,
        /// Slot content as `(slot name, node handle)` pairs.
        children: Vec<(String, u64)>,
        /// Reserved spawn token for the instance root.
        reserved: u64,
    },

    // -- dynamic DOM: events (phase 4) ---------------------------------
    /// 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.
    BindEvent {
        /// Target node (packed handle or reserved spawn token).
        node: u64,
        /// Event type (`"click"`, `"keydown"`, ...).
        event_type: String,
        /// `true` for a capture-phase listener.
        capture: bool,
        /// Off / handler token (`handler_ref`).
        token: u64,
    },
    /// Unbind a previously-bound event handler by its off token
    /// (`removeEventListener`). No-op if the token is unknown.
    UnbindEvent {
        /// Off token returned by the matching `on(...)`.
        token: u64,
    },

    // -- window / document (section 4.8) -------------------------------
    /// Set the OS window title (`window.set_title`).
    WindowSetTitle {
        /// New title string.
        title: String,
    },
    /// Resize the OS window to `width` x `height` logical pixels
    /// (`window.set_size`).
    WindowSetSize {
        /// Logical width.
        width: f32,
        /// Logical height.
        height: f32,
    },

    // -- app lifecycle (recent files, autostart) ------------------------
    /// Record `path` as recently opened (move-to-front, capped list).
    /// Relative paths resolve against the app directory.
    AddRecentFile {
        /// File path to record.
        path: String,
        /// Display label; empty derives one from the path's file name.
        label: String,
    },
    /// Request the recent-files list. The runtime reads it and fires
    /// `on_recent_files(tag, paths)`, most recent first, paths joined by
    /// `|`.
    ListRecentFiles {
        /// Identifier the script gets back in the event handler.
        tag: String,
    },
    /// Remove every entry from the recent-files list.
    ClearRecentFiles,
    /// Enable or disable launching this app at login.
    SetAutostart {
        /// Whether the app should autostart.
        on: bool,
    },
    /// Request the current autostart state. The runtime reads it and fires
    /// `on_autostart_enabled(tag)` or `on_autostart_disabled(tag)`.
    QueryAutostart {
        /// Identifier the script gets back in the event handler.
        tag: String,
    },
    /// 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.
    RequestFrame,
    /// 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.
    SetLocale {
        /// BCP-47 tag, such as `"de-DE"`.
        tag: String,
    },
}

impl ScriptCommand {
    /// Whether the command changes the tree rather than the state behind it,
    /// which is what the DOM applier answers for.
    pub fn mutates_dom(&self) -> bool {
        matches!(
            self,
            ScriptCommand::SetAttr { .. }
                | ScriptCommand::RemoveAttr { .. }
                | ScriptCommand::SetNodeText { .. }
                | ScriptCommand::SetClasses { .. }
                | ScriptCommand::ClassAdd { .. }
                | ScriptCommand::ClassRemove { .. }
                | ScriptCommand::ClassToggle { .. }
                | ScriptCommand::SetStyleProp { .. }
                | ScriptCommand::RemoveStyleProp { .. }
                | ScriptCommand::Spawn { .. }
                | ScriptCommand::Insert { .. }
                | ScriptCommand::ReplaceWith { .. }
                | ScriptCommand::RemoveNode { .. }
                | ScriptCommand::CloneNode { .. }
                | ScriptCommand::SetInnerMarkup { .. }
                | ScriptCommand::SpawnFragment { .. }
                | ScriptCommand::BindEvent { .. }
                | ScriptCommand::UnbindEvent { .. }
                | ScriptCommand::WindowSetTitle { .. }
                | ScriptCommand::WindowSetSize { .. }
        )
    }

    /// 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.
    pub fn builds_nodes(&self) -> bool {
        matches!(
            self,
            ScriptCommand::Spawn { .. }
                | ScriptCommand::Insert { .. }
                | ScriptCommand::ReplaceWith { .. }
                | ScriptCommand::RemoveNode { .. }
                | ScriptCommand::CloneNode { .. }
                | ScriptCommand::SetInnerMarkup { .. }
                | ScriptCommand::SpawnFragment { .. }
        )
    }
}

/// The builtins that open a file dialog, as the prefixes a source scan looks
/// for: `pick_file` also covers `pick_files` and `pick_file_filtered`. What
/// installs a dialog executor, and what compiles one in, both key off these.
pub const FILE_DIALOG_BUILTINS: &[&str] = &["pick_file", "save_file", "pick_folder"];

/// File dialog flavour for [`ScriptCommand::OpenFileDialog`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum FileDialogKind {
    /// Pick one existing file. Fires `on_file_picked(tag, path)`.
    Open,
    /// Pick multiple existing files. Fires
    /// `on_files_picked(tag, "p1|p2|p3")` (paths joined with `|`).
    OpenMulti,
    /// Pick a save destination (may not exist yet). Fires
    /// `on_file_picked(tag, path)` (same handler as `Open` since the
    /// shape is identical).
    Save,
    /// Pick a folder. Fires `on_folder_picked(tag, path)`.
    PickFolder,
}

/// Typed sum the script-host trait understands across the boundary.
///
/// Mirrors what a dynamic script value carries - scalars, arrays, maps -
/// without leaking any host's value type into the trait. Backends translate
/// to / from their native value type.
///
/// Variants are append-only; see [`SCRIPT_WIRE_VERSION`].
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum ScriptValue {
    /// Absence of a value (Rhai `()`).
    Unit,
    /// Boolean payload.
    Bool(bool),
    /// Signed 64-bit integer payload.
    I64(i64),
    /// 64-bit float payload.
    F64(f64),
    /// Owned string payload.
    Str(String),
    /// Heterogeneous list.
    Array(Vec<ScriptValue>),
    /// Field map (insertion order is not preserved across the boundary).
    Map(std::collections::HashMap<String, ScriptValue>),
}

impl From<bool> for ScriptValue {
    fn from(v: bool) -> Self {
        Self::Bool(v)
    }
}

impl From<i64> for ScriptValue {
    fn from(v: i64) -> Self {
        Self::I64(v)
    }
}

impl From<f64> for ScriptValue {
    fn from(v: f64) -> Self {
        Self::F64(v)
    }
}

impl From<String> for ScriptValue {
    fn from(v: String) -> Self {
        Self::Str(v)
    }
}

impl<'a> From<&'a str> for ScriptValue {
    fn from(v: &'a str) -> Self {
        Self::Str(v.to_string())
    }
}

impl ScriptValue {
    /// Stringify any variant. Strings stay verbatim; everything else
    /// uses the canonical `Display` form. UNIT becomes the empty string.
    pub fn stringify(&self) -> String {
        match self {
            Self::Unit => String::new(),
            Self::Bool(b) => b.to_string(),
            Self::I64(i) => i.to_string(),
            Self::F64(f) => f.to_string(),
            Self::Str(s) => s.clone(),
            Self::Array(arr) => {
                let parts: Vec<String> = arr.iter().map(Self::stringify).collect();
                format!("[{}]", parts.join(", "))
            }
            Self::Map(m) => {
                let mut keys: Vec<&String> = m.keys().collect();
                keys.sort();
                let parts: Vec<String> = keys
                    .iter()
                    .map(|k| format!("{}: {}", k, m[*k].stringify()))
                    .collect();
                format!("{{{}}}", parts.join(", "))
            }
        }
    }
}

/// Backend-agnostic facade exposing the reactive property store to
/// script hosts. Mirrors QML's `QQmlContext::setContextProperty` /
/// `contextProperty()` shape: scripts read + write through a thin layer
/// the host keeps internally so callers don't have to thread an
/// `Engine` or a per-backend `Dynamic` type through.
///
/// Concrete impls own the underlying signal store. The trait is intentionally small:
/// every method maps to one host-side write so backends can rebuild
/// their internal mirror without re-implementing scalar/array policy
/// on top of `Dynamic`.
pub trait ScriptContext {
    /// Read a named scalar / structured property. `None` => the property
    /// has never been written.
    fn get(&self, name: &str) -> Option<ScriptValue>;

    /// Write a named scalar / structured property. The backend mirrors
    /// the write into its native value type and queues a stringified
    /// `SetSignal` for the ECS-side `Signals` resource.
    fn set(&mut self, name: &str, value: ScriptValue);

    /// Append `value` onto the named array property. Lazy-initialises
    /// the array if absent. Drives `<for each="<name>">` reconciliation.
    fn array_push(&mut self, name: &str, value: ScriptValue);

    /// Clear the named array property (set to empty).
    fn array_clear(&mut self, name: &str);

    /// Entity-scoped read for properties keyed by `(entity_id, name)`.
    /// Returns `None` when the backend doesn't model entity-scoped
    /// properties (most backends do not).
    fn entity(&self, entity_id: &str, name: &str) -> Option<ScriptValue> {
        let _ = (entity_id, name);
        None
    }
}

/// Outcome of one [`ScriptHost::call`] invocation.
///
/// `commands` is the full drain of the host's command sink at return. It is
/// drained even when `found == false`, because builtins invoked outside
/// handlers may have queued commands.
#[derive(Debug, Clone)]
pub struct CallOutcome {
    /// Commands the host's builtins pushed into the sink during (and
    /// before) the call, drained at return.
    pub commands: Vec<ScriptCommand>,
    /// The script function's return value. `None` when the function was
    /// not found (or no program is loaded). Carries meaning for hooks
    /// like `on_close()` -> `Bool(false)` vetoes the close.
    pub ret: Option<ScriptValue>,
    /// `false` when the function does not exist - the runtime probes
    /// optional handlers and treats a miss as silent success.
    pub found: bool,
}

/// A [`ScriptHost::call`] whose function raised an error.
///
/// `commands` holds what the function queued before it failed, drained from
/// the sink like a successful call's. The runtime applies them, the way a
/// browser keeps the DOM changes a throwing handler made before the throw:
/// a `print` placed before the failing line still reaches the log, and a
/// timer armed there still fires.
#[derive(Debug)]
pub struct CallFailure {
    /// The error the function raised.
    pub error: ScriptError,
    /// Commands queued before the failure.
    pub commands: Vec<ScriptCommand>,
}

impl std::fmt::Display for CallFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.error.fmt(f)
    }
}

impl std::error::Error for CallFailure {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.error)
    }
}

/// Merge a pre-reload registry snapshot back under the entries the reloaded
/// script just registered, so a reload never silently loses a registration.
///
/// `current` holds what the new top level registered and wins every collision;
/// `prior` fills in the rest. Every [`ScriptHost::replace`] implementation runs
/// this over its handler, event-handler, and derivation maps on the success
/// path. The registrations that need it are the ones an app makes from
/// `on_start`: that callback fires once at app construction and never again, so
/// its handlers cannot re-register themselves during a reload.
///
/// One case stays stale until the app restarts: renaming a handler function
/// together with the `on(...)` call that binds it leaves the old name in the
/// map under its old key, because nothing in the new source collides with it.
pub fn carry_forward<K, V>(
    current: &mut std::collections::HashMap<K, V>,
    prior: std::collections::HashMap<K, V>,
) where
    K: std::hash::Hash + Eq,
{
    for (key, value) in prior {
        current.entry(key).or_insert(value);
    }
}

/// Backend that compiles + executes scripts and exposes the host-neutral
/// registries the generic runtime (`lumen-script`) drives: the
/// command sink, the rich-typed signal mirror, the per-id handler
/// registry, and the derivation registry.
///
/// `Send + Sync` bound: hosts sit in a plain bevy `Resource` and
/// participate in parallel scheduling. A host that cannot be `Send` needs a
/// `NonSend` variant of the install path.
///
/// One script-side callable the generic runtime can re-invoke is modeled
/// by [`Self::Closure`] - Rhai: `FnPtr`; candela: a function handle once its
/// embedding API lands.
pub trait ScriptHost: Send + Sync + 'static {
    /// Host-native handle to a script closure (a `derive(...)` body).
    type Closure: Clone + Send + Sync + 'static;

    /// Whether this host is the one a component marker in the tree names a
    /// function in.
    ///
    /// A marker is what the build leaves where a component has to run, and
    /// markup blocks are one language's macro, so exactly one host answers
    /// for them. Every other host leaves a marker alone rather than reporting
    /// a function it was never going to have.
    const FILLS_COMPONENTS: bool = false;

    // -- lifecycle -----------------------------------------------------

    /// Compile-only, side-effect free, with the exact engine settings
    /// [`Self::load`] uses - `lumenc check` and `run` must agree on what
    /// parses. `uri` seeds [`ScriptError::Compile::uri`].
    fn compile_check(&self, source: &str, uri: &str) -> Result<(), ScriptError>;

    /// Compile + evaluate the top level into persistent state.
    /// Fresh-start load; replaces any previously loaded program.
    fn load(&mut self, source: &str, uri: &str) -> Result<(), ScriptError>;

    /// Hot reload: compile first (no state touched on a parse error), then
    /// swap atomically. Snapshot the registries, clear them, re-evaluate the
    /// top level into the existing persistent scope, and roll the snapshot
    /// back in full if that evaluation fails. Persistent across the swap:
    /// engine registrations, scope bindings, the signal mirror, and the
    /// in-flight command sink.
    ///
    /// On success the snapshot is merged back under whatever the new top
    /// level registered, via [`carry_forward`]. Lifecycle callbacks do not
    /// re-fire on reload, so a handler an app bound from `on_start` has no
    /// second chance to register itself; without the merge every such handler
    /// would go quiet after the first reload.
    fn replace(&mut self, source: &str, uri: &str) -> Result<(), ScriptError>;

    /// Drop the loaded program and all persistent state. Genuine
    /// restart; hot reload should use [`Self::replace`].
    fn reset(&mut self);

    // -- invocation (reactive-only: no per-frame hook in this trait) ---

    /// Call a script function by name. A missing function is silent
    /// success (`found: false`); see [`CallOutcome`]. A function that raises
    /// returns [`CallFailure`], which still carries the commands it queued
    /// before the error.
    fn call(&mut self, fn_name: &str, args: &[ScriptValue]) -> Result<CallOutcome, CallFailure>;

    /// Re-entrant closure invocation. Must be callable while the generic
    /// runtime holds NO host locks (snapshot-then-call pattern): the
    /// closure body may re-enter builtins that touch the sink / mirror.
    fn call_closure(
        &mut self,
        closure: &Self::Closure,
        args: &[ScriptValue],
    ) -> Result<ScriptValue, ScriptError>;

    /// Evaluate one derivation: read the dep values, invoke `closure`,
    /// store the rich result into the mirror under `name`, and return
    /// the host-canonical stringification for the ECS property store.
    ///
    /// Deviation from the original v2 sketch (documented in the design
    /// doc section 1.9): the default impl composes `mirror_get` -> `call_closure`
    /// -> `mirror_set` -> [`ScriptValue::stringify`], but hosts should
    /// override with a native path - round-tripping dep values through
    /// [`ScriptValue`] loses fidelity for host-native structured values,
    /// and stringification is host-canonical (Rhai renders `1.0` where
    /// Rust's `f64` Display renders `1`; store strings feed `bind-text`
    /// and the parse-back policy, so the host must own the format).
    fn eval_derivation(
        &mut self,
        closure: &Self::Closure,
        deps: &[String],
        name: &str,
    ) -> Result<String, ScriptError> {
        let args: Vec<ScriptValue> = deps
            .iter()
            .map(|d| self.mirror_get(d).unwrap_or(ScriptValue::Unit))
            .collect();
        let value = self.call_closure(closure, &args)?;
        let text = value.stringify();
        self.mirror_set(name, value);
        Ok(text)
    }

    // -- command sink --------------------------------------------------

    /// Drain commands queued by builtins since the last drain. Default: a
    /// host with no command sink has nothing to drain.
    fn drain_commands(&mut self) -> Vec<ScriptCommand> {
        Vec::new()
    }

    /// Put commands back into the sink so they flow through the next
    /// tick's normal drain (the `on_start` re-stash). Default: dropped.
    fn push_commands(&mut self, cmds: Vec<ScriptCommand>) {
        let _ = cmds;
    }

    // -- signal mirror (host-local, rich-typed) ------------------------

    /// Read a mirror entry. `None` => never written. Default: no mirror.
    fn mirror_get(&self, name: &str) -> Option<ScriptValue> {
        let _ = name;
        None
    }

    /// Write a mirror entry (host-native conversion of `value`). Default:
    /// no mirror, so the write is dropped.
    fn mirror_set(&mut self, name: &str, value: ScriptValue) {
        let _ = (name, value);
    }

    /// section 1.3 type-preserving parse-back of a store string. The trait pins
    /// the POLICY: a mirror entry currently holding a scalar (bool / int
    /// / float) parses the string back into that SAME type; structured
    /// mirror values (arrays, maps) stay authoritative and ignore the
    /// string; unparseable strings leave the mirror untouched; absent /
    /// string entries take the store string verbatim. Default: no mirror.
    fn mirror_sync_str(&mut self, name: &str, value: &str) {
        let _ = (name, value);
    }

    // -- registries populated by host builtins, read by the runtime ----

    /// Per-id handler lookup (`on(event, id, fn)`), including the
    /// template-suffix fallback: a handler registered for `save` also
    /// matches `user-card:save` via the last-`:` suffix. Default: no
    /// handler registry.
    fn handler_for(&self, event: &str, key: &str) -> Option<String> {
        let _ = (event, key);
        None
    }

    /// Snapshot of derivations matching `dirty` plus `pending`
    /// `(name, deps, closure)` - taken OUTSIDE any host lock so the
    /// driver can invoke closures re-entrantly. Default: no derivation
    /// registry.
    fn derivations_matching(
        &self,
        dirty: &HashSet<&str>,
        pending: &HashSet<String>,
    ) -> Vec<(String, Vec<String>, Self::Closure)> {
        let _ = (dirty, pending);
        Vec::new()
    }

    /// Names of derivations registered but never successfully evaluated;
    /// they all run on the next derivation pass regardless of dirt.
    /// Default: none.
    fn pending_initial(&self) -> HashSet<String> {
        HashSet::new()
    }

    /// Remove successfully-evaluated names from the pending-initial set.
    /// Erroring derivations stay pending and retry next tick. Default: no-op.
    fn clear_pending(&mut self, evaluated: &[String]) {
        let _ = evaluated;
    }

    // -- event handlers (phase 4) --------------------------------------

    /// Invoke the event-handler closure the host registered under `token`
    /// (via its `on(node, type, handler)` builtin). The host builds its
    /// native event object, which reads the process-global current-event
    /// cell ([`crate::event`]); commands the handler queues are drained via
    /// [`Self::drain_commands`] afterwards by the caller. Returns whether a
    /// closure was found and run.
    ///
    /// Default: not supported (no closure registry) -> `Ok(false)`. Hosts
    /// that expose `on(...)` with real closures override this.
    fn dispatch_event_handler(&mut self, token: u64) -> Result<bool, ScriptError> {
        let _ = token;
        Ok(false)
    }

    /// Drop the event-handler closure registered under `token` (the host
    /// side of `off()` / `UnbindEvent`). Default: no-op.
    fn drop_event_handler(&mut self, token: u64) {
        let _ = token;
    }

    // -- extension -----------------------------------------------------

    /// Bind one [`ScriptFn`] so the script can call it.
    ///
    /// The host maps [`ScriptNs`] onto its own name space, binds the
    /// signature's arity range, and retains `f` in a [`ScriptFnStore`] so
    /// [`Self::reset`] can put it back. A host's own engine accessors
    /// remain available for anything this shape cannot express.
    ///
    /// # Errors
    ///
    /// The host could not bind the function: its binding window has closed
    /// (candela binds host declarations when the artifact loads) or the engine
    /// rejected the registration.
    fn register_script_fn(&mut self, f: &ScriptFn) -> Result<(), ScriptError>;

    /// Take source a plugin ships alongside the functions it registered under
    /// `ns`, to be compiled ahead of the app's own program.
    ///
    /// This is how a plugin offers sugar over its functions: a struct and an
    /// `impl` block in this host's own language, so a script calls
    /// `pin(21).level()` instead of the free function. The registry hands a
    /// host only the sources written in its language.
    ///
    /// A host that cannot stage source says so rather than dropping it, which
    /// is what the default does.
    fn add_prelude(&mut self, ns: &str, source: &str) {
        let _ = source;
        warn_line!(
            "{}: the `{ns}` plugin ships source this host cannot compile ahead of the program; \
             call its functions directly",
            prefix(self.lang())
        );
    }

    // -- metadata ------------------------------------------------------

    /// Language tag, such as `"candela"`. Used in diagnostics prefixes
    /// (`lumen-<lang>: ...`).
    fn lang(&self) -> &'static str;

    /// The builtin-function metadata table feeding LSP completion /
    /// hover and the parity test. Default: none.
    fn builtins(&self) -> &'static [BuiltinFn] {
        &[]
    }
}

/// Marker trait reserving the script-side state-proxy contract. Currently empty.
pub trait StateProxy {}