Crate lumen 

Lumen C-ABI surface.

Opaque LumenApp plus a tagged LumenValue union let any language with C interop embed Lumen. The app’s script reaches across the ABI through callbacks the embedder registers via lumen_app_expose. No Rust panic escapes any lumen_* fn - every entry point wraps its body in catch_unwind and stashes a UTF-8 message that C callers read through lumen_last_error.

W6.12 hardening

• user_data no longer uses the usize stash trick. It now lives in UserData, a NonNull<c_void> newtype with an explicit unsafe impl Send + Sync whose SAFETY comment names the embedder’s contract.
• LumenStatus split from 5 variants into a richer error surface so C callers can branch on ErrParse vs ErrCss vs ErrWindow instead of one opaque ErrRuntime.
• LUMEN_ABI_VERSION + lumen_abi_version export a runtime ABI version (major << 16) | (minor << 8) | patch.
• lumen_last_error keeps its thread-local primary store but now falls back to a global Mutex<Option<CString>> when the thread has no error recorded. This trades a cheap lock for the common case where embedders call lumen_app_run on thread A and check the error on thread B.

Modules

sdk

The Rust crates this library is built from, re-exported so a Rust program can reach them through it.

Structs

LumenApp

Builder + handle for one embedded Lumen application. Construct with lumen_app_new, populate with lumen_app_expose / lumen_app_set_*, run with lumen_app_run (which consumes the handle). If you decide not to run, lumen_app_free drops it.

LumenArrayView

Borrowed view of an array of LumenValue. Pointer must stay valid for the duration of the call returning it.

LumenEvent

Scalar snapshot of the event delivered to a LumenEventFn. The string fields (type / key / value) are read separately via lumen_event_type / lumen_event_key / lumen_event_value. #[repr(C)] (never packed): the fields are naturally aligned.

LumenFrameInfo

Per-frame counters (frame_info()).

LumenKV

One (key, value) pair in a LumenKVList. Both are owned, UTF-8, NUL-terminated strings freed by lumen_kvlist_free.

LumenKVList

Owned key-value buffer returned by the string-map introspection reads. Free with lumen_kvlist_free.

LumenMapEntry

One entry in a LumenMapView. key is UTF-8, NUL-terminated.

LumenMapView

Borrowed view of a map of LumenMapEntry. Pointer must stay valid for the duration of the call returning it.

LumenNodeList

Owned list of node handles returned by a query / children call. Free with lumen_nodelist_free; index with lumen_nodelist_get.

LumenPointerState

Pointer state snapshot (pointer_state()).

LumenRect

Post-layout box (design 4.7 rect() / content_rect()). Local x / y are relative to the parent; client_* are window coordinates.

LumenScroll

Scroll offsets + travel limits (scroll()).

LumenStrList

Owned string buffer returned by classes / components. Free with lumen_strlist_free.

LumenValue

One scalar / container value crossing the C ABI in either direction. Always pass kind consistently with the populated union field. Pointers are borrowed for the duration of the call; Lumen copies before returning to the script.

UserData

Embedder-supplied opaque pointer carried across the FFI to native callbacks. A script host moves the wrapping closure across threads, which requires Send + Sync - that bound is impossible to satisfy generically for *mut c_void, so this newtype carries an explicit unsafe impl with the contract spelled out in SAFETY.

Enums

LumenKind

Discriminant for LumenValue.

LumenStatus

Return code for every lumen_* C function.

Constants

LUMEN_ABI_MAJOR

Major ABI version. Bump on breaking layout/signature changes.

LUMEN_ABI_MINOR

Minor ABI version. Bump on additive changes (new exports, new variants at the end of enums).

LUMEN_ABI_PATCH

Patch ABI version. Bump on non-API metadata changes (docs, code, etc.).

LUMEN_ABI_VERSION

Packed runtime ABI version (major << 16) | (minor << 8) | patch. Mirrored in lumen.h as LUMEN_API_VERSION. Embedders compare at runtime to refuse a header / shared-library mismatch.

Functions

lumen_abi_version

Returns the packed ABI version this library was compiled with. Compare against LUMEN_API_VERSION from lumen.h at startup.

lumen_app_expose^⚠

Expose a native callback to the app’s script under name. arg_count is the arity (0..=8 sensible); a host that dispatches on arity reads it, and candela binds the call variadically. Pointers are stored by value; the embedder owns user_data and must keep it valid until lumen_app_run returns.

lumen_app_free^⚠

Drop the app handle without running. Safe to call on null.

lumen_app_new^⚠

Allocate a new app rooted at dir (UTF-8, NUL-terminated). The directory must exist and contain lumen.toml and/or src/main.lmn. Returns null on error; call lumen_last_error for details.

lumen_app_new_from_lmna^⚠

Allocate a new app from prebuilt LMNA artifact bytes (ABI 0.7). data points to len bytes of a lumenc-compiled artifact (magic LMNA); Lumen copies them in immediately, so the caller may free data as soon as this returns. base_dir (UTF-8, NUL-terminated, or null) is the directory relative asset paths in the artifact resolve against; null means the current directory.

lumen_app_on_click^⚠

Register an id-scoped native click handler (ABI 0.3).

lumen_app_on_close^⚠

Register an app-level close hook (ABI 0.5).

lumen_app_run^⚠

Consume the app handle and enter the Lumen event loop. Blocks until the window closes. After this returns, app is freed - do not call lumen_app_free on the same pointer.

lumen_app_run_headless^⚠

Consume the app handle and drive ticks main-schedule ticks without opening a window or GPU surface (ABI 0.3). After this returns, app is freed - do not call lumen_app_free on the same pointer.

lumen_app_set_size^⚠

Override the initial window size in logical pixels.

lumen_app_set_title^⚠

Override the window title (default: derived from lumen.toml or the directory name).

lumen_current_page^⚠

Read the current active page key into buf (UTF-8 + trailing NUL), following the shared string-out convention: on success *out_len (when non-null) is the byte length excluding the NUL; when buf is null or too small, *out_len is set to the required capacity and LumenStatus::ErrBufferTooSmall is returned. Empty before the first page mounts. Thread-safe (reads the lumen_core::nav current-page mirror, which lags a resolved navigation by at most one tick).

lumen_document^⚠

Write the document root node to *out (0 before the first tick). Thread-safe.

lumen_document_spawn^⚠

document.spawn(tag): document-scoped create verb; writes the new handle to *out. Thread-safe.

lumen_dump_tree^⚠

Whole-tree structural dump. Owned C string, free with lumen_string_free. An inspection call.

lumen_event_current_target

The current event’s current_target node (packed handle). Thread-safe.

lumen_event_key^⚠

Copy the current event’s key (keyboard events) into buf. See lumen_event_type for the convention. Thread-safe.

lumen_event_prevent_default

Cancel the current event’s default action (link navigation for click, form submission for submit). Thread-safe.

lumen_event_stop_immediate_propagation

Stop the current event immediately: no further handlers run, on this node or any other. Thread-safe.

lumen_event_stop_propagation

Stop the current event propagating to further nodes. Thread-safe.

lumen_event_target

The current event’s target node (packed handle), or 0 outside a callback. Thread-safe.

lumen_event_type^⚠

Copy the current event’s type name into buf (string-out convention: *out_len excludes the NUL; too-small returns LumenStatus::ErrBufferTooSmall with the required capacity). Valid only inside a LumenEventFn callback. Thread-safe.

lumen_event_value^⚠

Copy the current event’s value (input / change events) into buf. See lumen_event_type for the convention. Thread-safe.

lumen_frame_info^⚠

Current frame counters, written to *out. Thread-safe.

lumen_get_by_id^⚠

Fast id lookup. Writes the matching node to *out, or 0 when no element carries id. Thread-safe.

lumen_history_go^⚠

history.go(delta): step delta entries (negative back, positive forward) through the in-memory history stack. Thread-safe.

lumen_kvlist_free^⚠

Release a LumenKVList returned by an introspection read.

lumen_last_error^⚠

Last error message set by any lumen_* call on this thread. Returns null if no error has been recorded on this thread AND no error has been recorded globally. The pointer is valid until the next lumen_* call on this thread that produces an error.

lumen_last_error_global

Returns the most recent error message recorded by any thread. May return null if no error has ever been recorded. The returned pointer is valid until the next lumen_* call anywhere in the process that produces an error.

lumen_navigate^⚠

Navigate the active page to path (UTF-8, NUL-terminated). path is a page path ("settings", "/user/7", "/"), resolved by longest existing .lmn prefix - not a URL scheme. Equivalent to the script page("...") command and the Rust SDK Signals::navigate. Thread-safe.

lumen_navigate_back^⚠

Step one entry back in the in-memory history stack (desktop). No-op at the start of history. Thread-safe.

lumen_navigate_forward^⚠

Step one entry forward in the in-memory history stack (desktop). No-op at the end of history. Thread-safe.

lumen_node_append^⚠

Append child under parent (appendChild). Thread-safe.

lumen_node_attrs^⚠

Full attribute map of node. Free with lumen_kvlist_free.

lumen_node_children^⚠

Children of node in document order, written to *out_list (own + free with lumen_nodelist_free). Thread-safe.

lumen_node_class_add^⚠

Add one class to node’s class list. Thread-safe.

lumen_node_class_remove^⚠

Remove one class from node’s class list. Thread-safe.

lumen_node_class_toggle^⚠

Toggle one class on node’s class list. Thread-safe.

lumen_node_classes^⚠

Class list of node. Free with lumen_strlist_free.

lumen_node_clone^⚠

Deep-clone source’s subtree into a fresh detached node, writing its handle to *out. Thread-safe.

lumen_node_closest^⚠

Nearest ancestor-or-self of node matching selector, written to *out (0 when none). Bad selector returns LumenStatus::ErrCss. Thread-safe.

lumen_node_component^⚠

Field map of node’s name component. Free with lumen_kvlist_free. A non-whitelisted component name returns LumenStatus::ErrBadArg.

lumen_node_components^⚠

Names of the whitelisted components present on node. Free with lumen_strlist_free.

lumen_node_computed_style^⚠

Full computed style of node as an owned key-value buffer. Free with lumen_kvlist_free. An inspection call. Thread-safe.

lumen_node_content_rect^⚠

Content-box (inner box minus padding + border) of node. Thread-safe.

lumen_node_entity_id^⚠

Raw (index, generation) of node, written to *out_index / *out_gen.

lumen_node_first_child^⚠

First child of node (0 when none). Thread-safe.

lumen_node_inline_style^⚠

Inline-style override map of node. Free with lumen_kvlist_free.

lumen_node_inner_markup^⚠

Serialize node’s children (not the node itself) to .lmn-ish text – the read half of lumen_node_set_inner_markup. Owned C string, free with lumen_string_free.

lumen_node_insert_before^⚠

Insert child under parent before reference (insertBefore). A reference of 0 appends. Thread-safe.

lumen_node_is_visible^⚠

Effective visibility of node (1 / 0), written to *out.

lumen_node_last_child^⚠

Last child of node (0 when none). Thread-safe.

lumen_node_next^⚠

Next sibling of node (0 when none). Thread-safe.

lumen_node_outer_markup^⚠

Serialize node’s subtree to .lmn-ish text. Owned C string, free with lumen_string_free.

lumen_node_parent^⚠

Parent of node (0 for a root or unknown handle). Thread-safe.

lumen_node_prev^⚠

Previous sibling of node (0 when none). Thread-safe.

lumen_node_rect^⚠

Post-layout border-box of node, written to *out. Thread-safe.

lumen_node_remove^⚠

Detach and despawn node and its subtree (node.remove). Thread-safe.

lumen_node_remove_attr^⚠

Remove an attribute from node. Thread-safe.

lumen_node_remove_style^⚠

Remove an inline style property from node. Thread-safe.

lumen_node_replace_with^⚠

Replace old with new in old’s parent, despawning old’s subtree. Thread-safe.

lumen_node_scroll^⚠

Scroll offsets + limits of node, written to *out. Thread-safe.

lumen_node_set_attr^⚠

Set an attribute on node. KNOWN attrs (id / class / text / disabled) route to their typed component; others land in the generic attribute map. Thread-safe.

lumen_node_set_inner_markup^⚠

Replace node’s children with the subtree parsed from markup (element.innerHTML = ...). Parsed by the injected front-end and spawned through the same path the <for> reconciler uses; a no-op on the precompiled-artifact path (no parser linked). Guarded: do not feed untrusted content; this injects live markup. Thread-safe.

lumen_node_set_parent^⚠

Attach node under parent (node.set_parent / reparent). Thread-safe.

lumen_node_set_style^⚠

Set an inline style property on node (element.style). Thread-safe.

lumen_node_set_text^⚠

Replace node’s text content. Thread-safe.

lumen_node_spawn^⚠

Create a fresh detached element with markup tag tag, writing its handle to *out. The handle is valid for the rest of the tick; attach it with lumen_node_append / lumen_node_set_parent. Thread-safe.

lumen_node_valid^⚠

Whether node is present in the current snapshot (1) or not (0), written to *out. The snapshot rebuilds each tick, so a despawned node reads 0. Thread-safe.

lumen_node_z_index^⚠

Resolved stacking order of node, written to *out.

lumen_nodelist_free^⚠

Release a LumenNodeList returned by a query / children call. Double-free / freeing a non-Lumen list is undefined; call once.

lumen_nodelist_get^⚠

Read the handle at index in list, written to *out. Out-of-range (or null list) returns LumenStatus::ErrBadArg. The iteration primitive: walk 0..list.len. Thread-safe.

lumen_off

Unbind a callback previously registered with lumen_on. No-op for an unknown token. Thread-safe.

lumen_on^⚠

Bind callback to node for event_type. capture (non-zero) makes it a capture-phase listener. Returns an off token (0 on a bad argument); unbind with lumen_off. Thread-safe.

lumen_pointer_state^⚠

Current pointer state, written to *out. Thread-safe.

lumen_query^⚠

Run a CSS selector against the current DOM snapshot, writing the matches (document order) into *out_list. On success the caller owns the list and must release it with lumen_nodelist_free. A bad selector returns LumenStatus::ErrCss. Thread-safe.

lumen_query_len^⚠

Number of matches for selector, written to *out_len. Thread-safe.

lumen_query_single^⚠

Bevy single() contract: succeed only when selector matches exactly one node, writing it to *out. Zero or many matches returns LumenStatus::ErrBadArg (and sets *out to 0). Thread-safe.

lumen_signal_array_get_field^⚠

Read one field of one row of an array signal as a UTF-8 string (ABI 0.3).

lumen_signal_array_len^⚠

Report the row count of an array signal (ABI 0.3).

lumen_signal_clear^⚠

Clear a signal (scalar => empty string, array => empty vec).

lumen_signal_get_bool^⚠

Read a scalar signal as a boolean, typed.

lumen_signal_get_color^⚠

Read a scalar signal as a 4-byte RGBA color. out must point to at least 4 writable bytes.

lumen_signal_get_float64^⚠

Read a scalar signal as an IEEE-754 double, typed.

lumen_signal_get_int64^⚠

Read a scalar signal as a 64-bit signed integer, typed. Returns LumenStatus::ErrBadArg when the signal holds no number.

lumen_signal_get_str^⚠

Read a scalar signal as a UTF-8 string into a caller-provided buffer.

lumen_signal_set_array^⚠

Replace the contents of an array signal. value must be a LUMEN_ARRAY of LUMEN_MAP entries - each map becomes one row (string->string after stringification) consumed by <for> markup. Pointer is borrowed for the duration of the call; Lumen copies immediately. Embedder may free buffers as soon as this returns.

lumen_signal_set_bool^⚠

Set a scalar signal to a boolean, typed.

lumen_signal_set_color^⚠

Set a scalar signal to a 4-byte RGBA color (each channel in 0..=255). rgba must point to at least 4 bytes (R, G, B, A).

lumen_signal_set_float64^⚠

Set a scalar signal to an IEEE-754 double, typed.

lumen_signal_set_int64^⚠

Set a scalar signal to a 64-bit signed integer, typed.

lumen_signal_set_str^⚠

Set a scalar signal to a UTF-8 string. A null value writes an empty string. Thread-safe.

lumen_signal_watch^⚠

Subscribe to changes of the global signal name (ABI 0.4).

lumen_signals_all^⚠

The whole signal set as an owned key-value buffer. Free with lumen_kvlist_free. An inspection call. Thread-safe.

lumen_status_message

Returns a static, NUL-terminated UTF-8 description of status. Useful for log messages on a non-OK return without an lumen_last_error round-trip (which carries the thread-local context message instead of the status enum’s canonical name). The returned pointer lives for the program’s lifetime; callers must not free it.

lumen_string_free^⚠

Release an owned C string returned by dump_tree / outer_markup.

lumen_strlist_free^⚠

Release a LumenStrList returned by classes / components.

lumen_window_dpr^⚠

window.dpr: current device-pixel ratio, written to *out. Thread-safe.

lumen_window_reload^⚠

window.reload: re-navigate to the current page. Thread-safe.

lumen_window_set_href^⚠

window.set_href: navigate to a page path. Binds onto the same lumen_core::nav bus as lumen_navigate. Thread-safe.

lumen_window_set_size^⚠

window.set_size in logical pixels. Thread-safe.

lumen_window_set_title^⚠

window.set_title. Thread-safe.

Type Aliases

LumenClickFn

Id-scoped native click callback (ABI 0.3). Registered with lumen_app_on_click; invoked once per [ClickEvent] whose target element carries the matching LumenId. id is the element id (UTF-8, NUL-terminated), borrowed for the duration of the call.

LumenCloseFn

App-level close callback (ABI 0.5). Registered with lumen_app_on_close; invoked once per OS close request - the window close button, or (Unix) the first SIGINT/SIGTERM - before the runtime tears anything down, so embedders get a last chance to persist state.

LumenEventFn

C callback invoked when a bound event fires. event is borrowed for the duration of the call; copy anything retained. user_data is the pointer passed to lumen_on.

LumenEventToken

Off token returned by lumen_on; pass to lumen_off to unbind.

LumenFn

Signature of an exposed callback. Register with lumen_app_expose.

LumenNode

Opaque packed node handle. 0 means “no node”.

LumenWatchFn

Signal-change subscription callback (ABI 0.4). Registered with lumen_signal_watch; fires once per tick in which the watched global signal’s committed value changed (plus once on the first tick the value is observed after the watch is registered).

Unions

LumenValueData

Payload union for LumenValue. Read the field matching LumenValue::kind.