cranpose_ui/

render_state.rs

#[cfg(test)]
use std::sync::{Mutex, OnceLock};
use std::{
    cell::{Cell, RefCell},
    rc::{Rc, Weak},
    sync::Arc,
};

use cranpose_core::{
    MemoryApplier, NodeId, SnapshotStateObserver, collections::map::HashSet, current_runtime_handle,
};

pub(crate) type ModifierChainTraceCallback =
    dyn Fn(&[crate::modifier::ModifierChainInspectorNode]) + Send + Sync + 'static;

struct RenderState {
    layout_repasses: RefCell<DirtyNodeSet>,
    measure_repasses: RefCell<DirtyNodeSet>,
    draw_repasses: RefCell<DirtyNodeSet>,
    layer_property_repasses: RefCell<DirtyNodeSet>,
    modifier_slice_repasses: RefCell<DirtyNodeSet>,
    geometry_scene_nodes: RefCell<NotedSceneNodes<NodeId>>,
    moved_scene_nodes: RefCell<NotedSceneNodes<MovedSceneNode>>,
    /// Nodes whose z index changed: their parents' layers hold the order.
    z_order_changes: RefCell<DirtyNodeSet>,
    /// Nodes whose redraw flag was set before they had an id, so no draw
    /// repass names them: each surface's frame takes those under its root.
    retained_redraws: RefCell<Vec<NodeId>>,
    render_invalidated: Cell<bool>,
    pointer_invalidated: Cell<bool>,
    focus_invalidated: Cell<bool>,
    layout_invalidated: Cell<bool>,
    density_bits: Cell<u32>,
    font_scale: Cell<crate::font_scale::FontScaleCurve>,
    /// Whether `font_scale` leaves every size as it is, read by every text
    /// measured instead of the curve.
    font_scale_identity: Cell<bool>,
    /// `font_scale`'s fingerprint, computed when the curve is set.
    font_scale_fingerprint: Cell<u32>,
}

#[doc(hidden)]
pub struct AppContext {
    id: AppContextId,
    self_weak: RefCell<Weak<AppContext>>,
    state: RenderState,
    draw_observer: SnapshotStateObserver,
    text: crate::text::measure::TextService,
    layout_frame_arena: RefCell<crate::layout::FrameLayoutArena>,
    /// The host the next layout pass lends its applier to; `None` while a
    /// pass has it.
    layout_host: RefCell<Option<crate::layout::LayoutHost>>,
    layout_cache_epoch: Cell<u64>,
    layout_cache_floor: Cell<u64>,
    last_fling_velocity_bits: Cell<u32>,
    scroll_motion_contexts: crate::scroll::ScrollMotionContextStore,
    lazy_prefetch: crate::lazy_prefetch::LazyPrefetchState,
    layout_node_registry: crate::widgets::nodes::layout_node::LayoutNodeRegistryState,
    pointer_dispatch: crate::pointer_dispatch::PointerDispatchState,
    mouse_input: crate::mouse_input::MouseInputQueue,
    pointer_claim: Cell<Option<cranpose_core::NodeId>>,
    focus_dispatch: crate::focus_dispatch::FocusInvalidationState,
    modal: crate::modal::ModalState,
    modal_nodes: crate::modal_nodes::ModalNodes,
    semantics_layout: crate::semantics_layout_log::SemanticsLayoutLog,
    hosted_popups: crate::widgets::popup::HostedPopupRegistries,
    pub(crate) semantics_dispatch: crate::semantics_dispatch::SemanticsInvalidationState,
    pub(crate) cursor_animation: crate::cursor_animation::CursorAnimationState,
    pub(crate) text_field_focus: crate::text_field_focus::TextFieldFocusState,
    pub(crate) text_input_session: crate::text_input_session::PlatformTextInputState,
    clipboard_session: crate::clipboard_session::ClipboardSessionState,
    pointer_icon: crate::pointer_icon_session::PointerIconState,
    pointer_input_tasks: crate::modifier::pointer_input::PointerInputTaskRegistry,
    modifier_chain_trace: RefCell<Option<Arc<ModifierChainTraceCallback>>>,
    window_roots: crate::modifier::WindowRootRegistry,
    drag_and_drop: crate::modifier::DragAndDropState,
    placement_pass: crate::widgets::nodes::layout_node::PlacementPass,
}

/// Nonzero, so that an absent one takes no more room than one: every
/// layout node keeps the id of the context it registered with.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) struct AppContextId(std::num::NonZeroU64);

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) struct DrawObservationScope {
    node_id: NodeId,
    modifier_index: usize,
    command_index: usize,
    kind: DrawObservationKind,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
enum DrawObservationKind {
    Content,
    LayerProperties,
}

impl DrawObservationScope {
    pub(crate) fn new(node_id: NodeId, modifier_index: usize, command_index: usize) -> Self {
        Self {
            node_id,
            modifier_index,
            command_index,
            kind: DrawObservationKind::Content,
        }
    }

    pub(crate) fn layer_properties(node_id: NodeId, modifier_index: usize) -> Self {
        Self {
            node_id,
            modifier_index,
            command_index: 0,
            kind: DrawObservationKind::LayerProperties,
        }
    }
}

fn new_draw_observer() -> SnapshotStateObserver {
    let observer = SnapshotStateObserver::new(|callback| {
        if let Some(runtime) = current_runtime_handle() {
            runtime.enqueue_ui_task(callback);
        } else {
            callback();
        }
    });
    observer.start();
    observer
}

struct CurrentDrawNodeGuard {
    previous: Option<NodeId>,
}

impl Drop for CurrentDrawNodeGuard {
    fn drop(&mut self) {
        crate::thread_state::cells(|cells| cells.current_draw_node.set(self.previous));
    }
}

pub(crate) fn observe_draw_reads<R>(scope: DrawObservationScope, block: impl FnOnce() -> R) -> R {
    let context = require_current_app_context("draw observer access");
    let context_id = context.id;
    let _guard = CurrentDrawNodeGuard {
        previous: crate::thread_state::cells(|cells| {
            cells.current_draw_node.replace(Some(scope.node_id))
        }),
    };
    context.draw_observer.observe_reads(
        scope,
        move |scope| match scope.kind {
            DrawObservationKind::Content => {
                schedule_draw_repass_for_app_context(context_id, scope.node_id);
            }
            DrawObservationKind::LayerProperties => {
                schedule_layer_property_repass_for_app_context(context_id, scope.node_id);
            }
        },
        block,
    )
}

/// The draw-phase animation contract: a draw closure that advances its own
/// spring or clock (a Cell no observation can see) must schedule the next
/// frame's re-record of ITS OWN node — a bare render invalidation only
/// re-presents the retained scene, which would freeze the animation
/// mid-flight. Callable only from inside a recording draw closure; anywhere
/// else it degrades to a plain frame request.
pub fn request_current_draw_redraw() {
    if let Some(node_id) = crate::thread_state::cells(|cells| cells.current_draw_node.get()) {
        schedule_draw_repass(node_id);
    }
    request_render_invalidation();
}

pub(crate) fn clear_draw_observations_for_node(node_id: NodeId) {
    with_draw_observer(|observer| {
        observer.clear_if(|scope| {
            scope
                .downcast_ref::<DrawObservationScope>()
                .is_some_and(|scope| scope.node_id == node_id)
        });
    });
}

/// Removes draw observations whose owners are absent from the retained scene.
pub fn prune_draw_observations_to_nodes(retained: &HashSet<NodeId>) {
    with_draw_observer(|observer| {
        observer.clear_if(|scope| {
            scope
                .downcast_ref::<DrawObservationScope>()
                .is_some_and(|scope| !retained.contains(&scope.node_id))
        });
    });
}

impl RenderState {
    fn new_with_density(density: f32) -> Self {
        Self {
            layout_repasses: RefCell::new(DirtyNodeSet::new()),
            measure_repasses: RefCell::new(DirtyNodeSet::new()),
            draw_repasses: RefCell::new(DirtyNodeSet::new()),
            layer_property_repasses: RefCell::new(DirtyNodeSet::new()),
            modifier_slice_repasses: RefCell::new(DirtyNodeSet::new()),
            geometry_scene_nodes: RefCell::new(NotedSceneNodes::new()),
            moved_scene_nodes: RefCell::new(NotedSceneNodes::new()),
            z_order_changes: RefCell::new(DirtyNodeSet::new()),
            retained_redraws: RefCell::new(Vec::new()),
            render_invalidated: Cell::new(false),
            pointer_invalidated: Cell::new(false),
            focus_invalidated: Cell::new(false),
            layout_invalidated: Cell::new(false),
            density_bits: Cell::new(normalize_density(density).to_bits()),
            font_scale: Cell::new(crate::font_scale::FontScaleCurve::linear(1.0)),
            font_scale_identity: Cell::new(true),
            font_scale_fingerprint: Cell::new(
                crate::font_scale::FontScaleCurve::linear(1.0).fingerprint(),
            ),
        }
    }
}

fn next_app_context_id() -> AppContextId {
    crate::thread_state::cells(|cells| {
        let next = &cells.next_app_context_id;
        let id = next.get();
        next.set(id.checked_add(1).unwrap_or(std::num::NonZeroU64::MIN));
        AppContextId(id)
    })
}

#[doc(hidden)]
pub struct AppContextScope;

impl Drop for AppContextScope {
    fn drop(&mut self) {
        crate::thread_state::try_with(|state| {
            state.app_context_stack.borrow_mut().pop();
        });
    }
}

impl AppContext {
    pub fn new() -> Rc<Self> {
        Self::new_with_density(1.0)
    }

    pub fn new_with_density(density: f32) -> Rc<Self> {
        let context = Rc::new(Self {
            id: next_app_context_id(),
            self_weak: RefCell::new(Weak::new()),
            state: RenderState::new_with_density(density),
            draw_observer: new_draw_observer(),
            text: crate::text::measure::TextService::new(),
            layout_frame_arena: RefCell::new(crate::layout::FrameLayoutArena::default()),
            layout_host: RefCell::new(None),
            layout_cache_epoch: Cell::new(1),
            layout_cache_floor: Cell::new(0),
            last_fling_velocity_bits: Cell::new(0.0f32.to_bits()),
            scroll_motion_contexts: crate::scroll::ScrollMotionContextStore::new(),
            lazy_prefetch: crate::lazy_prefetch::LazyPrefetchState::new(),
            layout_node_registry: crate::widgets::nodes::layout_node::LayoutNodeRegistryState::new(
            ),
            pointer_dispatch: crate::pointer_dispatch::PointerDispatchState::new(),
            mouse_input: crate::mouse_input::MouseInputQueue::default(),
            pointer_claim: Cell::new(None),
            focus_dispatch: crate::focus_dispatch::FocusInvalidationState::new(),
            modal: crate::modal::ModalState::new(),
            modal_nodes: crate::modal_nodes::ModalNodes::default(),
            semantics_layout: crate::semantics_layout_log::SemanticsLayoutLog::default(),
            hosted_popups: crate::widgets::popup::HostedPopupRegistries::default(),
            semantics_dispatch: crate::semantics_dispatch::SemanticsInvalidationState::new(),
            cursor_animation: crate::cursor_animation::CursorAnimationState::new(),
            text_field_focus: crate::text_field_focus::TextFieldFocusState::new(),
            text_input_session: crate::text_input_session::PlatformTextInputState::new(),
            clipboard_session: crate::clipboard_session::ClipboardSessionState::new(),
            pointer_icon: crate::pointer_icon_session::PointerIconState::new(),
            pointer_input_tasks: crate::modifier::pointer_input::PointerInputTaskRegistry::new(),
            modifier_chain_trace: RefCell::new(None),
            window_roots: crate::modifier::WindowRootRegistry::default(),
            drag_and_drop: crate::modifier::DragAndDropState::default(),
            placement_pass: crate::widgets::nodes::layout_node::PlacementPass::new(),
        });
        *context.self_weak.borrow_mut() = Rc::downgrade(&context);
        crate::thread_state::with(|state| {
            state
                .app_contexts
                .borrow_mut()
                .insert(context.id, Rc::downgrade(&context));
        });
        context
    }

    pub fn enter<R>(self: &Rc<Self>, block: impl FnOnce() -> R) -> R {
        let _scope = self.enter_scope();
        block()
    }

    pub(crate) fn id(&self) -> AppContextId {
        self.id
    }

    pub(crate) fn mouse_input(&self) -> &crate::mouse_input::MouseInputQueue {
        &self.mouse_input
    }

    /// Number of coalesced mouse movements waiting for host dispatch.
    #[doc(hidden)]
    pub fn pending_mouse_moves(&self) -> usize {
        self.mouse_input.len()
    }

    /// Takes the oldest queued mouse movement, retaining the queue's storage.
    #[doc(hidden)]
    pub fn take_mouse_move(&self) -> Option<crate::mouse_input::MouseMoveRequest> {
        self.mouse_input.take()
    }

    /// Asks the shell to give the rest of the held press to `node` alone: the
    /// other targets under the press see it cancelled.
    pub(crate) fn claim_pointer(&self, node: cranpose_core::NodeId) {
        self.pointer_claim.set(Some(node));
    }

    /// Takes the node that claimed the held press since the last call.
    #[doc(hidden)]
    pub fn take_pointer_claim(&self) -> Option<cranpose_core::NodeId> {
        self.pointer_claim.take()
    }

    /// The window roots attached in this context.
    pub fn window_roots(&self) -> &crate::modifier::WindowRootRegistry {
        &self.window_roots
    }

    /// The drag and drop transfer and targets of this context.
    pub fn drag_and_drop(&self) -> &crate::modifier::DragAndDropState {
        &self.drag_and_drop
    }

    #[doc(hidden)]
    pub fn enter_scope(self: &Rc<Self>) -> AppContextScope {
        crate::thread_state::with(|state| {
            state
                .app_context_stack
                .borrow_mut()
                .push(Rc::downgrade(self));
        });
        AppContextScope
    }

    pub fn set_text_measurer<M: crate::text::TextMeasurer>(&self, measurer: M) {
        self.set_text_measurer_rc(Rc::new(measurer));
    }

    pub fn set_text_measurer_rc(&self, measurer: Rc<dyn crate::text::TextMeasurer>) {
        self.text.set_measurer(measurer);
        self.invalidate_layout_caches();
        self.state.layout_invalidated.set(true);
        self.state.render_invalidated.set(true);
    }

    fn invalidate_layout_caches(&self) {
        let floor = self.layout_cache_epoch.get() + 1;
        self.layout_cache_epoch.set(floor);
        self.layout_cache_floor.set(floor);
    }

    #[doc(hidden)]
    pub fn downgrade(&self) -> Weak<Self> {
        self.self_weak.borrow().clone()
    }
}

impl Drop for AppContext {
    fn drop(&mut self) {
        let id = self.id;
        crate::thread_state::try_with(|state| {
            state.app_contexts.borrow_mut().remove(&id);
        });
    }
}

fn app_context_by_id(id: AppContextId) -> Option<Rc<AppContext>> {
    crate::thread_state::try_with(|state| {
        let contexts = &state.app_contexts;
        let context = contexts.borrow().get(&id).cloned()?;
        let Some(context) = context.upgrade() else {
            contexts.borrow_mut().remove(&id);
            return None;
        };
        Some(context)
    })
    .flatten()
}

#[cfg(test)]
fn app_context_registry_entry_count() -> usize {
    crate::thread_state::try_with(|state| state.app_contexts.borrow().len()).unwrap_or_default()
}

pub(crate) fn with_app_context_by_id<R>(
    id: AppContextId,
    f: impl FnOnce(&Rc<AppContext>) -> R,
) -> Option<R> {
    app_context_by_id(id).map(|context| f(&context))
}

pub(crate) fn current_app_context_id() -> AppContextId {
    require_current_app_context("app context identity access").id
}

pub(crate) fn with_layout_node_registry_by_app_context<R>(
    id: AppContextId,
    f: impl FnOnce(&crate::widgets::nodes::layout_node::LayoutNodeRegistryState) -> R,
) -> Option<R> {
    with_app_context_by_id(id, |context| f(&context.layout_node_registry))
}

pub(crate) fn enter_app_context_by_id<R>(id: AppContextId, f: impl FnOnce() -> R) -> Option<R> {
    with_app_context_by_id(id, |context| context.enter(f))
}

pub(crate) fn current_app_context() -> Option<Rc<AppContext>> {
    crate::thread_state::try_with(|state| {
        let mut stack = state.app_context_stack.borrow_mut();
        loop {
            let context = stack.last()?;
            if let Some(context) = context.upgrade() {
                return Some(context);
            }
            stack.pop();
        }
    })
    .flatten()
}

#[doc(hidden)]
pub fn has_current_app_context() -> bool {
    current_app_context().is_some()
}

pub(crate) fn require_current_app_context(operation: &str) -> Rc<AppContext> {
    if let Some(context) = current_app_context() {
        return context;
    }
    require_current_app_context_without_scope(operation)
}

fn require_current_app_context_without_scope(operation: &str) -> Rc<AppContext> {
    panic!("{operation} requires an active AppContext")
}

fn with_render_state<R>(f: impl FnOnce(&RenderState) -> R) -> R {
    let context = require_current_app_context("render state access");
    f(&context.state)
}

fn normalize_density(density: f32) -> f32 {
    if density.is_finite() && density > 0.0 {
        density
    } else {
        1.0
    }
}

fn normalize_font_scale(scale: f32) -> f32 {
    if scale.is_finite() && scale > 0.0 {
        scale.clamp(MIN_FONT_SCALE, MAX_FONT_SCALE)
    } else {
        1.0
    }
}

/// Smallest system font scale honoured; below this, text stops being readable
/// as text.
pub const MIN_FONT_SCALE: f32 = 0.5;
/// Largest system font scale honoured. Android's own accessibility slider tops
/// out at 2.0.
pub const MAX_FONT_SCALE: f32 = 3.0;

pub(crate) fn with_text_measurer<R>(f: impl FnOnce(&dyn crate::text::TextMeasurer) -> R) -> R {
    let context = require_current_app_context("text measurer access");
    context.text.with_measurer(f)
}

/// Tells the current app context's text service, and its measurer, a
/// layout pass starts. Outside an app context there is neither to tell.
#[cfg(test)]
pub(crate) fn begin_text_layout_pass() {
    if let Some(context) = current_app_context() {
        context.begin_text_layout_pass();
    }
}

pub(crate) fn with_text_service<R>(f: impl FnOnce(&crate::text::measure::TextService) -> R) -> R {
    let context = require_current_app_context("text service access");
    f(&context.text)
}

pub(crate) fn set_current_text_measurer(measurer: Rc<dyn crate::text::TextMeasurer>) {
    let Some(context) = current_app_context() else {
        panic!("set_text_measurer requires an active AppContext");
    };
    context.set_text_measurer_rc(measurer);
}

pub(crate) fn set_modifier_chain_trace(callback: Arc<ModifierChainTraceCallback>) -> AppContextId {
    let context = require_current_app_context("modifier chain trace installation");
    *context.modifier_chain_trace.borrow_mut() = Some(callback);
    context.id
}

pub(crate) fn clear_modifier_chain_trace(context_id: AppContextId) {
    let _ = with_app_context_by_id(context_id, |context| {
        *context.modifier_chain_trace.borrow_mut() = None;
    });
}

pub(crate) fn emit_modifier_chain_trace(nodes: &[crate::modifier::ModifierChainInspectorNode]) {
    let Some(context) = current_app_context() else {
        return;
    };
    let callback = context.modifier_chain_trace.borrow().clone();
    if let Some(callback) = callback {
        callback(nodes);
    }
}

/// What a layout pass takes from its app context. A pass looks the context
/// up once and asks it directly: each lookup reads a thread-local, which on
/// ESP-IDF goes through a pthread key.
impl AppContext {
    /// Tells the text service, and its measurer, a layout pass starts.
    pub(crate) fn begin_text_layout_pass(&self) {
        self.text.begin_layout_pass();
    }

    pub(crate) fn take_layout_frame_arena(&self) -> crate::layout::FrameLayoutArena {
        std::mem::take(&mut *self.layout_frame_arena.borrow_mut())
    }

    pub(crate) fn replace_layout_frame_arena(&self, arena: crate::layout::FrameLayoutArena) {
        *self.layout_frame_arena.borrow_mut() = arena;
    }

    /// The host for a layout pass: the one the last pass gave back, or a new
    /// one when a pass is still running or none ran yet.
    pub(crate) fn take_layout_host(&self) -> crate::layout::LayoutHost {
        self.layout_host.borrow_mut().take().unwrap_or_default()
    }

    pub(crate) fn replace_layout_host(&self, host: crate::layout::LayoutHost) {
        *self.layout_host.borrow_mut() = Some(host);
    }

    pub(crate) fn next_layout_cache_epoch(&self) -> u64 {
        let epoch = self.layout_cache_epoch.get();
        self.layout_cache_epoch.set(epoch + 1);
        epoch
    }

    pub(crate) fn layout_cache_floor(&self) -> u64 {
        self.layout_cache_floor.get()
    }

    pub(crate) fn current_layout_cache_epoch(&self) -> u64 {
        self.layout_cache_epoch.get()
    }

    pub(crate) fn take_modifier_slice_repass_nodes(&self) -> Vec<NodeId> {
        self.state
            .modifier_slice_repasses
            .borrow_mut()
            .take_dirty_nodes()
    }

    pub(crate) fn take_measure_repass_nodes(&self) -> Vec<NodeId> {
        self.state.measure_repasses.borrow_mut().take_dirty_nodes()
    }

    pub(crate) fn take_layout_repass_nodes(&self) -> Vec<NodeId> {
        self.state.layout_repasses.borrow_mut().take_dirty_nodes()
    }
}

pub(crate) fn invalidate_layout_cache_epoch() {
    require_current_app_context("layout cache epoch access").invalidate_layout_caches();
}

pub(crate) fn record_last_fling_velocity(velocity: f32) {
    if let Some(context) = current_app_context() {
        context.last_fling_velocity_bits.set(velocity.to_bits());
    }
}

#[doc(hidden)]
pub fn debug_last_fling_velocity() -> f32 {
    let context = require_current_app_context("fling velocity diagnostics access");
    f32::from_bits(context.last_fling_velocity_bits.get())
}

#[doc(hidden)]
pub fn debug_reset_last_fling_velocity() {
    let context = require_current_app_context("fling velocity diagnostics access");
    context.last_fling_velocity_bits.set(0.0f32.to_bits());
}

impl AppContext {
    pub(crate) fn lazy_prefetch(&self) -> &crate::lazy_prefetch::LazyPrefetchState {
        &self.lazy_prefetch
    }

    /// Whether the next frame has work in this context: a render, pointer,
    /// focus or layout invalidation, or a layout, measure or layer-property
    /// repass. Reads the context directly, without looking up the current
    /// one.
    pub fn has_pending_frame_work(&self) -> bool {
        let state = &self.state;
        state.render_invalidated.get()
            || state.pointer_invalidated.get()
            || state.focus_invalidated.get()
            || state.layout_invalidated.get()
            || state.layout_repasses.borrow_mut().has_pending_repass()
            || state.measure_repasses.borrow_mut().has_pending_repass()
            || state
                .layer_property_repasses
                .borrow_mut()
                .has_pending_repass()
    }

    /// [`Self::has_pending_frame_work`], or a pending draw or pointer repass
    /// or focus invalidation.
    pub fn has_stale_work(&self) -> bool {
        self.has_pending_frame_work()
            || self.state.draw_repasses.borrow_mut().has_pending_repass()
            || self.pointer_dispatch.has_pending_repass()
            || self.focus_dispatch.has_pending_invalidation()
    }

    /// Whether a modal node may be live in this context.
    ///
    /// While `count` holds, the context keeps its modal nodes: the first call
    /// reads every node of `applier` once, and later calls read only the nodes
    /// whose semantics changed since. Without `count` nothing is kept and the
    /// answer is always `true`, leaving the caller to walk.
    pub fn modal_node_may_be_live(&self, applier: &mut MemoryApplier, count: bool) -> bool {
        self.modal_nodes.may_be_live(applier, count)
    }

    /// Whether a dismissable popup is open on one of this context's hosts.
    /// Unlike [`crate::dismissable_popup_open`], a composable that asks does
    /// not recompose when popups open or close.
    pub fn dismissable_popup_open(&self) -> bool {
        self.hosted_popups.dismissable_open(false)
    }

    /// Moves the nodes waiting for a draw repass into `output`, as
    /// [`take_draw_repass_nodes_into`] does in the current context.
    pub fn take_draw_repass_nodes_into(&self, output: &mut Vec<NodeId>) {
        self.state
            .draw_repasses
            .borrow_mut()
            .take_dirty_nodes_into(output);
    }

    /// Moves into `output` the nodes whose redraw flag was set before they
    /// had an id, for a surface's frame to take those under its root.
    pub fn take_retained_redraw_nodes_into(&self, output: &mut Vec<NodeId>) {
        output.append(&mut self.state.retained_redraws.borrow_mut());
    }

    /// Gives back a node [`Self::take_retained_redraw_nodes_into`] moved out
    /// that the surface did not take: one under another window root or not
    /// attached yet.
    pub fn keep_retained_redraw_node(&self, node_id: NodeId) {
        self.state.retained_redraws.borrow_mut().push(node_id);
    }

    /// Appends the nodes whose z index changed since the last call to
    /// `output`, as [`append_z_order_changes`] does in the current context.
    pub fn append_z_order_changes(&self, output: &mut Vec<NodeId>) {
        let mut changes = self.state.z_order_changes.borrow_mut();
        if !changes.dirty_nodes.is_empty() {
            output.extend(changes.dirty_nodes.drain());
        }
    }

    /// Moves the nodes waiting for a graphics-layer property update into
    /// `output`, as [`take_layer_property_repass_nodes_into`] does in the
    /// current context.
    pub fn take_layer_property_repass_nodes_into(&self, output: &mut Vec<NodeId>) {
        self.state
            .layer_property_repasses
            .borrow_mut()
            .take_dirty_nodes_into(output);
    }

    /// Whether a layout repass waits, as [`has_pending_layout_repasses`]
    /// says in the current context.
    pub fn has_pending_layout_repasses(&self) -> bool {
        self.state.layout_repasses.borrow_mut().has_pending_repass()
    }

    /// The nodes waiting for a layout repass, which stay waiting.
    pub fn pending_layout_repass_nodes_snapshot(&self) -> Vec<NodeId> {
        self.state
            .layout_repasses
            .borrow_mut()
            .dirty_nodes_snapshot()
    }

    /// Whether a measure repass waits, as [`has_pending_measure_repasses`]
    /// says in the current context.
    pub fn has_pending_measure_repasses(&self) -> bool {
        self.state
            .measure_repasses
            .borrow_mut()
            .has_pending_repass()
    }

    /// The nodes waiting for a measure repass, which stay waiting.
    pub fn pending_measure_repass_nodes_snapshot(&self) -> Vec<NodeId> {
        self.state
            .measure_repasses
            .borrow_mut()
            .dirty_nodes_snapshot()
    }

    /// Moves the nodes whose geometry the last layout pass changed into
    /// `output`, as [`take_geometry_scene_nodes_into`] does in the current
    /// context.
    pub fn take_geometry_scene_nodes_into(&self, output: &mut GeometrySceneNodes) {
        self.state
            .geometry_scene_nodes
            .borrow_mut()
            .take_into(&mut output.reshaped);
        self.state
            .moved_scene_nodes
            .borrow_mut()
            .take_into(&mut output.moved);
    }

    /// Notes that the layout pass changed `node_id`'s geometry. A node
    /// whose layout state is at hand notes it with
    /// [`Self::note_geometry_scene_node`] instead, once a take.
    pub(crate) fn record_geometry_scene_node(&self, node_id: NodeId) {
        self.state.geometry_scene_nodes.borrow_mut().push(node_id);
    }

    /// Notes that the layout pass changed `node_id`'s geometry. `noted_in`
    /// is the node's own record of the take it was last noted in.
    pub(crate) fn note_geometry_scene_node(&self, node_id: NodeId, noted_in: &mut u64) {
        self.state
            .geometry_scene_nodes
            .borrow_mut()
            .note(node_id, noted_in);
    }

    /// Notes that the layout pass moved `node_id`, which `placer` placed, and
    /// changed nothing else of it, so the scene can keep what it drew for the
    /// node. `noted_in` is the node's own record of the take it was last
    /// noted in.
    pub(crate) fn record_moved_scene_node(
        &self,
        node_id: NodeId,
        placer: Option<NodeId>,
        noted_in: &mut u64,
    ) {
        self.state.moved_scene_nodes.borrow_mut().note(
            MovedSceneNode {
                node: node_id,
                placer,
            },
            noted_in,
        );
    }

    /// The placement bookkeeping of this context's running layout pass.
    pub(crate) fn placement_pass(&self) -> &crate::widgets::nodes::layout_node::PlacementPass {
        &self.placement_pass
    }

    /// Takes the pending layout invalidation, as [`take_layout_invalidation`]
    /// does in the current context.
    pub fn take_layout_invalidation(&self) -> bool {
        self.state.layout_invalidated.replace(false)
    }

    /// Takes the pending render invalidation, as [`take_render_invalidation`]
    /// does in the current context.
    pub fn take_render_invalidation(&self) -> bool {
        self.state.render_invalidated.replace(false)
    }

    /// Takes the pending pointer invalidation, as
    /// [`take_pointer_invalidation`] does in the current context.
    pub fn take_pointer_invalidation(&self) -> bool {
        self.state.pointer_invalidated.replace(false)
    }

    /// Takes the pending focus invalidation, as [`take_focus_invalidation`]
    /// does in the current context.
    pub fn take_focus_invalidation(&self) -> bool {
        self.state.focus_invalidated.replace(false)
    }

    /// Ends the frame for the transient scroll motion contexts, as
    /// [`clear_transient_scroll_motion_contexts`] does in the current context.
    pub fn clear_transient_scroll_motion_contexts(&self) {
        self.scroll_motion_contexts.clear_transient_after_frame();
    }

    /// Whether a pointer repass waits, as
    /// [`crate::has_pending_pointer_repasses`] says in the current context.
    pub fn has_pending_pointer_repasses(&self) -> bool {
        self.pointer_dispatch.has_pending_repass()
    }

    /// Whether a focus invalidation waits, as
    /// [`crate::has_pending_focus_invalidations`] says in the current context.
    pub fn has_pending_focus_invalidations(&self) -> bool {
        self.focus_dispatch.has_pending_invalidation()
    }

    /// The node holding focus, as [`crate::active_focus_target`] says in the
    /// current context.
    pub fn active_focus_target(&self) -> Option<NodeId> {
        self.focus_dispatch.active_focus_target()
    }
}

pub(crate) fn with_scroll_motion_context_store<R>(
    f: impl FnOnce(&crate::scroll::ScrollMotionContextStore) -> R,
) -> R {
    let context = require_current_app_context("scroll motion context access");
    f(&context.scroll_motion_contexts)
}

#[doc(hidden)]
pub fn clear_transient_scroll_motion_contexts() {
    if let Some(context) = current_app_context() {
        context.clear_transient_scroll_motion_contexts();
    }
}

#[cfg(test)]
pub(crate) fn layout_frame_arena_placement_scratch_count() -> usize {
    let context = require_current_app_context("layout frame arena access");

    context
        .layout_frame_arena
        .borrow()
        .available_placement_scratch_count()
}

/// Runs `f` on the current app context's layout node registry and returns
/// that context's id.
pub(crate) fn with_current_layout_node_registry(
    f: impl FnOnce(&crate::widgets::nodes::layout_node::LayoutNodeRegistryState),
) -> AppContextId {
    let context = require_current_app_context("layout node registry access");
    f(&context.layout_node_registry);
    context.id
}

pub(crate) fn with_layout_node_registry<R>(
    f: impl FnOnce(&crate::widgets::nodes::layout_node::LayoutNodeRegistryState) -> R,
) -> R {
    let context = require_current_app_context("layout node registry access");
    f(&context.layout_node_registry)
}

pub(crate) fn with_pointer_dispatch<R>(
    f: impl FnOnce(&crate::pointer_dispatch::PointerDispatchState) -> R,
) -> R {
    let context = require_current_app_context("pointer dispatch access");
    f(&context.pointer_dispatch)
}

pub(crate) fn with_focus_dispatch<R>(
    f: impl FnOnce(&crate::focus_dispatch::FocusInvalidationState) -> R,
) -> R {
    let context = require_current_app_context("focus dispatch access");
    f(&context.focus_dispatch)
}

pub(crate) fn with_focus_dispatch_by_app_context<R>(
    id: AppContextId,
    f: impl FnOnce(&crate::focus_dispatch::FocusInvalidationState) -> R,
) -> Option<R> {
    with_app_context_by_id(id, |context| context.enter(|| f(&context.focus_dispatch)))
}

pub(crate) fn with_modal_state<R>(f: impl FnOnce(&crate::modal::ModalState) -> R) -> R {
    let context = require_current_app_context("modal state access");
    f(&context.modal)
}

pub(crate) fn with_current_modal_nodes<R>(
    f: impl FnOnce(&crate::modal_nodes::ModalNodes) -> R,
) -> Option<R> {
    current_app_context().map(|context| f(&context.modal_nodes))
}

pub(crate) fn with_current_semantics_layout_log<R>(
    f: impl FnOnce(&crate::semantics_layout_log::SemanticsLayoutLog) -> R,
) -> Option<R> {
    current_app_context().map(|context| f(&context.semantics_layout))
}

pub(crate) fn with_hosted_popup_registries<R>(
    f: impl FnOnce(&crate::widgets::popup::HostedPopupRegistries) -> R,
) -> R {
    let context = require_current_app_context("hosted popup registries access");
    f(&context.hosted_popups)
}

pub(crate) fn with_semantics_dispatch<R>(
    f: impl FnOnce(&crate::semantics_dispatch::SemanticsInvalidationState) -> R,
) -> R {
    let context = require_current_app_context("semantics dispatch access");
    f(&context.semantics_dispatch)
}

pub(crate) fn with_semantics_dispatch_by_app_context(
    id: AppContextId,
    f: impl FnOnce(&crate::semantics_dispatch::SemanticsInvalidationState),
) {
    with_app_context_by_id(id, |context| f(&context.semantics_dispatch));
}

pub(crate) fn current_app_context_id_opt() -> Option<AppContextId> {
    current_app_context().map(|context| context.id)
}

pub(crate) fn with_cursor_animation<R>(
    f: impl FnOnce(&crate::cursor_animation::CursorAnimationState) -> R,
) -> R {
    let context = require_current_app_context("cursor animation access");
    f(&context.cursor_animation)
}

pub(crate) fn with_text_field_focus<R>(
    f: impl FnOnce(&crate::text_field_focus::TextFieldFocusState) -> R,
) -> R {
    let context = require_current_app_context("text field focus access");
    f(&context.text_field_focus)
}

pub(crate) fn with_text_input_session<R>(
    f: impl FnOnce(&crate::text_input_session::PlatformTextInputState) -> R,
) -> R {
    let context = require_current_app_context("platform text input session access");
    f(&context.text_input_session)
}

pub(crate) fn with_clipboard_session<R>(
    f: impl FnOnce(&crate::clipboard_session::ClipboardSessionState) -> R,
) -> R {
    let context = require_current_app_context("clipboard session access");
    f(&context.clipboard_session)
}

pub(crate) fn with_pointer_icon_session<R>(
    f: impl FnOnce(&crate::pointer_icon_session::PointerIconState) -> R,
) -> R {
    let context = require_current_app_context("pointer icon session access");
    f(&context.pointer_icon)
}

pub(crate) fn register_pointer_input_task(
    task_id: u64,
    task: Rc<crate::modifier::pointer_input::PointerInputTaskInner>,
) -> crate::modifier::pointer_input::PointerInputTaskOwner {
    let context = require_current_app_context("pointer input task registration");
    context.pointer_input_tasks.insert(task_id, task);
    crate::modifier::pointer_input::PointerInputTaskOwner::App(context.id)
}

pub(crate) fn remove_pointer_input_task(
    owner: crate::modifier::pointer_input::PointerInputTaskOwner,
    task_id: u64,
) {
    match owner {
        crate::modifier::pointer_input::PointerInputTaskOwner::App(context_id) => {
            let _ = with_app_context_by_id(context_id, |context| {
                context.pointer_input_tasks.remove(task_id);
            });
        }
    }
}

pub(crate) fn request_pointer_input_task_poll(
    owner: crate::modifier::pointer_input::PointerInputTaskOwner,
    task_id: u64,
) {
    match owner {
        crate::modifier::pointer_input::PointerInputTaskOwner::App(context_id) => {
            let _ = with_app_context_by_id(context_id, |context| {
                context.enter(|| {
                    context.pointer_input_tasks.request_poll(task_id, owner);
                });
            });
        }
    }
}

fn with_draw_observer<R>(f: impl FnOnce(&SnapshotStateObserver) -> R) -> R {
    let context = require_current_app_context("draw observer access");
    f(&context.draw_observer)
}

struct DirtyNodeSet {
    dirty_nodes: HashSet<NodeId>,
}

/// The nodes a layout pass names to the scene, each once a take: a node
/// keeps the take it was last noted in, so a second note in the same take
/// is dropped with one comparison instead of a hash. A node pushed without
/// that record may come twice, which the scene's routing marks absorb.
struct NotedSceneNodes<T> {
    nodes: Vec<T>,
    /// The take the list fills: a number no other list on the thread uses.
    take: u64,
}

impl<T> NotedSceneNodes<T> {
    fn new() -> Self {
        Self {
            nodes: Vec::new(),
            take: next_moved_scene_node_take(),
        }
    }

    fn note(&mut self, node: T, noted_in: &mut u64) {
        if *noted_in != self.take {
            *noted_in = self.take;
            self.nodes.push(node);
        }
    }

    fn push(&mut self, node: T) {
        self.nodes.push(node);
    }

    /// Moves the nodes into `output` and keeps the storage `output` held
    /// for the next take.
    fn take_into(&mut self, output: &mut Vec<T>) {
        output.clear();
        if !self.nodes.is_empty() {
            std::mem::swap(&mut self.nodes, output);
            self.take = next_moved_scene_node_take();
        }
    }
}

fn next_moved_scene_node_take() -> u64 {
    crate::thread_state::cells(|cells| {
        let take = cells.moved_scene_node_takes.get() + 1;
        cells.moved_scene_node_takes.set(take);
        take
    })
}

impl DirtyNodeSet {
    fn new() -> Self {
        Self {
            dirty_nodes: HashSet::default(),
        }
    }

    fn schedule_repass(&mut self, node_id: NodeId) {
        self.dirty_nodes.insert(node_id);
    }

    fn has_pending_repass(&self) -> bool {
        !self.dirty_nodes.is_empty()
    }

    // A drain clears every control byte of the table when it ends, even of
    // an empty one: most frames take sets that are empty.
    fn take_dirty_nodes(&mut self) -> Vec<NodeId> {
        if self.dirty_nodes.is_empty() {
            return Vec::new();
        }
        self.dirty_nodes.drain().collect()
    }

    fn take_dirty_nodes_into(&mut self, output: &mut Vec<NodeId>) {
        output.clear();
        if self.dirty_nodes.is_empty() {
            return;
        }
        output.extend(self.dirty_nodes.drain());
    }

    fn dirty_nodes_snapshot(&self) -> Vec<NodeId> {
        let mut nodes = self.dirty_nodes.iter().copied().collect::<Vec<_>>();
        nodes.sort_unstable();
        nodes
    }
}

/// Schedules a layout repass for a specific node.
///
/// **This is the preferred way to invalidate layout for local changes** (e.g., scroll, single-node mutations).
///
/// The app shell will call `take_layout_repass_nodes()` and bubble dirty flags up the tree
/// via `bubble_layout_dirty`. This gives you **O(subtree) performance** - only the affected
/// subtree is remeasured, and layout caches for other parts of the app remain valid.
///
/// A scoped repass never invalidates the whole tree, and it never cancels a global
/// invalidation requested for the same frame.
///
/// # For Global Invalidation
///
/// For rare global events (window resize, global scale changes), use `request_layout_invalidation()` instead.
#[track_caller]
pub fn schedule_layout_repass(node_id: NodeId) {
    if layout_repass_schedule_diagnostics_enabled_for(node_id) {
        let caller = std::panic::Location::caller();
        log::warn!(
            "[layout-repass-schedule] node={} caller={}:{}:{}",
            node_id,
            caller.file(),
            caller.line(),
            caller.column()
        );
    }
    with_render_state(|state| {
        state.layout_repasses.borrow_mut().schedule_repass(node_id);
    });
    request_render_invalidation();
}

#[derive(Clone, Copy)]
enum LayoutRepassScheduleDiag {
    Disabled,
    All,
    Node(NodeId),
}

fn layout_repass_schedule_diagnostics_enabled_for(node_id: NodeId) -> bool {
    static MODE: std::sync::OnceLock<LayoutRepassScheduleDiag> = std::sync::OnceLock::new();
    match *MODE.get_or_init(|| {
        let Some(value) = std::env::var_os("CRANPOSE_LAYOUT_REPASS_SCHEDULE_DIAG") else {
            return LayoutRepassScheduleDiag::Disabled;
        };
        if value == "all" {
            return LayoutRepassScheduleDiag::All;
        }
        value.to_string_lossy().parse::<NodeId>().map_or(
            LayoutRepassScheduleDiag::Disabled,
            LayoutRepassScheduleDiag::Node,
        )
    }) {
        LayoutRepassScheduleDiag::Disabled => false,
        LayoutRepassScheduleDiag::All => true,
        LayoutRepassScheduleDiag::Node(target) => target == node_id,
    }
}

pub(crate) fn schedule_modifier_slices_repass(node_id: NodeId) {
    with_render_state(|state| {
        state
            .modifier_slice_repasses
            .borrow_mut()
            .schedule_repass(node_id);
    });
    schedule_draw_repass(node_id);
}

/// Schedules a draw-only repass for a specific node.
///
/// This ensures draw/pointer data stays in sync when modifier updates do not
/// require a layout pass (e.g., draw-only modifier changes).
pub fn schedule_draw_repass(node_id: NodeId) {
    let context = require_current_app_context("render state access");
    schedule_draw_repass_in_context(&context, node_id);
}

fn schedule_draw_repass_for_app_context(context_id: AppContextId, node_id: NodeId) {
    let _ = with_app_context_by_id(context_id, |context| {
        schedule_draw_repass_in_context(context, node_id);
    });
}

fn schedule_draw_repass_in_context(context: &AppContext, node_id: NodeId) {
    context
        .state
        .draw_repasses
        .borrow_mut()
        .schedule_repass(node_id);
    context.state.render_invalidated.set(true);
}

fn schedule_layer_property_repass_for_app_context(context_id: AppContextId, node_id: NodeId) {
    let _ = with_app_context_by_id(context_id, |context| {
        schedule_layer_property_repass_in_context(context, node_id);
    });
}

fn schedule_layer_property_repass_in_context(context: &AppContext, node_id: NodeId) {
    context
        .state
        .layer_property_repasses
        .borrow_mut()
        .schedule_repass(node_id);
    context.state.render_invalidated.set(true);
}

/// Notes `node_id`, whose redraw flag was set before it had an id, in the
/// current context: no draw repass names it, so a surface's frame takes it.
pub(crate) fn note_retained_redraw(node_id: NodeId) {
    if let Some(context) = current_app_context() {
        context.keep_retained_redraw_node(node_id);
    }
}

/// Returns true if any draw repasses are pending.
pub fn has_pending_draw_repasses() -> bool {
    with_render_state(|state| state.draw_repasses.borrow_mut().has_pending_repass())
}

/// Takes all pending draw repass node IDs.
pub fn take_draw_repass_nodes() -> Vec<NodeId> {
    with_render_state(|state| state.draw_repasses.borrow_mut().take_dirty_nodes())
}

/// Takes pending draw repasses into reusable caller-owned storage.
///
/// ```
/// let context = cranpose_ui::AppContext::new();
/// context.enter(|| {
///     let mut nodes = Vec::new();
///     cranpose_ui::take_draw_repass_nodes_into(&mut nodes);
///     assert!(nodes.is_empty());
/// });
/// ```
pub fn take_draw_repass_nodes_into(output: &mut Vec<NodeId>) {
    require_current_app_context("render state access").take_draw_repass_nodes_into(output);
}

/// Records that `node_id`'s z index changed. The frame rebuilds the layer of
/// its parent, which holds the order the parent's children draw and take
/// taps in.
pub fn schedule_z_order_change(node_id: NodeId) {
    with_render_state(|state| {
        state.z_order_changes.borrow_mut().schedule_repass(node_id);
        state.render_invalidated.set(true);
    });
}

/// Appends the nodes whose z index changed since the last call to `output`,
/// after what it already holds.
pub fn append_z_order_changes(output: &mut Vec<NodeId>) {
    require_current_app_context("render state access").append_z_order_changes(output);
}

/// Returns true if graphics-layer property updates are pending.
#[doc(hidden)]
pub fn has_pending_layer_property_repasses() -> bool {
    with_render_state(|state| {
        state
            .layer_property_repasses
            .borrow_mut()
            .has_pending_repass()
    })
}

/// Takes pending graphics-layer property updates into reusable storage.
#[doc(hidden)]
pub fn take_layer_property_repass_nodes_into(output: &mut Vec<NodeId>) {
    require_current_app_context("render state access")
        .take_layer_property_repass_nodes_into(output);
}

/// Returns true if any layout repasses are pending.
pub fn has_pending_layout_repasses() -> bool {
    require_current_app_context("render state access").has_pending_layout_repasses()
}

/// Returns a stable snapshot of pending layout repass node IDs without consuming them.
pub fn pending_layout_repass_nodes_snapshot() -> Vec<NodeId> {
    require_current_app_context("render state access").pending_layout_repass_nodes_snapshot()
}

/// Takes all pending layout repass node IDs.
///
/// The caller should iterate over these and call `bubble_layout_dirty` for each.
pub fn take_layout_repass_nodes() -> Vec<NodeId> {
    require_current_app_context("render state access").take_layout_repass_nodes()
}

/// Schedules a scoped re-*measure* of `node_id` on the next frame.
///
/// Like [`schedule_layout_repass`], but processing bubbles *measure* dirtiness
/// (not just layout/placement) up the tree, so the node and its ancestors are
/// re-measured. Use this when a node's own measured size changes off a frame
/// callback (e.g. a row collapsing after a swipe dismiss): a plain layout
/// repass would leave the node's `needs_measure` flag unset, and an enclosing
/// `LazyColumn` would reuse its cached, full-height item slot.
pub fn schedule_measure_repass(node_id: NodeId) {
    with_render_state(|state| {
        state.measure_repasses.borrow_mut().schedule_repass(node_id);
    });
    request_render_invalidation();
}

/// Returns true if any measure repasses are pending.
pub fn has_pending_measure_repasses() -> bool {
    require_current_app_context("render state access").has_pending_measure_repasses()
}

/// Returns a stable snapshot of pending measure repass node IDs without
/// consuming them.
///
/// The layout pass takes these ids to bubble measure dirtiness; the scene phase
/// needs the same ids *before* that happens, to scope its graph update to the
/// subtree that moved. Without the snapshot a measure repass reaches the scene
/// phase as "something changed, but nothing says where", which is
/// indistinguishable from a full invalidation.
pub fn pending_measure_repass_nodes_snapshot() -> Vec<NodeId> {
    require_current_app_context("render state access").pending_measure_repass_nodes_snapshot()
}

/// Takes all pending measure repass node IDs.
///
/// The caller should iterate over these and call `bubble_measure_dirty` for each.
pub fn take_measure_repass_nodes() -> Vec<NodeId> {
    require_current_app_context("render state access").take_measure_repass_nodes()
}

#[cfg(any(test, feature = "test-helpers"))]
pub(crate) fn take_modifier_slice_repass_nodes() -> Vec<NodeId> {
    require_current_app_context("render state access").take_modifier_slice_repass_nodes()
}

pub(crate) fn record_geometry_scene_node(node_id: NodeId) {
    require_current_app_context("render state access").record_geometry_scene_node(node_id);
}

/// The nodes whose geometry a layout pass changed, by what the scene redoes
/// for them.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct GeometrySceneNodes {
    /// Nodes that changed size or were placed anew: the scene draws them
    /// again.
    pub reshaped: Vec<NodeId>,
    /// Nodes that moved in their parent: the scene moves what it drew for
    /// them, unless they are also reshaped or drawn again.
    pub moved: Vec<MovedSceneNode>,
}

/// A node a layout pass moved, with the node whose placement put it there:
/// its nearest ancestor that is not virtual, the parent of its layer.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct MovedSceneNode {
    /// The node that moved.
    pub node: NodeId,
    /// The node that placed it; `None` for a root.
    pub placer: Option<NodeId>,
}

impl GeometrySceneNodes {
    /// Whether the pass changed no node's geometry.
    pub fn is_empty(&self) -> bool {
        self.reshaped.is_empty() && self.moved.is_empty()
    }
}

/// Takes the nodes whose geometry the last layout pass actually changed.
///
/// The scene phase merges these into its scoped update scope. Consuming them
/// is mandatory whenever layout ran: geometry recorded by one pass is
/// meaningless to the next.
pub fn take_geometry_scene_nodes() -> GeometrySceneNodes {
    let mut nodes = GeometrySceneNodes::default();
    take_geometry_scene_nodes_into(&mut nodes);
    nodes
}

/// Takes changed geometry nodes into reusable caller-owned storage.
///
/// ```
/// let context = cranpose_ui::AppContext::new();
/// context.enter(|| {
///     let mut nodes = cranpose_ui::GeometrySceneNodes::default();
///     cranpose_ui::take_geometry_scene_nodes_into(&mut nodes);
///     assert!(nodes.is_empty());
/// });
/// ```
pub fn take_geometry_scene_nodes_into(output: &mut GeometrySceneNodes) {
    require_current_app_context("render state access").take_geometry_scene_nodes_into(output);
}

/// Returns the current density scale factor (logical px per dp).
pub fn current_density() -> f32 {
    with_render_state(|state| f32::from_bits(state.density_bits.get()))
}

/// Updates the current density scale factor.
///
/// This triggers a global layout invalidation when the value changes because
/// density impacts layout, text measurement, and input thresholds.
pub fn set_density(density: f32) {
    let normalized = normalize_density(density);
    let new_bits = normalized.to_bits();
    with_render_state(|state| {
        let old_bits = state.density_bits.replace(new_bits);
        if old_bits != new_bits {
            state.layout_invalidated.set(true);
        }
    });
}

/// Returns the system font scale — the multiplier the user chose in the
/// platform's font-size setting, `1.0` when they left it alone.
///
/// This is the setting `Sp` is defined against, so text follows it while
/// everything measured in `Dp` does not. A platform that does not report one
/// leaves it at `1.0`.
///
/// It is the number to *report*, not the number to multiply by: what a size in
/// `Sp` comes to is [`scale_sp`], and on Android 14 and up the two are not the
/// same arithmetic. See [`crate::font_scale`].
pub fn current_font_scale() -> f32 {
    current_font_scale_curve().scale()
}

/// Returns the conversion the platform performs for a size in `Sp`.
///
/// The setting is not a multiplier on every platform — see
/// [`crate::font_scale`] — so this, and not [`current_font_scale`], is what a
/// size in `Sp` is resolved through. The scalar remains the thing to *report*.
pub fn current_font_scale_curve() -> crate::font_scale::FontScaleCurve {
    with_render_state(|state| state.font_scale.get())
}

/// The current app context's density and font scale curve, read through one
/// lookup of the context, or `None` outside a context.
pub(crate) fn current_host_density() -> Option<(f32, crate::font_scale::FontScaleCurve)> {
    current_app_context().map(|context| {
        (
            f32::from_bits(context.state.density_bits.get()),
            context.state.font_scale.get(),
        )
    })
}

/// The running app's font scale curve, or `None` when it leaves every size as
/// it is, which the caller then need not read.
pub(crate) fn current_scaling_font_scale_curve() -> Option<crate::font_scale::FontScaleCurve> {
    with_render_state(|state| (!state.font_scale_identity.get()).then(|| state.font_scale.get()))
}

/// What a prepared text layout is valid for: the text service's generation
/// and the font scale curve's fingerprint, read in one app context access.
pub(crate) fn text_layout_stamp() -> (u64, u32) {
    let context = require_current_app_context("text layout stamp access");
    (
        context.text.generation(),
        context.state.font_scale_fingerprint.get(),
    )
}

/// A size in scale-independent pixels, in dp, through the running app's curve.
pub fn scale_sp(sp: f32) -> f32 {
    current_font_scale_curve().sp_to_dp(sp)
}

/// Updates the system font scale, taking it as a plain multiplier.
///
/// Hosts call this when the platform reports the setting, and again whenever it
/// changes while the app is running — on Android that is a configuration
/// change, which arrives without the process restarting. Like density it
/// invalidates layout, because every `Sp` size on screen has just changed.
///
/// A host whose platform converts `Sp` through a table of its own calls
/// [`set_font_scale_curve`] instead.
pub fn set_font_scale(scale: f32) {
    set_font_scale_curve(crate::font_scale::FontScaleCurve::linear(scale));
}

/// Updates the system font scale and the conversion behind it.
///
/// Hosts that can read the platform's real `Sp` conversion call this instead of
/// [`set_font_scale`], which is the same thing with no table behind it. A curve
/// whose scale is not a value a platform could report is refused the same way a
/// bare scalar is, and refusing it drops the table with it: knots sampled at a
/// scale that was rejected describe a conversion the app is not going to use.
pub fn set_font_scale_curve(curve: crate::font_scale::FontScaleCurve) {
    let normalized = normalize_font_scale(curve.scale());
    let curve = if (normalized - curve.scale()).abs() <= f32::EPSILON {
        curve
    } else {
        crate::font_scale::FontScaleCurve::linear(normalized)
    };
    with_render_state(|state| {
        if state.font_scale.get() != curve {
            state.font_scale.set(curve);
            state.font_scale_identity.set(curve.is_identity());
            state.font_scale_fingerprint.set(curve.fingerprint());
            state.layout_invalidated.set(true);
        }
    });
}

/// Requests that the renderer rebuild the current scene.
pub fn request_render_invalidation() {
    with_render_state(|state| state.render_invalidated.set(true));
}

/// Returns true if a render invalidation was pending and clears the flag.
pub fn take_render_invalidation() -> bool {
    require_current_app_context("render state access").take_render_invalidation()
}

/// Returns true if a render invalidation is pending without clearing it.
pub fn peek_render_invalidation() -> bool {
    with_render_state(|state| state.render_invalidated.get())
}

/// Requests a new pointer-input pass without touching layout or draw dirties.
pub fn request_pointer_invalidation() {
    with_render_state(|state| state.pointer_invalidated.set(true));
}

/// Returns true if a pointer invalidation was pending and clears the flag.
pub fn take_pointer_invalidation() -> bool {
    require_current_app_context("render state access").take_pointer_invalidation()
}

/// Returns true if a pointer invalidation is pending without clearing it.
pub fn peek_pointer_invalidation() -> bool {
    with_render_state(|state| state.pointer_invalidated.get())
}

/// Requests a focus recomposition without affecting layout/draw dirties.
pub fn request_focus_invalidation() {
    with_render_state(|state| state.focus_invalidated.set(true));
}

/// Returns true if a focus invalidation was pending and clears the flag.
pub fn take_focus_invalidation() -> bool {
    require_current_app_context("render state access").take_focus_invalidation()
}

/// Returns true if a focus invalidation is pending without clearing it.
pub fn peek_focus_invalidation() -> bool {
    with_render_state(|state| state.focus_invalidated.get())
}

/// Requests a **global** layout re-run.
///
/// # ⚠️ WARNING: Extremely Expensive - O(entire app size)
///
/// This triggers internal cache invalidation that forces **every node** in the app
/// to re-measure, even if nothing changed. This is a performance footgun!
///
/// ## Valid Use Cases (rare!)
///
/// Only use this for **true global changes** that affect layout computation everywhere:
/// - Window/viewport resize
/// - Global font scale or density changes
/// - System-wide theme changes that affect layout
/// - Debug toggles that change layout behavior globally
///
/// ## For Local Changes - DO NOT USE THIS
///
/// **If you're invalidating layout for scroll, a single widget update, or any local change,
/// you MUST use the scoped repass mechanism instead:**
///
/// ```text
/// cranpose_ui::schedule_layout_repass(node_id);
/// ```
///
/// Scoped repasses give you O(subtree) performance instead of O(app), and they don't
/// invalidate caches across the entire app.
pub fn request_layout_invalidation() {
    with_render_state(|state| state.layout_invalidated.set(true));
}

/// Returns true if a layout invalidation was pending and clears the flag.
pub fn take_layout_invalidation() -> bool {
    require_current_app_context("render state access").take_layout_invalidation()
}

/// Returns true if a layout invalidation is pending without clearing it.
pub fn peek_layout_invalidation() -> bool {
    with_render_state(|state| state.layout_invalidated.get())
}

#[cfg(any(test, feature = "test-helpers"))]
#[doc(hidden)]
pub fn reset_render_state_for_tests() {
    let _ = take_draw_repass_nodes();
    let mut layer_nodes = Vec::new();
    take_layer_property_repass_nodes_into(&mut layer_nodes);
    let _ = take_layout_repass_nodes();
    let _ = take_modifier_slice_repass_nodes();
    append_z_order_changes(&mut layer_nodes);
    let _ = take_render_invalidation();
    let _ = take_pointer_invalidation();
    let _ = take_focus_invalidation();
    let _ = take_layout_invalidation();
    debug_reset_last_fling_velocity();
    set_density(1.0);
    set_font_scale(1.0);
    let _ = take_layout_invalidation();
}

#[cfg(test)]
pub(crate) struct TestAppContextScope {
    _scope: AppContextScope,
    _context: Rc<AppContext>,
}

#[cfg(test)]
pub(crate) fn app_context_test_scope() -> TestAppContextScope {
    let context = AppContext::new();
    let scope = context.enter_scope();
    context.enter(reset_render_state_for_tests);
    TestAppContextScope {
        _scope: scope,
        _context: context,
    }
}

#[cfg(test)]
pub(crate) struct RenderStateTestGuard {
    _app_scope: TestAppContextScope,
    _lock: std::sync::MutexGuard<'static, ()>,
}

#[cfg(test)]
pub(crate) fn render_state_test_guard() -> RenderStateTestGuard {
    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
    let lock = match TEST_LOCK.get_or_init(|| Mutex::new(())).lock() {
        Ok(guard) => guard,
        Err(poisoned) => poisoned.into_inner(),
    };
    RenderStateTestGuard {
        _app_scope: app_context_test_scope(),
        _lock: lock,
    }
}

#[cfg(test)]
#[path = "tests/render_state_tests.rs"]
mod tests;