cranpose_core/

composer.rs

use std::{
    any::Any,
    cell::{Cell, RefCell, RefMut},
    hash::Hash,
    marker::PhantomData,
    rc::{Rc, Weak},
};

use smallvec::SmallVec;

use crate::{
    AnchorId, Applier, ApplierGuard, ApplierHost, COMMAND_FLUSH_THRESHOLD, ChildList, Command,
    CommandQueue, CompositionLocal, DirtyBubble, Key, LocalKey, LocalStackSnapshot,
    LocalStateEntry, MutableState, Node, NodeError, NodeId, Owned, ProvidedValue, RecomposeOptions,
    RecomposeScope, RecomposeScopeInner, RecycledNode, RetentionMode, RetentionPolicy,
    RuntimeHandle, ScopeId, SlotId, SlotPassOutcome, SlotTable, SlotsHost, SnapshotStateList,
    SnapshotStateMap, StaticCompositionLocal, StaticLocalEntry, SubcomposeState,
    collections::map::{HashMap, HashSet},
    composer_context, explicit_group_key_seed,
    retention::{RetainKey, RetentionManager},
    runtime,
    slot::{FinishGroupResult, GroupStart, GroupStartKind, PayloadKind, RootNodeIds, ValueSlotId},
};

pub struct ValueSlotHandle<'pass, T: 'static> {
    slot: ValueSlotId,
    _pass: PhantomData<&'pass Composer>,
    _value: PhantomData<fn() -> T>,
}

impl<T: 'static> Copy for ValueSlotHandle<'_, T> {}

impl<T: 'static> Clone for ValueSlotHandle<'_, T> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<T: 'static> ValueSlotHandle<'_, T> {
    pub(crate) fn new(slot: ValueSlotId) -> Self {
        Self {
            slot,
            _pass: PhantomData,
            _value: PhantomData,
        }
    }

    pub(crate) fn slot(self) -> ValueSlotId {
        self.slot
    }
}

fn slots_storage_key(host: &Rc<SlotsHost>) -> usize {
    host.storage_key()
}

fn bind_slots_host_to_runtime_state(
    state: &Rc<ComposerRuntimeState>,
    host: &Rc<SlotsHost>,
) -> Rc<SlotsHost> {
    if let Some(bound_state) = host.runtime_state() {
        if Rc::ptr_eq(&bound_state, state) {
            state.bind_slots_host(host);
            return Rc::clone(host);
        }
        drop(bound_state);
        if host.rebind_orphaned_runtime_state(state) {
            state.bind_slots_host(host);
            return Rc::clone(host);
        }
        log::error!(
            "slot host already belongs to a different composer runtime state; using a fresh slot host"
        );
        let replacement = Rc::new(SlotsHost::new(SlotTable::new()));
        state.bind_slots_host(&replacement);
        return replacement;
    }
    state.bind_slots_host(host);
    Rc::clone(host)
}

struct GroupEntry {
    key: crate::slot::GroupKey,
    /// Boxed: a restore is rare, and the entry moves on every call.
    restored: Option<Box<crate::slot::DetachedSubtree>>,
    placeholder_for: Option<crate::slot::GroupKey>,
}

struct GroupScopeEntry<'a> {
    options: RecomposeOptions,
    start_kind: GroupStartKind,
    host: &'a SlotsHost,
    group: crate::slot::ActiveGroupId,
}

struct SlotHostPassGuard {
    core: Rc<ComposerCore>,
    host: Rc<SlotsHost>,
    active: bool,
}

impl SlotHostPassGuard {
    fn close(&mut self) {
        if !self.active {
            return;
        }
        if self.host.has_active_pass() {
            self.host.abandon_active_pass();
        }
        match self.core.slot_hosts.borrow_mut().pop() {
            Some(host) if Rc::ptr_eq(&host, &self.host) => {}
            Some(_) => {
                log::error!("slot host stack mismatch while closing slot host pass");
            }
            None => {
                log::error!("slot host stack underflow while closing slot host pass");
            }
        }
        self.active = false;
    }
}

impl Drop for SlotHostPassGuard {
    fn drop(&mut self) {
        self.close();
    }
}

pub(crate) struct PendingMovable {
    pub(crate) key: crate::slot::GroupKey,
    pub(crate) placeholder: AnchorId,
    pub(crate) parent_scope: Option<Weak<RecomposeScopeInner>>,
}

fn reparent_restored_scopes(
    host: &SlotsHost,
    group: crate::slot::ActiveGroupId,
    old_hint: Option<NodeId>,
    parent_hint: Option<NodeId>,
) {
    host.with_write_session(|slots| {
        slots.for_each_subtree_scope(group, |scope| {
            if scope.parent_hint() == old_hint {
                scope.set_parent_hint(parent_hint);
            }
            scope.reactivate();
        });
    });
}

fn movable_retain_key(id: Key) -> RetainKey {
    RetainKey::for_group(
        None,
        crate::slot::GroupKey::new(crate::slot::MOVABLE_STATIC_KEY, Some(id), 0),
    )
}

pub(crate) struct ComposerRuntimeState {
    retention_by_host: RefCell<HashMap<usize, RetentionManager>>,
    pending_movables_by_host: RefCell<HashMap<usize, Vec<PendingMovable>>>,
    retention_policy: Cell<RetentionPolicy>,
    live_hosts: RefCell<HashMap<usize, std::rc::Weak<SlotsHost>>>,
    applier_host: RefCell<Option<std::rc::Weak<dyn ApplierHost>>>,
}

/// How many applied command queues a thread keeps for its passes.
const SPARE_COMMAND_QUEUES: usize = 8;

/// The most commands a kept queue has room for. A larger one grew in a
/// spike such as the first composition, and keeping it would hold its memory.
const SPARE_COMMAND_CAPACITY: usize = 1024;

thread_local! {
    /// Applied command queues for the next passes' composers to fill. A
    /// composer takes the last one kept; nested passes finish first, so each
    /// pass gets back the storage a pass at its depth grew.
    static SPARE_COMMANDS: RefCell<Vec<CommandQueue>> = const { RefCell::new(Vec::new()) };
}

fn spare_commands() -> CommandQueue {
    SPARE_COMMANDS
        .try_with(|spare| spare.borrow_mut().pop())
        .ok()
        .flatten()
        .unwrap_or_default()
}

/// Keeps an applied, empty command queue for the next pass on this thread.
pub(crate) fn recycle_commands(commands: CommandQueue) {
    if commands.capacity() > SPARE_COMMAND_CAPACITY {
        return;
    }
    let _ = SPARE_COMMANDS.try_with(|spare| {
        let mut spare = spare.borrow_mut();
        if spare.len() < SPARE_COMMAND_QUEUES {
            spare.push(commands);
        }
    });
}

impl Default for ComposerRuntimeState {
    fn default() -> Self {
        Self {
            retention_by_host: RefCell::new(HashMap::default()),
            pending_movables_by_host: RefCell::new(HashMap::default()),
            retention_policy: Cell::new(RetentionPolicy::default()),
            live_hosts: RefCell::new(HashMap::default()),
            applier_host: RefCell::new(None),
        }
    }
}

impl ComposerRuntimeState {
    pub(crate) fn clear_host_storage_key(&self, host_key: usize, table: &mut SlotTable) {
        self.retention_by_host.borrow_mut().remove(&host_key);
        self.pending_movables_by_host.borrow_mut().remove(&host_key);
        self.live_hosts.borrow_mut().remove(&host_key);
        table.release_scopes();
    }

    pub(crate) fn force_recompose_retained_scopes(&self, host_key: usize) {
        if let Some(retention) = self.retention_by_host.borrow().get(&host_key) {
            for scope in retention
                .subtrees()
                .flat_map(crate::slot::DetachedSubtree::scopes)
            {
                scope.force_recompose();
            }
        }
    }

    pub(crate) fn bind_applier_host(&self, applier: &Rc<dyn ApplierHost>) {
        *self.applier_host.borrow_mut() = Some(Rc::downgrade(applier));
    }

    pub(crate) fn has_live_applier_host(&self) -> bool {
        self.applier_host
            .borrow()
            .as_ref()
            .and_then(std::rc::Weak::upgrade)
            .is_some()
    }

    pub(crate) fn bind_slots_host(self: &Rc<Self>, host: &Rc<SlotsHost>) {
        host.bind_runtime_state(self);
        self.live_hosts
            .borrow_mut()
            .insert(host.storage_key(), Rc::downgrade(host));
    }

    pub(crate) fn set_retention_policy(&self, policy: RetentionPolicy) {
        self.retention_policy.set(policy);
    }

    pub(crate) fn retention_policy(&self) -> RetentionPolicy {
        self.retention_policy.get()
    }

    pub(crate) fn take_retained(
        &self,
        host: &Rc<SlotsHost>,
        key: RetainKey,
        preflight: impl FnOnce(&mut crate::slot::DetachedSubtree) -> bool,
    ) -> Option<crate::slot::DetachedSubtree> {
        let host_key = slots_storage_key(host);
        let mut retention = self.retention_by_host.borrow_mut();
        let subtree = retention
            .get_mut(&host_key)?
            .take_after_restore_preflight(key, preflight);
        if retention
            .get(&host_key)
            .is_some_and(|manager| manager.is_empty() && manager.evictions_total() == 0)
        {
            retention.remove(&host_key);
        }
        subtree
    }

    pub(crate) fn insert_retained(
        &self,
        host: &Rc<SlotsHost>,
        key: RetainKey,
        subtree: crate::slot::DetachedSubtree,
        pinned: bool,
    ) -> Vec<crate::slot::DetachedSubtree> {
        let policy = self.retention_policy();
        let mut retention_by_host = self.retention_by_host.borrow_mut();
        let manager = retention_by_host
            .entry(slots_storage_key(host))
            .or_insert_with(|| RetentionManager::new(policy));
        manager.set_policy(policy);
        if pinned {
            manager.insert_pinned(key, subtree)
        } else {
            manager.insert(key, subtree)
        }
    }

    pub(crate) fn take_retained_movable(
        &self,
        id: Key,
    ) -> Option<(Rc<SlotsHost>, crate::slot::DetachedSubtree)> {
        self.take_retained_movable_by_key(movable_retain_key(id))
    }

    fn take_retained_movable_by_key(
        &self,
        key: RetainKey,
    ) -> Option<(Rc<SlotsHost>, crate::slot::DetachedSubtree)> {
        let mut retention_by_host = self.retention_by_host.borrow_mut();
        let (host_key, manager) = retention_by_host
            .iter_mut()
            .find(|(_, manager)| manager.contains(key))?;
        let host = self.host_for_storage_key(*host_key)?;
        let subtree = manager.take(key)?;
        Some((host, subtree))
    }

    /// Takes a movable's retained content out of a slot table other than the
    /// one composing, which is how it crosses a subcomposition.
    pub(crate) fn take_retained_movable_elsewhere(
        &self,
        besides: &Rc<SlotsHost>,
        key: RetainKey,
    ) -> Option<(Rc<SlotsHost>, crate::slot::DetachedSubtree)> {
        let besides_key = slots_storage_key(besides);
        let mut retention_by_host = self.retention_by_host.borrow_mut();
        let (host_key, manager) = retention_by_host
            .iter_mut()
            .find(|(host_key, manager)| **host_key != besides_key && manager.contains(key))?;
        let host = self.host_for_storage_key(*host_key)?;
        let subtree = manager.take(key)?;
        Some((host, subtree))
    }

    /// Whether a movable's content is retained in any slot table, which is
    /// what a site waiting for it has to know: the content may have been let
    /// go by a parent composed in another host, such as a subcomposition.
    pub(crate) fn movable_retained_anywhere(&self, key: RetainKey) -> bool {
        self.retention_by_host
            .borrow()
            .values()
            .any(|manager| manager.contains(key))
    }

    /// The slot table a movable's content is attached to right now, if any.
    pub(crate) fn host_holding_movable(&self, id: Key) -> Option<Rc<SlotsHost>> {
        self.live_hosts
            .borrow()
            .values()
            .filter_map(std::rc::Weak::upgrade)
            .find(|host| host.borrow().movable_is_attached(id))
    }

    pub(crate) fn record_pending_movable(&self, host: &Rc<SlotsHost>, pending: PendingMovable) {
        let mut by_host = self.pending_movables_by_host.borrow_mut();
        let sites = by_host.entry(slots_storage_key(host)).or_default();
        if sites
            .iter()
            .all(|site| site.placeholder != pending.placeholder)
        {
            sites.push(pending);
        }
    }

    pub(crate) fn take_pending_movables(&self, host: &Rc<SlotsHost>) -> Vec<PendingMovable> {
        self.pending_movables_by_host
            .borrow_mut()
            .remove(&slots_storage_key(host))
            .unwrap_or_default()
    }

    /// Every slot table with a site still waiting for movable content. The
    /// content may be let go by a parent composed in another table, so a pass
    /// that ends has to look wider than itself.
    pub(crate) fn hosts_awaiting_movables(&self) -> Vec<Rc<SlotsHost>> {
        let waiting = self
            .pending_movables_by_host
            .borrow()
            .iter()
            .filter(|(_, sites)| !sites.is_empty())
            .map(|(host_key, _)| *host_key)
            .collect::<Vec<_>>();
        waiting
            .into_iter()
            .filter_map(|host_key| self.host_for_storage_key(host_key))
            .collect()
    }

    pub(crate) fn keep_pending_movables(&self, host: &Rc<SlotsHost>, sites: Vec<PendingMovable>) {
        if sites.is_empty() {
            return;
        }
        self.pending_movables_by_host
            .borrow_mut()
            .insert(slots_storage_key(host), sites);
    }

    pub(crate) fn advance_retention_pass(
        &self,
        host: &Rc<SlotsHost>,
    ) -> Vec<crate::slot::DetachedSubtree> {
        let host_key = slots_storage_key(host);
        let policy = self.retention_policy();
        let mut retention_by_host = self.retention_by_host.borrow_mut();
        let Some(manager) = retention_by_host.get_mut(&host_key) else {
            return Vec::new();
        };
        manager.set_policy(policy);
        manager.advance_pass()
    }

    pub(crate) fn fill_slot_debug_snapshot(
        &self,
        host: &SlotsHost,
        snapshot: &mut crate::SlotDebugSnapshot,
    ) {
        let retention = self.retention_debug_stats(host.storage_key());
        snapshot.retained_subtree_count = retention.subtree_count;
        snapshot.retained_group_count = retention.group_count;
        snapshot.retained_payload_count = retention.payload_count;
        snapshot.retained_node_count = retention.node_count;
        snapshot.retained_scope_count = retention.scope_count;
    }

    pub(crate) fn slot_retention_debug_stats(
        &self,
        host: &SlotsHost,
    ) -> crate::slot::SlotRetentionDebugStats {
        let retention = self.retention_debug_stats(host.storage_key());
        crate::slot::SlotRetentionDebugStats {
            retained_subtree_count: retention.subtree_count,
            retained_group_count: retention.group_count,
            retained_payload_count: retention.payload_count,
            retained_node_count: retention.node_count,
            retained_scope_count: retention.scope_count,
            retained_anchor_count: retention.anchor_count,
            retained_heap_bytes: retention.heap_bytes,
            retained_evictions_total: retention.evictions_total,
        }
    }

    pub(crate) fn compact_table_identity_storage_for_host(
        &self,
        host: &SlotsHost,
        table: &mut SlotTable,
        compact_anchors: bool,
        compact_payloads: bool,
    ) {
        if !compact_anchors && !compact_payloads {
            return;
        }

        let host_key = host.storage_key();
        let mut retention = self.retention_by_host.borrow_mut();
        if let Some(retained) = retention.get_mut(&host_key) {
            if compact_anchors {
                table.compact_anchor_registry_storage(Some(&mut *retained));
            }
            if compact_payloads {
                table.compact_payload_anchor_registry_storage(Some(&mut *retained));
            }
        } else {
            if compact_anchors {
                table.compact_anchor_registry_storage(None);
            }
            if compact_payloads {
                table.compact_payload_anchor_registry_storage(None);
            }
        }
    }

    pub(crate) fn clear_host(&self, host: &SlotsHost, table: &mut SlotTable) {
        let host_key = host.storage_key();
        debug_assert!(
            self.host_retention_is_empty(host),
            "host retention must be drained before clearing host ownership"
        );
        self.clear_host_storage_key(host_key, table);
    }

    fn deactivate_and_queue_subtrees(
        &self,
        retention: RetentionManager,
        table: &mut SlotTable,
        lifecycle: &mut crate::slot::SlotLifecycleCoordinator,
    ) {
        for subtree in retention.into_subtrees() {
            for scope in subtree.scopes() {
                scope.deactivate();
            }
            table.invalidate_detached_subtree_anchors(&subtree);
            lifecycle.queue_subtree_disposal(subtree);
        }
    }

    pub(crate) fn dispose_retained_subtrees_for_host(
        &self,
        host_key: usize,
        table: &mut SlotTable,
        lifecycle: &mut crate::slot::SlotLifecycleCoordinator,
    ) -> Result<(), NodeError> {
        let retention = self.retention_by_host.borrow_mut().remove(&host_key);
        let applier_host = self
            .applier_host
            .borrow()
            .as_ref()
            .and_then(std::rc::Weak::upgrade);
        if let Some(applier_host) = applier_host {
            let mut disposal = crate::NodeDisposal::default();
            if let Some(retention) = retention {
                for subtree in retention.into_subtrees() {
                    subtree.scopes().for_each(RecomposeScope::deactivate);
                    table.invalidate_detached_subtree_anchors(&subtree);
                    disposal.retain_subtree(subtree);
                }
            }
            applier_host.dispose_nodes(disposal)?;
        } else if let Some(retention) = retention {
            self.deactivate_and_queue_subtrees(retention, table, lifecycle);
        }
        Ok(())
    }

    pub(crate) fn abandon_retained_subtrees_for_host(
        &self,
        host_key: usize,
        table: &mut SlotTable,
        lifecycle: &mut crate::slot::SlotLifecycleCoordinator,
    ) {
        let Some(retention) = self.retention_by_host.borrow_mut().remove(&host_key) else {
            self.clear_host_storage_key(host_key, table);
            return;
        };
        self.deactivate_and_queue_subtrees(retention, table, lifecycle);
        self.clear_host_storage_key(host_key, table);
    }

    pub(crate) fn host_retention_is_empty(&self, host: &SlotsHost) -> bool {
        self.retention_by_host
            .borrow()
            .get(&host.storage_key())
            .is_none_or(RetentionManager::is_empty)
    }

    #[cfg(any(test, debug_assertions))]
    pub(crate) fn debug_verify_host(&self, host: &SlotsHost, table: &SlotTable) {
        if let Some(retention) = self.retention_by_host.borrow().get(&host.storage_key()) {
            retention.debug_verify(table);
        }
    }

    #[cfg(test)]
    pub(crate) fn validate_host_retention(
        &self,
        host: &SlotsHost,
        table: &SlotTable,
    ) -> Result<(), crate::slot::SlotInvariantError> {
        if let Some(retention) = self.retention_by_host.borrow().get(&host.storage_key()) {
            retention.validate(table)?;
        }
        Ok(())
    }

    pub(crate) fn host_for_storage_key(&self, storage_key: usize) -> Option<Rc<SlotsHost>> {
        self.live_hosts
            .borrow()
            .get(&storage_key)
            .and_then(std::rc::Weak::upgrade)
    }

    fn retention_debug_stats(&self, host_key: usize) -> crate::retention::RetentionDebugStats {
        self.retention_by_host
            .borrow()
            .get(&host_key)
            .map(RetentionManager::debug_stats)
            .unwrap_or_default()
    }
}

pub(crate) struct ParentFrame {
    pub(crate) id: NodeId,
    pub(crate) previous: ChildList,
    pub(crate) new_children: ChildList,
    pub(crate) new_children_membership: Option<HashSet<NodeId>>,
    pub(crate) attach_mode: ParentAttachMode,
    pub(crate) synthetic_root: bool,
}

#[derive(Clone, Copy)]
pub(crate) enum InitialParentFrame {
    SyntheticRoot,
    RealParent,
}

const LARGE_DEFERRED_CHILD_TRACKING_THRESHOLD: usize = 16;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ParentAttachMode {
    ImmediateAppend,
    DeferredSync,
}

#[derive(Default)]
pub(crate) struct SubcomposeFrame {
    pub(crate) nodes: Vec<NodeId>,
    pub(crate) scopes: Vec<RecomposeScope>,
}

/// The values one provider supplies, over the frames of the providers around
/// it.
pub(crate) struct LocalFrame {
    values: SmallVec<[(LocalKey, Rc<dyn Any>); 2]>,
    parent: LocalStackSnapshot,
}

/// The entry the innermost provider in `stack` supplies for `key`.
fn provided_entry(stack: &LocalStackSnapshot, key: &LocalKey) -> Option<Rc<dyn Any>> {
    let mut frame = stack.as_deref();
    while let Some(current) = frame {
        if let Some((_, entry)) = current.values.iter().find(|(provided, _)| provided == key) {
            return Some(Rc::clone(entry));
        }
        frame = current.parent.as_deref();
    }
    None
}

pub(crate) struct ComposerCore {
    pub(crate) shared_state: Rc<ComposerRuntimeState>,
    pub(crate) slots: Rc<SlotsHost>,
    slot_hosts: RefCell<Vec<Rc<SlotsHost>>>,
    pub(crate) applier: Rc<dyn ApplierHost>,
    pub(crate) runtime: RuntimeHandle,
    pub(crate) parent_stack: RefCell<Vec<ParentFrame>>,
    pub(crate) subcompose_stack: RefCell<Vec<SubcomposeFrame>>,
    pub(crate) root: Cell<Option<NodeId>>,
    pub(crate) commands: RefCell<CommandQueue>,
    pub(crate) scope_stack: RefCell<Vec<RecomposeScope>>,
    subcomposition_owner_scope: RefCell<Option<RecomposeScope>>,
    pub(crate) local_stack: RefCell<LocalStackSnapshot>,
    pub(crate) side_effects: RefCell<Vec<Box<dyn FnOnce()>>>,
    pub(crate) pending_scope_options: RefCell<Option<RecomposeOptions>>,
    pub(crate) phase: Cell<crate::Phase>,
    pub(crate) last_node_reused: Cell<Option<bool>>,
    pub(crate) recompose_parent_hint: Cell<Option<NodeId>>,
    pub(crate) recompose_child_cursor: Cell<Option<usize>>,
    pub(crate) root_render_requested: Cell<bool>,
    pub(crate) _not_send: PhantomData<*const ()>,
}

/// The composition context inherited by work that is composed in another slot
/// host. Besides composition locals, this carries the source owner scope so a
/// secondary tree cannot outlive the composition that supplied its callbacks.
#[derive(Clone)]
pub struct CapturedCompositionContext {
    locals: LocalStackSnapshot,
    owner_scope: Option<Weak<RecomposeScopeInner>>,
}

impl CapturedCompositionContext {
    /// Total deactivations along the capturing scope's owner chain right now;
    /// see [`crate::RecomposeScope::owner_chain_deactivation_epoch`]. Zero
    /// when the context has no owner scope or it is gone.
    pub fn owner_chain_deactivation_epoch(&self) -> u64 {
        self.owner_scope
            .as_ref()
            .and_then(Weak::upgrade)
            .map_or(0, |inner| {
                crate::RecomposeScope { inner }.owner_chain_deactivation_epoch()
            })
    }
}

fn take_subcompose_frame(core: &ComposerCore, operation: &str) -> SubcomposeFrame {
    match core.subcompose_stack.borrow_mut().pop() {
        Some(frame) => frame,
        None => {
            log::error!("subcompose stack underflow while finishing {operation}");
            SubcomposeFrame::default()
        }
    }
}

struct SubcomposeStackGuard {
    core: Rc<ComposerCore>,
    leaked: bool,
}

impl Drop for SubcomposeStackGuard {
    fn drop(&mut self) {
        if !self.leaked {
            self.core.subcompose_stack.borrow_mut().pop();
        }
    }
}

impl Drop for ComposerCore {
    /// A pass that queued nothing never takes its queue: hand its storage
    /// back for the next pass.
    fn drop(&mut self) {
        let commands = std::mem::take(self.commands.get_mut());
        if commands.len() == 0 && commands.capacity() > 0 {
            recycle_commands(commands);
        }
    }
}

impl ComposerCore {
    pub(crate) fn open_branch_fold(&self, key: Key) -> BranchGroupGuard {
        let hosts = self.slot_hosts.borrow();
        let host = hosts.last().unwrap_or(&self.slots);
        BranchGroupGuard {
            fold: host
                .try_push_branch_fold(key)
                .map(|token| (Rc::clone(host), token)),
        }
    }

    pub(crate) fn new(
        shared_state: Rc<ComposerRuntimeState>,
        slots: Rc<SlotsHost>,
        applier: Rc<dyn ApplierHost>,
        runtime: RuntimeHandle,
        root: Option<NodeId>,
        initial_parent_frame: InitialParentFrame,
    ) -> Self {
        let parent_stack = if let Some(root_id) = root {
            vec![ParentFrame {
                id: root_id,
                previous: ChildList::new(),
                new_children: ChildList::new(),
                new_children_membership: None,
                attach_mode: ParentAttachMode::DeferredSync,
                synthetic_root: matches!(initial_parent_frame, InitialParentFrame::SyntheticRoot),
            }]
        } else {
            Vec::new()
        };

        let commands = spare_commands();
        Self {
            shared_state,
            slots,
            slot_hosts: RefCell::new(Vec::new()),
            applier,
            runtime,
            parent_stack: RefCell::new(parent_stack),
            subcompose_stack: RefCell::new(Vec::new()),
            root: Cell::new(root),
            commands: RefCell::new(commands),
            scope_stack: RefCell::new(Vec::new()),
            subcomposition_owner_scope: RefCell::new(None),
            local_stack: RefCell::new(None),
            side_effects: RefCell::new(Vec::new()),
            pending_scope_options: RefCell::new(None),
            phase: Cell::new(crate::Phase::Compose),
            last_node_reused: Cell::new(None),
            recompose_parent_hint: Cell::new(None),
            recompose_child_cursor: Cell::new(None),
            root_render_requested: Cell::new(false),
            _not_send: PhantomData,
        }
    }
}

#[derive(Clone)]
pub struct Composer {
    pub(crate) core: Rc<ComposerCore>,
}

pub struct BranchGroupGuard {
    fold: Option<(Rc<SlotsHost>, usize)>,
}

impl Drop for BranchGroupGuard {
    fn drop(&mut self) {
        let Some((host, token)) = &self.fold else {
            return;
        };
        if !host.try_close_branch_fold(*token) {
            log::error!("a branch fold guard closed while its slot host was busy");
        }
    }
}

pub(crate) enum EmittedNode {
    Fresh(Box<dyn Node>),
    Recycled(RecycledNode),
}

impl Composer {
    pub(crate) fn new_with_shared_state(
        shared_state: Rc<ComposerRuntimeState>,
        slots: Rc<SlotsHost>,
        applier: Rc<dyn ApplierHost>,
        runtime: RuntimeHandle,
        root: Option<NodeId>,
    ) -> Self {
        Self::new_with_shared_state_with_parent_frame(
            shared_state,
            slots,
            applier,
            runtime,
            root,
            InitialParentFrame::SyntheticRoot,
        )
    }

    fn new_with_shared_state_with_parent_frame(
        shared_state: Rc<ComposerRuntimeState>,
        slots: Rc<SlotsHost>,
        applier: Rc<dyn ApplierHost>,
        runtime: RuntimeHandle,
        root: Option<NodeId>,
        initial_parent_frame: InitialParentFrame,
    ) -> Self {
        shared_state.bind_applier_host(&applier);
        let slots = bind_slots_host_to_runtime_state(&shared_state, &slots);
        let core = Rc::new(ComposerCore::new(
            shared_state,
            slots,
            applier,
            runtime,
            root,
            initial_parent_frame,
        ));
        Self { core }
    }

    pub fn new(
        slots: Rc<SlotsHost>,
        applier: Rc<dyn ApplierHost>,
        runtime: RuntimeHandle,
        root: Option<NodeId>,
    ) -> Self {
        Self::new_with_shared_state_with_parent_frame(
            slots
                .runtime_state()
                .unwrap_or_else(|| Rc::new(ComposerRuntimeState::default())),
            slots,
            applier,
            runtime,
            root,
            InitialParentFrame::RealParent,
        )
    }

    pub(crate) fn from_core(core: Rc<ComposerCore>) -> Self {
        Self { core }
    }

    pub(crate) fn clone_core(&self) -> Rc<ComposerCore> {
        Rc::clone(&self.core)
    }

    pub(crate) fn request_root_render(&self) {
        self.core.root_render_requested.set(true);
    }

    pub(crate) fn take_root_render_request(&self) -> bool {
        self.core.root_render_requested.replace(false)
    }

    pub fn active_slots_host(&self) -> Rc<SlotsHost> {
        self.core
            .slot_hosts
            .borrow()
            .last()
            .cloned()
            .unwrap_or_else(|| Rc::clone(&self.core.slots))
    }

    fn with_active_slots_host<R>(&self, f: impl FnOnce(&SlotsHost) -> R) -> R {
        let hosts = self.core.slot_hosts.borrow();
        f(hosts.last().unwrap_or(&self.core.slots))
    }

    pub(crate) fn with_slots<R>(&self, f: impl FnOnce(&SlotTable) -> R) -> R {
        self.with_active_slots_host(|host| f(&host.borrow()))
    }

    pub(crate) fn with_slots_mut<R>(&self, f: impl FnOnce(&mut SlotTable) -> R) -> R {
        self.with_active_slots_host(|host| f(&mut host.borrow_mut()))
    }

    pub(crate) fn with_slot_session_mut<R>(
        &self,
        f: impl FnOnce(&mut crate::slot::SlotWriteSession<'_>) -> R,
    ) -> R {
        self.with_active_slots_host(|host| host.with_write_session(f))
    }

    pub(crate) fn try_with_slot_host_pass<R>(
        &self,
        slots: Rc<SlotsHost>,
        mode: crate::slot::SlotPassMode,
        f: impl FnOnce(&Composer) -> R,
    ) -> Result<(R, SlotPassOutcome), NodeError> {
        let mut guard = self.begin_slot_host_pass(&slots, mode);
        let result = f(self);
        let outcome = self.finish_slot_host_pass(&guard.host)?;
        guard.close();
        Ok((result, outcome))
    }

    pub(crate) fn with_slot_host_pass<R>(
        &self,
        slots: Rc<SlotsHost>,
        mode: crate::slot::SlotPassMode,
        f: impl FnOnce(&Composer) -> R,
    ) -> (R, SlotPassOutcome) {
        let mut guard = self.begin_slot_host_pass(&slots, mode);
        let result = f(self);
        let outcome = match self.finish_slot_host_pass(&guard.host) {
            Ok(outcome) => outcome,
            Err(err) => {
                log::error!("slot host pass finalization failed: {err}");
                SlotPassOutcome::default()
            }
        };
        guard.close();
        (result, outcome)
    }

    pub(crate) fn with_slot_override<R>(
        &self,
        slots: Rc<SlotsHost>,
        f: impl FnOnce(&Composer) -> R,
    ) -> (R, SlotPassOutcome) {
        self.with_slot_host_pass(slots, crate::slot::SlotPassMode::Compose, f)
    }

    fn begin_slot_host_pass(
        &self,
        slots: &Rc<SlotsHost>,
        mode: crate::slot::SlotPassMode,
    ) -> SlotHostPassGuard {
        let slots = bind_slots_host_to_runtime_state(&self.core.shared_state, slots);
        slots.begin_pass(mode);
        {
            let mut stack = self.core.slot_hosts.borrow_mut();
            if let Some(parent) = stack.last()
                && !Rc::ptr_eq(parent, &slots)
            {
                parent.note_nested_host(&slots);
            }
            stack.push(Rc::clone(&slots));
        }
        SlotHostPassGuard {
            core: self.clone_core(),
            host: slots,
            active: true,
        }
    }

    fn finish_slot_host_pass(&self, slots: &Rc<SlotsHost>) -> Result<SlotPassOutcome, NodeError> {
        let finished = {
            let mut applier = self.core.applier.borrow_dyn();
            slots.finish_pass(&mut *applier)
        }?;
        self.handle_detached_children_in_host(slots, None, finished.detached_root_children)?;
        self.wake_sites_whose_movable_arrived();
        self.evict_retained_subtrees_for_host(slots)?;
        slots.complete_pass_cleanup(&finished.outcome);
        Ok(finished.outcome)
    }

    fn wake_sites_whose_movable_arrived(&self) {
        for host in self.core.shared_state.hosts_awaiting_movables() {
            self.wake_sites_in_host(&host);
        }
    }

    fn wake_sites_in_host(&self, slots: &Rc<SlotsHost>) {
        let pending = self.core.shared_state.take_pending_movables(slots);
        if pending.is_empty() {
            return;
        }
        let mut waiting = Vec::new();
        for site in pending {
            if !slots.borrow().group_is_active(site.placeholder) {
                continue;
            }
            let retain_key = RetainKey::for_group(None, site.key);
            if !self.core.shared_state.movable_retained_anywhere(retain_key) {
                waiting.push(site);
                continue;
            }
            match site.parent_scope.as_ref().and_then(RecomposeScope::upgrade) {
                Some(scope) => {
                    scope.force_recompose();
                    scope.invalidate();
                }
                None => log::error!(
                    "movable content {:?} arrived for a site whose scope is gone",
                    site.key
                ),
            }
        }
        self.core.shared_state.keep_pending_movables(slots, waiting);
    }

    pub(crate) fn forget_movables(&self, ids: &[Key]) -> Result<(), NodeError> {
        for id in ids {
            let Some((host, subtree)) = self.core.shared_state.take_retained_movable(*id) else {
                continue;
            };
            self.dispose_detached_subtree_in_host(&host, subtree)?;
            host.flush_pending_drops();
        }
        Ok(())
    }

    pub(crate) fn parent_stack(&self) -> RefMut<'_, Vec<ParentFrame>> {
        self.core.parent_stack.borrow_mut()
    }

    pub(crate) fn current_parent_hint(&self) -> Option<NodeId> {
        let stack = self.core.parent_stack.borrow();
        let stack_hint = stack
            .last()
            .and_then(|frame| (!frame.synthetic_root).then_some(frame.id));
        stack_hint.or_else(|| self.core.recompose_parent_hint.get())
    }

    pub(crate) fn subcompose_stack(&self) -> RefMut<'_, Vec<SubcomposeFrame>> {
        self.core.subcompose_stack.borrow_mut()
    }

    pub(crate) fn commands_mut(&self) -> RefMut<'_, CommandQueue> {
        self.core.commands.borrow_mut()
    }

    pub(crate) fn enqueue_semantics_invalidation(&self, id: NodeId) {
        self.commands_mut().push(Command::BubbleDirty {
            node_id: id,
            bubble: DirtyBubble::SEMANTICS,
        });
    }

    pub(crate) fn scope_stack(&self) -> RefMut<'_, Vec<RecomposeScope>> {
        self.core.scope_stack.borrow_mut()
    }

    pub(crate) fn local_stack(&self) -> RefMut<'_, LocalStackSnapshot> {
        self.core.local_stack.borrow_mut()
    }

    pub(crate) fn current_local_stack(&self) -> LocalStackSnapshot {
        self.core.local_stack.borrow().clone()
    }

    pub(crate) fn side_effects_mut(&self) -> RefMut<'_, Vec<Box<dyn FnOnce()>>> {
        self.core.side_effects.borrow_mut()
    }

    fn pending_scope_options(&self) -> RefMut<'_, Option<RecomposeOptions>> {
        self.core.pending_scope_options.borrow_mut()
    }

    pub(crate) fn borrow_applier(&self) -> ApplierGuard<'_, dyn Applier> {
        self.core.applier.borrow_dyn()
    }

    /// Records nodes whose retained subtrees a reused subcompose slot just
    /// rebound to new content.
    ///
    /// The rebinding recomposes inline during measure, so every repass it
    /// schedules is consumed by the layout pass already running — nothing
    /// else survives to tell the scoped scene update these subtrees changed,
    /// and a translate-only update would keep their stale layers (measured:
    /// a 60pt lazy scroll presented the old row's text at the new row's
    /// position). The structural-change set is the one channel drained
    /// after layout, so the rebound children ride it.
    pub fn record_rebound_slot_children(&self, children: &[NodeId]) {
        let mut applier = self.borrow_applier();
        for &child in children {
            applier.record_structural_change(child);
        }
    }

    /// Registers a virtual node in the Applier.
    ///
    /// Assigns the node's ID so its layout registry and invalidation metadata
    /// belong to the node stored in the applier.
    pub fn register_virtual_node(
        &self,
        node_id: NodeId,
        node: Box<dyn Node>,
    ) -> Result<(), NodeError> {
        let mut applier = self.borrow_applier();
        applier.insert_with_id(node_id, node)?;
        applier.get_mut(node_id)?.set_node_id(node_id);
        Ok(())
    }

    /// Detaches and disposes subcomposition roots evicted from their reuse pool.
    /// Applies pending composition commands before releasing the roots and their descendants.
    ///
    /// ```no_run
    /// # use cranpose_core::{Composer, NodeError, SubcomposeState};
    /// # fn finish(composer: &Composer, state: &mut SubcomposeState) -> Result<(), NodeError> {
    /// let evicted = state.finish_pass();
    /// composer.dispose_subcomposed_nodes(evicted)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn dispose_subcomposed_nodes(
        &self,
        disposal: crate::subcompose::SubcomposeDisposal,
    ) -> Result<(), NodeError> {
        if disposal.nodes.is_empty() && disposal.slot_hosts.is_empty() {
            return Ok(());
        }
        self.apply_pending_commands()?;
        let disposal = crate::NodeDisposal::from_subcomposed(disposal, &*self.borrow_applier());
        self.core.applier.dispose_nodes(disposal)
    }

    /// Checks if a node has no parent (is a root node).
    /// Used by SubcomposeMeasureScope to filter subcompose results.
    pub fn node_has_no_parent(&self, node_id: NodeId) -> bool {
        let mut applier = self.borrow_applier();
        match applier.get_mut(node_id) {
            Ok(node) => node.parent().is_none(),
            Err(_) => true,
        }
    }

    /// Returns a node's parent, or `None` for a root node.
    ///
    /// Returns an error when the node is no longer present in the applier.
    pub fn node_parent(&self, node_id: NodeId) -> Result<Option<NodeId>, NodeError> {
        self.borrow_applier()
            .get_mut(node_id)
            .map(|node| node.parent())
    }

    /// Gets the children of a node from the Applier.
    ///
    /// This is used by SubcomposeLayoutNode to get children of virtual nodes
    /// directly from the Applier, where insert_child commands have been applied.
    pub fn get_node_children(&self, node_id: NodeId) -> SmallVec<[NodeId; 8]> {
        let mut applier = self.borrow_applier();
        match applier.get_mut(node_id) {
            Ok(node) => {
                let mut children = SmallVec::<[NodeId; 8]>::new();
                node.collect_children_into(&mut children);
                children
            }
            Err(_) => SmallVec::<[NodeId; 8]>::new(),
        }
    }

    /// Whether any node needs measurement or placement before its cached layout can be reused.
    ///
    /// ```no_run
    /// # use cranpose_core::{Composer, NodeId};
    /// # fn cache_is_current(composer: &Composer, children: &[NodeId]) -> bool {
    /// !composer.nodes_need_relayout(children.iter().copied())
    /// # }
    /// ```
    pub fn nodes_need_relayout(&self, node_ids: impl IntoIterator<Item = NodeId>) -> bool {
        let mut applier = self.borrow_applier();
        node_ids.into_iter().any(|node_id| {
            applier
                .get_mut(node_id)
                .is_ok_and(|node| node.layout_dirty())
        })
    }

    /// Records a child node in the current parent frame's expected children list.
    ///
    /// Used by SubcomposeLayout's `perform_subcompose` to register virtual nodes
    /// with the outer composer's parent frame. This ensures that the `pop_parent`
    /// call at the end of `subcompose_slot` generates a correct `SyncChildren`
    /// command that preserves (rather than removes) the virtual nodes.
    ///
    /// Without this, `pop_parent` would generate `SyncChildren { expected: [] }`,
    /// which removes all virtual nodes and their subtrees from the applier.
    pub fn record_subcompose_child(&self, child_id: NodeId) {
        let mut parent_stack = self.parent_stack();
        if let Some(frame) = parent_stack.last_mut()
            && matches!(frame.attach_mode, ParentAttachMode::DeferredSync)
        {
            if let Some(membership) = frame.new_children_membership.as_mut() {
                if membership.insert(child_id) {
                    frame.new_children.push(child_id);
                }
            } else if frame.new_children.len() >= LARGE_DEFERRED_CHILD_TRACKING_THRESHOLD {
                let mut membership = HashSet::default();
                membership.reserve(frame.new_children.len() + 1);
                membership.extend(frame.new_children.iter().copied());
                if membership.insert(child_id) {
                    frame.new_children.push(child_id);
                }
                frame.new_children_membership = Some(membership);
            } else if !frame.new_children.contains(&child_id) {
                frame.new_children.push(child_id);
            }
        }
    }

    /// Clears all children of a node in the Applier.
    ///
    /// This is used by SubcomposeLayoutNode when reusing a virtual node for
    /// different content. Without clearing, old children remain attached,
    /// causing duplicate/interleaved items in lazy lists after scrolling.
    pub fn clear_node_children(&self, node_id: NodeId) {
        let mut applier = self.borrow_applier();
        if let Ok(node) = applier.get_mut(node_id) {
            node.update_children(&[]);
        }
    }

    pub fn install<R>(&self, f: impl FnOnce(&Composer) -> R) -> R {
        let _composer_guard = composer_context::enter(self);
        runtime::push_active_runtime(&self.core.runtime);
        struct Guard;
        impl Drop for Guard {
            fn drop(&mut self) {
                runtime::pop_active_runtime();
            }
        }
        let guard = Guard;
        let result = f(self);
        drop(guard);
        result
    }

    pub(crate) fn flush_pending_commands_if_large(&self) -> Result<(), NodeError> {
        let queued = self.core.commands.borrow().len();
        if queued < COMMAND_FLUSH_THRESHOLD {
            return Ok(());
        }
        self.apply_pending_commands()
    }

    fn resolve_group_entry(
        &self,
        host: &Rc<SlotsHost>,
        seed: crate::slot::GroupKeySeed,
        parent_scope_id: Option<ScopeId>,
    ) -> GroupEntry {
        let key = host.with_write_session(|slots| slots.reserve_group_key(seed));
        let retain_key = RetainKey::for_group(parent_scope_id, key);
        let restored = self
            .core
            .shared_state
            .take_retained(host, retain_key, |subtree| {
                host.with_write_session(|slots| slots.retained_restore_ready(key, subtree))
            })
            .or_else(|| self.take_movable_from_another_table(host, retain_key, key))
            .map(Box::new);
        if restored.is_some() || !key.is_movable() {
            return GroupEntry {
                key,
                restored,
                placeholder_for: None,
            };
        }
        let attached_elsewhere = self.movable_attached_elsewhere(host, key);
        if !attached_elsewhere {
            return GroupEntry {
                key,
                restored: None,
                placeholder_for: None,
            };
        }
        let id = key.explicit_key.unwrap_or_default();
        let placeholder = host.with_write_session(|slots| {
            slots.reserve_group_key(crate::slot::GroupKeySeed::movable_placeholder(id))
        });
        GroupEntry {
            key: placeholder,
            restored: None,
            placeholder_for: Some(key),
        }
    }

    /// Movable content that was let go by a parent composed in another slot
    /// table — a `SubcomposeLayout`'s, or the one a subcomposition owns — is
    /// retained there, not here. Bring it over: the table that held it lets
    /// go of its anchors, and this one issues its own.
    fn take_movable_from_another_table(
        &self,
        host: &Rc<SlotsHost>,
        retain_key: RetainKey,
        key: crate::slot::GroupKey,
    ) -> Option<crate::slot::DetachedSubtree> {
        if !key.is_movable() {
            return None;
        }
        let (source, mut subtree) = self
            .core
            .shared_state
            .take_retained_movable_elsewhere(host, retain_key)?;
        source
            .borrow_mut()
            .invalidate_detached_subtree_anchors(&subtree);
        if host.with_write_session(|slots| slots.retained_restore_ready(key, &mut subtree)) {
            return Some(subtree);
        }
        log::error!(
            "movable content {key:?} could not be taken over by the slot table that asked for it"
        );
        if let Err(error) = self.dispose_detached_subtree_in_host(host, subtree) {
            log::error!("disposing movable content that could not move failed: {error}");
        }
        None
    }

    /// Whether the movable's content is attached to some parent that is not
    /// the one composing, in this slot table or in another.
    fn movable_attached_elsewhere(&self, host: &Rc<SlotsHost>, key: crate::slot::GroupKey) -> bool {
        if host.with_write_session(|slots| slots.movable_attached_elsewhere(key)) {
            return true;
        }
        let Some(id) = key.movable_id() else {
            return false;
        };
        self.core
            .shared_state
            .host_holding_movable(id)
            .is_some_and(|holder| !Rc::ptr_eq(&holder, host))
    }

    fn scope_for_started_group(
        &self,
        host: &SlotsHost,
        group: crate::slot::ActiveGroupId,
        scope: Option<RecomposeScope>,
    ) -> RecomposeScope {
        if let Some(scope) = scope {
            return scope;
        }
        let scope = RecomposeScope::new(self.runtime_handle());
        host.with_write_session(|slots| slots.set_group_scope(group, scope.clone()));
        scope
    }

    fn enter_group_scope(&self, scope_ref: &RecomposeScope, entry: GroupScopeEntry<'_>) {
        let GroupScopeEntry {
            options,
            start_kind,
            host,
            group,
        } = entry;
        // A group entered while its scope is inactive is reused content, as
        // when a lazy list gives a recycled row to another item: like Compose,
        // it composes again rather than skipping, which reactivates the
        // scopes beneath it.
        let reused = !scope_ref.is_active() && scope_ref.has_composed_once();
        scope_ref.reactivate();
        {
            let mut stack = self.scope_stack();
            let parent_scope = stack.last();
            scope_ref.set_parent_scope(parent_scope);
            if parent_scope.is_none() {
                scope_ref.set_lifetime_owner_scope(
                    self.core.subcomposition_owner_scope.borrow().as_ref(),
                );
            } else {
                scope_ref.set_lifetime_owner_scope(None);
            }
            stack.push(scope_ref.clone());
        }
        scope_ref.set_retention_mode(options.retention);

        if options.force_recompose {
            scope_ref.force_recompose();
        } else if options.force_reuse {
            scope_ref.force_reuse();
        } else if reused {
            scope_ref.force_recompose();
        }
        let restored = matches!(start_kind, GroupStartKind::Restored);
        if restored {
            scope_ref.force_recompose();
        }

        scope_ref.set_slots_host(host);

        {
            let mut stack = self.subcompose_stack();
            if let Some(frame) = stack.last_mut() {
                frame.scopes.push(scope_ref.clone());
            }
        }

        scope_ref.snapshot_locals(&self.core.local_stack.borrow());
        let parent_hint = self.current_parent_hint();
        if restored {
            reparent_restored_scopes(host, group, scope_ref.parent_hint(), parent_hint);
        }
        scope_ref.set_parent_hint(parent_hint);
    }

    #[inline(never)]
    fn with_group_in_active_pass_dyn(
        &self,
        host: &Rc<SlotsHost>,
        key: crate::slot::GroupKeySeed,
        f: &mut dyn FnMut(&Composer),
    ) {
        struct GroupGuard<'a> {
            composer: &'a Composer,
            host: &'a Rc<SlotsHost>,
            scope: RecomposeScope,
        }

        impl Drop for GroupGuard<'_> {
            fn drop(&mut self) {
                let result = self.host.with_write_session(|slots| {
                    let result = slots.finish_group_body();
                    slots.end_group();
                    result
                });
                self.composer
                    .close_finished_group(self.host, &self.scope, result);
                self.scope.mark_recomposed();
                if let Err(err) = self.composer.flush_pending_commands_if_large() {
                    log::error!("mid-composition command flush failed: {err}");
                }
            }
        }

        let options = self.pending_scope_options().take().unwrap_or_default();
        let parent_scope_id = self
            .core
            .scope_stack
            .borrow()
            .last()
            .map(RecomposeScope::id);
        let GroupEntry {
            key: reserved_key,
            restored,
            placeholder_for,
        } = self.resolve_group_entry(host, key, parent_scope_id);
        let parent_node = self.current_parent_hint();
        let GroupStart {
            group,
            anchor,
            scope,
            kind,
        } = host.with_write_session(|slots| slots.begin_group(reserved_key, restored, parent_node));
        let scope_ref = self.scope_for_started_group(host, group, scope);
        if let Some(movable_key) = placeholder_for {
            self.core.shared_state.record_pending_movable(
                host,
                PendingMovable {
                    key: movable_key,
                    placeholder: anchor,
                    parent_scope: self
                        .core
                        .scope_stack
                        .borrow()
                        .last()
                        .map(RecomposeScope::downgrade),
                },
            );
        }
        self.enter_group_scope(
            &scope_ref,
            GroupScopeEntry {
                options,
                start_kind: kind,
                host,
                group,
            },
        );

        let guard = GroupGuard {
            composer: self,
            host,
            scope: scope_ref,
        };
        if placeholder_for.is_none() {
            f(self);
        }
        guard.scope.mark_composed_once();
        drop(guard);
    }

    fn with_group_seed_dyn(&self, key: crate::slot::GroupKeySeed, f: &mut dyn FnMut(&Composer)) {
        let host = self.active_slots_host();
        if host.has_active_pass() {
            self.with_group_in_active_pass_dyn(&host, key, f);
            return;
        }
        self.with_slot_host_pass(host, crate::slot::SlotPassMode::Compose, |composer| {
            composer.with_group_in_active_pass_dyn(&composer.active_slots_host(), key, f);
        });
    }

    pub(crate) fn with_group_seed<R>(
        &self,
        key: crate::slot::GroupKeySeed,
        f: impl FnOnce(&Composer) -> R,
    ) -> R {
        let mut f = Some(f);
        let mut result = None;
        self.with_group_seed_dyn(key, &mut |composer| {
            let f = f.take().expect("group body must run at most once");
            result = Some(f(composer));
        });
        result.expect("group body must run exactly once")
    }

    pub(crate) fn with_movable_group(&self, id: Key, f: impl FnOnce(&Composer)) {
        let mut f = Some(f);
        self.with_group_seed_dyn(crate::slot::GroupKeySeed::movable(id), &mut |composer| {
            if let Some(f) = f.take() {
                f(composer);
            }
        });
    }

    pub fn with_group<R>(&self, key: Key, f: impl FnOnce(&Composer) -> R) -> R {
        self.with_group_seed(crate::slot::GroupKeySeed::unkeyed(key), f)
    }

    pub fn cranpose_with_reuse<R>(
        &self,
        key: Key,
        mut options: RecomposeOptions,
        f: impl FnOnce(&Composer) -> R,
    ) -> R {
        options.retention = RetentionMode::RetainWhenInactive;
        self.pending_scope_options().replace(options);
        self.with_group(key, f)
    }

    #[track_caller]
    pub fn with_key<K: Hash, R>(&self, key: &K, f: impl FnOnce(&Composer) -> R) -> R {
        let seed = explicit_group_key_seed(key, std::panic::Location::caller());
        self.with_group_seed(seed, f)
    }

    #[doc(hidden)]
    pub fn __branch_group_deferred(&self, key: Key) -> BranchGroupGuard {
        self.core.open_branch_fold(key)
    }

    fn dispose_detached_nodes(&self, nodes: impl IntoIterator<Item = NodeId>) {
        for node_id in nodes {
            self.commands_mut().push(Command::callback(move |applier| {
                crate::slot::dispose_detached_node_now(applier, node_id)
            }));
        }
    }

    fn detached_root_parent_commands(
        &self,
        subtree: &crate::slot::DetachedSubtree,
        context: &'static str,
    ) -> Result<Vec<(NodeId, Option<NodeId>)>, NodeError> {
        let mut root_nodes = Vec::new();
        subtree.collect_root_nodes_checked_into(&mut root_nodes, context);
        let mut roots = Vec::with_capacity(root_nodes.len());
        for root in root_nodes {
            let parent_id = {
                let mut applier = self.borrow_applier();
                applier.get_mut(root)?.parent()
            };
            roots.push((root, parent_id));
        }
        Ok(roots)
    }

    fn retain_detached_subtree_in_host(
        &self,
        slots_host: &Rc<SlotsHost>,
        parent_scope: Option<ScopeId>,
        subtree: crate::slot::DetachedSubtree,
    ) -> Result<(), NodeError> {
        let Some(root_key) = subtree.root_key_checked() else {
            log::error!("retention rejected detached subtree without a root group");
            self.dispose_detached_subtree_in_host(slots_host, subtree)?;
            return Ok(());
        };
        let root_detaches = self.detached_root_parent_commands(&subtree, "retention")?;
        subtree.scopes().for_each(RecomposeScope::deactivate);
        for (root, parent_id) in root_detaches {
            if let Some(parent_id) = parent_id {
                self.commands_mut().push(Command::DetachChild {
                    parent_id,
                    child_id: root,
                });
            }
        }
        let evicted = self.core.shared_state.insert_retained(
            slots_host,
            RetainKey::for_group(parent_scope, root_key),
            subtree,
            root_key.is_movable(),
        );
        for subtree in evicted {
            self.dispose_detached_subtree_in_host(slots_host, subtree)?;
        }
        Ok(())
    }

    fn evict_retained_subtrees_for_host(
        &self,
        slots_host: &Rc<SlotsHost>,
    ) -> Result<(), NodeError> {
        let evicted = self.core.shared_state.advance_retention_pass(slots_host);
        for subtree in evicted {
            self.dispose_detached_subtree_in_host(slots_host, subtree)?;
        }
        Ok(())
    }

    fn dispose_detached_subtree_in_host(
        &self,
        slots_host: &Rc<SlotsHost>,
        subtree: crate::slot::DetachedSubtree,
    ) -> Result<(), NodeError> {
        let root_nodes = self
            .detached_root_parent_commands(&subtree, "disposal")?
            .into_iter()
            .map(|(root, _)| root);
        subtree.scopes().for_each(RecomposeScope::deactivate);
        self.dispose_detached_nodes(root_nodes);
        slots_host.with_table_and_lifecycle_mut(|table, lifecycle| {
            table.invalidate_detached_subtree_anchors(&subtree);
            lifecycle.queue_subtree_disposal(subtree);
        });
        Ok(())
    }

    fn handle_detached_children_in_host(
        &self,
        slots_host: &Rc<SlotsHost>,
        parent_scope: Option<ScopeId>,
        detached: Vec<crate::slot::DetachedSubtree>,
    ) -> Result<(), NodeError> {
        for mut subtree in detached {
            for movable in subtree.split_off_nested_movables() {
                self.retain_detached_subtree_in_host(slots_host, None, movable)?;
            }
            if subtree
                .root_key_checked()
                .is_some_and(crate::slot::GroupKey::is_movable)
            {
                self.retain_detached_subtree_in_host(slots_host, None, subtree)?;
                continue;
            }
            let retention_mode = subtree
                .root_scope()
                .map(RecomposeScope::retention_mode)
                .unwrap_or_default();
            match retention_mode {
                RetentionMode::DisposeWhenInactive => {
                    self.dispose_detached_subtree_in_host(slots_host, subtree)?;
                }
                RetentionMode::RetainWhenInactive => {
                    self.retain_detached_subtree_in_host(slots_host, parent_scope, subtree)?;
                }
            }
        }
        Ok(())
    }

    fn handle_finished_group_result(
        &self,
        host: &Rc<SlotsHost>,
        parent_scope: Option<ScopeId>,
        result: FinishGroupResult,
    ) {
        let FinishGroupResult {
            detached_children,
            direct_nodes,
            root_nodes,
            was_skipped,
        } = result;
        if was_skipped {
            self.attach_root_nodes(root_nodes);
        }
        self.dispose_detached_nodes(direct_nodes);
        if detached_children.is_empty() {
            return;
        }
        if let Err(err) =
            self.handle_detached_children_in_host(host, parent_scope, detached_children)
        {
            log::error!("detached subtree handling failed while closing a group: {err}");
        }
    }

    pub(crate) fn close_current_group_body_for_scope(&self, scope: &RecomposeScope) {
        self.close_group_body(&self.active_slots_host(), scope);
    }

    fn close_group_body(&self, host: &Rc<SlotsHost>, scope: &RecomposeScope) {
        #[expect(
            clippy::redundant_closure_for_method_calls,
            reason = "the method path is not general over the session lifetime"
        )]
        let result = host.with_write_session(|slots| slots.finish_group_body());
        self.close_finished_group(host, scope, result);
    }

    fn close_finished_group(
        &self,
        host: &Rc<SlotsHost>,
        scope: &RecomposeScope,
        result: FinishGroupResult,
    ) {
        self.handle_finished_group_result(host, Some(scope.id()), result);
        if let Some(popped) = self.scope_stack().pop() {
            debug_assert_eq!(
                popped.id(),
                scope.id(),
                "closed scope must match the active scope stack"
            );
        } else {
            log::error!("scope stack underflow while closing scope {}", scope.id());
        }
    }

    #[track_caller]
    pub fn remember<T: 'static>(&self, init: impl FnOnce() -> T) -> Owned<T> {
        self.remember_at(crate::caller_location_key(), init)
    }

    #[doc(hidden)]
    pub fn remember_at<T: 'static>(
        &self,
        source: crate::Key,
        init: impl FnOnce() -> T,
    ) -> Owned<T> {
        self.with_slot_session_mut(|slots| {
            slots.remember_with_kind(PayloadKind::Remember, source, init)
        })
    }

    #[track_caller]
    pub(crate) fn remember_internal<T: 'static>(
        &self,
        source_salt: crate::Key,
        init: impl FnOnce() -> T,
    ) -> Owned<T> {
        let source = crate::caller_location_key() ^ source_salt;
        self.with_slot_session_mut(|slots| {
            slots.remember_with_kind(PayloadKind::Internal, source, init)
        })
    }

    #[track_caller]
    pub(crate) fn remember_effect<T: Default + 'static>(&self) -> Owned<T> {
        let source = crate::caller_location_key();
        self.with_slot_session_mut(|slots| slots.remember_effect::<T>(source))
    }

    #[track_caller]
    pub fn use_value_slot<T: 'static>(&self, init: impl FnOnce() -> T) -> ValueSlotHandle<'_, T> {
        let source = crate::caller_location_key();
        let slot = self.with_slot_session_mut(|slots| {
            slots.value_slot_with_kind(PayloadKind::Internal, source, init)
        });
        ValueSlotHandle::new(slot)
    }

    #[doc(hidden)]
    pub fn __use_param_slot<T: 'static>(
        &self,
        source: Key,
        init: impl FnOnce() -> T,
    ) -> ValueSlotHandle<'_, T> {
        let slot = self.with_slot_session_mut(|slots| {
            slots.value_slot_with_kind(PayloadKind::Param, source, init)
        });
        ValueSlotHandle::new(slot)
    }

    /// Finds the call's next parameter slot and runs `update` on its value,
    /// with one slot lookup for both.
    #[doc(hidden)]
    pub fn __update_param_slot<T: 'static, R>(
        &self,
        source: Key,
        init: impl FnOnce() -> T,
        update: impl FnOnce(&mut T) -> R,
    ) -> (ValueSlotHandle<'_, T>, R) {
        self.update_value_slot(PayloadKind::Param, source, init, update)
    }

    /// Finds the call's return slot and runs `read` on its value, with one
    /// slot lookup for both.
    #[doc(hidden)]
    pub fn __update_return_slot<T: 'static, R>(
        &self,
        source: Key,
        init: impl FnOnce() -> T,
        read: impl FnOnce(&mut T) -> R,
    ) -> (ValueSlotHandle<'_, T>, R) {
        self.update_value_slot(PayloadKind::Return, source, init, read)
    }

    fn update_value_slot<T: 'static, R>(
        &self,
        kind: PayloadKind,
        source: Key,
        init: impl FnOnce() -> T,
        update: impl FnOnce(&mut T) -> R,
    ) -> (ValueSlotHandle<'_, T>, R) {
        self.with_slot_session_mut(|slots| {
            let (slot, value) = slots.value_slot_and_value(kind, source, init);
            (ValueSlotHandle::new(slot), update(value))
        })
    }

    #[doc(hidden)]
    #[track_caller]
    pub fn __use_return_slot<T: 'static>(
        &self,
        init: impl FnOnce() -> T,
    ) -> ValueSlotHandle<'_, T> {
        let source = crate::caller_location_key();
        let slot = self.with_slot_session_mut(|slots| {
            slots.value_slot_with_kind(PayloadKind::Return, source, init)
        });
        ValueSlotHandle::new(slot)
    }

    #[doc(hidden)]
    pub fn __invalidate_return_consumer_scope(&self) {
        let Some(scope) = self.current_recompose_scope() else {
            self.request_root_render();
            return;
        };

        if let Some(target) = scope.callback_promotion_target() {
            target.invalidate();
        } else {
            self.request_root_render();
        }
    }

    pub fn with_slot_value<'pass, T: 'static, R>(
        &'pass self,
        handle: ValueSlotHandle<'pass, T>,
        f: impl FnOnce(&T) -> R,
    ) -> R {
        self.with_slots(|slots| f(slots.read_value(handle.slot())))
    }

    pub fn with_slot_value_mut<'pass, T: 'static, R>(
        &'pass self,
        handle: ValueSlotHandle<'pass, T>,
        f: impl FnOnce(&mut T) -> R,
    ) -> R {
        self.with_slots_mut(|slots| f(slots.read_value_mut(handle.slot())))
    }

    pub fn mutable_state_of<T: Clone + 'static>(&self, initial: T) -> MutableState<T> {
        MutableState::with_runtime(initial, self.runtime_handle())
    }

    pub fn mutable_state_list_of<T, I>(&self, values: I) -> SnapshotStateList<T>
    where
        T: Clone + 'static,
        I: IntoIterator<Item = T>,
    {
        SnapshotStateList::with_runtime(values, self.runtime_handle())
    }

    pub fn mutable_state_map_of<K, V, I>(&self, pairs: I) -> SnapshotStateMap<K, V>
    where
        K: Clone + Eq + Hash + 'static,
        V: Clone + 'static,
        I: IntoIterator<Item = (K, V)>,
    {
        SnapshotStateMap::with_runtime(pairs, self.runtime_handle())
    }

    pub fn read_composition_local<T: Clone + 'static>(&self, local: &CompositionLocal<T>) -> T {
        self.provided_local::<LocalStateEntry<T>>(&local.key)
            .map_or_else(|| local.default_value(), |entry| entry.value())
    }

    pub fn read_static_composition_local<T: Clone + 'static>(
        &self,
        local: &StaticCompositionLocal<T>,
    ) -> T {
        self.provided_local::<StaticLocalEntry<T>>(&local.key)
            .map_or_else(|| local.default_value(), |entry| entry.value())
    }

    /// The innermost provided entry for `key`, when it is an `E`.
    fn provided_local<E: 'static>(&self, key: &LocalKey) -> Option<Rc<E>> {
        let entry = provided_entry(&self.core.local_stack.borrow(), key)?;
        entry
            .downcast::<E>()
            .inspect_err(|_| log::error!("composition local entry type mismatch for key {key:?}"))
            .ok()
    }

    pub fn current_recompose_scope(&self) -> Option<RecomposeScope> {
        self.core.scope_stack.borrow().last().cloned()
    }

    pub(crate) fn current_state_invalidation_scope(&self) -> Option<RecomposeScope> {
        let stack = self.core.scope_stack.borrow();
        stack
            .iter()
            .rev()
            .find(|scope| scope.has_recompose_callback())
            .cloned()
            .or_else(|| stack.last().cloned())
    }

    pub fn phase(&self) -> crate::Phase {
        self.core.phase.get()
    }

    pub(crate) fn set_phase(&self, phase: crate::Phase) {
        self.core.phase.set(phase);
    }

    pub fn enter_phase(&self, phase: crate::Phase) {
        self.set_phase(phase);
    }

    pub(crate) fn subcompose<R>(
        &self,
        state: &mut SubcomposeState,
        slot_id: SlotId,
        content: impl FnOnce(&Composer) -> R,
    ) -> (R, Vec<NodeId>) {
        match self.phase() {
            crate::Phase::Measure | crate::Phase::Layout => {}
            current => panic!(
                "subcompose() may only be called during measure or layout; current phase: {current:?}"
            ),
        }

        self.subcompose_stack().push(SubcomposeFrame::default());
        let mut guard = SubcomposeStackGuard {
            core: self.clone_core(),
            leaked: false,
        };

        let slot_host = state.get_or_create_slots(slot_id);
        let (result, _) = self.with_slot_override(slot_host, |composer| {
            composer.with_group(slot_id.raw(), |composer| content(composer))
        });

        let frame = {
            let frame = take_subcompose_frame(&guard.core, "subcompose");
            guard.leaked = true;
            frame
        };
        let nodes = frame.nodes;
        let scopes = frame.scopes;
        state.register_active(slot_id, &nodes, &scopes);
        (result, nodes)
    }

    pub fn subcompose_measurement<R>(
        &self,
        state: &mut SubcomposeState,
        slot_id: SlotId,
        content: impl FnOnce(&Composer) -> R,
    ) -> (R, Vec<NodeId>) {
        let (result, nodes) = self.subcompose(state, slot_id, content);
        let roots = nodes
            .into_iter()
            .filter(|&id| self.node_has_no_parent(id))
            .collect();

        (result, roots)
    }

    fn spin_up_subcompose_core(
        &self,
        slots: &Rc<SlotsHost>,
        root: Option<NodeId>,
        runtime_handle: &RuntimeHandle,
        locals: LocalStackSnapshot,
    ) -> Rc<ComposerCore> {
        let phase = self.phase();
        let shared_state = slots
            .runtime_state()
            .unwrap_or_else(|| Rc::clone(&self.core.shared_state));
        let core = Rc::new(ComposerCore::new(
            shared_state,
            Rc::clone(slots),
            Rc::clone(&self.core.applier),
            runtime_handle.clone(),
            root,
            InitialParentFrame::RealParent,
        ));
        core.phase.set(phase);
        *core.local_stack.borrow_mut() = locals;
        core
    }

    fn flush_subcompose_pass(
        &self,
        mut commands: CommandQueue,
        runtime_handle: &RuntimeHandle,
        compact_applier: bool,
        side_effects: Vec<Box<dyn FnOnce()>>,
    ) -> Result<(), NodeError> {
        {
            let mut applier = self.borrow_applier();
            commands.apply(&mut *applier)?;
            for update in runtime_handle.take_updates() {
                update.apply(&mut *applier)?;
            }
        }
        recycle_commands(commands);
        if compact_applier {
            self.core.applier.compact();
            self.core.applier.borrow_dyn().clear_recycled_nodes();
        }
        composer_context::without_composer(|| {
            for effect in side_effects {
                effect();
            }
        });
        Ok(())
    }

    pub fn subcompose_in<R>(
        &self,
        slots: &Rc<SlotsHost>,
        root: Option<NodeId>,
        f: impl FnOnce(&Composer) -> R,
    ) -> Result<R, NodeError> {
        let runtime_handle = self.runtime_handle();
        let locals = self.current_local_stack();
        let core = self.spin_up_subcompose_core(slots, root, &runtime_handle, locals);
        let composer = Composer::from_core(core);
        let (result, commands, side_effects, compact_applier) = composer.install(|composer| {
            let (output, outcome) = composer.try_with_slot_host_pass(
                Rc::clone(slots),
                crate::slot::SlotPassMode::Compose,
                |composer| f(composer),
            )?;
            let commands = composer.take_commands();
            let side_effects = composer.take_side_effects();
            Ok((output, commands, side_effects, outcome.compacted))
        })?;
        self.flush_subcompose_pass(commands, &runtime_handle, compact_applier, side_effects)?;
        Ok(result)
    }

    /// Captures the composition context at the current point so work composed
    /// in another slot host inherits both locals and source ownership.
    ///
    /// A `SubcomposeLayout` captures this while it is being composed and replays
    /// it while subcomposing off the measure pass, so content that is
    /// subcomposed during layout observes the same composition locals as the
    /// `SubcomposeLayout` call site — matching Jetpack Compose, where a
    /// subcomposition inherits the composition locals of the layout that
    /// created it rather than whatever happens to be in scope during measure
    /// (which, after composition unwinds, no longer carries ancestor providers).
    pub fn capture_composition_context(&self) -> CapturedCompositionContext {
        CapturedCompositionContext {
            locals: self.current_local_stack(),
            owner_scope: self
                .current_recompose_scope()
                .map(|scope| scope.downgrade()),
        }
    }

    /// Subcomposes content using an isolated SlotsHost without resetting it.
    /// Unlike `subcompose_in`, this preserves existing slot state across calls,
    /// allowing efficient reuse during measurement passes. This is critical for
    /// lazy lists where items need stable slot positions.
    pub fn subcompose_slot<R>(
        &self,
        slots: &Rc<SlotsHost>,
        root: Option<NodeId>,
        f: impl FnOnce(&Composer) -> R,
    ) -> Result<(R, Vec<RecomposeScope>), NodeError> {
        let context = self.capture_composition_context();
        self.subcompose_slot_with_context(slots, root, &context, f)
    }

    /// Like [`Composer::subcompose_slot`], but uses a context captured at the
    /// source composition site. This is required for measure-time composition,
    /// where the source scope is no longer on the active stack.
    pub fn subcompose_slot_with_context<R>(
        &self,
        slots: &Rc<SlotsHost>,
        root: Option<NodeId>,
        context: &CapturedCompositionContext,
        f: impl FnOnce(&Composer) -> R,
    ) -> Result<(R, Vec<RecomposeScope>), NodeError> {
        let runtime_handle = self.runtime_handle();
        let locals = context.locals.clone();
        let core = self.spin_up_subcompose_core(slots, root, &runtime_handle, locals);
        *core.subcomposition_owner_scope.borrow_mut() = context
            .owner_scope
            .as_ref()
            .and_then(RecomposeScope::upgrade);
        let composer = Composer::from_core(core);
        composer.subcompose_stack().push(SubcomposeFrame::default());
        let mut guard = SubcomposeStackGuard {
            core: composer.clone_core(),
            leaked: false,
        };
        let root_group_key = crate::location_key(file!(), line!(), column!());
        let (result, commands, side_effects, compact_applier) = composer.install(|composer| {
            let (output, outcome) = composer.try_with_slot_host_pass(
                Rc::clone(slots),
                crate::slot::SlotPassMode::Compose,
                |composer| {
                    let output = composer.with_group(root_group_key, |composer| f(composer));
                    if root.is_some() {
                        composer.pop_parent();
                    }
                    output
                },
            )?;
            let commands = composer.take_commands();
            let side_effects = composer.take_side_effects();
            Ok((output, commands, side_effects, outcome.compacted))
        })?;
        let frame = {
            let frame = take_subcompose_frame(&guard.core, "subcompose_slot");
            guard.leaked = true;
            frame
        };

        self.flush_subcompose_pass(commands, &runtime_handle, compact_applier, side_effects)?;
        Ok((result, frame.scopes))
    }

    fn attach_root_nodes(&self, root_nodes: RootNodeIds) {
        for id in root_nodes {
            self.attach_to_parent(id);
        }
    }

    pub fn skip_current_group(&self) {
        #[expect(
            clippy::redundant_closure_for_method_calls,
            reason = "the method path is not general over the session lifetime"
        )]
        self.with_slot_session_mut(|slots| slots.skip_group());
    }

    pub fn runtime_handle(&self) -> RuntimeHandle {
        self.core.runtime.clone()
    }

    pub fn set_recompose_callback<F>(&self, callback: F)
    where
        F: FnMut(&Composer) + 'static,
    {
        let stateless = (std::mem::size_of::<F>() == 0).then(std::any::TypeId::of::<F>);
        if let Some(body) = stateless
            && self.current_scope_reruns(body)
        {
            return;
        }
        self.set_recompose_callback_boxed(Box::new(callback), stateless);
    }

    fn current_scope_reruns(&self, body: std::any::TypeId) -> bool {
        self.core
            .scope_stack
            .borrow()
            .last()
            .is_some_and(|scope| scope.reruns_stateless(body))
    }

    #[inline(never)]
    fn set_recompose_callback_boxed(
        &self,
        callback: Box<dyn FnMut(&Composer)>,
        stateless: Option<std::any::TypeId>,
    ) {
        if let Some(scope) = self.current_recompose_scope() {
            scope.set_boxed_recompose(callback, stateless);
        }
    }

    pub fn set_recompose_fn(&self, callback: fn(&Composer)) {
        if let Some(scope) = self.current_recompose_scope() {
            scope.set_recompose_fn(callback);
        }
    }

    /// Runs `f` with `provided` in scope over the locals around it; of values
    /// for one local, the last wins.
    pub fn with_composition_locals<R>(
        &self,
        provided: impl IntoIterator<Item = ProvidedValue>,
        site: crate::Key,
        f: impl FnOnce(&Composer) -> R,
    ) -> R {
        let provided: SmallVec<[ProvidedValue; 2]> = provided.into_iter().collect();
        if provided.is_empty() {
            return f(self);
        }
        let mut values = SmallVec::<[(LocalKey, Rc<dyn Any>); 2]>::new();
        for value in provided.into_iter().rev() {
            if values.iter().any(|(key, _)| key == value.key()) {
                continue;
            }
            values.push(value.into_entry(self, site));
        }
        let parent = self.current_local_stack();
        *self.local_stack() = Some(Rc::new(LocalFrame {
            values,
            parent: parent.clone(),
        }));
        let result = f(self);
        *self.local_stack() = parent;
        result
    }
}