Skip to main content

gpui_rhai/
lifecycle.rs

1use std::cell::RefCell;
2use std::collections::{BTreeMap, BTreeSet};
3use std::rc::Rc;
4
5use crate::state::topmost_paths;
6use rhai::Dynamic;
7use thiserror::Error;
8
9use crate::{
10    AsyncDelivery, AsyncScope, CompiledUi, ComponentInstancePath, ComponentStateSchema,
11    EventSchema, ExecutionPhase, MotionError, RuntimeEngine, RuntimeError, ScriptCallback,
12    ScriptGeneration, StateError, UiContext, UiNode, UiRuntimeState, UiValue,
13};
14
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub enum LifecycleState {
17    Created,
18    Initialized,
19    Running,
20    Suspended,
21    Disposed,
22}
23
24pub struct ScriptLifecycle {
25    compiled: CompiledUi,
26    runtime: Rc<RefCell<UiRuntimeState>>,
27    root_path: ComponentInstancePath,
28    window: Option<String>,
29    view: Option<String>,
30    events: BTreeMap<String, EventSchema>,
31    state: LifecycleState,
32    root: Option<Rc<UiNode>>,
33    retained: crate::RetainedUiTree,
34    semantics: crate::CommittedSemanticFrame,
35    suspended_at: Option<std::time::Instant>,
36    /// Advances whenever a new retained tree is committed (or restored).
37    revision: u64,
38    commit_statistics: CommitStatistics,
39}
40
41#[derive(Clone)]
42pub(crate) struct ScriptLifecycleCheckpoint {
43    compiled: CompiledUi,
44    state: LifecycleState,
45    root: Option<Rc<UiNode>>,
46    retained: crate::RetainedUiTree,
47    semantics: crate::CommittedSemanticFrame,
48    suspended_at: Option<std::time::Instant>,
49}
50
51/// Commits and the time spent in each of their phases, summed since the last
52/// [`ScriptLifecycle::take_commit_statistics`].
53#[derive(Clone, Debug, Default, PartialEq, Eq)]
54pub(crate) struct CommitStatistics {
55    pub commits: u64,
56    /// Phases in the order they first ran.
57    pub phases: Vec<(&'static str, std::time::Duration)>,
58}
59
60impl CommitStatistics {
61    fn add(&mut self, phase: &'static str, elapsed: std::time::Duration) {
62        if let Some((_, total)) = self.phases.iter_mut().find(|(name, _)| *name == phase) {
63            *total += elapsed;
64        } else {
65            self.phases.push((phase, elapsed));
66        }
67    }
68
69    pub(crate) fn merge(&mut self, other: Self) {
70        self.commits += other.commits;
71        for (phase, elapsed) in other.phases {
72            self.add(phase, elapsed);
73        }
74    }
75}
76
77/// Laps one commit's phases; folded into the lifecycle's statistics when the
78/// commit ends, whether it succeeded or not.
79struct PhaseClock {
80    last: std::time::Instant,
81    laps: CommitStatistics,
82}
83
84impl PhaseClock {
85    fn start() -> Self {
86        Self {
87            last: std::time::Instant::now(),
88            laps: CommitStatistics::default(),
89        }
90    }
91
92    fn lap(&mut self, phase: &'static str) {
93        let now = std::time::Instant::now();
94        self.laps.add(phase, now - self.last);
95        self.last = now;
96    }
97}
98
99#[derive(Default)]
100struct RetainedDeclarations {
101    effects: BTreeMap<crate::EffectId, crate::EffectDescriptor>,
102    timers: BTreeMap<crate::TimerId, crate::TimerDescriptor>,
103    signals: BTreeMap<crate::SignalId, crate::signal::SignalDescriptor>,
104    element_refs: BTreeMap<crate::ElementRefId, crate::NodeId>,
105}
106
107impl ScriptLifecycle {
108    pub(crate) fn execution_checkpoint(&self) -> ScriptLifecycleCheckpoint {
109        ScriptLifecycleCheckpoint {
110            compiled: self.compiled.clone(),
111            state: self.state,
112            root: self.root.clone(),
113            retained: self.retained.clone(),
114            semantics: self.semantics.clone(),
115            suspended_at: self.suspended_at,
116        }
117    }
118
119    pub(crate) fn restore_execution_checkpoint(&mut self, checkpoint: ScriptLifecycleCheckpoint) {
120        self.compiled = checkpoint.compiled;
121        self.state = checkpoint.state;
122        self.root = checkpoint.root;
123        self.retained = checkpoint.retained;
124        self.semantics = checkpoint.semantics;
125        // Two steps: a revision one past another is always the reconcile of
126        // the tree before it, which cache islands rely on, and a restore is
127        // not.
128        self.revision = self.revision.wrapping_add(2);
129        self.suspended_at = checkpoint.suspended_at;
130    }
131
132    /// Create an application lifecycle and mount its root component state.
133    ///
134    /// # Errors
135    ///
136    /// Returns [`LifecycleError`] when runtime state is already borrowed or the
137    /// root state schema cannot mount.
138    pub fn new(
139        compiled: CompiledUi,
140        runtime: Rc<RefCell<UiRuntimeState>>,
141        root_path: ComponentInstancePath,
142        window: Option<String>,
143        events: BTreeMap<String, EventSchema>,
144        state_schema: &ComponentStateSchema,
145    ) -> Result<Self, LifecycleError> {
146        {
147            let mut runtime_state = runtime
148                .try_borrow_mut()
149                .map_err(|_| LifecycleError::Borrowed)?;
150            let mut transaction = runtime_state
151                .component_state
152                .begin_render_scope(root_path.clone());
153            transaction.mount(root_path.clone(), state_schema)?;
154            runtime_state.component_state.commit_render(transaction);
155            runtime_state.ensure_component_incarnation(&root_path);
156            runtime_state
157                .effect_cascades
158                .register_generation(&root_path, compiled.generation());
159        }
160        Ok(Self {
161            compiled,
162            runtime,
163            root_path,
164            window,
165            view: None,
166            events,
167            state: LifecycleState::Created,
168            root: None,
169            retained: crate::RetainedUiTree::new(),
170            semantics: crate::CommittedSemanticFrame::default(),
171            suspended_at: None,
172            revision: 0,
173            commit_statistics: CommitStatistics::default(),
174        })
175    }
176
177    /// Commits since the last call and the time each phase took.
178    pub(crate) fn take_commit_statistics(&mut self) -> CommitStatistics {
179        std::mem::take(&mut self.commit_statistics)
180    }
181
182    /// The revision of the committed retained tree; it advances on every
183    /// commit, so observers can skip work when nothing new was rendered.
184    #[must_use]
185    pub const fn revision(&self) -> u64 {
186        self.revision
187    }
188
189    #[must_use]
190    pub const fn state(&self) -> LifecycleState {
191        self.state
192    }
193
194    #[must_use]
195    pub fn root(&self) -> Option<&UiNode> {
196        self.root.as_deref()
197    }
198
199    #[must_use]
200    pub const fn retained(&self) -> &crate::RetainedUiTree {
201        &self.retained
202    }
203
204    #[must_use]
205    pub const fn semantics(&self) -> &crate::CommittedSemanticFrame {
206        &self.semantics
207    }
208
209    #[must_use]
210    pub fn generation(&self) -> ScriptGeneration {
211        self.compiled.generation()
212    }
213
214    #[must_use]
215    pub fn runtime(&self) -> Rc<RefCell<UiRuntimeState>> {
216        Rc::clone(&self.runtime)
217    }
218
219    #[must_use]
220    pub fn with_view_id(mut self, view: impl Into<String>) -> Self {
221        let view = view.into();
222        if let Ok(mut runtime) = self.runtime.try_borrow_mut() {
223            runtime.ensure_presentation(&view);
224        }
225        self.view = Some(view);
226        self
227    }
228
229    /// Run optional `init(ctx)` exactly once.
230    ///
231    /// # Errors
232    ///
233    /// Returns [`LifecycleError::InvalidTransition`] outside `Created`, or a
234    /// script evaluation error.
235    pub fn initialize(&mut self, engine: &RuntimeEngine) -> Result<(), LifecycleError> {
236        self.require_state(LifecycleState::Created)?;
237        let snapshot = self.begin_runtime_transaction()?;
238        let context = self.context(ExecutionPhase::Init);
239        match engine.call_optional_lifecycle(&self.compiled, "init", context) {
240            Ok(_) => {
241                self.state = LifecycleState::Initialized;
242                self.commit_runtime_transaction()
243            }
244            Err(error) => {
245                self.runtime
246                    .try_borrow_mut()
247                    .map_err(|_| LifecycleError::Borrowed)?
248                    .restore(snapshot)?;
249                Err(error.into())
250            }
251        }
252    }
253
254    /// Validate the initial `view(ctx)` without executing `init(ctx)`.
255    ///
256    /// This entry point is for static tooling that has no Host capability
257    /// implementations. It validates the rendered tree but deliberately does
258    /// not claim that Host-dependent initialization succeeded.
259    ///
260    /// # Errors
261    ///
262    /// Returns the same render, reconciliation, and resource errors as
263    /// [`Self::render`].
264    pub fn validate_initial_view_without_init(
265        &mut self,
266        engine: &mut RuntimeEngine,
267    ) -> Result<&UiNode, LifecycleError> {
268        self.require_state(LifecycleState::Created)?;
269        self.state = LifecycleState::Initialized;
270        self.render(engine)
271    }
272
273    /// Evaluate required `view(ctx)` and activate its generation on success.
274    ///
275    /// # Errors
276    ///
277    /// Returns [`LifecycleError::InvalidTransition`] before initialization or
278    /// after disposal, or a script evaluation error.
279    pub fn render(&mut self, engine: &mut RuntimeEngine) -> Result<&UiNode, LifecycleError> {
280        self.render_impl(engine, None)
281    }
282
283    fn render_impl(
284        &mut self,
285        engine: &mut RuntimeEngine,
286        reuse_dirty: Option<&BTreeSet<ComponentInstancePath>>,
287    ) -> Result<&UiNode, LifecycleError> {
288        if !matches!(
289            self.state,
290            LifecycleState::Initialized | LifecycleState::Running
291        ) {
292            return Err(LifecycleError::InvalidTransition {
293                from: self.state,
294                operation: "render",
295            });
296        }
297        let mut clock = PhaseClock::start();
298        let runtime_snapshot = self.begin_runtime_transaction()?;
299        let engine_checkpoint = engine.execution_checkpoint();
300        let previous_root = reuse_dirty.and_then(|_| self.root.clone());
301        let result = (|| {
302            let context = self.context(ExecutionPhase::Render);
303            let mut root = match (previous_root.as_ref(), reuse_dirty) {
304                (Some(previous_root), Some(dirty)) => engine.render_with_context_staged_reusing(
305                    &self.compiled,
306                    context,
307                    Rc::clone(previous_root),
308                    dirty,
309                )?,
310                _ => engine.render_with_context_staged(&self.compiled, context)?,
311            };
312            clock.lap("render");
313            let mut retained = self.retained.clone();
314            clock.lap("clone");
315            let semantics = self.commit_phases(
316                engine,
317                &runtime_snapshot,
318                &mut retained,
319                &mut root,
320                &mut clock,
321            )?;
322            Ok((root, retained, semantics))
323        })();
324        self.commit_statistics.merge(clock.laps);
325        match result {
326            Ok((root, retained, semantics)) => {
327                self.commit_or_roll_back(engine, runtime_snapshot, engine_checkpoint)?;
328                self.trace_reconcile("full", retained.last_report());
329                self.retained = retained;
330                self.semantics = semantics;
331                self.revision = self.revision.wrapping_add(1);
332                self.state = LifecycleState::Running;
333                self.root = Some(Rc::new(root));
334                self.root.as_deref().ok_or(LifecycleError::MissingRoot)
335            }
336            Err(error) => {
337                self.runtime
338                    .try_borrow_mut()
339                    .map_err(|_| LifecycleError::Borrowed)?
340                    .restore(runtime_snapshot)?;
341                engine.restore_execution_checkpoint(engine_checkpoint);
342                Err(error)
343            }
344        }
345    }
346
347    /// Rerender only the topmost dirty formal component subtrees.
348    ///
349    /// Falls back to a complete root render when the root itself is dirty or a
350    /// component has no active invocation recipe.
351    ///
352    /// # Errors
353    ///
354    /// Returns component invocation, script evaluation, reconciliation, or
355    /// runtime-state rollback errors.
356    pub fn render_dirty(&mut self, engine: &mut RuntimeEngine) -> Result<bool, LifecycleError> {
357        if !self
358            .runtime
359            .try_borrow()
360            .map_err(|_| LifecycleError::Borrowed)?
361            .has_window_dirty(&self.root_path)
362        {
363            return Ok(false);
364        }
365        let runtime_snapshot = self.begin_runtime_transaction()?;
366        let engine_checkpoint = engine.execution_checkpoint();
367        let dirty = self
368            .runtime
369            .try_borrow_mut()
370            .map_err(|_| LifecycleError::Borrowed)?
371            .take_window_dirty_components(&self.root_path);
372        debug_assert!(!dirty.is_empty());
373        let topmost = topmost_paths(&dirty);
374        if topmost.iter().any(|path| path == &self.root_path)
375            || topmost.iter().any(|path| {
376                engine
377                    .component_invocations()
378                    .all(|recipe| recipe.path() != path)
379            })
380        {
381            return self.render_dirty_full(engine, &dirty, runtime_snapshot, engine_checkpoint);
382        }
383
384        let mut root = self
385            .root
386            .as_deref()
387            .cloned()
388            .ok_or(LifecycleError::MissingRoot)?;
389        let active = engine
390            .component_invocations()
391            .map(|recipe| recipe.path().clone())
392            .collect::<BTreeSet<_>>();
393        let Some(topmost) = replaceable_component_paths(&root, &self.root_path, topmost, &active)
394        else {
395            return self.render_dirty_full(engine, &dirty, runtime_snapshot, engine_checkpoint);
396        };
397        engine.begin_execution_session();
398        let mut clock = PhaseClock::start();
399        let mut retained = self.retained.clone();
400        clock.lap("clone");
401        let result = (|| {
402            for path in topmost {
403                let subtree = engine.rerender_component(&path, &root, &dirty)?;
404                if !root.replace_component_subtree(&path, subtree) {
405                    return Err(LifecycleError::MissingComponentSubtree(path));
406                }
407            }
408            clock.lap("render");
409            self.commit_phases(
410                engine,
411                &runtime_snapshot,
412                &mut retained,
413                &mut root,
414                &mut clock,
415            )
416        })();
417        self.commit_statistics.merge(clock.laps);
418        match result {
419            Ok(semantics) => {
420                self.commit_or_roll_back(engine, runtime_snapshot, engine_checkpoint)?;
421                self.trace_reconcile("incremental", retained.last_report());
422                self.root = Some(Rc::new(root));
423                self.retained = retained;
424                self.semantics = semantics;
425                self.revision = self.revision.wrapping_add(1);
426                self.state = LifecycleState::Running;
427                Ok(true)
428            }
429            Err(error) => {
430                self.runtime
431                    .try_borrow_mut()
432                    .map_err(|_| LifecycleError::Borrowed)?
433                    .restore(runtime_snapshot)?;
434                engine.restore_execution_checkpoint(engine_checkpoint);
435                Err(error)
436            }
437        }
438    }
439
440    fn render_dirty_full(
441        &mut self,
442        engine: &mut RuntimeEngine,
443        dirty: &BTreeSet<ComponentInstancePath>,
444        runtime_snapshot: crate::UiStateSnapshot,
445        engine_checkpoint: crate::engine::RuntimeEngineCheckpoint,
446    ) -> Result<bool, LifecycleError> {
447        match self.render_impl(engine, Some(dirty)) {
448            Ok(_) => {
449                self.commit_runtime_transaction()?;
450                Ok(true)
451            }
452            Err(error) => {
453                self.runtime
454                    .try_borrow_mut()
455                    .map_err(|_| LifecycleError::Borrowed)?
456                    .restore(runtime_snapshot)?;
457                engine.restore_execution_checkpoint(engine_checkpoint);
458                Err(error)
459            }
460        }
461    }
462
463    /// Realize requested data-backed virtual items outside GPUI layout/paint.
464    ///
465    /// # Errors
466    ///
467    /// Returns renderer, retained reconciliation, effect, or rollback errors.
468    #[allow(clippy::too_many_lines)]
469    pub fn realize_virtual_requests(
470        &mut self,
471        engine: &mut RuntimeEngine,
472    ) -> Result<bool, LifecycleError> {
473        if !self
474            .runtime
475            .try_borrow()
476            .map_err(|_| LifecycleError::Borrowed)?
477            .virtual_requests
478            .has_scope(&self.root_path)
479        {
480            return Ok(false);
481        }
482        let runtime_snapshot = self.begin_runtime_transaction()?;
483        let engine_checkpoint = engine.execution_checkpoint();
484        let requests = self
485            .runtime
486            .try_borrow()
487            .map_err(|_| LifecycleError::Borrowed)?
488            .virtual_requests
489            .drain();
490        let mut selected = Vec::new();
491        for (id, indices) in requests {
492            if id.component.is_within(&self.root_path) {
493                selected.push((id, indices));
494            } else {
495                self.runtime
496                    .try_borrow()
497                    .map_err(|_| LifecycleError::Borrowed)?
498                    .virtual_requests
499                    .request(id, indices);
500            }
501        }
502        if selected.is_empty() {
503            return Ok(false);
504        }
505        engine.begin_execution_session();
506        let mut root = self
507            .root
508            .as_deref()
509            .cloned()
510            .ok_or(LifecycleError::MissingRoot)?;
511        let mut clock = PhaseClock::start();
512        let mut retained = self.retained.clone();
513        clock.lap("clone");
514        let result = (|| {
515            let mut changed = false;
516            for (id, indices) in selected {
517                // Parent targets are processed first. A child that existed at
518                // batch start may legitimately be removed by a parent prune.
519                if root.virtual_collection_spec(&id).is_none()
520                    && self
521                        .root
522                        .as_deref()
523                        .is_some_and(|root| root.virtual_collection_spec(&id).is_some())
524                {
525                    continue;
526                }
527                let mut items = root
528                    .virtual_collection_items(&id)
529                    .cloned()
530                    .ok_or_else(|| LifecycleError::MissingVirtualCollection(id.clone()))?;
531                let previous_indices = items.keys().copied().collect::<BTreeSet<_>>();
532                if previous_indices == indices {
533                    continue;
534                }
535                let inherited_motion_group = root.virtual_collection_spec(&id).and_then(|spec| {
536                    spec.inherited_motion_group
537                        .clone()
538                        .map(|group| (group, spec.inherited_motion_scope.clone()))
539                });
540                clock.lap("lookup");
541                let previous = items;
542                items = engine.realize_virtual_collection(&id, &indices, &previous)?;
543                clock.lap("realize");
544                if let Some((group, scope)) = inherited_motion_group {
545                    // An item kept from before has its group already; applying
546                    // it again would copy the item and add the mutation twice.
547                    for (index, node) in &mut items {
548                        if !previous.get(index).is_some_and(|kept| kept.ptr_eq(node)) {
549                            crate::node::apply_motion_group(node, &group, scope.as_deref());
550                        }
551                    }
552                }
553                if !root.replace_virtual_collection_items(&id, items.clone()) {
554                    return Err(LifecycleError::MissingVirtualCollection(id));
555                }
556                engine.update_virtual_collection_snapshot(&id, &items);
557                changed = true;
558            }
559            clock.lap("replace");
560            if !changed {
561                return Ok((false, self.semantics.clone()));
562            }
563            let semantics = self.commit_phases(
564                engine,
565                &runtime_snapshot,
566                &mut retained,
567                &mut root,
568                &mut clock,
569            )?;
570            Ok((true, semantics))
571        })();
572        self.commit_statistics.merge(clock.laps);
573        match result {
574            Ok((changed, semantics)) => {
575                self.commit_or_roll_back(engine, runtime_snapshot, engine_checkpoint)?;
576                if changed {
577                    self.trace_reconcile("virtual", retained.last_report());
578                    self.root = Some(Rc::new(root));
579                    self.retained = retained;
580                    self.semantics = semantics;
581                    self.revision = self.revision.wrapping_add(1);
582                }
583                Ok(changed)
584            }
585            Err(error) => {
586                self.runtime
587                    .try_borrow_mut()
588                    .map_err(|_| LifecycleError::Borrowed)?
589                    .restore(runtime_snapshot)?;
590                engine.restore_execution_checkpoint(engine_checkpoint);
591                Err(error)
592            }
593        }
594    }
595
596    /// The phases every commit runs over its candidate root, in order:
597    /// reconcile `retained` (the working copy that becomes the committed tree
598    /// on success) against `root`, where an error boundary that contains a
599    /// script mistake becomes its fallback, then budgets, motion, exit ghosts,
600    /// effects, geometry, signal bindings and the semantic frame.
601    fn commit_phases(
602        &self,
603        engine: &mut RuntimeEngine,
604        runtime_snapshot: &crate::UiStateSnapshot,
605        retained: &mut crate::RetainedUiTree,
606        root: &mut UiNode,
607        clock: &mut PhaseClock,
608    ) -> Result<crate::CommittedSemanticFrame, LifecycleError> {
609        clock.laps.commits += 1;
610        let motion_reconcile_report = retained.reconcile_contained(root)?;
611        clock.lap("reconcile");
612        self.validate_resource_budgets(engine, retained, root)?;
613        clock.lap("budgets");
614        self.reconcile_motion(root, retained, self.compiled.generation())?;
615        clock.lap("motion");
616        self.reconcile_exit_ghosts(&motion_reconcile_report)?;
617        clock.lap("ghosts");
618        self.reconcile_effects(
619            engine,
620            &self.compiled,
621            runtime_snapshot.component_state().clone(),
622            retained,
623            root,
624        )?;
625        clock.lap("effects");
626        self.retain_geometry_nodes(retained)?;
627        clock.lap("geometry");
628        // A tree whose nodes read no signal has none to validate.
629        if retained.summary().signals > 0 {
630            self.validate_signal_bindings(root)?;
631        }
632        clock.lap("signals");
633        let semantics = crate::CommittedSemanticFrame::from_retained(retained)?;
634        clock.lap("semantics");
635        Ok(semantics)
636    }
637
638    /// Run optional `dispose(ctx)` once and make the lifecycle terminal.
639    ///
640    /// # Errors
641    ///
642    /// Returns [`LifecycleError::InvalidTransition`] before initialization or
643    /// after disposal, or a script evaluation error.
644    pub fn dispose(&mut self, engine: &mut RuntimeEngine) -> Result<(), LifecycleError> {
645        if !matches!(
646            self.state,
647            LifecycleState::Initialized | LifecycleState::Running | LifecycleState::Suspended
648        ) {
649            return Err(LifecycleError::InvalidTransition {
650                from: self.state,
651                operation: "dispose",
652            });
653        }
654        let snapshot = self.begin_runtime_transaction()?;
655        self.restart_effect_cascade()?;
656        let result = (|| {
657            self.reconcile_effect_candidate(
658                engine,
659                &self.compiled,
660                RetainedDeclarations::default(),
661                None,
662            )?;
663            let context = self.context(ExecutionPhase::Dispose);
664            engine.call_optional_lifecycle(&self.compiled, "dispose", context)?;
665            Ok(())
666        })();
667        match result {
668            Ok(()) => {
669                self.state = LifecycleState::Disposed;
670                self.runtime
671                    .try_borrow()
672                    .map_err(|_| LifecycleError::Borrowed)?
673                    .virtual_requests
674                    .release_scope(&self.root_path);
675                self.commit_runtime_transaction()?;
676                Ok(())
677            }
678            Err(error) => {
679                self.runtime
680                    .try_borrow_mut()
681                    .map_err(|_| LifecycleError::Borrowed)?
682                    .restore(snapshot)?;
683                Err(error)
684            }
685        }
686    }
687
688    /// Quiesce one retained view without discarding its tree, state, native
689    /// entities, measurements, or current script generation.
690    ///
691    /// # Errors
692    ///
693    /// Returns lifecycle, callback, cleanup, or rollback errors. Repeated
694    /// suspension is an idempotent no-op.
695    pub fn suspend(&mut self, engine: &mut RuntimeEngine) -> Result<bool, LifecycleError> {
696        if self.state == LifecycleState::Suspended {
697            return Ok(false);
698        }
699        if self.state != LifecycleState::Running {
700            return Err(LifecycleError::InvalidTransition {
701                from: self.state,
702                operation: "suspend",
703            });
704        }
705        let snapshot = self.begin_runtime_transaction()?;
706        self.restart_effect_cascade()?;
707        let checkpoint = engine.execution_checkpoint();
708        let result = (|| {
709            engine.call_optional_lifecycle(
710                &self.compiled,
711                "suspend",
712                self.context(ExecutionPhase::Suspend),
713            )?;
714            self.stop_active_effects(engine)?;
715            let mut runtime = self
716                .runtime
717                .try_borrow_mut()
718                .map_err(|_| LifecycleError::Borrowed)?;
719            let now = runtime.clock.now();
720            runtime.timers.pause_component_scope(&self.root_path, now);
721            runtime
722                .motions
723                .suspend_node_scope(&self.motion_root_path(), now);
724            runtime.motion_values = runtime.motions.snapshot(now);
725            runtime
726                .pointer_capture_for(self.presentation_scope())
727                .clear();
728            Ok(now)
729        })();
730        match result {
731            Ok(now) => {
732                self.suspended_at = Some(now);
733                self.state = LifecycleState::Suspended;
734                self.commit_runtime_transaction()?;
735                Ok(true)
736            }
737            Err(error) => {
738                self.runtime
739                    .try_borrow_mut()
740                    .map_err(|_| LifecycleError::Borrowed)?
741                    .restore(snapshot)?;
742                engine.restore_execution_checkpoint(checkpoint);
743                Err(error)
744            }
745        }
746    }
747
748    /// Resume a retained view transactionally against current Host data.
749    ///
750    /// The optional `resume(ctx, elapsed_ms)` hook runs before one full render;
751    /// effect declarations then restart with fresh activation identities.
752    ///
753    /// # Errors
754    ///
755    /// Returns lifecycle, callback, render, reconciliation, or rollback errors.
756    pub fn resume(&mut self, engine: &mut RuntimeEngine) -> Result<bool, LifecycleError> {
757        if self.state == LifecycleState::Running {
758            return Ok(false);
759        }
760        if self.state != LifecycleState::Suspended {
761            return Err(LifecycleError::InvalidTransition {
762                from: self.state,
763                operation: "resume",
764            });
765        }
766        let snapshot = self.begin_runtime_transaction()?;
767        self.restart_effect_cascade()?;
768        let checkpoint = engine.execution_checkpoint();
769        let suspended_at = self
770            .suspended_at
771            .ok_or(LifecycleError::MissingSuspendTime)?;
772        let now = self
773            .runtime
774            .try_borrow()
775            .map_err(|_| LifecycleError::Borrowed)?
776            .clock
777            .now();
778        let elapsed = now.saturating_duration_since(suspended_at);
779        let result = (|| {
780            {
781                self.resume_runtime_mechanisms(now, elapsed)?;
782            }
783            engine.call_optional_lifecycle_with_value(
784                &self.compiled,
785                "resume",
786                self.context(ExecutionPhase::Resume),
787                UiValue::Integer(i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX)),
788            )?;
789            self.state = LifecycleState::Initialized;
790            self.render_impl(engine, None)?;
791            Ok(())
792        })();
793        match result {
794            Ok(()) => {
795                self.suspended_at = None;
796                self.state = LifecycleState::Running;
797                self.commit_runtime_transaction()?;
798                Ok(true)
799            }
800            Err(error) => {
801                self.state = LifecycleState::Suspended;
802                self.runtime
803                    .try_borrow_mut()
804                    .map_err(|_| LifecycleError::Borrowed)?
805                    .restore(snapshot)?;
806                engine.restore_execution_checkpoint(checkpoint);
807                Err(error)
808            }
809        }
810    }
811
812    fn stop_active_effects(&self, engine: &RuntimeEngine) -> Result<(), LifecycleError> {
813        let plan = self
814            .runtime
815            .try_borrow()
816            .map_err(|_| LifecycleError::Borrowed)?
817            .effects
818            .plan(&self.root_path, BTreeMap::new());
819        if plan.transition_count() > crate::effect::EFFECT_TRANSITION_CALLBACK_BUDGET {
820            return Err(LifecycleError::EffectBudget(plan.transition_count()));
821        }
822        for (descriptor, scope) in plan.cleanup_descriptors() {
823            self.invoke_effect_callback(
824                engine,
825                &self.compiled,
826                descriptor.cleanup(),
827                descriptor.dependencies().clone(),
828                scope,
829            )?;
830        }
831        let mut runtime = self
832            .runtime
833            .try_borrow_mut()
834            .map_err(|_| LifecycleError::Borrowed)?;
835        for (_, scope) in plan.cleanup_descriptors() {
836            runtime.cancel_async_scope(&scope)?;
837        }
838        runtime.effects.commit(plan);
839        Ok(())
840    }
841
842    /// Invoke a generation-bound event callback with `(ctx, payload)`.
843    ///
844    /// # Errors
845    ///
846    /// Returns stale callback or Rhai evaluation errors.
847    pub fn invoke_callback(
848        &self,
849        engine: &RuntimeEngine,
850        callback: &ScriptCallback,
851        payload: UiValue,
852    ) -> Result<Dynamic, LifecycleError> {
853        self.invoke_callback_with_event_target(engine, callback, payload, None)
854    }
855
856    pub(crate) fn invoke_callback_with_event_target(
857        &self,
858        engine: &RuntimeEngine,
859        callback: &ScriptCallback,
860        payload: UiValue,
861        event_target: Option<crate::GeometryBounds>,
862    ) -> Result<Dynamic, LifecycleError> {
863        self.validate_callback_owner(callback)?;
864        // Effect-generated semantic events retain their origin when delivered
865        // later. They are part of the same cascade, not new user operations.
866        {
867            let mut runtime = self
868                .runtime
869                .try_borrow_mut()
870                .map_err(|_| LifecycleError::Borrowed)?;
871            runtime.prune_pending_dispatch();
872            if runtime.invocation_origin() == &crate::InvocationOrigin::Effect {
873                let root = runtime
874                    .dispatch_owner
875                    .as_ref()
876                    .and_then(crate::SemanticDispatchOwner::cascade_root)
877                    .cloned()
878                    .unwrap_or_else(|| self.root_path.clone());
879                if runtime.effect_cascades.blocked(&root) {
880                    return Ok(Dynamic::UNIT);
881                }
882                if runtime.dispatch_owner.is_none() {
883                    runtime.effect_cascades.retain_unowned_dispatch(&root);
884                }
885                // Pure semantic recursion may never restart an effect. Every
886                // effect-origin callback shares the graph's transition budget.
887                runtime
888                    .effect_cascades
889                    .charge(&root, 1)
890                    .map_err(LifecycleError::EffectBudget)?;
891            } else {
892                runtime.effect_cascades.restart(&self.root_path);
893            }
894        }
895        let root_context = self.context(ExecutionPhase::Event);
896        let context = callback
897            .component()
898            .map_or(root_context.clone(), |component| {
899                root_context.for_component(component.clone(), callback.events().clone())
900            })
901            .with_native_context(callback.native_context().cloned())
902            .with_event_target(event_target);
903        Ok(engine.invoke_callback(&self.compiled, callback, (context, payload.into_dynamic()))?)
904    }
905
906    /// Invoke a foreground callback and roll back runtime UI state if it fails.
907    /// External capability side effects are outside this transaction.
908    ///
909    /// # Errors
910    ///
911    /// Returns callback or runtime borrow errors.
912    pub fn invoke_callback_transactional(
913        &self,
914        engine: &RuntimeEngine,
915        callback: &ScriptCallback,
916        payload: UiValue,
917    ) -> Result<Dynamic, LifecycleError> {
918        let snapshot = self.begin_runtime_transaction()?;
919        match self.invoke_callback(engine, callback, payload) {
920            Ok(value) => {
921                self.commit_runtime_transaction()?;
922                Ok(value)
923            }
924            Err(error) => {
925                self.runtime
926                    .try_borrow_mut()
927                    .map_err(|_| LifecycleError::Borrowed)?
928                    .restore(snapshot)?;
929                Err(error)
930            }
931        }
932    }
933
934    /// Invoke an async delivery in its owning component scope.
935    ///
936    /// # Errors
937    ///
938    /// Returns stale callback or Rhai evaluation errors.
939    pub fn invoke_async_delivery(
940        &self,
941        engine: &RuntimeEngine,
942        delivery: AsyncDelivery,
943    ) -> Result<Dynamic, LifecycleError> {
944        if !self
945            .runtime
946            .try_borrow()
947            .map_err(|_| LifecycleError::Borrowed)?
948            .effects
949            .contains_scope(&delivery.scope)
950        {
951            return Ok(Dynamic::UNIT);
952        }
953        self.validate_callback_owner(&delivery.callback)?;
954        self.restart_effect_cascade()?;
955        let component = delivery
956            .callback
957            .component()
958            .cloned()
959            .or_else(|| delivery.scope.component().cloned())
960            .unwrap_or_else(|| self.root_path.clone());
961        let events = delivery.callback.events().clone();
962        let scope = delivery.scope.clone();
963        let origin = delivery.origin.clone();
964        let context = UiContext::new(
965            Rc::clone(&self.runtime),
966            component,
967            self.window.clone(),
968            ExecutionPhase::Event,
969            events,
970        )
971        .with_optional_view_id(self.view.clone())
972        .with_generation(self.compiled.generation())
973        .with_native_context(delivery.callback.native_context().cloned())
974        .with_async_scope(scope);
975        self.with_dispatch_owner(None, || {
976            self.with_origin(origin, || {
977                Ok(engine.invoke_callback(
978                    &self.compiled,
979                    &delivery.callback,
980                    (context, delivery.payload.into_dynamic()),
981                )?)
982            })
983        })
984    }
985
986    /// Run `invoke` with `origin` as the running invocation's origin, then
987    /// restore the previous one.
988    pub(crate) fn with_origin<T>(
989        &self,
990        origin: crate::InvocationOrigin,
991        invoke: impl FnOnce() -> Result<T, LifecycleError>,
992    ) -> Result<T, LifecycleError> {
993        let previous = self
994            .runtime
995            .try_borrow_mut()
996            .map_err(|_| LifecycleError::Borrowed)?
997            .replace_origin(origin);
998        let result = invoke();
999        self.runtime
1000            .try_borrow_mut()
1001            .map_err(|_| LifecycleError::Borrowed)?
1002            .replace_origin(previous);
1003        result
1004    }
1005
1006    /// Deliver async work with the same UI-state rollback as foreground events.
1007    ///
1008    /// # Errors
1009    ///
1010    /// Returns callback or runtime borrow errors.
1011    pub fn invoke_async_delivery_transactional(
1012        &self,
1013        engine: &RuntimeEngine,
1014        delivery: AsyncDelivery,
1015    ) -> Result<Dynamic, LifecycleError> {
1016        let snapshot = self.begin_runtime_transaction()?;
1017        match self.invoke_async_delivery(engine, delivery) {
1018            Ok(value) => {
1019                self.commit_runtime_transaction()?;
1020                Ok(value)
1021            }
1022            Err(error) => {
1023                self.runtime
1024                    .try_borrow_mut()
1025                    .map_err(|_| LifecycleError::Borrowed)?
1026                    .restore(snapshot)?;
1027                Err(error)
1028            }
1029        }
1030    }
1031
1032    /// Deliver one declared component event to its rendered caller callback.
1033    /// Missing optional listeners are treated as intentionally unobserved.
1034    ///
1035    /// # Errors
1036    ///
1037    /// Returns callback or runtime borrow errors.
1038    pub fn invoke_component_event_transactional(
1039        &self,
1040        engine: &RuntimeEngine,
1041        pending: crate::PendingEvent,
1042    ) -> Result<Option<Dynamic>, LifecycleError> {
1043        if !self
1044            .runtime
1045            .try_borrow()
1046            .map_err(|_| LifecycleError::Borrowed)?
1047            .dispatch_owner_active(pending.owner.as_ref())
1048        {
1049            return Ok(None);
1050        }
1051        let callback = self
1052            .runtime
1053            .try_borrow()
1054            .map_err(|_| LifecycleError::Borrowed)?
1055            .component_event_handler(&pending.target, &pending.event.name);
1056        callback
1057            .map(|callback| {
1058                self.with_dispatch_owner(pending.owner, || {
1059                    self.with_origin(pending.origin, || {
1060                        self.invoke_callback_transactional(engine, &callback, pending.event.payload)
1061                    })
1062                })
1063            })
1064            .transpose()
1065    }
1066
1067    /// Deliver a queued semantic action with its original origin and opaque
1068    /// provenance. Stale generation, mount, activation or rejected derivations
1069    /// are ignored, including clones retained by an external Host.
1070    ///
1071    /// # Errors
1072    /// Returns callback, effect-budget or transaction errors.
1073    pub fn invoke_action_transactional(
1074        &self,
1075        engine: &RuntimeEngine,
1076        pending: crate::ActionInvocation,
1077    ) -> Result<Dynamic, LifecycleError> {
1078        if pending.callback.generation() != self.generation()
1079            || !self
1080                .runtime
1081                .try_borrow()
1082                .map_err(|_| LifecycleError::Borrowed)?
1083                .dispatch_owner_active(pending.owner.as_ref())
1084        {
1085            return Ok(Dynamic::UNIT);
1086        }
1087        self.with_dispatch_owner(pending.owner, || {
1088            self.with_origin(pending.origin, || {
1089                self.invoke_callback_transactional(engine, &pending.callback, pending.payload)
1090            })
1091        })
1092    }
1093
1094    fn with_dispatch_owner<T>(
1095        &self,
1096        owner: Option<crate::SemanticDispatchOwner>,
1097        invoke: impl FnOnce() -> Result<T, LifecycleError>,
1098    ) -> Result<T, LifecycleError> {
1099        let previous = {
1100            let mut runtime = self
1101                .runtime
1102                .try_borrow_mut()
1103                .map_err(|_| LifecycleError::Borrowed)?;
1104            std::mem::replace(&mut runtime.dispatch_owner, owner)
1105        };
1106        let result = invoke();
1107        self.runtime
1108            .try_borrow_mut()
1109            .map_err(|_| LifecycleError::Borrowed)?
1110            .dispatch_owner = previous;
1111        result
1112    }
1113
1114    pub(crate) fn reject_semantic_dispatch_budget(
1115        &self,
1116        origin: &crate::InvocationOrigin,
1117        owner: Option<&crate::SemanticDispatchOwner>,
1118    ) -> Result<(), LifecycleError> {
1119        let mut runtime = self
1120            .runtime
1121            .try_borrow_mut()
1122            .map_err(|_| LifecycleError::Borrowed)?;
1123        if origin == &crate::InvocationOrigin::Effect && runtime.dispatch_owner_active(owner) {
1124            let root = owner
1125                .and_then(crate::SemanticDispatchOwner::cascade_root)
1126                .unwrap_or(&self.root_path);
1127            runtime.effect_cascades.reject(root);
1128        }
1129        Ok(())
1130    }
1131
1132    /// Transactionally run candidate `init(ctx)` and `view(ctx)` during hot reload.
1133    ///
1134    /// Component/store state and the last-good AST/root are preserved when
1135    /// either candidate lifecycle stage fails.
1136    ///
1137    /// # Errors
1138    ///
1139    /// Returns runtime or borrow errors from the candidate generation.
1140    pub fn reload(
1141        &mut self,
1142        engine: &mut RuntimeEngine,
1143        candidate: CompiledUi,
1144        state_schema: &ComponentStateSchema,
1145    ) -> Result<&UiNode, LifecycleError> {
1146        if self.state != LifecycleState::Running {
1147            return Err(LifecycleError::InvalidTransition {
1148                from: self.state,
1149                operation: "reload",
1150            });
1151        }
1152        let snapshot = self.begin_runtime_transaction()?;
1153        self.restart_effect_cascade()?;
1154        let engine_checkpoint = engine.execution_checkpoint();
1155        let result: Result<
1156            (UiNode, crate::RetainedUiTree, crate::CommittedSemanticFrame),
1157            LifecycleError,
1158        > = (|| {
1159            self.runtime
1160                .try_borrow_mut()
1161                .map_err(|_| LifecycleError::Borrowed)?
1162                .component_state
1163                .mount_instance(self.root_path.clone(), state_schema)?;
1164            engine.call_optional_lifecycle(
1165                &candidate,
1166                "init",
1167                self.context_for(ExecutionPhase::Init, candidate.generation()),
1168            )?;
1169            let mut root = engine.render_with_context_staged(
1170                &candidate,
1171                self.context_for(ExecutionPhase::Render, candidate.generation()),
1172            )?;
1173            let mut retained = self.retained.clone();
1174            let motion_reconcile_report = retained.reconcile_contained(&mut root)?;
1175            self.validate_resource_budgets(engine, &retained, &root)?;
1176            self.reconcile_motion(&root, &retained, candidate.generation())?;
1177            self.reconcile_exit_ghosts(&motion_reconcile_report)?;
1178            self.reconcile_effects(
1179                engine,
1180                &candidate,
1181                snapshot.component_state().clone(),
1182                &retained,
1183                &root,
1184            )?;
1185            self.retain_geometry_nodes(&retained)?;
1186            self.validate_signal_bindings(&root)?;
1187            let semantics = crate::CommittedSemanticFrame::from_retained(&retained)?;
1188            Ok((root, retained, semantics))
1189        })();
1190        match result {
1191            Ok((root, retained, semantics)) => {
1192                self.commit_or_roll_back(engine, snapshot, engine_checkpoint)?;
1193                self.trace_reconcile("reload", retained.last_report());
1194                self.compiled = candidate;
1195                self.retained = retained;
1196                self.semantics = semantics;
1197                self.revision = self.revision.wrapping_add(1);
1198                self.state = LifecycleState::Running;
1199                self.root = Some(Rc::new(root));
1200                self.root.as_deref().ok_or(LifecycleError::MissingRoot)
1201            }
1202            Err(error) => {
1203                self.runtime
1204                    .try_borrow_mut()
1205                    .map_err(|_| LifecycleError::Borrowed)?
1206                    .restore(snapshot)?;
1207                engine.restore_execution_checkpoint(engine_checkpoint);
1208                Err(error)
1209            }
1210        }
1211    }
1212
1213    /// Resume a suspended retained view into a newer compiled generation.
1214    ///
1215    /// Candidate initialization, the optional resume hook, reconciliation,
1216    /// and effect activation form one rollback-safe transaction. Async
1217    /// deliveries from the replaced generation must be discarded by the host
1218    /// before entering this transaction.
1219    ///
1220    /// # Errors
1221    ///
1222    /// Returns lifecycle, callback, render, reconciliation, or rollback errors.
1223    pub fn resume_reload(
1224        &mut self,
1225        engine: &mut RuntimeEngine,
1226        candidate: CompiledUi,
1227        state_schema: &ComponentStateSchema,
1228    ) -> Result<&UiNode, LifecycleError> {
1229        if self.state != LifecycleState::Suspended {
1230            return Err(LifecycleError::InvalidTransition {
1231                from: self.state,
1232                operation: "resume_reload",
1233            });
1234        }
1235        let snapshot = self.begin_runtime_transaction()?;
1236        self.restart_effect_cascade()?;
1237        let engine_checkpoint = engine.execution_checkpoint();
1238        let suspended_at = self
1239            .suspended_at
1240            .ok_or(LifecycleError::MissingSuspendTime)?;
1241        let now = self
1242            .runtime
1243            .try_borrow()
1244            .map_err(|_| LifecycleError::Borrowed)?
1245            .clock
1246            .now();
1247        let elapsed = now.saturating_duration_since(suspended_at);
1248        let result: Result<
1249            (UiNode, crate::RetainedUiTree, crate::CommittedSemanticFrame),
1250            LifecycleError,
1251        > = (|| {
1252            self.runtime
1253                .try_borrow_mut()
1254                .map_err(|_| LifecycleError::Borrowed)?
1255                .component_state
1256                .mount_instance(self.root_path.clone(), state_schema)?;
1257            engine.call_optional_lifecycle(
1258                &candidate,
1259                "init",
1260                self.context_for(ExecutionPhase::Init, candidate.generation()),
1261            )?;
1262            engine.call_optional_lifecycle_with_value(
1263                &candidate,
1264                "resume",
1265                self.context_for(ExecutionPhase::Resume, candidate.generation()),
1266                UiValue::Integer(i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX)),
1267            )?;
1268            {
1269                let mut runtime = self
1270                    .runtime
1271                    .try_borrow_mut()
1272                    .map_err(|_| LifecycleError::Borrowed)?;
1273                runtime.motion_values = runtime.motions.snapshot(now);
1274            }
1275            let mut root = engine.render_with_context_staged(
1276                &candidate,
1277                self.context_for(ExecutionPhase::Render, candidate.generation()),
1278            )?;
1279            let mut retained = self.retained.clone();
1280            let motion_reconcile_report = retained.reconcile_contained(&mut root)?;
1281            self.validate_resource_budgets(engine, &retained, &root)?;
1282            self.reconcile_motion(&root, &retained, candidate.generation())?;
1283            self.reconcile_exit_ghosts(&motion_reconcile_report)?;
1284            self.reconcile_effects(
1285                engine,
1286                &candidate,
1287                snapshot.component_state().clone(),
1288                &retained,
1289                &root,
1290            )?;
1291            self.resume_runtime_mechanisms(now, elapsed)?;
1292            self.retain_geometry_nodes(&retained)?;
1293            self.validate_signal_bindings(&root)?;
1294            let semantics = crate::CommittedSemanticFrame::from_retained(&retained)?;
1295            Ok((root, retained, semantics))
1296        })();
1297        match result {
1298            Ok((root, retained, semantics)) => {
1299                if let Err(error) = self.commit_or_roll_back(engine, snapshot, engine_checkpoint) {
1300                    self.state = LifecycleState::Suspended;
1301                    return Err(error);
1302                }
1303                self.trace_reconcile("resume_reload", retained.last_report());
1304                self.compiled = candidate;
1305                self.retained = retained;
1306                self.semantics = semantics;
1307                self.revision = self.revision.wrapping_add(1);
1308                self.root = Some(Rc::new(root));
1309                self.suspended_at = None;
1310                self.state = LifecycleState::Running;
1311                self.root.as_deref().ok_or(LifecycleError::MissingRoot)
1312            }
1313            Err(error) => {
1314                self.runtime
1315                    .try_borrow_mut()
1316                    .map_err(|_| LifecycleError::Borrowed)?
1317                    .restore(snapshot)?;
1318                engine.restore_execution_checkpoint(engine_checkpoint);
1319                self.state = LifecycleState::Suspended;
1320                Err(error)
1321            }
1322        }
1323    }
1324
1325    /// Run initialization followed by the first render.
1326    ///
1327    /// # Errors
1328    ///
1329    /// Returns lifecycle or script errors from either stage.
1330    pub fn start(&mut self, engine: &mut RuntimeEngine) -> Result<&UiNode, LifecycleError> {
1331        let runtime_snapshot = self.begin_runtime_transaction()?;
1332        self.restart_effect_cascade()?;
1333        let engine_checkpoint = engine.execution_checkpoint();
1334        let lifecycle_checkpoint = self.execution_checkpoint();
1335        let result = (|| {
1336            self.initialize(engine)?;
1337            self.render(engine)?;
1338            Ok::<_, LifecycleError>(())
1339        })();
1340        match result {
1341            Ok(()) => {
1342                self.commit_runtime_transaction()?;
1343                self.root.as_deref().ok_or(LifecycleError::MissingRoot)
1344            }
1345            Err(error) => {
1346                self.runtime
1347                    .try_borrow_mut()
1348                    .map_err(|_| LifecycleError::Borrowed)?
1349                    .restore(runtime_snapshot)?;
1350                engine.restore_execution_checkpoint(engine_checkpoint);
1351                self.restore_execution_checkpoint(lifecycle_checkpoint);
1352                Err(error)
1353            }
1354        }
1355    }
1356
1357    fn context(&self, phase: ExecutionPhase) -> UiContext {
1358        self.context_for(phase, self.compiled.generation())
1359    }
1360
1361    fn reconcile_motion(
1362        &self,
1363        root: &UiNode,
1364        retained: &crate::RetainedUiTree,
1365        generation: ScriptGeneration,
1366    ) -> Result<(), LifecycleError> {
1367        let domain = self.motion_root_path();
1368        let inert = retained
1369            .root_id()
1370            .and_then(|id| retained.node(id))
1371            .is_some_and(|node| node.summary().motion == 0)
1372            && self
1373                .runtime
1374                .try_borrow()
1375                .map_err(|_| LifecycleError::Borrowed)?
1376                .motions
1377                .live_scope_idle(&domain);
1378        if inert {
1379            return self.reconcile_inert_motion(root, retained, generation, &domain);
1380        }
1381        let identities = crate::motion::retained_motion_identities(root, retained, &domain)?;
1382        let mut runtime = self
1383            .runtime
1384            .try_borrow_mut()
1385            .map_err(|_| LifecycleError::Borrowed)?;
1386        let now = runtime.clock.now();
1387        let geometry_slots = crate::motion::node_motion_resource_usage(root).geometry_slots;
1388        crate::RuntimeBudgets::check(
1389            "active_motions",
1390            geometry_slots,
1391            runtime.budgets.active_motions,
1392        )?;
1393        let active_limit = runtime.budgets.active_motions;
1394        runtime.motions.set_active_limit(active_limit);
1395        let incarnations = runtime.component_incarnations_snapshot();
1396        let root_incarnation = runtime
1397            .component_incarnation(&self.root_path)
1398            .unwrap_or_else(crate::ComponentIncarnation::unscoped);
1399        let shared_layout_ids = crate::motion::shared_layout_ids(root)?;
1400        runtime
1401            .geometry_for(self.presentation_scope())
1402            .retain_shared_layout_ids(&shared_layout_ids);
1403        runtime
1404            .motions
1405            .set_active_reservation(&domain, geometry_slots);
1406        let values = crate::motion::reconcile_node_motion_scoped_owned(
1407            root,
1408            &mut runtime.motions,
1409            now,
1410            &domain,
1411            crate::motion::MotionReconcileContext {
1412                domain: &domain,
1413                root_component: &self.root_path,
1414                root_incarnation,
1415                generation,
1416                incarnations: &incarnations,
1417                identities: Some(&identities),
1418            },
1419        )?;
1420        let usage = runtime.motions.resource_usage();
1421        let active = usage.active.saturating_add(usage.geometry_slots);
1422        crate::RuntimeBudgets::check("active_motions", active, runtime.budgets.active_motions)?;
1423        runtime.reconcile_page_visibility(retained, &self.root_path, &domain);
1424        runtime.motion_values = if values.is_empty() {
1425            values
1426        } else {
1427            runtime.motions.snapshot(now)
1428        };
1429        Ok(())
1430    }
1431
1432    /// [`Self::reconcile_motion`] for a tree that declares no motion
1433    /// ([`crate::motion::node_takes_motion`]) in a domain that holds none:
1434    /// the declarations, identities and scene it would walk the tree for are
1435    /// empty, and the scopes it would retain hold nothing to cancel, so what
1436    /// remains are its budget checks, reservations and resamples.
1437    fn reconcile_inert_motion(
1438        &self,
1439        root: &UiNode,
1440        retained: &crate::RetainedUiTree,
1441        generation: ScriptGeneration,
1442        domain: &str,
1443    ) -> Result<(), LifecycleError> {
1444        #[cfg(debug_assertions)]
1445        let reference = self.reference_motion_outcome(root, retained, generation, domain);
1446        #[cfg(not(debug_assertions))]
1447        let _ = (root, generation);
1448        let mut runtime = self
1449            .runtime
1450            .try_borrow_mut()
1451            .map_err(|_| LifecycleError::Borrowed)?;
1452        let now = runtime.clock.now();
1453        let active_limit = runtime.budgets.active_motions;
1454        runtime.motions.set_active_limit(active_limit);
1455        runtime
1456            .geometry_for(self.presentation_scope())
1457            .retain_shared_layout_ids(&BTreeSet::new());
1458        runtime.motions.set_active_reservation(domain, 0);
1459        let usage = runtime.motions.resource_usage();
1460        let active = usage.active.saturating_add(usage.geometry_slots);
1461        let result = if active > active_limit {
1462            Err(crate::motion::MotionError::ActiveBudget {
1463                actual: active,
1464                limit: active_limit,
1465            }
1466            .into())
1467        } else {
1468            runtime.reconcile_page_visibility(retained, &self.root_path, domain);
1469            runtime.motion_values = runtime.motions.snapshot(now);
1470            Ok(())
1471        };
1472        #[cfg(debug_assertions)]
1473        debug_assert_eq!(
1474            result
1475                .as_ref()
1476                .map(|()| runtime.motions.snapshot(now))
1477                .map_err(ToString::to_string),
1478            reference,
1479            "an inert commit's motion phase differs from the full one"
1480        );
1481        result
1482    }
1483
1484    /// The motion values (or the error) the full motion phase reaches from
1485    /// the current motion state, which it leaves as it is.
1486    #[cfg(debug_assertions)]
1487    fn reference_motion_outcome(
1488        &self,
1489        root: &UiNode,
1490        retained: &crate::RetainedUiTree,
1491        generation: ScriptGeneration,
1492        domain: &str,
1493    ) -> Result<BTreeMap<crate::MotionKey, f64>, String> {
1494        let runtime = self.runtime.borrow();
1495        let mut motions = runtime.motions.transaction_snapshot();
1496        let now = runtime.clock.now();
1497        let outcome = (|| {
1498            let identities = crate::motion::retained_motion_identities(root, retained, domain)?;
1499            let geometry_slots = crate::motion::node_motion_resource_usage(root).geometry_slots;
1500            crate::RuntimeBudgets::check(
1501                "active_motions",
1502                geometry_slots,
1503                runtime.budgets.active_motions,
1504            )?;
1505            motions.set_active_limit(runtime.budgets.active_motions);
1506            let shared_layout_ids = crate::motion::shared_layout_ids(root)?;
1507            assert!(shared_layout_ids.is_empty(), "an inert tree shares layout");
1508            motions.set_active_reservation(domain, geometry_slots);
1509            let incarnations = runtime.component_incarnations_snapshot();
1510            crate::motion::reconcile_node_motion_scoped_owned(
1511                root,
1512                &mut motions,
1513                now,
1514                domain,
1515                crate::motion::MotionReconcileContext {
1516                    domain,
1517                    root_component: &self.root_path,
1518                    root_incarnation: runtime
1519                        .component_incarnation(&self.root_path)
1520                        .unwrap_or_else(crate::ComponentIncarnation::unscoped),
1521                    generation,
1522                    incarnations: &incarnations,
1523                    identities: Some(&identities),
1524                },
1525            )?;
1526            let usage = motions.resource_usage();
1527            let active = usage.active.saturating_add(usage.geometry_slots);
1528            crate::RuntimeBudgets::check("active_motions", active, runtime.budgets.active_motions)?;
1529            Ok::<_, LifecycleError>(motions.snapshot(now))
1530        })();
1531        outcome.map_err(|error| error.to_string())
1532    }
1533
1534    fn resume_runtime_mechanisms(
1535        &self,
1536        now: std::time::Instant,
1537        elapsed: std::time::Duration,
1538    ) -> Result<(), LifecycleError> {
1539        let mut runtime = self
1540            .runtime
1541            .try_borrow_mut()
1542            .map_err(|_| LifecycleError::Borrowed)?;
1543        runtime.timers.resume_component_scope(&self.root_path, now);
1544        runtime
1545            .motions
1546            .resume_node_scope(&self.motion_root_path(), now);
1547        runtime
1548            .geometry_for(self.presentation_scope())
1549            .delay_motion(elapsed);
1550        runtime.motion_values = runtime.motions.snapshot(now);
1551        Ok(())
1552    }
1553
1554    fn reconcile_exit_ghosts(&self, report: &crate::ReconcileReport) -> Result<(), LifecycleError> {
1555        let Some(previous) = self.root.as_deref() else {
1556            return Ok(());
1557        };
1558        let Some(root_id) = self.retained.root_id() else {
1559            return Ok(());
1560        };
1561        // Only a removed node with exit motions leaves a ghost.
1562        if report.unmounted.iter().all(|id| {
1563            self.retained
1564                .node(*id)
1565                .is_none_or(|node| node.summary().exit == 0)
1566        }) {
1567            return Ok(());
1568        }
1569        let removed = report.unmounted.iter().copied().collect::<BTreeSet<_>>();
1570        let mut exits = Vec::<(crate::NodeId, &UiNode)>::new();
1571        collect_removed_exit_nodes(previous, root_id, &self.retained, &removed, &mut exits);
1572        if exits.is_empty() {
1573            return Ok(());
1574        }
1575        let mut runtime = self
1576            .runtime
1577            .try_borrow_mut()
1578            .map_err(|_| LifecycleError::Borrowed)?;
1579        let now = runtime.clock.now();
1580        let domain = self.motion_root_path();
1581        let geometry_registry = runtime.geometry_for(self.presentation_scope());
1582        for (retained, node) in exits {
1583            let Some(geometry) = geometry_registry.get(retained) else {
1584                continue;
1585            };
1586            let ghost = node.motion_ghost().ok_or_else(|| {
1587                LifecycleError::Motion(MotionError::UnsupportedExitGhost(format!(
1588                    "{:?}",
1589                    node.kind_tag()
1590                )))
1591            })?;
1592            let path = format!("{domain}/ghost:{}", retained.get());
1593            if runtime.motion_ghosts.iter().any(|ghost| ghost.path == path) {
1594                continue;
1595            }
1596            for source in node.exit_motions() {
1597                runtime.motions.start_exit(
1598                    ComponentInstancePath::root("UiNode", path.clone()),
1599                    source.clone(),
1600                    now,
1601                )?;
1602            }
1603            if runtime.motions.is_node_scope_active(&path) {
1604                runtime.motion_ghosts.push(crate::motion::MotionGhost {
1605                    id: retained.get().to_string(),
1606                    node: ghost,
1607                    bounds: geometry.visual,
1608                    path,
1609                    domain: domain.clone(),
1610                });
1611            }
1612        }
1613        crate::RuntimeBudgets::check(
1614            "motion_ghosts",
1615            runtime.motion_ghosts.len(),
1616            runtime.budgets.motion_ghosts,
1617        )?;
1618        Ok(())
1619    }
1620
1621    #[allow(clippy::too_many_lines)]
1622    fn validate_resource_budgets(
1623        &self,
1624        engine: &RuntimeEngine,
1625        retained: &crate::RetainedUiTree,
1626        root: &UiNode,
1627    ) -> Result<(), LifecycleError> {
1628        let budgets = self
1629            .runtime
1630            .try_borrow()
1631            .map_err(|_| LifecycleError::Borrowed)?
1632            .budgets
1633            .clone();
1634        budgets.validate()?;
1635        crate::RuntimeBudgets::check("retained_nodes", retained.len(), budgets.retained_nodes)?;
1636        // The tree keeps these totals as it is reconciled.
1637        let summary = retained.summary();
1638        let totals = summary.resources;
1639        debug_assert_eq!(totals, retained.recounted_resources());
1640        crate::RuntimeBudgets::check("event_handlers", totals.handlers, budgets.event_handlers)?;
1641        crate::RuntimeBudgets::check("layers", totals.layers, budgets.layers)?;
1642        crate::RuntimeBudgets::check("canvas_scenes", totals.canvas_scenes, budgets.canvas_scenes)?;
1643        crate::RuntimeBudgets::check(
1644            "canvas_commands",
1645            totals.canvas_commands,
1646            budgets.canvas_commands,
1647        )?;
1648        crate::RuntimeBudgets::check(
1649            "virtual_data_items",
1650            totals.virtual_data_items,
1651            budgets.virtual_data_items,
1652        )?;
1653        crate::RuntimeBudgets::check(
1654            "virtual_realized_items",
1655            totals.virtual_realized_items,
1656            budgets.virtual_realized_items,
1657        )?;
1658        crate::RuntimeBudgets::check(
1659            "formal_components",
1660            engine.component_invocations().len(),
1661            budgets.formal_components,
1662        )?;
1663        crate::RuntimeBudgets::check(
1664            "effects",
1665            engine.component_effects_in_scope(&self.root_path).len(),
1666            budgets.effects,
1667        )?;
1668        crate::RuntimeBudgets::check(
1669            "signals",
1670            engine.component_signals_in_scope(&self.root_path).len(),
1671            budgets.signals,
1672        )?;
1673        crate::RuntimeBudgets::check(
1674            "element_refs",
1675            engine
1676                .component_element_refs_in_scope(&self.root_path)
1677                .len(),
1678            budgets.element_refs,
1679        )?;
1680        crate::RuntimeBudgets::check(
1681            "timers",
1682            engine.component_timers_in_scope(&self.root_path).len(),
1683            budgets.timers,
1684        )?;
1685        // A tree that declares no motion uses none of these.
1686        let motion = if summary.motion == 0 {
1687            crate::motion::MotionResourceUsage::default()
1688        } else {
1689            crate::motion::node_motion_resource_usage(root)
1690        };
1691        crate::RuntimeBudgets::check(
1692            "motion_declarations",
1693            motion.declarations,
1694            budgets.motion_declarations,
1695        )?;
1696        crate::RuntimeBudgets::check(
1697            "motion_keyframes",
1698            motion.keyframes,
1699            budgets.motion_keyframes,
1700        )?;
1701        crate::RuntimeBudgets::check(
1702            "motion_timelines",
1703            motion.timelines,
1704            budgets.motion_timelines,
1705        )?;
1706        crate::RuntimeBudgets::check(
1707            "motion_timeline_steps",
1708            motion.timeline_steps,
1709            budgets.motion_timeline_steps,
1710        )?;
1711        crate::RuntimeBudgets::check(
1712            "motion_particles",
1713            motion.particles,
1714            budgets.motion_particles,
1715        )?;
1716        crate::RuntimeBudgets::check(
1717            "shared_motion_snapshots",
1718            motion.shared_snapshots,
1719            budgets.shared_motion_snapshots,
1720        )?;
1721        crate::RuntimeBudgets::check(
1722            "active_motions",
1723            motion.geometry_slots,
1724            budgets.active_motions,
1725        )?;
1726        Ok(())
1727    }
1728
1729    fn reconcile_effects(
1730        &self,
1731        engine: &mut RuntimeEngine,
1732        candidate: &CompiledUi,
1733        previous_state: crate::StateStore,
1734        retained: &crate::RetainedUiTree,
1735        root: &UiNode,
1736    ) -> Result<(), LifecycleError> {
1737        let declarations = RetainedDeclarations {
1738            effects: engine.component_effects_in_scope(&self.root_path),
1739            timers: engine.component_timers_in_scope(&self.root_path),
1740            signals: engine.component_signals_in_scope(&self.root_path),
1741            element_refs: self.element_ref_bindings(engine, retained)?,
1742        };
1743        // The items virtual collections keep keep their reads too.
1744        let mut contributions = root.virtual_read_contributions();
1745        contributions.extend(engine.kept_virtual_read_contributions(&self.root_path));
1746        self.runtime
1747            .try_borrow_mut()
1748            .map_err(|_| LifecycleError::Borrowed)?
1749            .retain_virtual_read_contributions(&self.root_path, &contributions);
1750        self.reconcile_effect_candidate(engine, candidate, declarations, Some(previous_state))?;
1751        self.runtime
1752            .try_borrow()
1753            .map_err(|_| LifecycleError::Borrowed)?
1754            .virtual_requests
1755            .native_views
1756            .retain_scope(&self.root_path, retained, candidate.generation());
1757        Ok(())
1758    }
1759
1760    fn reconcile_effect_candidate(
1761        &self,
1762        engine: &mut RuntimeEngine,
1763        candidate: &CompiledUi,
1764        declarations: RetainedDeclarations,
1765        previous_state: Option<crate::StateStore>,
1766    ) -> Result<(), LifecycleError> {
1767        {
1768            let mut runtime = self
1769                .runtime
1770                .try_borrow_mut()
1771                .map_err(|_| LifecycleError::Borrowed)?;
1772            runtime
1773                .effect_cascades
1774                .register_generation(&self.root_path, candidate.generation());
1775            runtime.prune_pending_dispatch();
1776        }
1777        let plan = self
1778            .runtime
1779            .try_borrow()
1780            .map_err(|_| LifecycleError::Borrowed)?
1781            .effects
1782            .plan(&self.root_path, declarations.effects);
1783        let transition_count = plan.transition_count();
1784        self.runtime
1785            .try_borrow_mut()
1786            .map_err(|_| LifecycleError::Borrowed)?
1787            .effect_cascades
1788            .charge(&self.root_path, transition_count)
1789            .map_err(LifecycleError::EffectBudget)?;
1790        if plan.has_cleanup()
1791            && let Some(previous_state) = previous_state
1792        {
1793            self.runtime
1794                .try_borrow_mut()
1795                .map_err(|_| LifecycleError::Borrowed)?
1796                .component_state = previous_state;
1797        }
1798        for (descriptor, scope) in plan.cleanup_descriptors() {
1799            self.invoke_effect_callback(
1800                engine,
1801                candidate,
1802                descriptor.cleanup(),
1803                descriptor.dependencies().clone(),
1804                scope,
1805            )?;
1806        }
1807        let virtual_collections = engine.virtual_collection_ids_in_scope(&self.root_path);
1808        {
1809            let mut runtime = self
1810                .runtime
1811                .try_borrow_mut()
1812                .map_err(|_| LifecycleError::Borrowed)?;
1813            let now = runtime.clock.now();
1814            engine.commit_component_renders(&mut runtime)?;
1815            runtime
1816                .timers
1817                .reconcile(&self.root_path, declarations.timers, now);
1818            runtime
1819                .signals
1820                .reconcile(&self.root_path, declarations.signals);
1821            runtime
1822                .element_refs
1823                .reconcile(&self.root_path, declarations.element_refs);
1824            let geometry_bindings = runtime.element_refs.geometry_bindings(&self.root_path);
1825            let geometry = runtime.geometry_for(self.presentation_scope());
1826            geometry.sync_ref_readers(&self.root_path, geometry_bindings);
1827            runtime
1828                .virtual_requests
1829                .retain_within(&self.root_path, &virtual_collections);
1830        }
1831        for (descriptor, scope) in plan.start_descriptors() {
1832            self.invoke_effect_callback(
1833                engine,
1834                candidate,
1835                descriptor.start(),
1836                descriptor.dependencies().clone(),
1837                scope,
1838            )?;
1839        }
1840        {
1841            let mut runtime = self
1842                .runtime
1843                .try_borrow_mut()
1844                .map_err(|_| LifecycleError::Borrowed)?;
1845            for (_, scope) in plan.cleanup_descriptors() {
1846                runtime.cancel_async_scope(&scope)?;
1847            }
1848            runtime.effects.commit(plan);
1849        }
1850        Ok(())
1851    }
1852
1853    fn invoke_effect_callback(
1854        &self,
1855        engine: &RuntimeEngine,
1856        candidate: &CompiledUi,
1857        callback: &ScriptCallback,
1858        dependencies: UiValue,
1859        scope: AsyncScope,
1860    ) -> Result<(), LifecycleError> {
1861        self.validate_callback_owner(callback)?;
1862        let compiled = if callback.generation() == candidate.generation() {
1863            candidate
1864        } else if callback.generation() == self.compiled.generation() {
1865            &self.compiled
1866        } else {
1867            return Err(LifecycleError::StaleEffect {
1868                name: callback.name().to_owned(),
1869                generation: callback.generation(),
1870            });
1871        };
1872        let root_context = self.context_for(ExecutionPhase::Event, compiled.generation());
1873        let context = callback
1874            .component()
1875            .map_or(root_context.clone(), |component| {
1876                root_context.for_component(component.clone(), callback.events().clone())
1877            })
1878            .with_native_context(callback.native_context().cloned())
1879            .with_async_scope(scope);
1880        self.with_dispatch_owner(None, || {
1881            self.with_origin(crate::InvocationOrigin::Effect, || {
1882                let _ = engine.invoke_callback_for_generation(
1883                    compiled,
1884                    callback,
1885                    (context, dependencies.into_dynamic()),
1886                )?;
1887                Ok(())
1888            })
1889        })
1890    }
1891
1892    fn validate_callback_owner(&self, callback: &ScriptCallback) -> Result<(), LifecycleError> {
1893        let (Some(component), Some(incarnation)) = (callback.component(), callback.incarnation())
1894        else {
1895            return Ok(());
1896        };
1897        let active = self
1898            .runtime
1899            .try_borrow()
1900            .map_err(|_| LifecycleError::Borrowed)?
1901            .component_incarnation(component);
1902        if active == Some(incarnation) {
1903            Ok(())
1904        } else {
1905            Err(RuntimeError::StaleComponentCallback {
1906                name: callback.name().to_owned(),
1907                component: component.clone(),
1908            }
1909            .into())
1910        }
1911    }
1912
1913    fn validate_signal_bindings(&self, root: &UiNode) -> Result<(), LifecycleError> {
1914        let runtime = self
1915            .runtime
1916            .try_borrow()
1917            .map_err(|_| LifecycleError::Borrowed)?;
1918        let mut pending = vec![root];
1919        while let Some(node) = pending.pop() {
1920            for (_, signal) in node.signal_bindings() {
1921                let _ = runtime.signals.read(signal)?;
1922            }
1923            if let Some(style) = node.signal_style() {
1924                let _ = runtime.signals.read(&style.signal)?;
1925            }
1926            for binding in node.progress_motions() {
1927                if let Some(trigger) = &binding.signal_trigger {
1928                    let _ = runtime.signals.read(&trigger.signal)?;
1929                }
1930            }
1931            for (_, children) in node.retained_child_groups() {
1932                pending.extend(children);
1933            }
1934        }
1935        Ok(())
1936    }
1937
1938    fn element_ref_bindings(
1939        &self,
1940        engine: &RuntimeEngine,
1941        retained: &crate::RetainedUiTree,
1942    ) -> Result<BTreeMap<crate::ElementRefId, crate::NodeId>, LifecycleError> {
1943        let declared = engine.component_element_refs_in_scope(&self.root_path);
1944        let mut bindings = BTreeMap::new();
1945        for node in retained.nodes() {
1946            let Some(reference) = node.element_ref() else {
1947                continue;
1948            };
1949            if node.key().is_none() {
1950                return Err(crate::ElementRefError::MissingNodeKey(reference.id().clone()).into());
1951            }
1952            if !declared.contains(reference.id()) {
1953                return Err(crate::ElementRefError::Undeclared(reference.id().clone()).into());
1954            }
1955            if bindings.insert(reference.id().clone(), node.id()).is_some() {
1956                return Err(
1957                    crate::ElementRefError::DuplicateBinding(reference.id().clone()).into(),
1958                );
1959            }
1960        }
1961        Ok(bindings)
1962    }
1963
1964    fn retain_geometry_nodes(
1965        &self,
1966        retained: &crate::RetainedUiTree,
1967    ) -> Result<(), LifecycleError> {
1968        let runtime = self
1969            .runtime
1970            .try_borrow()
1971            .map_err(|_| LifecycleError::Borrowed)?;
1972        runtime
1973            .geometry_for(self.presentation_scope())
1974            .retain_tree(retained);
1975        runtime
1976            .pointer_capture_for(self.presentation_scope())
1977            .retain_nodes(|node| retained.node(node).is_some() && retained.is_page_visible(node));
1978        Ok(())
1979    }
1980
1981    fn presentation_scope(&self) -> Option<&str> {
1982        self.view.as_deref().or(self.window.as_deref())
1983    }
1984
1985    fn begin_runtime_transaction(&self) -> Result<crate::UiStateSnapshot, LifecycleError> {
1986        self.runtime
1987            .try_borrow_mut()
1988            .map_err(|_| LifecycleError::Borrowed)?
1989            .begin_transaction()
1990            .map_err(LifecycleError::from)
1991    }
1992
1993    fn restart_effect_cascade(&self) -> Result<(), LifecycleError> {
1994        self.runtime
1995            .try_borrow_mut()
1996            .map_err(|_| LifecycleError::Borrowed)?
1997            .effect_cascades
1998            .restart(&self.root_path);
1999        Ok(())
2000    }
2001
2002    /// Commits the runtime transaction a commit began, before the commit
2003    /// publishes anything; when that fails, rolls the runtime and the engine
2004    /// back, so nothing of the commit stays.
2005    fn commit_or_roll_back(
2006        &self,
2007        engine: &mut RuntimeEngine,
2008        snapshot: crate::UiStateSnapshot,
2009        checkpoint: crate::engine::RuntimeEngineCheckpoint,
2010    ) -> Result<(), LifecycleError> {
2011        let Err(error) = self.commit_runtime_transaction() else {
2012            return Ok(());
2013        };
2014        self.runtime
2015            .try_borrow_mut()
2016            .map_err(|_| LifecycleError::Borrowed)?
2017            .restore(snapshot)?;
2018        engine.restore_execution_checkpoint(checkpoint);
2019        Err(error)
2020    }
2021
2022    fn commit_runtime_transaction(&self) -> Result<(), LifecycleError> {
2023        self.runtime
2024            .try_borrow_mut()
2025            .map_err(|_| LifecycleError::Borrowed)?
2026            .commit_transaction()?;
2027        Ok(())
2028    }
2029
2030    #[must_use]
2031    pub fn window_id(&self) -> Option<&str> {
2032        self.window.as_deref()
2033    }
2034
2035    #[must_use]
2036    pub fn view_id(&self) -> Option<&str> {
2037        self.view.as_deref()
2038    }
2039
2040    #[must_use]
2041    pub fn root_path(&self) -> &ComponentInstancePath {
2042        &self.root_path
2043    }
2044
2045    pub(crate) fn diagnostic_context(
2046        &self,
2047        engine: &RuntimeEngine,
2048        component: Option<&ComponentInstancePath>,
2049    ) -> Result<crate::DiagnosticContext, crate::DiagnosticContextError> {
2050        let root_context = self.context(ExecutionPhase::Event);
2051        let component = component
2052            .cloned()
2053            .or_else(|| engine.last_failed_component())
2054            .unwrap_or_else(|| self.root_path.clone());
2055        let key = component.leaf_key().map(str::to_owned);
2056        let context = root_context.for_component(component, BTreeMap::new());
2057        let source = engine.last_failed_timing().map(|timing| timing.source);
2058        crate::DiagnosticContext::capture(engine, &context, source, key)
2059    }
2060
2061    #[must_use]
2062    pub fn compiled(&self) -> CompiledUi {
2063        self.compiled.clone()
2064    }
2065
2066    fn motion_root_path(&self) -> String {
2067        match (self.window.as_deref(), self.view.as_deref()) {
2068            (Some(window), Some(view)) => format!("window:{window}/view:{view}/root"),
2069            (Some(window), None) => format!("window:{window}/root"),
2070            (None, Some(view)) => format!("view:{view}/root"),
2071            (None, None) => "root".to_owned(),
2072        }
2073    }
2074
2075    fn trace_reconcile(&self, operation: &str, report: &crate::ReconcileReport) {
2076        const ID_SAMPLE_LIMIT: usize = 16;
2077
2078        fn ids(values: &[crate::NodeId]) -> crate::UiValue {
2079            crate::UiValue::Array(
2080                values
2081                    .iter()
2082                    .take(ID_SAMPLE_LIMIT)
2083                    .map(|id| crate::UiValue::Integer(i64::try_from(id.get()).unwrap_or(i64::MAX)))
2084                    .collect(),
2085            )
2086        }
2087
2088        let metrics = report.metrics();
2089        let truncated = [
2090            &report.mounted,
2091            &report.preserved,
2092            &report.moved,
2093            &report.unmounted,
2094        ]
2095        .into_iter()
2096        .any(|nodes| nodes.len() > ID_SAMPLE_LIMIT);
2097        let payload = crate::UiValue::Map(BTreeMap::from([
2098            ("mounted".to_owned(), ids(&report.mounted)),
2099            ("preserved".to_owned(), ids(&report.preserved)),
2100            ("moved".to_owned(), ids(&report.moved)),
2101            ("unmounted".to_owned(), ids(&report.unmounted)),
2102            ("truncated".to_owned(), crate::UiValue::Bool(truncated)),
2103        ]));
2104        if let Ok(mut runtime) = self.runtime.try_borrow_mut() {
2105            runtime.traces.push(
2106                crate::RuntimeTraceKind::Reconcile,
2107                self.root_path.to_string(),
2108                format!(
2109                    "{operation}: mounted={} preserved={} moved={} unmounted={}",
2110                    metrics.mounted, metrics.preserved, metrics.moved, metrics.unmounted
2111                ),
2112                Some(payload),
2113                false,
2114            );
2115        }
2116    }
2117
2118    fn context_for(&self, phase: ExecutionPhase, generation: ScriptGeneration) -> UiContext {
2119        UiContext::new(
2120            Rc::clone(&self.runtime),
2121            self.root_path.clone(),
2122            self.window.clone(),
2123            phase,
2124            self.events.clone(),
2125        )
2126        .with_optional_view_id(self.view.clone())
2127        .with_generation(generation)
2128    }
2129
2130    fn require_state(&self, required: LifecycleState) -> Result<(), LifecycleError> {
2131        if self.state == required {
2132            Ok(())
2133        } else {
2134            Err(LifecycleError::InvalidTransition {
2135                from: self.state,
2136                operation: "initialize",
2137            })
2138        }
2139    }
2140}
2141
2142#[derive(Debug, Error)]
2143pub enum LifecycleError {
2144    #[error("cannot {operation} while lifecycle is {from:?}")]
2145    InvalidTransition {
2146        from: LifecycleState,
2147        operation: &'static str,
2148    },
2149    #[error("UI runtime state is already borrowed")]
2150    Borrowed,
2151    #[error(transparent)]
2152    State(#[from] StateError),
2153    #[error(transparent)]
2154    Runtime(#[from] RuntimeError),
2155    #[error(transparent)]
2156    Motion(#[from] MotionError),
2157    #[error(transparent)]
2158    Reconcile(#[from] crate::ReconcileError),
2159    #[error("script lifecycle has no accepted root")]
2160    MissingRoot,
2161    #[error("suspended lifecycle is missing its monotonic suspension timestamp")]
2162    MissingSuspendTime,
2163    #[error("component subtree `{0}` is missing from the accepted UiNode snapshot")]
2164    MissingComponentSubtree(ComponentInstancePath),
2165    #[error("virtual collection `{0:?}` is missing from the accepted UiNode snapshot")]
2166    MissingVirtualCollection(crate::VirtualCollectionId),
2167    #[error("effect transition exceeded the 64-callback budget with {0} callbacks")]
2168    EffectBudget(usize),
2169    #[error("effect callback `{name}` belongs to unavailable generation {generation}")]
2170    StaleEffect {
2171        name: String,
2172        generation: ScriptGeneration,
2173    },
2174    #[error(transparent)]
2175    Asset(#[from] crate::AssetError),
2176    #[error(transparent)]
2177    Transaction(#[from] crate::UiTransactionError),
2178    #[error(transparent)]
2179    Signal(#[from] crate::SignalError),
2180    #[error(transparent)]
2181    ElementRef(#[from] crate::ElementRefError),
2182    #[error(transparent)]
2183    Budget(#[from] crate::RuntimeBudgetError),
2184    #[error(transparent)]
2185    Accessibility(#[from] crate::AccessibilityError),
2186}
2187
2188fn collect_removed_exit_nodes<'a>(
2189    node: &'a UiNode,
2190    id: crate::NodeId,
2191    retained: &crate::RetainedUiTree,
2192    removed: &BTreeSet<crate::NodeId>,
2193    output: &mut Vec<(crate::NodeId, &'a UiNode)>,
2194) {
2195    if removed.contains(&id) && !node.exit_motions().is_empty() {
2196        output.push((id, node));
2197        return;
2198    }
2199    let Some(retained_node) = retained.node(id) else {
2200        return;
2201    };
2202    if retained_node.summary().exit == 0 {
2203        return;
2204    }
2205    for (group, children) in node.retained_child_groups() {
2206        let ids = retained_node
2207            .children()
2208            .filter(|child| child.group() == group)
2209            .map(crate::RetainedChildLink::node)
2210            .collect::<Vec<_>>();
2211        for (child, id) in children.into_iter().zip(ids) {
2212            collect_removed_exit_nodes(child, id, retained, removed, output);
2213        }
2214    }
2215}
2216
2217fn replaceable_component_paths(
2218    root: &UiNode,
2219    root_path: &ComponentInstancePath,
2220    paths: Vec<ComponentInstancePath>,
2221    active: &BTreeSet<ComponentInstancePath>,
2222) -> Option<Vec<ComponentInstancePath>> {
2223    let index = crate::node::ComponentSubtreeIndex::new(root);
2224    let mut replaceable = BTreeSet::new();
2225    for path in paths {
2226        let mut candidate = path;
2227        loop {
2228            if active.contains(&candidate) && index.get(root, &candidate).is_some() {
2229                replaceable.insert(candidate);
2230                break;
2231            }
2232            candidate = candidate.parent()?;
2233            if &candidate == root_path {
2234                return None;
2235            }
2236        }
2237    }
2238    Some(topmost_paths(&replaceable))
2239}
2240
2241#[cfg(test)]
2242mod tests {
2243    use super::*;
2244    use crate::{
2245        AssetData, AsyncCapabilityHandler, CapabilityDescriptor, CapabilityId, CapabilityMethod,
2246        ExecutionOperation, InMemoryAssetProvider, OpaqueHandle, StateField,
2247        SubscriptionCapabilityHandler, SubscriptionWork, TaskWork, UiNodeKind, UiValue,
2248        ValueSchema,
2249    };
2250    use semver::{Version, VersionReq};
2251    use std::time::{Duration, Instant};
2252
2253    #[test]
2254    fn effect_origin_followup_does_not_restart_a_rejected_cascade() {
2255        let mut engine = RuntimeEngine::new();
2256        let compiled = engine
2257            .compile(
2258                r#"
2259            fn followup(ctx, payload) { ctx.set_state("phase", "changed"); }
2260            fn view(ctx) { text(ctx.get_state("phase")) }
2261        "#,
2262            )
2263            .unwrap();
2264        let followup = engine.callback(&compiled, "followup").unwrap();
2265        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
2266        let root = ComponentInstancePath::root("App", "main");
2267        let mut lifecycle = ScriptLifecycle::new(
2268            compiled,
2269            Rc::clone(&runtime),
2270            root.clone(),
2271            Some("main".to_owned()),
2272            BTreeMap::new(),
2273            &state_schema(),
2274        )
2275        .unwrap();
2276        lifecycle.start(&mut engine).unwrap();
2277        {
2278            let mut runtime = runtime.borrow_mut();
2279            runtime.effect_cascades.restart(&root);
2280            runtime.effect_cascades.charge(&root, 64).unwrap();
2281            assert!(runtime.effect_cascades.charge(&root, 1).is_err());
2282        }
2283        let _ = lifecycle
2284            .with_origin(crate::InvocationOrigin::Effect, || {
2285                lifecycle.invoke_callback_transactional(&engine, &followup, UiValue::Null)
2286            })
2287            .unwrap();
2288        assert!(!lifecycle.render_dirty(&mut engine).unwrap());
2289        let _ = lifecycle
2290            .invoke_callback_transactional(&engine, &followup, UiValue::Null)
2291            .unwrap();
2292        assert!(lifecycle.render_dirty(&mut engine).unwrap());
2293    }
2294
2295    #[test]
2296    fn pure_event_loop_without_effect_transitions_shares_budget_and_prunes_restored_queue() {
2297        let mut engine = RuntimeEngine::new();
2298        let compiled = engine
2299            .compile(
2300                r#"
2301            fn echo(ctx, payload) { ctx.emit("tick", ()); }
2302            fn view(ctx) { text("stable") }
2303        "#,
2304            )
2305            .unwrap();
2306        let mut echo = engine.callback(&compiled, "echo").unwrap();
2307        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
2308        let root = ComponentInstancePath::root("App", "pure_event");
2309        let events = BTreeMap::from([(
2310            "tick".to_owned(),
2311            crate::EventSchema::new(ValueSchema::Null),
2312        )]);
2313        let mut lifecycle = ScriptLifecycle::new(
2314            compiled,
2315            Rc::clone(&runtime),
2316            root.clone(),
2317            None,
2318            events.clone(),
2319            &ComponentStateSchema::default(),
2320        )
2321        .unwrap();
2322        lifecycle.start(&mut engine).unwrap();
2323        echo.bind_component_scope_if_unset(
2324            &root,
2325            runtime.borrow().component_incarnation(&root).unwrap(),
2326            events,
2327        );
2328        runtime.borrow_mut().replace_component_event_handlers(
2329            &root,
2330            BTreeMap::from([((root.clone(), "tick".to_owned()), echo)]),
2331        );
2332        let context = lifecycle.context(ExecutionPhase::Event);
2333        lifecycle
2334            .with_origin(crate::InvocationOrigin::Effect, || {
2335                context.emit("tick", Dynamic::UNIT).unwrap();
2336                Ok(())
2337            })
2338            .unwrap();
2339        let checkpoint = runtime.borrow_mut().begin_transaction().unwrap();
2340        let mut rejected = false;
2341        for _ in 0..65 {
2342            let pending = runtime.borrow_mut().drain_batch().events.pop().unwrap();
2343            match lifecycle.invoke_component_event_transactional(&engine, pending) {
2344                Ok(Some(_)) => (),
2345                Err(LifecycleError::EffectBudget(65)) => {
2346                    rejected = true;
2347                    break;
2348                }
2349                result => panic!("unexpected pure event result {result:?}"),
2350            }
2351        }
2352        assert!(rejected);
2353        runtime
2354            .borrow_mut()
2355            .rollback_transaction(checkpoint)
2356            .unwrap();
2357        assert!(runtime.borrow_mut().drain_batch().events.is_empty());
2358        assert!(!lifecycle.render_dirty(&mut engine).unwrap());
2359    }
2360
2361    fn state_schema() -> ComponentStateSchema {
2362        ComponentStateSchema::new(BTreeMap::from([(
2363            "phase".to_owned(),
2364            StateField::new(ValueSchema::string(), UiValue::String("created".to_owned())),
2365        )]))
2366        .unwrap()
2367    }
2368
2369    const STREAM_COMPONENT_APP: &str = r#"
2370        define_component(#{
2371            metadata: #{ id: "test/stream", "export": "StreamProbe", version: "0.1.0",
2372                runtime_api: #{ min_inclusive: 3, max_exclusive: 4 },
2373                dependencies: [], capabilities: #{ "app.stream": "*" } },
2374            schema: #{ props: #{ key: #{ schema: #{ type: "string" }, required: true, sensitive: false } },
2375                state: #{ fields: #{ phase: #{ schema: #{ type: "string" },
2376                    "default": #{ type: "string", value: "idle" } } } },
2377                events: #{}, slots: #{}, parts: [], effects: ["watch"] },
2378            render: Fn("render_StreamProbe"),
2379        });
2380        fn start_stream(ctx, deps) {
2381            ctx.start_subscription(
2382                "app.stream", "watch", (),
2383                Fn("received"), Fn("failed"), #{ delivery: "all" }
2384            );
2385        }
2386        fn stop_stream(ctx, deps) { () }
2387        fn received(ctx, value) { ctx.set_state("phase", value); }
2388        fn failed(ctx, error) { ctx.set_state("phase", "failed"); }
2389        fn render_StreamProbe(ctx, props) {
2390            effect("watch", (), Fn("start_stream"), Fn("stop_stream"));
2391            text(ctx.get_state("phase"))
2392        }
2393        fn view(ctx) { render_component("test/stream", #{ key: "stream" }) }
2394    "#;
2395
2396    #[test]
2397    fn a_duplicate_key_reports_script_positions_and_an_error_boundary_contains_it() {
2398        let mount = |source: &str| {
2399            let mut engine = RuntimeEngine::new();
2400            let compiled = engine.compile(source).unwrap();
2401            let mut lifecycle = ScriptLifecycle::new(
2402                compiled,
2403                Rc::new(RefCell::new(UiRuntimeState::new())),
2404                ComponentInstancePath::root("App", "root"),
2405                Some("main".to_owned()),
2406                BTreeMap::new(),
2407                &state_schema(),
2408            )
2409            .unwrap();
2410            lifecycle.start(&mut engine).cloned()
2411        };
2412        let rows = r#"column([
2413            text("a").with_key("same"),
2414            text("b").with_key("same"),
2415        ]).with_key("list")"#;
2416        let error = mount(&format!(
2417            "fn view(ctx) {{ column([{rows}]).with_key(\"page\") }}"
2418        ))
2419        .unwrap_err()
2420        .to_string();
2421        assert!(
2422            error.contains(
2423                "duplicate key `same` in child group `children` of page > list, \
2424                 created at ui/main.rhai:2:13 and ui/main.rhai:3:13"
2425            ),
2426            "{error}"
2427        );
2428
2429        let root = mount(&format!(
2430            "fn view(ctx) {{ column([error_boundary({rows}, text(\"fallback\")), \
2431             text(\"kept\")]).with_key(\"page\") }}"
2432        ))
2433        .unwrap();
2434        let crate::UiNodeKind::Box { children } = root.kind() else {
2435            panic!("the page renders");
2436        };
2437        assert!(
2438            matches!(children[0].kind(), crate::UiNodeKind::Text { text } if text == "fallback")
2439        );
2440        assert!(children[0].attributes().contains_key("boundary_error"));
2441        assert!(matches!(children[1].kind(), crate::UiNodeKind::Text { text } if text == "kept"));
2442    }
2443
2444    #[test]
2445    fn lifecycle_order_and_optional_functions_are_enforced() {
2446        let mut engine = RuntimeEngine::new();
2447        let compiled = engine
2448            .compile(
2449                r#"
2450                    fn init(ctx) { ctx.set_state("phase", "initialized"); }
2451                    fn view(ctx) { text(ctx.get_state("phase")) }
2452                    fn dispose(ctx) { ctx.set_state("phase", "disposed"); }
2453                "#,
2454            )
2455            .unwrap();
2456        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
2457        let path = ComponentInstancePath::root("App", "root");
2458        let mut lifecycle = ScriptLifecycle::new(
2459            compiled,
2460            Rc::clone(&runtime),
2461            path.clone(),
2462            Some("main".to_owned()),
2463            BTreeMap::new(),
2464            &state_schema(),
2465        )
2466        .unwrap();
2467
2468        assert!(matches!(
2469            lifecycle.render(&mut engine),
2470            Err(LifecycleError::InvalidTransition { .. })
2471        ));
2472        let root = lifecycle.start(&mut engine).unwrap();
2473        assert!(matches!(
2474            root.kind(),
2475            crate::UiNodeKind::Text { text } if text == "initialized"
2476        ));
2477        assert!(root.source().is_some());
2478        let reconcile = runtime
2479            .borrow()
2480            .traces
2481            .snapshot()
2482            .into_iter()
2483            .find(|trace| trace.kind == crate::RuntimeTraceKind::Reconcile)
2484            .expect("successful initial render must trace retained mutations");
2485        assert!(reconcile.message.contains("full: mounted=1"));
2486        assert!(matches!(reconcile.payload, Some(UiValue::Map(_))));
2487        lifecycle.dispose(&mut engine).unwrap();
2488        assert_eq!(lifecycle.state(), LifecycleState::Disposed);
2489        assert_eq!(
2490            runtime.borrow().component_state.get(&path, "phase"),
2491            Some(&UiValue::String("disposed".to_owned()))
2492        );
2493        assert!(matches!(
2494            lifecycle.dispose(&mut engine),
2495            Err(LifecycleError::InvalidTransition { .. })
2496        ));
2497    }
2498
2499    #[test]
2500    fn lifecycle_motion_uses_the_host_runtime_clock() {
2501        let mut engine = RuntimeEngine::new();
2502        let compiled = engine
2503            .compile(
2504                r#"
2505                    fn view(ctx) {
2506                        text("clocked")
2507                            .with_key("probe")
2508                            .motion(motion_transition("width", 0.0, 100.0, #{ duration_ms: 100, easing: "linear" }))
2509                    }
2510                "#,
2511            )
2512            .unwrap();
2513        let start = Instant::now();
2514        let manual = crate::ManualRuntimeClock::new(start);
2515        let mut runtime_state = UiRuntimeState::new();
2516        runtime_state.clock = manual.clock();
2517        let runtime = Rc::new(RefCell::new(runtime_state));
2518        let mut lifecycle = ScriptLifecycle::new(
2519            compiled,
2520            Rc::clone(&runtime),
2521            ComponentInstancePath::root("App", "root"),
2522            Some("main".to_owned()),
2523            BTreeMap::new(),
2524            &ComponentStateSchema::default(),
2525        )
2526        .unwrap();
2527
2528        lifecycle.start(&mut engine).unwrap();
2529        assert_eq!(
2530            runtime
2531                .borrow()
2532                .motion_values
2533                .values()
2534                .copied()
2535                .collect::<Vec<_>>(),
2536            vec![0.0]
2537        );
2538
2539        manual.advance(Duration::from_millis(50));
2540        let mut runtime = runtime.borrow_mut();
2541        let now = runtime.clock.now();
2542        let frame = runtime.motions.tick(now);
2543        assert_eq!(
2544            frame.values.values().copied().collect::<Vec<_>>(),
2545            vec![50.0]
2546        );
2547    }
2548
2549    #[test]
2550    fn reload_migrates_timeline_authority_to_the_candidate_generation() {
2551        let source = r#"
2552            fn view(ctx) {
2553                text("x").with_key("x").timeline(motion_timeline("intro",
2554                    motion_track(".", motion_transition("opacity", 0.0, 1.0,
2555                        #{ duration_ms: 1000, easing: "linear" })), #{}))
2556            }
2557        "#;
2558        let mut engine = RuntimeEngine::new();
2559        let compiled = engine.compile(source).unwrap();
2560        let now = Instant::now();
2561        let manual = crate::ManualRuntimeClock::new(now);
2562        let mut state = UiRuntimeState::new();
2563        state.clock = manual.clock();
2564        let runtime = Rc::new(RefCell::new(state));
2565        let mut lifecycle = ScriptLifecycle::new(
2566            compiled,
2567            Rc::clone(&runtime),
2568            ComponentInstancePath::root("View", "reload"),
2569            Some("window".to_owned()),
2570            BTreeMap::new(),
2571            &ComponentStateSchema::default(),
2572        )
2573        .unwrap()
2574        .with_view_id("reload");
2575        lifecycle.start(&mut engine).unwrap();
2576        let old = lifecycle
2577            .context(ExecutionPhase::Event)
2578            .motion_handle("intro")
2579            .unwrap();
2580        manual.advance(Duration::from_millis(250));
2581        let generation = lifecycle.generation();
2582        let rejected = engine
2583            .compile(r#"fn view(ctx) { throw "reload rejected"; }"#)
2584            .unwrap();
2585        assert!(
2586            lifecycle
2587                .reload(&mut engine, rejected, &ComponentStateSchema::default(),)
2588                .is_err()
2589        );
2590        assert_eq!(lifecycle.generation(), generation);
2591        assert_eq!(
2592            runtime.borrow().motions.timeline_state(&old),
2593            Some(crate::MotionPlaybackState::Playing)
2594        );
2595        let candidate = engine.compile(source).unwrap();
2596        lifecycle
2597            .reload(&mut engine, candidate, &ComponentStateSchema::default())
2598            .unwrap();
2599        let current = lifecycle
2600            .context(ExecutionPhase::Event)
2601            .motion_handle("intro")
2602            .unwrap();
2603        assert_ne!(old, current);
2604        assert_eq!(runtime.borrow().motions.timeline_state(&old), None);
2605        assert_eq!(
2606            runtime.borrow().motions.timeline_state(&current),
2607            Some(crate::MotionPlaybackState::Playing)
2608        );
2609        assert!(
2610            (runtime
2611                .borrow()
2612                .motions
2613                .snapshot(manual.clock().now())
2614                .values()
2615                .next()
2616                .copied()
2617                .unwrap()
2618                - 0.25)
2619                .abs()
2620                < 0.01
2621        );
2622    }
2623
2624    #[test]
2625    #[allow(clippy::too_many_lines)]
2626    fn resume_reload_unfreezes_motion_at_the_preserved_position() {
2627        let source = r#"
2628            fn view(ctx) {
2629                text("x").with_key("x").motion(motion_transition(
2630                    "width", 0.0, 100.0, #{ duration_ms: 1000, easing: "linear" }))
2631            }
2632        "#;
2633        let source_with_new_motion = r#"
2634            fn view(ctx) {
2635                text("x").with_key("x")
2636                    .motion(motion_transition("width", 0.0, 100.0,
2637                        #{ duration_ms: 1000, easing: "linear" }))
2638                    .motion(motion_transition("opacity", 0.0, 1.0,
2639                        #{ duration_ms: 1000, easing: "linear" }))
2640            }
2641        "#;
2642        let mut engine = RuntimeEngine::new();
2643        let compiled = engine.compile(source).unwrap();
2644        let now = Instant::now();
2645        let manual = crate::ManualRuntimeClock::new(now);
2646        let mut state = UiRuntimeState::new();
2647        state.clock = manual.clock();
2648        let runtime = Rc::new(RefCell::new(state));
2649        let mut lifecycle = ScriptLifecycle::new(
2650            compiled,
2651            Rc::clone(&runtime),
2652            ComponentInstancePath::root("View", "resume-reload"),
2653            Some("window".to_owned()),
2654            BTreeMap::new(),
2655            &ComponentStateSchema::default(),
2656        )
2657        .unwrap()
2658        .with_view_id("resume-reload");
2659        lifecycle.start(&mut engine).unwrap();
2660        let node = lifecycle.retained().root_id().unwrap();
2661        let geometry = runtime.borrow().geometry_for(Some("resume-reload"));
2662        let old_bounds = crate::GeometryBounds::new(0.0, 0.0, 100.0, 20.0).unwrap();
2663        let target_bounds = crate::GeometryBounds::new(100.0, 0.0, 100.0, 20.0).unwrap();
2664        geometry.update(
2665            node,
2666            crate::ElementGeometry {
2667                layout: old_bounds,
2668                visual: old_bounds,
2669                clip: None,
2670            },
2671        );
2672        let layout_request = |now| crate::geometry::LayoutMotionRequest {
2673            shared: None,
2674            duration: Duration::from_secs(1),
2675            easing: crate::MotionEasing::Linear,
2676            preference: crate::MotionPreference::Normal,
2677            now,
2678        };
2679        let _ = geometry.sample_layout_motion(node, target_bounds, layout_request(now));
2680        let trigger = crate::MotionProgressBinding::new(
2681            crate::MotionProgressDriver::Hover,
2682            crate::MotionSource::Transition(crate::MotionTransition::new(
2683                crate::MotionProperty::Opacity,
2684                0.0,
2685                1.0,
2686                1_000,
2687            )),
2688        )
2689        .unwrap();
2690        geometry.set_motion_trigger(node, crate::MotionProgressDriver::Hover, true);
2691        let _ =
2692            geometry.sample_motion_trigger(node, &trigger, crate::MotionPreference::Normal, now);
2693        manual.advance(Duration::from_millis(200));
2694        let before_layout = geometry.sample_layout_motion(
2695            node,
2696            target_bounds,
2697            layout_request(manual.clock().now()),
2698        );
2699        let before_trigger = geometry.sample_motion_trigger(
2700            node,
2701            &trigger,
2702            crate::MotionPreference::Normal,
2703            manual.clock().now(),
2704        );
2705        lifecycle.suspend(&mut engine).unwrap();
2706        manual.advance(Duration::from_millis(500));
2707        let rejected = engine
2708            .compile(r#"fn view(ctx) { throw "resume reload rejected"; }"#)
2709            .unwrap();
2710        assert!(
2711            lifecycle
2712                .resume_reload(&mut engine, rejected, &ComponentStateSchema::default(),)
2713                .is_err()
2714        );
2715        assert_eq!(lifecycle.state(), LifecycleState::Suspended);
2716        {
2717            let mut runtime = runtime.borrow_mut();
2718            let frame = runtime.motions.tick(manual.clock().now());
2719            assert!(!frame.needs_frame);
2720            assert!((frame.values.values().next().copied().unwrap() - 20.0).abs() < 0.01);
2721        }
2722        let candidate = engine.compile(source_with_new_motion).unwrap();
2723        lifecycle
2724            .resume_reload(&mut engine, candidate, &ComponentStateSchema::default())
2725            .unwrap();
2726        let resumed_layout = geometry.sample_layout_motion(
2727            node,
2728            target_bounds,
2729            layout_request(manual.clock().now()),
2730        );
2731        let resumed_trigger = geometry.sample_motion_trigger(
2732            node,
2733            &trigger,
2734            crate::MotionPreference::Normal,
2735            manual.clock().now(),
2736        );
2737        assert!((resumed_layout.offset_x - before_layout.offset_x).abs() < 0.01);
2738        assert!((resumed_trigger.value - before_trigger.value).abs() < 0.01);
2739        manual.advance(Duration::from_millis(200));
2740        let mut runtime = runtime.borrow_mut();
2741        let frame = runtime.motions.tick(manual.clock().now());
2742        assert!(frame.needs_frame);
2743        assert!(frame.values.iter().any(|(key, value)| {
2744            key.property == crate::MotionProperty::Width && (*value - 40.0).abs() < 0.01
2745        }));
2746        assert!(frame.values.iter().any(|(key, value)| {
2747            key.property == crate::MotionProperty::Opacity && (*value - 0.2).abs() < 0.01
2748        }));
2749        drop(runtime);
2750        let advanced_layout = geometry.sample_layout_motion(
2751            node,
2752            target_bounds,
2753            layout_request(manual.clock().now()),
2754        );
2755        let advanced_trigger = geometry.sample_motion_trigger(
2756            node,
2757            &trigger,
2758            crate::MotionPreference::Normal,
2759            manual.clock().now(),
2760        );
2761        assert!(advanced_layout.offset_x > resumed_layout.offset_x);
2762        assert!(advanced_trigger.value > resumed_trigger.value);
2763    }
2764
2765    #[test]
2766    fn retained_root_remount_allocates_new_motion_identity() {
2767        let source = r#"
2768            fn view(ctx) {
2769                text("card").with_key(if ctx.get_state("second") { "two" } else { "one" })
2770                    .timeline(motion_timeline("intro", motion_track(".",
2771                        motion_transition("opacity", 0.0, 1.0,
2772                            #{ duration_ms: 1000, easing: "linear" })), #{}))
2773            }
2774        "#;
2775        let schema = ComponentStateSchema::new(BTreeMap::from([(
2776            "second".to_owned(),
2777            StateField::new(ValueSchema::Bool, UiValue::Bool(false)),
2778        )]))
2779        .unwrap();
2780        let mut engine = RuntimeEngine::new();
2781        let compiled = engine.compile(source).unwrap();
2782        let now = Instant::now();
2783        let manual = crate::ManualRuntimeClock::new(now);
2784        let mut state = UiRuntimeState::new();
2785        state.clock = manual.clock();
2786        let runtime = Rc::new(RefCell::new(state));
2787        let root = ComponentInstancePath::root("View", "remount");
2788        let mut lifecycle = ScriptLifecycle::new(
2789            compiled,
2790            Rc::clone(&runtime),
2791            root.clone(),
2792            Some("window".to_owned()),
2793            BTreeMap::new(),
2794            &schema,
2795        )
2796        .unwrap()
2797        .with_view_id("remount");
2798        lifecycle.start(&mut engine).unwrap();
2799        let old_node = lifecycle.retained().root_id().unwrap();
2800        let old_handle = lifecycle
2801            .context(ExecutionPhase::Event)
2802            .motion_handle("intro")
2803            .unwrap();
2804        manual.advance(Duration::from_millis(500));
2805        runtime
2806            .borrow_mut()
2807            .set_component_state_from_host(&root, "second", UiValue::Bool(true))
2808            .unwrap();
2809        lifecycle.render_dirty(&mut engine).unwrap();
2810        let new_node = lifecycle.retained().root_id().unwrap();
2811        let new_handle = lifecycle
2812            .context(ExecutionPhase::Event)
2813            .motion_handle("intro")
2814            .unwrap();
2815        assert_ne!(old_node, new_node);
2816        assert_ne!(old_handle, new_handle);
2817        assert_eq!(runtime.borrow().motions.timeline_state(&old_handle), None);
2818        assert!(
2819            runtime
2820                .borrow()
2821                .motions
2822                .snapshot(manual.clock().now())
2823                .values()
2824                .next()
2825                .copied()
2826                .unwrap()
2827                .abs()
2828                < f64::EPSILON
2829        );
2830    }
2831
2832    #[test]
2833    fn geometry_motion_reserves_capacity_from_timeline_control() {
2834        let mut engine = RuntimeEngine::new();
2835        let compiled = engine
2836            .compile(
2837                r#"
2838                    fn view(ctx) {
2839                        text("card").with_key("card")
2840                            .layout_motion(100, "linear")
2841                            .timeline(motion_timeline("intro", motion_track(".",
2842                                motion_transition("opacity", 0.0, 1.0,
2843                                    #{ duration_ms: 100 })), #{ autoplay: false }))
2844                    }
2845                "#,
2846            )
2847            .unwrap();
2848        let mut state = UiRuntimeState::new();
2849        state.budgets.active_motions = 1;
2850        let runtime = Rc::new(RefCell::new(state));
2851        let mut lifecycle = ScriptLifecycle::new(
2852            compiled,
2853            Rc::clone(&runtime),
2854            ComponentInstancePath::root("View", "budget"),
2855            None,
2856            BTreeMap::new(),
2857            &ComponentStateSchema::default(),
2858        )
2859        .unwrap();
2860        lifecycle.start(&mut engine).unwrap();
2861        let context = lifecycle.context(ExecutionPhase::Event);
2862        let handle = context.motion_handle("intro").unwrap();
2863        assert!(matches!(
2864            context.play_motion(&handle),
2865            Err(crate::UiContextError::Motion(
2866                crate::MotionError::ActiveBudget {
2867                    actual: 2,
2868                    limit: 1,
2869                }
2870            ))
2871        ));
2872    }
2873
2874    #[test]
2875    fn motion_budget_admits_active_timeline_to_idle_plus_direct_replacement() {
2876        let source = r#"
2877            fn view(ctx) {
2878                let switching = ctx.get_state("go");
2879                let node = text("card").with_key("card").timeline(motion_timeline(
2880                    "intro", motion_track(".", motion_transition("opacity", 0.0, 1.0,
2881                        #{ duration_ms: 1000 })), #{ autoplay: !switching }));
2882                if switching {
2883                    node.motion(motion_transition("width", 0.0, 100.0,
2884                        #{ duration_ms: 1000 }))
2885                } else {
2886                    node
2887                }
2888            }
2889        "#;
2890        let schema = ComponentStateSchema::new(BTreeMap::from([(
2891            "go".to_owned(),
2892            StateField::new(ValueSchema::Bool, UiValue::Bool(false)),
2893        )]))
2894        .unwrap();
2895        let mut engine = RuntimeEngine::new();
2896        let compiled = engine.compile(source).unwrap();
2897        let mut state = UiRuntimeState::new();
2898        state.budgets.active_motions = 1;
2899        let runtime = Rc::new(RefCell::new(state));
2900        let root = ComponentInstancePath::root("View", "budget-replacement");
2901        let mut lifecycle = ScriptLifecycle::new(
2902            compiled,
2903            Rc::clone(&runtime),
2904            root.clone(),
2905            None,
2906            BTreeMap::new(),
2907            &schema,
2908        )
2909        .unwrap();
2910        lifecycle.start(&mut engine).unwrap();
2911        runtime
2912            .borrow_mut()
2913            .set_component_state_from_host(&root, "go", UiValue::Bool(true))
2914            .unwrap();
2915        assert!(lifecycle.render_dirty(&mut engine).unwrap());
2916        assert_eq!(runtime.borrow().motions.resource_usage().active, 1);
2917        let handle = lifecycle
2918            .context(ExecutionPhase::Event)
2919            .motion_handle("intro")
2920            .unwrap();
2921        assert_eq!(
2922            runtime.borrow().motions.timeline_state(&handle),
2923            Some(crate::MotionPlaybackState::Idle)
2924        );
2925    }
2926
2927    #[test]
2928    fn virtual_item_motion_uses_the_stable_data_key_path() {
2929        let mut engine = RuntimeEngine::new();
2930        let compiled = engine
2931            .compile(
2932                r#"
2933                    fn render_row(ctx, props) {
2934                        text("A").with_key(props.key)
2935                            .motion(motion_transition("opacity", 0.0, 1.0,
2936                                #{ duration_ms: 1000 }))
2937                    }
2938                    fn view(ctx) {
2939                        virtual_collection(#{
2940                            key: "list",
2941                            data: [#{ key: "alpha" }],
2942                            height: 100,
2943                            estimated_height: 20
2944                        }, Fn("render_row"))
2945                    }
2946                "#,
2947            )
2948            .unwrap();
2949        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
2950        let mut lifecycle = ScriptLifecycle::new(
2951            compiled,
2952            Rc::clone(&runtime),
2953            ComponentInstancePath::root("View", "virtual"),
2954            None,
2955            BTreeMap::new(),
2956            &ComponentStateSchema::default(),
2957        )
2958        .unwrap();
2959        lifecycle.start(&mut engine).unwrap();
2960
2961        let values = runtime.borrow().motions.snapshot(Instant::now());
2962        let item = lifecycle
2963            .retained()
2964            .nodes()
2965            .find(|node| node.key() == Some("alpha"))
2966            .unwrap()
2967            .id();
2968        assert!(values.contains_key(&crate::MotionKey::for_node(
2969            &crate::motion::retained_node_path("root", item),
2970            crate::MotionProperty::Opacity,
2971        )));
2972        assert_eq!(values.len(), 1);
2973    }
2974
2975    #[test]
2976    fn exit_ghost_uses_the_views_committed_geometry_domain() {
2977        let mut engine = RuntimeEngine::new();
2978        let compiled = engine
2979            .compile(
2980                r#"
2981                    fn view(ctx) {
2982                        let children = [text(ctx.get_state("n").to_string()).with_key("counter")];
2983                        if ctx.get_state("visible") {
2984                            children.push(text("gone").with_key("panel")
2985                                .exit_motion(motion_transition("opacity", 1.0, 0.0,
2986                                    #{ duration_ms: 1000, easing: "linear" })))
2987                        }
2988                        column(children)
2989                    }
2990                "#,
2991            )
2992            .unwrap();
2993        let manual = crate::ManualRuntimeClock::new(Instant::now());
2994        let mut state = UiRuntimeState::new();
2995        state.clock = manual.clock();
2996        let runtime = Rc::new(RefCell::new(state));
2997        let root = ComponentInstancePath::root("View", "v");
2998        let schema = ComponentStateSchema::new(BTreeMap::from([
2999            (
3000                "visible".to_owned(),
3001                StateField::new(ValueSchema::Bool, UiValue::Bool(true)),
3002            ),
3003            (
3004                "n".to_owned(),
3005                StateField::new(ValueSchema::integer(), UiValue::Integer(0)),
3006            ),
3007        ]))
3008        .unwrap();
3009        let mut lifecycle = ScriptLifecycle::new(
3010            compiled,
3011            Rc::clone(&runtime),
3012            root.clone(),
3013            Some("w".to_owned()),
3014            BTreeMap::new(),
3015            &schema,
3016        )
3017        .unwrap()
3018        .with_view_id("v");
3019        lifecycle.start(&mut engine).unwrap();
3020        let panel = lifecycle
3021            .retained()
3022            .nodes()
3023            .find(|node| node.key() == Some("panel"))
3024            .unwrap()
3025            .id();
3026        let bounds = crate::GeometryBounds::new(0.0, 0.0, 100.0, 20.0).unwrap();
3027        runtime.borrow_mut().presentation_geometry("v").update(
3028            panel,
3029            crate::ElementGeometry {
3030                layout: bounds,
3031                visual: bounds,
3032                clip: None,
3033            },
3034        );
3035        runtime
3036            .borrow_mut()
3037            .set_component_state_from_host(&root, "visible", UiValue::Bool(false))
3038            .unwrap();
3039        lifecycle.render_dirty(&mut engine).unwrap();
3040
3041        let ghost_path = {
3042            let runtime = runtime.borrow();
3043            assert_eq!(runtime.motion_ghosts.len(), 1);
3044            assert_eq!(runtime.motion_ghosts[0].domain, "window:w/view:v/root");
3045            assert_eq!(runtime.motion_ghosts[0].bounds, bounds);
3046            assert!(
3047                runtime.motion_ghosts[0]
3048                    .path
3049                    .starts_with("window:w/view:v/root/ghost:")
3050            );
3051            assert!(runtime.motions.resource_usage().active > 0);
3052            runtime.motion_ghosts[0].path.clone()
3053        };
3054        manual.advance(Duration::from_millis(100));
3055        runtime
3056            .borrow_mut()
3057            .set_component_state_from_host(&root, "n", UiValue::Integer(1))
3058            .unwrap();
3059        lifecycle.render_dirty(&mut engine).unwrap();
3060        assert_eq!(runtime.borrow().motions.resource_usage().active, 1);
3061        assert!(
3062            (runtime.borrow().motions.snapshot(manual.clock().now())
3063                [&crate::MotionKey::for_node(&ghost_path, crate::MotionProperty::Opacity,)]
3064                - 0.9)
3065                .abs()
3066                < 0.01
3067        );
3068        let now = manual.clock().now();
3069        let frame = runtime
3070            .borrow_mut()
3071            .motions
3072            .tick_scope(now + Duration::from_millis(900), "window:w/view:v/root");
3073        assert!(frame.completed.contains(&crate::MotionKey::for_node(
3074            &ghost_path,
3075            crate::MotionProperty::Opacity,
3076        )));
3077    }
3078
3079    #[test]
3080    fn suspend_resume_preserves_state_and_freezes_motion_time() {
3081        let mut engine = RuntimeEngine::new();
3082        let compiled = engine
3083            .compile(
3084                r#"
3085                    fn suspend(ctx) { ctx.set_state("phase", "suspended"); }
3086                    fn resume(ctx, elapsed_ms) {
3087                        ctx.set_state("phase", "resumed");
3088                        ctx.set_state("elapsed", elapsed_ms);
3089                    }
3090                    fn view(ctx) {
3091                        text(ctx.get_state("phase")).with_key("probe")
3092                            .motion(motion_transition("width", 0.0, 100.0, #{ duration_ms: 100, easing: "linear" }))
3093                    }
3094                "#,
3095            )
3096            .unwrap();
3097        let start = Instant::now();
3098        let manual = crate::ManualRuntimeClock::new(start);
3099        let mut runtime_state = UiRuntimeState::new();
3100        runtime_state.clock = manual.clock();
3101        let runtime = Rc::new(RefCell::new(runtime_state));
3102        let path = ComponentInstancePath::root("App", "root");
3103        let schema = ComponentStateSchema::new(BTreeMap::from([
3104            (
3105                "phase".to_owned(),
3106                StateField::new(ValueSchema::string(), UiValue::String("active".to_owned())),
3107            ),
3108            (
3109                "elapsed".to_owned(),
3110                StateField::new(ValueSchema::integer(), UiValue::Integer(0)),
3111            ),
3112        ]))
3113        .unwrap();
3114        let mut lifecycle = ScriptLifecycle::new(
3115            compiled,
3116            Rc::clone(&runtime),
3117            path.clone(),
3118            Some("main".to_owned()),
3119            BTreeMap::new(),
3120            &schema,
3121        )
3122        .unwrap();
3123        lifecycle.start(&mut engine).unwrap();
3124        manual.advance(Duration::from_millis(50));
3125        {
3126            let mut runtime = runtime.borrow_mut();
3127            let now = runtime.clock.now();
3128            runtime.motion_values = runtime.motions.tick(now).values;
3129        }
3130        let before = *runtime.borrow().motion_values.values().next().unwrap();
3131        assert!(lifecycle.suspend(&mut engine).unwrap());
3132        assert_eq!(lifecycle.state(), LifecycleState::Suspended);
3133        assert_eq!(
3134            runtime.borrow().component_state.get(&path, "phase"),
3135            Some(&UiValue::String("suspended".to_owned()))
3136        );
3137        assert!(!lifecycle.suspend(&mut engine).unwrap());
3138
3139        manual.advance(Duration::from_secs(1));
3140        {
3141            let mut runtime = runtime.borrow_mut();
3142            let now = runtime.clock.now();
3143            let frame = runtime.motions.tick(now);
3144            assert!(
3145                !frame.needs_frame,
3146                "a suspended scope must not keep another window's frame loop alive"
3147            );
3148            runtime.motion_values = frame.values;
3149        }
3150        assert!(
3151            (before - *runtime.borrow().motion_values.values().next().unwrap()).abs() < 0.001,
3152            "a shared runtime tick must not advance a suspended scope"
3153        );
3154        assert!(lifecycle.resume(&mut engine).unwrap());
3155        assert_eq!(lifecycle.state(), LifecycleState::Running);
3156        assert_eq!(
3157            runtime.borrow().component_state.get(&path, "elapsed"),
3158            Some(&UiValue::Integer(1_000))
3159        );
3160        let after = *runtime.borrow().motion_values.values().next().unwrap();
3161        assert!(
3162            (before - after).abs() < 0.001,
3163            "animation advanced while suspended"
3164        );
3165        assert!(!lifecycle.resume(&mut engine).unwrap());
3166    }
3167
3168    #[test]
3169    fn suspended_reload_migrates_atomically_and_keeps_last_good_on_failure() {
3170        let mut engine = RuntimeEngine::new();
3171        let active = engine
3172            .compile(
3173                r#"
3174                    fn suspend(ctx) { ctx.set_state("phase", "parked"); }
3175                    fn view(ctx) { text(ctx.get_state("phase")) }
3176                "#,
3177            )
3178            .unwrap();
3179        let active_generation = active.generation();
3180        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3181        let path = ComponentInstancePath::root("App", "root");
3182        let mut lifecycle = ScriptLifecycle::new(
3183            active,
3184            Rc::clone(&runtime),
3185            path.clone(),
3186            Some("main".to_owned()),
3187            BTreeMap::new(),
3188            &state_schema(),
3189        )
3190        .unwrap();
3191        lifecycle.start(&mut engine).unwrap();
3192        lifecycle.suspend(&mut engine).unwrap();
3193
3194        let rejected = engine
3195            .compile(
3196                r#"
3197                    fn init(ctx) { ctx.set_state("phase", "candidate-init"); }
3198                    fn resume(ctx, elapsed_ms) { throw "candidate resume failed"; }
3199                    fn view(ctx) { text(ctx.get_state("phase")) }
3200                "#,
3201            )
3202            .unwrap();
3203        assert!(
3204            lifecycle
3205                .resume_reload(&mut engine, rejected, &state_schema())
3206                .is_err()
3207        );
3208        assert_eq!(lifecycle.state(), LifecycleState::Suspended);
3209        assert_eq!(lifecycle.generation(), active_generation);
3210        assert_eq!(
3211            runtime.borrow().component_state.get(&path, "phase"),
3212            Some(&UiValue::String("parked".to_owned()))
3213        );
3214
3215        let accepted = engine
3216            .compile(
3217                r#"
3218                    fn init(ctx) { ctx.set_state("phase", "candidate-init"); }
3219                    fn resume(ctx, elapsed_ms) { ctx.set_state("phase", "candidate-resumed"); }
3220                    fn view(ctx) { text(ctx.get_state("phase")) }
3221                "#,
3222            )
3223            .unwrap();
3224        let accepted_generation = accepted.generation();
3225        lifecycle
3226            .resume_reload(&mut engine, accepted, &state_schema())
3227            .unwrap();
3228        assert_eq!(lifecycle.state(), LifecycleState::Running);
3229        assert_eq!(lifecycle.generation(), accepted_generation);
3230        assert_eq!(
3231            runtime.borrow().component_state.get(&path, "phase"),
3232            Some(&UiValue::String("candidate-resumed".to_owned()))
3233        );
3234    }
3235
3236    #[test]
3237    fn a_realization_in_a_motion_group_keeps_the_items_it_kept() {
3238        let mut engine = RuntimeEngine::new();
3239        let compiled = engine
3240            .compile(
3241                r#"
3242                    fn render_item(ctx, payload) {
3243                        text(payload.item.label).with_key(payload.key)
3244                            .shared_layout(payload.key)
3245                    }
3246                    fn view(ctx) {
3247                        let data = [];
3248                        for index in 0..32 {
3249                            data.push(#{ key: `row-${index}`, label: `Row ${index}` });
3250                        }
3251                        motion_group("rows", [virtual_collection(#{
3252                            key: "rows", label: "Rows", data: data,
3253                            estimated_height: 24, height: 96,
3254                            overdraw_pixels: 24, alignment: "top", follow_tail: false,
3255                            batch_items: 1, retain_items: 0
3256                        }, Fn("render_item"))])
3257                    }
3258                "#,
3259            )
3260            .unwrap();
3261        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3262        let path = ComponentInstancePath::root("App", "root");
3263        let mut lifecycle = ScriptLifecycle::new(
3264            compiled,
3265            Rc::clone(&runtime),
3266            path.clone(),
3267            Some("main".to_owned()),
3268            BTreeMap::new(),
3269            &ComponentStateSchema::default(),
3270        )
3271        .unwrap();
3272        lifecycle.start(&mut engine).unwrap();
3273        let id = engine
3274            .virtual_collection_ids_in_scope(&path)
3275            .into_iter()
3276            .next()
3277            .unwrap();
3278        let items = |lifecycle: &ScriptLifecycle| {
3279            lifecycle
3280                .root()
3281                .unwrap()
3282                .virtual_collection_items(&id)
3283                .unwrap()
3284                .clone()
3285        };
3286        let before = items(&lifecycle);
3287        let kept = *before.keys().last().unwrap();
3288        runtime
3289            .borrow()
3290            .virtual_requests
3291            .request(id.clone(), [kept, kept + 1]);
3292        assert!(lifecycle.realize_virtual_requests(&mut engine).unwrap());
3293        let after = items(&lifecycle);
3294        assert!(
3295            after[&kept].ptr_eq(&before[&kept]),
3296            "the kept item was copied"
3297        );
3298        assert_eq!(
3299            after[&(kept + 1)].attributes().get("shared_layout_group"),
3300            Some(&UiValue::String("rows".to_owned()))
3301        );
3302        // Applying the group to a grouped item changes nothing.
3303        let mut again = after[&(kept + 1)].clone();
3304        crate::node::apply_motion_group(&mut again, "rows", None);
3305        assert!(again.ptr_eq(&after[&(kept + 1)]));
3306    }
3307
3308    #[test]
3309    #[allow(clippy::too_many_lines)]
3310    fn virtual_realization_commits_the_complete_target_window_and_prunes_old_items() {
3311        let mut engine = RuntimeEngine::new();
3312        let compiled = engine
3313            .compile(
3314                r#"
3315                    fn render_item(ctx, payload) {
3316                        text(payload.item.label).with_key(payload.key)
3317                    }
3318                    fn view(ctx) {
3319                        let data = [];
3320                        for index in 0..32 {
3321                            data.push(#{ key: `row-${index}`, label: `Row ${index}` });
3322                        }
3323                        virtual_collection(#{
3324                            key: "rows", label: "Rows", data: data,
3325                            estimated_height: 24, height: 96,
3326                            overdraw_pixels: 24, alignment: "top", follow_tail: false,
3327                            batch_items: 1, retain_items: 0
3328                        }, Fn("render_item"))
3329                    }
3330                "#,
3331            )
3332            .unwrap();
3333        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3334        let path = ComponentInstancePath::root("App", "root");
3335        let mut lifecycle = ScriptLifecycle::new(
3336            compiled,
3337            Rc::clone(&runtime),
3338            path.clone(),
3339            Some("main".to_owned()),
3340            BTreeMap::new(),
3341            &ComponentStateSchema::default(),
3342        )
3343        .unwrap();
3344        lifecycle.start(&mut engine).unwrap();
3345        let id = engine
3346            .virtual_collection_ids_in_scope(&path)
3347            .into_iter()
3348            .next()
3349            .unwrap();
3350        let initial_indices = lifecycle
3351            .root()
3352            .unwrap()
3353            .virtual_collection_items(&id)
3354            .unwrap()
3355            .keys()
3356            .copied()
3357            .collect::<Vec<_>>();
3358        let retained = *initial_indices.last().unwrap();
3359        let first_new = retained + 1;
3360        let second_new = first_new + 1;
3361        let _ = engine.take_timings();
3362
3363        runtime
3364            .borrow()
3365            .virtual_requests
3366            .request(id.clone(), [retained, first_new]);
3367        assert!(lifecycle.realize_virtual_requests(&mut engine).unwrap());
3368        assert_eq!(
3369            lifecycle
3370                .root()
3371                .unwrap()
3372                .virtual_collection_items(&id)
3373                .unwrap()
3374                .keys()
3375                .copied()
3376                .collect::<Vec<_>>(),
3377            vec![retained, first_new]
3378        );
3379        let timings = engine.take_timings();
3380        assert_eq!(
3381            timings
3382                .iter()
3383                .filter(|timing| matches!(
3384                    timing.operation,
3385                    ExecutionOperation::VirtualCollection(_)
3386                ))
3387                .count(),
3388            1
3389        );
3390        assert!(timings.iter().all(|timing| timing.operations > 0));
3391
3392        runtime
3393            .borrow()
3394            .virtual_requests
3395            .request(id.clone(), [retained, first_new]);
3396        assert!(!lifecycle.realize_virtual_requests(&mut engine).unwrap());
3397        assert_eq!(
3398            engine.take_timings(),
3399            [] as [crate::engine::ExecutionTiming; 0]
3400        );
3401
3402        runtime
3403            .borrow()
3404            .virtual_requests
3405            .request(id.clone(), [first_new, second_new]);
3406        assert!(lifecycle.realize_virtual_requests(&mut engine).unwrap());
3407        assert_eq!(
3408            lifecycle
3409                .root()
3410                .unwrap()
3411                .virtual_collection_items(&id)
3412                .unwrap()
3413                .keys()
3414                .copied()
3415                .collect::<Vec<_>>(),
3416            vec![first_new, second_new]
3417        );
3418        assert_eq!(
3419            engine
3420                .take_timings()
3421                .iter()
3422                .filter(|timing| matches!(
3423                    timing.operation,
3424                    ExecutionOperation::VirtualCollection(_)
3425                ))
3426                .count(),
3427            1
3428        );
3429    }
3430
3431    #[test]
3432    #[allow(clippy::too_many_lines)]
3433    fn virtual_target_commit_retains_and_releases_the_complete_component_manifest() {
3434        fn counter_callback(node: &UiNode) -> Option<ScriptCallback> {
3435            if let Some(handler) = node.handler("click") {
3436                return handler.as_script().cloned();
3437            }
3438            match node.kind() {
3439                crate::UiNodeKind::Box { children } | crate::UiNodeKind::Fragment { children } => {
3440                    children.iter().find_map(counter_callback)
3441                }
3442                _ => None,
3443            }
3444        }
3445        for (wrapper, row) in [
3446            (
3447                "child",
3448                r#"render_component("test/virtual_counter",#{key:payload.key})"#,
3449            ),
3450            (
3451                "child",
3452                r#"render_component("test/wrapper",#{key:payload.key,depth:0})"#,
3453            ),
3454            (
3455                "child",
3456                r#"render_component("test/wrapper",#{key:payload.key,depth:2})"#,
3457            ),
3458            (
3459                "column([child])",
3460                r#"render_component("test/wrapper",#{key:payload.key,depth:0})"#,
3461            ),
3462        ] {
3463            let mut engine = RuntimeEngine::new();
3464            let source = r#"
3465            define_component(#{
3466                metadata: #{id:"test/virtual_counter", "export":"Counter", version:"0.1.8",
3467                    runtime_api:#{min_inclusive: 3,max_exclusive: 4},dependencies:[],capabilities:#{}},
3468                schema: #{props:#{key:#{schema:#{type:"string"},required:true,sensitive:false}},
3469                    state:#{fields:#{count:#{schema:#{type:"integer"},"default":#{type:"integer",value:7}}}},
3470                    events:#{},slots:#{},parts:[],effects:["keep"]},render:Fn("render_counter")
3471            });
3472            fn read_count(ctx,payload) {ctx.get_state("count")}
3473            fn start(ctx,deps) {()}
3474            fn cleanup(ctx,deps) {()}
3475            fn tick(ctx,value) {()}
3476            fn render_counter(ctx,props) {
3477                effect("keep",(),Fn("start"),Fn("cleanup"));
3478                timeout("tick",1000,false,Fn("tick"),());
3479                let opacity=signal("opacity",1.0);
3480                text(`${ctx.get_state("count")}`).with_key(props.key).bind_signal("opacity",opacity)
3481                    .with_ref(element_ref("counter")).on_click(Fn("read_count"))
3482            }
3483            define_component(#{
3484                metadata:#{id:"test/wrapper","export":"Wrapper",version:"0.1.8",
3485                    runtime_api:#{min_inclusive: 3,max_exclusive: 4},dependencies:[],capabilities:#{}},
3486                schema:#{props:#{key:#{schema:#{type:"string"},required:true,sensitive:false},
3487                    depth:#{schema:#{type:"integer"},required:true,sensitive:false}},
3488                    state:#{fields:#{}},events:#{},slots:#{},parts:[]},render:Fn("render_wrapper")
3489            });
3490            fn render_wrapper(ctx,props) {
3491                let child=if props.depth==0 {
3492                    render_component("test/virtual_counter",#{key:"inner"})
3493                } else {
3494                    render_component("test/wrapper",#{key:"inner",depth:props.depth-1})
3495                };
3496                WRAPPER_BODY
3497            }
3498            fn row(ctx,payload) {
3499                if payload.index==19 {throw "candidate row failed";}
3500                ROW_BODY
3501            }
3502            fn view(ctx) {
3503                let data=[];for index in 0..20 {data.push(#{key:`row-${index}`});}
3504                virtual_collection(#{key:"rows",label:"Rows",data:data,height:24,
3505                    estimated_height:24,overdraw_pixels:0,batch_items:1,retain_items:0},Fn("row"))
3506            }
3507        "#.replace("WRAPPER_BODY",wrapper).replace("ROW_BODY",row);
3508            let compiled = engine.compile(&source).unwrap();
3509            let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3510            let path = ComponentInstancePath::root("App", "manifest");
3511            let mut lifecycle = ScriptLifecycle::new(
3512                compiled,
3513                Rc::clone(&runtime),
3514                path.clone(),
3515                None,
3516                BTreeMap::new(),
3517                &ComponentStateSchema::default(),
3518            )
3519            .unwrap();
3520            lifecycle.start(&mut engine).unwrap();
3521            let id = engine
3522                .virtual_collection_ids_in_scope(&path)
3523                .into_iter()
3524                .next()
3525                .unwrap();
3526            let callback = counter_callback(
3527                &lifecycle
3528                    .root()
3529                    .unwrap()
3530                    .virtual_collection_items(&id)
3531                    .unwrap()[&0],
3532            )
3533            .unwrap();
3534            let child = callback.component().unwrap().clone();
3535            let signal = runtime.borrow().signals.resolve(&child, "opacity").unwrap();
3536            let initial_effects = runtime
3537                .borrow()
3538                .effects
3539                .iter_active()
3540                .filter(|(id, _, _)| id.component() == &child)
3541                .map(|(id, _, activation)| (id.clone(), activation))
3542                .collect::<Vec<_>>();
3543            runtime
3544                .borrow()
3545                .virtual_requests
3546                .request(id.clone(), [0, 10]);
3547            lifecycle.realize_virtual_requests(&mut engine).unwrap();
3548            assert_eq!(
3549                lifecycle
3550                    .invoke_callback(&engine, &callback, UiValue::Null)
3551                    .unwrap()
3552                    .as_int()
3553                    .unwrap(),
3554                7
3555            );
3556            assert_eq!(
3557                runtime
3558                    .borrow()
3559                    .effects
3560                    .iter_active()
3561                    .filter(|(id, _, _)| id.component() == &child)
3562                    .map(|(id, _, activation)| (id.clone(), activation))
3563                    .collect::<Vec<_>>(),
3564                initial_effects
3565            );
3566            assert!(runtime.borrow().signals.read(&signal).is_ok());
3567            assert_eq!(engine.component_timers_in_scope(&child).len(), 1);
3568            assert_eq!(engine.component_element_refs_in_scope(&child).len(), 1);
3569            let event = UiContext::new(
3570                Rc::clone(&runtime),
3571                child.clone(),
3572                None,
3573                ExecutionPhase::Event,
3574                BTreeMap::new(),
3575            );
3576            event
3577                .set_state("count", UiValue::Integer(8).into_dynamic())
3578                .unwrap();
3579            assert!(lifecycle.render_dirty(&mut engine).unwrap());
3580            assert_eq!(
3581                lifecycle
3582                    .invoke_callback(&engine, &callback, UiValue::Null)
3583                    .unwrap()
3584                    .as_int()
3585                    .unwrap(),
3586                8,
3587                "transparent descendants remain executable after scrolling"
3588            );
3589            runtime
3590                .borrow()
3591                .virtual_requests
3592                .request(id.clone(), [0, 10, 19]);
3593            assert!(lifecycle.realize_virtual_requests(&mut engine).is_err());
3594            assert_eq!(
3595                lifecycle
3596                    .root()
3597                    .unwrap()
3598                    .virtual_collection_items(&id)
3599                    .unwrap()
3600                    .keys()
3601                    .copied()
3602                    .collect::<Vec<_>>(),
3603                vec![0, 10]
3604            );
3605            assert!(runtime.borrow().signals.read(&signal).is_ok());
3606            runtime.borrow().virtual_requests.request_target(id, [10]);
3607            lifecycle.realize_virtual_requests(&mut engine).unwrap();
3608            assert!(
3609                runtime
3610                    .borrow()
3611                    .component_state
3612                    .get(&child, "count")
3613                    .is_none()
3614            );
3615            assert!(
3616                lifecycle
3617                    .invoke_callback(&engine, &callback, UiValue::Null)
3618                    .is_err()
3619            );
3620            assert!(runtime.borrow().signals.read(&signal).is_err());
3621            assert!(engine.component_timers_in_scope(&child).is_empty());
3622            assert!(engine.component_element_refs_in_scope(&child).is_empty());
3623            assert!(
3624                !runtime
3625                    .borrow()
3626                    .effects
3627                    .iter()
3628                    .any(|(id, _)| id.component() == &child)
3629            );
3630        }
3631    }
3632
3633    #[test]
3634    #[allow(clippy::too_many_lines)]
3635    fn nested_virtual_targets_preserve_callbacks_snapshots_and_prune_atomically() {
3636        let mut engine = RuntimeEngine::new();
3637        let compiled = engine.compile(r#"
3638            define_component(#{
3639                metadata:#{id:"test/panel","export":"Panel",version:"0.1.8",
3640                    runtime_api:#{min_inclusive: 3,max_exclusive: 4},dependencies:[],capabilities:#{}},
3641                schema:#{props:#{key:#{schema:#{type:"string"},required:true,sensitive:false}},
3642                    state:#{fields:#{count:#{schema:#{type:"integer"},"default":#{type:"integer",value:7}}}},
3643                    events:#{},slots:#{},parts:[]},render:Fn("render_panel")
3644            });
3645            fn data() {let rows=[];for i in 0..20 {rows.push(#{key:`row-${i}`});}rows}
3646            fn read_count(ctx,payload) {ctx.get_state("count")}
3647            fn inner_row(ctx,payload) {
3648                if payload.index==19 {throw "candidate rejected";}
3649                text(payload.key).on_click(Fn("read_count"))
3650            }
3651            fn outer_row(ctx,payload) {
3652                virtual_collection(#{key:`inner-${payload.key}`,label:"Inner",data:data(),height:24,
3653                    estimated_height:24,overdraw_pixels:0,batch_items:1,retain_items:0},Fn("inner_row"))
3654            }
3655            fn render_panel(ctx,props) {
3656                virtual_collection(#{key:"outer",label:"Outer",data:data(),height:24,
3657                    estimated_height:24,overdraw_pixels:0,batch_items:1,retain_items:0},Fn("outer_row"))
3658            }
3659            fn view(ctx) {column([text(`${ctx.get_state("other")}`),render_component("test/panel",#{key:"panel"})])}
3660        "#).unwrap();
3661        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3662        let path = ComponentInstancePath::root("App", "nested");
3663        let schema = ComponentStateSchema::new(BTreeMap::from([(
3664            "other".into(),
3665            crate::StateField::new(crate::ValueSchema::integer(), UiValue::Integer(0)),
3666        )]))
3667        .unwrap();
3668        let mut lifecycle = ScriptLifecycle::new(
3669            compiled,
3670            Rc::clone(&runtime),
3671            path.clone(),
3672            None,
3673            BTreeMap::new(),
3674            &schema,
3675        )
3676        .unwrap();
3677        lifecycle.start(&mut engine).unwrap();
3678        let panel = path.child("Panel", "panel");
3679        let ids = engine.virtual_collection_ids_in_scope(&path);
3680        let outer = ids.iter().find(|id| id.key == "outer").unwrap().clone();
3681        let inner = ids
3682            .iter()
3683            .find(|id| id.key == "inner-row-0")
3684            .unwrap()
3685            .clone();
3686        runtime
3687            .borrow()
3688            .virtual_requests
3689            .request_target(inner.clone(), [10]);
3690        lifecycle.realize_virtual_requests(&mut engine).unwrap();
3691        let callback = lifecycle
3692            .root()
3693            .unwrap()
3694            .virtual_collection_items(&inner)
3695            .unwrap()[&10]
3696            .handler("click")
3697            .unwrap()
3698            .as_script()
3699            .unwrap()
3700            .clone();
3701        assert_eq!(callback.component(), Some(&panel));
3702        assert_eq!(
3703            lifecycle
3704                .invoke_callback(&engine, &callback, UiValue::Null)
3705                .unwrap()
3706                .as_int()
3707                .unwrap(),
3708            7
3709        );
3710
3711        // An unrelated root update reuses Panel. Its committed snapshot must
3712        // contain the latest inner target, not the initial seed window.
3713        let context = UiContext::new(
3714            Rc::clone(&runtime),
3715            path,
3716            None,
3717            ExecutionPhase::Event,
3718            BTreeMap::new(),
3719        );
3720        context
3721            .set_state("other", UiValue::Integer(1).into_dynamic())
3722            .unwrap();
3723        lifecycle.render_dirty(&mut engine).unwrap();
3724        assert_eq!(
3725            lifecycle
3726                .root()
3727                .unwrap()
3728                .virtual_collection_items(&inner)
3729                .unwrap()
3730                .keys()
3731                .copied()
3732                .collect::<Vec<_>>(),
3733            vec![10]
3734        );
3735
3736        // Keep the outer row while adding a sibling, then exercise rollback.
3737        runtime
3738            .borrow()
3739            .virtual_requests
3740            .request_target(outer.clone(), [0, 10]);
3741        lifecycle.realize_virtual_requests(&mut engine).unwrap();
3742        assert!(
3743            engine
3744                .virtual_collection_ids_in_scope(&panel)
3745                .contains(&inner)
3746        );
3747        runtime
3748            .borrow()
3749            .virtual_requests
3750            .request_target(inner.clone(), [10, 19]);
3751        assert!(lifecycle.realize_virtual_requests(&mut engine).is_err());
3752        assert_eq!(
3753            lifecycle
3754                .root()
3755                .unwrap()
3756                .virtual_collection_items(&inner)
3757                .unwrap()
3758                .keys()
3759                .copied()
3760                .collect::<Vec<_>>(),
3761            vec![10]
3762        );
3763
3764        // A simultaneous parent prune makes a child request obsolete; it must
3765        // not roll back the parent or recreate the removed collection.
3766        runtime
3767            .borrow()
3768            .virtual_requests
3769            .request_target(outer, [10]);
3770        runtime
3771            .borrow()
3772            .virtual_requests
3773            .request_target(inner.clone(), [11]);
3774        lifecycle.realize_virtual_requests(&mut engine).unwrap();
3775        assert!(
3776            lifecycle
3777                .root()
3778                .unwrap()
3779                .virtual_collection_spec(&inner)
3780                .is_none()
3781        );
3782        assert!(
3783            !engine
3784                .virtual_collection_ids_in_scope(&panel)
3785                .contains(&inner)
3786        );
3787    }
3788
3789    /// 64 rows of 24px in a 96px viewport with one row of overdraw, `EXTRA` appended to
3790    /// the collection's config. Rows from 40 on are a component that owns an effect, and
3791    /// row 50 fails to render. The state `version` renders the collection again.
3792    const RENDER_AHEAD: &str = r#"
3793        define_component(#{
3794            metadata:#{id:"test/ticking","export":"Ticking",version:"0.1.0",
3795                runtime_api:#{min_inclusive: 3,max_exclusive: 4},dependencies:[],capabilities:#{}},
3796            schema:#{props:#{key:#{schema:#{type:"string"},required:true,sensitive:false}},
3797                state:#{fields:#{}},events:#{},slots:#{},parts:[],effects:["tick"]},
3798            render:Fn("render_ticking")
3799        });
3800        fn start(ctx,deps) {()}
3801        fn stop(ctx,deps) {()}
3802        fn render_ticking(ctx,props) {
3803            effect("tick",(),Fn("start"),Fn("stop"));
3804            text("ticking").with_key(props.key)
3805        }
3806        fn row(ctx,payload) {
3807            if payload.index == 50 { throw "row 50 failed"; }
3808            if payload.index >= 40 { render_component("test/ticking",#{key:payload.key}) }
3809            else { text(payload.item.label).with_key(payload.key) }
3810        }
3811        fn view(ctx) {
3812            let version = ctx.get_state("version");
3813            let data=[];
3814            for index in 0..64 {data.push(#{key:`row-${index}`,label:`Row ${index}:${version}`});}
3815            virtual_collection(#{key:"rows",label:"Rows",data:data,height:96,
3816                estimated_height:24,overdraw_pixels:24 EXTRA},Fn("row"))
3817        }
3818    "#;
3819
3820    struct RenderAhead {
3821        engine: RuntimeEngine,
3822        lifecycle: ScriptLifecycle,
3823        runtime: Rc<RefCell<UiRuntimeState>>,
3824        id: crate::VirtualCollectionId,
3825        path: ComponentInstancePath,
3826    }
3827
3828    impl RenderAhead {
3829        fn start(extra: &str, policy: crate::VirtualCollectionPolicy) -> Self {
3830            let mut engine = RuntimeEngine::new();
3831            engine.set_virtual_collection_policy(policy);
3832            let compiled = engine
3833                .compile(&RENDER_AHEAD.replace("EXTRA", extra))
3834                .unwrap();
3835            let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
3836            let path = ComponentInstancePath::root("App", "ahead");
3837            let schema = ComponentStateSchema::new(BTreeMap::from([(
3838                "version".to_owned(),
3839                StateField::new(ValueSchema::integer(), UiValue::Integer(0)),
3840            )]))
3841            .unwrap();
3842            let mut lifecycle = ScriptLifecycle::new(
3843                compiled,
3844                Rc::clone(&runtime),
3845                path.clone(),
3846                Some("main".to_owned()),
3847                BTreeMap::new(),
3848                &schema,
3849            )
3850            .unwrap();
3851            lifecycle.start(&mut engine).unwrap();
3852            let id = engine
3853                .virtual_collection_ids_in_scope(&path)
3854                .into_iter()
3855                .next()
3856                .unwrap();
3857            let _ = engine.take_timings();
3858            Self {
3859                engine,
3860                lifecycle,
3861                runtime,
3862                id,
3863                path,
3864            }
3865        }
3866
3867        fn realized(&self) -> Vec<usize> {
3868            self.lifecycle
3869                .root()
3870                .unwrap()
3871                .virtual_collection_items(&self.id)
3872                .unwrap()
3873                .keys()
3874                .copied()
3875                .collect()
3876        }
3877
3878        /// Ask for `range`, as a frame that needs it does, replacing any pending target;
3879        /// returns the rows the renderer rendered for it.
3880        fn request(&mut self, range: std::ops::Range<usize>) -> usize {
3881            self.runtime
3882                .borrow()
3883                .virtual_requests
3884                .request_target(self.id.clone(), range);
3885            self.lifecycle
3886                .realize_virtual_requests(&mut self.engine)
3887                .unwrap();
3888            self.engine
3889                .take_timings()
3890                .iter()
3891                .filter(|timing| {
3892                    matches!(timing.operation, ExecutionOperation::VirtualCollection(_))
3893                })
3894                .count()
3895        }
3896
3897        fn render_again(&mut self) {
3898            self.runtime
3899                .borrow_mut()
3900                .set_component_state_from_host(&self.path, "version", UiValue::Integer(1))
3901                .unwrap();
3902            assert!(self.lifecycle.render_dirty(&mut self.engine).unwrap());
3903            let _ = self.engine.take_timings();
3904        }
3905    }
3906
3907    #[test]
3908    fn a_commit_keeps_the_requests_of_other_scopes_sharing_the_runtime() {
3909        let mut ahead = RenderAhead::start(
3910            ",batch_items:1,retain_items:0",
3911            crate::VirtualCollectionPolicy::default(),
3912        );
3913        // A window opened from this view shares its runtime and commits on its own.
3914        let theirs = crate::VirtualCollectionId {
3915            component: ComponentInstancePath::root("View", "window"),
3916            key: "rows".to_owned(),
3917        };
3918        ahead
3919            .runtime
3920            .borrow()
3921            .virtual_requests
3922            .request(theirs.clone(), [4]);
3923        assert_eq!(ahead.request(2..8), 2);
3924        let pending = ahead.runtime.borrow().virtual_requests.drain();
3925        assert_eq!(pending.get(&theirs), Some(&BTreeSet::from([4])));
3926    }
3927
3928    #[test]
3929    fn a_scroll_that_needs_new_items_renders_a_batch_beyond_them() {
3930        let mut ahead = RenderAhead::start(
3931            ",batch_items:8,retain_items:0",
3932            crate::VirtualCollectionPolicy::default(),
3933        );
3934        assert_eq!(ahead.realized(), (0..6).collect::<Vec<_>>());
3935        // Rows 6 and 7 are needed; seven more follow them.
3936        assert_eq!(ahead.request(2..8), 9);
3937        assert_eq!(ahead.realized(), (2..15).collect::<Vec<_>>());
3938        // Scrolling back up needs rows 0 and 1, and renders seven above them where there
3939        // are rows: none.
3940        assert_eq!(ahead.request(0..6), 2);
3941        assert_eq!(ahead.realized(), (0..6).collect::<Vec<_>>());
3942    }
3943
3944    #[test]
3945    fn items_leaving_the_range_come_back_without_rendering() {
3946        let mut ahead = RenderAhead::start(
3947            ",batch_items:1,retain_items:32",
3948            crate::VirtualCollectionPolicy::default(),
3949        );
3950        assert_eq!(ahead.request(20..26), 6);
3951        assert_eq!(ahead.request(0..6), 0, "rows 0 to 5 were kept");
3952        assert_eq!(ahead.realized(), (0..6).collect::<Vec<_>>());
3953        let items = ahead
3954            .lifecycle
3955            .root()
3956            .unwrap()
3957            .virtual_collection_items(&ahead.id)
3958            .unwrap()
3959            .clone();
3960        assert!(matches!(items[&3].kind(), UiNodeKind::Text { text } if text == "Row 3:0"));
3961        assert_eq!(ahead.request(20..26), 0, "and so were rows 20 to 25");
3962    }
3963
3964    #[test]
3965    fn kept_items_are_dropped_when_the_collection_renders_again() {
3966        let mut ahead = RenderAhead::start(
3967            ",batch_items:1,retain_items:32",
3968            crate::VirtualCollectionPolicy::default(),
3969        );
3970        assert_eq!(ahead.request(20..26), 6);
3971        assert_eq!(ahead.request(30..36), 6);
3972        ahead.render_again();
3973        // Rows 20 to 25 were kept from the first render; the new one renders them anew,
3974        // with the new data.
3975        assert_eq!(ahead.request(20..26), 6);
3976        let items = ahead
3977            .lifecycle
3978            .root()
3979            .unwrap()
3980            .virtual_collection_items(&ahead.id)
3981            .unwrap()
3982            .clone();
3983        assert!(matches!(items[&22].kind(), UiNodeKind::Text { text } if text == "Row 22:1"));
3984    }
3985
3986    #[test]
3987    fn an_item_whose_component_owns_an_effect_is_released_not_kept() {
3988        let mut ahead = RenderAhead::start(
3989            ",batch_items:1,retain_items:32",
3990            crate::VirtualCollectionPolicy::default(),
3991        );
3992        assert_eq!(ahead.request(40..46), 6);
3993        assert_eq!(ahead.request(20..26), 6);
3994        // Rows 40 to 45 stopped their effects when they left; they render again.
3995        assert_eq!(ahead.request(40..46), 6);
3996        // Rows 20 to 25 own no work and were kept.
3997        assert_eq!(ahead.request(20..26), 0);
3998    }
3999
4000    #[test]
4001    fn kept_items_survive_a_failed_realization() {
4002        let mut ahead = RenderAhead::start(
4003            ",batch_items:1,retain_items:32",
4004            crate::VirtualCollectionPolicy::default(),
4005        );
4006        assert_eq!(ahead.request(20..26), 6);
4007        // Row 50 fails: the items roll back to 20 to 25, which this attempt had kept.
4008        ahead
4009            .runtime
4010            .borrow()
4011            .virtual_requests
4012            .request(ahead.id.clone(), 48..52);
4013        assert!(
4014            ahead
4015                .lifecycle
4016                .realize_virtual_requests(&mut ahead.engine)
4017                .is_err()
4018        );
4019        let _ = ahead.engine.take_timings();
4020        assert_eq!(ahead.realized(), (20..26).collect::<Vec<_>>());
4021        // What the collection kept before and during the failed attempt still comes back
4022        // without rendering.
4023        assert_eq!(ahead.request(0..6), 0);
4024        assert_eq!(ahead.request(20..26), 0);
4025        assert_eq!(ahead.realized(), (20..26).collect::<Vec<_>>());
4026    }
4027
4028    #[test]
4029    fn a_failing_item_rendered_ahead_falls_back_to_the_requested_ones() {
4030        let mut ahead = RenderAhead::start(
4031            ",batch_items:8,retain_items:0",
4032            crate::VirtualCollectionPolicy::default(),
4033        );
4034        // The batch after rows 44 and 45 reaches row 50, which fails: rows 44 to 49 render
4035        // and 50 fails (seven renders), then only the requested rows render again (two).
4036        // No failure is reported.
4037        assert_eq!(ahead.request(44..46), 9);
4038        assert_eq!(ahead.realized(), vec![44, 45]);
4039        // Within the engine's session, before the lifecycle starts another, the recovered
4040        // failure is not the last one either.
4041        let previous = ahead
4042            .lifecycle
4043            .root()
4044            .unwrap()
4045            .virtual_collection_items(&ahead.id)
4046            .unwrap()
4047            .clone();
4048        ahead.engine.begin_execution_session();
4049        let realized = ahead
4050            .engine
4051            .realize_virtual_collection(&ahead.id, &BTreeSet::from([46, 47]), &previous)
4052            .unwrap();
4053        assert_eq!(realized.keys().copied().collect::<Vec<_>>(), vec![46, 47]);
4054        assert_eq!(ahead.engine.last_failed_timing(), None);
4055        assert_eq!(ahead.engine.last_failed_component(), None);
4056        // A failing requested row still fails the realization.
4057        ahead
4058            .runtime
4059            .borrow()
4060            .virtual_requests
4061            .request_target(ahead.id.clone(), 50..51);
4062        assert!(
4063            ahead
4064                .lifecycle
4065                .realize_virtual_requests(&mut ahead.engine)
4066                .is_err()
4067        );
4068    }
4069
4070    #[test]
4071    fn the_host_policy_applies_unless_a_collection_sets_its_own() {
4072        let policy = crate::VirtualCollectionPolicy {
4073            overscan_items: Some(3),
4074            batch_items: Some(4),
4075            retain_items: Some(0),
4076        };
4077        let mut ahead = RenderAhead::start("", policy);
4078        // Three items of overscan replace the collection's own 24 pixels.
4079        let spec = ahead
4080            .lifecycle
4081            .root()
4082            .unwrap()
4083            .virtual_collection_spec(&ahead.id)
4084            .unwrap()
4085            .clone();
4086        assert!((spec.overdraw_pixels - 72.0).abs() < f64::EPSILON);
4087        let first = *ahead.realized().last().unwrap() + 1;
4088        // The Host's batch of four: the needed row and three more.
4089        assert_eq!(ahead.request(first..first + 1), 4);
4090
4091        let mut own = RenderAhead::start(",overscan_items:0,batch_items:1", policy);
4092        let spec = own
4093            .lifecycle
4094            .root()
4095            .unwrap()
4096            .virtual_collection_spec(&own.id)
4097            .unwrap()
4098            .clone();
4099        assert!(spec.overdraw_pixels.abs() < f64::EPSILON);
4100        let first = *own.realized().last().unwrap() + 1;
4101        assert_eq!(own.request(first..first + 1), 1);
4102    }
4103
4104    #[test]
4105    fn render_ahead_settings_are_validated() {
4106        for (extra, field) in [
4107            (",batch_items:0", "batch_items"),
4108            (",retain_items:-1", "retain_items"),
4109            (",overscan_items:1001", "overscan_items"),
4110            (",batch_items:2.5", "batch_items"),
4111        ] {
4112            let mut engine = RuntimeEngine::new();
4113            let compiled = engine
4114                .compile(&RENDER_AHEAD.replace("EXTRA", extra))
4115                .unwrap();
4116            let schema = ComponentStateSchema::new(BTreeMap::from([(
4117                "version".to_owned(),
4118                StateField::new(ValueSchema::integer(), UiValue::Integer(0)),
4119            )]))
4120            .unwrap();
4121            let mut lifecycle = ScriptLifecycle::new(
4122                compiled,
4123                Rc::new(RefCell::new(UiRuntimeState::new())),
4124                ComponentInstancePath::root("App", "invalid"),
4125                Some("main".to_owned()),
4126                BTreeMap::new(),
4127                &schema,
4128            )
4129            .unwrap();
4130            let error = lifecycle.start(&mut engine).unwrap_err().to_string();
4131            assert!(error.contains(field), "{extra}: {error}");
4132        }
4133    }
4134
4135    #[test]
4136    fn controlled_rerender_synchronously_rebuilds_the_retained_virtual_window() {
4137        let mut engine = RuntimeEngine::new();
4138        let compiled = engine
4139            .compile(
4140                r#"
4141                    fn render_item(ctx, payload) {
4142                        text(`${payload.item.label}:${payload.item.active}`).with_key(payload.key)
4143                    }
4144                    fn view(ctx) {
4145                        let active = ctx.get_state("active");
4146                        let data = [];
4147                        for index in 0..32 {
4148                            data.push(#{
4149                                key: `row-${index}`,
4150                                label: `Row ${index}`,
4151                                active: index == active,
4152                            });
4153                        }
4154                        virtual_collection(#{
4155                            key: "rows", label: "Rows", data: data,
4156                            estimated_height: 24, height: 96,
4157                            overdraw_pixels: 24, alignment: "top", follow_tail: false,
4158                            batch_items: 1, retain_items: 0,
4159                            reveal_key: `row-${active}`,
4160                        }, Fn("render_item"))
4161                    }
4162                "#,
4163            )
4164            .unwrap();
4165        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4166        let path = ComponentInstancePath::root("App", "root");
4167        let schema = ComponentStateSchema::new(BTreeMap::from([(
4168            "active".to_owned(),
4169            StateField::new(ValueSchema::integer(), UiValue::Integer(0)),
4170        )]))
4171        .unwrap();
4172        let mut lifecycle = ScriptLifecycle::new(
4173            compiled,
4174            Rc::clone(&runtime),
4175            path.clone(),
4176            Some("main".to_owned()),
4177            BTreeMap::new(),
4178            &schema,
4179        )
4180        .unwrap();
4181        lifecycle.start(&mut engine).unwrap();
4182        let id = engine
4183            .virtual_collection_ids_in_scope(&path)
4184            .into_iter()
4185            .next()
4186            .unwrap();
4187
4188        runtime
4189            .borrow()
4190            .virtual_requests
4191            .request(id.clone(), 14..20);
4192        assert!(lifecycle.realize_virtual_requests(&mut engine).unwrap());
4193        assert_eq!(
4194            lifecycle
4195                .root()
4196                .unwrap()
4197                .virtual_collection_items(&id)
4198                .unwrap()
4199                .keys()
4200                .copied()
4201                .collect::<Vec<_>>(),
4202            (14..20).collect::<Vec<_>>()
4203        );
4204
4205        runtime
4206            .borrow_mut()
4207            .set_component_state_from_host(&path, "active", UiValue::Integer(16))
4208            .unwrap();
4209        assert!(lifecycle.render_dirty(&mut engine).unwrap());
4210        let realized = lifecycle
4211            .root()
4212            .unwrap()
4213            .virtual_collection_items(&id)
4214            .unwrap();
4215        for index in 14..20 {
4216            assert!(
4217                realized.contains_key(&index),
4218                "retained row {index} is missing"
4219            );
4220        }
4221        assert!(matches!(
4222            realized[&16].kind(),
4223            crate::UiNodeKind::Text { text } if text == "Row 16:true"
4224        ));
4225        assert!(matches!(
4226            realized[&15].kind(),
4227            crate::UiNodeKind::Text { text } if text == "Row 15:false"
4228        ));
4229    }
4230
4231    #[test]
4232    fn failed_event_callback_rolls_back_ui_state() {
4233        let mut engine = RuntimeEngine::new();
4234        let compiled = engine
4235            .compile(
4236                r#"
4237                    fn view(ctx) { text(ctx.get_state("phase")) }
4238                    fn fail(ctx, payload) {
4239                        ctx.set_state("phase", "partial");
4240                        ctx.register_action("test.temporary", Fn("fail"));
4241                        ctx.open_window("temporary", "Temporary", 400, 300, false);
4242                        throw "event failed";
4243                    }
4244                "#,
4245            )
4246            .unwrap();
4247        let callback = engine.callback(&compiled, "fail").unwrap();
4248        let mut runtime_state = UiRuntimeState::new();
4249        runtime_state.windows.register_open("main").unwrap();
4250        let runtime = Rc::new(RefCell::new(runtime_state));
4251        let path = ComponentInstancePath::root("App", "root");
4252        let mut lifecycle = ScriptLifecycle::new(
4253            compiled,
4254            Rc::clone(&runtime),
4255            path.clone(),
4256            Some("main".to_owned()),
4257            BTreeMap::new(),
4258            &state_schema(),
4259        )
4260        .unwrap();
4261        lifecycle.start(&mut engine).unwrap();
4262        assert!(
4263            lifecycle
4264                .invoke_callback_transactional(&engine, &callback, UiValue::Null)
4265                .is_err()
4266        );
4267        assert_eq!(
4268            runtime.borrow().component_state.get(&path, "phase"),
4269            Some(&UiValue::String("created".to_owned()))
4270        );
4271        let runtime = runtime.borrow();
4272        assert!(!runtime.windows.contains("temporary"));
4273        assert!(
4274            runtime
4275                .actions
4276                .dispatch(
4277                    &crate::ActionId::parse("test.temporary").unwrap(),
4278                    UiValue::Null,
4279                )
4280                .is_err()
4281        );
4282    }
4283
4284    #[test]
4285    fn missing_optional_lifecycle_functions_are_valid() {
4286        let mut engine = RuntimeEngine::new();
4287        let compiled = engine
4288            .compile("fn view(ctx) { text(\"only view\") }")
4289            .unwrap();
4290        let mut lifecycle = ScriptLifecycle::new(
4291            compiled,
4292            Rc::new(RefCell::new(UiRuntimeState::new())),
4293            ComponentInstancePath::root("App", "root"),
4294            None,
4295            BTreeMap::new(),
4296            &ComponentStateSchema::default(),
4297        )
4298        .unwrap();
4299        lifecycle.start(&mut engine).unwrap();
4300        lifecycle.dispose(&mut engine).unwrap();
4301    }
4302
4303    #[test]
4304    fn retained_candidate_over_host_budget_is_rejected_before_commit() {
4305        let mut engine = RuntimeEngine::new();
4306        let compiled = engine
4307            .compile("fn view(ctx) { box([text(\"child\")]) }")
4308            .unwrap();
4309        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4310        runtime.borrow_mut().budgets.retained_nodes = 1;
4311        let mut lifecycle = ScriptLifecycle::new(
4312            compiled,
4313            Rc::clone(&runtime),
4314            ComponentInstancePath::root("App", "root"),
4315            Some("main".to_owned()),
4316            BTreeMap::new(),
4317            &ComponentStateSchema::default(),
4318        )
4319        .unwrap();
4320        assert!(matches!(
4321            lifecycle.start(&mut engine),
4322            Err(LifecycleError::Budget(
4323                crate::RuntimeBudgetError::Exceeded {
4324                    resource: "retained_nodes",
4325                    actual: 2,
4326                    limit: 1,
4327                }
4328            ))
4329        ));
4330        assert!(lifecycle.retained().is_empty());
4331    }
4332
4333    #[test]
4334    fn invalid_native_semantics_reject_the_candidate_before_commit() {
4335        let mut engine = RuntimeEngine::new();
4336        let compiled = engine
4337            .compile(
4338                r#"fn view(ctx) {
4339                    text("Mystery").accessibility_role("mystery_widget")
4340                }"#,
4341            )
4342            .unwrap();
4343        let mut lifecycle = ScriptLifecycle::new(
4344            compiled,
4345            Rc::new(RefCell::new(UiRuntimeState::new())),
4346            ComponentInstancePath::root("App", "root"),
4347            None,
4348            BTreeMap::new(),
4349            &ComponentStateSchema::default(),
4350        )
4351        .unwrap();
4352        assert!(matches!(
4353            lifecycle.start(&mut engine),
4354            Err(LifecycleError::Accessibility(
4355                crate::AccessibilityError::UnsupportedRole(role)
4356            )) if role == "mystery_widget"
4357        ));
4358        assert!(lifecycle.retained().is_empty());
4359        assert!(lifecycle.semantics().nodes().next().is_none());
4360    }
4361
4362    #[test]
4363    fn layer_budget_rejects_candidate_before_commit() {
4364        let mut engine = RuntimeEngine::new();
4365        let compiled = engine
4366            .compile(
4367                r#"
4368                    fn view(ctx) {
4369                        box([
4370                            layer(text("first"), #{ id: "first", placement: "top_right" }),
4371                            layer(text("second"), #{ id: "second", placement: "bottom_right" })
4372                        ])
4373                    }
4374                "#,
4375            )
4376            .unwrap();
4377        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4378        runtime.borrow_mut().budgets.layers = 1;
4379        let mut lifecycle = ScriptLifecycle::new(
4380            compiled,
4381            Rc::clone(&runtime),
4382            ComponentInstancePath::root("App", "root"),
4383            Some("main".to_owned()),
4384            BTreeMap::new(),
4385            &ComponentStateSchema::default(),
4386        )
4387        .unwrap();
4388
4389        assert!(matches!(
4390            lifecycle.start(&mut engine),
4391            Err(LifecycleError::Budget(
4392                crate::RuntimeBudgetError::Exceeded {
4393                    resource: "layers",
4394                    actual: 2,
4395                    limit: 1,
4396                }
4397            ))
4398        ));
4399        assert!(lifecycle.retained().is_empty());
4400    }
4401
4402    #[test]
4403    fn canvas_scene_budget_is_independent_from_command_budget() {
4404        let mut engine = RuntimeEngine::new();
4405        let compiled = engine
4406            .compile(
4407                r#"
4408                    fn view(ctx) {
4409                        box([
4410                            canvas(canvas_scene([canvas_rect("a", 0.0, 0.0, 1.0, 1.0, rgb(0))])),
4411                            canvas(canvas_scene([canvas_rect("b", 0.0, 0.0, 1.0, 1.0, rgb(0))]))
4412                        ])
4413                    }
4414                "#,
4415            )
4416            .unwrap();
4417        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4418        {
4419            let mut runtime = runtime.borrow_mut();
4420            runtime.budgets.canvas_scenes = 1;
4421            runtime.budgets.canvas_commands = 10;
4422        }
4423        let mut lifecycle = ScriptLifecycle::new(
4424            compiled,
4425            Rc::clone(&runtime),
4426            ComponentInstancePath::root("App", "root"),
4427            Some("main".to_owned()),
4428            BTreeMap::new(),
4429            &ComponentStateSchema::default(),
4430        )
4431        .unwrap();
4432
4433        assert!(matches!(
4434            lifecycle.start(&mut engine),
4435            Err(LifecycleError::Budget(
4436                crate::RuntimeBudgetError::Exceeded {
4437                    resource: "canvas_scenes",
4438                    actual: 2,
4439                    limit: 1,
4440                }
4441            ))
4442        ));
4443        assert!(lifecycle.retained().is_empty());
4444    }
4445
4446    #[test]
4447    fn hot_reload_rolls_back_candidate_init_state_on_render_failure() {
4448        let mut engine = RuntimeEngine::new();
4449        let active = engine
4450            .compile(
4451                r#"
4452                    fn init(ctx) { ctx.set_state("phase", "active"); }
4453                    fn view(ctx) { text(ctx.get_state("phase")) }
4454                "#,
4455            )
4456            .unwrap();
4457        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4458        let path = ComponentInstancePath::root("App", "root");
4459        let mut lifecycle = ScriptLifecycle::new(
4460            active,
4461            Rc::clone(&runtime),
4462            path.clone(),
4463            None,
4464            BTreeMap::new(),
4465            &state_schema(),
4466        )
4467        .unwrap();
4468        lifecycle.start(&mut engine).unwrap();
4469        let active_generation = lifecycle.generation();
4470
4471        let rejected = engine
4472            .compile(
4473                r#"
4474                    fn init(ctx) { ctx.set_state("phase", "candidate"); }
4475                    fn view(ctx) { throw "reject"; }
4476                "#,
4477            )
4478            .unwrap();
4479        assert!(
4480            lifecycle
4481                .reload(&mut engine, rejected, &state_schema())
4482                .is_err()
4483        );
4484        assert_eq!(lifecycle.generation(), active_generation);
4485        assert_eq!(
4486            runtime.borrow().component_state.get(&path, "phase"),
4487            Some(&UiValue::String("active".to_owned()))
4488        );
4489    }
4490
4491    #[test]
4492    fn hot_reload_keeps_a_disabled_action_disabled() {
4493        let source = r#"
4494            fn init(ctx) { ctx.register_action("document.save", Fn("save")); }
4495            fn save(ctx, payload) {}
4496            fn disable(ctx, payload) { ctx.set_action_enabled("document.save", false); }
4497            fn view(ctx) { text("actions") }
4498        "#;
4499        let mut engine = RuntimeEngine::new();
4500        let active = engine.compile(source).unwrap();
4501        let disable = engine.callback(&active, "disable").unwrap();
4502        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4503        let mut lifecycle = ScriptLifecycle::new(
4504            active,
4505            Rc::clone(&runtime),
4506            ComponentInstancePath::root("App", "root"),
4507            None,
4508            BTreeMap::new(),
4509            &state_schema(),
4510        )
4511        .unwrap();
4512        lifecycle.start(&mut engine).unwrap();
4513        let id = crate::ActionId::parse("document.save").unwrap();
4514        assert_eq!(runtime.borrow().actions.is_enabled(&id), Some(true));
4515        let _ = lifecycle
4516            .invoke_callback(&engine, &disable, UiValue::Null)
4517            .unwrap();
4518        assert_eq!(runtime.borrow().actions.is_enabled(&id), Some(false));
4519
4520        let candidate = engine.compile(source).unwrap();
4521        let generation = candidate.generation();
4522        lifecycle
4523            .reload(&mut engine, candidate, &state_schema())
4524            .unwrap();
4525        let mut runtime = runtime.borrow_mut();
4526        assert_eq!(runtime.actions.is_enabled(&id), Some(false));
4527        runtime.actions.set_enabled(&id, true).unwrap();
4528        let invocation = runtime.actions.dispatch(&id, UiValue::Null).unwrap();
4529        assert_eq!(invocation.callback.generation(), generation);
4530    }
4531
4532    #[test]
4533    fn hot_reload_rolls_back_engine_generation_after_retained_validation_failure() {
4534        let mut engine = RuntimeEngine::new();
4535        let active = engine
4536            .compile(
4537                r#"
4538                    fn init(ctx) { ctx.set_state("phase", "active"); }
4539                    fn view(ctx) { text(ctx.get_state("phase")) }
4540                "#,
4541            )
4542            .unwrap();
4543        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4544        let path = ComponentInstancePath::root("App", "root");
4545        let mut lifecycle = ScriptLifecycle::new(
4546            active,
4547            Rc::clone(&runtime),
4548            path.clone(),
4549            None,
4550            BTreeMap::new(),
4551            &state_schema(),
4552        )
4553        .unwrap();
4554        lifecycle.start(&mut engine).unwrap();
4555        let active_generation = lifecycle.generation();
4556        let reconcile_trace_count = runtime
4557            .borrow()
4558            .traces
4559            .snapshot()
4560            .iter()
4561            .filter(|trace| trace.kind == crate::RuntimeTraceKind::Reconcile)
4562            .count();
4563
4564        let rejected = engine
4565            .compile(
4566                r#"
4567                    fn init(ctx) { ctx.set_state("phase", "candidate"); }
4568                    fn view(ctx) {
4569                        row([
4570                            text("first").with_key("duplicate"),
4571                            text("second").with_key("duplicate")
4572                        ])
4573                    }
4574                "#,
4575            )
4576            .unwrap();
4577        assert!(
4578            lifecycle
4579                .reload(&mut engine, rejected, &state_schema())
4580                .is_err()
4581        );
4582        assert_eq!(lifecycle.generation(), active_generation);
4583        assert!(engine.is_current(active_generation));
4584        assert_eq!(
4585            runtime.borrow().component_state.get(&path, "phase"),
4586            Some(&UiValue::String("active".to_owned()))
4587        );
4588        assert!(matches!(
4589            lifecycle.root().unwrap().kind(),
4590            crate::UiNodeKind::Text { text } if text == "active"
4591        ));
4592        assert_eq!(
4593            runtime
4594                .borrow()
4595                .traces
4596                .snapshot()
4597                .iter()
4598                .filter(|trace| trace.kind == crate::RuntimeTraceKind::Reconcile)
4599                .count(),
4600            reconcile_trace_count
4601        );
4602    }
4603
4604    #[test]
4605    fn async_capability_completes_through_foreground_delivery() {
4606        struct Echo;
4607        impl AsyncCapabilityHandler for Echo {
4608            fn start(&mut self, _: &str, input: UiValue) -> Result<TaskWork, String> {
4609                Ok(TaskWork::new(move || Ok(input)))
4610            }
4611        }
4612
4613        let mut engine = RuntimeEngine::new();
4614        let compiled = engine
4615            .compile(
4616                r#"
4617                    fn init(ctx) {
4618                        ctx.start_task(
4619                            "app.echo", "echo", "loaded",
4620                            Fn("loaded"), Fn("failed")
4621                        );
4622                    }
4623                    fn loaded(ctx, value) { ctx.set_state("phase", value); }
4624                    fn failed(ctx, error) { ctx.set_state("phase", "failed"); }
4625                    fn view(ctx) { text(ctx.get_state("phase")) }
4626                "#,
4627            )
4628            .unwrap();
4629        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4630        let capability = CapabilityId::parse("app.echo").unwrap();
4631        runtime
4632            .borrow_mut()
4633            .capabilities
4634            .register_async(
4635                CapabilityDescriptor {
4636                    id: capability.clone(),
4637                    version: Version::new(1, 0, 0),
4638                    methods: BTreeMap::from([(
4639                        "echo".to_owned(),
4640                        CapabilityMethod {
4641                            input: ValueSchema::string(),
4642                            output: ValueSchema::string(),
4643                        },
4644                    )]),
4645                },
4646                Echo,
4647            )
4648            .unwrap();
4649        runtime
4650            .borrow_mut()
4651            .capabilities
4652            .activate(&BTreeMap::from([(capability, VersionReq::STAR)]))
4653            .unwrap();
4654        let path = ComponentInstancePath::root("App", "root");
4655        let mut lifecycle = ScriptLifecycle::new(
4656            compiled,
4657            Rc::clone(&runtime),
4658            path.clone(),
4659            None,
4660            BTreeMap::new(),
4661            &state_schema(),
4662        )
4663        .unwrap();
4664        lifecycle.start(&mut engine).unwrap();
4665
4666        let deadline = Instant::now() + Duration::from_secs(1);
4667        loop {
4668            let deliveries = runtime.borrow_mut().tasks.drain(lifecycle.generation());
4669            if !deliveries.is_empty() {
4670                for delivery in deliveries {
4671                    let _ = lifecycle.invoke_async_delivery(&engine, delivery).unwrap();
4672                }
4673                lifecycle.render(&mut engine).unwrap();
4674                break;
4675            }
4676            assert!(Instant::now() < deadline);
4677            std::thread::yield_now();
4678        }
4679        assert_eq!(
4680            runtime.borrow().component_state.get(&path, "phase"),
4681            Some(&UiValue::String("loaded".to_owned()))
4682        );
4683    }
4684
4685    #[test]
4686    fn async_image_decode_completes_through_lifecycle_delivery() {
4687        let mut png = std::io::Cursor::new(Vec::new());
4688        image::DynamicImage::new_rgba8(1, 1)
4689            .write_to(&mut png, image::ImageFormat::Png)
4690            .unwrap();
4691        let mut engine = RuntimeEngine::new();
4692        let compiled = engine
4693            .compile(
4694                r#"
4695                    fn init(ctx) {
4696                        ctx.start_image_decode(
4697                            asset("app/pixel"), Fn("loaded"), Fn("failed")
4698                        );
4699                    }
4700                    fn loaded(ctx, handle) { ctx.set_state("image", handle); }
4701                    fn failed(ctx, error) { () }
4702                    fn view(ctx) { image(ctx.get_state("image")) }
4703                "#,
4704            )
4705            .unwrap();
4706        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4707        runtime
4708            .borrow()
4709            .assets
4710            .register(
4711                "app",
4712                InMemoryAssetProvider::new(BTreeMap::from([(
4713                    "pixel".to_owned(),
4714                    AssetData {
4715                        mime_type: "image/png".to_owned(),
4716                        bytes: png.into_inner(),
4717                    },
4718                )])),
4719            )
4720            .unwrap();
4721        let path = ComponentInstancePath::root("App", "root");
4722        let schema = ComponentStateSchema::new(BTreeMap::from([(
4723            "image".to_owned(),
4724            StateField::new(
4725                ValueSchema::Handle {
4726                    kind: "image".to_owned(),
4727                },
4728                UiValue::Handle(OpaqueHandle::new("image", 0)),
4729            ),
4730        )]))
4731        .unwrap();
4732        let mut lifecycle = ScriptLifecycle::new(
4733            compiled,
4734            Rc::clone(&runtime),
4735            path.clone(),
4736            None,
4737            BTreeMap::new(),
4738            &schema,
4739        )
4740        .unwrap();
4741        lifecycle.start(&mut engine).unwrap();
4742
4743        let assets = runtime.borrow().assets.clone();
4744        let deadline = Instant::now() + Duration::from_secs(1);
4745        loop {
4746            let deliveries = assets.drain_image_decodes(lifecycle.generation()).unwrap();
4747            if !deliveries.is_empty() {
4748                for delivery in deliveries {
4749                    let _ = lifecycle.invoke_async_delivery(&engine, delivery).unwrap();
4750                }
4751                lifecycle.render(&mut engine).unwrap();
4752                break;
4753            }
4754            assert!(Instant::now() < deadline);
4755            std::thread::yield_now();
4756        }
4757        assert!(matches!(
4758            runtime.borrow().component_state.get(&path, "image"),
4759            Some(UiValue::Handle(handle)) if handle.id() != 0
4760        ));
4761    }
4762
4763    #[test]
4764    fn subscription_capability_streams_until_close() {
4765        struct Stream;
4766        impl SubscriptionCapabilityHandler for Stream {
4767            fn subscribe(&mut self, _: &str, _: UiValue) -> Result<SubscriptionWork, String> {
4768                Ok(SubscriptionWork::new(|emitter| {
4769                    emitter.emit(UiValue::String("first".to_owned())).unwrap();
4770                    emitter.emit(UiValue::String("second".to_owned())).unwrap();
4771                }))
4772            }
4773        }
4774
4775        let mut engine = RuntimeEngine::new();
4776        let compiled = engine.compile(&STREAM_COMPONENT_APP.replace(
4777            "fn view(ctx) { render_component(\"test/stream\", #{ key: \"stream\" }) }",
4778            "fn view(ctx) { if ctx.get_state(\"phase\")==\"hidden\" {text(\"hidden\")} else {render_component(\"test/stream\", #{key:\"stream\"})} }",
4779        )).unwrap();
4780        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4781        let capability = CapabilityId::parse("app.stream").unwrap();
4782        runtime
4783            .borrow_mut()
4784            .capabilities
4785            .register_subscription(
4786                CapabilityDescriptor {
4787                    id: capability.clone(),
4788                    version: Version::new(1, 0, 0),
4789                    methods: BTreeMap::from([(
4790                        "watch".to_owned(),
4791                        CapabilityMethod {
4792                            input: ValueSchema::Null,
4793                            output: ValueSchema::string(),
4794                        },
4795                    )]),
4796                },
4797                Stream,
4798            )
4799            .unwrap();
4800        runtime
4801            .borrow_mut()
4802            .capabilities
4803            .activate(&BTreeMap::from([(capability, VersionReq::STAR)]))
4804            .unwrap();
4805        let path = ComponentInstancePath::root("App", "root");
4806        let mut lifecycle = ScriptLifecycle::new(
4807            compiled,
4808            Rc::clone(&runtime),
4809            path.clone(),
4810            None,
4811            BTreeMap::new(),
4812            &state_schema(),
4813        )
4814        .unwrap();
4815        lifecycle.start(&mut engine).unwrap();
4816
4817        let deadline = Instant::now() + Duration::from_secs(1);
4818        let mut already_drained = None;
4819        loop {
4820            let deliveries = runtime
4821                .borrow_mut()
4822                .subscriptions
4823                .drain(lifecycle.generation());
4824            for delivery in deliveries {
4825                already_drained = Some(delivery.clone());
4826                let _ = lifecycle.invoke_async_delivery(&engine, delivery).unwrap();
4827            }
4828            if runtime.borrow().subscriptions.active_count() == 0 {
4829                lifecycle.render(&mut engine).unwrap();
4830                break;
4831            }
4832            assert!(Instant::now() < deadline);
4833            std::thread::yield_now();
4834        }
4835        assert_eq!(
4836            runtime
4837                .borrow()
4838                .component_state
4839                .get(&path.child("StreamProbe", "stream"), "phase"),
4840            Some(&UiValue::String("second".to_owned()))
4841        );
4842        let late = already_drained.unwrap();
4843        runtime
4844            .borrow_mut()
4845            .set_component_state_from_host(&path, "phase", UiValue::String("hidden".to_owned()))
4846            .unwrap();
4847        lifecycle.render_dirty(&mut engine).unwrap();
4848        let callback = late.callback.clone();
4849        let _ = lifecycle.invoke_async_delivery(&engine, late).unwrap();
4850        assert!(
4851            lifecycle
4852                .invoke_callback(&engine, &callback, UiValue::Null)
4853                .is_err()
4854        );
4855    }
4856
4857    #[test]
4858    fn subscription_start_outside_a_declarative_effect_is_rejected() {
4859        let mut engine = RuntimeEngine::new();
4860        let compiled = engine
4861            .compile(
4862                r#"
4863                    fn init(ctx) {
4864                        ctx.start_subscription(
4865                            "app.stream", "watch", (),
4866                            Fn("received"), Fn("failed"), #{ delivery: "all" }
4867                        );
4868                    }
4869                    fn received(ctx, value) { () }
4870                    fn failed(ctx, error) { () }
4871                    fn view(ctx) { text("never mounted") }
4872                "#,
4873            )
4874            .unwrap();
4875        let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4876        let mut lifecycle = ScriptLifecycle::new(
4877            compiled,
4878            runtime,
4879            ComponentInstancePath::root("App", "root"),
4880            None,
4881            BTreeMap::new(),
4882            &state_schema(),
4883        )
4884        .unwrap();
4885        let error = lifecycle.start(&mut engine).unwrap_err().to_string();
4886        assert!(
4887            error.contains("subscriptions must be started by a declarative component effect"),
4888            "unexpected error: {error}"
4889        );
4890    }
4891
4892    fn assert_table_panel_marker(
4893        lifecycle: &ScriptLifecycle,
4894        runtime: &UiRuntimeState,
4895        track: bool,
4896        internal: bool,
4897        count: i32,
4898    ) {
4899        let root = lifecycle.root().unwrap();
4900        let panel = if track {
4901            root
4902        } else {
4903            let UiNodeKind::Box { children } = root.kind() else {
4904                panic!("expected track")
4905            };
4906            &children[0]
4907        };
4908        assert_eq!(
4909            panel.style().base.width,
4910            Some(crate::LayoutLength::Definite(
4911                crate::Length::pixels(123.0).unwrap()
4912            ))
4913        );
4914        if track {
4915            let Some(crate::table_layout::TableLayout::Columns(columns)) = panel.table_layout()
4916            else {
4917                panic!("track marker lost: internal={internal}, count={count}")
4918            };
4919            let plan = crate::table_layout::resolve(columns.as_slice(), 400.0, &runtime.signals);
4920            assert_eq!(
4921                plan.widths,
4922                vec![120.0 + if internal { f64::from(count) } else { 0.0 }, 140.0]
4923            );
4924        } else {
4925            assert_eq!(
4926                panel.table_column(),
4927                Some(if internal {
4928                    usize::try_from(count % 2).unwrap()
4929                } else {
4930                    0
4931                })
4932            );
4933        }
4934        let UiNodeKind::Box { children } = panel.kind() else {
4935            panic!("expected panel")
4936        };
4937        assert!(
4938            matches!(children[0].kind(), UiNodeKind::Text { text } if text.as_str() == count.to_string())
4939        );
4940    }
4941
4942    fn assert_table_modifier_replay(track: bool) {
4943        for internal in [true, false] {
4944            let modifier = if track {
4945                ".with_table_track(columns(120), [])"
4946            } else {
4947                ".with_table_column(0)"
4948            };
4949            let internal_modifier = if track {
4950                ".with_table_track(columns(120 + count), [])"
4951            } else {
4952                ".with_table_column(count % 2)"
4953            };
4954            let panel = format!(
4955                "render_component(\"tests/table_panel\", #{{key:\"panel\"}}){}.with_style(style().width(px(123)))",
4956                if internal { "" } else { modifier }
4957            );
4958            let source = r#"
4959                define_component(#{
4960                    metadata:#{id:"tests/table_panel","export":"Panel",version:"0.1.8",
4961                        runtime_api:#{min_inclusive: 3,max_exclusive: 4},dependencies:[],capabilities:#{}},
4962                    schema:#{props:#{key:#{schema:#{type:"string"},required:true,sensitive:false}},
4963                        state:#{fields:#{count:#{schema:#{type:"integer"},"default":#{type:"integer",value:0}}}},
4964                        events:#{},slots:#{},parts:[]},render:Fn("render_panel")
4965                });
4966                fn columns(width) { [#{key:"a",width:#{kind:"fixed",value:width}},
4967                    #{key:"b",width:#{kind:"fixed",value:140}}] }
4968                fn render_panel(ctx, props) {
4969                    let count = ctx.get_state("count");
4970                    if count < 0 { throw "rejected panel candidate"; }
4971                    column([text(`${count}`)])INTERNAL
4972                }
4973                fn view(ctx) { VIEW }
4974            "#
4975            .replace("INTERNAL", if internal { internal_modifier } else { "" })
4976            .replace(
4977                "VIEW",
4978                &if track { panel } else { format!("column([{panel}]).with_table_track(columns(120), [])") },
4979            );
4980            let mut engine = RuntimeEngine::new();
4981            let compiled = engine
4982                .compile_named("table-modifier.rhai", &source)
4983                .unwrap();
4984            let runtime = Rc::new(RefCell::new(UiRuntimeState::new()));
4985            let root = ComponentInstancePath::root("App", format!("table-{track}-{internal}"));
4986            let component = root.child("Panel", "panel");
4987            let mut lifecycle = ScriptLifecycle::new(
4988                compiled,
4989                Rc::clone(&runtime),
4990                root,
4991                Some("main".into()),
4992                BTreeMap::new(),
4993                &ComponentStateSchema::default(),
4994            )
4995            .unwrap();
4996            lifecycle.start(&mut engine).unwrap();
4997            assert_table_panel_marker(&lifecycle, &runtime.borrow(), track, internal, 0);
4998            for count in [1, 2] {
4999                runtime
5000                    .borrow_mut()
5001                    .set_component_state_from_host(
5002                        &component,
5003                        "count",
5004                        UiValue::Integer(i64::from(count)),
5005                    )
5006                    .unwrap();
5007                assert_eq!(
5008                    runtime.borrow().dirty_components(),
5009                    &BTreeSet::from([component.clone()])
5010                );
5011                assert!(lifecycle.render_dirty(&mut engine).unwrap());
5012                assert_table_panel_marker(&lifecycle, &runtime.borrow(), track, internal, count);
5013            }
5014            runtime
5015                .borrow_mut()
5016                .set_component_state_from_host(&component, "count", UiValue::Integer(-1))
5017                .unwrap();
5018            assert!(lifecycle.render_dirty(&mut engine).is_err());
5019            assert_table_panel_marker(&lifecycle, &runtime.borrow(), track, internal, 2);
5020            runtime
5021                .borrow_mut()
5022                .set_component_state_from_host(&component, "count", UiValue::Integer(3))
5023                .unwrap();
5024            assert!(lifecycle.render_dirty(&mut engine).unwrap());
5025            assert_table_panel_marker(&lifecycle, &runtime.borrow(), track, internal, 3);
5026        }
5027    }
5028
5029    #[test]
5030    fn table_modifiers_replay_track_across_incremental_updates_and_failed_candidates() {
5031        assert_table_modifier_replay(true);
5032    }
5033
5034    #[test]
5035    fn table_modifiers_replay_column_across_incremental_updates_and_failed_candidates() {
5036        assert_table_modifier_replay(false);
5037    }
5038}