egui_map/

map.rs

//! Interactive map widget and the data types it renders.
//!
//! [`Map`] is an [`egui::Widget`] that draws a 2D set of nodes
//! ([`objects::MapPoint`]), the connection lines between them
//! ([`objects::MapSegment`]) and free-floating text labels
//! ([`objects::MapLabel`]). Nodes are indexed in a kd-tree so that only the
//! ones inside the current viewport are painted each frame.
//!
//! ## Coordinate model
//!
//! The widget works with two coordinate spaces:
//!
//! - **Map coordinates**: the logical position of your nodes, as loaded through
//!   [`Map::add_hashmap_points`].
//! - **Screen coordinates**: positions inside the widget's rectangle on screen.
//!
//! Both are related by the current zoom factor and viewport origin:
//! `screen = map * zoom - origin`. Use [`Map::set_zoom`], [`Map::set_pos`] and
//! [`Map::set_pos_from_nodeid`] to control the visible region.
//!
//! ## Connecting nodes with lines
//!
//! Lines are wired up in three steps:
//!
//! 1. Create the nodes as a [`HashMap`] keyed by node id.
//! 2. For every connection, choose a unique `(usize, usize)` id -- typically
//!    the pair of node ids it joins -- and push it into
//!    [`MapPoint::connections`] of **both** endpoint nodes.
//! 3. Load the nodes with [`Map::add_hashmap_points`], then load a
//!    [`HashMap`] of [`MapSegment`] keyed by those same connection ids and
//!    add it to the widget with [`Map::add_hashmap_lines`].
//!
//! ```
//! use egui_map::map::Map;
//! use egui_map::map::objects::{MapPoint, MapSegment};
//! use std::collections::HashMap;
//!
//! // 1. Create the nodes.
//! let mut points: HashMap<usize, MapPoint> = HashMap::new();
//! points.insert(1, MapPoint::new(1, [0.0, 0.0]));
//! points.insert(2, MapPoint::new(2, [10.0, 10.0]));
//!
//! // 2. Register the connection id on both endpoints.
//! for id in [1, 2] {
//!     points.get_mut(&id).unwrap().connections.push((1, 2));
//! }
//!
//! let mut map = Map::new();
//! map.add_hashmap_points(points);
//!
//! // 3. Provide the line geometry keyed by the same connection id.
//! let mut lines: HashMap<(usize, usize), MapSegment> = HashMap::new();
//! lines.insert((1, 2), MapSegment::new((1, 2), [0.0, 0.0], [10.0, 10.0]));
//! map.add_hashmap_lines(lines);
//! ```
//!
//! A line is only drawn while the zoom level is above
//! [`MapSettings::line_visible_zoom`] and its bounding box intersects the
//! viewport. Segments are culled broad-phase with an R-tree built by
//! [`Map::add_lines`], so long lines crossing the view are drawn even when
//! both endpoints lie outside of it.
//!
//! ## Custom node rendering
//!
//! Install a [`NodeTemplate`] implementation with [`Map::set_node_template`]
//! to take over the rendering of nodes, selection highlights, notification
//! animations and markers. Note that this replaces
//! *all* built-in node rendering, including the node name labels: draw them
//! yourself in [`NodeTemplate::node_ui`] if you need them.

use crate::map::animation::Animation;
use crate::map::objects::{
    ContextMenuManager, MapBounds, MapLabel, MapPoint, MapSegment, MapSettings, MapStyle,
    NodeAnimation, RawLine, RawPoint, SteadyAnimation, TextSettings, VisibilitySetting,
};
use egui::{widgets::*, *};
use kdtree::KdTree;
use kdtree::distance::squared_euclidean;
use std::collections::HashMap;
use std::rc::Rc;
use std::time::Instant;

use self::objects::NodeTemplate;

pub mod animation;
pub mod objects;

/// An interactive 2D map widget.
///
/// `Map` renders a set of nodes ([`objects::MapPoint`]), connection lines
/// ([`objects::MapSegment`]) and text labels ([`objects::MapLabel`]). The user can
/// pan the view by dragging and zoom with the mouse wheel (hold `Ctrl` — or
/// `Cmd` on macOS — to zoom faster), or use the built-in zoom slider drawn at
/// the top-right corner of the widget.
///
/// The map is fed through [`Map::add_hashmap_points`], which also builds the
/// internal kd-tree used for viewport culling and nearest-node hover queries.
/// Behavior and appearance are configured through the public
/// [`settings`](Map::settings) field (see [`objects::MapSettings`]).
///
/// Rendering of nodes and their visual effects (selection highlight,
/// notifications and markers) can be fully customized by installing a
/// [`objects::NodeTemplate`] implementation with [`Map::set_node_template`];
/// likewise, a right-click context menu can be provided with
/// [`Map::set_context_manager`].
///
/// # Examples
///
/// ```no_run
/// # fn example(ui: &mut egui::Ui) {
/// use egui_map::map::Map;
/// use egui_map::map::objects::MapPoint;
/// use std::collections::HashMap;
///
/// let mut points = HashMap::new();
/// points.insert(1, MapPoint::new(1, [0.0, 0.0]));
///
/// let mut map = Map::new();
/// map.add_hashmap_points(points);
///
/// // Every frame, inside your egui update logic:
/// ui.add(&mut map);
/// # }
/// ```
#[derive(Clone)]
pub struct Map {
    zoom: f32,
    previous_zoom: f32,
    points: Option<HashMap<usize, MapPoint>>,
    segments: Option<rstar::RTree<MapSegment>>,
    labels: Vec<MapLabel>,
    tree: Option<KdTree<f32, usize, [f32; 2]>>,
    visible_points: Vec<isize>,
    map_area: Rect,
    reference: MapBounds,
    current: MapBounds,
    current_index: usize,
    notifications: HashMap<usize, Notification>,
    node_states: HashMap<usize, NodeState>,
    min_size: (Option<f32>, Option<f32>),
    max_size: (Option<f32>, Option<f32>),
    /// Behavior and appearance configuration (zoom limits, visibility
    /// thresholds and per-theme styles). See [`objects::MapSettings`].
    pub settings: MapSettings,
    menu_manager: Option<Rc<dyn ContextMenuManager>>,
    node_template: Option<Rc<dyn NodeTemplate>>,
    markers: HashMap<usize, usize>,
}

/// A one-off effect attached to a node, with the moment it started.
#[derive(Clone, Copy, Debug)]
struct Notification {
    started: Instant,
    animation: NodeAnimation,
    /// `None` falls back to the current style's `alert_color`.
    color: Option<Color32>,
}

/// Lasting state attached to a node, drawn until it is cleared.
#[derive(Clone, Copy, Debug)]
struct NodeState {
    animation: SteadyAnimation,
    /// `None` falls back to the current style's `alert_color`.
    color: Option<Color32>,
}

/// A borrowed node, obtained from [`Map::node`], that an animation can be
/// attached to.
///
/// Modifiers such as [`NodeHandle::color`] come first; the effect method is the
/// terminal call that writes everything at once. A modifier on its own does
/// nothing, so there is no way to configure a notification that does not exist.
///
/// Effects come in two families, and which one you call decides how it ends:
///
/// - [`pulse`](Self::pulse), [`ripple`](Self::ripple),
///   [`countdown`](Self::countdown), [`scale_in`](Self::scale_in) and
///   [`crosshair`](Self::crosshair) play once from the [`Instant`] you pass and
///   stop on their own.
/// - [`halo`](Self::halo), [`blink`](Self::blink) and [`orbit`](Self::orbit)
///   are lasting state: they run until [`clear`](Self::clear), and keep the app
///   repainting the whole time.
///
/// A node can carry one of each at once; the state is drawn underneath the
/// event.
pub struct NodeHandle<'a> {
    map: &'a mut Map,
    id: usize,
    color: Option<Color32>,
}

impl NodeHandle<'_> {
    /// Overrides the colour of the effect about to be attached.
    ///
    /// Without this the effect uses the current style's `alert_color`.
    pub fn color(mut self, color: Color32) -> Self {
        self.color = Some(color);
        self
    }

    fn notify_with(self, animation: NodeAnimation, at: Instant) {
        self.map.notifications.insert(
            self.id,
            Notification {
                started: at,
                animation,
                color: self.color,
            },
        );
    }

    fn set_state(self, animation: SteadyAnimation) {
        self.map.node_states.insert(
            self.id,
            NodeState {
                animation,
                color: self.color,
            },
        );
    }

    /// Expanding, fading disc. Reads as "one thing happened here".
    pub fn pulse(self, at: Instant) {
        self.notify_with(NodeAnimation::Pulse, at);
    }

    /// Three staggered expanding rings. Reads as "activity is ongoing".
    pub fn ripple(self, at: Instant) {
        self.notify_with(NodeAnimation::Ripple, at);
    }

    /// A ring emptying clockwise. Reads as "how old is this information".
    pub fn countdown(self, at: Instant) {
        self.notify_with(NodeAnimation::CountdownArc, at);
    }

    /// A disc that overshoots and settles. For a node that just appeared.
    pub fn scale_in(self, at: Instant) {
        self.notify_with(NodeAnimation::ScaleIn, at);
    }

    /// Four ticks converging on the node. Reads as "target acquired".
    pub fn crosshair(self, at: Instant) {
        self.notify_with(NodeAnimation::Crosshair, at);
    }

    /// Lasting ring whose opacity breathes. Runs until [`Self::clear`].
    pub fn halo(self) {
        self.set_state(SteadyAnimation::Halo);
    }

    /// Lasting thick ring blinking on and off. Runs until [`Self::clear`].
    pub fn blink(self) {
        self.set_state(SteadyAnimation::Blink);
    }

    /// Lasting dot circling the node. Runs until [`Self::clear`].
    pub fn orbit(self) {
        self.set_state(SteadyAnimation::Orbit);
    }

    /// Removes both the notification and the lasting state of this node.
    pub fn clear(self) {
        self.map.notifications.remove(&self.id);
        self.map.node_states.remove(&self.id);
    }
}

impl Default for Map {
    /// Creates an empty map; equivalent to [`Map::new`].
    fn default() -> Self {
        Map::new()
    }
}

impl Widget for &mut Map {
    /// Renders the map, handling panning (drag), zooming (mouse wheel) and the
    /// right-click context menu if one was installed.
    fn ui(self, ui: &mut egui::Ui) -> Response {
        let rect = self.calculate_widget_dimensions(ui);

        // we define the initial coordinate as the center of such rectangle
        self.reference.dist = rect.distance();

        self.assign_visual_style(ui);

        let canvas = egui::Frame::canvas(ui.style()).inner_margin(Margin::symmetric(3, 5));

        // The frame consumes `total_margin` (inner margin + stroke width +
        // outer margin) around whatever is drawn inside it. `map_area` is the
        // widget's *whole* footprint, so the painter may only claim what is
        // left after that margin. Allocating `map_area.size()` inside the
        // frame made the frame grow to `map_area.size() + 2 * total_margin`
        // and spill past the space the widget was given, which left the
        // visible drawable region truncated on the right/bottom -- so its
        // centre no longer matched the point `set_pos`/`set_pos_from_nodeid`
        // centre on, and nodes were drawn half a margin off.
        let frame_margin = canvas.total_margin().sum();
        let painter_size = (self.map_area.size() - frame_margin).max(Vec2::ZERO);

        let inner_response = canvas.show(ui, |ui| {
            let _span = tracing::info_span!("paint_map").entered();

            if ui.is_rect_visible(self.map_area) {
                let (resp, paint) =
                    ui.allocate_painter(painter_size, egui::Sense::click_and_drag());
                let vec = resp.drag_delta();
                if vec.length() != 0.0 {
                    let _span = tracing::info_span!("calculating_points_in_visible_area").entered();

                    let coords = RawPoint::from(vec.to_pos2());
                    let new_pos = self.reference.pos - (coords / self.zoom);
                    self.set_pos(new_pos.into());
                }
                if self.zoom < self.settings.line_visible_zoom {
                    // filling text settings
                    let mut text_settings = TextSettings {
                        // Screen-space size: unlike the map geometry this is
                        // NOT multiplied by the zoom, so the label stays just
                        // as readable however far the map is zoomed out.
                        size: self.settings.label_text_size,
                        anchor: Align2::CENTER_CENTER,
                        family: FontFamily::Proportional,
                        text: String::new(),
                        position: RawPoint::default(),
                        text_color: ui.visuals().text_color(),
                    };
                    for label in &self.labels {
                        text_settings.text.clone_from(&label.text);
                        text_settings.position = RawPoint::from(label.center);
                        self.paint_label(&paint, &text_settings);
                    }
                }

                // Centre on the rect we actually paint into. Now that the
                // painter is sized to the frame's content area this is exactly
                // `map_area.center()`, but deriving it from `resp.rect` keeps
                // projection, hover hit-testing and the frame in agreement if
                // the frame's margins ever change.
                let rect_midpoint = RawPoint::from(resp.rect.center());
                let min_point = self.current.pos - rect_midpoint;
                let vec_points = &self.visible_points;
                let hashm = &self.points;

                // Safety net: drop stale notifications even if their node is
                // outside the viewport and never finishes its animation.
                let now = Instant::now();
                self.notifications
                    .retain(|_, n| now.duration_since(n.started).as_secs_f32() < 10.0);

                self.paint_map_lines(&paint, &min_point);

                if let Ok(nodes_to_remove) =
                    self.paint_map_points(vec_points, hashm, &paint, ui, &min_point, &resp)
                {
                    for node in nodes_to_remove {
                        self.notifications.remove(&node);
                    }
                }

                for marker in &self.markers {
                    if let Some(point) = self.points.as_ref().unwrap().get(marker.1) {
                        let adjusted_point = RawPoint::from(point.coords) * self.zoom - min_point;
                        if let Some(template) = &self.node_template {
                            template.marker_ui(ui, adjusted_point.into(), self.zoom);
                        } else {
                            let color = if ui.visuals().dark_mode {
                                Color32::LIGHT_GREEN
                            } else {
                                Color32::GREEN
                            };
                            // Frame time, so every marker in this frame shares
                            // one clock instead of each sampling the wall clock
                            // at a slightly different moment.
                            let time = ui.input(|i| i.time) as f32;
                            let effect = match self.settings.marker_animation {
                                SteadyAnimation::Blink => Animation::blink,
                                SteadyAnimation::Halo => Animation::halo,
                                SteadyAnimation::Orbit => Animation::orbit,
                            };
                            effect(ui.painter(), adjusted_point.into(), self.zoom, time, color);
                            // Persistent effects never finish on their own.
                            ui.ctx().request_repaint();
                        }
                    }
                }

                self.paint_sub_components(ui, self.map_area);

                self.capture_mouse_events(ui, &resp);

                if self.zoom != self.previous_zoom {
                    let _span = tracing::info_span!("calculating viewport with zoom").entered();
                    self.adjust_bounds();
                    self.calculate_visible_points();
                    self.previous_zoom = self.zoom;
                }

                if let Some(menu_mon) = &mut self.menu_manager {
                    resp.context_menu(|ui| {
                        menu_mon.ui(ui);
                    });
                }

                #[cfg(feature = "debug_overlay")]
                self.print_debug_info(ui, &resp);
            }
        });
        // `Frame::show` already allocated the frame's outer rect in the parent
        // `Ui` (that is what `inner_response.response.rect` reports), so the
        // widget must not allocate `map_area` a second time -- doing so made
        // it consume twice its own height in the surrounding layout.
        inner_response.response
    }
}

impl Map {
    /// Creates an empty map widget with default [`MapSettings`].
    ///
    /// The widget displays nothing until nodes are loaded with
    /// [`Map::add_hashmap_points`].
    pub fn new() -> Self {
        let settings = MapSettings::default();
        Self {
            zoom: 1.0,
            previous_zoom: 1.0,
            map_area: Rect::NOTHING,
            tree: None,
            points: None,
            labels: Vec::new(),
            visible_points: Vec::new(),
            current: MapBounds::default(),
            reference: MapBounds::default(),
            settings,
            min_size: (None, None),
            max_size: (None, None),
            current_index: 0,
            notifications: HashMap::new(),
            node_states: HashMap::new(),
            menu_manager: None,
            node_template: None,
            markers: HashMap::new(),
            segments: None,
        }
    }

    fn calculate_widget_dimensions(&mut self, ui: &mut Ui) -> RawLine {
        let available = ui.available_rect_before_wrap();
        let mut size = available.size();
        if let Some(max_width) = self.max_size.0 {
            size.x = size.x.min(max_width);
        }
        if let Some(max_height) = self.max_size.1 {
            size.y = size.y.min(max_height);
        }
        if let Some(min_width) = self.min_size.0 {
            size.x = size.x.max(min_width);
        }
        if let Some(min_height) = self.min_size.1 {
            size.y = size.y.max(min_height);
        }
        self.map_area = Rect::from_min_size(available.min, size);
        RawLine::new(
            RawPoint::from(self.map_area.left_top()),
            RawPoint::from(self.map_area.right_bottom()),
        )
    }

    fn calculate_visible_points(&mut self) {
        let _span = tracing::info_span!("calculate_visible_points").entered();
        if self.current.dist > 0.0
            && self.current.dist < f32::INFINITY
            && let Some(tree) = &self.tree
        {
            let center = self.current.pos / self.zoom;
            let radius = self.current.dist.powi(2);
            let point: [f32; 2] = center.into();
            let vis_pos = tree.within(&point, radius, &squared_euclidean).unwrap();
            self.visible_points.clear();
            for point in vis_pos {
                self.visible_points.push(point.1.cast_signed());
            }
        }
    }

    /// Loads the node set and (re)builds the spatial index.
    ///
    /// This replaces any previously loaded points, computes the bounding box of
    /// the whole set, centers the view on its midpoint and refreshes the list
    /// of visible nodes. It must be called at least once before the widget can
    /// display anything.
    ///
    /// The kd-tree built here is what enables viewport culling and
    /// nearest-neighbor hover lookups, so calling this method on every frame is
    /// discouraged; call it only when the node set changes.
    ///
    /// # Examples
    ///
    /// ```
    /// use egui_map::map::Map;
    /// use egui_map::map::objects::MapPoint;
    ///
    /// let mut points = Vec::new();
    /// points.push(MapPoint::new(1, [0.0, 0.0]));
    /// points.push(MapPoint::new(2, [10.0, 10.0]));
    ///
    /// let mut map = Map::new();
    /// map.add_points(points);
    ///
    /// // The view is centered on the midpoint of the loaded nodes.
    /// assert_eq!(map.get_pos(), [5.0, 5.0]);
    /// ```
    pub fn add_points(&mut self, points: Vec<MapPoint>) {
        let mut tree = KdTree::<f32, usize, [f32; 2]>::new(2);
        let mut hash_map = HashMap::new();
        let mut min = RawPoint::new(f32::INFINITY, f32::INFINITY);
        let mut max = RawPoint::new(f32::NEG_INFINITY, f32::NEG_INFINITY);
        for entry in points {
            for i in 0..min.components.len() {
                if entry.coords[i] < min.components[i] {
                    min.components[i] = entry.coords[i];
                }
                if entry.coords[i] > max.components[i] {
                    max.components[i] = entry.coords[i];
                }
            }
            let _result = tree.add(entry.coords, entry.get_id());
            hash_map.insert(entry.get_id(), entry);
        }
        // We stablish the max and min coordinates in this map, this wont change until we change the point hash map
        self.reference.min = min;
        self.reference.max = max;
        self.points = Some(hash_map);
        self.tree = Some(tree);
        self.reference.pos = RawLine::new(min, max).midpoint();
        // we create a rect that include every node in the map
        // Stupid fix because rect area could be infinite
        // I need to implement a more elegant fix
        if self.map_area.area() == 0.0 {
            self.reference.dist = 3000.00;
        } else {
            let rect = RawLine::new(
                RawPoint::from(self.map_area.left_top()),
                RawPoint::from(self.map_area.right_bottom()),
            );
            self.reference.dist = rect.distance();
        }
        self.current = self.reference.clone();
        self.calculate_visible_points();
    }

    /// Loads the node set and (re)builds the spatial index.
    ///
    /// This replaces any previously loaded points, computes the bounding box of
    /// the whole set, centers the view on its midpoint and refreshes the list
    /// of visible nodes. It must be called at least once before the widget can
    /// display anything.
    ///
    /// The kd-tree built here is what enables viewport culling and
    /// nearest-neighbor hover lookups, so calling this method on every frame is
    /// discouraged; call it only when the node set changes.
    ///
    /// # Examples
    ///
    /// ```
    /// use egui_map::map::Map;
    /// use egui_map::map::objects::MapPoint;
    /// use std::collections::HashMap;
    ///
    /// let mut points = HashMap::new();
    /// points.insert(1, MapPoint::new(1, [0.0, 0.0]));
    /// points.insert(2, MapPoint::new(2, [10.0, 10.0]));
    ///
    /// let mut map = Map::new();
    /// map.add_hashmap_points(points);
    ///
    /// // The view is centered on the midpoint of the loaded nodes.
    /// assert_eq!(map.get_pos(), [5.0, 5.0]);
    /// ```
    //#[deprecated(since="0.2.3", note="please use `add_points` instead")]
    pub fn add_hashmap_points(&mut self, hash_map: HashMap<usize, MapPoint>) {
        let _span = tracing::info_span!("add_hashmap_points").entered();
        let mut min = RawPoint::new(f32::INFINITY, f32::INFINITY);
        let mut max = RawPoint::new(f32::NEG_INFINITY, f32::NEG_INFINITY);
        let mut tree = KdTree::<f32, usize, [f32; 2]>::new(2);

        for entry in hash_map.iter() {
            for i in 0..min.components.len() {
                if entry.1.coords[i] < min.components[i] {
                    min.components[i] = entry.1.coords[i];
                }
                if entry.1.coords[i] > max.components[i] {
                    max.components[i] = entry.1.coords[i];
                }
            }
            let _result = tree.add(entry.1.coords, *entry.0);
        }

        // We stablish the max and min coordinates in this map, this wont change until we change the point hash map
        self.reference.min = min;
        self.reference.max = max;
        self.points = Some(hash_map);
        self.tree = Some(tree);
        self.reference.pos = RawLine::new(min, max).midpoint();
        // we create a rect that include every node in the map
        // Stupid fix because rect area could be infinite
        // I need to implement a more elegant fix
        if self.map_area.area() == 0.0 {
            self.reference.dist = 3000.00;
        } else {
            let rect = RawLine::new(
                RawPoint::from(self.map_area.left_top()),
                RawPoint::from(self.map_area.right_bottom()),
            );
            self.reference.dist = rect.distance();
        }
        self.current = self.reference.clone();
        self.calculate_visible_points();
    }

    /// Centers the view on the node with the given id.
    ///
    /// Returns `true` if the view moved. Returns `false` — leaving the view
    /// untouched — when no points have been loaded yet or when `node_id` is
    /// not among them; that case also emits a `tracing` warning, since a
    /// silently ignored id is otherwise indistinguishable from a node that
    /// was centered but drawn in the wrong place.
    ///
    /// A `false` here usually means the id belongs to a different set than
    /// the one loaded through [`Map::add_hashmap_points`] — for example a
    /// map showing only part of the universe, or ids coming from a different
    /// query than the one that produced the nodes.
    ///
    /// ```
    /// use egui_map::map::Map;
    /// use egui_map::map::objects::MapPoint;
    ///
    /// let mut map = Map::new();
    /// map.add_points(vec![MapPoint::new(1, [10.0, 20.0])]);
    ///
    /// assert!(map.set_pos_from_nodeid(1));
    /// assert_eq!(map.get_pos(), [10.0, 20.0]);
    ///
    /// // Unknown id: the view stays where it was.
    /// assert!(!map.set_pos_from_nodeid(999));
    /// assert_eq!(map.get_pos(), [10.0, 20.0]);
    /// ```
    pub fn set_pos_from_nodeid(&mut self, node_id: usize) -> bool {
        let _span = tracing::info_span!("set_pos_from_nodeid").entered();
        if let Some(hash_map) = &self.points
            && let Some(map_point) = hash_map.get(&node_id)
        {
            self.reference.pos = RawPoint::from(map_point.coords);
            self.adjust_bounds();
            self.calculate_visible_points();
            true
        } else {
            tracing::warn!(
                node_id,
                loaded_nodes = self.points.as_ref().map_or(0, |p| p.len()),
                "set_pos_from_nodeid: unknown node id, the view was left unchanged"
            );
            false
        }
    }

    /// Centers the view on the given map coordinates.
    pub fn set_pos(&mut self, position: [f32; 2]) {
        let _span = tracing::info_span!("set_pos").entered();
        let point = RawPoint::from(position);
        self.reference.pos = point;
        self.adjust_bounds();
        self.calculate_visible_points();
    }

    /// Returns the map coordinates the view is currently centered on.
    pub fn get_pos(&self) -> [f32; 2] {
        let _span = tracing::info_span!("get_pos").entered();
        self.reference.pos.into()
    }

    /// Replaces the set of free-floating text labels drawn on the map.
    ///
    /// Labels are only rendered while the zoom level is below
    /// [`MapSettings::line_visible_zoom`].
    pub fn add_labels(&mut self, labels: Vec<MapLabel>) {
        let _span = tracing::info_span!("add_labels").entered();
        self.labels = labels;
    }

    /// Replaces the set of connection lines between nodes.
    ///
    /// Lines are keyed by a connection id that the endpoint nodes must
    /// reference through [`MapPoint::connections`] — push each line's key into
    /// the `connections` of the nodes it joins. The segments are stored in an
    /// R-tree keyed by bounding box: a line is drawn while its bounding box
    /// intersects the viewport and the zoom level is above
    /// [`MapSettings::line_visible_zoom`].
    ///
    /// See the [module-level example](self#connecting-nodes-with-lines) for
    /// the complete wiring.
    pub fn add_lines(&mut self, segments: Vec<MapSegment>) {
        let _span = tracing::info_span!("add_lines").entered();
        // Intern the keys as Rc<str> and build the broad-phase spatial index
        // over the line bounding boxes, so viewport culling and hit-testing
        // discard whole regions without touching every segment.

        self.segments = Some(rstar::RTree::bulk_load(segments));
    }

    /// Replaces the set of connection lines between nodes, from a map keyed
    /// by the same `(usize, usize)` id used in [`MapSegment::id`] and
    /// referenced by [`MapPoint::connections`].
    ///
    /// Equivalent to [`add_lines`](Self::add_lines) but avoids callers having
    /// to collect their segments into a `Vec` first when they already have
    /// them keyed in a `HashMap` (e.g. straight from an adapter that mirrors
    /// them 1:1 by id, with no intermediate ordering to preserve).
    pub fn add_hashmap_lines(&mut self, segments: HashMap<(usize, usize), MapSegment>) {
        let _span = tracing::info_span!("add_hashmap_lines").entered();
        let segments: Vec<MapSegment> = segments.into_values().collect();
        self.segments = Some(rstar::RTree::bulk_load(segments));
    }

    fn adjust_bounds(&mut self) {
        let _span = tracing::info_span!("adjust_bounds").entered();
        self.current.max = self.reference.max * self.zoom;
        self.current.min = self.reference.min * self.zoom;
        self.current.dist = self.reference.dist / self.zoom;
        self.current.pos = self.reference.pos * self.zoom;
    }

    fn capture_mouse_events(&mut self, ui: &Ui, _resp: &Response) {
        let _span = tracing::info_span!("capture_mouse_events").entered();
        // capture MouseWheel Event for Zoom control change
        if ui.rect_contains_pointer(self.map_area) {
            ui.input(|x| {
                let _span = tracing::info_span!("capture_mouse_events_input").entered();

                if !x.events.is_empty() {
                    for event in &x.events {
                        match event {
                            Event::MouseWheel {
                                unit: _,
                                delta,
                                modifiers,
                                phase: _,
                            } => {
                                #[cfg(target_os = "macos")]
                                let zoom_modifier = if modifiers.mac_cmd {
                                    delta.y / 80.00
                                } else {
                                    delta.y / 400.00
                                };

                                #[cfg(not(target_os = "macos"))]
                                let zoom_modifier = if modifiers.ctrl {
                                    delta.y / 8.00
                                } else {
                                    delta.y / 40.00
                                };

                                let mut pre_zoom = self.zoom + zoom_modifier;
                                if pre_zoom > self.settings.max_zoom {
                                    pre_zoom = self.settings.max_zoom;
                                }
                                if pre_zoom < self.settings.min_zoom {
                                    pre_zoom = self.settings.min_zoom;
                                }
                                self.zoom = pre_zoom;
                            }
                            _ => {
                                continue;
                            }
                        };
                    }
                }
            });
        }
    }

    /// Sets the zoom factor.
    ///
    /// Values outside the [`MapSettings::min_zoom`]..=[`MapSettings::max_zoom`]
    /// range are ignored.
    pub fn set_zoom(&mut self, value: f32) {
        if value >= self.settings.min_zoom && value <= self.settings.max_zoom {
            self.zoom = value;
        }
    }

    /// Returns the current zoom factor.
    pub fn get_zoom(&mut self) -> f32 {
        self.zoom
    }

    /// Returns the style for the current theme, falling back to the first
    /// style if the current theme index has no entry.
    fn current_style(&self) -> &MapStyle {
        self.settings
            .styles
            .get(self.current_index)
            .or(self.settings.styles.first())
            .expect("MapSettings::styles must not be empty")
    }

    fn assign_visual_style(&mut self, ui_obj: &mut Ui) {
        let style_index = ui_obj.visuals().dark_mode as usize;

        if self.current_index != style_index {
            let _span = tracing::info_span!("asign_visual_style").entered();

            self.current_index = style_index;
            let map_style = self.settings.styles.get_mut(style_index).unwrap();
            let visuals = &ui_obj.style().visuals;
            map_style.background_color = visuals.extreme_bg_color;
            map_style.border = Some(visuals.window_stroke);
        }
    }

    /// Floating debug read-out, compiled in only under the `debug_overlay`
    /// feature.
    ///
    /// Deliberately unobtrusive: it renders as a collapsed `dbg` toggle in the
    /// map's top-left corner with no background of its own, so it costs a few
    /// dim pixels until a developer clicks it open. egui remembers the
    /// open/closed state per widget instance, so it stays open across frames
    /// once expanded.
    #[cfg(feature = "debug_overlay")]
    fn print_debug_info(&mut self, ui: &mut Ui, resp: &Response) {
        let _span = tracing::info_span!("printing debug data").entered();

        let p = |v: f32| format!("{v:.2}");
        let mut rows: Vec<(String, Color32)> = vec![
            (
                format!(
                    "MIN {}, {}",
                    p(self.current.min.components[0]),
                    p(self.current.min.components[1])
                ),
                Color32::LIGHT_GREEN,
            ),
            (
                format!(
                    "MAX {}, {}",
                    p(self.current.max.components[0]),
                    p(self.current.max.components[1])
                ),
                Color32::LIGHT_GREEN,
            ),
            (
                format!(
                    "CUR {}, {}",
                    p(self.current.pos.components[0]),
                    p(self.current.pos.components[1])
                ),
                Color32::LIGHT_GREEN,
            ),
            (
                format!("DST {}", p(self.current.dist)),
                Color32::LIGHT_GREEN,
            ),
            (format!("ZOM {}", self.zoom), Color32::GREEN),
            (
                format!(
                    "REC {}, {} .. {}, {}",
                    p(self.map_area.left_top().x),
                    p(self.map_area.left_top().y),
                    p(self.map_area.right_bottom().x),
                    p(self.map_area.right_bottom().y)
                ),
                Color32::LIGHT_GREEN,
            ),
        ];
        if let Some(points) = &self.points {
            rows.push((format!("NUM {}", points.len()), Color32::LIGHT_GREEN));
        }
        if !self.visible_points.is_empty() {
            rows.push((
                format!("VIS {}", self.visible_points.len()),
                Color32::LIGHT_GREEN,
            ));
        }
        if let Some(pointer_pos) = resp.hover_pos() {
            rows.push((
                format!("HVR {}, {}", p(pointer_pos.x), p(pointer_pos.y)),
                Color32::LIGHT_BLUE,
            ));
        }
        let drag = resp.drag_delta();
        if drag.length() != 0.0 {
            rows.push((format!("DRG {}, {}", p(drag.x), p(drag.y)), Color32::GOLD));
        }

        // Drawn into a *detached* child `Ui` in the map's own layer.
        //
        // `new_child` alone does not call `advance_cursor_after_rect`, so the
        // overlay never contributes to the parent's `min_rect`. That matters:
        // the canvas `Frame` sizes itself from its content's `min_rect`, and
        // letting this grow it would push the frame past the space the widget
        // was given -- exactly the overflow that used to knock the map
        // off-centre. Being laid out after the map's painter also means the
        // toggle wins pointer input over the pan/zoom surface underneath.
        let overlay_rect = Rect::from_min_max(
            self.map_area.left_top() + Vec2::new(6.0, 6.0),
            self.map_area.right_bottom(),
        );
        let mut overlay_ui = ui.new_child(
            UiBuilder::new()
                .max_rect(overlay_rect)
                .layout(Layout::top_down(Align::Min)),
        );
        // No frame and no header background: the map shows straight through,
        // so this costs a few dim pixels until someone opens it.
        CollapsingHeader::new(RichText::new("dbg").monospace().small().weak())
            .id_salt("egui_map_debug_overlay")
            .default_open(false)
            .show_background(false)
            .show(&mut overlay_ui, |ui| {
                for (text, color) in rows {
                    ui.label(RichText::new(text).monospace().small().color(color));
                }
            });
    }

    fn paint_sub_components(&mut self, ui_obj: &mut Ui, rect: Rect) {
        let _span = tracing::info_span!("map_ui_paint_sub_components").entered();
        let zoom_slider = egui::Slider::new(
            &mut self.zoom,
            self.settings.min_zoom..=self.settings.max_zoom,
        )
        .show_value(false)
        .orientation(SliderOrientation::Vertical);
        let mut pos1 = rect.right_top();
        let mut pos2 = rect.right_top();
        pos1.x -= 80.0;
        pos1.y += 120.0;
        pos2.x -= 60.0;
        pos2.y += 240.0;

        let sub_rect = egui::Rect::from_two_pos(pos1, pos2);
        let ui_builder = egui::UiBuilder::new().clone().max_rect(sub_rect);
        ui_obj.scope_builder(ui_builder, |ui_obj| {
            ui_obj.add(zoom_slider);
        });
    }

    fn paint_map_points(
        &self,
        vec_points: &Vec<isize>,
        hashm: &Option<HashMap<usize, MapPoint>>,
        paint: &Painter,
        ui_obj: &mut Ui,
        min_point: &RawPoint,
        resp: &Response,
    ) -> Result<Vec<usize>, ()> {
        let mut nearest_id = None;
        let mut nodes_to_remove = Vec::new();
        let mut shape_vec = vec![];

        if hashm.is_none() {
            return Err(());
        }
        if vec_points.is_empty() {
            return Err(());
        }
        // detecting the nearest hover node
        if self.settings.node_text_visibility == VisibilitySetting::Hover
            && resp.hovered()
            && let Some(point) = resp.hover_pos()
        {
            let raw_point = RawPoint::from(point);
            let hovered_map_point = (*min_point + raw_point) / self.zoom;
            if let Ok(nearest_node) = self.tree.as_ref().unwrap().nearest(
                &hovered_map_point.components,
                1,
                &squared_euclidean,
            ) {
                nearest_id = Some(nearest_node.first().unwrap().1);
            }
        }
        // filling text settings
        let mut text_settings = TextSettings {
            // Screen-space size: unlike the map geometry this is NOT
            // multiplied by the zoom, so a node name stays just as readable
            // when the map is zoomed all the way out.
            size: self.settings.node_text_size,
            anchor: Align2::LEFT_BOTTOM,
            family: FontFamily::Proportional,
            text: String::new(),
            position: RawPoint::default(),
            text_color: ui_obj.visuals().text_color(),
        };

        // Drawing Points
        for temp_point in vec_points {
            let parsed_point = temp_point.cast_unsigned();
            if let Some(system) = hashm.as_ref().unwrap().get(&parsed_point) {
                let _span = tracing::info_span!("painting_points_m").entered();
                let viewport_point = RawPoint::from(system.coords) * self.zoom - min_point;
                if let Some(node_template) = &self.node_template {
                    if nearest_id.unwrap_or(&0usize) == &system.get_id() {
                        node_template.selection_ui(ui_obj, viewport_point.into(), self.zoom);
                    }
                } else if self.zoom > self.settings.label_visible_zoom
                    && self.settings.node_text_visibility == VisibilitySetting::Always
                    || (self.settings.node_text_visibility == VisibilitySetting::Hover
                        && nearest_id.unwrap_or(&0usize) == &system.get_id())
                {
                    let mut viewport_text = viewport_point;
                    viewport_text.components[0] += 3.0 * self.zoom;
                    viewport_text.components[1] -= 3.0 * self.zoom;
                    text_settings.position = viewport_text;
                    text_settings.text = system.get_name();
                    self.paint_label(paint, &text_settings);
                }

                let system_id = system.get_id();

                // Persistent node state is drawn first so a notification --
                // the *event* -- sits on top of the *state*.
                if let Some(state) = self.node_states.get(&system_id) {
                    let color = state.color.unwrap_or(self.current_style().alert_color);
                    if let Some(template) = &self.node_template {
                        // There is no dedicated template hook for node state:
                        // `marker_ui` is the persistent-visual one, so state and
                        // markers share it. Adding a hook would break every
                        // existing `NodeTemplate` implementor.
                        template.marker_ui(ui_obj, viewport_point.into(), self.zoom);
                    } else {
                        let effect = match state.animation {
                            SteadyAnimation::Blink => Animation::blink,
                            SteadyAnimation::Halo => Animation::halo,
                            SteadyAnimation::Orbit => Animation::orbit,
                        };
                        // Frame time, so every element animated this frame
                        // shares one clock instead of sampling its own.
                        let time = ui_obj.input(|i| i.time) as f32;
                        effect(paint, viewport_point.into(), self.zoom, time, color);
                    }
                    // Persistent effects never finish on their own.
                    ui_obj.ctx().request_repaint();
                }

                if let Some(notification) = self.notifications.get(&system_id) {
                    let color = notification
                        .color
                        .unwrap_or(self.current_style().alert_color);
                    if let Some(template) = &self.node_template {
                        template.notification_ui(
                            ui_obj,
                            viewport_point.into(),
                            self.zoom,
                            notification.started,
                            color,
                        );
                    } else {
                        let effect = match notification.animation {
                            NodeAnimation::Pulse => Animation::pulse,
                            NodeAnimation::Ripple => Animation::ripple,
                            NodeAnimation::CountdownArc => Animation::countdown_arc,
                            NodeAnimation::ScaleIn => Animation::scale_in,
                            NodeAnimation::Crosshair => Animation::crosshair,
                        };
                        if effect(
                            paint,
                            viewport_point.into(),
                            self.zoom,
                            notification.started,
                            color,
                        ) {
                            ui_obj.ctx().request_repaint();
                        } else {
                            nodes_to_remove.push(system_id);
                        }
                    }
                }
                if let Some(node_template) = &self.node_template {
                    node_template.node_ui(ui_obj, viewport_point.into(), self.zoom, system);
                } else {
                    shape_vec.push(Shape::circle_filled(
                        viewport_point.into(),
                        4.00 * self.zoom,
                        system.color.unwrap_or(self.current_style().fill_color),
                    ));
                }
            }
        }
        paint.extend(shape_vec);
        Ok(nodes_to_remove)
    }

    fn paint_map_lines(&self, painter: &Painter, min_point: &RawPoint) {
        let _span = tracing::info_span!("paint_map_lines").entered();

        // Drawing Lines
        if self.zoom > self.settings.line_visible_zoom
            && let Some(mut stroke) = self.current_style().line
            && let Some(segments) = &self.segments
        {
            let mut shape_vec = vec![];
            let transparency_range = self.zoom - self.settings.line_visible_zoom;
            if (0.00..0.80).contains(&transparency_range) {
                let mut tup_stroke = stroke.color.to_tuple();
                let transparency = (self.zoom - self.settings.line_visible_zoom) / 0.80;
                tup_stroke.3 = (255.0 * transparency).round() as u8;
                let color = Color32::from_rgba_unmultiplied(
                    tup_stroke.0,
                    tup_stroke.1,
                    tup_stroke.2,
                    tup_stroke.3,
                );
                stroke = Stroke::new(stroke.width, color);
            }
            // Broad-phase: query the segment R-tree with the viewport AABB
            // (in map coordinates), padded by the stroke width so lines at
            // the very edge are not clipped prematurely.
            let center = self.current.pos / self.zoom;
            let padding = stroke.width / self.zoom;
            let half = RawPoint::new(
                self.map_area.width() / 2.0 / self.zoom + padding,
                self.map_area.height() / 2.0 / self.zoom + padding,
            );
            let query = rstar::AABB::from_corners((center - half).into(), (center + half).into());
            for segment in segments.locate_in_envelope_intersecting(query) {
                let raw_line = segment.raw_line();
                let pos_a = raw_line.points[0] * self.zoom - min_point;
                let pos_b = raw_line.points[1] * self.zoom - min_point;
                shape_vec.push(Shape::line_segment([pos_a.into(), pos_b.into()], stroke));
            }
            painter.extend(shape_vec);
        }
    }

    fn paint_label(&self, paint: &Painter, text_settings: &TextSettings) {
        let _span = tracing::info_span!("paint_label").entered();
        paint.text(
            text_settings.position.into(),
            text_settings.anchor,
            text_settings.text.clone(),
            FontId::new(text_settings.size, text_settings.family.clone()),
            text_settings.text_color,
        );
    }

    /// Triggers a pulsing notification on the node `id_node`.
    ///
    /// # Deprecated
    ///
    /// This only ever played one of the available effects. Use [`Map::node`]
    /// and pick the effect you want:
    ///
    /// ```
    /// # use egui_map::map::Map;
    /// # use egui_map::map::objects::MapPoint;
    /// # use std::time::Instant;
    /// # let mut map = Map::new();
    /// # map.add_points(vec![MapPoint::new(1, [0.0, 0.0])]);
    /// # let time = Instant::now();
    /// if let Some(node) = map.node(1) {
    ///     node.pulse(time);
    /// }
    /// ```
    ///
    /// Note the one behavioural difference: `notify` accepts an id that was
    /// never loaded (the notification simply never draws), while [`Map::node`]
    /// returns `None` for it.
    #[deprecated(
        since = "0.4.0",
        note = "use `map.node(id)` and pick an effect, e.g. `if let Some(n) = map.node(id) { n.pulse(time) }`"
    )]
    pub fn notify(&mut self, id_node: usize, time: Instant) {
        let _span = tracing::info_span!("notify").entered();
        self.notifications.insert(
            id_node,
            Notification {
                started: time,
                animation: NodeAnimation::Pulse,
                color: None,
            },
        );
    }

    /// Borrows the node `id` so an animation can be attached to it.
    ///
    /// Returns `None` when `id` was never loaded through
    /// [`Map::add_points`] / [`Map::add_hashmap_points`], so a stale or
    /// mistyped id is a compile-time-visible case rather than a silent no-op.
    ///
    /// The handle carries optional configuration that must be set *before* the
    /// effect, which is the terminal call:
    ///
    /// ```
    /// # use egui_map::map::Map;
    /// # use egui_map::map::objects::MapPoint;
    /// # use std::time::Instant;
    /// # let mut map = Map::new();
    /// # map.add_points(vec![MapPoint::new(1, [0.0, 0.0])]);
    /// # let time = Instant::now();
    /// // a one-off event
    /// if let Some(node) = map.node(1) {
    ///     node.color(egui::Color32::RED).ripple(time);
    /// }
    ///
    /// // lasting state, until cleared
    /// if let Some(node) = map.node(1) {
    ///     node.halo();
    /// }
    ///
    /// assert!(map.node(999).is_none());
    /// ```
    pub fn node(&mut self, id: usize) -> Option<NodeHandle<'_>> {
        if !self
            .points
            .as_ref()
            .is_some_and(|points| points.contains_key(&id))
        {
            return None;
        }
        Some(NodeHandle {
            map: self,
            id,
            color: None,
        })
    }

    /// Returns the id of the line closest to `point`, in map coordinates,
    /// when it lies within `tolerance` map units of the segment.
    ///
    /// Broad-phase candidates are taken from the segment R-tree built by
    /// [`Map::add_lines`]; the exact point-to-segment distance is then
    /// computed against the line geometry and the closest match wins. Returns
    /// `None` when no lines are loaded or every segment is farther than
    /// `tolerance`. A negative `tolerance` behaves like `0.0`.
    ///
    /// To hit-test a mouse click, convert the screen position to map
    /// coordinates first (`map = (screen + origin) / zoom`, see the
    /// [coordinate model](self#coordinate-model)) and pick a tolerance scaled
    /// by `1.0 / zoom` so it stays constant in screen pixels.
    pub fn line_at(&self, point: [f32; 2], tolerance: f32) -> Option<(usize, usize)> {
        let _span = tracing::info_span!("line_at").entered();
        let segments = self.segments.as_ref()?;
        let tolerance = tolerance.max(0.0);

        let center = RawPoint::from(point);
        let padding = RawPoint::new(tolerance, tolerance);
        let query = rstar::AABB::from_corners((center - padding).into(), (center + padding).into());

        let mut closest: Option<(f32, (usize, usize))> = None;
        for segment in segments.locate_in_envelope_intersecting(query) {
            let distance = segment.raw_line().distance_to_point(center);
            if distance <= tolerance && closest.as_ref().is_none_or(|(best, _)| distance < *best) {
                closest = Some((distance, segment.id));
            }
        }
        closest.map(|(_, id)| id)
    }

    /// Installs a right-click context menu whose contents are built by the
    /// given [`ContextMenuManager`] implementation.
    pub fn set_context_manager(&mut self, manager: Rc<dyn ContextMenuManager>) {
        self.menu_manager = Some(manager);
    }

    /// Replaces the built-in node rendering with a custom [`NodeTemplate`]
    /// implementation.
    ///
    /// The template takes over the drawing of nodes, selection highlights,
    /// notification animations and markers — including the node name labels,
    /// which the widget no longer draws once a template is installed. See the
    /// [`NodeTemplate`] examples for custom shapes and animations.
    pub fn set_node_template(&mut self, template: Rc<dyn NodeTemplate>) {
        self.node_template = Some(template);
    }

    /// Adds the marker `id`, or moves it, so it points to the node `node_id`.
    ///
    /// Markers are drawn as a blinking ring around the target node unless a
    /// custom [`objects::NodeTemplate::marker_ui`] is installed.
    pub fn update_marker(&mut self, id: usize, node_id: usize) {
        self.markers
            .entry(id)
            .and_modify(|value| *value = node_id)
            .or_insert(node_id);
    }

    /// Sets the minimum width and/or height the widget should occupy, in egui
    /// points. `None` leaves the corresponding dimension unconstrained.
    pub fn allocate_at_least(&mut self, width: Option<f32>, height: Option<f32>) {
        self.min_size = (width, height);
    }

    /// Sets the maximum width and/or height the widget should occupy, in egui
    /// points. `None` leaves the corresponding dimension unconstrained.
    pub fn allocate_at_most(&mut self, width: Option<f32>, height: Option<f32>) {
        self.max_size = (width, height);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::Duration;

    fn sample_points() -> Vec<MapPoint> {
        let mut map = Vec::new();
        map.push(MapPoint::new(1, [0.0, 0.0]));
        map.push(MapPoint::new(2, [10.0, 10.0]));
        map.push(MapPoint::new(3, [-10.0, -10.0]));
        map
    }

    // ---------- construcción ----------

    #[test]
    fn map_new_initial_state() {
        let map = Map::new();
        assert_eq!(map.zoom, 1.0);
        assert_eq!(map.previous_zoom, 1.0);
        assert!(map.points.is_none());
        assert!(map.segments.is_none());
        assert!(map.tree.is_none());
        assert!(map.labels.is_empty());
        assert!(map.visible_points.is_empty());
        assert!(map.markers.is_empty());
        assert!(map.notifications.is_empty());
        assert!(map.node_states.is_empty());
        assert_eq!(map.min_size, (None, None));
        assert_eq!(map.max_size, (None, None));
        assert_eq!(map.current_index, 0);
    }

    #[test]
    fn map_default_equals_new() {
        let map = Map::default();
        assert_eq!(map.zoom, 1.0);
        assert!(map.points.is_none());
    }

    // ---------- zoom ----------

    #[test]
    fn set_zoom_within_range() {
        let mut map = Map::new();
        map.set_zoom(1.5);
        assert_eq!(map.get_zoom(), 1.5);
    }

    #[test]
    fn set_zoom_at_exact_limits() {
        let mut map = Map::new();
        map.set_zoom(map.settings.min_zoom);
        assert_eq!(map.get_zoom(), 0.1);
        map.set_zoom(map.settings.max_zoom);
        assert_eq!(map.get_zoom(), 2.0);
    }

    #[test]
    fn set_zoom_out_of_range_is_ignored() {
        let mut map = Map::new();
        let initial = map.get_zoom();
        map.set_zoom(0.05); // por debajo de min_zoom
        assert_eq!(map.get_zoom(), initial);
        map.set_zoom(2.5); // por encima de max_zoom
        assert_eq!(map.get_zoom(), initial);
    }

    // ---------- puntos ----------

    #[test]
    fn add_hashmap_points_computes_bounds() {
        let mut map = Map::new();
        map.add_points(sample_points());

        assert_eq!(map.reference.min.components, [-10.0, -10.0]);
        assert_eq!(map.reference.max.components, [10.0, 10.0]);
        // pos es el punto medio del rectángulo que contiene todos los puntos
        assert_eq!(map.reference.pos.components, [0.0, 0.0]);
        // map_area tiene área 0 antes de renderizar, así que dist es el valor fijo
        assert_eq!(map.reference.dist, 3000.0);
        // current se inicializa como copia de reference
        assert_eq!(map.current.min.components, map.reference.min.components);
        assert_eq!(map.current.max.components, map.reference.max.components);
        assert_eq!(map.current.pos.components, map.reference.pos.components);
        assert_eq!(map.current.dist, map.reference.dist);
        assert!(map.points.is_some());
        assert!(map.tree.is_some());
        assert_eq!(map.points.as_ref().unwrap().len(), 3);
    }

    #[test]
    fn add_hashmap_points_populates_visible_points() {
        let mut map = Map::new();
        map.add_points(sample_points());
        // todos los puntos de muestra caen dentro del radio por defecto
        assert_eq!(map.visible_points.len(), 3);
    }

    /// Renders one frame of `map` in a 500x500 viewport and returns the
    /// painted line segments.
    fn render_line_segments(map: &mut Map) -> Vec<[egui::Pos2; 2]> {
        use egui::{Context, RawInput, Shape};
        let ctx = Context::default();
        let input = RawInput {
            screen_rect: Some(egui::Rect::from_min_size(
                egui::Pos2::ZERO,
                egui::vec2(500.0, 500.0),
            )),
            ..RawInput::default()
        };
        let output = ctx.run_ui(input, |ui| {
            ui.add(&mut *map);
        });
        output
            .shapes
            .iter()
            .filter_map(|cs| match cs.shape {
                Shape::LineSegment { points, .. } => Some(points),
                _ => None,
            })
            .collect()
    }

    #[test]
    fn segment_crossing_viewport_is_painted_even_with_far_endpoints() {
        // With the old endpoint-based rule this line was culled: both
        // endpoints sit beyond the point-culling radius. With the R-tree the
        // segment AABB intersects the viewport, so it is painted — no points
        // needed at all.
        let mut map = Map::new();
        map.set_zoom(1.0);
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [-4000.0, -1.0], [4000.0, 1.0]));
        map.add_lines(lines);
        map.set_pos([0.0, 0.0]);

        let segments = render_line_segments(&mut map);
        assert_eq!(segments.len(), 1);
    }

    #[test]
    fn segment_outside_viewport_is_not_painted() {
        let mut map = Map::new();
        map.set_zoom(1.0);
        let mut lines = Vec::new();
        lines.push(MapSegment::new(
            (1, 2),
            [10_000.0, 10_000.0],
            [10_100.0, 10_100.0],
        ));
        map.add_lines(lines);
        map.set_pos([0.0, 0.0]);

        assert!(render_line_segments(&mut map).is_empty());
    }

    #[test]
    fn add_lines_builds_segment_tree() {
        let mut map = Map::new();
        map.add_points(sample_points());
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [0.0, 0.0], [10.0, 10.0]));
        map.add_lines(lines);

        let tree = map
            .segments
            .as_ref()
            .expect("add_lines must build the segment tree");
        assert_eq!(tree.size(), 1);

        // Broad-phase query: a viewport containing (0,0) must hit the segment;
        // a far-away viewport must not.
        let hit_query = rstar::AABB::from_corners([-1.0, -1.0], [1.0, 1.0]);
        let hits: Vec<_> = tree.locate_in_envelope_intersecting(hit_query).collect();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, (1, 2));

        let miss_query = rstar::AABB::from_corners([100.0, 100.0], [200.0, 200.0]);
        assert_eq!(tree.locate_in_envelope_intersecting(miss_query).count(), 0);
    }

    #[test]
    fn map_check_line_is_painted_on_first_frame() {
        use egui::{Context, RawInput, Shape};

        // --- arrange ---
        let mut map = Map::new();
        map.set_zoom(1.0);

        let mut point_a = MapPoint::new(0, [0.0, 0.0]);
        point_a.connections.push((0, 1));
        let mut point_b = MapPoint::new(1, [50.0, 50.0]);
        point_b.connections.push((0, 1));

        let mut lines = Vec::new();
        lines.push(MapSegment::new((0, 1), point_a.coords, point_b.coords));

        let mut points = Vec::new();
        points.push(point_a);
        points.push(point_b);
        // Load points before lines — the natural order shown in the examples.
        map.add_points(points);
        map.add_lines(lines);

        map.set_pos([25.0, 25.0]);

        // --- act: 1st frame (no CentralPanel — run_ui creates the root Ui) ---
        let ctx = Context::default();
        let screen = egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(500.0, 500.0));
        let input = RawInput {
            screen_rect: Some(screen),
            ..RawInput::default()
        };

        let output1 = ctx.run_ui(input.clone(), |ui| {
            ui.add(&mut map);
        });

        let segments1: Vec<[egui::Pos2; 2]> = output1
            .shapes
            .iter()
            .filter_map(|cs| match cs.shape {
                Shape::LineSegment { points, .. } => Some(points),
                _ => None,
            })
            .collect();

        assert!(
            !segments1.is_empty(),
            "Frame 1: no LineSegment shapes painted (map lines did not draw)"
        );

        // Expected projection of (0,0)->(50,50) with zoom=1, center=(25,25),
        // viewport 500x500: pos_a = (225, 225), pos_b = (275, 275). Tolerance ±2 px.
        let expected_a = egui::pos2(225.0, 225.0);
        let expected_b = egui::pos2(275.0, 275.0);
        let tolerance = 2.0;
        let found_on_frame1 = segments1.iter().any(|[p1, p2]| {
            let d_a1 = p1.distance(expected_a);
            let d_b1 = p2.distance(expected_b);
            let d_a2 = p2.distance(expected_a);
            let d_b2 = p1.distance(expected_b);
            (d_a1 < tolerance && d_b1 < tolerance) || (d_a2 < tolerance && d_b2 < tolerance)
        });
        assert!(
            found_on_frame1,
            "Frame 1: no LineSegment matches expected endpoints (~225,225 -> ~275,275); got {:?}",
            segments1
        );

        // --- act: 2nd frame (unchanged) — detect duplicate-lines regression ---
        let output2 = ctx.run_ui(input, |ui| {
            ui.add(&mut map);
        });

        let segments2: Vec<[egui::Pos2; 2]> = output2
            .shapes
            .iter()
            .filter_map(|cs| match cs.shape {
                Shape::LineSegment { points, .. } => Some(points),
                _ => None,
            })
            .collect();

        assert_eq!(
            segments1.len(),
            segments2.len(),
            "Frame 2: expected {} line segments (no duplication across frames), got {}",
            segments1.len(),
            segments2.len()
        );
    }

    // ---------- posición ----------

    #[test]
    fn set_pos_and_get_pos_roundtrip() {
        let mut map = Map::new();
        map.set_pos([25.0, -35.0]);
        assert_eq!(map.get_pos(), [25.0, -35.0]);
    }

    #[test]
    fn set_pos_from_nodeid_with_valid_id() {
        let mut map = Map::new();
        map.add_points(sample_points());
        assert!(map.set_pos_from_nodeid(2));
        assert_eq!(map.get_pos(), [10.0, 10.0]);
    }

    /// Regression: the widget used to allocate a painter of the full
    /// `map_area.size()` *inside* the canvas frame, so the frame grew by
    /// `2 * total_margin` and spilled out of the space the widget was given.
    /// The drawable region was then truncated on the right/bottom and its
    /// centre no longer matched `map_area.center()`, leaving a centred node
    /// visibly off-centre by half a margin.
    #[test]
    fn centered_node_is_painted_at_the_middle_of_the_drawable_area() {
        use egui::{Context, RawInput, Shape};

        for screen_size in [egui::vec2(500.0, 500.0), egui::vec2(800.0, 400.0)] {
            for zoom in [1.0, 2.0] {
                let mut map = Map::new();
                map.set_zoom(zoom);
                map.add_points(vec![MapPoint::new(7, [123.0, 456.0])]);
                map.set_pos_from_nodeid(7);

                let screen = egui::Rect::from_min_size(egui::Pos2::ZERO, screen_size);
                let ctx = Context::default();
                let mut widget_rect = egui::Rect::NOTHING;
                let mut output = ctx.run_ui(
                    RawInput {
                        screen_rect: Some(screen),
                        ..RawInput::default()
                    },
                    |ui| {
                        widget_rect = ui.add(&mut map).rect;
                    },
                );

                // The widget must stay inside the space it was handed.
                assert!(
                    screen.contains_rect(widget_rect),
                    "{screen_size:?} zoom {zoom}: widget rect {widget_rect:?} overflows {screen:?}"
                );

                // The centred node must land at the middle of the region the
                // map actually paints into (the painter's clip rect).
                let (node_center, drawable) = output
                    .shapes
                    .iter()
                    .find_map(|cs| match &cs.shape {
                        Shape::Circle(circle) => Some((circle.center, cs.clip_rect)),
                        _ => None,
                    })
                    .expect("the node must be painted");

                assert!(
                    node_center.distance(drawable.center()) < 0.5,
                    "{screen_size:?} zoom {zoom}: node painted at {node_center:?} but the \
                     drawable area {drawable:?} is centred at {:?}",
                    drawable.center()
                );

                output.textures_delta.clear();
            }
        }
    }

    #[test]
    fn set_pos_from_nodeid_with_invalid_id_keeps_position() {
        let mut map = Map::new();
        map.add_points(sample_points());
        let before = map.reference.pos.components;
        // An unknown id must report the failure instead of silently no-op'ing.
        assert!(!map.set_pos_from_nodeid(999));
        assert_eq!(map.reference.pos.components, before);
    }

    #[test]
    fn set_pos_from_nodeid_without_points_does_nothing() {
        let mut map = Map::new();
        assert!(!map.set_pos_from_nodeid(1));
        assert_eq!(map.reference.pos.components, [0.0, 0.0]);
    }

    // ---------- etiquetas y líneas ----------

    #[test]
    fn add_labels_stores_labels() {
        let mut map = Map::new();
        let label = MapLabel {
            text: "Region".to_string(),
            center: Pos2::new(1.0, 2.0),
        };
        map.add_labels(vec![label]);
        assert_eq!(map.labels.len(), 1);
        assert_eq!(map.labels[0].text, "Region");
    }

    #[test]
    fn add_lines_stores_lines() {
        let mut map = Map::new();
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [0.0, 0.0], [1.0, 1.0]));
        map.add_lines(lines);
        let tree = map.segments.as_ref().unwrap();
        assert_eq!(tree.size(), 1);
        assert_eq!(
            tree.locate_in_envelope_intersecting(rstar::AABB::from_corners(
                [-1.0, -1.0],
                [2.0, 2.0],
            ))
            .next()
            .unwrap()
            .id,
            (1, 2)
        );
    }

    // ---------- notificaciones y marcadores ----------

    #[test]
    fn line_at_returns_closest_line_within_tolerance() {
        let mut map = Map::new();
        map.add_points(sample_points());
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [0.0, 0.0], [10.0, 0.0]));
        lines.push(MapSegment::new((3, 4), [20.0, -5.0], [20.0, 5.0]));
        map.add_lines(lines);

        // 1.5 units above the horizontal segment.
        let hit = map.line_at([5.0, 1.5], 2.0).expect("line must be hit");
        assert_eq!(hit, (1, 2));

        // Closest to the vertical segment.
        let hit = map.line_at([19.0, 0.0], 2.0).expect("line must be hit");
        assert_eq!(hit, (3, 4));
    }

    #[test]
    fn line_at_returns_none_beyond_tolerance() {
        let mut map = Map::new();
        map.add_points(sample_points());
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [0.0, 0.0], [10.0, 10.0]));
        map.add_lines(lines);

        // Distance from (5,4) to the diagonal segment (0,0)-(10,10) is
        // |5-4|/sqrt(2) ~= 0.707.
        assert!(map.line_at([5.0, 4.0], 0.8).is_some());
        assert!(map.line_at([5.0, 4.0], 0.5).is_none());
        assert!(map.line_at([100.0, 100.0], 5.0).is_none());
    }

    #[test]
    fn line_at_returns_none_without_lines() {
        let map = Map::new();
        assert!(map.line_at([0.0, 0.0], 10.0).is_none());
    }

    #[test]
    fn line_at_negative_tolerance_behaves_like_zero() {
        let mut map = Map::new();
        map.add_points(sample_points());
        let mut lines = Vec::new();
        lines.push(MapSegment::new((1, 2), [0.0, 0.0], [10.0, 10.0]));
        map.add_lines(lines);

        // Exact point on the segment is hit even with tolerance clamped to 0.
        assert!(map.line_at([5.0, 5.0], -1.0).is_some());
        assert!(map.line_at([5.0, 5.1], -1.0).is_none());
    }

    /// The deprecated shortcut must keep behaving exactly as it did: a pulse,
    /// restarted on every call, and tolerant of ids that were never loaded.
    #[test]
    #[allow(deprecated)]
    fn deprecated_notify_still_records_a_pulse() {
        let mut map = Map::new();
        let t1 = Instant::now();
        map.notify(5, t1);
        let recorded = map.notifications.get(&5).expect("notify must record");
        assert_eq!(recorded.started, t1);
        assert_eq!(recorded.animation, NodeAnimation::Pulse);
        assert_eq!(recorded.color, None);

        let t2 = t1 + Duration::from_secs(1);
        map.notify(5, t2);
        assert_eq!(map.notifications.get(&5).unwrap().started, t2);
        assert_eq!(map.notifications.len(), 1);
    }

    // ---------- NodeHandle ----------

    fn map_with_nodes() -> Map {
        let mut map = Map::new();
        map.add_points(vec![
            MapPoint::new(1, [0.0, 0.0]),
            MapPoint::new(2, [10.0, 10.0]),
        ]);
        map
    }

    #[test]
    fn node_returns_none_for_an_unknown_id() {
        let mut map = map_with_nodes();
        assert!(map.node(1).is_some());
        assert!(map.node(999).is_none());
        // and with nothing loaded at all
        assert!(Map::new().node(1).is_none());
    }

    #[test]
    fn each_event_effect_records_its_own_animation() {
        let now = Instant::now();
        for (apply, expected) in [
            (
                Box::new(|n: NodeHandle| n.pulse(now)) as Box<dyn FnOnce(NodeHandle)>,
                NodeAnimation::Pulse,
            ),
            (
                Box::new(|n: NodeHandle| n.ripple(now)),
                NodeAnimation::Ripple,
            ),
            (
                Box::new(|n: NodeHandle| n.countdown(now)),
                NodeAnimation::CountdownArc,
            ),
            (
                Box::new(|n: NodeHandle| n.scale_in(now)),
                NodeAnimation::ScaleIn,
            ),
            (
                Box::new(|n: NodeHandle| n.crosshair(now)),
                NodeAnimation::Crosshair,
            ),
        ] {
            let mut map = map_with_nodes();
            apply(map.node(1).unwrap());
            let recorded = map.notifications.get(&1).expect("effect must be recorded");
            assert_eq!(recorded.animation, expected);
            assert_eq!(recorded.started, now);
            // an event effect must not leave lasting state behind
            assert!(map.node_states.is_empty());
        }
    }

    #[test]
    fn each_steady_effect_records_lasting_state() {
        for (apply, expected) in [
            (
                Box::new(|n: NodeHandle| n.halo()) as Box<dyn FnOnce(NodeHandle)>,
                SteadyAnimation::Halo,
            ),
            (Box::new(|n: NodeHandle| n.blink()), SteadyAnimation::Blink),
            (Box::new(|n: NodeHandle| n.orbit()), SteadyAnimation::Orbit),
        ] {
            let mut map = map_with_nodes();
            apply(map.node(1).unwrap());
            assert_eq!(map.node_states.get(&1).unwrap().animation, expected);
            // lasting state must not masquerade as a notification
            assert!(map.notifications.is_empty());
        }
    }

    #[test]
    fn color_modifier_reaches_both_families() {
        let mut map = map_with_nodes();
        map.node(1)
            .unwrap()
            .color(Color32::RED)
            .pulse(Instant::now());
        map.node(2).unwrap().color(Color32::BLUE).halo();

        assert_eq!(map.notifications.get(&1).unwrap().color, Some(Color32::RED));
        assert_eq!(map.node_states.get(&2).unwrap().color, Some(Color32::BLUE));
    }

    #[test]
    fn a_node_can_carry_state_and_a_notification_at_once() {
        let mut map = map_with_nodes();
        map.node(1).unwrap().halo();
        map.node(1).unwrap().ripple(Instant::now());

        assert!(map.node_states.contains_key(&1));
        assert!(map.notifications.contains_key(&1));
    }

    #[test]
    fn clear_removes_both_families_for_that_node_only() {
        let mut map = map_with_nodes();
        map.node(1).unwrap().halo();
        map.node(1).unwrap().ripple(Instant::now());
        map.node(2).unwrap().halo();

        map.node(1).unwrap().clear();

        assert!(!map.node_states.contains_key(&1));
        assert!(!map.notifications.contains_key(&1));
        assert!(map.node_states.contains_key(&2), "node 2 must be untouched");
    }

    #[test]
    fn re_triggering_replaces_the_previous_effect() {
        let mut map = map_with_nodes();
        map.node(1).unwrap().pulse(Instant::now());
        map.node(1).unwrap().crosshair(Instant::now());

        assert_eq!(map.notifications.len(), 1);
        assert_eq!(
            map.notifications.get(&1).unwrap().animation,
            NodeAnimation::Crosshair
        );
    }

    #[test]
    fn update_marker_inserts_and_updates() {
        let mut map = Map::new();
        map.update_marker(1, 100);
        assert_eq!(map.markers.get(&1), Some(&100));
        map.update_marker(1, 200);
        assert_eq!(map.markers.get(&1), Some(&200));
        assert_eq!(map.markers.len(), 1);
    }

    // ---------- tamaño ----------

    #[test]
    fn allocate_at_least_sets_min_size() {
        let mut map = Map::new();
        map.allocate_at_least(Some(100.0), None);
        assert_eq!(map.min_size, (Some(100.0), None));
    }

    #[test]
    fn allocate_at_most_sets_max_size() {
        let mut map = Map::new();
        map.allocate_at_most(None, Some(200.0));
        assert_eq!(map.max_size, (None, Some(200.0)));
    }

    // ---------- bounds ----------

    #[test]
    fn adjust_bounds_scales_with_zoom() {
        let mut map = Map::new();
        map.reference.min = RawPoint::new(-10.0, -20.0);
        map.reference.max = RawPoint::new(10.0, 20.0);
        map.reference.pos = RawPoint::new(5.0, 5.0);
        map.reference.dist = 100.0;
        map.set_zoom(2.0);
        map.adjust_bounds();

        assert_eq!(map.current.max.components, [20.0, 40.0]);
        assert_eq!(map.current.min.components, [-20.0, -40.0]);
        assert_eq!(map.current.pos.components, [10.0, 10.0]);
        assert_eq!(map.current.dist, 50.0);
    }
}