Struct RunOptions 

pub struct RunOptions {

    pub dir: PathBuf,
    pub title: Option<String>,
    pub size: (u32, u32),
    pub clear: Color,
    pub hot_reload: bool,
    pub plugins: Vec<PluginInstaller>,
    pub native_fns: Vec<ScriptFn>,
    pub markup: Option<String>,
    pub css: Option<String>,
    pub app_hooks: Vec<AppHook>,
    pub artifact: Option<PathBuf>,
    pub artifact_bytes: Option<Vec<u8>>,
    pub bounded: bool,
    pub assets: Option<PathBuf>,
    pub parser: Option<Box<dyn SourceParser>>,
    pub compiler_plugins: Option<Arc<dyn CompilerPlugins>>,
    pub resolved_modules: ResolvedModules,
    pub import_roots: Vec<(String, PathBuf)>,
    /* private fields */
}

Options for lumenc run.

Fields

dir: PathBuf

Path to the app directory (must contain src/main.lmn).

title: Option<String>

Window title. Defaults to the directory name.

size: (u32, u32)

Window size in logical pixels.

clear: Color

Background color when no CSS sets one.

hot_reload: bool

Watch source files and reload on change. On by default.

plugins: Vec<PluginInstaller>

Plugins installed on the App before the markup is parsed and the script hosts load. See Self::with_plugin.

native_fns: Vec<ScriptFn>

Native functions exposed to the app’s script in host-neutral terms. Each one is registered into every host the app runs, marshalling arguments and results through lumen_script::ScriptValue. This is what the C-ABI’s lumen_app_expose builds.

candela resolves host calls through a declared block, so a candela script reaches these as native::<name>(...) after declaring host "native" { any <name>(...); }.

markup: Option<String>

In-memory markup source. When Some, the runtime parses this string instead of reading <dir>/src/main.lmn from disk, and hot reload is disabled (there is no file to watch). Set by the Rust SDK’s include_str!-based embedding path; dir is still used to resolve relative asset paths and lumen.toml.

css: Option<String>

In-memory stylesheet source. When Some, used instead of <dir>/src/main.css. Independent of Self::markup; None falls back to the on-disk lookup.

app_hooks: Vec<AppHook>

Callbacks invoked on the fully-built App just before the event loop starts. See AppHook.

artifact: Option<PathBuf>

Load a precompiled AOT artifact (lumenc build) instead of parsing <dir>/src/main.lmn + src/main.css from source. When Some, the parser is bypassed entirely (and hot reload is disabled); dir is still used to resolve lumen.toml. Required for a runtime built without the runtime-parse feature.

artifact_bytes: Option<Vec<u8>>

Load a precompiled AOT artifact from in-memory bytes instead of a file path. The link-not-embed launcher path: the compiler produces LMNA bytes in-process and hands them across the C-ABI (lumen_app_new_from_lmna) so the runtime never touches the parser or a source file. When Some, it wins over Self::artifact and Self::parser; dir is still used to resolve relative asset paths.

bounded: bool

True for a headless / bounded automation run (--headless, and the FFI/test run_app_headless contract). Suppresses the long-lived interactive daemons that only make sense for a windowed session: the MCP introspection server (unless [mcp] simulate = true, which automation drivers set) and the hot-reload file watcher. Off by default so an ordinary lumenc run keeps both. See build_app.

assets: Option<PathBuf>

Serve the app’s assets from a .lpak archive (lumenc bundle) instead of the loose files under Self::dir. A path the markup resolves under dir is looked up in the archive first and read from disk only when the archive has no such entry, so an app can ship one file next to its binary. None reads everything from disk. Applied by run_app and build_headless_app.

parser: Option<Box<dyn SourceParser>>

Injected markup/CSS front-end used for dev source-load and hot-reload re-parse. lumen-runtime links no parser itself (it stays in the compiler); the CLI / SDK / FFI dev paths populate this with a SourceParser impl (lumenc’s LumencParser). None is valid for the precompiled-artifact path (Self::artifact) and for a runtime that only ever loads AOT artifacts; a from-source run with no parser fails with RunError::ParserDisabled.

compiler_plugins: Option<Arc<dyn CompilerPlugins>>

Injected compiler-plugin chain, mirroring Self::parser: the runtime links no plugin loader; lumenc builds the chain from the app’s [[plugins]] declarations and hands it in here. None runs the empty chain.

resolved_modules: ResolvedModules

Injected version-source module resolutions, mirroring Self::compiler_plugins: the runtime never resolves a version entry of [dependencies] itself (no semver, no registry in its graph); lumenc asks lpm to resolve each one and hands the outcome in here for the module loader to consult before its own on-disk probe.

import_roots: Vec<(String, PathBuf)>

Script libraries the app depends on, as the name a script imports under and the directory holding its sources. Filled in the same way Self::resolved_modules is: the runtime resolves nothing, and lumenc hands in what the registry answered.

Implementations

impl RunOptions

pub const DEFAULT_SIZE: (u32, u32)

Built-in default window size - kept as a constant so the runtime can detect that the caller didn’t override it and let lumen.toml’s [window] size win instead.

pub fn new(dir: impl Into<PathBuf>) -> Self

Construct with sensible defaults.

pub fn with_parser(self, parser: Box<dyn SourceParser>) -> Self

Builder: inject the markup/CSS front-end used for dev source-load and hot-reload re-parse. See Self::parser.

pub fn with_compiler_plugins(self, plugins: Arc<dyn CompilerPlugins>) -> Self

Builder: inject the compiler-plugin chain run by the dev source-load and hot-reload paths. See Self::compiler_plugins.

pub fn with_artifact(self, path: impl Into<PathBuf>) -> Self

Builder: load a precompiled AOT lumen_ir::artifact instead of parsing source. See Self::artifact.

pub fn with_artifact_bytes(self, bytes: impl Into<Vec<u8>>) -> Self

Builder: load a precompiled AOT lumen_ir::artifact from in-memory bytes instead of a file path. See Self::artifact_bytes.

pub fn with_plugin<P: Plugin + Send + 'static>(self, plugin: P) -> Self

Builder: install a Plugin on the app before the markup is parsed and before the script hosts load.

A plugin that brings an element registers its tag from build, which this phase puts ahead of the parse that would otherwise refuse it. It is also the phase a plugin that registers script functions (ScriptFnAppExt::add_script_fn) belongs in: candela binds its host declarations when the program compiles or the artifact loads, so a function registered later has nothing to bind to. Contrast Self::with_app_hook, which runs on the fully-built app and is where systems ordered against the default stack belong.

Plugins install in the order they are added, after the runtime’s own built-in script functions and before Self::native_fns; a name registered later shadows an earlier one.

pub fn with_native_fn(self, f: ScriptFn) -> Self

Builder: expose a native function to the app’s script in host-neutral terms. See Self::native_fns.

pub fn with_markup(self, src: impl Into<String>) -> Self

Builder: parse this in-memory markup string instead of reading <dir>/src/main.lmn from disk. Disables hot reload. See Self::markup.

pub fn with_css(self, src: impl Into<String>) -> Self

Builder: apply this in-memory stylesheet instead of reading <dir>/src/main.css from disk. See Self::css.

pub fn with_app_hook<F>(self, f: F) -> Self

where F: FnOnce(&mut App) + 'static,

Builder: install a callback invoked on the fully-built App right before the event loop starts. See AppHook.

pub fn with_assets(self, lpak: impl Into<PathBuf>) -> Self

Builder: serve assets from a .lpak archive. See Self::assets.