Struct ScriptLifecycle 

pub struct ScriptLifecycle { /* private fields */ }

Implementations

impl ScriptLifecycle

pub fn new( compiled: CompiledUi, runtime: Rc<RefCell<UiRuntimeState>>, root_path: ComponentInstancePath, window: Option<String>, events: BTreeMap<String, EventSchema>, state_schema: &ComponentStateSchema, ) -> Result<Self, LifecycleError>

Create an application lifecycle and mount its root component state.

Errors

Returns LifecycleError when runtime state is already borrowed or the root state schema cannot mount.

pub const fn state(&self) -> LifecycleState

pub fn root(&self) -> Option<&UiNode>

pub const fn retained(&self) -> &RetainedUiTree

pub const fn semantics(&self) -> &CommittedSemanticFrame

pub fn generation(&self) -> ScriptGeneration

pub fn runtime(&self) -> Rc<RefCell<UiRuntimeState>>

pub fn with_view_id(self, view: impl Into<String>) -> Self

pub fn initialize( &mut self, engine: &RuntimeEngine, ) -> Result<(), LifecycleError>

Run optional init(ctx) exactly once.

Errors

Returns LifecycleError::InvalidTransition outside Created, or a script evaluation error.

pub fn validate_initial_view_without_init( &mut self, engine: &mut RuntimeEngine, ) -> Result<&UiNode, LifecycleError>

Validate the initial view(ctx) without executing init(ctx).

This entry point is for static tooling that has no Host capability implementations. It validates the rendered tree but deliberately does not claim that Host-dependent initialization succeeded.

Errors

Returns the same render, reconciliation, and resource errors as Self::render.

pub fn render( &mut self, engine: &mut RuntimeEngine, ) -> Result<&UiNode, LifecycleError>

Evaluate required view(ctx) and activate its generation on success.

Errors

Returns LifecycleError::InvalidTransition before initialization or after disposal, or a script evaluation error.

pub fn render_dirty( &mut self, engine: &mut RuntimeEngine, ) -> Result<bool, LifecycleError>

Rerender only the topmost dirty formal component subtrees.

Falls back to a complete root render when the root itself is dirty or a component has no active invocation recipe.

Errors

Returns component invocation, script evaluation, reconciliation, or runtime-state rollback errors.

pub fn realize_virtual_requests( &mut self, engine: &mut RuntimeEngine, ) -> Result<bool, LifecycleError>

Realize requested data-backed virtual items outside GPUI layout/paint.

Errors

Returns renderer, retained reconciliation, effect, or rollback errors.

pub fn dispose( &mut self, engine: &mut RuntimeEngine, ) -> Result<(), LifecycleError>

Run optional dispose(ctx) once and make the lifecycle terminal.

Errors

Returns LifecycleError::InvalidTransition before initialization or after disposal, or a script evaluation error.

pub fn suspend( &mut self, engine: &mut RuntimeEngine, ) -> Result<bool, LifecycleError>

Quiesce one retained view without discarding its tree, state, native entities, measurements, or current script generation.

Errors

Returns lifecycle, callback, cleanup, or rollback errors. Repeated suspension is an idempotent no-op.

pub fn resume( &mut self, engine: &mut RuntimeEngine, ) -> Result<bool, LifecycleError>

Resume a retained view transactionally against current Host data.

The optional resume(ctx, elapsed_ms) hook runs before one full render; effect declarations then restart with fresh activation identities.

Errors

Returns lifecycle, callback, render, reconciliation, or rollback errors.

pub fn invoke_callback( &self, engine: &RuntimeEngine, callback: &ScriptCallback, payload: UiValue, ) -> Result<Dynamic, LifecycleError>

Invoke a generation-bound event callback with (ctx, payload).

Errors

Returns stale callback or Rhai evaluation errors.

pub fn invoke_callback_transactional( &self, engine: &RuntimeEngine, callback: &ScriptCallback, payload: UiValue, ) -> Result<Dynamic, LifecycleError>

Invoke a foreground callback and roll back runtime UI state if it fails. External capability side effects are outside this transaction.

Errors

Returns callback or runtime borrow errors.

pub fn invoke_async_delivery( &self, engine: &RuntimeEngine, delivery: AsyncDelivery, ) -> Result<Dynamic, LifecycleError>

Invoke an async delivery in its owning component scope.

Errors

Returns stale callback or Rhai evaluation errors.

pub fn invoke_async_delivery_transactional( &self, engine: &RuntimeEngine, delivery: AsyncDelivery, ) -> Result<Dynamic, LifecycleError>

Deliver async work with the same UI-state rollback as foreground events.

Errors

Returns callback or runtime borrow errors.

pub fn invoke_component_event_transactional( &self, engine: &RuntimeEngine, pending: PendingEvent, ) -> Result<Option<Dynamic>, LifecycleError>

Deliver one declared component event to its rendered caller callback. Missing optional listeners are treated as intentionally unobserved.

Errors

Returns callback or runtime borrow errors.

pub fn reload( &mut self, engine: &mut RuntimeEngine, candidate: CompiledUi, state_schema: &ComponentStateSchema, ) -> Result<&UiNode, LifecycleError>

Transactionally run candidate init(ctx) and view(ctx) during hot reload.

Component/store state and the last-good AST/root are preserved when either candidate lifecycle stage fails.

Errors

Returns runtime or borrow errors from the candidate generation.

pub fn resume_reload( &mut self, engine: &mut RuntimeEngine, candidate: CompiledUi, state_schema: &ComponentStateSchema, ) -> Result<&UiNode, LifecycleError>

Resume a suspended retained view into a newer compiled generation.

Candidate initialization, the optional resume hook, reconciliation, and effect activation form one rollback-safe transaction. Async deliveries from the replaced generation must be discarded by the host before entering this transaction.

Errors

Returns lifecycle, callback, render, reconciliation, or rollback errors.

pub fn start( &mut self, engine: &mut RuntimeEngine, ) -> Result<&UiNode, LifecycleError>

Run initialization followed by the first render.

Errors

Returns lifecycle or script errors from either stage.

pub fn window_id(&self) -> Option<&str>

pub fn view_id(&self) -> Option<&str>

pub fn root_path(&self) -> &ComponentInstancePath

pub fn compiled(&self) -> CompiledUi