Module run 

The ECS run loop, RunOptions/RunError, build_app, hot reload, and the script-command machinery. Launches a pure-markup Lumen app via lumenc run <dir>.

Expects:

<dir>/
  lumen.toml   # optional: app config
  src/
    main.lmn   # required: markup (with optional inline <script>)
    main.css   # optional: stylesheet

• Wires the default plugin stack: the registered layout engine, cosmic text, input, hover/press/drag/scroll primitives, the script host module for each language the app ships, optional MCP server.
• Runs the registered window backend’s event loop and returns when the window closes or a fatal error occurs.
• Hot reload: a notify file watcher (inotify / FSEvents / ReadDirectoryChangesW) covers src/main.lmn, src/main.css, and every included / imported source; an fs event wakes the loop for one tick and the hot_reload system re-checks mtimes. On change it despawns the spawned root, re-parses, re-applies CSS, re-spawns, and reloads each script host’s program in place. Parse errors keep the previous tree intact and log to stderr. LUMEN_HOT_RELOAD_POLL=1 (or watcher init failure) falls back to the legacy 300 ms mtime poll.
• Script commands: SetText updates the matching LumenId’s [TextContent]; other variants (Print, AddClicks, SetString) no-op here.

Structs

CheckReport

Summary returned by check_app.

ColorSchemeIntent

Cross-thread payload pushed by the W4.6 set_color_scheme(name) Rhai builtin. Carries the parsed lumen_core::components::ColorScheme intent over the bounded lumen_core::command::CommandQueue so the main-thread handler can apply it via lumen_core::components::StyleManager::set_scheme during TickStage::CommandDrain.

CompileDeps

What a compile takes from outside the app directory: the target it builds for, and what lumenc resolved for that target before it started.

ErrorBanner

In-app error banner. Hot-reload parse failures land here; a dedicated system paints a red strip at the top of the window with the error text. Esc / click clears the banner.

ErrorBannerMarker

Marker for the entity spawned to render the ErrorBanner. Used to find + update + despawn the banner across ticks.

ModuleSurface

What a set of modules registers for scripts: the functions a program calls them by, and the language sources compiled ahead of it.

RunOptions

Options for lumenc run.

WindowSetup

The window-facing half of a built app: the resolved WindowOptions plus the render-side text shaper the build picked for it. Returned alongside the App by build_app and build_headless_app.

Enums

RunError

Errors raised while preparing the app.

Functions

build_app

Construct the fully-configured App and the WindowSetup the windowed path would run it with - everything run_app does short of entering the event loop. Split out so run_app_headless can reuse the identical build without duplicating the plugin / system wiring.

build_headless_app

Shared headless plumbing: build_app plus the window-free half of every window backend, WindowCorePlugin (the window messages, the RedrawScheduler, and the extract pipeline). A window backend installs the same plugin when it runs; only the event loop and the renderer bind need a display. Installing it here gives every headless schedule the same resource/system set, so a system that reads window state doesn’t fail validation. Used by run_app_headless (no renderer; FFI/test contract), crate::run_headless::run_app_headless_rendered (full offscreen-render mode), and the golden-image screenshot suite (public/lumenc/tests/golden.rs), which installs an offscreen renderer on top and reads the framebuffer back.

check_app

Parse <dir>/src/main.lmn + optional <dir>/src/main.css and validate them without spawning a window. Used by CI / pre-commit hooks.

compile_app

Ahead-of-time compile an app directory into a lumen_ir::artifact::CompiledApp: parse markup + CSS once, run the full cascade, resolve asset / include / import paths, and bake the combined script source. The returned artifact is what lumenc build writes to disk and what a parser-free runtime loads via RunOptions::artifact.

compile_app_with_skin

compile_app with the skin named outright instead of read from lumen.toml.

dismiss_error_banner_on_escape

Esc clears the error banner. Wired alongside the dialog Esc handler so a single keystroke dismisses any blocking surface.

locale_dir

Directory holding an app’s .ftl catalogues.

module_surface

What the modules in deps register for scripts, read the way a run reads it: each is installed into a scratch app, in headless mode, by the loader a run uses, and its registrations are taken back out. A module compiled into this binary answers from there, and any other is opened from disk, so the surface is the one the app’s run binds to.

reconcile_error_banner

Reconcile the on-screen banner against ErrorBanner:

run_app

Read <dir>/src/main.lmn + optional <dir>/src/main.css, build a default App, spawn the parsed tree, and run it in the registered window backend.

run_app_headless

Build the full app WITHOUT opening a window, then drive ticks main-schedule ticks and return. Headless / CI entry point: same plugin stack, scripts, and reactive bindings as run_app, but no windowing, input, or rendering - just App::tick in a loop.

script_exports

The names a compiled program can be called by.

Type Aliases

AppHook

An embedder callback invoked on the fully-built App right before the window event loop starts. Every default plugin and system is already registered at that point, so a hook can insert resources and add systems ordered against the default stack’s public systems (for example .before(lumen_core::signals::apply_text_bindings)).

PluginInstaller

One deferred Plugin installation, held until build_app reaches the phase that runs it. Send so an embedder can build the options on one thread and run them on another; the plugin itself is moved into the closure.