cranpose_app_shell/

shell_input.rs

use cranpose_ui::FocusDirection;

use super::*;

mod dispatch_stop;
pub(crate) mod key_activation;
mod key_navigation;

use dispatch_stop::Stop;

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: Stop)
    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={:?}",
                event.kind,
                node_id,
                event.is_consumed(),
                stop,
            );
            if stop == Stop::AtConsumer && 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(HitTestTarget::capture_path)
            .collect::<Vec<_>>();
        let targets = 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(), Stop::AtConsumer);

        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
    }

    /// Moves the pointer to `(x, y)` in logical pixels and sends the enter, exit, move or drag
    /// events that follow. Returns `true` when a control or overlay handled the move.
    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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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, Stop::Never);
                    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(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, Stop::Never);
            }
        }

        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, Stop::Never);
            }
        }

        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, Stop::AtConsumer);
            true
        } else {
            false
        }
    }

    /// Presses the primary pointer button at the position set by `set_cursor`. Returns `true` when
    /// a control or overlay handled the press.
    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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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);
        }
        let event = self.cursor_event(PointerEventKind::Down, event_time);
        self.press_hits(hits, event, PointerId::PRIMARY)
    }

    /// An event of `kind` at the cursor, with the buttons held and the
    /// pointer's source.
    fn cursor_event(&self, kind: PointerEventKind, event_time: PointerEventTime) -> PointerEvent {
        let (x, y) = self.surface().cursor;
        self.pointer_event(kind, Point { x, y }, Point { x, y }, event_time)
            .with_buttons(self.surface().buttons_pressed)
            .with_source(self.surface().pointer_source)
    }

    /// Delivers a press to `hits`, nearest first, until one consumes it, and
    /// keeps the paths it reached as `pointer`'s gesture targets.
    fn press_hits(
        &mut self,
        hits: Vec<<<R as Renderer>::Scene as RenderScene>::HitTarget>,
        event: PointerEvent,
        pointer: PointerId,
    ) -> bool {
        if hits.is_empty() {
            self.surface_mut().hit_path_tracker.remove_path(pointer);
            return false;
        }
        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=AtConsumer",
                event.kind,
                node_id,
                event.is_consumed(),
            );
            if event.is_consumed() {
                break;
            }
        }

        surface
            .hit_path_tracker
            .add_hit_path(pointer, delivered_capture_paths);
        log::trace!(
            target: "cranpose::input",
            "press cached_hit_path={:?}",
            surface.hit_path_tracker.get_path(pointer),
        );
        true
    }

    /// Presses `button` of the mouse at the position set by `set_cursor`.
    /// The primary button presses as [`pointer_pressed`](Self::pointer_pressed)
    /// does. Another button reaches the nodes under the pointer as a
    /// [`PointerEventKind::ButtonDown`], or, while a button is already down,
    /// the nodes that took its press; those nodes take the moves until the
    /// last button goes up. Returns `true` when a node received the press.
    pub fn mouse_button_pressed(&mut self, button: PointerButton) -> bool {
        if button == PointerButton::Primary {
            return self.pointer_pressed();
        }
        self.mouse_button_change(|surface, event_time| {
            surface.other_button_pressed(button, event_time)
        })
    }

    /// Releases `button` of the mouse. The primary button releases as
    /// [`pointer_released`](Self::pointer_released) does; another reaches the
    /// nodes that took the press as a [`PointerEventKind::ButtonUp`]. Returns
    /// `true` when a node received the release.
    pub fn mouse_button_released(&mut self, button: PointerButton) -> bool {
        if button == PointerButton::Primary {
            return self.pointer_released();
        }
        self.mouse_button_change(|surface, event_time| {
            surface.other_button_released(button, event_time)
        })
    }

    fn mouse_button_change(
        &mut self,
        change: impl FnOnce(&mut Self, PointerEventTime) -> bool,
    ) -> bool {
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            run_in_mutable_snapshot(|| change(self, event_time)).unwrap_or(false)
        };
        if result {
            self.mark_dirty();
        }
        result
    }

    fn other_button_pressed(
        &mut self,
        button: PointerButton,
        event_time: PointerEventTime,
    ) -> bool {
        self.activate();
        let first = self.surface().buttons_pressed == PointerButtons::NONE;
        self.surface_mut().buttons_pressed.insert(button);
        let event = self.cursor_event(PointerEventKind::ButtonDown(button), event_time);
        if first {
            let (x, y) = self.surface().cursor;
            let hits = self.surface().renderer.scene().hit_test(x, y);
            return self.press_hits(hits, event, PointerId::PRIMARY);
        }
        let targets = self.resolve_gesture_targets(PointerId::PRIMARY);
        if targets.is_empty() {
            return false;
        }
        self.dispatch_targets(targets, event, Stop::Never);
        true
    }

    fn other_button_released(
        &mut self,
        button: PointerButton,
        event_time: PointerEventTime,
    ) -> bool {
        if !self.surface().buttons_pressed.contains(button) {
            return false;
        }
        self.surface_mut().buttons_pressed.remove(button);
        let targets = self.resolve_gesture_targets(PointerId::PRIMARY);
        if self.surface().buttons_pressed == PointerButtons::NONE {
            self.surface_mut()
                .hit_path_tracker
                .remove_path(PointerId::PRIMARY);
        }
        if targets.is_empty() {
            return false;
        }
        let event = self.cursor_event(PointerEventKind::ButtonUp(button), event_time);
        self.dispatch_targets(targets, event, Stop::Never);
        true
    }

    /// Releases the primary pointer button at the position set by `set_cursor`. Returns `true` when
    /// a control or overlay handled the release.
    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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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);

        // Another button still down keeps the gesture's targets for its
        // moves and its release.
        if corrected_buttons == PointerButtons::NONE {
            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, Stop::Never);
            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: PointerId,
        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: PointerId,
        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: PointerId,
        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: PointerId,
        x: f32,
        y: f32,
        event_time: PointerEventTime,
    ) -> bool {
        if pointer_id.is_primary() {
            log::warn!(
                target: "cranpose::input",
                "secondary pointer dispatch called with the primary pointer id"
            );
            return false;
        }

        let _event_handler = enter_event_handler_scope();
        let result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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, Stop::Never);
                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
    }

    /// Points pointer `pointer_id` along `ray` in the 3D scene the node
    /// `scene` shows: a controller, a hand or a gaze, in the coordinates of
    /// the space the scene's eye stands in. A `Down` reaches the content of
    /// the mesh surface the ray meets first and keeps its targets as the
    /// pointer's gesture, which the pointer's `Move`s and its `Up` or
    /// `Cancel` reach wherever the ray points then. `pointer_id`, not 0,
    /// tells the pointer from the window's others. Returns `true` when a
    /// target received the event.
    pub fn ray_pointer(
        &mut self,
        (pointer_id, scene): (PointerId, NodeId),
        ray: cranpose_ui_graphics::space::Ray,
        kind: PointerEventKind,
    ) -> bool {
        if pointer_id.is_primary() {
            log::warn!(
                target: "cranpose::input",
                "ray pointer dispatch called with the primary pointer id"
            );
            return false;
        }
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let _event_handler = enter_event_handler_scope();
        let result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            run_in_mutable_snapshot(|| {
                let pointer = pointer_id;
                let event = self
                    .pointer_event(kind, Point::default(), Point::default(), event_time)
                    .with_id(pointer)
                    .with_ray(ray);
                if kind == PointerEventKind::Down {
                    let hits = self.surface().renderer.scene().hit_test_ray(scene, ray);
                    return self.press_hits(hits, event, pointer);
                }
                let targets = self.resolve_gesture_targets(pointer);
                if matches!(kind, PointerEventKind::Up | PointerEventKind::Cancel) {
                    self.surface_mut().hit_path_tracker.remove_path(pointer);
                }
                if targets.is_empty() {
                    return false;
                }
                self.dispatch_targets(targets, event, Stop::Never);
                true
            })
            .unwrap_or(false)
        };
        if result {
            self.mark_dirty();
        }
        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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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: 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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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 result = {
            let _app_context = self.shell.app.app_context.enter_scope();
            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(), Stop::AtConsumer);
            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(), Stop::AtConsumer);
            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 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(HitTestTarget::capture_path)
            .collect::<Vec<_>>();
        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 _ = {
            let _app_context = self.shell.app.app_context.enter_scope();
            run_in_mutable_snapshot(|| {
                self.cancel_gesture_inner(event_time);
            })
        };
        self.route_drag_and_drop();
    }

    /// Gives the held press to `node` alone, as a long press does once it
    /// fires: every handler under the press sees it cancelled, the other
    /// handlers on `node` too, so a button does not click when the press
    /// ends, and the rest of the press reaches `node` alone. Does nothing on
    /// a surface whose press does not reach `node`.
    pub(crate) fn give_press_to(&mut self, node: NodeId) {
        let holds = self
            .surface()
            .hit_path_tracker
            .get_path(PointerId::PRIMARY)
            .is_some_and(|paths| paths.iter().any(|path| path.contains(&node)));
        if !holds {
            return;
        }
        let event_time = self.shell.app.realtime_pointer_event_time(None);
        let targets = self.resolve_gesture_targets(PointerId::PRIMARY);
        self.surface_mut()
            .hit_path_tracker
            .add_hit_path(PointerId::PRIMARY, vec![vec![node]]);
        let cursor = Point {
            x: self.surface().cursor.0,
            y: self.surface().cursor.1,
        };
        let event = self
            .pointer_event(PointerEventKind::Cancel, cursor, cursor, event_time)
            .with_source(self.surface().pointer_source);
        let _event_handler = enter_event_handler_scope();
        let _ = run_in_mutable_snapshot(|| self.dispatch_targets(targets, event, Stop::Never));
    }

    fn route_drag_and_drop(&mut self) {
        let source = self.index;
        let shell = &*self.shell;
        let app_context = &shell.app.app_context;
        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 {
            self.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, Stop::Never);
        }

        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, Stop::Never);
            }
        }
        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);
    }

    /// Sends a key event to the focused control, the key handlers above it and the focus traversal.
    /// Returns `true` when the event was handled and the platform should not process it further.
    pub fn on_key_event(&mut self, event: &KeyEvent) -> bool {
        let _event_handler = enter_event_handler_scope();
        let _app_context = self.shell.app.app_context.enter_scope();
        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;
        }
        route.focus_is_current() && self.on_unconsumed_key(event)
    }

    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<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.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() {
                    Key::C => {
                        if let Some(text) = self.on_copy_inner() {
                            cranpose_ui::clipboard_session::clipboard_write_text(&text);
                            return true;
                        }
                    }
                    Key::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;
                        }
                    }
                    Key::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_field_dpad_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 = self.shell.app.app_context.enter_scope();
        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> {
        if self.inspector_owns_keyboard() {
            return None;
        }
        let _app_context = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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<ImeEditorState> {
        let _app_context = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        self.receives_focused_input()
            .then(cranpose_ui::text_field_focus::focused_caret_geometry)
            .flatten()
    }

    /// Window bounds of the focused field in logical pixels, for platforms
    /// that place a native editor over it, or `None` when this surface has
    /// no focused text field that has been laid out.
    pub fn ime_field_bounds(&mut self) -> Option<Rect> {
        let _app_context = self.shell.app.app_context.enter_scope();
        self.receives_focused_input()
            .then(cranpose_ui::text_field_focus::focused_field_bounds)
            .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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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 = self.shell.app.app_context.enter_scope();
        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) {
        self.app
            .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 {
        self.app
            .app_context
            .enter(cranpose_ui::text_input_session::notify_app_resumed)
    }

    /// Copies `text` to the Linux PRIMARY selection, which a middle click pastes.
    #[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:?}");
            }
        }
    }

    /// Copies `text` to the Linux PRIMARY selection, which a middle click pastes. Does nothing
    /// here, because this build has no PRIMARY selection.
    #[cfg(not(all(
        feature = "clipboard-native",
        target_os = "linux",
        not(target_arch = "wasm32")
    )))]
    pub fn set_primary_selection(&mut self, _text: &str) {}

    /// Returns the text in the Linux PRIMARY selection, or `None` when it is empty or unavailable.
    #[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
        }
    }

    /// Returns `None` always, because this build has no PRIMARY selection.
    #[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: PointerId,
        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::ray_pointer`].
    pub fn ray_pointer(
        &mut self,
        (pointer_id, scene): (PointerId, NodeId),
        ray: cranpose_ui_graphics::space::Ray,
        kind: PointerEventKind,
    ) -> bool {
        self.primary().ray_pointer((pointer_id, scene), ray, kind)
    }

    /// Primary-surface form of [`SurfaceMut::secondary_pointer_moved`].
    pub fn secondary_pointer_moved(
        &mut self,
        pointer_id: PointerId,
        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: PointerId,
        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: 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 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<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_bounds`].
    pub fn ime_field_bounds(&mut self) -> Option<Rect> {
        self.primary().ime_field_bounds()
    }

    /// 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)
    }
}