blockworx_egui/

view.rs

use std::cell::RefCell;
use std::rc::Rc;
use std::time::Duration;

use blockworx_doc::{block_model::Asset, hash::AssetHash};
use blockworx_geom::{Rect, WorldPx};
use blockworx_paint::edit::{EDITOR_BORDER, EDITOR_PAD, EDITOR_ROUNDING};
use blockworx_paint::ground::{GridLine, horizontals, verticals};
use blockworx_paint::{
    Button, Color, Cursor, DrawOp, EditColors, EditField, Factor, Input, Keys, Move, Raw, ScrollPx,
    TextEvent, Tick, Vantage,
};
use egui::{PointerButton, Sense, Stroke};

use crate::convert::{IntoEgui as _, IntoGeom};
use crate::image::ImageRegistry;
use crate::replay::replay;

pub use blockworx_paint::Camera;
/// The colours the canvas paints its own ground with, under the canvas's own
/// name for them.
pub use blockworx_paint::Ground as CanvasChrome;

fn grid_stroke(line: GridLine, color: Color) -> Stroke {
    Stroke::new(line.width(), color.egui())
}

/// Whether the key that turns a left-drag into a pan is held: **space**, the
/// convention across drawing and diagram editors (Figma, Illustrator, Inkscape,
/// Miro). A text editor owning the keyboard is typing, not panning.
fn pan_key_held(ui: &egui::Ui) -> bool {
    !ui.ctx().egui_wants_keyboard_input() && ui.input(|i| i.key_down(egui::Key::Space))
}

/// The canvas as egui shows it: the rect it is laid out in, the pointer and
/// the gestures over it, and the in-place editor drawn into it. Where the
/// diagram is shown *from* is the session's; this reads what would move it
/// and reports the move.
pub struct View {
    /// The in-place editor shown last frame and what has been typed into it,
    /// so a freshly-shown editor (different id, or none previously) opens on
    /// the request's text and grabs keyboard focus exactly once.
    draft: Option<Draft>,
    /// Whether the pointer was over the canvas response (not a floating overlay)
    /// as of the last [`Self::begin`]. Lets the app suppress the tool cursor when
    /// the pointer sits over the nav bar, toolbar, or selection overlay.
    hovered: bool,
    /// Whether the primary-button drag in progress is panning the canvas (it
    /// began with the [pan key](pan_key_held) held). Latched at drag start so
    /// releasing the key mid-drag can't hand a half-finished pan to a tool.
    primary_drag_pans: bool,
    /// Whether a two-finger gesture is in progress. `MultiTouchInfo` vanishes
    /// the instant a finger lifts, but the finger still down keeps arriving as
    /// an ordinary drag — so the latch holds the canvas until the last one
    /// leaves, rather than handing a half-finished pan to a tool.
    touch_pans: bool,
    /// What the last [`Self::begin`] made of the frame's camera input, kept for
    /// the chrome drawn after the canvas pass.
    camera: Camera,
    /// The artwork the display list may name, registered through
    /// [`Self::register_image`] as each asset's bytes are handed off.
    images: Rc<RefCell<ImageRegistry>>,
}

/// The frame clock as egui states it: the time, and how long it predicts
/// the frame will take, which is what the easing table reads ahead by.
pub fn tick(ctx: &egui::Context) -> Tick {
    let (now, predicted_dt) = ctx.input(|i| (i.time, i.predicted_dt));
    // A clock that ran backwards would be a broken host, not a lost frame:
    // fall back to zero rather than take the drawing down with it.
    Tick::predicting(
        Duration::try_from_secs_f64(now).unwrap_or_default(),
        Duration::try_from_secs_f32(predicted_dt).unwrap_or_default(),
    )
}

impl Default for View {
    fn default() -> Self {
        Self {
            draft: None,
            hovered: false,
            primary_drag_pans: false,
            touch_pans: false,
            camera: Camera::Settled,
            images: Rc::new(RefCell::new(ImageRegistry::default())),
        }
    }
}

impl View {
    /// Hand an asset's bytes to the loader under the hash the display list
    /// names it by. Idempotent, so a re-sent asset costs nothing.
    pub fn register_image(&self, ctx: &egui::Context, hash: AssetHash, asset: &Asset) {
        self.images.borrow_mut().register(ctx, hash, asset);
    }

    /// Whether the bytes behind `hash` have been registered — what a suite
    /// above this crate checks a hand-off reached the canvas by.
    #[cfg(any(test, feature = "test-support"))]
    pub fn holds_image(&self, hash: AssetHash) -> bool {
        self.images.borrow().uri(hash).is_some()
    }

    /// Whether the pointer was over the canvas (not a floating overlay) as of the
    /// last [`Self::begin`]. The app gates the tool cursor on this so it never
    /// leaks over the nav bar, toolbar, or selection overlay.
    pub fn canvas_hovered(&self) -> bool {
        self.hovered
    }

    /// Whether the camera is being worked, as of the last [`Self::begin`]. The
    /// selection overlay is drawn after the canvas pass and reads it there.
    pub fn camera(&self) -> Camera {
        self.camera
    }

    /// Id of the in-place editor rendered last frame. A fallback for surrendering
    /// editor focus when `Memory::focused` can't be trusted to name it.
    pub fn focused_edit_id(&self) -> Option<egui::Id> {
        self.draft.as_ref().map(|draft| draft.id)
    }

    /// Open the canvas frame: allocate the viewport and read this frame's
    /// pan/zoom — everything that would move the camera, and nothing that
    /// paints under it. The [`Canvas`] it answers with is a value, so the
    /// frame can carry it across whatever runs between reading the pointer
    /// and painting.
    pub fn begin(&mut self, ui: &mut egui::Ui) -> Canvas {
        let (rect, response) = ui.allocate_exact_size(ui.available_size(), Sense::click_and_drag());
        let diagram = ui.painter().add(egui::Shape::Noop);
        let rect = rect.geom();
        self.hovered = response.hovered();

        let mut moves = Vec::new();
        let pan = self.handle_pan_zoom(ui, &response, rect, &mut moves);
        self.camera = pan;

        Canvas {
            rect,
            response,
            diagram,
            pan,
            moves,
        }
    }

    /// Paint the frame: the ground and the grid under `diagram`'s camera,
    /// then its display list replayed over them, clipped to the canvas —
    /// into the slot [`Self::begin`] reserved, so it lies under whatever the
    /// frame placed over the canvas in between.
    /// Answers the cursor the pointer is left with: the diagram's own,
    /// unless the camera is being worked — an armed or in-progress pan owns
    /// the pointer.
    pub fn show(&mut self, ui: &egui::Ui, canvas: &Canvas, diagram: Diagram<'_>) -> Option<Cursor> {
        let painter = ui.painter().with_clip_rect(canvas.rect.egui());
        let mut shapes = View::grid(diagram.vantage, canvas.rect, diagram.ground);
        shapes.extend(replay(diagram.draw_list, &painter, &self.images.borrow()));
        painter.set(canvas.diagram, egui::Shape::Vec(shapes));
        if canvas.pan == Camera::Moving {
            Some(Cursor::Grabbing)
        } else if self.hovered && pan_key_held(ui) {
            Some(Cursor::Grab)
        } else {
            diagram.cursor
        }
    }

    /// Wheel zoom (centered on the cursor), two-finger pan/pinch, and drag pan —
    /// right/middle button, or the primary button with the [pan key](pan_key_held)
    /// held — each reported as a [`Move`] for the session to apply.
    fn handle_pan_zoom(
        &mut self,
        ui: &egui::Ui,
        response: &egui::Response,
        rect: Rect,
        moves: &mut Vec<Move>,
    ) -> Camera {
        if let Some(pan) = self.handle_touch_gesture(ui, response, moves) {
            return pan;
        }
        // `hovered()` is false when a floating overlay (the nav tree, toolbar, …)
        // sits under the pointer, so scrolling there scrolls that overlay instead
        // of also zooming the canvas.
        if response.hovered() {
            let cursor = ui
                .ctx()
                .pointer_hover_pos()
                .map_or(rect.center(), IntoGeom::geom);
            // A bare wheel zooms — this canvas has no document flow to scroll
            // past. egui diverts ctrl/⌘+wheel and trackpad pinch into
            // `zoom_delta` instead (leaving `smooth_scroll_delta` at zero), so
            // both channels are read: the modifier is optional, not a different
            // gesture.
            let (scroll, pinch) = ui.input(|i| (i.smooth_scroll_delta.y, i.zoom_delta()));
            let factor = Factor::of_scroll(ScrollPx::up(scroll)).get() * pinch;
            if factor != 1.0 {
                moves.push(Move::Zoom {
                    factor: Factor::new(factor),
                    anchor: cursor,
                });
            }
        }

        // A left-drag pans while the pan key is held, for pointing devices where
        // the other buttons are awkward. Shift+left-drag stays the selection
        // marquee (handled by the tools), so it is not a pan gesture.
        if response.drag_started() {
            self.primary_drag_pans = pan_key_held(ui);
        }
        // The latch also covers the frame the drag stops on, so the gesture's
        // closing event is consumed by the pan rather than reaching a tool.
        let primary_pan = self.primary_drag_pans
            && (response.dragged_by(PointerButton::Primary) || response.drag_stopped());
        if response.drag_stopped() {
            self.primary_drag_pans = false;
        }
        if primary_pan
            || response.dragged_by(PointerButton::Secondary)
            || response.dragged_by(PointerButton::Middle)
        {
            moves.push(Move::Pan(response.drag_delta().geom()));
            Camera::Moving
        } else {
            Camera::Settled
        }
    }

    /// Two fingers pan and pinch the canvas together, about the gesture's own
    /// center. `Some` means the gesture owns the frame — the primary finger also
    /// arrives as an ordinary drag, which a tool would otherwise read as a
    /// marquee or a wire.
    ///
    /// This is the only pan a touch screen has: it has no wheel, no middle
    /// button, and no space bar to hold.
    fn handle_touch_gesture(
        &mut self,
        ui: &egui::Ui,
        response: &egui::Response,
        moves: &mut Vec<Move>,
    ) -> Option<Camera> {
        let (gesture, touching) = ui.input(|i| (i.multi_touch(), i.any_touches()));
        if !touching {
            self.touch_pans = false;
            return None;
        }
        // A gesture that began on the canvas keeps it even if a finger strays
        // over an overlay; one that began on an overlay never takes it.
        let ours = self.touch_pans || response.hovered() || response.is_pointer_button_down_on();
        let Some(gesture) = gesture.filter(|_| ours) else {
            // The latch outlives `MultiTouchInfo`, which is gone the moment the
            // gesture drops back to one finger.
            return self.touch_pans.then_some(Camera::Moving);
        };
        self.touch_pans = true;
        moves.push(Move::Pan(gesture.translation_delta.geom()));
        if gesture.zoom_delta != 1.0 {
            moves.push(Move::Zoom {
                factor: Factor::new(gesture.zoom_delta),
                anchor: gesture.center_pos.geom(),
            });
        }
        Some(Camera::Moving)
    }

    /// The canvas background and the grid over it, in the chrome colors the
    /// caller already resolved rather than through the palette-based
    /// recording.
    fn grid(vantage: Vantage, rect: Rect, chrome: CanvasChrome) -> Vec<egui::Shape> {
        let down = verticals(vantage, rect).map(|(x, line)| {
            egui::Shape::vline(x, rect.y_range().egui(), grid_stroke(line, chrome.grid))
        });
        let across = horizontals(vantage, rect).map(|(y, line)| {
            egui::Shape::hline(rect.x_range().egui(), y, grid_stroke(line, chrome.grid))
        });
        std::iter::once(egui::Shape::rect_filled(
            rect.egui(),
            0.0,
            chrome.background.egui(),
        ))
        .chain(down)
        .chain(across)
        .collect()
    }

    /// The editor the last call asked for, run as egui's own text field
    /// over the diagram: it keeps the draft, the caret and the selection,
    /// and says only how the edit ended. `angle` is not honoured — egui
    /// cannot rotate a `TextEdit` — so a vertical label is edited upright.
    pub fn capture(
        &mut self,
        ui: &mut egui::Ui,
        field: Option<&EditField>,
        vantage: Vantage,
    ) -> Option<TextEvent> {
        let Some(edit) = field else {
            self.draft = None;
            return None;
        };
        let id = edit.id;
        let edit_id = id.egui();
        let (draft, opening) = match &mut self.draft {
            Some(draft) if draft.id == edit_id => (draft, false),
            slot => (
                slot.insert(Draft {
                    id: edit_id,
                    text: edit.text.clone(),
                }),
                true,
            ),
        };
        if opening {
            // Where the edit opens: the whole text selected where the
            // request asks for that, so typing replaces it, else the caret
            // after it.
            let chars = draft.text.chars().count();
            let range = if edit.tab_cycle || edit.select_all_on_focus {
                egui::text::CCursorRange::two(
                    egui::text::CCursor::new(0),
                    egui::text::CCursor::new(chars),
                )
            } else {
                egui::text::CCursorRange::one(egui::text::CCursor::new(chars))
            };
            let mut state =
                egui::text_edit::TextEditState::load(ui.ctx(), edit_id).unwrap_or_default();
            state.cursor.set_char_range(Some(range));
            state.store(ui.ctx(), edit_id);
        }
        let screen_font = vantage.remap_font(&edit.font).egui();
        let ink = edit.colors.text.egui();
        let layout_font = screen_font.clone();
        let wrap_px = edit.wrap_width.map(|w| w.get() * vantage.zoom.get());
        let mut wrap_at = move |ui: &egui::Ui, buf: &dyn egui::TextBuffer, _avail: f32| {
            let job = egui::text::LayoutJob::simple(
                buf.as_str().to_owned(),
                layout_font.clone(),
                ink,
                wrap_px.unwrap_or(f32::INFINITY),
            );
            ui.fonts_mut(|f| f.layout_job(job))
        };
        let mut widget = if edit.multiline {
            egui::TextEdit::multiline(&mut draft.text)
        } else {
            egui::TextEdit::singleline(&mut draft.text)
        }
        .id(edit_id)
        .desired_width(f32::INFINITY)
        .font(screen_font)
        .frame(editor_frame(&edit.colors, vantage))
        .min_size(edit.rect.size().egui())
        .desired_rows(1)
        .horizontal_align(edit.align.x().egui())
        .vertical_align(edit.align.y().egui())
        .text_color(ink)
        .layouter(&mut wrap_at);
        if let Some(hint) = &edit.hint {
            widget =
                widget.hint_text(egui::RichText::new(hint.as_ref()).color(edit.colors.hint.egui()));
        }
        if let Some(limit) = edit.char_limit {
            widget = widget.char_limit(limit);
        }
        let resp = ui
            .scope(|ui| {
                let visuals = ui.visuals_mut();
                visuals.selection.bg_fill = edit.colors.selection.egui();
                visuals.selection.stroke = egui::Stroke::NONE;
                visuals.text_cursor.stroke.color = edit.colors.caret.egui();
                ui.place(edit.rect.egui(), widget)
            })
            .inner;
        // Escape is the editor's, and Tab a cycle editor's. egui's focus
        // system moves focus on Tab and clears it on Escape at the *start* of
        // the next frame unless the focused widget's filter claims them, and
        // the field sets a filter of its own as it is placed — so this one is
        // set after it. (The field never inserts a tab: it reads events with
        // its own filter, which still excludes Tab.)
        ui.memory_mut(|m| {
            m.set_focus_lock_filter(
                edit_id,
                egui::EventFilter {
                    horizontal_arrows: true,
                    vertical_arrows: true,
                    tab: edit.tab_cycle,
                    escape: true,
                },
            );
        });
        // Auto-focus an editor the first frame it appears so the user can
        // type immediately (e.g. right after creating a text box) without a
        // separate click into the field.
        if opening {
            resp.request_focus();
        }
        if resp.has_focus() {
            let (tab, escape) = ui.input_mut(|i| {
                (
                    edit.tab_cycle && i.consume_key(egui::Modifiers::NONE, egui::Key::Tab),
                    i.consume_key(egui::Modifiers::NONE, egui::Key::Escape),
                )
            });
            if tab {
                return Some(TextEvent::TabPressed {
                    id,
                    text: draft.text.clone(),
                });
            }
            if escape {
                return Some(TextEvent::Cancelled { id });
            }
        }
        resp.lost_focus().then(|| TextEvent::Committed {
            id,
            text: draft.text.clone(),
        })
    }
}

/// The draft the editor holds between frames: egui's field edits a buffer
/// the caller keeps.
struct Draft {
    id: egui::Id,
    text: String,
}

/// The field as an opaque plate ringed in the editor's border, so it reads
/// as standing over the drawing rather than as more of it. Its geometry is
/// the one the kernel sized the field by.
fn editor_frame(colors: &EditColors, vantage: Vantage) -> egui::Frame {
    let margin = |len: f32| vantage.remap_len(WorldPx::new(len)).round() as i8;
    egui::Frame::new()
        .fill(colors.background.egui())
        .stroke(egui::Stroke::new(
            vantage.remap_len(EDITOR_BORDER),
            colors.border.egui(),
        ))
        .corner_radius(vantage.remap_len(EDITOR_ROUNDING))
        .inner_margin(egui::Margin::symmetric(
            margin(EDITOR_PAD.x),
            margin(EDITOR_PAD.y),
        ))
}

/// What a call answered for the canvas: the display list, the camera it
/// was painted under, the colours under it, and the cursor it left.
#[derive(Clone, Copy)]
pub struct Diagram<'a> {
    pub draw_list: &'a [DrawOp],
    pub vantage: Vantage,
    pub ground: CanvasChrome,
    pub cursor: Option<Cursor>,
}

/// One canvas frame as the pointer left it: the rect it was laid out in,
/// the moves it read for the session to apply, and the raw input the
/// session resolves. A value rather than a borrow of the view, so the
/// frame can call the editor between reading its input and painting.
pub struct Canvas {
    rect: Rect,
    response: egui::Response,
    /// Where the diagram is painted, reserved as the canvas is laid out.
    diagram: egui::layers::ShapeIdx,
    pan: Camera,
    moves: Vec<Move>,
}

impl Canvas {
    /// The screen rect this frame paints into.
    pub fn viewport(&self) -> Rect {
        self.rect
    }

    /// What the pointer did to the camera this frame — a drag pan, a wheel
    /// notch, a pinch — in the order it happened, for the session to apply
    /// before the pointer is resolved.
    pub fn moves(&mut self) -> Vec<Move> {
        std::mem::take(&mut self.moves)
    }

    /// What the pointer and the keys did this frame, as the core resolves
    /// them: the pointer's motions and button edges while it is over the
    /// canvas or holding a press that began there, its leaving otherwise,
    /// and a pan in progress, which owns the pointer.
    ///
    /// Presses that began on a toolbar button never arrive: holding one —
    /// whose screen point maps to some world position — must not arm a
    /// canvas affordance. egui keeps that promise for chrome in a layer of
    /// its own; for chrome the host draws in the canvas's layer it counts
    /// the canvas as hovered on the press and not on the release, so the
    /// host names the rects of such chrome as `glass`, and a press on one
    /// is not taken either.
    pub fn input(&self, ui: &egui::Ui, glass: &[Rect]) -> Input {
        let response = &self.response;
        let over = response.hovered();
        let held_here = response.is_pointer_button_down_on();
        let mut raw = Vec::new();
        if over || held_here {
            ui.input(|input| {
                for event in &input.events {
                    match *event {
                        egui::Event::PointerMoved(pos) => raw.push(Raw::Moved(pos.geom())),
                        egui::Event::PointerButton {
                            pos,
                            button,
                            pressed,
                            ..
                        } => {
                            let Some(button) = button_of(button) else {
                                continue;
                            };
                            let pos = pos.geom();
                            if pressed && glass.iter().any(|rect| rect.contains(pos)) {
                                continue;
                            }
                            raw.push(if pressed {
                                Raw::Down { pos, button }
                            } else {
                                Raw::Up { pos, button }
                            });
                        }
                        egui::Event::PointerGone => raw.push(Raw::Gone),
                        _ => {}
                    }
                }
            });
            // A pointer that stood still while the chrome under it went away
            // is over the canvas now without having moved onto it.
            if over
                && !raw.iter().any(|raw| matches!(raw, Raw::Moved(_)))
                && let Some(pos) = response.hover_pos()
            {
                raw.push(Raw::Moved(pos.geom()));
            }
        } else {
            raw.push(Raw::Gone);
        }
        // egui abandons a drag on Escape, whatever holds the keyboard.
        if ui.input(|input| input.key_pressed(egui::Key::Escape)) {
            raw.push(Raw::Cancelled);
        }
        if self.pan == Camera::Moving {
            raw.push(Raw::Panning);
        }
        let keys = keys(response, ui);
        Input { raw, keys }
    }
}

fn button_of(button: PointerButton) -> Option<Button> {
    match button {
        PointerButton::Primary => Some(Button::Primary),
        PointerButton::Secondary => Some(Button::Secondary),
        PointerButton::Middle => Some(Button::Middle),
        PointerButton::Extra1 | PointerButton::Extra2 => None,
    }
}

/// The keys the frame carries, scoped by who holds the keyboard.
fn keys(response: &egui::Response, ui: &egui::Ui) -> Keys {
    // Any other widget owning the keyboard — a rename TextEdit, the nav
    // dialog's filter box, the command palette — claims these keys, so a
    // Backspace editing its text must not delete the selected shape and its
    // Escape must not cancel an in-progress gesture.
    let other_focus = ui.memory(|m| m.focused().is_some_and(|id| id != response.id));
    let canvas_keys = !response.has_focus() && !other_focus;
    Keys {
        escape: canvas_keys && ui.input(|i| i.key_pressed(egui::Key::Escape)),
        delete: canvas_keys
            && ui
                .input(|i| i.key_pressed(egui::Key::Delete) || i.key_pressed(egui::Key::Backspace)),
        shift: ui.input(|i| i.modifiers.shift),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_geom::{Pos2, Vec2, pos2};
    use blockworx_paint::{EditId, Font, Zoom};

    /// Nothing painted, under a camera at rest.
    fn at_rest(ground: CanvasChrome) -> Diagram<'static> {
        Diagram {
            draw_list: &[],
            vantage: Vantage::resting(),
            ground,
            cursor: None,
        }
    }

    /// One frame of the canvas, fed `events`, returning the raw input the
    /// core would resolve and the camera moves it would apply.
    fn frame(
        ctx: &egui::Context,
        view: &mut View,
        events: Vec<egui::Event>,
    ) -> (Vec<Raw>, Vec<Move>) {
        let screen = Rect::from_min_size(Pos2::ZERO, Vec2::new(800.0, 600.0));
        let input = egui::RawInput {
            screen_rect: Some(screen.egui()),
            events,
            ..Default::default()
        };
        let mut seen = (Vec::new(), Vec::new());
        let chrome = CanvasChrome {
            background: Color::BLACK,
            grid: Color::GRAY,
        };
        ctx.run_ui(input, |ui| {
            let mut canvas = view.begin(ui);
            seen = (canvas.input(ui, &[]).raw, canvas.moves());
            view.show(ui, &canvas, at_rest(chrome));
        })
        .drop_without_applying_deltas();
        seen
    }

    /// Whether a frame's raw input is a pan's — the core makes no tool
    /// gesture of a panning frame — or a gesture the tools may read.
    fn panning(seen: &[Raw]) -> bool {
        seen.contains(&Raw::Panning)
    }

    fn key_down(key: egui::Key) -> egui::Event {
        egui::Event::Key {
            key,
            physical_key: None,
            pressed: true,
            repeat: false,
            modifiers: egui::Modifiers::default(),
        }
    }

    fn key_up(key: egui::Key) -> egui::Event {
        egui::Event::Key {
            key,
            physical_key: None,
            pressed: false,
            repeat: false,
            modifiers: egui::Modifiers::default(),
        }
    }

    /// The primary button going down at `pos` (these tests never release it —
    /// every gesture under test is judged mid-drag).
    fn press(pos: Pos2) -> egui::Event {
        egui::Event::PointerButton {
            pos: pos.egui(),
            button: PointerButton::Primary,
            pressed: true,
            modifiers: egui::Modifiers::default(),
        }
    }

    /// Space+left-drag pans (the drawing-app convention), and the tool must not
    /// also see the drag — the view consumes it.
    #[test]
    fn space_plus_left_drag_pans_instead_of_reaching_the_tool() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let start = pos2(400.0, 300.0);
        frame(&ctx, &mut view, vec![key_down(egui::Key::Space)]);
        frame(
            &ctx,
            &mut view,
            vec![egui::Event::PointerMoved(start.egui())],
        );
        frame(&ctx, &mut view, vec![press(start)]);
        let (seen, moves) = frame(
            &ctx,
            &mut view,
            vec![egui::Event::PointerMoved(
                (start + Vec2::new(60.0, -25.0)).egui(),
            )],
        );
        assert_eq!(moves, vec![Move::Pan(Vec2::new(60.0, -25.0))]);
        assert!(panning(&seen), "the pan leaked to the tool as {seen:?}");
    }

    /// The same drag without the key belongs to the tool: no pan, and the tool
    /// sees the gesture.
    #[test]
    fn a_plain_left_drag_is_left_to_the_tool() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let start = pos2(400.0, 300.0);
        frame(
            &ctx,
            &mut view,
            vec![egui::Event::PointerMoved(start.egui())],
        );
        frame(&ctx, &mut view, vec![press(start)]);
        let (seen, moves) = frame(
            &ctx,
            &mut view,
            vec![egui::Event::PointerMoved(
                (start + Vec2::new(60.0, -25.0)).egui(),
            )],
        );
        assert!(moves.is_empty(), "a plain drag must not pan: {moves:?}");
        assert!(
            !panning(&seen) && seen.iter().any(|raw| matches!(raw, Raw::Moved(_))),
            "the tool never saw the drag ({seen:?})"
        );
    }

    /// Releasing the key mid-drag leaves the gesture a pan: it was latched when
    /// the drag began, so no tool inherits a half-finished pan.
    #[test]
    fn releasing_the_key_mid_drag_keeps_panning() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let start = pos2(400.0, 300.0);
        frame(&ctx, &mut view, vec![key_down(egui::Key::Space)]);
        frame(
            &ctx,
            &mut view,
            vec![egui::Event::PointerMoved(start.egui())],
        );
        frame(&ctx, &mut view, vec![press(start)]);
        let mut at = start + Vec2::new(30.0, 0.0);
        frame(&ctx, &mut view, vec![egui::Event::PointerMoved(at.egui())]);
        at += Vec2::new(20.0, 10.0);
        let (seen, moves) = frame(
            &ctx,
            &mut view,
            vec![
                key_up(egui::Key::Space),
                egui::Event::PointerMoved(at.egui()),
            ],
        );
        assert_eq!(moves, vec![Move::Pan(Vec2::new(20.0, 10.0))]);
        assert!(panning(&seen), "{seen:?}");
    }

    /// One finger's touch event. A touch screen delivers every finger; egui
    /// derives the pinch and the two-finger translation from the set.
    fn touch(id: u64, phase: egui::TouchPhase, pos: Pos2) -> egui::Event {
        egui::Event::Touch {
            device_id: egui::TouchDeviceId(0),
            id: egui::TouchId(id),
            phase,
            pos: pos.egui(),
            force: None,
        }
    }

    /// Both fingers of a two-finger gesture moving to `at`, plus the primary
    /// finger's pointer event — which is what the web backend also sends, and
    /// what a tool would read as a drag if the view didn't consume it.
    fn two_fingers(phase: egui::TouchPhase, at: [Pos2; 2]) -> Vec<egui::Event> {
        vec![
            egui::Event::PointerMoved(at[0].egui()),
            touch(0, phase, at[0]),
            touch(1, phase, at[1]),
        ]
    }

    /// Put two fingers down on `at` and hold them there for one frame. The
    /// leading empty frame gives egui the canvas rect to hit-test the press
    /// against; adding a finger makes the touch averages jump, so egui withholds
    /// a delta until the frame after that.
    fn start_two_finger_gesture(ctx: &egui::Context, view: &mut View, at: [Pos2; 2]) {
        frame(ctx, view, Vec::new());
        let mut down = two_fingers(egui::TouchPhase::Start, at);
        down.push(press(at[0]));
        frame(ctx, view, down);
        frame(ctx, view, two_fingers(egui::TouchPhase::Move, at));
    }

    /// Two fingers pan the canvas. This is the only pan a touch screen has —
    /// there is no wheel, no middle button, and no space bar — and egui reports
    /// it *only* through `multi_touch`: a touch drag leaves `smooth_scroll_delta`
    /// at zero, so a view that reads scroll alone never moves.
    #[test]
    fn two_fingers_pan_the_canvas() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let start = [pos2(360.0, 300.0), pos2(440.0, 300.0)];
        let step = Vec2::new(20.0, -12.0);

        start_two_finger_gesture(&ctx, &mut view, start);
        frame(
            &ctx,
            &mut view,
            two_fingers(egui::TouchPhase::Move, start.map(|p| p + step)),
        );
        let (seen, moves) = frame(
            &ctx,
            &mut view,
            two_fingers(egui::TouchPhase::Move, start.map(|p| p + step * 2.0)),
        );

        assert_eq!(
            moves,
            vec![Move::Pan(step)],
            "the canvas did not follow the fingers, or zoomed though they held their spacing"
        );
        assert!(
            panning(&seen),
            "the primary finger reached the tool as a drag ({seen:?})"
        );
    }

    /// Spreading the fingers zooms about the gesture's own center, holding the
    /// world under it — the pinch counterpart of the wheel's zoom-about-cursor.
    #[test]
    fn pinching_zooms_about_the_gesture_center() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let center = pos2(400.0, 300.0);
        let reach = Vec2::new(40.0, 0.0);
        let start = [center - reach, center + reach];

        start_two_finger_gesture(&ctx, &mut view, start);

        let (_, moves) = frame(
            &ctx,
            &mut view,
            two_fingers(
                egui::TouchPhase::Move,
                [center - reach * 2.0, center + reach * 2.0],
            ),
        );

        let Some(Move::Zoom { factor, anchor }) = moves
            .iter()
            .find(|moved| matches!(moved, Move::Zoom { .. }))
        else {
            panic!("spreading the fingers reported no zoom: {moves:?}");
        };
        assert!(
            factor.get() > 1.5,
            "spreading the fingers should have doubled the zoom, got {factor:?}"
        );
        assert_eq!(*anchor, center, "the pinch zooms about its own centre");
    }

    /// Lifting one of two fingers must not hand the remaining one to a tool: the
    /// gesture owns the canvas until the last finger leaves.
    #[test]
    fn the_last_finger_of_a_pan_never_becomes_a_tool_drag() {
        let ctx = egui::Context::default();
        let mut view = View::default();
        let start = [pos2(360.0, 300.0), pos2(440.0, 300.0)];
        let step = Vec2::new(25.0, 0.0);

        start_two_finger_gesture(&ctx, &mut view, start);
        frame(
            &ctx,
            &mut view,
            two_fingers(egui::TouchPhase::Move, start.map(|p| p + step)),
        );
        // Second finger up; the first keeps sliding.
        frame(
            &ctx,
            &mut view,
            vec![touch(1, egui::TouchPhase::End, start[1] + step)],
        );
        let (seen, _) = frame(
            &ctx,
            &mut view,
            vec![
                egui::Event::PointerMoved((start[0] + step * 2.0).egui()),
                touch(0, egui::TouchPhase::Move, start[0] + step * 2.0),
            ],
        );
        assert!(
            panning(&seen),
            "the trailing finger reached the tool as a drag ({seen:?})"
        );

        // Once every finger is up the canvas is the tool's again.
        frame(
            &ctx,
            &mut view,
            vec![touch(0, egui::TouchPhase::End, start[0] + step * 2.0)],
        );
        assert!(!view.touch_pans, "the gesture latch outlived the gesture");
    }

    /// An open in-place editor must not hammer repaints. On the desktop a
    /// repaint storm is a warm fan; in a browser tab on a tablet it is an app
    /// that stops answering, and the editor is the one thing there that cannot
    /// be dismissed without a keyboard.
    #[test]
    fn an_open_editor_settles() {
        let mut view = View::default();
        let chrome = CanvasChrome {
            background: Color::BLACK,
            grid: Color::GRAY,
        };
        let field = EditField {
            id: EditId::of("settle_title_edit"),
            rect: Rect::from_min_size(pos2(100.0, 100.0), Vec2::new(120.0, 20.0)),
            angle: blockworx_geom::Angle::ZERO,
            font: Font::proportional(14.0),
            align: blockworx_geom::Align2::LEFT_CENTER,
            wrap_width: None,
            text: "Amplifier".to_owned(),
            multiline: false,
            char_limit: Some(blockworx_geom::grid::MAX_LABEL_CHARS),
            tab_cycle: true,
            select_all_on_focus: false,
            hint: None,
            colors: blockworx_paint::EditColors {
                text: Color::WHITE,
                background: Color::BLACK,
                caret: Color::WHITE,
                selection: Color::GRAY,
                hint: Color::GRAY,
                border: Color::WHITE,
            },
        };
        let settle = crate::settle::probe(30, |ui| {
            // The caret's blink is the editor's own timed wake, not the
            // hammering this is looking for; it would otherwise vary the
            // shape count.
            ui.style_mut().visuals.text_cursor.blink = false;
            let canvas = view.begin(ui);
            view.show(ui, &canvas, at_rest(chrome));
            let _ = view.capture(ui, Some(&field), Vantage::resting());
        });
        crate::settle::assert_settles(&settle, 8);
    }

    #[test]
    fn frame_zoom_clamps_huge_content_to_the_floor() {
        let viewport = Vec2::new(800.0, 600.0);
        let huge = Vec2::new(100_000.0, 100_000.0);
        assert_eq!(
            Zoom::framing(viewport, huge, Zoom::max_value()),
            Zoom::min_value()
        );
    }
}