bevy_react_core 0.8.0

//! Mouse-wheel scrolling for `overflow: scroll` nodes.
//!
//! `bevy_ui` clips an `OverflowAxis::Scroll` node's content and offsets its
//! children by the node's [`ScrollPosition`], but nothing drives that component
//! from input — Bevy leaves the wheel handling to the app. [`apply_scroll`] is
//! that handler: each frame it reads the accumulated wheel delta, finds the
//! scroll container under the cursor, and moves its `ScrollPosition`.

use bevy::camera::{NormalizedRenderTarget, RenderTarget};
use bevy::ecs::system::SystemParam;
use bevy::input::mouse::{AccumulatedMouseScroll, MouseScrollUnit};
use bevy::picking::pointer::{PointerId, PointerLocation};
use bevy::prelude::*;
use bevy::ui::{ComputedNode, ComputedUiTargetCamera, ScrollPosition, UiGlobalTransform, UiStack};
use bevy::window::PrimaryWindow;

use crate::bridge::{JsBridge, ReactNode, ScrollStep, WheelListener};
use crate::plugin::PointerCapture;
use crate::protocol::{outbound::Outbound, outbound::UiEvent};
use crate::transition::ScrollTransitionState;

/// Default logical pixels scrolled per wheel "line" (mice report `Line` units;
/// trackpads report `Pixel`). A middling value that feels close to a typical
/// desktop. A node's `scrollStep` prop ([`ScrollStep`]) overrides it per container.
const LINE_HEIGHT: f32 = 20.0;

/// Where the wheel points, per UI camera: UI on a window camera is hit-tested
/// against the window cursor; UI on an image-target camera (a `<surface>`)
/// against the [`VirtualPointers`](crate::ext::VirtualPointers) pointer sitting
/// on that image, and is out of reach while none does — its geometry is in
/// texture px, which the window cursor must never be tested against.
#[derive(SystemParam)]
pub struct WheelCursors<'w, 's> {
    windows: Query<'w, 's, &'static Window, With<PrimaryWindow>>,
    cameras: Query<'w, 's, &'static RenderTarget, With<Camera>>,
    pointers: Query<'w, 's, (&'static PointerId, &'static PointerLocation)>,
    virtual_pointers: Option<Res<'w, crate::ext::VirtualPointers>>,
    target_cameras: Query<'w, 's, &'static ComputedUiTargetCamera>,
}

/// A wheel cursor in physical px (node geometry's space) and logical px (the
/// event's `clientX`/`clientY`).
#[derive(Clone, Copy)]
struct WheelCursor {
    physical: Vec2,
    logical: Vec2,
}

impl WheelCursors<'_, '_> {
    /// The UI nodes the wheel may hit with the cursor each is tested against,
    /// topmost first: window UI before image-target UI (screen UI draws over
    /// the world), each in `UiStack` order.
    fn candidates(&self, ui_stack: &UiStack) -> Vec<(Entity, WheelCursor)> {
        let window = self.windows.single().ok().and_then(|w| {
            let logical = w.cursor_position()?;
            Some(WheelCursor {
                physical: logical * w.scale_factor(),
                logical,
            })
        });
        let on_images: Vec<(AssetId<Image>, WheelCursor)> = self
            .pointers
            .iter()
            .filter(|(id, _)| {
                self.virtual_pointers
                    .as_ref()
                    .is_some_and(|v| v.contains(**id))
            })
            .filter_map(|(_, location)| {
                let location = location.location()?;
                let NormalizedRenderTarget::Image(image) = &location.target else {
                    return None;
                };
                Some((
                    image.handle.id(),
                    WheelCursor {
                        physical: location.position * image.scale_factor,
                        logical: location.position,
                    },
                ))
            })
            .collect();
        // `Some(is_image, cursor)`: the node's cursor, `None` = out of reach.
        let cursor_of = |entity: Entity| -> Option<(bool, WheelCursor)> {
            let camera = self.target_cameras.get(entity).ok().and_then(|c| c.get());
            match camera.and_then(|c| self.cameras.get(c).ok()) {
                Some(RenderTarget::Image(image)) => on_images
                    .iter()
                    .find(|(id, _)| *id == image.handle.id())
                    .map(|(_, cursor)| (true, *cursor)),
                _ => window.map(|cursor| (false, cursor)),
            }
        };
        let mut window_nodes = Vec::new();
        let mut image_nodes = Vec::new();
        for &entity in ui_stack.uinodes.iter().rev() {
            match cursor_of(entity) {
                Some((false, cursor)) => window_nodes.push((entity, cursor)),
                Some((true, cursor)) => image_nodes.push((entity, cursor)),
                None => {}
            }
        }
        window_nodes.extend(image_nodes);
        window_nodes
    }
}

/// Whether a node opts into scrolling on either axis.
pub(crate) fn is_scroll_container(node: &Node) -> bool {
    node.overflow.x == OverflowAxis::Scroll || node.overflow.y == OverflowAxis::Scroll
}

/// The scrollable range in logical px per axis (`0` = "no scroll"). Bevy clamps
/// the offset it *applies* for rendering but never writes that back to
/// `ScrollPosition`, so every scroll writer clamps against this itself.
/// `ComputedNode` sizes are physical; the component is logical — hence
/// `inverse_scale_factor`.
///
/// Mirrors what `ui_layout_system` clamps to, taffy's `Layout::scroll_width`
/// / `scroll_height`: `content_size` is the scrollable overflow extent
/// (measured inside the border), so the range is that extent less the
/// padding box (`size` minus both borders), plus the scrollbar's gutter.
pub(crate) fn scroll_range(computed: &ComputedNode) -> Vec2 {
    let border = computed.border.min_inset + computed.border.max_inset;
    (computed.content_size + computed.scrollbar_size.min(computed.size) - computed.size + border)
        .max(Vec2::ZERO)
        * computed.inverse_scale_factor
}

/// The offset a scroll writer moves from: the eased target when a scroll
/// transition owns the offset (so successive ticks accumulate toward a farther
/// target instead of re-basing mid-ease), else the live position.
pub(crate) fn scroll_base(pos: &ScrollPosition, state: Option<&ScrollTransitionState>) -> Vec2 {
    state.map_or(pos.0, |s| s.target)
}

/// Write `next` to the eased target when a transition owns the offset
/// (`drive_scroll_transition` then moves `ScrollPosition`), else to the live
/// offset directly. `!=`-guarded on both paths so re-writing an unchanged value
/// stays change-tick quiet (`settle_controlled_scroll`'s read-back dedup
/// relies on that).
pub(crate) fn write_scroll(
    pos: &mut ScrollPosition,
    state: Option<Mut<ScrollTransitionState>>,
    next: Vec2,
) {
    match state {
        Some(mut state) => {
            if state.target != next {
                state.target = next;
            }
        }
        None => {
            if pos.0 != next {
                pos.0 = next;
            }
        }
    }
}

/// Move the `ScrollPosition` of the scroll container under the cursor by the
/// frame's wheel delta. Runs in `PointerCaptureSet` after `collect_pointer_events`
/// so that, when it actually scrolls, it can flag the pointer as UI-owned and stop
/// world systems (e.g. a wheel-zoom camera) from also consuming the same wheel.
///
/// The pointer is only claimed (`PointerCapture::over_ui`) when a container actually
/// moves — a scroll container whose content fits (no scroll range on the wheeled axis)
/// lets the wheel fall through, so a camera behind a transparent, non-overflowing
/// scroll pane can still zoom.
///
/// Target selection is by **geometry, topmost-first**. Every `Node` carries a
/// `ScrollPosition` (it's a required component), so "has a `ScrollPosition`" is
/// meaningless — we must check `Node.overflow`. We walk the `UiStack` top to bottom
/// and hit-test each node's rectangle with [`ComputedNode::contains_point`] against
/// its camera's cursor ([`WheelCursors`]: the window cursor, or the in-world
/// pointer on a `<surface>`):
/// - The topmost node under the cursor that declared `onWheel` (a [`WheelListener`])
///   **claims** the wheel: it emits via [`collect_wheel_events`], and here we stop
///   without scrolling anything beneath it. That is what lets an `onWheel` node
///   (e.g. a zoomable map) sit inside a scroll page and swallow the wheel instead of
///   also scrolling its ancestor — DOM `preventDefault` semantics.
/// - Otherwise the topmost real scroll container under the cursor scrolls. This stays
///   content-agnostic: plain nodes on top (text glyphs, images) are transparent
///   because they are neither listeners nor scroll containers.
///
/// Bevy's layout clamps the *applied* offset to `[0, max]`, so writing freely here
/// never overscrolls.
#[allow(clippy::type_complexity)]
pub fn apply_scroll(
    accumulated: Res<AccumulatedMouseScroll>,
    cursors: WheelCursors,
    ui_stack: Res<UiStack>,
    mut scrollables: Query<(
        &ComputedNode,
        &UiGlobalTransform,
        &Node,
        &mut ScrollPosition,
        Option<&ScrollStep>,
        Option<&mut ScrollTransitionState>,
    )>,
    wheel_listeners: Query<(), With<WheelListener>>,
    mut capture: ResMut<PointerCapture>,
) {
    if accumulated.delta == Vec2::ZERO {
        return;
    }
    // Topmost-first: the first node under the cursor that claims the wheel wins.
    // This also resolves nested scroll areas correctly (an inner one sits later in
    // the stack, so it's hit first). Geometry is physical px; a camera with a custom
    // viewport offset is not handled here.
    for (entity, cursor) in cursors.candidates(&ui_stack) {
        let Ok((computed, transform, node, mut pos, step, scroll_state)) =
            scrollables.get_mut(entity)
        else {
            continue;
        };
        if !computed.contains_point(*transform, cursor.physical) {
            continue; // cursor not over this node — transparent, keep scanning
        }
        // An `onWheel` node on top claims the wheel: stop before scrolling anything
        // beneath it. `collect_wheel_events` does the emission (+ the `over_ui`
        // claim); we only need to make sure no ancestor scroll container also moves.
        if wheel_listeners.contains(entity) {
            return;
        }
        if !is_scroll_container(node) {
            continue; // a plain node over the cursor is transparent to scrolling
        }
        // Wheel delta → logical pixels, scaled by this container's step. A positive
        // wheel delta scrolls the view up (content down), i.e. *decreases* the offset.
        let delta = match accumulated.unit {
            MouseScrollUnit::Line => accumulated.delta * step.map(|s| s.0).unwrap_or(LINE_HEIGHT),
            MouseScrollUnit::Pixel => accumulated.delta,
        };
        // Clamp to the scrollable range so the offset can't accumulate past the
        // ends (otherwise you'd have to "unscroll" the slack before it moves).
        let max = scroll_range(computed);
        let base = scroll_base(&pos, scroll_state.as_deref());
        // Only the axes with actual scroll range (`max > 0`) consume the wheel;
        // a container whose content fits has nothing to move.
        let mut next = base;
        let mut consumed = false;
        if node.overflow.x == OverflowAxis::Scroll && delta.x != 0.0 && max.x > 0.0 {
            next.x = (base.x - delta.x).clamp(0.0, max.x);
            consumed = true;
        }
        if node.overflow.y == OverflowAxis::Scroll && delta.y != 0.0 && max.y > 0.0 {
            next.y = (base.y - delta.y).clamp(0.0, max.y);
            consumed = true;
        }
        if consumed {
            write_scroll(&mut pos, scroll_state, next);
            // The wheel consumed an in-range axis — claim the wheel channel
            // so world wheel-consumers that honor `PointerCapture` (the orbit
            // camera's wheel-zoom, etc.) ignore the same wheel this frame. Not
            // a hover claim: `over_ui` stays as this frame's hover left it.
            capture.wheel_captured = true;
            break;
        }
        // Nothing to scroll here (content fits the container) — keep scanning lower
        // containers, and ultimately leave the wheel for world input so e.g. a
        // camera behind a transparent, non-overflowing scroll pane can still zoom.
    }
}

/// A controlled `scrollTop`/`scrollLeft` request (raw, pre-clamp) whose clamp
/// must be redone after layout. The op-apply clamp
/// (`reconcile::update_controlled_scroll`) runs before `UiSystems::Layout`,
/// so when the same commit also changes the content (the canonical case: a
/// log appending rows AND pinning `scrollTop={BIG}` to the bottom), it clamps
/// against LAST frame's `ComputedNode` and lands short — or, worse, the stale
/// clamp equals the live offset and nothing is written at all.
/// [`settle_controlled_scroll`] re-clamps this raw request against fresh
/// post-layout geometry and removes the marker. Inserted whenever a
/// controlled write's request falls outside the stale range (and on create,
/// where no geometry exists yet at all).
#[derive(Component, Debug, Clone, Copy, PartialEq)]
pub struct PendingControlledScroll(pub Vec2);

/// Re-clamp deferred controlled-scroll requests against this frame's layout
/// (runs in `PostUpdate` after `UiSystems::Layout`). The corrected offset is
/// applied to child transforms by NEXT frame's layout — one frame late, but
/// exact. The `!=` guards keep change ticks quiet when the stale clamp was
/// already right, so the `onScroll` read-back dedup (which compares against
/// the recorded RAW request) fires exactly once with the real offset when —
/// and only when — the request overshot.
pub fn settle_controlled_scroll(
    mut commands: Commands,
    mut pending: Query<(
        Entity,
        &PendingControlledScroll,
        &ComputedNode,
        &mut ScrollPosition,
        Option<&mut ScrollTransitionState>,
    )>,
) {
    for (entity, request, computed, mut pos, scroll_state) in &mut pending {
        let clamped = request.0.clamp(Vec2::ZERO, scroll_range(computed));
        write_scroll(&mut pos, scroll_state, clamped);
        commands.entity(entity).remove::<PendingControlledScroll>();
    }
}

/// Deliver raw mouse-wheel deltas to the topmost `onWheel` node under the cursor.
///
/// Unlike [`apply_scroll`] (which only moves `overflow: scroll` containers), this
/// fires for **any** node that declared an `onWheel` handler — e.g. a zoomable
/// `<canvas>` map. The delta is passed through untouched (no `ScrollStep` scaling);
/// `deltaMode` (`"line"`/`"pixel"`) tells the app how to read it, like DOM
/// `WheelEvent`.
///
/// Target selection mirrors [`apply_scroll`]: a geometric hit-test over the
/// `UiStack`, topmost first, filtered to [`WheelListener`] nodes — no hover
/// state needed, so it composes cleanly with the `onPointer*` machinery. Runs in
/// `PointerCaptureSet` after `collect_pointer_events` so the
/// `PointerCapture::wheel_captured` claim survives (that system *resets* it),
/// letting world wheel-consumers (a zoom camera) ignore a wheel a node just
/// handled.
pub fn collect_wheel_events(
    accumulated: Res<AccumulatedMouseScroll>,
    cursors: WheelCursors,
    ui_stack: Res<UiStack>,
    bridge: Res<JsBridge>,
    listeners: Query<(&ComputedNode, &UiGlobalTransform, &ReactNode), With<WheelListener>>,
    mut capture: ResMut<PointerCapture>,
    // `Option` so headless harnesses without input needn't init it.
    keys: Option<Res<ButtonInput<KeyCode>>>,
) {
    if accumulated.delta == Vec2::ZERO {
        return;
    }
    let delta_mode = match accumulated.unit {
        MouseScrollUnit::Line => "line",
        MouseScrollUnit::Pixel => "pixel",
    };

    // Topmost-first: the first `onWheel` node whose rect contains its cursor wins.
    for (entity, cursor) in cursors.candidates(&ui_stack) {
        let Ok((computed, transform, rnode)) = listeners.get(entity) else {
            continue;
        };
        if !computed.contains_point(*transform, cursor.physical) {
            continue;
        }
        // Normalized 0..1 position within the node (top-left origin), matching the
        // pointer events' `x`/`y`. A successful `contains_point` implies a non-zero
        // size, so the divide is safe.
        let size = computed.size;
        let min = transform.translation - size * 0.5;
        let norm = ((cursor.physical - min) / size).clamp(Vec2::ZERO, Vec2::ONE);
        let mut event = UiEvent {
            id: rnode.0,
            kind: "wheel".to_string(),
            x: Some(norm.x),
            y: Some(norm.y),
            client_x: Some(cursor.logical.x),
            client_y: Some(cursor.logical.y),
            delta_x: Some(accumulated.delta.x),
            delta_y: Some(accumulated.delta.y),
            delta_mode: Some(delta_mode.to_string()),
            ..default()
        };
        crate::reconcile::Modifiers::read(keys.as_deref()).stamp(&mut event);
        let _ = bridge.outbound_tx.send(Outbound::UiEvent { event });
        // The node handled the wheel — claim the wheel channel so world
        // wheel-consumers that honor `PointerCapture` ignore the same wheel
        // this frame. Not a hover claim: `over_ui` stays untouched.
        capture.wheel_captured = true;
        break;
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use bevy::ecs::system::RunSystemOnce;

    #[test]
    fn scroll_range_is_zero_when_content_fits() {
        let fits = ComputedNode {
            size: Vec2::new(100.0, 100.0),
            content_size: Vec2::new(100.0, 100.0),
            inverse_scale_factor: 1.0,
            ..default()
        };
        assert_eq!(scroll_range(&fits), Vec2::ZERO);

        let overflowing = ComputedNode {
            size: Vec2::new(100.0, 100.0),
            content_size: Vec2::new(100.0, 300.0),
            inverse_scale_factor: 1.0,
            ..default()
        };
        assert_eq!(scroll_range(&overflowing), Vec2::new(0.0, 200.0));
    }

    /// Drive `apply_scroll` against a 200×100 scroll container centered at (300, 200)
    /// holding `content_h`px of content (so the scroll range is `[0, content_h - 100]`
    /// logical), with a non-scrolling child node ("text") on top of it (also carrying a
    /// `ScrollPosition`, since every `Node` does). Starts the container at `start`,
    /// applies one `Line` wheel tick of `wheel`, and returns the container's resulting
    /// `ScrollPosition` plus the resulting [`PointerCapture`].
    fn run_with_content(
        cursor: Vec2,
        start: Vec2,
        wheel: Vec2,
        content_h: f32,
    ) -> (Vec2, PointerCapture) {
        let mut world = World::new();

        let mut window = Window::default();
        window.set_physical_cursor_position(Some(cursor.as_dvec2()));
        world.spawn((window, PrimaryWindow));

        let container = world
            .spawn((
                Node {
                    overflow: Overflow::scroll_y(),
                    ..default()
                },
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, content_h),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                ScrollPosition(start),
            ))
            .id();
        // A child "text" node fully inside the container. It is NOT a scroll container
        // (overflow visible) yet still carries a `ScrollPosition` — exactly the case
        // that broke before. It sits in front of the container in the stack.
        let child = world
            .spawn((
                Node::default(),
                ComputedNode {
                    size: Vec2::new(80.0, 20.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                ScrollPosition::default(),
            ))
            .id();

        // Back-to-front: container behind, child in front (so the child is hit first
        // when iterating topmost-first, and must be skipped for not opting into scroll).
        world.insert_resource(UiStack {
            uinodes: vec![container, child],
            partition: Vec::new(),
        });
        world.insert_resource(AccumulatedMouseScroll {
            unit: MouseScrollUnit::Line,
            delta: wheel,
        });
        world.insert_resource(PointerCapture::default());

        world.run_system_once(apply_scroll).unwrap();

        let pos = world.entity(container).get::<ScrollPosition>().unwrap().0;
        let capture = *world.resource::<PointerCapture>();
        (pos, capture)
    }

    /// Like [`run_with_content`] with the default 300px content (scroll range `[0, 200]`).
    fn run(cursor: Vec2, start: Vec2, wheel: Vec2) -> (Vec2, PointerCapture) {
        run_with_content(cursor, start, wheel, 300.0)
    }

    /// A 200×100 scroll container holding 300px of content, plus any extra components
    /// the caller adds (e.g. `ScrollStep`, `ScrollTransitionState`). Cursor centered,
    /// one `Line` wheel tick of `wheel`. Returns the container entity + world.
    fn run_with(extra: impl Bundle, wheel: Vec2) -> (World, Entity) {
        let mut world = World::new();
        let mut window = Window::default();
        window.set_physical_cursor_position(Some(Vec2::new(300.0, 200.0).as_dvec2()));
        world.spawn((window, PrimaryWindow));
        let container = world
            .spawn((
                Node {
                    overflow: Overflow::scroll_y(),
                    ..default()
                },
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, 300.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                ScrollPosition::default(),
                extra,
            ))
            .id();
        world.insert_resource(UiStack {
            uinodes: vec![container],
            partition: Vec::new(),
        });
        world.insert_resource(AccumulatedMouseScroll {
            unit: MouseScrollUnit::Line,
            delta: wheel,
        });
        world.insert_resource(PointerCapture::default());
        world.run_system_once(apply_scroll).unwrap();
        (world, container)
    }

    #[test]
    fn scroll_step_scales_the_wheel_delta() {
        // A custom step of 40 moves twice the default 20 per line tick (wheel down).
        let (world, container) = run_with(ScrollStep(40.0), Vec2::new(0.0, -1.0));
        let pos = world.entity(container).get::<ScrollPosition>().unwrap().0;
        assert_eq!(pos, Vec2::new(0.0, 40.0));
    }

    #[test]
    fn wheel_feeds_target_when_scroll_transition_present() {
        // With a `ScrollTransitionState`, the wheel sets the eased *target*, leaving
        // `ScrollPosition` untouched (the drive system moves it later).
        let (world, container) = run_with(ScrollTransitionState::default(), Vec2::new(0.0, -1.0));
        assert_eq!(
            world.entity(container).get::<ScrollPosition>().unwrap().0,
            Vec2::ZERO,
            "the wheel must not move the offset directly when easing"
        );
        assert_eq!(
            world
                .entity(container)
                .get::<ScrollTransitionState>()
                .unwrap()
                .target,
            Vec2::new(0.0, 20.0),
            "the wheel accumulates into the eased target"
        );
    }

    #[test]
    fn scrolls_container_when_cursor_is_over_its_child_text() {
        // Cursor over the child "text"; wheel down (delta.y < 0) reveals lower content
        // → offset.y increases by LINE_HEIGHT, within the [0, 200] range.
        let (pos, capture) = run(Vec2::new(300.0, 200.0), Vec2::ZERO, Vec2::new(0.0, -1.0));
        assert_eq!(pos, Vec2::new(0.0, LINE_HEIGHT));
        assert!(
            capture.wheel_captured,
            "a consumed wheel must claim the wheel channel"
        );
        assert!(
            !capture.over_ui,
            "consuming the wheel is not a hover claim — `over_ui` stays untouched \
             so world drag/press gating is unaffected"
        );
    }

    #[test]
    fn clamps_at_the_bottom() {
        // Near the end (190) + a 20px wheel-down tick would reach 210, but the max is
        // 200 (content 300 − size 100), so it clamps instead of accumulating slack.
        let (pos, _) = run(
            Vec2::new(300.0, 200.0),
            Vec2::new(0.0, 190.0),
            Vec2::new(0.0, -1.0),
        );
        assert_eq!(pos, Vec2::new(0.0, 200.0));
    }

    #[test]
    fn clamps_at_the_top() {
        // Near the start (10) + a 20px wheel-up tick would reach −10, but it clamps to 0.
        let (pos, _) = run(
            Vec2::new(300.0, 200.0),
            Vec2::new(0.0, 10.0),
            Vec2::new(0.0, 1.0),
        );
        assert_eq!(pos, Vec2::new(0.0, 0.0));
    }

    /// `<surface>` UI (on an image-target camera) is wheeled by the virtual
    /// pointer sitting on that image, never by the window cursor — whose
    /// window px would otherwise hit texture-px geometry at the same numbers.
    #[test]
    fn surface_ui_scrolls_under_its_virtual_pointer_only() {
        use bevy::camera::ImageRenderTarget;
        use bevy::picking::pointer::Location;
        use bevy::reflect::{FromReflect, structs::DynamicStruct};

        let run = |pointer_at: Option<Vec2>| {
            let mut world = World::new();
            world.init_resource::<bevy::picking::pointer::PointerMap>();
            let mut window = Window::default();
            window.set_physical_cursor_position(Some(Vec2::new(300.0, 200.0).as_dvec2()));
            world.spawn((window, PrimaryWindow));
            let image = ImageRenderTarget {
                handle: Handle::<Image>::default(),
                scale_factor: 1.0,
            };
            let camera = world
                .spawn((Camera::default(), RenderTarget::Image(image.clone())))
                .id();
            let mut target = DynamicStruct::default();
            target.insert("camera", Some(camera));
            let container = world
                .spawn((
                    Node {
                        overflow: Overflow::scroll_y(),
                        ..default()
                    },
                    ComputedNode {
                        size: Vec2::new(200.0, 100.0),
                        content_size: Vec2::new(200.0, 300.0),
                        inverse_scale_factor: 1.0,
                        ..default()
                    },
                    UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                    ScrollPosition::default(),
                    ComputedUiTargetCamera::from_reflect(&target).unwrap(),
                ))
                .id();
            if let Some(position) = pointer_at {
                let id = PointerId::Custom(bevy::asset::uuid::Uuid::from_u128(7));
                let mut pointers = crate::ext::VirtualPointers::default();
                pointers.register(id);
                world.insert_resource(pointers);
                world.spawn((
                    id,
                    PointerLocation::new(Location {
                        target: NormalizedRenderTarget::Image(image),
                        position,
                    }),
                ));
            }
            world.insert_resource(UiStack {
                uinodes: vec![container],
                partition: Vec::new(),
            });
            world.insert_resource(AccumulatedMouseScroll {
                unit: MouseScrollUnit::Line,
                delta: Vec2::new(0.0, -1.0),
            });
            world.insert_resource(PointerCapture::default());
            world.run_system_once(apply_scroll).unwrap();
            world.entity(container).get::<ScrollPosition>().unwrap().0
        };
        assert_eq!(run(None), Vec2::ZERO, "the window cursor must not reach it");
        assert_eq!(
            run(Some(Vec2::new(250.0, 180.0))),
            Vec2::new(0.0, LINE_HEIGHT)
        );
        assert_eq!(
            run(Some(Vec2::splat(-1.0))),
            Vec2::ZERO,
            "parked off-bounds"
        );
    }

    #[test]
    fn ignores_wheel_when_cursor_is_outside_the_container() {
        // In-window but outside the container's rect (x:200..400, y:150..250).
        let (pos, capture) = run(
            Vec2::new(50.0, 50.0),
            Vec2::new(0.0, 30.0),
            Vec2::new(0.0, -1.0),
        );
        assert_eq!(pos, Vec2::new(0.0, 30.0));
        assert!(!capture.wheel_captured);
    }

    #[test]
    fn does_not_claim_wheel_when_content_fits() {
        // A scroll container whose content fits (content 100 == size 100, so the scroll
        // range is empty) under the cursor. The wheel must NOT be consumed: position stays
        // put and the pointer is left un-owned so a world system (e.g. the orbit camera's
        // wheel-zoom behind a transparent, non-overflowing scroll pane) still receives it.
        let (pos, capture) = run_with_content(
            Vec2::new(300.0, 200.0),
            Vec2::ZERO,
            Vec2::new(0.0, -1.0),
            100.0,
        );
        assert_eq!(pos, Vec2::ZERO);
        assert!(
            !capture.wheel_captured,
            "a container with nothing to scroll must not claim the wheel"
        );
    }

    #[test]
    fn wheel_listener_on_top_blocks_ancestor_scroll() {
        // A scroll container with a `WheelListener` child on top of it (the reported
        // bug shape: an `onWheel` box inside a scrollable page). Cursor over the child
        // → `apply_scroll` must yield, leaving the ancestor container un-scrolled. The
        // event itself is emitted separately by `collect_wheel_events`.
        let mut world = World::new();
        let mut window = Window::default();
        window.set_physical_cursor_position(Some(Vec2::new(300.0, 200.0).as_dvec2()));
        world.spawn((window, PrimaryWindow));

        let container = world
            .spawn((
                Node {
                    overflow: Overflow::scroll_y(),
                    ..default()
                },
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, 300.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                ScrollPosition::default(),
            ))
            .id();
        let child = world
            .spawn((
                Node::default(),
                ComputedNode {
                    size: Vec2::new(80.0, 20.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                ScrollPosition::default(),
                WheelListener,
            ))
            .id();
        // Container behind, `onWheel` child in front (topmost-first hits the child).
        world.insert_resource(UiStack {
            uinodes: vec![container, child],
            partition: Vec::new(),
        });
        world.insert_resource(AccumulatedMouseScroll {
            unit: MouseScrollUnit::Line,
            delta: Vec2::new(0.0, -1.0),
        });
        world.insert_resource(PointerCapture::default());
        world.run_system_once(apply_scroll).unwrap();

        assert_eq!(
            world.entity(container).get::<ScrollPosition>().unwrap().0,
            Vec2::ZERO,
            "an onWheel node on top must block its ancestor scroll container"
        );
    }

    /// The post-layout settle: a pinned-to-bottom request (`scrollTop={BIG}`)
    /// clamped against STALE geometry lands short; `settle_controlled_scroll`
    /// re-clamps the raw request with fresh `ComputedNode` values and removes
    /// the marker. This is the "log appends rows + pins to bottom in one
    /// commit" fix.
    #[test]
    fn settle_reclamps_pending_request_with_fresh_geometry() {
        let mut world = World::new();
        // Stale clamp landed at 200 (content was 300); fresh layout says the
        // content grew to 500 → true max 400.
        let container = world
            .spawn((
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, 500.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                ScrollPosition(Vec2::new(0.0, 200.0)),
                PendingControlledScroll(Vec2::new(0.0, 1e9)),
            ))
            .id();
        world.run_system_once(settle_controlled_scroll).unwrap();
        assert_eq!(
            world.entity(container).get::<ScrollPosition>().unwrap().0,
            Vec2::new(0.0, 400.0),
            "the raw request must re-clamp against fresh geometry"
        );
        assert!(
            world
                .entity(container)
                .get::<PendingControlledScroll>()
                .is_none(),
            "the marker is one-shot"
        );
    }

    /// With a scroll transition, the settle corrects the eased *target*, not
    /// the live offset; an already-correct request settles silently.
    #[test]
    fn settle_feeds_transition_target_and_in_range_is_silent() {
        let mut world = World::new();
        let eased = world
            .spawn((
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, 500.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                ScrollPosition(Vec2::new(0.0, 50.0)),
                ScrollTransitionState::default(),
                PendingControlledScroll(Vec2::new(0.0, 1e9)),
            ))
            .id();
        world
            .entity_mut(eased)
            .get_mut::<ScrollTransitionState>()
            .unwrap()
            .target = Vec2::new(0.0, 200.0);
        // In-range request (created node whose raw offset was fine).
        let in_range = world
            .spawn((
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    content_size: Vec2::new(200.0, 500.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                ScrollPosition(Vec2::new(0.0, 120.0)),
                PendingControlledScroll(Vec2::new(0.0, 120.0)),
            ))
            .id();
        world.run_system_once(settle_controlled_scroll).unwrap();
        assert_eq!(
            world
                .entity(eased)
                .get::<ScrollTransitionState>()
                .unwrap()
                .target,
            Vec2::new(0.0, 400.0),
            "easing: the settle corrects the target"
        );
        assert_eq!(
            world.entity(eased).get::<ScrollPosition>().unwrap().0,
            Vec2::new(0.0, 50.0),
            "easing: the live offset is the drive system's job"
        );
        assert_eq!(
            world.entity(in_range).get::<ScrollPosition>().unwrap().0,
            Vec2::new(0.0, 120.0),
            "an in-range request settles to itself"
        );
        assert!(
            world
                .entity(in_range)
                .get::<PendingControlledScroll>()
                .is_none()
        );
    }

    /// Drive `collect_wheel_events` against a single 200×100 `WheelListener` node (id 7)
    /// centered at (300, 200), with one wheel tick of `wheel` in `unit`. Returns the
    /// emitted `wheel` `UiEvent` (if any) and the resulting [`PointerCapture`].
    fn run_wheel(
        cursor: Vec2,
        wheel: Vec2,
        unit: MouseScrollUnit,
    ) -> (Option<UiEvent>, PointerCapture) {
        let mut world = World::new();

        let mut window = Window::default();
        window.set_physical_cursor_position(Some(cursor.as_dvec2()));
        world.spawn((window, PrimaryWindow));

        let (_ops_tx, ops_rx) = crossbeam_channel::unbounded::<Vec<crate::protocol::op::Op>>();
        let (out_tx, mut out_rx) = tokio::sync::mpsc::unbounded_channel::<Outbound>();
        let root = world.spawn_empty().id();
        world.insert_resource(JsBridge::new(ops_rx, out_tx, root));

        let node = world
            .spawn((
                ReactNode(7),
                ComputedNode {
                    size: Vec2::new(200.0, 100.0),
                    inverse_scale_factor: 1.0,
                    ..default()
                },
                UiGlobalTransform::from_translation(Vec2::new(300.0, 200.0)),
                WheelListener,
            ))
            .id();
        world.insert_resource(UiStack {
            uinodes: vec![node],
            partition: Vec::new(),
        });
        world.insert_resource(AccumulatedMouseScroll { unit, delta: wheel });
        world.insert_resource(PointerCapture::default());

        world.run_system_once(collect_wheel_events).unwrap();

        let event = out_rx.try_recv().ok().map(|o| match o {
            Outbound::UiEvent { event } => event,
            other => panic!("expected a UiEvent, got {other:?}"),
        });
        let capture = *world.resource::<PointerCapture>();
        (event, capture)
    }

    #[test]
    fn wheel_over_listener_emits_raw_delta_and_claims() {
        // Cursor over the node; the raw delta rides through untouched (no ScrollStep
        // scaling), tagged with its unit, and the wheel is claimed for the UI.
        let (event, capture) = run_wheel(
            Vec2::new(300.0, 200.0),
            Vec2::new(3.0, -2.0),
            MouseScrollUnit::Line,
        );
        let event = event.expect("a wheel event over the listener");
        assert_eq!(event.id, 7);
        assert_eq!(event.kind, "wheel");
        assert_eq!(event.delta_x, Some(3.0));
        assert_eq!(event.delta_y, Some(-2.0));
        assert_eq!(event.delta_mode.as_deref(), Some("line"));
        // Cursor at the node's center → normalized (0.5, 0.5), absolute = logical cursor.
        assert_eq!(event.x, Some(0.5));
        assert_eq!(event.y, Some(0.5));
        assert_eq!(event.client_x, Some(300.0));
        assert_eq!(event.client_y, Some(200.0));
        assert!(
            capture.wheel_captured,
            "a handled wheel must claim the wheel channel"
        );
        assert!(
            !capture.over_ui,
            "handling the wheel is not a hover claim — `over_ui` stays untouched"
        );
    }

    #[test]
    fn wheel_reports_pixel_unit_for_trackpads() {
        let (event, _) = run_wheel(
            Vec2::new(300.0, 200.0),
            Vec2::new(0.0, 12.0),
            MouseScrollUnit::Pixel,
        );
        assert_eq!(
            event.expect("a wheel event").delta_mode.as_deref(),
            Some("pixel")
        );
    }

    #[test]
    fn wheel_outside_listener_emits_nothing() {
        // In-window but outside the node's rect (x:200..400, y:150..250) → no event, and
        // the wheel is left un-owned so world systems still receive it.
        let (event, capture) = run_wheel(
            Vec2::new(50.0, 50.0),
            Vec2::new(0.0, -1.0),
            MouseScrollUnit::Line,
        );
        assert!(event.is_none(), "no listener under the cursor");
        assert!(!capture.wheel_captured);
    }

    #[test]
    fn zero_wheel_emits_nothing() {
        let (event, capture) =
            run_wheel(Vec2::new(300.0, 200.0), Vec2::ZERO, MouseScrollUnit::Line);
        assert!(event.is_none(), "a zero delta must not emit a wheel event");
        assert!(!capture.wheel_captured);
    }
}