cranpose_app_shell/

shell_input.rs

use cranpose_ui::FocusDirection;

use super::*;

impl<R> SurfaceMut<'_, R>
where
    R: Renderer,
    R::Error: Debug,
{
    fn pointer_event(
        &self,
        kind: PointerEventKind,
        position: Point,
        global_position: Point,
        event_time: PointerEventTime,
    ) -> PointerEvent {
        let screen_position = self.surface().screen_origin.map(|origin| Point {
            x: origin.x + global_position.x,
            y: origin.y + global_position.y,
        });
        let mut event = PointerEvent::new(kind, position, global_position)
            .with_time_ms(event_time.platform_time_ms)
            .with_animation_time_nanos(event_time.animation_time_nanos)
            .with_screen_position(screen_position);
        event.modifiers = self.shell.app.modifiers;
        event
    }

    fn resolve_gesture_targets(
        &self,
        pointer: PointerId,
    ) -> Vec<<<R as Renderer>::Scene as RenderScene>::HitTarget> {
        self.resolve_hit_path(pointer)
    }

    fn resolve_hit_path(
        &self,
        pointer: PointerId,
    ) -> Vec<<<R as Renderer>::Scene as RenderScene>::HitTarget> {
        let Some(node_ids) = self.surface().hit_path_tracker.dispatch_order(pointer) else {
            return Vec::new();
        };

        let scene = self.surface().renderer.scene();
        let targets: Vec<_> = node_ids
            .iter()
            .filter_map(|&id| scene.find_target(id))
            .collect();
        log::trace!(
            target: "cranpose::input",
            "resolve_hit_path pointer={pointer:?} cached={node_ids:?} resolved_count={}",
            targets.len()
        );
        targets
    }

    fn dispatch_targets<I>(&mut self, targets: I, event: PointerEvent, stop_on_consume: bool)
    where
        I: IntoIterator<Item = <<R as Renderer>::Scene as RenderScene>::HitTarget>,
    {
        let mut applier = self.shell.app.composition.applier_mut();
        for target in targets {
            let node_id = target.node_id();
            target.dispatch_with_applier(&mut applier, event.clone());
            log::trace!(
                target: "cranpose::input",
                "dispatch {:?} node={} consumed={} stop_on_consume={}",
                event.kind,
                node_id,
                event.is_consumed(),
                stop_on_consume,
            );
            if stop_on_consume && event.is_consumed() {
                break;
            }
        }
        event.finish_post_dispatch();
    }

    fn dispatch_to_hits(
        &mut self,
        hits: &[<<R as Renderer>::Scene as RenderScene>::HitTarget],
        event: PointerEvent,
    ) -> bool {
        let capture_paths = hits
            .iter()
            .map(cranpose_render_common::HitTestTarget::capture_path)
            .collect::<Vec<_>>();
        let targets = crate::hit_path_tracker::dispatch_order_for_paths(&capture_paths)
            .into_iter()
            .filter_map(|node_id| self.surface().renderer.scene().find_target(node_id))
            .collect::<Vec<_>>();

        self.dispatch_targets(targets, event.clone(), true);

        event.is_consumed()
    }

    /// Sets the device source (touch/mouse/stylus) of the pointer sample that
    /// the platform is about to dispatch. Call this before `set_cursor` /
    /// `pointer_pressed` / `pointer_released` so the resulting `PointerEvent`s
    /// carry the source so consumers can preserve device-specific gesture
    /// details without changing shared pointer UI.
    pub fn set_pointer_source(&mut self, source: PointerSource) {
        self.surface_mut().pointer_source = source;
    }

    /// The device source of the most recent pointer sample.
    pub fn pointer_source(&self) -> PointerSource {
        self.surface().pointer_source
    }

    pub fn set_cursor(&mut self, x: f32, y: f32) -> bool {
        self.set_cursor_at_time(x, y, None)
    }

    /// Like [`set_cursor`](Self::set_cursor), but carries the platform input
    /// timestamp (milliseconds, platform-specific time base) of the sample.
    ///
    /// Platforms that deliver input batched/frame-aligned (Android) must use
    /// this so gesture velocity is computed from real event times instead of
    /// delivery times.
    pub fn set_cursor_at_time(&mut self, x: f32, y: f32, time_ms: Option<i64>) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.set_cursor_at_event_time(x, y, event_time)
    }

    /// Set the cursor using a timestamp already resolved into both clock domains.
    pub fn set_cursor_at_event_time(
        &mut self,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.set_cursor_inner(x, y, event_time)).unwrap_or(false)
        });
        self.route_drag_and_drop();
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "set_cursor ({x:.2},{y:.2}) time_ms={:?} animation_time_nanos={} -> {result}",
            event_time.platform_time_ms,
            event_time.animation_time_nanos,
        );
        result
    }

    fn set_cursor_inner(&mut self, x: f32, y: f32, event_time: PointerEventTime) -> bool {
        self.surface_mut().cursor = (x, y);
        if self.inspector_move(x, y) {
            return true;
        }

        if self.surface().buttons_pressed != PointerButtons::NONE {
            if self.surface().hit_path_tracker.has_path(PointerId::PRIMARY) {
                let targets = self.resolve_gesture_targets(PointerId::PRIMARY);
                if !targets.is_empty() {
                    let event = self
                        .pointer_event(
                            PointerEventKind::Move,
                            Point { x, y },
                            Point { x, y },
                            event_time,
                        )
                        .with_buttons(self.surface().buttons_pressed)
                        .with_source(self.surface().pointer_source);
                    self.dispatch_targets(targets, event, false);
                    return true;
                }

                return false;
            }

            return false;
        }

        let hits = if self.inspector_blocks_pointer(x, y) {
            Vec::new()
        } else {
            self.surface().renderer.scene().hit_test(x, y)
        };
        let new_ids: Vec<NodeId> = hits
            .iter()
            .map(cranpose_render_common::HitTestTarget::node_id)
            .collect();

        let pos = Point { x, y };
        let previously_hovered = self.surface().hovered_nodes.clone();
        for old_id in previously_hovered {
            if !new_ids.contains(&old_id)
                && let Some(target) = self.surface().renderer.scene().find_target(old_id)
            {
                let exit_event = self
                    .pointer_event(PointerEventKind::Exit, pos, pos, event_time)
                    .with_buttons(self.surface().buttons_pressed)
                    .with_source(self.surface().pointer_source);
                self.dispatch_targets(std::iter::once(target), exit_event, false);
            }
        }

        for hit in &hits {
            if !self.surface().hovered_nodes.contains(&hit.node_id()) {
                let enter_event = self
                    .pointer_event(PointerEventKind::Enter, pos, pos, event_time)
                    .with_buttons(self.surface().buttons_pressed)
                    .with_source(self.surface().pointer_source);
                self.dispatch_targets(std::iter::once(hit.clone()), enter_event, false);
            }
        }

        self.surface_mut().hovered_nodes = new_ids;
        self.apply_hovered_pointer_icon(&hits);

        if !hits.is_empty() {
            let event = self
                .pointer_event(PointerEventKind::Move, pos, pos, event_time)
                .with_buttons(self.surface().buttons_pressed)
                .with_source(self.surface().pointer_source);
            self.dispatch_targets(hits, event, true);
            true
        } else {
            false
        }
    }

    /// Activates the identified control using its current semantics and geometry.
    ///
    /// Hidden, disabled, removed and modal-background controls reject activation.
    /// `canvas_key` identifies a drawn child of `node_id`. The action bypasses
    /// overlapping controls and developer overlays without changing pointer capture.
    pub fn accessibility_activate(&mut self, node_id: NodeId, canvas_key: Option<u64>) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.activate_node(node_id, canvas_key, event_time))
                .unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        result
    }

    fn activate_node(
        &mut self,
        node_id: NodeId,
        canvas_key: Option<u64>,
        event_time: PointerEventTime,
    ) -> bool {
        let target = {
            let (app, surface) = self.parts();
            surface
                .semantics_tree_for_input(app)
                .and_then(|tree| activation_target(tree.root(), node_id, canvas_key))
        };
        let (target_id, canvas_bounds) = match target {
            Some(ActivationTarget::Direct(action)) => {
                action.invoke();
                return true;
            }
            Some(ActivationTarget::Edit(node_id)) => {
                self.activate();
                return cranpose_ui::request_focus_from_platform(node_id);
            }
            Some(ActivationTarget::Pointer(node_id, bounds)) => (node_id, bounds),
            None => return false,
        };
        let position =
            self.with_layout_tree(|tree| activation_input(tree?.root(), target_id, canvas_bounds));
        let Some((position, local, handlers)) = position else {
            return false;
        };
        for kind in [PointerEventKind::Down, PointerEventKind::Up] {
            let event = self.pointer_event(kind, local, position, event_time);
            handlers.dispatch_pointer_event(event.clone());
            event.finish_post_dispatch();
        }
        true
    }

    pub fn pointer_pressed(&mut self) -> bool {
        self.pointer_pressed_at_time(None)
    }

    /// Like [`pointer_pressed`](Self::pointer_pressed), but carries the
    /// platform input timestamp (milliseconds) of the press sample.
    pub fn pointer_pressed_at_time(&mut self, time_ms: Option<i64>) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.pointer_pressed_at_event_time(event_time)
    }

    /// Dispatch primary-button down with an already resolved event timestamp.
    pub fn pointer_pressed_at_event_time(&mut self, event_time: PointerEventTime) -> bool {
        let (cursor_x, cursor_y) = self.surface().cursor;
        if self.inspector_press(cursor_x, cursor_y) {
            return true;
        }
        if self.dev_overlay_press(cursor_x, cursor_y) {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.pointer_pressed_inner(event_time)).unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "pointer_pressed time_ms={:?} animation_time_nanos={} -> {result}",
            event_time.platform_time_ms,
            event_time.animation_time_nanos,
        );
        result
    }

    fn pointer_pressed_inner(&mut self, event_time: PointerEventTime) -> bool {
        self.activate();
        self.note_focus_moved_by_keyboard(false);
        self.surface_mut()
            .buttons_pressed
            .insert(PointerButton::Primary);

        let (cursor_x, cursor_y) = self.surface().cursor;
        let mut hits = self.surface().renderer.scene().hit_test(cursor_x, cursor_y);
        if self.surface().pointer_source.is_touch_like()
            && let Some(near) = self
                .surface()
                .renderer
                .scene()
                .hit_test_near(cursor_x, cursor_y)
            && hits.iter().all(|hit| {
                hit.node_id() != near.node_id() && near.capture_path().contains(&hit.node_id())
            })
        {
            hits.insert(0, near);
        }
        if hits.is_empty() {
            self.surface_mut()
                .hit_path_tracker
                .remove_path(PointerId::PRIMARY);
            false
        } else {
            let event = self
                .pointer_event(
                    PointerEventKind::Down,
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    event_time,
                )
                .with_buttons(self.surface().buttons_pressed)
                .with_source(self.surface().pointer_source);

            let mut delivered_capture_paths = Vec::new();
            let (app, surface) = self.parts();
            let mut applier = app.composition.applier_mut();
            for hit in hits {
                let node_id = hit.node_id();
                delivered_capture_paths.push(hit.capture_path());
                hit.dispatch_with_applier(&mut applier, event.clone());
                log::trace!(
                    target: "cranpose::input",
                    "dispatch {:?} node={} consumed={} stop_on_consume=true",
                    event.kind,
                    node_id,
                    event.is_consumed(),
                );
                if event.is_consumed() {
                    break;
                }
            }

            surface
                .hit_path_tracker
                .add_hit_path(PointerId::PRIMARY, delivered_capture_paths);
            log::trace!(
                target: "cranpose::input",
                "pointer_pressed_inner cached_hit_path={:?}",
                surface.hit_path_tracker.get_path(PointerId::PRIMARY),
            );

            true
        }
    }

    pub fn pointer_released(&mut self) -> bool {
        self.pointer_released_at_time(None)
    }

    /// Releases the pointer at the position carried by the platform's release
    /// sample (Android `ACTION_UP`, web `pointerup`/`touchend`).
    ///
    /// The cursor is moved to `(x, y)` WITHOUT dispatching a Move event, then
    /// the Up event is dispatched at that position. Platforms whose release
    /// events carry their own coordinates must use this instead of
    /// `set_cursor* + pointer_released*`: lift-off samples routinely roll back
    /// a few dp against the travel direction as the finger peels off, and
    /// feeding that jitter into gesture velocity trackers as a final Move
    /// sample can flip the sign of the computed fling velocity (flings that
    /// suddenly go the opposite way). Jetpack Compose likewise never feeds the
    /// up sample into velocity tracking.
    pub fn pointer_released_at_position(&mut self, x: f32, y: f32) -> bool {
        self.pointer_released_at_position_time(x, y, None)
    }

    /// Like [`pointer_released_at_position`](Self::pointer_released_at_position),
    /// but carries the platform input timestamp (milliseconds) of the release
    /// sample.
    pub fn pointer_released_at_position_time(
        &mut self,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.pointer_released_at_position_event_time(x, y, event_time)
    }

    /// Release at a position with an already resolved event timestamp.
    pub fn pointer_released_at_position_event_time(
        &mut self,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| {
                self.surface_mut().cursor = (x, y);
                self.pointer_released_inner(event_time)
            })
            .unwrap_or(false)
        });
        self.route_drag_and_drop();
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "pointer_released_at_position ({x:.2},{y:.2}) time_ms={:?} animation_time_nanos={} -> {result}",
            event_time.platform_time_ms,
            event_time.animation_time_nanos,
        );
        result
    }

    /// Like [`pointer_released`](Self::pointer_released), but carries the
    /// platform input timestamp (milliseconds) of the release sample.
    pub fn pointer_released_at_time(&mut self, time_ms: Option<i64>) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.pointer_released_at_event_time(event_time)
    }

    /// Dispatch primary-button up with an already resolved event timestamp.
    pub fn pointer_released_at_event_time(&mut self, event_time: PointerEventTime) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.pointer_released_inner(event_time)).unwrap_or(false)
        });
        self.route_drag_and_drop();
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "pointer_released time_ms={:?} animation_time_nanos={} -> {result}",
            event_time.platform_time_ms,
            event_time.animation_time_nanos,
        );
        result
    }

    fn pointer_released_inner(&mut self, event_time: PointerEventTime) -> bool {
        if self.surface_mut().inspector.release_pointer() {
            return true;
        }
        self.release_app_pointer(event_time)
    }

    fn release_app_pointer(&mut self, event_time: PointerEventTime) -> bool {
        self.surface_mut()
            .buttons_pressed
            .remove(PointerButton::Primary);
        let corrected_buttons = self.surface().buttons_pressed;
        let targets = self.resolve_gesture_targets(PointerId::PRIMARY);

        self.surface_mut()
            .hit_path_tracker
            .remove_path(PointerId::PRIMARY);

        if !targets.is_empty() {
            let event = self
                .pointer_event(
                    PointerEventKind::Up,
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    event_time,
                )
                .with_buttons(corrected_buttons)
                .with_source(self.surface().pointer_source);

            self.dispatch_targets(targets, event, false);
            true
        } else {
            false
        }
    }

    /// Dispatches an event for a secondary pointer (`pointer_id != 0`).
    ///
    /// Multi-touch gestures act on the element the first finger grabbed, so
    /// secondary pointers are routed to the hit path captured by the primary
    /// pointer's Down. They carry no hover/click semantics and are ignored
    /// when no primary gesture is in progress.
    ///
    /// Returns `true` when the event was dispatched to at least one target.
    pub fn secondary_pointer_pressed(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.dispatch_secondary_pointer(PointerEventKind::Down, pointer_id, x, y, event_time)
    }

    /// Move counterpart of [`secondary_pointer_pressed`](Self::secondary_pointer_pressed).
    pub fn secondary_pointer_moved(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.dispatch_secondary_pointer(PointerEventKind::Move, pointer_id, x, y, event_time)
    }

    /// Release counterpart of [`secondary_pointer_pressed`](Self::secondary_pointer_pressed).
    pub fn secondary_pointer_released(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(time_ms);
        self.dispatch_secondary_pointer(PointerEventKind::Up, pointer_id, x, y, event_time)
    }

    fn dispatch_secondary_pointer(
        &mut self,
        kind: PointerEventKind,
        pointer_id: u64,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        if pointer_id == 0 {
            log::warn!(
                target: "cranpose::input",
                "secondary pointer dispatch called with the primary pointer id"
            );
            return false;
        }

        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| {
                if !self.surface().hit_path_tracker.has_path(PointerId::PRIMARY) {
                    return false;
                }
                let targets = self.resolve_gesture_targets(PointerId::PRIMARY);
                if targets.is_empty() {
                    return false;
                }
                let pos = Point { x, y };
                let event = self
                    .pointer_event(kind, pos, pos, event_time)
                    .with_buttons(self.surface().buttons_pressed)
                    .with_id(pointer_id)
                    .with_source(self.surface().pointer_source);
                self.dispatch_targets(targets, event, false);
                true
            })
            .unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "secondary_pointer {kind:?} id={pointer_id} ({x:.2},{y:.2}) time_ms={:?} animation_time_nanos={} -> {result}",
            event_time.platform_time_ms,
            event_time.animation_time_nanos,
        );
        result
    }

    /// Dispatches a discrete zoom step (desktop ctrl+wheel, browser pinch)
    /// to the pointer handlers under the cursor.
    ///
    /// `zoom_factor` is multiplicative: `> 1.0` zooms in, `< 1.0` zooms out.
    /// Returns `true` if a handler consumed the event.
    pub fn pointer_zoomed(&mut self, zoom_factor: f32) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.pointer_zoomed_inner(zoom_factor, event_time))
                .unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "pointer_zoomed factor={zoom_factor:.4} -> {result}"
        );
        result
    }

    fn pointer_zoomed_inner(&mut self, zoom_factor: f32, event_time: PointerEventTime) -> bool {
        if !zoom_factor.is_finite() || zoom_factor <= 0.0 || zoom_factor == 1.0 {
            return false;
        }

        let hits = self
            .surface()
            .renderer
            .scene()
            .hit_test(self.surface().cursor.0, self.surface().cursor.1);
        if hits.is_empty() {
            return false;
        }

        let pos = Point {
            x: self.surface().cursor.0,
            y: self.surface().cursor.1,
        };
        let event = self
            .pointer_event(PointerEventKind::Zoom, pos, pos, event_time)
            .with_buttons(self.surface().buttons_pressed)
            .with_zoom_delta(zoom_factor)
            .with_source(self.surface().pointer_source);

        self.dispatch_to_hits(&hits, event)
    }

    /// Dispatches one mouse-wheel / trackpad sample through the whole wheel
    /// policy, and returns `true` when something consumed it.
    ///
    /// This is the single entry point every host with a wheel calls, after
    /// placing the cursor. A wheel sample is not just a scroll — it is whichever
    /// of four things the modifiers and the tree make it, in this order:
    ///
    /// 1. **Zoom** when ctrl is held. That is the desktop convention and the
    ///    way browsers deliver a trackpad pinch, so both arrive here as the
    ///    same gesture.
    /// 2. **Rotary**, offered to [`rotary_scrolled`](Self::rotary_scrolled)
    ///    before anything else can take it, so the Wear OS crown stack is
    ///    developable on a machine with a wheel. Nothing consumes rotary unless
    ///    the app opts in via `Modifier::on_rotary_scroll_event` or
    ///    [`set_on_rotary_scroll`](Self::set_on_rotary_scroll), so ordinary
    ///    scrolling is unaffected.
    /// 3. **Horizontal scroll** when alt is held on a wheel that only reports a
    ///    vertical axis.
    /// 4. **Scroll**, to the hovered scrollable.
    ///
    /// Hosts must not re-implement this order. Doing so is how the browser
    /// ended up scrolling backwards and never delivering rotary at all: the
    /// policy lived in the desktop event loop, and the second host that grew a
    /// wheel reimplemented the parts of it that were obvious from the outside.
    pub fn wheel_scrolled(&mut self, wheel: crate::WheelScroll) -> bool {
        if self.inspector_scroll(wheel.delta.y) {
            return true;
        }
        if wheel.is_zoom() {
            let zoom_factor = wheel.zoom_factor();
            log::trace!(
                target: "cranpose::input",
                "wheel zoom factor={zoom_factor:.4}"
            );
            return self.pointer_zoomed(zoom_factor);
        }

        let rotary =
            RotaryScrollEvent::from_wheel_pixels(wheel.delta.y, wheel.delta.x, wheel.uptime_millis);
        if self.rotary_scrolled(rotary) {
            return true;
        }

        let delta = wheel.scroll_delta();
        log::trace!(
            target: "cranpose::input",
            "wheel delta ({:.2},{:.2}) alt={}",
            delta.x,
            delta.y,
            wheel.modifiers.alt
        );
        self.pointer_scrolled(delta.x, delta.y)
    }

    /// Dispatches a mouse wheel / trackpad scroll event to hovered pointer handlers.
    ///
    /// Returns `true` if a handler consumed the event.
    ///
    /// This is the last step of the wheel policy, not its entry point: hosts
    /// call [`wheel_scrolled`](Self::wheel_scrolled), which reaches here once
    /// zoom and rotary have declined the sample.
    pub fn pointer_scrolled(&mut self, delta_x: f32, delta_y: f32) -> bool {
        if self.inspector_scroll(delta_y) {
            return true;
        }
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.pointer_scrolled_inner(delta_x, delta_y, event_time))
                .unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "pointer_scrolled ({delta_x:.2},{delta_y:.2}) -> {result}"
        );
        result
    }

    fn pointer_scrolled_inner(
        &mut self,
        delta_x: f32,
        delta_y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        if delta_x.abs() <= f32::EPSILON && delta_y.abs() <= f32::EPSILON {
            return false;
        }

        let hits = self
            .surface()
            .renderer
            .scene()
            .hit_test(self.surface().cursor.0, self.surface().cursor.1);
        if hits.is_empty() {
            return false;
        }

        let event = self
            .pointer_event(
                PointerEventKind::Scroll,
                Point {
                    x: self.surface().cursor.0,
                    y: self.surface().cursor.1,
                },
                Point {
                    x: self.surface().cursor.0,
                    y: self.surface().cursor.1,
                },
                event_time,
            )
            .with_buttons(self.surface().buttons_pressed)
            .with_scroll_delta(Point {
                x: delta_x,
                y: delta_y,
            })
            .with_source(self.surface().pointer_source);

        self.dispatch_to_hits(&hits, event)
    }

    /// Installs the window-level rotary (Wear OS crown / rotating bezel)
    /// handler — the low-level escape hatch.
    ///
    /// The handler runs only after the routed modifier chain has declined the
    /// event (see [`rotary_scrolled`](Self::rotary_scrolled)), so an app that
    /// draws everything into a single canvas receives every rotary delta
    /// without registering a focus target or a modifier. Returning `true`
    /// reports the event as consumed to the platform.
    ///
    /// Passing a new handler replaces the previous one.
    pub fn set_on_rotary_scroll<F>(&mut self, handler: F)
    where
        F: Fn(RotaryScrollEvent) -> bool + 'static,
    {
        self.surface_mut().on_rotary_scroll = Some(Rc::new(handler));
    }

    /// Removes the window-level rotary handler, if one is installed.
    pub fn clear_on_rotary_scroll(&mut self) {
        self.surface_mut().on_rotary_scroll = None;
    }

    /// Dispatches a rotary scroll expressed in raw detents (Android
    /// `AXIS_SCROLL`), converting to pixels with the configured scroll factor.
    ///
    /// Applies Compose's sign convention: a positive detent value (crown turned
    /// up/away) produces a negative `vertical_scroll_pixels`.
    pub fn rotary_scrolled_by_detents(&mut self, detents: f32, uptime_millis: u64) -> bool {
        let factor = self.shell.app.rotary_scroll_factor;
        self.rotary_scrolled(RotaryScrollEvent::from_detents(
            detents,
            factor,
            factor,
            uptime_millis,
        ))
    }

    /// Dispatches a rotary scroll event (Wear OS crown, Galaxy Watch bezel, or
    /// a desktop mouse wheel standing in for one during development).
    ///
    /// Routing mirrors Compose's `RotaryInputModifierNode` contract:
    ///
    /// 1. Resolve the target chain. When a focus target is registered
    ///    (`cranpose_ui::focus_dispatch::active_focus_target`) and still
    ///    exists in the current scene, rotary uses the focus target's capture
    ///    path. Otherwise, rotary uses the hit-test chain under the cursor.
    /// 2. **Capture pass**, root to leaf, invoking `on_pre_rotary_scroll_event`
    ///    handlers.
    /// 3. **Bubble pass**, leaf to root, invoking `on_rotary_scroll_event`
    ///    handlers.
    /// 4. If still unconsumed, the window-level handler installed by
    ///    [`set_on_rotary_scroll`](Self::set_on_rotary_scroll).
    ///
    /// The first handler returning `true` consumes the event and stops every
    /// remaining step. Returns `true` when the event was consumed.
    pub fn rotary_scrolled(&mut self, event: RotaryScrollEvent) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let result = app_context.enter(|| {
            run_in_mutable_snapshot(|| self.rotary_scrolled_inner(event)).unwrap_or(false)
        });
        if result {
            self.mark_dirty();
        }
        log::trace!(
            target: "cranpose::input",
            "rotary_scrolled v={:.2} h={:.2} uptime={} -> {result}",
            event.vertical_scroll_pixels,
            event.horizontal_scroll_pixels,
            event.uptime_millis,
        );
        result
    }

    fn rotary_scrolled_inner(&mut self, rotary: RotaryScrollEvent) -> bool {
        if rotary.is_empty() {
            return false;
        }

        let bubble_order = self.rotary_dispatch_order();
        let position = Point {
            x: self.surface().cursor.0,
            y: self.surface().cursor.1,
        };

        if !bubble_order.is_empty() {
            let capture_targets = bubble_order
                .iter()
                .rev()
                .filter_map(|&node_id| self.surface().renderer.scene().find_target(node_id))
                .collect::<Vec<_>>();
            let mut capture_event =
                PointerEvent::rotary(PointerEventKind::RotaryScrollPre, rotary, position);
            capture_event.modifiers = self.shell.app.modifiers;
            self.dispatch_targets(capture_targets, capture_event.clone(), true);
            if capture_event.is_consumed() {
                return true;
            }

            let bubble_targets = bubble_order
                .iter()
                .filter_map(|&node_id| self.surface().renderer.scene().find_target(node_id))
                .collect::<Vec<_>>();
            let mut bubble_event =
                PointerEvent::rotary(PointerEventKind::RotaryScroll, rotary, position);
            bubble_event.modifiers = self.shell.app.modifiers;
            self.dispatch_targets(bubble_targets, bubble_event.clone(), true);
            if bubble_event.is_consumed() {
                return true;
            }
        }

        if let Some(handler) = self.surface().on_rotary_scroll.clone() {
            return handler(rotary);
        }

        false
    }

    fn rotary_dispatch_order(&self) -> Vec<NodeId> {
        if let Some(focused) = cranpose_ui::active_focus_target()
            && let Some(target) = self.surface().renderer.scene().find_target(focused)
        {
            let path = target.capture_path();
            if !path.is_empty() {
                return crate::hit_path_tracker::dispatch_order_for_paths(&[path]);
            }
        }

        let hits = self
            .surface()
            .renderer
            .scene()
            .hit_test(self.surface().cursor.0, self.surface().cursor.1);
        if hits.is_empty() {
            return Vec::new();
        }
        let capture_paths = hits
            .iter()
            .map(cranpose_render_common::HitTestTarget::capture_path)
            .collect::<Vec<_>>();
        crate::hit_path_tracker::dispatch_order_for_paths(&capture_paths)
    }

    /// Cancels any active gesture, dispatching Cancel events to cached targets.
    /// Call this when:
    /// - Window loses focus
    /// - Mouse leaves window while button pressed
    /// - Any other gesture abort scenario
    pub fn cancel_gesture(&mut self) {
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        let _ = app_context.enter(|| {
            run_in_mutable_snapshot(|| {
                self.cancel_gesture_inner(event_time);
            })
        });
        self.route_drag_and_drop();
    }

    fn route_drag_and_drop(&mut self) {
        let app_context = Rc::clone(&self.shell.app.app_context);
        let source = self.index;
        let shell = &mut *self.shell;
        let routed = app_context.enter(|| {
            run_in_mutable_snapshot(|| {
                app_context
                    .drag_and_drop()
                    .route(|point| shell.drag_and_drop_target_at(point, source))
            })
            .unwrap_or(false)
        });
        if routed {
            shell.mark_all_dirty();
        }
    }

    /// Ends the gesture only when the pointer leaving really ended it.
    ///
    /// A held button belongs to the surface that received the press until
    /// the release: a window drawn over the cursor, or a drag carried past
    /// an edge, both leave the press where it started and deliver the
    /// release there too. Cancelling on either would drop a gesture the
    /// user has not finished, so a pressed pointer is left alone and only
    /// an idle one cancels.
    pub fn cancel_gesture_unless_pressed(&mut self) {
        if self.surface().buttons_pressed != PointerButtons::NONE
            || self.surface().inspector.pointer_captured
        {
            return;
        }
        self.cancel_gesture();
    }

    fn cancel_gesture_inner(&mut self, event_time: PointerEventTime) {
        self.surface_mut().inspector.cancel_pointer();
        let targets = self.resolve_gesture_targets(PointerId::PRIMARY);

        self.surface_mut().hit_path_tracker.clear();
        self.surface_mut().buttons_pressed = PointerButtons::NONE;

        if !targets.is_empty() {
            let event = self
                .pointer_event(
                    PointerEventKind::Cancel,
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    Point {
                        x: self.surface().cursor.0,
                        y: self.surface().cursor.1,
                    },
                    event_time,
                )
                .with_source(self.surface().pointer_source);

            self.dispatch_targets(targets, event, false);
        }

        let pos = Point {
            x: self.surface().cursor.0,
            y: self.surface().cursor.1,
        };
        let hovered_nodes = self.surface().hovered_nodes.clone();
        for node_id in hovered_nodes {
            if let Some(target) = self.surface().renderer.scene().find_target(node_id) {
                let exit_event = self
                    .pointer_event(PointerEventKind::Exit, pos, pos, event_time)
                    .with_source(self.surface().pointer_source);
                self.dispatch_targets(std::iter::once(target), exit_event, false);
            }
        }
        self.surface_mut().hovered_nodes.clear();
        self.surface().pointer_icon.set(PointerIcon::DEFAULT);
    }

    fn apply_hovered_pointer_icon(
        &self,
        hits: &[<<R as Renderer>::Scene as RenderScene>::HitTarget],
    ) {
        let icon = hits
            .iter()
            .find_map(HitTestTarget::pointer_icon)
            .unwrap_or(PointerIcon::DEFAULT);
        self.surface().pointer_icon.set(icon);
    }

    fn on_focus_key(&mut self, event: &KeyEvent) -> bool {
        if !plain_key_down(event) || event.key_code != KeyCode::Tab {
            return false;
        }
        self.on_group_navigation_key(event)
    }

    fn on_group_navigation_key(&mut self, event: &KeyEvent) -> bool {
        let focused = cranpose_ui::active_focus_target();
        let target = self.with_layout_tree(|tree| {
            cranpose_ui::keyboard_focus_target(
                tree?,
                focused,
                event.key_code,
                event.modifiers.shift,
            )
        });
        let Some(target) = target else {
            return false;
        };
        let moved =
            run_in_mutable_snapshot(|| cranpose_ui::request_focus_from_platform(target.node_id))
                .unwrap_or(false);
        if moved {
            self.mark_dirty();
            self.note_focus_moved_by_keyboard(true);
            if target.activate {
                self.on_activation_key(&KeyEvent::key_down(KeyCode::Space, " "));
            }
        }
        moved
    }

    fn on_activation_key(&mut self, event: &KeyEvent) -> bool {
        if !plain_key_down(event)
            || !matches!(event.key_code, KeyCode::Enter | KeyCode::Space)
            || cranpose_ui::text_field_focus::has_focused_field()
        {
            return false;
        }
        let Some(focused) = cranpose_ui::active_focus_target() else {
            return false;
        };
        let activated = self.accessibility_activate(focused, None);
        self.note_focus_moved_by_keyboard(true);
        activated
    }

    fn on_arrow_key(&mut self, event: &KeyEvent) -> bool {
        if !plain_key_down(event) || cranpose_ui::text_field_focus::has_focused_field() {
            return false;
        }
        if self.on_group_navigation_key(event) {
            return true;
        }
        let direction = match event.key_code {
            KeyCode::ArrowLeft => FocusDirection::Left,
            KeyCode::ArrowRight => FocusDirection::Right,
            KeyCode::ArrowUp => FocusDirection::Up,
            KeyCode::ArrowDown => FocusDirection::Down,
            _ => return false,
        };
        let Some(focused) = cranpose_ui::active_focus_target() else {
            return false;
        };
        let order = self.with_layout_tree(|layout_tree| {
            let layout_tree = layout_tree?;
            let group = cranpose_ui::selectable_group_of(layout_tree, focused)?;
            Some(cranpose_ui::collect_focus_order_under(layout_tree, group))
        });
        order.is_some_and(|order| self.move_focus_in_order(order, direction))
    }

    fn note_focus_moved_by_keyboard(&mut self, keyboard: bool) {
        if cranpose_ui::set_keyboard_focus_visible(keyboard) {
            cranpose_ui::request_render_invalidation();
            self.mark_dirty();
        }
    }

    fn on_escape_key(&mut self, event: &KeyEvent) -> bool {
        if event.event_type != KeyEventType::KeyDown || event.key_code != KeyCode::Escape {
            return false;
        }
        self.dismiss_top_modal_in_context()
    }

    /// Asks the innermost open dialog or popup to close, the way the platform
    /// back gesture does. Answers whether one was open to take the request.
    pub fn dismiss_top_modal(&mut self) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.dismiss_top_modal_in_context())
    }

    fn dismiss_top_modal_in_context(&mut self) -> bool {
        let closed = run_in_mutable_snapshot(|| {
            if cranpose_ui::modal_depth() > 0 {
                cranpose_ui::dispatch_modal_back()
            } else {
                cranpose_ui::dismiss_top_popup()
            }
        })
        .unwrap_or(false);
        if closed {
            self.mark_dirty();
        }
        closed
    }

    /// Publishes the focus order layout left behind and moves focus one step.
    /// Answers whether focus moved.
    pub fn move_focus_in_context(&mut self, direction: FocusDirection) -> bool {
        let order = self.with_layout_tree(|layout_tree| {
            layout_tree
                .map(cranpose_ui::collect_focus_order)
                .unwrap_or_default()
        });
        self.move_focus_in_order(order, direction)
    }

    fn move_focus_in_order(
        &mut self,
        order: Vec<cranpose_ui::FocusEntry>,
        direction: FocusDirection,
    ) -> bool {
        cranpose_ui::set_focus_order(order);
        let moved = run_in_mutable_snapshot(|| cranpose_ui::FocusManager.move_focus(direction))
            .unwrap_or(false);
        if moved {
            self.mark_dirty();
            self.note_focus_moved_by_keyboard(true);
        }
        moved
    }

    pub fn on_key_event(&mut self, event: &KeyEvent) -> bool {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            let handled = self.on_key_event_inner(event);
            self.run_requested_focus_move();
            handled
        })
    }

    /// Makes the focus move a keyboard action asked for during the event.
    fn run_requested_focus_move(&mut self) {
        if let Some(direction) = cranpose_ui::take_requested_focus_move() {
            self.move_focus_in_context(direction);
        }
    }

    fn on_key_event_inner(&mut self, event: &KeyEvent) -> bool {
        if self.inspector_key(event) {
            return true;
        }
        let root = self.key_event_root();
        if root.is_none() && self.id() != RootId::Primary {
            return false;
        }
        let route =
            cranpose_ui::KeyEventRoute::new(&mut self.shell.app.composition.applier_mut(), root);
        if self.dispatch_modifier_key(&route, event, true) {
            return true;
        }
        if route.focus_is_current() && self.on_focused_key_event(event) {
            return true;
        }
        if self.dispatch_modifier_key(&route, event, false) {
            return true;
        }
        if !route.focus_is_current() || cranpose_ui::text_field_focus::has_focused_field() {
            return false;
        }
        let handled = run_in_mutable_snapshot(|| cranpose_ui::dispatch_unhandled_key_event(event))
            .unwrap_or(false);
        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }
        handled
    }

    fn dispatch_modifier_key(
        &mut self,
        route: &cranpose_ui::KeyEventRoute,
        event: &KeyEvent,
        preview: bool,
    ) -> bool {
        let handled = run_in_mutable_snapshot(|| {
            let mut applier = self.shell.app.composition.applier_mut();
            if preview {
                route.dispatch_preview(&mut applier, event)
            } else {
                route.dispatch_bubble(&mut applier, event)
            }
        })
        .unwrap_or(false);
        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }
        handled
    }

    fn key_event_root(&self) -> Option<cranpose_core::NodeId> {
        self.surface()
            .modal_focus
            .last()
            .map(|entry| entry.0)
            .or_else(|| self.surface().root)
            .or_else(|| match self.id() {
                RootId::Primary => self.shell.app.composition.root(),
                RootId::Window(_) => None,
            })
    }

    fn receives_focused_input(&mut self) -> bool {
        let root = self.key_event_root();
        cranpose_ui::KeyEventRoute::contains_focus(
            &mut self.shell.app.composition.applier_mut(),
            root,
        )
    }

    fn on_focused_key_event(&mut self, event: &KeyEvent) -> bool {
        use KeyEventType::KeyDown;

        if event.event_type == KeyDown && event.modifiers.command_or_ctrl() {
            #[cfg(all(
                feature = "clipboard-native",
                not(target_arch = "wasm32"),
                not(target_os = "android"),
                not(target_os = "ios")
            ))]
            {
                match event.key_code {
                    KeyCode::C => {
                        if let Some(text) = self.on_copy_inner() {
                            cranpose_ui::clipboard_session::clipboard_write_text(&text);
                            return true;
                        }
                    }
                    KeyCode::X => {
                        if let Some(text) = self.on_cut_inner() {
                            cranpose_ui::clipboard_session::clipboard_write_text(&text);
                            self.mark_dirty();
                            self.shell.app.request_layout_pass();
                            return true;
                        }
                    }
                    KeyCode::V => {
                        if let Some(text) = cranpose_ui::clipboard_session::clipboard_read_text()
                            && self.on_paste_inner(&text)
                        {
                            return true;
                        }
                    }
                    _ => {}
                }
            }
        }

        if self.on_focus_key(event) {
            return true;
        }

        if self.on_escape_key(event) {
            return true;
        }

        if self.on_activation_key(event) || self.on_arrow_key(event) {
            return true;
        }

        let handled =
            run_in_mutable_snapshot(|| cranpose_ui::text_field_focus::dispatch_key_event(event))
                .unwrap_or(false);

        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        handled
    }

    /// Handles paste event from platform clipboard.
    /// Returns `true` if a focused text field in this surface consumed the paste.
    pub fn on_paste(&mut self, text: &str) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.on_paste_inner(text))
    }

    fn on_paste_inner(&mut self, text: &str) -> bool {
        if !self.receives_focused_input() {
            return false;
        }
        let handled =
            run_in_mutable_snapshot(|| cranpose_ui::text_field_focus::dispatch_paste(text))
                .unwrap_or(false);

        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        handled
    }

    /// Handles copy request from platform.
    /// Returns the selected text from this surface's focused field, or `None`.
    pub fn on_copy(&mut self) -> Option<String> {
        let app_context = Rc::clone(&self.shell.app.app_context);
        if self.inspector_owns_keyboard() {
            return None;
        }
        app_context.enter(|| self.on_copy_inner())
    }

    fn on_copy_inner(&mut self) -> Option<String> {
        if !self.receives_focused_input() {
            return None;
        }
        cranpose_ui::text_field_focus::dispatch_copy()
    }

    /// Handles cut request from platform.
    /// Returns the cut text from this surface's focused field, or `None`.
    pub fn on_cut(&mut self) -> Option<String> {
        let _event_handler = enter_event_handler_scope();
        if self.inspector_owns_keyboard() {
            return None;
        }
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.on_cut_inner())
    }

    fn on_cut_inner(&mut self) -> Option<String> {
        if !self.receives_focused_input() {
            return None;
        }
        let text =
            run_in_mutable_snapshot(cranpose_ui::text_field_focus::dispatch_cut).unwrap_or(None);

        if text.is_some() {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        text
    }

    /// Handles IME preedit (composition) events.
    /// Called when the input method is composing text (e.g., typing CJK characters).
    ///
    /// - `text`: The current preedit text (empty to clear composition state)
    /// - `cursor`: Optional cursor position within the preedit text (start, end)
    ///
    /// Returns `true` if a text field consumed the event.
    pub fn on_ime_preedit(&mut self, text: &str, cursor: Option<(usize, usize)>) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.on_ime_preedit_inner(text, cursor))
    }

    fn on_ime_preedit_inner(&mut self, text: &str, cursor: Option<(usize, usize)>) -> bool {
        if !self.receives_focused_input() {
            return false;
        }
        let handled = run_in_mutable_snapshot(|| {
            cranpose_ui::text_field_focus::dispatch_ime_preedit(text, cursor)
        })
        .unwrap_or(false);

        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        handled
    }

    /// Finishes the active IME composition, keeping the composed text as
    /// committed text (Android `finishComposingText` semantics).
    /// Returns `true` if a text field consumed the event.
    pub fn on_ime_finish_composing(&mut self) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.on_ime_finish_composing_inner())
    }

    fn on_ime_finish_composing_inner(&mut self) -> bool {
        if !self.receives_focused_input() {
            return false;
        }
        let handled =
            run_in_mutable_snapshot(cranpose_ui::text_field_focus::dispatch_ime_finish_composing)
                .unwrap_or(false);

        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        handled
    }

    /// Runs the focused field's keyboard action, as the software keyboard's
    /// action key asks: Android's editor action, iOS's return key, the web
    /// editor's Enter. [`ImeAction::Default`](cranpose_ui::ImeAction::Default)
    /// stands for the field's own action. Returns `true` if a text field
    /// handled it.
    pub fn on_ime_action(&mut self, action: cranpose_ui::ImeAction) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            if !self.receives_focused_input() {
                return false;
            }
            let handled = run_in_mutable_snapshot(|| {
                cranpose_ui::text_field_focus::dispatch_ime_action(action)
            })
            .unwrap_or(false);
            if handled {
                self.mark_dirty();
                self.shell.app.request_layout_pass();
            }
            self.run_requested_focus_move();
            handled
        })
    }

    /// Marks existing text in the focused field as the composing region
    /// without changing it (Android `setComposingRegion` semantics). Offsets
    /// are UTF-8 bytes. Returns `true` if a text field consumed the event.
    pub fn on_ime_set_composing_region(&mut self, start_bytes: usize, end_bytes: usize) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            if !self.receives_focused_input() {
                return false;
            }
            let handled = run_in_mutable_snapshot(|| {
                cranpose_ui::text_field_focus::dispatch_ime_set_composing_region(
                    start_bytes,
                    end_bytes,
                )
            })
            .unwrap_or(false);

            if handled {
                self.mark_dirty();
                self.shell.app.request_layout_pass();
            }

            handled
        })
    }

    /// Moves the focused field's selection/caret to `[start_bytes, end_bytes)`
    /// without editing text (Android `InputConnection.setSelection`; the path
    /// Gboard's spacebar-swipe uses to scrub the cursor). Offsets are UTF-8
    /// bytes. Returns `true` if a text field consumed the event.
    pub fn on_ime_set_selection(&mut self, start_bytes: usize, end_bytes: usize) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            if !self.receives_focused_input() {
                return false;
            }
            let handled = run_in_mutable_snapshot(|| {
                cranpose_ui::text_field_focus::dispatch_ime_set_selection(start_bytes, end_bytes)
            })
            .unwrap_or(false);

            if handled {
                self.mark_dirty();
            }

            handled
        })
    }

    /// Returns a snapshot of the focused text field's editable state for
    /// platform IMEs (text, selection and composition in UTF-8 bytes), or
    /// `None` when this surface has no focused text field.
    pub fn ime_editor_state(&mut self) -> Option<cranpose_ui::text_field_focus::ImeEditorState> {
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            self.receives_focused_input()
                .then(cranpose_ui::text_field_focus::focused_editor_state)
                .flatten()
        })
    }

    /// Window-space caret geometry of the focused field for coordinate-based
    /// platform text input (iOS trackpad cursor + tap-to-position), or `None`
    /// when this surface has no focused text field.
    pub fn ime_caret_geometry(
        &mut self,
    ) -> Option<cranpose_ui::text_field_focus::ImeCaretGeometry> {
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            self.receives_focused_input()
                .then(cranpose_ui::text_field_focus::focused_caret_geometry)
                .flatten()
        })
    }

    /// Whether the focused text field holds a secret, as
    /// `Modifier::password()` marks one. Only the semantics of the field's
    /// own node are read, so no semantics tree is built, and the answer holds
    /// with semantics off. A platform gives such a field a protected editor,
    /// which a software keyboard neither learns from nor suggests for.
    /// `false` when this surface has no focused text field.
    pub fn ime_field_is_password(&mut self) -> bool {
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            let Some(field) = self
                .receives_focused_input()
                .then(cranpose_ui::text_field_focus::focused_field_target)
                .flatten()
            else {
                return false;
            };
            let mut applier = self.shell.app.composition.applier_mut();
            applier
                .with_node::<LayoutNode, _>(field, |node| node.semantics_configuration())
                .or_else(|_| {
                    applier.with_node::<SubcomposeLayoutNode, _>(field, |node| {
                        node.semantics_configuration()
                    })
                })
                .ok()
                .flatten()
                .is_some_and(|config| config.password)
        })
    }

    /// Clears text-field focus (used by platform IME actions such as
    /// Android's Done). The focus-loss notification hides the soft keyboard.
    pub fn clear_text_field_focus(&mut self) {
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| {
            if self.receives_focused_input() {
                cranpose_ui::text_field_focus::clear_focus();
                self.mark_dirty();
                self.shell.app.request_layout_pass();
            }
        });
    }

    /// Handles IME delete-surrounding events.
    /// Returns `true` if a text field consumed the event.
    pub fn on_ime_delete_surrounding(&mut self, before_bytes: usize, after_bytes: usize) -> bool {
        if self.inspector_owns_keyboard() {
            return true;
        }
        let _event_handler = enter_event_handler_scope();
        let app_context = Rc::clone(&self.shell.app.app_context);
        app_context.enter(|| self.on_ime_delete_surrounding_inner(before_bytes, after_bytes))
    }

    fn on_ime_delete_surrounding_inner(&mut self, before_bytes: usize, after_bytes: usize) -> bool {
        if !self.receives_focused_input() {
            return false;
        }
        let handled = run_in_mutable_snapshot(|| {
            cranpose_ui::text_field_focus::dispatch_delete_surrounding(before_bytes, after_bytes)
        })
        .unwrap_or(false);

        if handled {
            self.mark_dirty();
            self.shell.app.request_layout_pass();
        }

        handled
    }
}

impl<R> AppShell<R>
where
    R: Renderer,
    R::Error: Debug,
{
    /// Sets the keyboard modifiers held right now, so the platform's live
    /// modifier state (winit's `ModifiersChanged`, a DOM event's
    /// `shiftKey`/`ctrlKey`/`altKey`/`metaKey`) reaches every `PointerEvent`
    /// the shell dispatches from here on -- the same state the wheel path
    /// already carries via [`WheelScroll::with_modifiers`](crate::WheelScroll::with_modifiers).
    /// A platform that never calls this leaves pointer events reporting
    /// `None` (see [`PointerEvent::modifiers`]) rather than a silently wrong
    /// "nothing held".
    pub fn set_modifiers(&mut self, modifiers: Modifiers) {
        self.app.modifiers = Some(modifiers);
    }

    /// The keyboard modifiers most recently set via
    /// [`set_modifiers`](Self::set_modifiers), or `None` if the platform has
    /// never reported them.
    pub fn modifiers(&self) -> Option<Modifiers> {
        self.app.modifiers
    }

    /// Pixels per rotary detent used by
    /// [`rotary_scrolled_by_detents`](Self::rotary_scrolled_by_detents).
    pub fn rotary_scroll_factor(&self) -> f32 {
        self.app.rotary_scroll_factor
    }

    /// Sets the pixels-per-detent factor for rotary input.
    ///
    /// On Wear OS this must be `ViewConfiguration.getScaledVerticalScrollFactor()`
    /// for pixel-exact parity with Compose. The host activity can read it over
    /// JNI once at startup and push it here; when it does not, the shell falls
    /// back to [`DEFAULT_ROTARY_SCROLL_FACTOR_DP`] scaled by display density.
    ///
    /// Non-finite or non-positive values are ignored.
    pub fn set_rotary_scroll_factor(&mut self, factor: f32) {
        if factor.is_finite() && factor > 0.0 {
            self.app.rotary_scroll_factor = factor;
        }
    }

    /// Notifies the framework that the host app was paused/backgrounded.
    ///
    /// Withdraws any outstanding soft-keyboard request (and hides the keyboard)
    /// so the "keyboard shown" state does not survive across the pause and get
    /// restored on resume with no focused field. Platform runtimes call this
    /// from their pause lifecycle event.
    pub fn notify_app_paused(&mut self) {
        let app_context = Rc::clone(&self.app.app_context);
        app_context.enter(cranpose_ui::text_input_session::notify_app_paused);
    }

    /// Notifies the framework that the host app resumed/foregrounded.
    ///
    /// Never auto-shows the soft keyboard, even for a still-focused field: a
    /// warm resume keeps the caret but must not resurrect the keyboard (the user
    /// taps the field to bring it back). Always returns `false` so the platform
    /// runtime force-hides the OS-restored keyboard. Platform runtimes call this
    /// from their resume lifecycle event.
    pub fn notify_app_resumed(&mut self) -> bool {
        let app_context = Rc::clone(&self.app.app_context);
        app_context.enter(cranpose_ui::text_input_session::notify_app_resumed)
    }

    #[cfg(all(
        feature = "clipboard-native",
        target_os = "linux",
        not(target_arch = "wasm32")
    ))]
    pub fn set_primary_selection(&mut self, text: &str) {
        use arboard::{LinuxClipboardKind, SetExtLinux};
        if let Some(ref mut clipboard) = self.app.clipboard {
            let result = clipboard
                .set()
                .clipboard(LinuxClipboardKind::Primary)
                .text(text.to_string());
            if let Err(e) = result {
                log::debug!("Primary selection set failed: {e:?}");
            }
        }
    }

    #[cfg(not(all(
        feature = "clipboard-native",
        target_os = "linux",
        not(target_arch = "wasm32")
    )))]
    pub fn set_primary_selection(&mut self, _text: &str) {}

    #[cfg(all(
        feature = "clipboard-native",
        target_os = "linux",
        not(target_arch = "wasm32")
    ))]
    pub fn get_primary_selection(&mut self) -> Option<String> {
        use arboard::{GetExtLinux, LinuxClipboardKind};
        if let Some(ref mut clipboard) = self.app.clipboard {
            clipboard
                .get()
                .clipboard(LinuxClipboardKind::Primary)
                .text()
                .ok()
        } else {
            None
        }
    }

    #[cfg(not(all(
        feature = "clipboard-native",
        target_os = "linux",
        not(target_arch = "wasm32")
    )))]
    pub fn get_primary_selection(&mut self) -> Option<String> {
        None
    }

    /// Syncs the current text field selection to PRIMARY (Linux X11).
    /// Call this when selection changes in a text field.
    pub fn sync_selection_to_primary(&mut self) {
        #[cfg(all(target_os = "linux", not(target_arch = "wasm32")))]
        {
            if let Some(text) = self.on_copy() {
                self.set_primary_selection(&text);
            }
        }
    }

    /// Primary-surface form of [`SurfaceMut::set_pointer_source`].
    pub fn set_pointer_source(&mut self, source: PointerSource) {
        self.primary().set_pointer_source(source);
    }

    /// Primary-surface form of [`SurfaceMut::pointer_source`].
    pub fn pointer_source(&self) -> PointerSource {
        self.surfaces[0].pointer_source
    }

    /// Primary-surface form of [`SurfaceMut::set_cursor`].
    pub fn set_cursor(&mut self, x: f32, y: f32) -> bool {
        self.primary().set_cursor(x, y)
    }

    /// Primary-surface form of [`SurfaceMut::set_cursor_at_time`].
    pub fn set_cursor_at_time(&mut self, x: f32, y: f32, time_ms: Option<i64>) -> bool {
        self.primary().set_cursor_at_time(x, y, time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::set_cursor_at_event_time`].
    pub fn set_cursor_at_event_time(
        &mut self,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        self.primary().set_cursor_at_event_time(x, y, event_time)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_pressed`].
    pub fn pointer_pressed(&mut self) -> bool {
        self.primary().pointer_pressed()
    }

    /// Primary-surface form of [`SurfaceMut::accessibility_activate`].
    pub fn accessibility_activate(&mut self, node_id: NodeId, canvas_key: Option<u64>) -> bool {
        self.primary().accessibility_activate(node_id, canvas_key)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_pressed_at_time`].
    pub fn pointer_pressed_at_time(&mut self, time_ms: Option<i64>) -> bool {
        self.primary().pointer_pressed_at_time(time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_pressed_at_event_time`].
    pub fn pointer_pressed_at_event_time(&mut self, event_time: PointerEventTime) -> bool {
        self.primary().pointer_pressed_at_event_time(event_time)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_released`].
    pub fn pointer_released(&mut self) -> bool {
        self.primary().pointer_released()
    }

    /// Primary-surface form of [`SurfaceMut::pointer_released_at_position`].
    pub fn pointer_released_at_position(&mut self, x: f32, y: f32) -> bool {
        self.primary().pointer_released_at_position(x, y)
    }

    /// Primary-surface form of
    /// [`SurfaceMut::pointer_released_at_position_time`].
    pub fn pointer_released_at_position_time(
        &mut self,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        self.primary()
            .pointer_released_at_position_time(x, y, time_ms)
    }

    /// Primary-surface form of
    /// [`SurfaceMut::pointer_released_at_position_event_time`].
    pub fn pointer_released_at_position_event_time(
        &mut self,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        self.primary()
            .pointer_released_at_position_event_time(x, y, event_time)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_released_at_time`].
    pub fn pointer_released_at_time(&mut self, time_ms: Option<i64>) -> bool {
        self.primary().pointer_released_at_time(time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_released_at_event_time`].
    pub fn pointer_released_at_event_time(&mut self, event_time: PointerEventTime) -> bool {
        self.primary().pointer_released_at_event_time(event_time)
    }

    /// Primary-surface form of [`SurfaceMut::secondary_pointer_pressed`].
    pub fn secondary_pointer_pressed(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        self.primary()
            .secondary_pointer_pressed(pointer_id, x, y, time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::secondary_pointer_moved`].
    pub fn secondary_pointer_moved(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        self.primary()
            .secondary_pointer_moved(pointer_id, x, y, time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::secondary_pointer_released`].
    pub fn secondary_pointer_released(
        &mut self,
        pointer_id: u64,
        x: f32,
        y: f32,
        time_ms: Option<i64>,
    ) -> bool {
        self.primary()
            .secondary_pointer_released(pointer_id, x, y, time_ms)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_zoomed`].
    pub fn pointer_zoomed(&mut self, zoom_factor: f32) -> bool {
        self.primary().pointer_zoomed(zoom_factor)
    }

    /// Primary-surface form of [`SurfaceMut::wheel_scrolled`].
    pub fn wheel_scrolled(&mut self, wheel: crate::WheelScroll) -> bool {
        self.primary().wheel_scrolled(wheel)
    }

    /// Primary-surface form of [`SurfaceMut::pointer_scrolled`].
    pub fn pointer_scrolled(&mut self, delta_x: f32, delta_y: f32) -> bool {
        self.primary().pointer_scrolled(delta_x, delta_y)
    }

    /// Primary-surface form of [`SurfaceMut::set_on_rotary_scroll`].
    pub fn set_on_rotary_scroll<F>(&mut self, handler: F)
    where
        F: Fn(RotaryScrollEvent) -> bool + 'static,
    {
        self.primary().set_on_rotary_scroll(handler);
    }

    /// Primary-surface form of [`SurfaceMut::clear_on_rotary_scroll`].
    pub fn clear_on_rotary_scroll(&mut self) {
        self.primary().clear_on_rotary_scroll();
    }

    /// Primary-surface form of [`SurfaceMut::rotary_scrolled_by_detents`].
    pub fn rotary_scrolled_by_detents(&mut self, detents: f32, uptime_millis: u64) -> bool {
        self.primary()
            .rotary_scrolled_by_detents(detents, uptime_millis)
    }

    /// Primary-surface form of [`SurfaceMut::rotary_scrolled`].
    pub fn rotary_scrolled(&mut self, event: RotaryScrollEvent) -> bool {
        self.primary().rotary_scrolled(event)
    }

    /// Primary-surface form of [`SurfaceMut::cancel_gesture`].
    pub fn cancel_gesture(&mut self) {
        self.primary().cancel_gesture();
    }

    /// Primary-surface form of [`SurfaceMut::cancel_gesture_unless_pressed`].
    pub fn cancel_gesture_unless_pressed(&mut self) {
        self.primary().cancel_gesture_unless_pressed();
    }

    /// Offers the primary window's current pointer icon to the platform
    /// again, for the moments a windowing system has drawn its own default
    /// over it.
    pub fn refresh_pointer_icon(&self) {
        self.surfaces[0].pointer_icon.refresh();
    }

    /// The pointer icon the platform has not applied to the primary window
    /// yet, or `None` when the icon has not changed since the last call.
    ///
    /// Platform backends call this after handing the shell a batch of input and
    /// set the returned icon on the window they own. Platforms with no pointing
    /// device never call it.
    pub fn take_pointer_icon_change(&self) -> Option<PointerIcon> {
        self.surfaces[0].pointer_icon.take_change()
    }

    /// Installs the platform soft-keyboard handler for the primary window.
    ///
    /// The handler is invoked when a text field gains focus (`show_keyboard`)
    /// or when text-field focus is cleared or goes stale (`hide_keyboard`).
    /// Platform runtimes with an on-screen keyboard (Android, iOS) call this
    /// once after creating the shell.
    pub fn set_platform_text_input(
        &mut self,
        handler: Rc<dyn cranpose_ui::PlatformTextInputHandler>,
    ) {
        self.primary().set_platform_text_input(handler);
    }

    /// Primary-surface form of [`SurfaceMut::dismiss_top_modal`].
    pub fn dismiss_top_modal(&mut self) -> bool {
        self.primary().dismiss_top_modal()
    }

    /// Primary-surface form of [`SurfaceMut::move_focus_in_context`].
    pub fn move_focus_in_context(&mut self, direction: FocusDirection) -> bool {
        self.primary().move_focus_in_context(direction)
    }

    /// Primary-surface form of [`SurfaceMut::on_key_event`].
    pub fn on_key_event(&mut self, event: &KeyEvent) -> bool {
        self.primary().on_key_event(event)
    }

    /// Primary-surface form of [`SurfaceMut::on_paste`].
    pub fn on_paste(&mut self, text: &str) -> bool {
        self.primary().on_paste(text)
    }

    /// Primary-surface form of [`SurfaceMut::on_copy`].
    pub fn on_copy(&mut self) -> Option<String> {
        self.primary().on_copy()
    }

    /// Primary-surface form of [`SurfaceMut::on_cut`].
    pub fn on_cut(&mut self) -> Option<String> {
        self.primary().on_cut()
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_preedit`].
    pub fn on_ime_preedit(&mut self, text: &str, cursor: Option<(usize, usize)>) -> bool {
        self.primary().on_ime_preedit(text, cursor)
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_finish_composing`].
    pub fn on_ime_finish_composing(&mut self) -> bool {
        self.primary().on_ime_finish_composing()
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_action`].
    pub fn on_ime_action(&mut self, action: cranpose_ui::ImeAction) -> bool {
        self.primary().on_ime_action(action)
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_set_composing_region`].
    pub fn on_ime_set_composing_region(&mut self, start_bytes: usize, end_bytes: usize) -> bool {
        self.primary()
            .on_ime_set_composing_region(start_bytes, end_bytes)
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_set_selection`].
    pub fn on_ime_set_selection(&mut self, start_bytes: usize, end_bytes: usize) -> bool {
        self.primary().on_ime_set_selection(start_bytes, end_bytes)
    }

    /// Primary-surface form of [`SurfaceMut::ime_editor_state`].
    pub fn ime_editor_state(&mut self) -> Option<cranpose_ui::text_field_focus::ImeEditorState> {
        self.primary().ime_editor_state()
    }

    /// Primary-surface form of [`SurfaceMut::ime_caret_geometry`].
    pub fn ime_caret_geometry(
        &mut self,
    ) -> Option<cranpose_ui::text_field_focus::ImeCaretGeometry> {
        self.primary().ime_caret_geometry()
    }

    /// Primary-surface form of [`SurfaceMut::ime_field_is_password`].
    pub fn ime_field_is_password(&mut self) -> bool {
        self.primary().ime_field_is_password()
    }

    /// Primary-surface form of [`SurfaceMut::clear_text_field_focus`].
    pub fn clear_text_field_focus(&mut self) {
        self.primary().clear_text_field_focus();
    }

    /// Primary-surface form of [`SurfaceMut::on_ime_delete_surrounding`].
    pub fn on_ime_delete_surrounding(&mut self, before_bytes: usize, after_bytes: usize) -> bool {
        self.primary()
            .on_ime_delete_surrounding(before_bytes, after_bytes)
    }
}

enum ActivationTarget {
    Direct(cranpose_foundation::SemanticsCustomAction),
    Edit(NodeId),
    Pointer(NodeId, Option<Rect>),
}

fn activation_target(
    node: &cranpose_ui::SemanticsNode,
    node_id: NodeId,
    canvas_key: Option<u64>,
) -> Option<ActivationTarget> {
    if node.hidden {
        return None;
    }
    if node.node_id != node_id {
        return node
            .children
            .iter()
            .find_map(|child| activation_target(child, node_id, canvas_key));
    }
    if !node.enabled {
        return None;
    }
    if let Some(key) = canvas_key {
        let child = node
            .details()
            .canvas_children
            .iter()
            .find(|child| child.key == key)?;
        return (child.enabled && child.clickable)
            .then_some(ActivationTarget::Pointer(node_id, Some(child.bounds)));
    }
    if let Some(action) = &node.on_click {
        return Some(ActivationTarget::Direct(action.clone()));
    }
    if node.details().editable_text && node.focusable {
        return Some(ActivationTarget::Edit(node_id));
    }
    node.actions.first().map(|action| match action {
        cranpose_ui::SemanticsAction::Click { handler } => {
            ActivationTarget::Pointer(handler.node_id(), None)
        }
    })
}

fn activation_input(
    root: &LayoutBox,
    node_id: NodeId,
    canvas_bounds: Option<Rect>,
) -> Option<(Point, Point, Rc<cranpose_ui::ModifierNodeSlices>)> {
    if root.node_id != node_id {
        return root
            .children
            .iter()
            .find_map(|child| activation_input(child, node_id, canvas_bounds));
    }
    let bounds = canvas_bounds.map_or(root.rect, |bounds| Rect {
        x: root.rect.x + bounds.x,
        y: root.rect.y + bounds.y,
        ..bounds
    });
    let position = Point {
        x: bounds.x + bounds.width * 0.5,
        y: bounds.y + bounds.height * 0.5,
    };
    let local = Point {
        x: position.x - root.rect.x,
        y: position.y - root.rect.y,
    };
    (bounds.width > 0.0 && bounds.height > 0.0 && position.x.is_finite() && position.y.is_finite())
        .then(|| (position, local, Rc::clone(&root.node_data.modifier_slices)))
}

fn plain_key_down(event: &KeyEvent) -> bool {
    event.event_type == KeyEventType::KeyDown
        && !event.modifiers.ctrl
        && !event.modifiers.meta
        && !event.modifiers.alt
}