cranpose_foundation/lazy/

lazy_list_state.rs

//! Lazy list state management.
//!
//! Provides [`LazyListState`] for controlling and observing lazy list scroll position.
//!
//! Design follows Jetpack Compose's LazyListState/LazyListScrollPosition pattern:
//! - Reactive properties are backed by `MutableState<T>`:
//!   - `first_visible_item_index`, `first_visible_item_scroll_offset`
//!   - `can_scroll_forward`, `can_scroll_backward`
//!   - `stats` (items_in_use, items_in_pool)
//! - Non-reactive internals (caches, callbacks, scroll window, diagnostic counters) are in inner state

use std::{cell::RefCell, rc::Rc};

use cranpose_core::{MutableState, NodeId, RuntimeCell, StateId, collections::map::HashMap};
use cranpose_macros::composable;

use super::{diagnostics, nearest_range::NearestRangeState};

const MAX_PENDING_SCROLL_DELTA: f32 = 2000.0;
const ITEM_SIZE_CACHE_CAPACITY: usize = 8192;

#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct LazyListMeasureStateSnapshot {
    pub(crate) first_visible_item_index: usize,
    pub(crate) first_visible_item_scroll_offset: f32,
    pub(crate) pending_scroll_delta: f32,
    pub(crate) window_scroll_delta: f32,
    pub(crate) pending_scroll_to: Option<(usize, f32)>,
    pub(crate) average_item_size: f32,
}

/// Statistics about lazy layout item lifecycle.
///
/// Used for testing and debugging virtualization behavior.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct LazyLayoutStats {
    /// Number of items currently composed and visible.
    pub items_in_use: usize,

    /// Number of items in the recycle pool (available for reuse).
    pub items_in_pool: usize,

    /// Total number of items that have been composed.
    pub total_composed: usize,

    /// Number of items that were reused instead of newly composed.
    pub reuse_count: usize,
}

/// Contains the current scroll position represented by the first visible item
/// index and the first visible item scroll offset.
///
/// This is a `Copy` type that holds reactive state. Reading `index` or `scroll_offset`
/// during composition creates a snapshot dependency for automatic recomposition.
///
/// Matches Jetpack Compose's `LazyListScrollPosition` design.
#[derive(Clone, Copy)]
pub struct LazyListScrollPosition {
    index: MutableState<usize>,
    scroll_offset: MutableState<f32>,
    inner: RuntimeCell<RefCell<ScrollPositionInner>>,
}

/// Non-reactive internal state for scroll position.
struct ScrollPositionInner {
    current_index: usize,
    current_scroll_offset: f32,
    last_known_first_item_key: Option<u64>,
    nearest_range_state: NearestRangeState,
}

impl LazyListScrollPosition {
    fn current_index(&self) -> usize {
        self.inner
            .try_with(|cell| cell.borrow().current_index)
            .unwrap_or(0)
    }

    fn current_scroll_offset(&self) -> f32 {
        self.inner
            .try_with(|cell| cell.borrow().current_scroll_offset)
            .unwrap_or(0.0)
    }

    /// Returns the index of the first visible item (reactive read).
    pub fn index(&self) -> usize {
        if !self.index.is_alive() {
            return 0;
        }
        let Some(index) = self.inner.try_with(|cell| cell.borrow().current_index) else {
            return 0;
        };
        self.index.subscribe_current_scope_only();
        index
    }

    /// Returns the scroll offset of the first visible item (reactive read).
    pub fn scroll_offset(&self) -> f32 {
        if !self.scroll_offset.is_alive() {
            return 0.0;
        }
        let Some(offset) = self
            .inner
            .try_with(|cell| cell.borrow().current_scroll_offset)
        else {
            return 0.0;
        };
        self.scroll_offset.subscribe_current_scope_only();
        offset
    }

    pub(crate) fn update_from_measure_result(
        &self,
        first_visible_index: usize,
        first_visible_scroll_offset: f32,
        first_visible_item_key: Option<u64>,
    ) {
        if !self.index.is_alive() || !self.scroll_offset.is_alive() {
            return;
        }
        let updated = self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            inner.current_index = first_visible_index;
            inner.current_scroll_offset = first_visible_scroll_offset;
            inner.last_known_first_item_key = first_visible_item_key;
            inner.nearest_range_state.update(first_visible_index);
        });
        if updated.is_none() {
            return;
        }

        if self.index.get_non_reactive() != first_visible_index {
            self.index.set(first_visible_index);
        }
        if (self.scroll_offset.get_non_reactive() - first_visible_scroll_offset).abs() > 0.001 {
            self.scroll_offset.set(first_visible_scroll_offset);
        }
    }

    pub(crate) fn request_position_and_forget_last_known_key(
        &self,
        index: usize,
        scroll_offset: f32,
    ) {
        if !self.index.is_alive() || !self.scroll_offset.is_alive() {
            return;
        }
        let updated = self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            inner.current_index = index;
            inner.current_scroll_offset = scroll_offset;
            inner.last_known_first_item_key = None;
            inner.nearest_range_state.update(index);
        });
        if updated.is_none() {
            return;
        }

        if self.index.get_non_reactive() != index {
            self.index.set(index);
        }
        if (self.scroll_offset.get_non_reactive() - scroll_offset).abs() > 0.001 {
            self.scroll_offset.set(scroll_offset);
        }
    }

    pub(crate) fn update_if_first_item_moved<F>(
        &self,
        new_item_count: usize,
        find_by_key: F,
    ) -> usize
    where
        F: Fn(u64) -> Option<usize>,
    {
        if !self.index.is_alive() {
            return 0;
        }
        let Some(cell) = self.inner.try_get() else {
            return 0;
        };
        let (current_index, last_key) = {
            let inner = cell.borrow();
            (inner.current_index, inner.last_known_first_item_key)
        };

        let new_index = match last_key {
            None => current_index.min(new_item_count.saturating_sub(1)),
            Some(key) => find_by_key(key)
                .unwrap_or_else(|| current_index.min(new_item_count.saturating_sub(1))),
        };

        if current_index != new_index {
            {
                let mut inner = cell.borrow_mut();
                inner.current_index = new_index;
                inner.nearest_range_state.update(new_index);
            }
            self.index.set(new_index);
        }
        new_index
    }

    /// Returns the nearest range for optimized key lookups.
    pub fn nearest_range(&self) -> std::ops::Range<usize> {
        self.inner
            .try_with(|cell| cell.borrow().nearest_range_state.range())
            .unwrap_or(0..0)
    }
}

/// State object for lazy list scroll position tracking.
///
/// Holds the current scroll position and provides methods to programmatically
/// control scrolling. Create with [`rememberLazyListState()`] in composition.
///
/// This type is `Copy`, so it can be passed to multiple closures without explicit `.clone()` calls.
///
/// # Reactive Properties (read during composition triggers recomposition)
/// - `first_visible_item_index()` - index of first visible item
/// - `first_visible_item_scroll_offset()` - scroll offset within first item
/// - `can_scroll_forward()` - whether more items exist below/right
/// - `can_scroll_backward()` - whether more items exist above/left
/// - `stats()` - lifecycle statistics (`items_in_use`, `items_in_pool`)
///
/// # Non-Reactive Properties
/// - `stats().total_composed` - total items composed (diagnostic)
/// - `stats().reuse_count` - items reused from pool (diagnostic)
/// - `layout_info()` - detailed layout information
///
/// # Example
///
/// ```rust,ignore
/// let state = rememberLazyListState();
///
/// // Scroll to item 50
/// state.scroll_to_item(50, 0.0);
///
/// // Get current visible item (reactive read)
/// println!("First visible: {}", state.first_visible_item_index());
/// ```
#[derive(Clone, Copy)]
pub struct LazyListState {
    scroll_position: LazyListScrollPosition,
    can_scroll_forward_state: MutableState<bool>,
    can_scroll_backward_state: MutableState<bool>,
    stats_state: MutableState<LazyLayoutStats>,
    scroll_in_progress_state: MutableState<bool>,
    dragged_state: MutableState<bool>,
    inner: RuntimeCell<RefCell<LazyListStateInner>>,
}

impl PartialEq for LazyListState {
    fn eq(&self, other: &Self) -> bool {
        self.inner == other.inner
    }
}

#[derive(Clone, Copy)]
struct CachedItemSize {
    size: f32,
    last_used: u64,
}

/// Non-reactive internal state for LazyListState.
/// Where a scroll that the user let go of comes to rest: given the rest
/// offset the release would reach, within the first visible item, and the
/// release velocity, the offset to settle at instead.
pub type LazySettlePolicy = Rc<dyn Fn(f32, f32) -> f32>;

struct LazyListStateInner {
    scroll_to_be_consumed: f32,
    settle_policy: Option<LazySettlePolicy>,
    /// The id of the running scroll animation and how to stop it.
    scroll_animation: Option<(u64, Rc<dyn Fn()>)>,
    next_scroll_animation: u64,
    /// Whether the scroll modifier's drag, fling or settle moves the list.
    gesture_scrolling: bool,
    /// The first visible item and its offset where the scroll in progress
    /// began.
    scroll_start: Option<(usize, f32)>,

    pending_scroll_to_index: Option<(usize, f32)>,

    layout_info: LazyListLayoutInfo,
    /// The visible items of the layout info before the last, cleared, which
    /// the next measure pass fills.
    spare_items_info: Vec<LazyListItemInfo>,
    current_can_scroll_forward: bool,
    current_can_scroll_backward: bool,

    invalidate_callbacks: Vec<(u64, Rc<dyn Fn()>)>,
    next_callback_id: u64,

    layout_invalidation_callback_id: Option<u64>,
    layout_invalidation_node_id: Option<NodeId>,

    total_composed: usize,
    reuse_count: usize,

    item_size_cache: HashMap<usize, CachedItemSize>,
    item_size_clock: u64,

    average_item_size: f32,
    total_measured_items: usize,
    next_measure_cycle_id: u64,
    next_item_measure_pass_id: u64,

    last_scroll_delta: f32,

    hold_scroll_window: bool,
}

/// Creates a remembered [`LazyListState`] with default initial position.
///
/// This is the recommended way to create a `LazyListState` in composition.
/// The returned state is `Copy` and can be passed to multiple closures without `.clone()`.
///
/// # Example
///
/// ```rust,ignore
/// let list_state = rememberLazyListState();
///
/// // Pass to multiple closures - no .clone() needed!
/// LazyColumn(modifier, list_state, spec, content);
/// Button(move || list_state.scroll_to_item(0, 0.0));
/// ```
#[composable]
#[track_caller]
pub fn rememberLazyListState() -> LazyListState {
    rememberLazyListStateWithPosition(0, 0.0)
}

/// Creates a remembered [`LazyListState`] with the specified initial position.
///
/// The returned state is `Copy` and can be passed to multiple closures without `.clone()`.
#[composable]
pub fn rememberLazyListStateWithPosition(
    initial_first_visible_item_index: usize,
    initial_first_visible_item_scroll_offset: f32,
) -> LazyListState {
    cranpose_core::remember(move || {
        LazyListState::new(
            initial_first_visible_item_index,
            initial_first_visible_item_scroll_offset,
        )
    })
    .with(|state| *state)
}

impl LazyListState {
    /// A list's scroll states, for code that remembers the list state itself.
    ///
    /// Call it inside a `remember` -- [`rememberLazyListState`] is this plus
    /// the slot -- so that the states belong to that slot and are released
    /// with it.
    pub fn new(
        initial_first_visible_item_index: usize,
        initial_first_visible_item_scroll_offset: f32,
    ) -> Self {
        LazyListState {
            scroll_position: LazyListScrollPosition {
                index: cranpose_core::mutableStateOf(initial_first_visible_item_index),
                scroll_offset: cranpose_core::mutableStateOf(
                    initial_first_visible_item_scroll_offset,
                ),
                inner: RuntimeCell::new(RefCell::new(ScrollPositionInner {
                    current_index: initial_first_visible_item_index,
                    current_scroll_offset: initial_first_visible_item_scroll_offset,
                    last_known_first_item_key: None,
                    nearest_range_state: NearestRangeState::new(initial_first_visible_item_index),
                })),
            },
            can_scroll_forward_state: cranpose_core::mutableStateOf(false),
            can_scroll_backward_state: cranpose_core::mutableStateOf(false),
            stats_state: cranpose_core::mutableStateOf(LazyLayoutStats::default()),
            scroll_in_progress_state: cranpose_core::mutableStateOf(false),
            dragged_state: cranpose_core::mutableStateOf(false),
            inner: RuntimeCell::new(RefCell::new(LazyListStateInner {
                scroll_to_be_consumed: 0.0,
                settle_policy: None,
                scroll_animation: None,
                next_scroll_animation: 1,
                gesture_scrolling: false,
                scroll_start: None,
                pending_scroll_to_index: None,
                layout_info: LazyListLayoutInfo::default(),
                spare_items_info: Vec::new(),
                current_can_scroll_forward: false,
                current_can_scroll_backward: false,
                invalidate_callbacks: Vec::new(),
                next_callback_id: 1,
                layout_invalidation_callback_id: None,
                layout_invalidation_node_id: None,
                total_composed: 0,
                reuse_count: 0,
                item_size_cache: HashMap::default(),
                item_size_clock: 0,
                average_item_size: super::DEFAULT_ITEM_SIZE_ESTIMATE,
                total_measured_items: 0,
                next_measure_cycle_id: 1,
                next_item_measure_pass_id: 1,
                last_scroll_delta: 0.0,
                hold_scroll_window: false,
            })),
        }
    }

    /// The first visible item and how far it is scrolled, or `None` once the
    /// slot that held this state was released. A saver reads it when the
    /// list leaves the composition.
    pub fn try_position(&self) -> Option<(usize, f32)> {
        self.scroll_position.inner.try_with(|inner| {
            let inner = inner.borrow();
            (inner.current_index, inner.current_scroll_offset)
        })
    }

    /// Returns a stable identity pointer for the live inner state allocation.
    ///
    /// The pointer is the address of the value `inner` keeps in the runtime, so it remains
    /// stable for the lifetime of a live `LazyListState` and can be used as a composition
    /// identity key.
    pub fn inner_ptr(&self) -> *const () {
        self.inner
            .try_with(|inner| std::ptr::from_ref(inner).cast::<()>())
            .unwrap_or(std::ptr::null())
    }

    /// Returns the index of the first visible item.
    ///
    /// When called during composition, this creates a reactive subscription
    /// so that changes to the index will trigger recomposition.
    pub fn first_visible_item_index(&self) -> usize {
        self.scroll_position.index()
    }

    /// How many items the list holds, as of its last measure.
    pub fn total_items_count(&self) -> usize {
        self.inner
            .with(|cell| cell.borrow().layout_info.total_items_count)
    }

    /// Returns the first visible item index without subscribing the current composition scope.
    ///
    /// Use this from draw/input/diagnostic code that needs the latest position but must not
    /// recompose when the scroll position changes.
    pub fn first_visible_item_index_non_reactive(&self) -> usize {
        self.scroll_position.current_index()
    }

    /// Returns the scroll offset of the first visible item.
    ///
    /// This is the amount the first item is scrolled off-screen (positive = scrolled up/left).
    /// When called during composition, this creates a reactive subscription
    /// so that changes to the offset will trigger recomposition.
    pub fn first_visible_item_scroll_offset(&self) -> f32 {
        self.scroll_position.scroll_offset()
    }

    /// Returns the first visible item scroll offset without subscribing the current composition scope.
    ///
    /// Use this from draw/input/diagnostic code that needs the latest position but must not
    /// recompose when the scroll position changes.
    pub fn first_visible_item_scroll_offset_non_reactive(&self) -> f32 {
        self.scroll_position.current_scroll_offset()
    }

    #[doc(hidden)]
    pub fn reactive_state_ids(&self) -> [StateId; 5] {
        [
            self.scroll_position.index.runtime_state_id(),
            self.scroll_position.scroll_offset.runtime_state_id(),
            self.can_scroll_forward_state.runtime_state_id(),
            self.can_scroll_backward_state.runtime_state_id(),
            self.stats_state.runtime_state_id(),
        ]
    }

    /// Returns the layout info from the last measure pass.
    pub fn layout_info(&self) -> LazyListLayoutInfo {
        self.with_layout_info(LazyListLayoutInfo::clone)
            .unwrap_or_default()
    }

    /// Reads the layout info from the last measure pass in place, without
    /// the copy of the visible items that [`Self::layout_info`] makes.
    /// `None` once the state is gone.
    pub fn with_layout_info<R>(&self, read: impl FnOnce(&LazyListLayoutInfo) -> R) -> Option<R> {
        self.inner.try_with(|cell| read(&cell.borrow().layout_info))
    }

    /// Returns the current item lifecycle statistics.
    ///
    /// When called during composition, this creates a reactive subscription
    /// so that changes to `items_in_use` or `items_in_pool` will trigger recomposition.
    /// The `total_composed` and `reuse_count` fields are diagnostic and non-reactive.
    pub fn stats(&self) -> LazyLayoutStats {
        if !self.stats_state.is_alive() || !self.inner.is_alive() {
            return LazyLayoutStats::default();
        }
        let reactive = self.stats_state.get();
        let (total_composed, reuse_count) = self.inner.with(|cell| {
            let inner = cell.borrow();
            (inner.total_composed, inner.reuse_count)
        });
        LazyLayoutStats {
            items_in_use: reactive.items_in_use,
            items_in_pool: reactive.items_in_pool,
            total_composed,
            reuse_count,
        }
    }

    /// Updates the item lifecycle statistics.
    ///
    /// Called by the layout measurement after updating slot pools.
    /// Triggers recomposition if `items_in_use` or `items_in_pool` changed.
    pub fn update_stats(&self, items_in_use: usize, items_in_pool: usize) {
        if !self.stats_state.is_alive() || !self.inner.is_alive() {
            return;
        }

        let current = self.stats_state.get_non_reactive();

        let should_update_reactive = if items_in_use > current.items_in_use {
            true
        } else if items_in_use < current.items_in_use {
            current.items_in_use - items_in_use > 1
        } else {
            false
        };

        if should_update_reactive {
            self.stats_state.set(LazyLayoutStats {
                items_in_use,
                items_in_pool,
                ..current
            });
        }
    }

    /// Records that an item was composed (either new or reused).
    ///
    /// This updates diagnostic counters in non-reactive state.
    /// Does NOT trigger recomposition.
    pub fn record_composition(&self, was_reused: bool) {
        self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            inner.total_composed += 1;
            if was_reused {
                inner.reuse_count += 1;
            }
        });
    }

    /// Makes the next measure pass size its beyond-bounds window by the last
    /// scroll delta a pass consumed when it has none of its own, so a pass
    /// between frames keeps the window the scroll gave the frame before it.
    pub fn hold_scroll_window(&self) {
        self.inner
            .try_with(|cell| cell.borrow_mut().hold_scroll_window = true);
    }

    /// Installs, or clears, where a drag or a fling the user let go of comes
    /// to rest: a pager settles on its pages.
    pub fn set_settle_policy(&self, policy: Option<LazySettlePolicy>) {
        self.inner
            .try_with(|cell| cell.borrow_mut().settle_policy = policy);
    }

    /// The installed settle policy, if any.
    pub fn settle_policy(&self) -> Option<LazySettlePolicy> {
        self.inner
            .try_with(|cell| cell.borrow().settle_policy.clone())
            .flatten()
    }

    /// Registers a scroll animation, which `stop` stops, in place of the one
    /// running, which it stops, and returns the new one's id. A press on the
    /// list stops it too.
    pub fn start_scroll_animation(&self, stop: Rc<dyn Fn()>) -> u64 {
        let Some((id, previous)) = self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            let id = inner.next_scroll_animation;
            inner.next_scroll_animation += 1;
            (id, inner.scroll_animation.replace((id, stop)))
        }) else {
            return 0;
        };
        if let Some((_, stop)) = previous {
            stop();
        }
        self.refresh_scroll_in_progress();
        id
    }

    /// Forgets the scroll animation `id` once it ended on its own.
    pub fn end_scroll_animation(&self, id: u64) {
        let _ = self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            if inner
                .scroll_animation
                .as_ref()
                .is_some_and(|(running, _)| *running == id)
            {
                inner.scroll_animation = None;
            }
        });
        self.refresh_scroll_in_progress();
    }

    /// Stops the running scroll animation, and returns whether one ran.
    pub fn stop_scroll_animation(&self) -> bool {
        let running = self
            .inner
            .try_with(|cell| cell.borrow_mut().scroll_animation.take())
            .flatten();
        let stopped = running.map(|(_, stop)| stop()).is_some();
        self.refresh_scroll_in_progress();
        stopped
    }

    /// Whether a drag, a fling, a settle or a scroll animation moves the list
    /// now: Compose's `isScrollInProgress`. A composable that reads it
    /// recomposes when a scroll starts and when it ends.
    pub fn is_scroll_in_progress(&self) -> bool {
        self.scroll_in_progress_state.is_alive() && self.scroll_in_progress_state.get()
    }

    /// Whether a finger or a pointer drags the list now: Compose's
    /// `interactionSource.collectIsDraggedAsState()`. A composable that reads
    /// it recomposes when a drag starts and when it ends.
    pub fn is_dragged(&self) -> bool {
        self.dragged_state.is_alive() && self.dragged_state.get()
    }

    /// Marks whether the scroll modifier's drag moves the list, for
    /// [`Self::is_dragged`]. The scroll modifier calls it.
    pub fn set_dragged(&self, dragged: bool) {
        if self.dragged_state.is_alive() && self.dragged_state.get_non_reactive() != dragged {
            self.dragged_state.set(dragged);
        }
    }

    /// Marks whether a drag, a fling or a settle of the scroll modifier moves
    /// the list, for [`Self::is_scroll_in_progress`]. The scroll modifier
    /// calls it; scroll animations mark themselves.
    pub fn set_gesture_scroll_active(&self, active: bool) {
        let changed = self.inner.try_with(|cell| {
            std::mem::replace(&mut cell.borrow_mut().gesture_scrolling, active) != active
        });
        if changed == Some(true) {
            self.refresh_scroll_in_progress();
        }
    }

    /// The first visible item and its offset where the scroll in progress
    /// began, or `None` while no scroll is in progress. A pager keeps its
    /// settled page from it.
    pub fn position_before_scroll(&self) -> Option<(usize, f32)> {
        self.inner
            .try_with(|cell| cell.borrow().scroll_start)
            .flatten()
    }

    fn refresh_scroll_in_progress(&self) {
        if !self.scroll_in_progress_state.is_alive() {
            return;
        }
        let Some(moving) = self.inner.try_with(|cell| {
            let inner = cell.borrow();
            inner.gesture_scrolling || inner.scroll_animation.is_some()
        }) else {
            return;
        };
        if self.scroll_in_progress_state.get_non_reactive() == moving {
            return;
        }
        let start = if moving { self.try_position() } else { None };
        let _ = self
            .inner
            .try_with(|cell| cell.borrow_mut().scroll_start = start);
        self.scroll_in_progress_state.set(moving);
    }

    /// Scrolls to the specified item index.
    ///
    /// # Arguments
    /// * `index` - The index of the item to scroll to
    /// * `scroll_offset` - Additional offset within the item (default 0)
    pub fn scroll_to_item(&self, index: usize, scroll_offset: f32) {
        if !self.inner.is_alive() {
            return;
        }
        if diagnostics::telemetry_enabled() {
            log::warn!(
                "[lazy-measure-telemetry] scroll_to_item request index={index} offset={scroll_offset:.2}"
            );
        }
        self.inner.with(|cell| {
            let mut inner = cell.borrow_mut();
            inner.pending_scroll_to_index = Some((index, scroll_offset));
            // The jump replaces the scroll deltas that have not been applied.
            inner.scroll_to_be_consumed = 0.0;
        });

        self.scroll_position
            .request_position_and_forget_last_known_key(index, scroll_offset);

        self.invalidate();
    }

    /// Dispatches a raw scroll delta.
    ///
    /// Returns the amount of scroll actually consumed.
    ///
    /// This triggers layout invalidation via registered callbacks. The callbacks
    /// are registered by LazyColumnImpl/LazyRowImpl with
    /// `schedule_measure_repass(node_id)` — the list's own item sizes are what
    /// changes, so the repass has to bubble measure dirtiness, not just
    /// placement. The node id carries through to the scene phase, which scopes
    /// its graph update to that subtree: O(subtree) instead of O(entire app).
    pub fn dispatch_scroll_delta(&self, delta: f32) -> f32 {
        let Some(cell) = self.inner.try_get() else {
            return 0.0;
        };
        let has_scroll_bounds = cell.borrow().layout_info.total_items_count > 0;
        let pushing_forward = delta < -0.001;
        let pushing_backward = delta > 0.001;
        let can_scroll_forward =
            self.can_scroll_forward_state.is_alive() && self.can_scroll_forward_non_reactive();
        let can_scroll_backward =
            self.can_scroll_backward_state.is_alive() && self.can_scroll_backward_non_reactive();
        let blocked_by_bounds = has_scroll_bounds
            && ((pushing_forward && !can_scroll_forward)
                || (pushing_backward && !can_scroll_backward));

        if blocked_by_bounds {
            let should_invalidate = {
                let mut inner = cell.borrow_mut();
                let pending_before = inner.scroll_to_be_consumed;
                if pending_before.abs() > 0.001 && pending_before.signum() == delta.signum() {
                    inner.scroll_to_be_consumed = 0.0;
                }
                if diagnostics::telemetry_enabled() {
                    log::warn!(
                        "[lazy-measure-telemetry] dispatch_scroll_delta blocked_by_bounds delta={:.2} pending_before={:.2} pending_after={:.2}",
                        delta,
                        pending_before,
                        inner.scroll_to_be_consumed
                    );
                }
                (inner.scroll_to_be_consumed - pending_before).abs() > 0.001
            };
            if should_invalidate {
                Self::run_invalidate_callbacks(&cell);
            }
            return 0.0;
        }

        let should_invalidate = {
            let mut inner = cell.borrow_mut();
            let pending_before = inner.scroll_to_be_consumed;
            let pending = inner.scroll_to_be_consumed;
            let reverse_input =
                pending.abs() > 0.001 && delta.abs() > 0.001 && pending.signum() != delta.signum();
            if reverse_input {
                if diagnostics::telemetry_enabled() {
                    log::warn!(
                        "[lazy-measure-telemetry] dispatch_scroll_delta direction_change pending={pending:.2} new_delta={delta:.2}"
                    );
                }
                inner.scroll_to_be_consumed = delta;
            } else {
                inner.scroll_to_be_consumed += delta;
            }
            inner.scroll_to_be_consumed = inner
                .scroll_to_be_consumed
                .clamp(-MAX_PENDING_SCROLL_DELTA, MAX_PENDING_SCROLL_DELTA);
            if diagnostics::telemetry_enabled() {
                log::warn!(
                    "[lazy-measure-telemetry] dispatch_scroll_delta delta={:.2} pending={:.2}",
                    delta,
                    inner.scroll_to_be_consumed
                );
            }
            (inner.scroll_to_be_consumed - pending_before).abs() > 0.001
        };
        if should_invalidate {
            Self::run_invalidate_callbacks(&cell);
        }
        delta
    }

    /// Peeks at the pending scroll delta without consuming it.
    ///
    /// Used for direction inference before measurement consumes the delta.
    /// This is more accurate than comparing first visible index, especially for:
    /// - Scrolling within the same item (partial scroll)
    /// - Variable height items where scroll offset changes without index change
    pub fn peek_scroll_delta(&self) -> f32 {
        self.inner
            .try_with(|cell| cell.borrow().scroll_to_be_consumed)
            .unwrap_or(0.0)
    }

    pub(crate) fn begin_measure_pass(&self) -> LazyListMeasureStateSnapshot {
        let (pending_scroll_delta, window_scroll_delta, pending_scroll_to, average_item_size) =
            self.inner
                .try_with(|cell| {
                    let mut inner = cell.borrow_mut();
                    let pending_scroll_to = inner.pending_scroll_to_index.take();
                    let pending_scroll_delta = inner.scroll_to_be_consumed;
                    inner.scroll_to_be_consumed = 0.0;
                    let held = std::mem::take(&mut inner.hold_scroll_window);
                    let window_scroll_delta = if pending_scroll_delta.abs() > 0.001 {
                        inner.last_scroll_delta = pending_scroll_delta;
                        pending_scroll_delta
                    } else if held {
                        inner.last_scroll_delta
                    } else {
                        0.0
                    };
                    (
                        pending_scroll_delta,
                        window_scroll_delta,
                        pending_scroll_to,
                        inner.average_item_size,
                    )
                })
                .unwrap_or((0.0, 0.0, None, super::DEFAULT_ITEM_SIZE_ESTIMATE));

        let (first_visible_item_index, first_visible_item_scroll_offset) =
            self.try_position().unwrap_or((0, 0.0));
        LazyListMeasureStateSnapshot {
            first_visible_item_index,
            first_visible_item_scroll_offset,
            pending_scroll_delta,
            window_scroll_delta,
            pending_scroll_to,
            average_item_size,
        }
    }

    pub(crate) fn next_measure_cycle_id(&self) -> u64 {
        self.inner
            .try_with(|cell| {
                let mut inner = cell.borrow_mut();
                let id = inner.next_measure_cycle_id;
                inner.next_measure_cycle_id = inner.next_measure_cycle_id.saturating_add(1);
                id
            })
            .unwrap_or(0)
    }

    pub(crate) fn next_item_measure_pass_id(&self) -> u64 {
        self.inner
            .try_with(|cell| {
                let mut inner = cell.borrow_mut();
                let id = inner.next_item_measure_pass_id;
                inner.next_item_measure_pass_id = inner.next_item_measure_pass_id.saturating_add(1);
                id
            })
            .unwrap_or(0)
    }

    fn record_item_size_sample(inner: &mut LazyListStateInner, size: f32) {
        inner.total_measured_items += 1;
        let n = inner.total_measured_items as f32;
        inner.average_item_size = inner.average_item_size * ((n - 1.0) / n) + size / n;
    }

    fn next_item_size_cache_tick(inner: &mut LazyListStateInner) -> u64 {
        inner.item_size_clock = inner.item_size_clock.saturating_add(1);
        inner.item_size_clock
    }

    fn insert_item_size(inner: &mut LazyListStateInner, index: usize, size: f32) -> bool {
        let tick = Self::next_item_size_cache_tick(inner);
        let item = CachedItemSize {
            size,
            last_used: tick,
        };
        if let Some(cached) = inner.item_size_cache.get_mut(&index) {
            *cached = item;
            return false;
        }
        if inner.item_size_cache.len() >= ITEM_SIZE_CACHE_CAPACITY {
            Self::evict_stale_item_sizes(inner, tick);
        }
        inner.item_size_cache.insert(index, item);
        true
    }

    /// Forgets the sizes that no read or write used in the last half of the
    /// cache's capacity of uses. Every use takes the next tick, so at most
    /// half the entries were used that recently: a full cache frees half its
    /// room in one pass, and the oldest sizes go first.
    fn evict_stale_item_sizes(inner: &mut LazyListStateInner, tick: u64) {
        let oldest_kept = tick.saturating_sub((ITEM_SIZE_CACHE_CAPACITY / 2) as u64);
        inner
            .item_size_cache
            .retain(|_, item| item.last_used > oldest_kept);
    }

    /// Caches the measured size of an item for scroll estimation.
    pub fn cache_item_size(&self, index: usize, size: f32) {
        self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            if Self::insert_item_size(&mut inner, index, size) {
                Self::record_item_size_sample(&mut inner, size);
            }
        });
    }

    /// Caches multiple measured item sizes in one pass and returns the updated average.
    pub fn cache_item_sizes<I>(&self, sizes: I) -> f32
    where
        I: IntoIterator<Item = (usize, f32)>,
    {
        self.inner
            .try_with(|cell| {
                let mut inner = cell.borrow_mut();
                for (index, size) in sizes {
                    if Self::insert_item_size(&mut inner, index, size) {
                        Self::record_item_size_sample(&mut inner, size);
                    }
                }
                inner.average_item_size
            })
            .unwrap_or(super::DEFAULT_ITEM_SIZE_ESTIMATE)
    }

    /// Gets a cached item size if available.
    pub fn get_cached_size(&self, index: usize) -> Option<f32> {
        self.inner
            .try_with(|cell| {
                let mut inner = cell.borrow_mut();
                let tick = Self::next_item_size_cache_tick(&mut inner);
                let item = inner.item_size_cache.get_mut(&index)?;
                item.last_used = tick;
                Some(item.size)
            })
            .flatten()
    }

    /// Returns the running average of measured item sizes.
    pub fn average_item_size(&self) -> f32 {
        self.inner
            .try_with(|cell| cell.borrow().average_item_size)
            .unwrap_or(super::DEFAULT_ITEM_SIZE_ESTIMATE)
    }

    /// Returns the current nearest range for optimized key lookup.
    pub fn nearest_range(&self) -> std::ops::Range<usize> {
        self.scroll_position.nearest_range()
    }

    pub(crate) fn update_scroll_position(
        &self,
        first_visible_item_index: usize,
        first_visible_item_scroll_offset: f32,
    ) {
        self.scroll_position.update_from_measure_result(
            first_visible_item_index,
            first_visible_item_scroll_offset,
            None,
        );
    }

    pub(crate) fn update_scroll_position_with_key(
        &self,
        first_visible_item_index: usize,
        first_visible_item_scroll_offset: f32,
        first_visible_item_key: u64,
    ) {
        self.scroll_position.update_from_measure_result(
            first_visible_item_index,
            first_visible_item_scroll_offset,
            Some(first_visible_item_key),
        );
    }

    /// Adjusts scroll position if the first visible item was moved due to data changes.
    ///
    /// Matches JC's `updateScrollPositionIfTheFirstItemWasMoved`.
    /// If items were inserted/removed before the current scroll position,
    /// this finds the item by its key and updates the index accordingly.
    ///
    /// Returns the adjusted first visible item index.
    pub fn update_scroll_position_if_item_moved<F>(
        &self,
        new_item_count: usize,
        get_index_by_key: F,
    ) -> usize
    where
        F: Fn(u64) -> Option<usize>,
    {
        self.scroll_position
            .update_if_first_item_moved(new_item_count, get_index_by_key)
    }

    pub(crate) fn update_layout_info(&self, mut info: LazyListLayoutInfo) {
        self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            info.snap_anchor_offset = continuous_snap_anchor_offset(&inner.layout_info, &info);
            let mut spare = std::mem::replace(&mut inner.layout_info, info).visible_items_info;
            spare.clear();
            inner.spare_items_info = spare;
        });
    }

    /// An empty list for the next layout info's visible items, which keeps
    /// the storage of the one before.
    pub(crate) fn spare_items_info(&self) -> Vec<LazyListItemInfo> {
        self.inner
            .try_with(|cell| std::mem::take(&mut cell.borrow_mut().spare_items_info))
            .unwrap_or_default()
    }

    /// Returns whether we can scroll forward (more items below/right).
    ///
    /// When called during composition, this creates a reactive subscription
    /// so that changes will trigger recomposition.
    pub fn can_scroll_forward(&self) -> bool {
        if !self.can_scroll_forward_state.is_alive() {
            return false;
        }
        self.can_scroll_forward_state.subscribe_current_scope_only();
        self.can_scroll_forward_non_reactive()
    }

    /// Returns whether the list can scroll forward without subscribing the current composition scope.
    pub fn can_scroll_forward_non_reactive(&self) -> bool {
        if !self.can_scroll_forward_state.is_alive() {
            return false;
        }
        self.inner
            .try_with(|cell| cell.borrow().current_can_scroll_forward)
            .unwrap_or(false)
    }

    /// Returns whether we can scroll backward (more items above/left).
    ///
    /// When called during composition, this creates a reactive subscription
    /// so that changes will trigger recomposition.
    pub fn can_scroll_backward(&self) -> bool {
        if !self.can_scroll_backward_state.is_alive() {
            return false;
        }
        self.can_scroll_backward_state
            .subscribe_current_scope_only();
        self.can_scroll_backward_non_reactive()
    }

    /// Returns whether the list can scroll backward without subscribing the current composition scope.
    pub fn can_scroll_backward_non_reactive(&self) -> bool {
        if !self.can_scroll_backward_state.is_alive() {
            return false;
        }
        self.inner
            .try_with(|cell| cell.borrow().current_can_scroll_backward)
            .unwrap_or(false)
    }

    pub(crate) fn update_scroll_bounds(&self) {
        if !self.can_scroll_forward_state.is_alive() || !self.can_scroll_backward_state.is_alive() {
            return;
        }
        let Some(cell) = self.inner.try_get() else {
            return;
        };
        let can_forward = {
            let inner = cell.borrow();
            let info = &inner.layout_info;
            let viewport_end = info.viewport_size - info.after_content_padding;
            // A staggered grid's last item by index need not be the one
            // that reaches furthest.
            if let Some(last_visible) = info.visible_items_info.last() {
                last_visible.index < info.total_items_count.saturating_sub(1)
                    || info
                        .visible_items_info
                        .iter()
                        .rev()
                        .any(|item| item.offset + item.size > viewport_end)
            } else {
                false
            }
        };

        let (first_index, first_offset) = self.try_position().unwrap_or((0, 0.0));
        let can_backward = first_index > 0 || first_offset > 0.0;

        {
            let mut inner = cell.borrow_mut();
            inner.current_can_scroll_forward = can_forward;
            inner.current_can_scroll_backward = can_backward;
        }

        if self.can_scroll_forward_state.get_non_reactive() != can_forward {
            self.can_scroll_forward_state.set(can_forward);
        }
        if self.can_scroll_backward_state.get_non_reactive() != can_backward {
            self.can_scroll_backward_state.set(can_backward);
        }
    }

    /// Adds an invalidation callback.
    pub fn add_invalidate_callback(&self, callback: Rc<dyn Fn()>) -> u64 {
        self.inner
            .try_with(|cell| {
                let mut inner = cell.borrow_mut();
                let id = inner.next_callback_id;
                inner.next_callback_id += 1;
                inner.invalidate_callbacks.push((id, callback));
                id
            })
            .unwrap_or(0)
    }

    /// Tries to register a layout invalidation callback for the specified node.
    ///
    /// Returns the callback id for the active layout callback.
    ///
    /// Registering again always replaces the previous active layout callback, even when
    /// the node id stays the same. This keeps ownership tied to the latest effect
    /// instance so disposing an older scope cannot unregister the live callback.
    pub fn try_register_layout_callback(
        &self,
        node_id: NodeId,
        callback: Rc<dyn Fn()>,
    ) -> Option<u64> {
        if !self.inner.is_alive() {
            return None;
        }
        self.inner.with(|cell| {
            let mut inner = cell.borrow_mut();
            if let Some(existing_id) = inner.layout_invalidation_callback_id {
                inner
                    .invalidate_callbacks
                    .retain(|(cb_id, _)| *cb_id != existing_id);
            }
            let id = inner.next_callback_id;
            inner.next_callback_id += 1;
            inner.invalidate_callbacks.push((id, callback));
            inner.layout_invalidation_callback_id = Some(id);
            inner.layout_invalidation_node_id = Some(node_id);
            Some(id)
        })
    }

    /// Removes an invalidation callback.
    pub fn remove_invalidate_callback(&self, id: u64) {
        self.inner.try_with(|cell| {
            let mut inner = cell.borrow_mut();
            inner.invalidate_callbacks.retain(|(cb_id, _)| *cb_id != id);
            if inner.layout_invalidation_callback_id == Some(id) {
                inner.layout_invalidation_callback_id = None;
                inner.layout_invalidation_node_id = None;
            }
        });
    }

    fn invalidate(&self) {
        if let Some(cell) = self.inner.try_get() {
            Self::run_invalidate_callbacks(&cell);
        }
    }

    /// Runs the invalidation callbacks `cell` holds, from a copy of the
    /// list: a callback may register or remove callbacks.
    fn run_invalidate_callbacks(cell: &RefCell<LazyListStateInner>) {
        let callbacks: Vec<_> = cell
            .borrow()
            .invalidate_callbacks
            .iter()
            .map(|(_, cb)| Rc::clone(cb))
            .collect();

        for callback in callbacks {
            callback();
        }
    }
}

/// Information about the currently visible items in a lazy list.
#[derive(Clone, Default, Debug)]
pub struct LazyListLayoutInfo {
    /// Information about each visible item.
    pub visible_items_info: Vec<LazyListItemInfo>,

    /// Total number of items in the list.
    pub total_items_count: usize,

    /// Raw viewport size reported by parent constraints (before infinite fallback).
    pub raw_viewport_size: f32,

    /// Whether the viewport was treated as infinite/unbounded.
    pub is_infinite_viewport: bool,

    /// Size of the viewport in the main axis.
    pub viewport_size: f32,

    /// Start offset of the viewport in layout coordinates.
    pub viewport_start_offset: f32,

    /// End offset of the viewport in layout coordinates.
    pub viewport_end_offset: f32,

    /// Content padding before the first item.
    pub before_content_padding: f32,

    /// Content padding after the last item.
    pub after_content_padding: f32,

    /// The space between two items — Compose's `mainAxisItemSpacing`.
    pub main_axis_item_spacing: f32,

    /// Continuous main-axis visual offset used to snap translated lazy-list content.
    pub snap_anchor_offset: f32,

    /// Whether item offsets are placed from the end edge of the viewport.
    pub reverse_layout: bool,
}

/// Information about a single visible item in a lazy list.
#[derive(Clone, Debug)]
pub struct LazyListItemInfo {
    /// Index of the item in the data source.
    pub index: usize,

    /// Key of the item.
    pub key: u64,

    /// Offset of the item from the start of the list content.
    pub offset: f32,

    /// Size of the item in the main axis.
    pub size: f32,
}

fn continuous_snap_anchor_offset(
    previous: &LazyListLayoutInfo,
    current: &LazyListLayoutInfo,
) -> f32 {
    let Some(first_current) = current.visible_items_info.first() else {
        return 0.0;
    };

    for current_item in &current.visible_items_info {
        if let Some(previous_item) = previous
            .visible_items_info
            .iter()
            .find(|item| item.key == current_item.key)
        {
            let previous_offset = snap_anchor_item_offset(previous, previous_item);
            let current_offset = snap_anchor_item_offset(current, current_item);
            return previous.snap_anchor_offset + current_offset - previous_offset;
        }
    }

    snap_anchor_item_offset(current, first_current)
}

fn snap_anchor_item_offset(info: &LazyListLayoutInfo, item: &LazyListItemInfo) -> f32 {
    if info.reverse_layout {
        info.viewport_size - item.offset - item.size
    } else {
        item.offset
    }
}

#[cfg(test)]
#[path = "tests/lazy_list_state_test_helpers.rs"]
pub(crate) mod test_helpers;

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