cranpose_app_shell/

surface.rs

//! Root surfaces: what the shell keeps per window.
//!
//! The composition is one tree. Each window the app shows is a root in that
//! tree: the composition root for the primary window, a node carrying
//! `Modifier::window_root` for every other. A [`RootSurface`] is the shell's
//! bookkeeping for one such root: the renderer that draws it, the viewport it
//! draws into, the pointer that hovers it, the gesture it tracks, the
//! snapshots a test or a platform reads for it, and the dirt that says whether
//! it owes the display a frame. A [`SurfaceMut`] borrows one surface together
//! with the app, which is how a platform delivers a window's events and reads
//! a window's frame.

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

use cranpose_core::{MemoryApplier, NodeId, collections::map::HashSet};
use cranpose_foundation::{
    PointerButton, PointerButtons, PointerId, PointerSource, RotaryScrollEvent,
};
use cranpose_render_common::{NodeUpdate, RenderScene, Renderer};
use cranpose_ui::{
    LayoutNode, LayoutTree, MovedSceneNode, PlatformTextInputHandler, SemanticsTree,
    pointer_icon_session::PointerIconState,
};
use cranpose_ui_graphics::{Point, PointerIcon, Size};

use crate::{
    AppShell, FramePacingMode, FrameRatePreference, FrameSchedule, FrameScheduler,
    FrameUpdateResult, PlatformFrameDriver, ShellApp, SurfaceRoutingScratch,
    hit_path_tracker::HitPathTracker, shell_frame::DevOverlay,
};

/// Names a root surface of the app: the primary window, or a window root
/// declared with [`Modifier::window_root`](cranpose_ui::Modifier::window_root)
/// by the id given there.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum RootId {
    /// The composition root, drawn in the app's first window.
    Primary,
    /// The node carrying `Modifier::window_root`.
    Window(NodeId),
}

/// The shell's bookkeeping for one root.
///
/// The primary surface draws the composition root. A window surface draws the
/// window root node registered under its id, and draws nothing while that
/// node is not in the tree. Everything here is what an OS owns per window:
/// the framebuffer, the viewport, the pointer, the cursor image, the soft
/// keyboard, the frame the window is asked for.
pub struct RootSurface<R: Renderer> {
    pub(crate) id: RootId,
    pub(crate) root: Option<NodeId>,
    pub(crate) renderer: R,
    pub(crate) cursor: (f32, f32),
    pub(crate) viewport: (f32, f32),
    pub(crate) buffer_size: (u32, u32),
    pub(crate) layout_tree: Option<LayoutTree>,
    pub(crate) semantics_tree: Option<SemanticsTree>,
    /// A layout pass ran since `semantics_tree` was brought up to date, so
    /// its bounds may be out of date though no node marked its semantics.
    semantics_moved: bool,
    // The scene's count of layer moves when the semantics revision last
    // looked: a layer that moves moves the window bounds of what it holds.
    seen_layer_moves: u64,
    pub(crate) modal_focus: Vec<(NodeId, Option<NodeId>)>,
    // The frames the surface started, counted by `begin_frame`.
    pub(crate) frames: u64,
    // The frame count at which a navigation key last moved focus; a held
    // key's repeats wait for the next frame, so they never queue moves
    // behind a slow layout. A count, not the frame time: Android draws its
    // frames with `update_without_frame`, which leaves the time unchanged.
    pub(crate) key_moved_focus_at: Option<u64>,
    // Whether a D-pad drives the window, and whether the next update checks
    // for a focused target with no layout of its own.
    pub(crate) dpad_navigation: bool,
    pub(crate) focus_check_due: bool,
    // The press a click key holds until it comes up.
    pub(crate) key_press: Option<crate::shell_input::key_activation::KeyPress>,
    pub(crate) frame_rate_preference: FrameRatePreference,
    pub(crate) scene_dirty: bool,
    pub(crate) scoped_layout_scene_nodes: Vec<NodeId>,
    /// Nodes the layout pass only moved: the scene moves their layers.
    pub(crate) scoped_moved_scene_nodes: Vec<NodeId>,
    pub(crate) scoped_draw_nodes: Vec<NodeId>,
    pub(crate) scoped_layer_property_nodes: Vec<NodeId>,
    pub(crate) structural_scene_nodes: Vec<NodeId>,
    pub(crate) scene_updates: Vec<(NodeId, NodeUpdate)>,
    /// The nodes the retained redraw walk has yet to visit, empty between
    /// frames; kept for its storage.
    pub(crate) redraw_walk: Vec<NodeId>,
    pub(crate) retained_visual_nodes: HashSet<NodeId>,
    pub(crate) is_dirty: bool,
    pub(crate) buttons_pressed: PointerButtons,
    pub(crate) pointer_source: PointerSource,
    pub(crate) hit_path_tracker: HitPathTracker,
    pub(crate) hovered_nodes: Vec<NodeId>,
    pub(crate) on_rotary_scroll: Option<Rc<dyn Fn(RotaryScrollEvent) -> bool>>,
    pub(crate) dev_overlay: DevOverlay,
    pub(crate) inspector: crate::inspector::DeveloperInspector,
    pub(crate) frame_scheduler: FrameScheduler,
    pub(crate) pointer_icon: PointerIconState,
    pub(crate) last_update: FrameUpdateResult,
    pub(crate) frame_owed: bool,
    pub(crate) screen_origin: Option<Point>,
}

impl<R: Renderer> RootSurface<R> {
    pub(crate) fn new(
        id: RootId,
        renderer: R,
        buffer_size: (u32, u32),
        viewport: (f32, f32),
    ) -> Self {
        Self {
            id,
            root: None,
            renderer,
            cursor: (0.0, 0.0),
            viewport,
            buffer_size,
            layout_tree: None,
            semantics_tree: None,
            semantics_moved: false,
            seen_layer_moves: 0,
            modal_focus: Vec::new(),
            frames: 0,
            key_moved_focus_at: None,
            dpad_navigation: false,
            focus_check_due: false,
            key_press: None,
            frame_rate_preference: FrameRatePreference::default(),
            scene_dirty: true,
            scoped_layout_scene_nodes: Vec::new(),
            scoped_moved_scene_nodes: Vec::new(),
            scoped_draw_nodes: Vec::new(),
            scoped_layer_property_nodes: Vec::new(),
            structural_scene_nodes: Vec::new(),
            scene_updates: Vec::new(),
            redraw_walk: Vec::new(),
            retained_visual_nodes: HashSet::default(),
            is_dirty: true,
            buttons_pressed: PointerButtons::NONE,
            pointer_source: PointerSource::Unknown,
            hit_path_tracker: HitPathTracker::new(),
            hovered_nodes: Vec::new(),
            on_rotary_scroll: None,
            dev_overlay: DevOverlay::default(),
            inspector: crate::inspector::DeveloperInspector::default(),
            frame_scheduler: FrameScheduler::default(),
            pointer_icon: PointerIconState::new(),
            last_update: FrameUpdateResult::default(),
            frame_owed: false,
            screen_origin: None,
        }
    }

    pub(crate) fn root_node(&self, app: &ShellApp) -> Option<NodeId> {
        match self.id {
            RootId::Primary => app.composition.root(),
            RootId::Window(_) => self.root,
        }
    }

    pub(crate) fn owns_nodes_under(&self, window_root: Option<NodeId>) -> bool {
        match self.id {
            RootId::Primary => window_root.is_none(),
            RootId::Window(_) => self.root.is_some() && self.root == window_root,
        }
    }

    pub(crate) fn viewport_size(&self) -> Size {
        Size {
            width: self.viewport.0,
            height: self.viewport.1,
        }
    }

    pub(crate) fn screen_point_inside(&self, screen: Point) -> Option<Point> {
        let origin = self.screen_origin?;
        let local = Point {
            x: screen.x - origin.x,
            y: screen.y - origin.y,
        };
        (local.x >= 0.0
            && local.y >= 0.0
            && local.x <= self.viewport.0
            && local.y <= self.viewport.1)
            .then_some(local)
    }

    pub(crate) fn set_root(&mut self, root: Option<NodeId>) {
        if self.root == root {
            return;
        }
        self.root = root;
        self.forget_snapshots();
        self.invalidate_scene_root(root);
        self.retained_visual_nodes.clear();
        self.hit_path_tracker.clear();
        self.hovered_nodes.clear();
        self.buttons_pressed = PointerButtons::NONE;
        self.is_dirty = true;
    }

    pub(crate) fn invalidate_scene_root(&mut self, root: Option<NodeId>) {
        self.scoped_layout_scene_nodes.clear();
        self.scoped_layout_scene_nodes.extend(root);
        self.scoped_moved_scene_nodes.clear();
        self.scoped_draw_nodes.clear();
        self.scoped_layer_property_nodes.clear();
        self.structural_scene_nodes.clear();
        self.scene_updates.clear();
        self.scene_dirty = true;
    }

    /// Drops the layout snapshot and marks the semantics tree for an update,
    /// which keeps what did not change.
    pub(crate) fn forget_snapshots(&mut self) {
        self.layout_tree = None;
        self.semantics_moved = true;
    }

    // Whether the scene moved a layer since the last call.
    pub(crate) fn layers_moved_since_look(&mut self) -> bool {
        let moves = self.renderer.scene().layer_moves();
        let moved = moves != self.seen_layer_moves;
        self.seen_layer_moves = moves;
        moved
    }

    pub(crate) fn has_active_pointer_gesture(&self) -> bool {
        self.buttons_pressed != PointerButtons::NONE
            && self.hit_path_tracker.has_path(PointerId::PRIMARY)
    }

    pub(crate) fn has_active_primary_gesture(&self) -> bool {
        self.buttons_pressed.contains(PointerButton::Primary)
            && self.hit_path_tracker.has_path(PointerId::PRIMARY)
    }

    // Starts a frame of the surface: counts it, and tells the renderer when
    // the app held still since the last one, before the frame builds its
    // scene.
    pub(crate) fn begin_frame(&mut self) {
        self.frames += 1;
        if self.frame_scheduler.take_held_still() {
            self.renderer.note_held_still();
        }
        if self.has_active_pointer_gesture() {
            self.renderer.note_pointer_held();
        }
    }

    pub(crate) fn renderer_warmup_due(&self, app: &ShellApp) -> bool {
        self.renderer.needs_frame_warmup() && !app.composition.runtime().has_frame_callbacks()
    }

    pub(crate) fn needs_redraw_in_context(&self, app: &ShellApp) -> bool {
        app.has_stale_work_in_context()
            || app.composition.should_recompose()
            || self.is_dirty
            || self.scene_dirty
            || self.renderer_warmup_due(app)
    }

    pub(crate) fn compute_frame_schedule(
        &self,
        app: &ShellApp,
        surfaces_dirty: bool,
    ) -> FrameSchedule {
        let (needs_update, needs_frame) = app.app_context.enter(|| {
            let needs_frame = self.is_dirty
                || self.scene_dirty
                || app.wants_frame_in_context()
                || self.has_active_pointer_gesture()
                || self.renderer_warmup_due(app);
            (app.needs_ui_update_in_context(surfaces_dirty), needs_frame)
        });
        FrameSchedule {
            needs_update,
            needs_frame,
            next_deadline: app.next_event_time(),
        }
    }

    pub(crate) fn layout_tree_in_context(&mut self, app: &mut ShellApp) -> Option<&LayoutTree> {
        if self.layout_tree.is_none() {
            let root = self.root_node(app)?;
            let mut applier = app.composition.applier_mut();
            match cranpose_ui::build_layout_tree_from_applier(&mut applier, root) {
                Ok(layout_tree) => {
                    self.layout_tree = layout_tree;
                }
                Err(err) => {
                    log::debug!("failed to build layout snapshot: {err}");
                    return None;
                }
            }
        }
        self.layout_tree.as_ref()
    }

    /// The node an open modal takes this surface over with, the root its
    /// semantics tree would have, found without building the tree.
    pub(crate) fn top_modal(&self, app: &mut ShellApp) -> Option<NodeId> {
        let root = self.root_node(app)?;
        let mut applier = app.composition.applier_mut();
        cranpose_ui::top_modal_from_applier(&mut applier, root).unwrap_or_else(|err| {
            log::debug!("failed to find the top modal under root #{root}: {err}");
            None
        })
    }

    pub(crate) fn semantics_tree_in_context(
        &mut self,
        app: &mut ShellApp,
    ) -> Option<&SemanticsTree> {
        if !app.semantics_enabled && !self.inspector.state.open {
            return None;
        }
        self.semantics_tree_for_input(app)
    }

    pub(crate) fn semantics_tree_for_input(
        &mut self,
        app: &mut ShellApp,
    ) -> Option<&SemanticsTree> {
        app.flush_semantics_invalidations();
        let root = self.root_node(app)?;
        let semantics_dirty = {
            let mut applier = app.composition.applier_mut();
            cranpose_ui::tree_needs_semantics(&mut *applier, root).unwrap_or_else(|err| {
                log::debug!("failed to check semantics dirty status for root #{root}: {err}");
                true
            })
        };
        if self.semantics_tree.is_none() || self.semantics_moved || semantics_dirty {
            let mut applier = app.composition.applier_mut();
            match cranpose_ui::update_semantics_tree_from_applier(
                &mut applier,
                root,
                &mut self.semantics_tree,
            ) {
                Ok(()) => {
                    #[cfg(debug_assertions)]
                    crate::semantics_check::assert_matches_rebuild(
                        &mut applier,
                        root,
                        self.semantics_tree.as_ref(),
                    );
                    self.semantics_moved = false;
                    app.semantics_snapshot_revision =
                        app.semantics_snapshot_revision.wrapping_add(1);
                }
                Err(err) => {
                    log::debug!("failed to build semantics snapshot: {err}");
                    return None;
                }
            }
        }
        self.semantics_tree.as_ref()
    }
}

#[derive(Default)]
pub(crate) struct TextInputRoutes {
    active: Option<RootId>,
    shown: Option<RootId>,
    handlers: Vec<(RootId, Rc<dyn PlatformTextInputHandler>)>,
}

impl TextInputRoutes {
    pub(crate) fn active(&self) -> RootId {
        self.active.unwrap_or(RootId::Primary)
    }

    pub(crate) fn set_active(&mut self, root: RootId) {
        self.active = Some(root);
    }

    pub(crate) fn set_handler(&mut self, root: RootId, handler: Rc<dyn PlatformTextInputHandler>) {
        self.remove(root);
        self.handlers.push((root, handler));
    }

    pub(crate) fn remove(&mut self, root: RootId) {
        self.handlers.retain(|(id, _)| *id != root);
        if self.shown == Some(root) {
            self.shown = None;
        }
    }

    fn handler(&self, root: RootId) -> Option<Rc<dyn PlatformTextInputHandler>> {
        self.handlers
            .iter()
            .find(|(id, _)| *id == root)
            .map(|(_, handler)| Rc::clone(handler))
    }

    fn take_show_target(&mut self) -> Option<Rc<dyn PlatformTextInputHandler>> {
        let active = self.active();
        let handler = self.handler(active);
        if handler.is_some() {
            self.shown = Some(active);
        }
        handler
    }

    fn take_hide_target(&mut self) -> Option<Rc<dyn PlatformTextInputHandler>> {
        let target = self.shown.take().unwrap_or_else(|| self.active());
        self.handler(target)
    }
}

pub(crate) struct TextInputRouter {
    pub(crate) routes: Rc<RefCell<TextInputRoutes>>,
}

impl PlatformTextInputHandler for TextInputRouter {
    fn show_keyboard(&self) {
        let handler = self.routes.borrow_mut().take_show_target();
        if let Some(handler) = handler {
            handler.show_keyboard();
        }
    }

    fn hide_keyboard(&self) {
        let handler = self.routes.borrow_mut().take_hide_target();
        if let Some(handler) = handler {
            handler.hide_keyboard();
        }
    }
}

#[derive(Clone, Copy)]
pub(crate) enum SurfaceDirtyLane {
    Layout,
    Moved,
    Draw,
    LayerProperties,
    Structural,
}

fn append_surface_dirty_node(
    surface: &mut RootSurface<impl Renderer>,
    surface_index: usize,
    node: NodeId,
    lane: SurfaceDirtyLane,
    seen: &mut HashSet<(usize, NodeId)>,
) {
    // The scene update drops repeats of reshaped and moved nodes: the
    // reshaped ones go into a sorted partial list, the moved ones into its
    // dirty map. Both lists are taken by the frame that sees them.
    match lane {
        SurfaceDirtyLane::Layout => {
            surface.scene_dirty = true;
            surface.scoped_layout_scene_nodes.push(node);
        }
        SurfaceDirtyLane::Moved => {
            surface.scene_dirty = true;
            surface.scoped_moved_scene_nodes.push(node);
        }
        SurfaceDirtyLane::Draw => surface.scoped_draw_nodes.push(node),
        SurfaceDirtyLane::LayerProperties => surface.scoped_layer_property_nodes.push(node),
        SurfaceDirtyLane::Structural => {
            if seen.insert((surface_index, node)) {
                surface.structural_scene_nodes.push(node);
            }
        }
    }
}

// Routes `nodes` to the surfaces that show them. A lane with no nodes, as
// in most frames, returns before the routing's prologue.
#[inline]
pub(crate) fn route_nodes_by_surface<R: Renderer>(
    app: &mut ShellApp,
    surfaces: &mut [RootSurface<R>],
    nodes: impl IntoIterator<Item = NodeId>,
    lane: SurfaceDirtyLane,
    scratch: &mut SurfaceRoutingScratch,
) {
    let nodes = nodes.into_iter();
    if nodes.size_hint().1 == Some(0) {
        scratch.attached.clear();
        scratch.owners.clear();
        return;
    }
    route_batch_by_surface(app, surfaces, nodes, lane, scratch);
}

#[inline(never)]
fn route_batch_by_surface<R: Renderer>(
    app: &mut ShellApp,
    surfaces: &mut [RootSurface<R>],
    nodes: impl Iterator<Item = NodeId>,
    lane: SurfaceDirtyLane,
    scratch: &mut SurfaceRoutingScratch,
) {
    let Some(primary_root) = app.composition.root() else {
        scratch.attached.clear();
        scratch.owners.clear();
        return;
    };
    let mut applier = app.composition.applier_mut();
    applier.scene_nodes_attached_to_into(
        nodes,
        primary_root,
        &mut scratch.attached,
        &mut scratch.attachment,
    );
    if scratch.attached.is_empty() {
        scratch.owners.clear();
        return;
    }
    scratch.seen.clear();
    if app.app_context.window_roots().is_empty() {
        scratch.owners.clear();
        if let Some(index) = surfaces
            .iter()
            .position(|surface| surface.id == RootId::Primary)
        {
            let surface = &mut surfaces[index];
            for node in scratch.attached.iter().flatten().copied() {
                append_surface_dirty_node(surface, index, node, lane, &mut scratch.seen);
            }
        }
        return;
    }
    cranpose_ui::nearest_window_roots_into(
        &mut applier,
        scratch.attached.iter().flatten().copied(),
        &mut scratch.owners,
        &mut scratch.window_roots,
    );
    for (node, owner) in scratch.attached.iter().flatten().zip(&scratch.owners) {
        let node = *node;
        if let Some(index) = surfaces
            .iter()
            .position(|surface| surface.owns_nodes_under(*owner))
        {
            let surface = &mut surfaces[index];
            append_surface_dirty_node(surface, index, node, lane, &mut scratch.seen);
        }
    }
}

/// Routes the nodes a layout pass laid out again, `laid_out`, and the nodes
/// it only moved. A moved node is left out when the scene update of its
/// surface lays out its placer again: that update places every child of the
/// placer's layer anew, so the node's own record would be found and settled
/// there and nowhere else.
pub(crate) fn route_geometry_scene_nodes<R: Renderer>(
    app: &mut ShellApp,
    surfaces: &mut [RootSurface<R>],
    laid_out: impl IntoIterator<Item = NodeId>,
    moved: &[MovedSceneNode],
    scratch: &mut SurfaceRoutingScratch,
) {
    if moved.is_empty() {
        route_nodes_by_surface(app, surfaces, laid_out, SurfaceDirtyLane::Layout, scratch);
        return;
    }
    scratch.laid_out_starts.clear();
    scratch.laid_out_starts.extend(
        surfaces
            .iter()
            .map(|surface| surface.scoped_layout_scene_nodes.len()),
    );
    route_nodes_by_surface(app, surfaces, laid_out, SurfaceDirtyLane::Layout, scratch);
    let mut routed = std::mem::take(&mut scratch.moved);
    routed.clear();
    {
        let applier = app.composition.applier_mut();
        scratch.laid_out.reset(&applier);
        for (surface, &start) in surfaces.iter().zip(&scratch.laid_out_starts) {
            for &node in &surface.scoped_layout_scene_nodes[start..] {
                scratch.laid_out.set(&applier, node, 1);
            }
        }
        let marks = &scratch.laid_out;
        let window_roots = !app.app_context.window_roots().is_empty();
        // The children one node placed come together: their placer is
        // looked up once.
        let mut last_placer = None;
        for &moved in moved {
            let placed_again = moved.placer.is_some_and(|placer| match last_placer {
                Some((last, laid_out)) if last == placer => laid_out,
                _ => {
                    let laid_out = marks.get(&applier, placer) != 0;
                    last_placer = Some((placer, laid_out));
                    laid_out
                }
            });
            if !placed_again || window_roots && is_window_root(&applier, moved.node) {
                routed.push(moved.node);
            }
        }
    }
    route_nodes_by_surface(
        app,
        surfaces,
        routed.iter().copied(),
        SurfaceDirtyLane::Moved,
        scratch,
    );
    scratch.moved = routed;
}

/// Whether `node` is a window root, which goes to a surface of its own.
fn is_window_root(applier: &MemoryApplier, node: NodeId) -> bool {
    applier.get_ref(node).is_ok_and(|node| {
        let node: &dyn std::any::Any = node;
        node.downcast_ref::<LayoutNode>()
            .is_some_and(LayoutNode::is_window_root)
    })
}

/// One surface borrowed together with its shell: the handle a platform
/// delivers a window's events through and reads a window's frame from.
///
/// [`AppShell::surface`] hands one out per root. Every method of [`AppShell`]
/// that names no root acts on the primary surface through the same code, so
/// a single-window platform never sees this type.
pub struct SurfaceMut<'a, R: Renderer> {
    pub(crate) shell: &'a mut AppShell<R>,
    pub(crate) index: usize,
}

impl<'a, R> SurfaceMut<'a, R>
where
    R: Renderer,
    R::Error: Debug,
{
    pub(crate) fn new(shell: &'a mut AppShell<R>, index: usize) -> Self {
        Self { shell, index }
    }

    /// The whole app, for what a window's event needs beyond its surface:
    /// the clipboard, the dev options, a debug report.
    pub fn shell(&mut self) -> &mut AppShell<R> {
        self.shell
    }

    pub(crate) fn shell_app(&mut self) -> &mut ShellApp {
        &mut self.shell.app
    }

    pub(crate) fn shell_app_ref(&self) -> &ShellApp {
        &self.shell.app
    }

    pub(crate) fn surface(&self) -> &RootSurface<R> {
        &self.shell.surfaces[self.index]
    }

    pub(crate) fn surface_mut(&mut self) -> &mut RootSurface<R> {
        &mut self.shell.surfaces[self.index]
    }

    pub(crate) fn parts(&mut self) -> (&mut ShellApp, &mut RootSurface<R>) {
        let shell = &mut *self.shell;
        (&mut shell.app, &mut shell.surfaces[self.index])
    }

    /// Which root this surface draws.
    pub fn id(&self) -> RootId {
        self.surface().id
    }

    /// The node this surface draws from, when it has one.
    pub fn root(&self) -> Option<NodeId> {
        let surface = self.surface();
        surface.root_node(self.shell_app_ref())
    }

    /// The renderer that draws this surface.
    pub fn renderer(&mut self) -> &mut R {
        &mut self.surface_mut().renderer
    }

    /// Runs a presentation operation with this surface's app context active.
    /// Software text rasterization uses the context's font measurement services.
    pub fn with_renderer<T>(&mut self, block: impl FnOnce(&mut R) -> T) -> T {
        let (app, surface) = self.parts();
        app.app_context.enter(|| block(&mut surface.renderer))
    }

    /// The scene this surface last built.
    pub fn scene(&self) -> &R::Scene {
        self.surface().renderer.scene()
    }

    /// Sets the logical size this surface lays out and draws into.
    ///
    /// The primary surface's viewport is the composition root's constraints.
    /// A window surface's viewport is what its renderer draws into; the
    /// window root lays out to the size its descriptor reports, which the
    /// platform keeps equal to this. The next update lays out and renders;
    /// [`AppShell::set_viewport`] additionally runs that frame at once.
    pub fn set_viewport(&mut self, width: f32, height: f32) {
        self.surface_mut().viewport = (width, height);
        match self.id() {
            RootId::Primary => self.shell_app().request_forced_layout_pass(),
            RootId::Window(_) => {
                if let Some(root) = self.root() {
                    self.shell_app_ref()
                        .app_context
                        .enter(|| cranpose_ui::schedule_measure_repass(root));
                }
                self.shell_app().request_layout_pass();
            }
        }
        let root = self.root();
        self.surface_mut().invalidate_scene_root(root);
        self.mark_dirty();
    }

    /// Tells the shell where the window drawing this surface sits on the
    /// screen, in logical pixels, so pointer events can carry a
    /// [`screen_position`](cranpose_foundation::PointerEvent::screen_position).
    /// A platform sets it when the window moves and before it delivers a
    /// pointer sample; `None` says the platform does not know.
    pub fn set_screen_origin(&mut self, origin: Option<Point>) {
        self.surface_mut().screen_origin = origin;
    }

    /// Where the window drawing this surface sits on the screen, as the
    /// platform last said.
    pub fn screen_origin(&self) -> Option<Point> {
        self.surface().screen_origin
    }

    /// The logical size this surface draws into.
    pub fn viewport_size(&self) -> (f32, f32) {
        self.surface().viewport
    }

    /// Sets the physical size of this surface's framebuffer.
    pub fn set_buffer_size(&mut self, width: u32, height: u32) {
        self.surface_mut().buffer_size = (width, height);
    }

    /// The physical size of this surface's framebuffer.
    pub fn buffer_size(&self) -> (u32, u32) {
        self.surface().buffer_size
    }

    /// Marks this surface as needing a redraw.
    pub fn mark_dirty(&mut self) {
        self.surface_mut().is_dirty = true;
    }

    /// Whether this surface owes the display a frame: stale pixels, or a
    /// renderer that has not warmed its swapchain yet. See
    /// [`AppShell::needs_redraw`].
    pub fn needs_redraw(&self) -> bool {
        self.shell_app_ref()
            .app_context
            .enter(|| self.surface().needs_redraw_in_context(self.shell_app_ref()))
    }

    /// Whether a pointer button is held down on a control of this surface,
    /// whichever button it is.
    pub fn has_active_pointer_gesture(&self) -> bool {
        self.surface().has_active_pointer_gesture()
    }

    /// Whether the primary button is held down on a control of this
    /// surface. A platform that polls the mouse's primary button compares
    /// it with this, so a held right button does not look like a lost left
    /// release.
    pub fn has_active_primary_gesture(&self) -> bool {
        self.surface().has_active_primary_gesture()
    }

    /// What the update and frame produced for this surface the last time
    /// the app updated.
    pub fn last_update_result(&self) -> FrameUpdateResult {
        self.surface().last_update
    }

    /// Whether an update since the platform last presented this surface
    /// changed its pixels. An update runs for the whole app, so the update a
    /// platform ran for one window may have drawn another; this is how the
    /// other window learns it has a frame to show.
    pub fn frame_owed(&self) -> bool {
        self.surface().frame_owed
    }

    /// [`Self::frame_owed`], cleared: the platform is about to present.
    pub fn take_frame_owed(&mut self) -> bool {
        std::mem::take(&mut self.surface_mut().frame_owed)
    }

    fn compute_frame_schedule(&self) -> FrameSchedule {
        self.surface()
            .compute_frame_schedule(self.shell_app_ref(), self.shell.any_surface_dirty())
    }

    /// The frame this surface asks its platform for, recorded for
    /// [`Self::frame_scheduler_snapshot`].
    pub fn frame_schedule(&self) -> FrameSchedule {
        let schedule = self.compute_frame_schedule();
        self.surface().frame_scheduler.record(schedule);
        schedule
    }

    /// Computes this surface's frame schedule and applies it to `driver`.
    pub fn schedule_platform_frame<D>(&self, driver: &D) -> FrameSchedule
    where
        D: PlatformFrameDriver + ?Sized,
    {
        let schedule = self.compute_frame_schedule();
        self.surface().frame_scheduler.schedule(schedule, driver);
        schedule
    }

    /// The schedule this surface last recorded.
    pub fn frame_scheduler_snapshot(&self) -> FrameSchedule {
        self.surface().frame_scheduler.snapshot()
    }

    /// Sets how the platform should vote the display's frame rate for the
    /// window showing this surface. See [`AppShell::set_frame_rate_preference`].
    pub fn set_frame_rate_preference(&mut self, preference: FrameRatePreference) {
        self.surface_mut().frame_rate_preference = preference;
    }

    /// This surface's display frame-rate preference.
    pub fn frame_rate_preference(&self) -> FrameRatePreference {
        self.surface().frame_rate_preference
    }

    /// Where this surface's dev overlay draws the control for `mode`, in
    /// logical pixels. See [`AppShell::dev_overlay_control_center`].
    pub fn dev_overlay_control_center(&self, mode: FramePacingMode) -> Option<(f32, f32)> {
        self.surface().dev_overlay.control_center(mode)
    }

    pub(crate) fn dev_overlay_press(&mut self, x: f32, y: f32) -> bool {
        if !self.shell_app_ref().dev_options.frame_pacing_controls {
            return false;
        }
        let Some(mode) = self.surface().dev_overlay.control_at(x, y) else {
            return false;
        };
        self.shell().set_frame_pacing_mode(mode);
        true
    }

    /// Runs `block` with this surface's layout snapshot, built on demand.
    pub fn with_layout_tree<T>(&mut self, block: impl FnOnce(Option<&LayoutTree>) -> T) -> T {
        let (app, surface) = self.parts();
        let _app_context = app.app_context.enter_scope();
        block(surface.layout_tree_in_context(app))
    }

    /// Runs `block` with this surface's semantics snapshot, built on demand;
    /// `None` while semantics are disabled.
    pub fn with_semantics_tree<T>(&mut self, block: impl FnOnce(Option<&SemanticsTree>) -> T) -> T {
        let (app, surface) = self.parts();
        let _app_context = app.app_context.enter_scope();
        block(surface.semantics_tree_in_context(app))
    }

    /// The pointer icon the platform has not applied to this surface's
    /// window yet. See [`AppShell::take_pointer_icon_change`].
    pub fn take_pointer_icon_change(&self) -> Option<PointerIcon> {
        self.surface().pointer_icon.take_change()
    }

    /// Offers this surface's pointer icon to the platform again. See
    /// [`AppShell::refresh_pointer_icon`].
    pub fn refresh_pointer_icon(&self) {
        self.surface().pointer_icon.refresh();
    }

    /// Installs the platform text input for the window showing this
    /// surface. Keyboard requests reach the handler of the surface the
    /// platform last called active, and a hide reaches the handler that
    /// showed. See [`AppShell::set_platform_text_input`].
    pub fn set_platform_text_input(&mut self, handler: Rc<dyn PlatformTextInputHandler>) {
        let id = self.id();
        let app = self.shell_app();
        app.text_input_routes.borrow_mut().set_handler(id, handler);
        app.install_text_input_router();
    }

    /// Makes this the surface the platform considers focused: the one the
    /// soft keyboard belongs to. Pointer presses do this on their own.
    pub fn activate(&mut self) {
        let id = self.id();
        self.shell_app()
            .text_input_routes
            .borrow_mut()
            .set_active(id);
    }
}

#[expect(clippy::multiple_inherent_impl, reason = "one file per shell concern")]
impl<R> AppShell<R>
where
    R: Renderer,
    R::Error: Debug,
{
    /// Says whether a D-pad drives the primary window, as a TV's remote does.
    /// A remote acts only through focus, so while `dpad` is set a layout that
    /// leaves nothing focused gives focus to a target: the one that took the
    /// place of the target focus left, or the first one. An arrow moves focus
    /// out of a focused text field, and one that moves focus onto a field
    /// leaves the software keyboard closed until the center button opens it.
    pub fn set_dpad_navigation(&mut self, dpad: bool) {
        let primary = &mut self.surfaces[0];
        primary.dpad_navigation = dpad;
        primary.focus_check_due = dpad;
    }

    // Ends an update: the surfaces are clean, and after a layout the primary
    // window keeps a focused target when it is set to.
    pub(crate) fn end_update(&mut self, laid_out: bool) {
        for surface in &mut self.surfaces {
            surface.is_dirty = false;
        }
        let primary = &mut self.surfaces[0];
        if primary.dpad_navigation && (laid_out || primary.focus_check_due) {
            primary.focus_check_due = false;
            self.primary().keep_focus();
        }
    }
}