Struct ModuleInstance 

pub struct ModuleInstance<S: State> { /* private fields */ }

A running module instance with live state.

Created from a ModuleDefinition when the module is mounted. Wraps a hypen_engine::Engine and manages state synchronization.

Implementations

impl<S: State> ModuleInstance<S>

pub fn new( definition: Arc<ModuleDefinition<S>>, global_context: Option<Arc<GlobalContext>>, ) -> Result<Self>

Create a new module instance from a definition.

pub fn new_with_components( definition: Arc<ModuleDefinition<S>>, global_context: Option<Arc<GlobalContext>>, components: &ComponentRegistry, ) -> Result<Self>

Create a new module instance with a component registry for resolving child components in the UI template.

This enables DSL like Column { Feed {} } where Feed is registered in the ComponentRegistry. Without a registry, the engine cannot resolve custom component references in the template.

Example

let mut registry = ComponentRegistry::new();
registry.register("Card", r#"Column { Text("Card") }"#, None);

let instance = ModuleInstance::new_with_components(
    Arc::new(def),
    Some(ctx),
    &registry,
).unwrap();

pub fn mount(&self)

Mount the module: fire the initial render, then run on_created (sync only).

The initial render is deferred from construction to mount() so callers can wire on_patches(cb) in between and capture the initial Create batch. Subsequent mount() calls are no-ops; the pending IR slot is consumed on the first call.

Async-only lifecycle handlers are silently skipped here — call mount_async to invoke them.

pub fn activate(&self)

Fire on_activated (sync only). Called by [ManagedRouter] every time the module gains the active route slot — including persist cache restores. Independent of mount; does not flip mounted.

pub fn deactivate(&self)

Fire on_deactivated (sync only). Paired with activate; fires before on_destroyed or before the persist-cache write.

pub fn unmount(&self)

Unmount the module (triggers on_destroyed if it was registered as sync).

Async-only lifecycle handlers are silently skipped here — call unmount_async to invoke them.

pub fn dispatch_action( &self, name: impl Into<String>, payload: Option<Value>, ) -> Result<()>

Dispatch an action by name with an optional payload.

Only sync handlers run here. Actions registered as async-only return ActionNotFound — call dispatch_action_async for async handlers.

The dispatch routes through engine.dispatch_action(...), which fires the per-action closure registered in register_action_handlers_with_engine during construction. That closure runs the typed handler against the per-instance state. After dispatch returns, this method diffs the state against its pre-handler snapshot and pushes any changed paths to the engine via engine.update_state(None, patch).

pub fn get_state(&self) -> S

Get a clone of the current state.

pub fn get_state_json(&self) -> Result<Value>

Get the current state as JSON.

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

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

Set the render callback for receiving patches.

pub fn is_mounted(&self) -> bool

Check if the module is currently mounted.

pub fn name(&self) -> &str

Name of this module.

Trait Implementations

impl<S: State> ManagedModule for ModuleInstance<S>

fn name(&self) -> &str

fn mount(&self)

fn activate(&self)

fn deactivate(&self)

fn destroy(&self)

fn is_persistent(&self) -> bool

Whether this module’s definition opted into persistence. Defaults to false — match the TS / Swift contract where persistence is opt-in via .persist().