Struct Engine 

pub struct Engine { /* private fields */ }

The main Hypen engine that orchestrates reactive UI rendering.

Architecture: Module-Scoped State Binding

Each Engine instance resolves ${state.xxx} bindings against one active module. This is a deliberate scoping decision — not a limitation. Each rendering scope owns its own state, and multi-module applications compose upward by nesting module instances under a parent (similar to Compose’s ViewModel scoping).

Multi-module Applications

Multi-module apps (e.g., AppState + StatsScreen) work as follows:

1. TypeScript SDK layer manages multiple HypenModuleInstance objects, each with its own Proxy-based state tracking.

2. Cross-module communication uses HypenGlobalContext:

   // In StatsScreen's action handler:
   const app = context.getModule<AppState>("app");
   app.setState({ showStats: true });

3. State binding scope: Each module’s template binds to its own state. Cross-module data flows through explicit props, callbacks, or action dispatching — keeping each module’s reactive graph self-contained:

   // StatsScreen receives app data via props, not state binding
   StatsView(data: @props.appStats)

Design Rationale

Scoping ${state.xxx} to a single module per rendering context keeps the reactive dependency graph simple and predictable. Rather than allowing ambient state access across modules (which creates implicit coupling), data flows explicitly through props, actions, and the global context. This makes each module independently testable and avoids the “state lives everywhere” problem.

Implementations

impl Engine

pub fn new() -> Self

pub fn register_component(&mut self, component: Component)

Register a custom component

pub fn set_component_resolver<F>(&mut self, resolver: F)

where F: Fn(&str, Option<&str>) -> Option<ResolvedComponent> + Send + Sync + 'static,

Set the component resolver for dynamic component loading The resolver receives (component_name, context_path) and should return ResolvedComponent { source, path } or None

pub fn set_module(&mut self, module: ModuleInstance)

Set the module instance

pub fn set_render_callback<F>(&mut self, callback: F)

where F: Fn(&[Patch]) + Send + Sync + 'static,

Set the render callback

pub fn on_action<F>(&mut self, action_name: impl Into<String>, handler: F)

where F: Fn(&Action) + Send + Sync + 'static,

Register an action handler

pub fn render(&mut self, element: &Element)

Render an element tree (initial render or full re-render).

This accepts a flat Element. For sources that use ForEach, When, or If, prefer [render_ir_node] which preserves first-class control flow.

pub fn render_ir_node(&mut self, ir_node: &IRNode)

Render an IRNode tree (initial render or full re-render).

Unlike [render], this accepts an IRNode (from ast_to_ir_node()), which preserves ForEach, When, and If as first-class control-flow nodes. This is the same path used by the WASM engine.

pub fn notify_state_change(&mut self, change: &StateChange)

Handle a state change notification from the module host The host keeps the actual state - we just need to know what changed

pub fn update_state(&mut self, state_patch: Value)

Convenience method for backward compatibility / JSON patches

pub fn dispatch_action(&mut self, action: Action) -> Result<(), EngineError>

Dispatch an action

pub fn revision(&self) -> u64

Get the current revision number

pub fn component_registry(&self) -> &ComponentRegistry

Get access to the component registry

pub fn component_registry_mut(&mut self) -> &mut ComponentRegistry

Get mutable access to the component registry

pub fn resources(&self) -> &ResourceCache

Get access to the resource cache

pub fn resources_mut(&mut self) -> &mut ResourceCache

Get mutable access to the resource cache

pub fn set_context(&mut self, name: &str, data: Value)

Set (or replace) a named data source context.

Registers the provider in the dependency graph (if not already known), stores the data, and re-renders every node bound to $name.*. This is the single entry point for all data source writes — sparse merging (if needed) should happen at the SDK layer before calling this method with the merged object.

Example

engine.set_context("spacetime", json!({
    "message": [{ "id": 1, "text": "Hello" }],
    "user": [{ "id": 1, "name": "Alice" }]
}));

pub fn remove_context(&mut self, name: &str)

Remove a data source context entirely.

Drops the provider’s state and re-renders bound nodes (they resolve to null).

pub fn data_sources(&self) -> &IndexMap<String, Value>

Get read access to the data sources map.

Trait Implementations

impl Default for Engine

fn default() -> Self

Returns the “default value” for a type.